Skip to content

fix: pass ReadableStreams through a forwarded or queued call - #296

Merged
ndisidore merged 4 commits into
mainfrom
fix/forward-readable-streams
Nov 18, 2026
Merged

ndisidore merged 4 commits into
mainfrom
fix/forward-readable-streams

Conversation

@ndisidore

@ndisidore ndisidore commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

A ReadableStream threw owned payload shouldn't contain raw ReadableStreams whenever it was serialized from an owned payload: passed to or returned from a stub that forwards to another session, or passed in a call made through a pending RpcPromise. Same for a Request or Response body. The throw asserted an invariant that never held: an owned payload keeps the raw stream, parsed off the wire or deep-copied, with a hook in hooks only for disposal.

Fixes #228.

  • Serializing an owned payload creates a new hook for the pipe. Same as params, and as the Request body and Blob paths in serialize.ts. createPipe() locks the stream at once, so the payload's own hook can't cancel it mid-pump. Holds with fix: release call arguments once a forwarded or queued call is sent #294, which disposes forwarded args after send.
  • Deep-copying a stream out of an owned payload still throws, as on main. Now from deepCopy(), with an accurate message. Covers await p.stream on a settled result and map() over stream fields.
  • Why not allow the copy. The first revision did, with a new hook per copy: source and copy each cancelled the stream on disposal, so streams arrived empty with no error (nested map(), map() on a settled result, await p.stream then dispose p). Dup'ing the payload's hook fixed those but leaked when the same property was read twice, and missed streams delivered through a nested promise. Needs a real stream-to-hook lookup. Follow-up in A ReadableStream can't be read off a settled result or through map() #303, alongside WritableStream cannot be passed or returned through a forwarded stub #297.
  • WritableStream not included (WritableStream cannot be passed or returned through a forwarded stub #297). Same throw, but a new hook is wrong there: the stream is already locked by its writer, or is a proxy over an import the payload disposes.
  • One new exposure. Asking for the same stream twice, e.g. Promise.all([p, p.stream]), used to throw; the second stream now hangs or arrives empty. That is Sending a locked ReadableStream hangs the receiver instead of erroring #295 reached a new way.
  • Tests go through the public API: a stream returned and a stream passed across three parties, a stream and a Request body passed in a call through a pending RpcPromise, and the refused copy, which also checks the result's own stream still reads. The first four fail on main; the last fails without the guard.
  • Checked by hand, no tests: Request/Response bodies through a hop, the proxy shapes from the ReadableStream cannot be returned through a forwarded stub #228 comment, errors propagating through the hop.
  • Cancel through the hop is slower than direct. Dropping or cancelling the stream only reaches the source on its next chunk, so an idle source stays open until then. Same as an app-level relay on main; a limit of the pipe relay, not fixed here.
  • Ran the Node and workerd projects locally. Browser projects not run locally.

@changeset-bot

changeset-bot Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 57eef2d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
capnweb Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@pkg-pr-new

pkg-pr-new Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

npm i https://pkg.pr.new/cloudflare/capnweb@296
npm i https://pkg.pr.new/cloudflare/capnweb/capnweb-validate@296

commit: 57eef2d

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of ac672cbc.

This review, of 45abd58b

✅ Approved — A small, well-reasoned fix that matches the existing "params" branch and has tests that go through the public API; no issues found.

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

📋 Code Quality: ✅ LGTM

In the "owned" branch, getHookForReadableStream (src/core.ts:1039-1041) now creates a fresh hook where it used to throw. This matches the "params" branch. Both callers expect a hook: createPipe in serialize.ts, and the code in core.ts that pushes the hook onto hooks. The new tests cover the return path and the send path through a forwarded stub. WritableStream still throws, as the description says; that is a planned follow-up.


📝 Documentation: ✅ LGTM

The changeset entry and the inline comment describe the change accurately.


Reviewed commit: 45abd58b

@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

🚀 Deploying Preview to Cloudflare 🚀

Preview URL: https://fix-forward-readable-streams.pr.capnweb.com (commit 57eef2d)

This URL reflects your latest Preview deployment

Preview Deployments by commit

Status Deployment URL Commit Updated (UTC) See this deployment's details
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://607ae50d.pr.capnweb.com 57eef2d 2026-11-17T17:34:32.756Z Visit the dashboard ↗
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://1c38289d.pr.capnweb.com c10a31a 2026-11-16T23:55:49.720Z Visit the dashboard ↗
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://a0bedafc.pr.capnweb.com f0efe7d 2026-11-12T20:47:09.413Z Visit the dashboard ↗
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://a46cba59.pr.capnweb.com ac672cb 2026-11-12T17:16:12.956Z Visit the dashboard ↗
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://f9fe9381.pr.capnweb.com 45abd58 2026-11-12T17:03:20.687Z Visit the dashboard ↗

A ReadableStream threw "owned payload shouldn't contain raw
ReadableStreams" whenever it was serialized from an owned payload:
passed to or returned from a stub that forwards to another session, or
passed in a call made through a pending RpcPromise. The same went for a
Request or Response body.

The throw asserted an invariant that never held. An owned payload keeps
the raw stream, whether parsed off the wire or deep-copied, with a hook
in `hooks` only so that disposing the payload cancels a stream nobody
read.

Create a new hook in that case, as for params. The payload's own hook
does not need sharing: it only cancels a stream that is still unlocked,
and createPipe() locks the stream while the payload is serialized.

WritableStream has the same throw but needs a dup of the payload's
existing hook, so it is left for a follow-up.
@ndisidore
ndisidore force-pushed the fix/forward-readable-streams branch from 45abd58 to ac672cb Compare November 12, 2026 17:14

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of f0efe7db.

This review, of ac672cbc

✅ Approved — A small, well-reasoned fix with tests for the return and send paths through a forwarded stub; no issues found.

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

📋 Code Quality: ✅ LGTM

In the "owned" branch, getHookForReadableStream in src/core.ts now creates a fresh hook where it used to throw. This is the same thing the "params" branch does. The new tests cover a stream that is returned through a forwarded stub and a stream that is passed through one. Since the last review, only the changeset file has changed.


📝 Documentation: ✅ LGTM

The changeset entry and the inline comment describe the change accurately.


Reviewed commit: ac672cbc

ndisidore added a commit to cloudflare/cloudflare-os that referenced this pull request Nov 12, 2026
A stream the session returns does not reach the gadget UI frame: capnweb
cannot forward one from the server's session into the frame's
(cloudflare/capnweb#296). Google states an image's length, which still
bounds what is read.
Comment thread src/core.ts Resolved
The previous commit let an owned payload hand out a new hook for a
stream in every case. That is right when the payload is serialized,
since createPipe() locks the stream at once. It is wrong when the
stream is deep-copied out of the payload: the copy and its source then
each cancel the one stream on disposal, with no shared refcount, and
streams arrive empty with no error. Nested map(), map() on a settled
result, and `await p.stream` followed by disposing `p` all did this.

Throw in deepCopy() instead, as main did, with an accurate message.
Sharing a refcount needs a stream-to-hook lookup, which is left for a
follow-up along with WritableStream (#297).

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of c10a31a5.

This review, of f0efe7db

✅ Approved — A focused fix. The serialize path now gets a new hook, the deep-copy path still refuses with a clear error, and tests cover both paths. No issues found.

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 concerns in this change.


📖 AGENTS.md: ✅ LGTM

No agent instruction files are affected.


📋 Code Quality: ✅ LGTM

The owned branch of getHookForReadableStream (src/core.ts:1038-1042) now creates a new hook, as the params branch does. The serializer hands that hook straight to createPipe, which locks the stream, so the payload's own hook can't cancel it mid-pump. The new guard in deepCopy (src/core.ts:1175-1179) fires only when the owner is owned, so ensureDeepCopied is unaffected: it copies while the source is still params or return. Request and Response bodies go through deepCopy, so they hit the same guard. The tests cover the return and send paths through a forwarded stub, and the refused copy.


⚡ Performance: ✅ LGTM

No performance concerns in this change.


📝 Documentation: ✅ LGTM

The changeset entry and the inline comments match the behavior.


Reviewed commit: f0efe7db

ndisidore added a commit to cloudflare/cloudflare-os that referenced this pull request Nov 12, 2026
A stream the session returns does not reach the gadget UI frame: capnweb
cannot forward one from the server's session into the frame's
(cloudflare/capnweb#296). Google states an image's length, which still
bounds what is read.
ndisidore added a commit to cloudflare/cloudflare-os that referenced this pull request Nov 15, 2026
A stream the session returns does not reach the gadget UI frame: capnweb
cannot forward one from the server's session into the frame's
(cloudflare/capnweb#296). Google states an image's length, which still
bounds what is read.
@ndisidore

ndisidore commented Nov 16, 2026 •

Copy link
Copy Markdown
Member Author

@teamchong re the await p.stream after disposing p test: you were right, with a new hook the stream came back empty once p was disposed.

tried dup-ing the existing hook instead. it fixed that case but leaked when the same property was read twice, and missed streams that came in through a nested promise. so f0efe7d keeps that path throwing like it does on main (clearer message, plus a test for the rejection), and this PR is just forwarding.

making it actually work is #303, your test would go there.

ndisidore added a commit to cloudflare/cloudflare-os that referenced this pull request Nov 16, 2026
A stream the session returns does not reach the gadget UI frame: capnweb
cannot forward one from the server's session into the frame's
(cloudflare/capnweb#296). Google states an image's length, which still
bounds what is read.

@ndisidore ndisidore left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Self-review by an AI agent (Claude Code /code-review, high effort). Five inline comments: one behaviour regression on the new branch, the rest low severity. Each repro was run on the Node project against this head and against main. Cancel, error and dispose-without-reading all propagate through the hop with clean stats in both sessions.

Comment thread src/core.ts Resolved
Comment thread src/core.ts Resolved
Comment thread src/core.ts Resolved
Comment thread src/core.ts Resolved
Comment thread .changeset/forward-readable-streams.md Resolved

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of 57eef2d3.

This review, of c10a31a5

✅ Approved — This is a focused fix with no issues found. Serialized streams get a new hook, copying a stream out of an owned payload still throws with a clearer message, and tests cover forwarding, a call through a pending RpcPromise and the refused copy.

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 concerns in this change.


📖 AGENTS.md: ✅ LGTM

No agent instruction files are affected.


📋 Code Quality: ✅ LGTM

Serialize path: the owned branch of getHookForReadableStream (src/core.ts:1038-1042) now creates a new hook, the same way the params branch does. The serializer pipes the stream through that hook. The pipe locks the stream immediately, so the payload's own hook can't cancel it.

Deep-copy check: when the owner is owned, the check in deepCopy (src/core.ts:1175-1179) still throws, as on main, now with a clearer message. ensureDeepCopied is unaffected.

Tests: they cover a stream returned and a stream passed through a forwarding stub, a call queued on a pending RpcPromise, and the refused copy.


⚡ Performance: ✅ LGTM

No performance concerns in this change.


📝 Documentation: ✅ LGTM

The changeset entry and the inline comments match the code's behaviour.


Reviewed commit: c10a31a5

@ndisidore
ndisidore requested a review from kentonv November 17, 2026 17:18

@clanky-the-clanker clanky-the-clanker Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Approved — A focused fix with no issues found. Serializing an owned payload gives the stream a new hook. Copying a stream out of an owned payload still throws, now with a clearer message, and the new tests cover the queued Request body path.

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 concerns in this change.


📖 AGENTS.md: ✅ LGTM

This pull request doesn't touch any agent instruction files.


📋 Code Quality: ✅ LGTM

  • Serialize path (src/core.ts:1038-1042): when the payload is owned, getHookForReadableStream now creates a new hook, the same way it does for params. Its only callers are the serializer paths in src/serialize.ts. The pipe locks the stream as soon as it is created, so the payload's own hook can't cancel it.
  • Deep-copy refusal (src/core.ts:1175-1179): deepCopy throws for an owned payload before it reaches getHookForReadableStream. A Request body copied out of an owned payload is refused the same way. The message matches what the new test checks for.
  • Tests: they cover:
    • a stream returned through a forwarding stub, and a stream passed through one;
    • a ReadableStream and a Request body sent in a call through a pending RpcPromise;
    • the refused copy, which also checks that the result's own stream still reads.

⚡ Performance: ✅ LGTM

No performance concerns in this change.


📝 Documentation: ✅ LGTM

The changeset entry and the inline comments match what the code does.


Reviewed commit: 57eef2d3

@ndisidore
ndisidore merged commit 66ed2fd into main Nov 18, 2026
11 checks passed
@github-actions github-actions Bot mentioned this pull request Nov 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

ReadableStream cannot be returned through a forwarded stub

3 participants