feat(runtime): serialize DOMException per Web IDL [Serializable] - #453
Draft
edusperoni wants to merge 4 commits into
Draft
feat(runtime): serialize DOMException per Web IDL [Serializable]#453edusperoni wants to merge 4 commits into
edusperoni wants to merge 4 commits into
Conversation
DOMException (Web IDL §4.3) arrives as a new lazy builtin: a class grafted onto Error.prototype with branded accessor attributes, the legacy code table, and the constants on interface object and prototype. CustomEvent is defined in events.js next to the Event it extends and placed by the lazy tier through the shared exports cache, so only the placement is deferred — Events::Init now runs the file via GetExports and reads the backing EventTarget from the exports bag. Builtins reach each other through a new internal require tier: registry rows marked internal-only resolve for the require builtins receive and nowhere else, the Node internal-module idiom the js README planned for. The four name-patched-Error stand-ins (abort-signal, performance, structured-clone, base64) now throw real DOMExceptions, required at first throw so the builtin never runs on a clean path, and the native serializer builds the same class for its DataCloneError with the old shape kept as a teardown fallback. With the tier in place the interim internals parameter loses its only two users: kListenerChanged and setListenerErrorReporter move into events.js's exports behind internal/events, and the builtin wrapper drops back to Node's five parameters (exports, require, module, binding, primordials). A consumer that runs before its producer now fails loudly at the require instead of silently reading a missing key. Not implemented: the spec's [Serializable] slot — a DOMException inside a cloned graph still degrades like any custom Error subclass, since v8::ValueSerializer has no hook for a plain JS class. Shared suites (self-gating, skip where the APIs are absent) land in the tests submodule; unguarded canaries on this runtime keep a regression from turning them into silent skips.
…racy detail is a readonly attribute in the IDL, unlike the base Event's fields that mutate during dispatch, so define it non-writable. The internal require tier's misdescribed failure mode is corrected in the README and abort-signal comment: a cache miss runs the producer on demand, so a consumer can never observe a missing capability. The docs that still described the pre-DOMException stand-ins (abort-signal, performance, structured-clone, index) now describe the real class.
The dom-exception builtin gains a native half: markCloneable stamps every instance with a per-isolate private brand (Caches::StateFor), and the serialization delegates claim branded objects through V8's HasCustomHostObject/IsHostObject hooks — the same escape hatch Node's JSTransferable protocol uses, reduced to the one class. The payload (name, message, stack) travels out-of-band on the SerializedValue with only a tag and index in the stream, because V8 forbids JS execution while a value is being read: Deserialize constructs every instance through the real constructor before ReadValue starts — on a worker isolate that never touched DOMException that runs the builtin on demand — and ReadHostObject hands them out by index, Node's host_objects_ design. Rebuilding through the constructor re-brands the instance, so a forwarded exception serializes again on the next hop. The degraded-wrapper path now writes an explicit tag where it wrote nothing; the bytes never outlive the process, so the format is free to change with the file. DOMException serializes under both host-object policies: structuredClone's kReject only refuses objects with a native half to lose, and a DOMException has none. Cost of the claim: with HasCustomHostObject on, V8 asks IsHostObject about every plain JS object in a graph — one private-symbol lookup each, the price Node pays for the same protocol.
|
Important Draft PR not reviewedDraft PRs are not automatically reviewed by default.
To automatically review draft PRs, update your CodeRabbit configuration: reviews:
auto_review:
drafts: trueThanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
HasCustomHostObject makes V8 consult IsHostObject for every plain JS object in a serialized graph — measured ~25ns each, ~+12% on an object-heavy structuredClone. An isolate that never constructed a DOMException cannot be holding one, so the claim is gated on a per-isolate flag markCloneable flips with the first instance; until then serialization runs the pre-claim path untouched. Accepted edge, documented at the sample site: a getter running during the very clone could construct the isolate's first DOMException after a false sample — that one instance degrades to a plain object, the pre-feature behavior, and every later serialization sees the flag.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on #452. Implements the
[Serializable]slot that PR deliberately left out, so DOMException survivesstructuredCloneand workerpostMessageinstead of degrading like a custom Error subclass.Mechanism (Node's JSTransferable protocol, reduced to one class)
binding.markCloneablestamps every instance with a per-isolatev8::Private(stored viaCaches::StateFor), unforgeable and invisible from JS. All threeGetExportscall sites for the builtin now share one binding factory (serialization::DomExceptionBinding) — GetExports consults the factory only on the run that populates the cache, so a site passing a different one would win or lose by init order.HasCustomHostObjectand answersIsHostObjectwith a private-symbol check, V8's escape hatch for treating a plain JS object as a host object. Cost: one private-symbol lookup per plain JS object in a serialized graph — the same price Node pays.ReadHostObjectis aV8_Fatal, found the hard way), so this mirrors Node'shost_objects_design:WriteHostObjectpushes{name, message, stack}onto an out-of-band list on theSerializedValueand writes only a tag + index into the stream;Deserializeconstructs every instance through the real constructor beforeReadValuestarts, andReadHostObjecthands them out by index. Construction re-brands the instance, so a forwarded exception serializes again on the next hop — and on a worker isolate that never touched DOMException, the pre-construction step runs the builtin on demand.0= degraded native wrapper, unchanged empty-object semantics;1= DOMException index). The bytes never outlive the process, so the format is free to evolve with the file.kReject(structuredClone) andkDegrade(worker postMessage): the reject policy exists to refuse objects whose native half would be left behind, and a DOMException has none. Graph identity is preserved by V8's object-id machinery — one payload per distinct instance.Tests
postMessagein both directions — main→worker exercises the on-demand builtin run in a fresh isolate.RuntimeImplementedAPIs.js.Benchmarks
structuredClonemedians, iPad Pro simulator, 12 runs after warmup (temporary in-suite benchmark, not committed). "Claim off" is an isolate that has never constructed a DOMException — the gatedHasCustomHostObject(second commit) keeps it on the exact pre-change path; "claim on" is after the first instance exists.{})Claim-off vs base differences are run-to-run noise. So: zero cost for apps that never touch DOMException, ~25ns per plain object on serialization-heavy paths afterward — the price Node pays unconditionally. Accepted edge (documented in-source): a getter constructing the isolate's first DOMException during the very clone that contains it degrades that one instance to a plain object.