feat: construct RpcPromise from a Promise by ndisidore · Pull Request #242 · cloudflare/capnweb

ndisidore · 2026-08-12T19:30:07Z

You can now write new RpcPromise(promise) (resolves the TODO). Calls made before the promise settles are queued and delivered in order once it does, and awaiting it yields the resolution. The promise can resolve to an RpcTarget, a stub, or a plain value.

@kentonv mentioned this re: reconnection in cloudflare-os#172

Passing an existing RpcPromise adopts its hook directly rather than awaiting it. Two caveats are documented in the README: ownership of the resolution transfers to the RpcPromise (resolve with a dup() if you also keep the stub), and pending calls queue unboundedly (reject the promise when giving up).

Stacked because the new tests exercise rejection and dispose-before-resolution paths that only behave correctly with the PromiseStubHook fixes in #241. Landing that first keeps this diff feature-only.

changeset-bot · 2026-08-12T19:30:12Z

🦋 Changeset detected

Latest commit: 33c0122

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

This PR includes changesets to release 1 package

Name	Type
capnweb	Minor

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 · 2026-08-12T19:30:39Z

Open in StackBlitz

npm i https://pkg.pr.new/cloudflare/capnweb@242

commit: 33c0122

…ind queued calls PromiseStubHook.call() and .stream() deep-copy their arguments before chaining on the backing promise, but if that promise rejects, the copies were never disposed, leaking any stubs they contained. PromiseStubHook.dispose() also had a fast path that disposed the resolution synchronously once available. A call chained on the promise just before disposal could then be delivered after its target was already disposed, violating ordering. Disposal now always chains on the promise so it stays behind previously queued calls.

ErrorStubHook.call() ignored the arguments it takes ownership of, and ErrorStubHook.map() likewise ignored its captures, so anything forwarded to a broken or disposed hook leaked. ValueStubHook.call() had the same gap on its error path (its own map() already disposes captures there), and PromiseStubHook's forwarding continuations did not clean up when the destination hook threw synchronously.

Resolves the long-standing TODO on the RpcPromise constructor: the application may now pass a Promise (or any other thenable) for the eventual resolution. Calls made before the promise settles are queued and delivered in order once it does, so an RpcPromise can stand in for a capability that doesn't exist yet -- for example, one that will only become available after a broken session has been re-established. The promise may resolve to an RpcTarget, a stub, or a plain value. Promise.resolve() performs thenable assimilation natively, so no hand-rolled hardening against misbehaving thenables is needed. The resolution is adopted with return semantics (the same representation used for resolutions of local async calls), so awaiting delivers the value, pipelined calls forward through it without forcing a pull, and brokenness of a stub resolution is preserved. Passing an existing RpcPromise adopts its hook directly, keeping it lazy. A rejection is adopted as an ErrorStubHook rather than left to reject the backing promise, so the promise chains behind queued calls never reject: calls land on the ErrorStubHook (which disposes their arguments) and the error surfaces only through pull() or onBroken(). Without this, a discarded pipelined call on a promise-backed stub would raise an unhandled rejection event when the promise rejects (crashing Node under its default handling), even though fire-and-forget calls on the session-backed stub it stands in for reject only on pull.

- Only adopt the hook of an existing RpcPromise; a bare stub's hook may not implement pull(), so bare stubs now take the generic path, whose resolution payload handles them correctly (await previously rejected with "Tried to resolve a non-promise stub."). Regression test added. - Inline hookForPromiseArg and hookForResolution into the constructor. - Collapse the constructor's type overloads into a single signature, narrowing the accepted type to Promise (runtime still assimilates arbitrary thenables). - Reframe the README section around the local-loopback RPC equivalence, and align the jsdoc and changeset with it.

ndisidore · 2026-08-12T23:32:44Z

@ask-bonk review this

ask-bonk

Review — LGTM

Re-reviewed at 33c0122, which addresses all four of @kentonv's review comments. Verified locally: build succeeds, test:types passes, and all 178 tests in index.test.ts pass on node, chromium, and workerd.

Review feedback resolution

Type overloads (src/index.ts) — the two overloads are collapsed into a single new <T extends RpcCompatible<T>>(value: Promise<T | Stub<T>>): RpcPromise<T>, and PromiseLike was dropped (non-Promise thenables no longer accepted, as agreed). Inference works without an explicit <T> — the type tests confirm new RpcPromise(Promise.resolve(pointStub)) infers RpcPromise<PointTarget> (__type-tests__/rpc-base-cases.test.ts:160-162).
hookForResolution one-liner — inlined.
hookForPromiseArg — inlined into the constructor.
The bare-stub bug — the real catch. The branch is now gated on typeForRpc(hook) === "rpc-promise" only (src/core.ts:555), so a bare RpcStub no longer has its non-promise hook adopted directly (which couldn't answer pull()); it falls through to the payload path instead. Covered by the regression test "resolves when awaited after construction from a bare local stub" (__tests__/index.test.ts).

Correctness

Rejection is adopted as an ErrorStubHook and the backing PromiseStubHook promise never rejects; combined with ignoreUnhandledRejections(), discarded pipelined calls, awaits, and map() results can't leak unhandled rejections. All three "does not report an unhandled rejection…" tests pass.
Disposal is correctly ordered behind queued calls via PromiseStubHook.dispose() — the "delivers a call initiated before disposal" and "disposes the eventual target when disposed before resolution" tests exercise exactly the ordering paths that rely on the #241 fixes, which justifies the stacking.
Adopting an existing RpcPromise directly preserves laziness (only one ["pull"] is sent) and brokenness — verified by the "keeps an adopted RpcPromise lazy" and "preserves brokenness" tests.
No wire-protocol change (client-side construction reusing existing representations), so no protocol.md update needed. Changeset present (minor). README documents the ownership-transfer and unbounded-queue caveats.

No logic bugs, capability leaks, or backward-compat concerns found. Ship it.

kentonv · 2026-08-13T21:14:45Z

 export type RpcPromise<T extends RpcCompatible<T>> = RpcPromiseType<T>;
 export const RpcPromise: {
-  // Note: Cannot construct directly!
+  new <T extends RpcCompatible<T>>(value: Promise<T | Stub<T>>): RpcPromise<T>;


I don't understand why we need | Stub<T> here.

Doesn't it block type inference? It seems like it would.

Either way though, I don't see why it would be needed.

This comment was marked as outdated.

Sign in to view

ndisidore force-pushed the feat/from-promise branch 3 times, most recently from 0535521 to 1ecfa82 Compare August 12, 2026 21:23

ndisidore marked this pull request as ready for review August 12, 2026 21:24

ndisidore added 3 commits August 12, 2026 16:33

ndisidore force-pushed the fix/promise-stubhook-disposal branch from 1cd41dc to ed803fe Compare August 12, 2026 21:35

ndisidore force-pushed the feat/from-promise branch from 1ecfa82 to 1065dbf Compare August 12, 2026 21:35

kentonv reviewed Aug 12, 2026

View reviewed changes

Comment thread src/index.ts Outdated

Comment thread src/core.ts Outdated

Comment thread src/core.ts Outdated

Comment thread src/core.ts Outdated

Comment thread README.md Outdated

ndisidore requested a review from kentonv August 12, 2026 23:32

ask-bonk Bot reviewed Aug 12, 2026

View reviewed changes

This comment was marked as off-topic.

Sign in to view

kentonv reviewed Aug 13, 2026

View reviewed changes

ndisidore force-pushed the fix/promise-stubhook-disposal branch 2 times, most recently from c93a265 to a8be070 Compare August 14, 2026 02:06

Navigation Menu

Uh oh!

feat: construct RpcPromise from a Promise - #242

feat: construct RpcPromise from a Promise#242
ndisidore wants to merge 4 commits into
fix/promise-stubhook-disposalfrom
feat/from-promise

ndisidore commented Aug 12, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Aug 12, 2026 •

edited

Loading

Uh oh!

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

edited

Loading

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ndisidore commented Aug 12, 2026

Uh oh!

ask-bonk Bot left a comment

Uh oh!

This comment was marked as off-topic.

This comment was marked as off-topic.

kentonv Aug 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

ndisidore commented Aug 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot Bot commented Aug 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

pkg-pr-new Bot commented Aug 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ndisidore commented Aug 12, 2026

Uh oh!

ask-bonk Bot left a comment

Choose a reason for hiding this comment

Review — LGTM

Review feedback resolution

Correctness

Uh oh!

This comment was marked as off-topic.

This comment was marked as off-topic.

kentonv Aug 13, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ndisidore commented Aug 12, 2026 •

edited

Loading

changeset-bot Bot commented Aug 12, 2026 •

edited

Loading

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

edited

Loading