Repository navigation
Implement structuredClone() in TypeScript behind an autogate - #7977
Conversation
Behind the experimental typescript_implemented_structured_clone flag, which needs the per-isolate-javascript-bootstrap autogate, replace the JSG structuredClone method on ServiceWorkerGlobalScope.prototype with a TypeScript one (GS-4 in the API migration catalogue). As with typescript_implemented_streams, setting the flag without the autogate fails worker startup. The TypeScript side is the WebIDL layer: the receiver check, the argument count and the options conversion. The clone itself goes through a new native utils.structuredClone(), which calls the same jsg::structuredClone the C++ method uses, so cloning, transfer and their errors are unchanged. src/tests/structured-clone/ runs one module set against both implementations and tables their divergences, all in the WebIDL layer: length 1 instead of 0, non-native source text, transfer accepting any iterable rather than only Arrays and read through its iterator, and the messages for a rejected transfer member or element. Compatibility: no change without the experimental flag; the generated types are unchanged, since they still come from the C++ method.
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #7977 +/- ##
=======================================
Coverage 67.03% 67.03%
=======================================
Files 799 799
Lines 206637 206658 +21
Branches 32062 32065 +3
=======================================
+ Hits 138519 138538 +19
Misses 49321 49321
- Partials 18797 18799 +2 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
piscisaureus
left a comment
There was a problem hiding this comment.
Looks right. Keeping the serializer native is the important part.
Nit: Symbol.iterator is fetched twice in toObjectSequence (once for the typeof check and again by for...of); WebIDL reads it once. Please add a cold-isolate clone microbench before this goes default-on.
jasnell
left a comment
There was a problem hiding this comment.
Long term we're not going to be using the compat flag mechanism for these, especially since these are going to be replacing the original impl and not sitting next to it. Instead, these should be gated by autogate
…clone-ts # Conflicts: # src/per_isolate/AGENTS.md # src/per_isolate/main.ts # src/per_isolate/per_isolate-env.d.ts # src/workerd/api/per-isolate-bootstrap.c++ # src/workerd/io/compatibility-date.capnp # src/workerd/io/worker.c++
Replace the experimental typescript_implemented_structured_clone compat flag with the TS_STRUCTURED_CLONE autogate. The TypeScript method is a replacement for the C++ one rather than an alternative a Worker opts into, so, like TS_URL and TS_EVENT_SOURCE, it rolls out per process instead of per Worker. Under the autogate, global-scope.h leaves out the C++ JSG_METHOD and main.ts installs the TypeScript method where JSG would, on ServiceWorkerGlobalScope.prototype with all three attributes true. User code cannot read an autogate, so each cell of the structuredClone suite says which implementation it runs through a USING_TS_IMPL binding, as the URL suite does. The C++ cell drops its @all-autogates variant, which would run the TypeScript implementation. Compatibility: no change while the autogate is off. With it on, the divergences tabled in src/tests/structured-clone/AGENTS.md apply to every Worker, all of them in the WebIDL conversion of the arguments; cloning and transfer go through the same native serializer. Generated types are unchanged.
toObjectSequence() used for...of, which differs observably from WebIDL's "create a sequence from an iterable": it read [Symbol.iterator] again after checking it, and it closed the iterator when an element failed the conversion to object. Spell the steps out instead: read the method and next once each, check that the iterator and each result are objects, and leave the iterator open on a rejected element. Only the TypeScript implementation, under TS_STRUCTURED_CLONE, is affected; C++ accepts only Arrays and reads them by index.
Split the structuredClone() benchmark into a config per implementation, as src/bench/url does: structured-clone-cpp and structured-clone-ts (TS_STRUCTURED_CLONE) run the same modules. The C++ config has no @all-autogates variant, which would run the TypeScript one. Add cases for the options, whose conversion is where the implementations differ: no transfer, an empty transfer, and transfers of 1 and 16 ArrayBuffers. Add a structured-clone-cold service whose top level makes the first structuredClone() calls in the isolate, so its startup group times them, and the bootstrap that installs the function, in a new isolate per sample.
There was a problem hiding this comment.
Superseded by the review of
212b1789.
This review, of 5ddbcd5c
💬 Approved with comments — No defects found. The only note (INFO) asks for the decision to accept the six API divergences, which apply to every Worker under the autogate, to be recorded, as the repository's compatibility rules require.
Findings: 1 info (1 is an inline comment on the diff)
The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.
📋 Code Quality: 💬 1 info
Sound implementation following the TS_URL pattern; one note on recording the compatibility decision.
Recommendation: 💬 Optional Nits
- [INFO] Record the decision to accept the six observable structuredClone() divergences that apply to every Worker under TS_STRUCTURED_CLONE (
src/workerd/util/autogate.h:118)
View full review
The TypeScript layer and the native StructuredClone binding look correct. The note below concerns the compatibility record for the autogate rollout.
✅ All other checks passed
🔒 Security: ✅ LGTM
The native function lives on the internal utils object. It reads only a dense array built by the bootstrap, so reading that array runs no user code. The conversion uses captured primordials, and the receiver check is at least as strict as the C++ method's.
📖 AGENTS.md: ✅ LGTM
No issues found.
⚡ Performance: ✅ LGTM
The options conversion is at parity or faster. The tree-clone slowdown is already tracked as open in the description, and a cold-isolate benchmark is included.
📝 Documentation: ✅ LGTM
No issues found.
Reviewed commit: 5ddbcd5c
The receiver and options checks test for undefined or null with `!= null`, as elsewhere in the per-isolate bootstrap. Behaviour is unchanged.
There was a problem hiding this comment.
Superseded by the review of
5d5a2f35.
This review, of 212b1789
✅ Approved — No findings. The switch to != null checks in structured-clone.ts keeps the same behaviour, and the earlier note about recording the divergences is resolved.
The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.
✅ All checks passed
🔒 Security: ✅ LGTM
No issues found. The native function reads only an array built by the bootstrap, and the conversion uses captured primordials.
📖 AGENTS.md: ✅ LGTM
No issues found.
📋 Code Quality: ✅ LGTM
The != null receiver and options checks match the bootstrap's convention, and their behaviour is unchanged. The native binding is registered in the names and values arrays of createUtilsObject, and the JSG method is left out under the autogate in global-scope.h.
⚡ Performance: ✅ LGTM
The transfer conversion makes a single linear pass over the iterator. The roughly 20% slowdown on the tree cases is in the shared deserializer, and the description already lists it as open.
📝 Documentation: ✅ LGTM
No issues found.
Reviewed commit: 212b1789
The generated types took structuredClone() and StructuredSerializeOptions from the C++ method. Removing JSG_METHOD(structuredClone) once the TypeScript implementation replaces it would have dropped StructuredSerializeOptions, which only that method's parameter brought in, and left the remaining declarations referring to a missing type. As with URL, URLPattern and DOMException, the declarations now live in types/defines/structured-clone.d.ts, and global-scope.h overrides the method and its options struct to never. The signatures are unchanged; they move within the snapshot. Generating types without the JSG_METHOD gives identical output. A type test, types/test/types/structured-clone.ts, covers the global function, the global scope member and the options type.
There was a problem hiding this comment.
Superseded by the review of
d9a57ffc.
This review, of 5d5a2f35
✅ Approved — No findings. The new types/defines declaration keeps the structuredClone() signatures unchanged and removes their dependence on the C++ JSG_METHOD.
Not opened by the correctness review: 3 changed files it was meant to read
types/generated-snapshot/experimental/index.d.tstypes/generated-snapshot/experimental/index.tstypes/generated-snapshot/index.ts
The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.
✅ All checks passed
🔒 Security: ✅ LGTM
No security issues. The TypeScript layer converts its arguments with captured primordials. The native binding reads only an array the bootstrap built itself, and the clone goes through the same jsg::structuredClone as the C++ method.
📖 AGENTS.md: ✅ LGTM
The src/per_isolate/AGENTS.md and types/AGENTS.md updates are consistent with the change.
📋 Code Quality: ✅ LGTM
The never overrides in global-scope.h for the method and for StructuredCloneOptions match the generated snapshot diffs. types/defines/structured-clone.d.ts declares StructuredSerializeOptions, the ServiceWorkerGlobalScope.structuredClone member and the global declare function with the same signatures as before. types/test/types/structured-clone.ts checks that the global, self and ServiceWorkerGlobalScope declarations agree.
⚡ Performance: ✅ LGTM
The transfer conversion makes a single linear pass over the iterator. The roughly 20% slowdown on the tree cases is in the shared deserializer, and the description already lists it as open.
📝 Documentation: ✅ LGTM
No issues found.
Reviewed commit: 5d5a2f35
jasnell
left a comment
There was a problem hiding this comment.
Not overly concerned with the perf gap on this. We can investigate further optimizations later.
There was a problem hiding this comment.
Superseded by the review of
5ee2e70d.
This review, of d9a57ffc
✅ Approved — No findings. The new types/defines declaration keeps the structuredClone() signatures unchanged and removes their dependence on the C++ JSG_METHOD.
Not opened by the correctness review: 3 changed files it was meant to read
types/generated-snapshot/experimental/index.d.tstypes/generated-snapshot/experimental/index.tstypes/generated-snapshot/index.ts
The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.
✅ All checks passed
🔒 Security: ✅ LGTM
No security issues. The TypeScript layer converts its arguments with captured primordials. The native binding reads only an array the bootstrap built itself, and the clone goes through the same jsg::structuredClone as the C++ method.
📖 AGENTS.md: ✅ LGTM
The src/per_isolate/AGENTS.md and types/AGENTS.md updates are consistent with the change.
📋 Code Quality: ✅ LGTM
The never overrides in global-scope.h for the method and for StructuredCloneOptions match the generated snapshot diffs. types/defines/structured-clone.d.ts declares StructuredSerializeOptions, the ServiceWorkerGlobalScope.structuredClone member and the global declare function with the same signatures as before. types/test/types/structured-clone.ts checks that the global, self and ServiceWorkerGlobalScope declarations agree.
⚡ Performance: ✅ LGTM
The transfer conversion makes a single linear pass over the iterator. The roughly 20% slowdown on the tree cases is in the shared deserializer, and the description already lists it as open.
📝 Documentation: ✅ LGTM
No issues found.
Reviewed commit: d9a57ffc — same changes as 5d5a2f35, so this is that commit's review (no new review was run; line numbers are as of 5d5a2f35)
There was a problem hiding this comment.
✅ Approved — No findings. The new types/defines declaration keeps the structuredClone() signatures unchanged and removes their dependence on the C++ JSG_METHOD.
Not opened by the correctness review: 3 changed files it was meant to read
types/generated-snapshot/experimental/index.d.tstypes/generated-snapshot/experimental/index.tstypes/generated-snapshot/index.ts
The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.
✅ All checks passed
🔒 Security: ✅ LGTM
No security issues. The TypeScript layer converts its arguments with captured primordials. The native binding reads only an array the bootstrap built itself, and the clone goes through the same jsg::structuredClone as the C++ method.
📖 AGENTS.md: ✅ LGTM
The src/per_isolate/AGENTS.md and types/AGENTS.md updates are consistent with the change.
📋 Code Quality: ✅ LGTM
The never overrides in global-scope.h for the method and for StructuredCloneOptions match the generated snapshot diffs. types/defines/structured-clone.d.ts declares StructuredSerializeOptions, the ServiceWorkerGlobalScope.structuredClone member and the global declare function with the same signatures as before. types/test/types/structured-clone.ts checks that the global, self and ServiceWorkerGlobalScope declarations agree.
⚡ Performance: ✅ LGTM
The transfer conversion makes a single linear pass over the iterator. The roughly 20% slowdown on the tree cases is in the shared deserializer, and the description already lists it as open.
📝 Documentation: ✅ LGTM
No issues found.
Reviewed commit: 5ee2e70d — same changes as 5d5a2f35, so this is that commit's review (no new review was run; line numbers are as of 5d5a2f35)
Behind the TS_STRUCTURED_CLONE autogate, replace the JSG structuredClone
method on ServiceWorkerGlobalScope.prototype with a TypeScript
implementation installed by the per-isolate bootstrap (GS-4 in the API
migration catalogue). Like TS_URL and TS_EVENT_SOURCE, it replaces the
C++ method rather than sitting next to it: under the autogate,
global-scope.h leaves out the C++ JSG_METHOD, and main.ts installs the
TypeScript method where JSG would, with the same attributes.
The TypeScript side (src/per_isolate/structured-clone.ts) is the WebIDL
layer: it checks the receiver, requires the value argument, and converts
the StructuredSerializeOptions dictionary, using captured primordials.
transfer is read as WebIDL reads a sequence: [Symbol.iterator]
and next once each, with the iterator left open when an element is
rejected. The clone itself goes through a new native
utils.structuredClone(), which calls the same jsg::structuredClone as
the C++ method, so which values clone, which objects transfer, and the
errors for either are unchanged.
Divergences from the C++ method, all in the argument conversion, each
pinned by a test and tabled in src/tests/structured-clone/AGENTS.md:
[native code].
only Arrays.
rather than "... not of type 'Array'.".
rather than reaching the serializer's "Object is not transferable".
The serializer's own deviations from the HTML spec are shared by both
implementations: duplicate or detached buffers are accepted, and
non-ArrayBuffer objects throw a TypeError instead of a DataCloneError.
Compatibility: no change while the autogate is off. With it on, the
divergences above apply to every Worker.
Types: structuredClone() and StructuredSerializeOptions are now declared
in types/defines/structured-clone.d.ts, as URL, URLPattern and
DOMException are, and global-scope.h overrides the C++ method and its
options struct to never. The signatures are unchanged; they move within
the generated snapshot. Since the types no longer come from
JSG_METHOD(structuredClone), retiring the C++ method leaves them as they
are.
Not for the merge commit:
The first commit predates review and uses an experimental compat flag.
Gate the TypeScript structuredClone() behind an autogate replaces that
flag with the autogate.
Tests
src/tests/structured-clone/runs one module set against both implementations. Each cell sayswhich one it runs through a
USING_TS_IMPLbinding, since user code cannot read an autogate; theC++ cell has no
@all-autogatesvariant. The full suite passes with the autogate on in every@all-autogatesvariant.Benchmarks
src/bench/serialization/now hasstructured-clone-cppandstructured-clone-ts, running thesame modules, with cases for the options and a
structured-clone-coldservice whose startupgroup times the first calls in a new isolate. Medians from a local
--config=benchmarkrun(Apple Silicon, V8 15.8):
startup:scriptstartup:worker(first calls)The options conversion is cheaper in TypeScript than in JSG. Cold, the first calls cost a few
tens of microseconds more, within about twice the confidence interval.
Open: the tree cases are consistently about 20% slower under the TypeScript config, though
the serializer is the same. The cost is in V8's
ValueDeserializer: its profile showsproperty-name internalization and transition-array searches where the C++ config mostly takes the
ExpectedTransitionfast path. It depends on the isolate's map-transition state: in a modulethat holds fewer inputs, the same tree clones at parity. The cause is not yet identified.