feat: serialize DOMException per Web IDL [Serializable]

[edusperoni]

Implements the [Serializable] slot DOMException was deliberately shipped without, so it survives structuredClone and worker postMessage instead of degrading like a custom Error subclass. Mirrors NativeScript/ios#453.

Mechanism (Node's JSTransferable protocol, reduced to one class)

• Branding. The dom-exception builtin gains a native half: binding.markCloneable stamps every instance with a per-isolate v8::Private (stored in the runtime's RuntimeState slot bag), unforgeable and invisible from JS. All three GetExports call sites for the builtin — the lazy-global row, the internal/dom-exception registry row and ThrowDataCloneError — now share one binding factory (serialization::DomExceptionBinding), because 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.
• Claiming. The serializer delegate turns on HasCustomHostObject and answers IsHostObject with a private-symbol check, V8's escape hatch for treating a plain JS object as a host object. That claim replaces V8's own embedder-field detection rather than adding to it, so IsHostObject claims anything with internal fields first — Java proxies, URL/URLPattern/URLSearchParams, ObjectManager wrappers — and those keep raising DataCloneError under structuredClone and keep arriving as {} over postMessage. Cost: one private-symbol lookup per plain JS object in a serialized graph, the same price Node pays.
• Two-phase payload. V8 forbids JS execution while a value is being read (calling the constructor inside ReadHostObject is a V8_Fatal), so this mirrors Node's host_objects_ design: WriteHostObject pushes {name, message, stack} onto an out-of-band list on the SerializedValue and writes only a tag + index into the stream; Deserialize constructs every instance through the real constructor before ReadValue starts, and ReadHostObject hands 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.
• Failure handling. Deserialize throws a DataCloneError rather than returning empty with nothing pending when the builtin cannot load, so structuredClone never yields undefined silently. The main-thread worker message read (WorkerWrapper::FireMessageOnParentWorkerObject) now runs under a TryCatch, so a failed read is logged instead of left pending on the isolate; the worker-side read in DrainPendingTasks was already inside one.

Wire format

Host objects now start with a uint32 tag: 0 = degraded native wrapper (writes nothing else; the reader returns Object::New, keeping today's empty-object shape), 1 = a uint32 index into the out-of-band DOMException payload list. The bytes never outlive the process (structuredClone round-trips in one isolate, worker messages cross isolates in the same binary), so the format is free to evolve with the file.

Policies

DOMException serializes under both kReject (structuredClone) and kDegrade (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.

Claiming is unconditional: V8 samples HasCustomHostObject once per ValueSerializer and never re-checks it, so a gate on "this isolate holds a DOMException" would lose the type of the isolate's first instance when a getter creates it during the very clone that carries it.

Tests

• Shared suite bumped to common-runtime-tests-app@aa7f8cf: DOMException round-trip (name/message/code/instanceof, identity within a graph, nesting, stack) and worker postMessage in both directions — main→worker exercises the on-demand builtin run in a fresh isolate. Those specs probe whether structuredClone actually carries a DOMException rather than assuming it from presence, so they self-gate on runtimes without the slot. The commit also pins the "Throw error in onerror" forward count on whether Worker is an EventTarget; Android's is not yet, so the legacy count of 2 stays pinned and the worker error path is untouched here.
• tests/testRuntimeImplementedAPIs.js: an unguarded structuredClone canary; a worker (tests/domExceptionFirstCloneWorker.js) whose first DOMException is born inside a getter during the clone that carries it; and a spec cloning new java.lang.Object() and new URL("https://example.com/") after a DOMException exists, pinning that native wrappers still raise DataCloneError.
• Full device suite on an arm64 API 36 emulator: 1216 specs, 0 failures (4 pre-existing skips).

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}