Allow sending `Fetcher` (service bindings) over RPC by kentonv · Pull Request #5693 · cloudflare/workerd

kentonv · 2025-12-14T03:23:51Z

Fetchers, aka SerivceStubs, aka SubrequestChannels, point at a stateless entrypoint of some other Worker.

DurableObjectClass stubs, aka ActarClassChannels, point at a DO class exported by some other Worker. Note: This is not the same thing as a Durable Object stub. A DurableObjectClass stub points at the class itself, independent of storage or any particular instances. It is used as part of Facets.

We want to make both of these serializable.

The serialization uses a byte string called a "channel token" (because it's a token obtained off a SubrequestChannel or ActorClassChannel, which can later be redeemed from IoChannelFactory for a new instance of the given channel type).

A channel token encodes a (service name, entrypoint name, props) triplet. Note that it would be very bad if an attacker were able to specify such a triplet directly, particularly as props usually contains authorization details that we don't want an attacker to be able to forge!

To that end, the channel token format is conservatively-designed at present:

For RPC, the token is encrypted and MAC'd using an AES key which is generated uniquely for each process. This means that tokens are only valid within the same process where they were created, and there's no way to forge such a token unless you can see into the process's memory. In the future, we may loosen things to allow sending tokens between processes somehow. For now, though, this format has the nice side property that there is no backwards-compatibility expectation at all, so we're free to change it later.

This PR also defines a format for tokens intended for long-term storage, e.g. to store in DO KV storage. Such tokens obviously cannot be signed by a per-process key since we want them to survive through process reloads. For the time being, we don't enrypt such tokens at all, but the feature will be hidden behind a new compat flag which will remain strictly experimental. This feature will eventually be replaced with a system that actually stores information about known "grants" in some separate storage, so that they can be audited and revoked.

For now, serialization for RPC is guarded by the common experimental compat flag, and serialization for storage is guarded by the extra flag allow_irrevocable_stub_storage.

src/workerd/api/actor.c++

src/workerd/server/channel-token.c++

src/workerd/api/http.c++

src/workerd/server/channel-token.c++

src/workerd/api/worker-rpc.c++

src/workerd/server/channel-token.c++

kentonv · 2025-12-18T19:47:56Z

Typo fixes:

Bug fix:

c8019f4

Fetchers, aka SerivceStubs, aka SubrequestChannels, point at a stateless entrypoint of some other Worker. DurableObjectClass stubs, aka ActarClassChannels, point at a DO class exported by some other Worker. Note: This is not the same thing as a Durable Object stub. A DurableObjectClass stub points at the class itself, independent of storage or any particular instances. It is used as part of Facets. We want to make both of these serializable. This commit defines a core format to do so (but doesn't hook it up yet). The serialization uses a byte string called a "channel token" (because it's a token obtained off a SubrequestChannel or ActorClassChannel, which can later be redeemed from IoChannelFactory for a new instance of the given channel type). A channel token encodes a (service name, entrypoint name, props) triplet. Note that it would be very bad if an attacker were able to specify such a triplet directly, particularly as `props` usually contains authorization details that we don't want an attacker to be able to forge! To that end, the channel token format is conservatively-designed at present: For RPC, the token is encrypted and MAC'd using an AES key which is generated uniquely for each process. This means that tokens are only valid within the same process where they were created, and there's no way to forge such a token unless you can see into the process's memory. In the future, we may loosen things to allow sending tokens between processes somehow. For now, though, this format has the nice side property that there is no backwards-compatibility expectation at all, so we're free to change it later. This commit also defines a format for tokens intended for long-term storage, e.g. to store in DO KV storage. Such tokens obviously cannot be signed by a per-process key since we want them to survive through process reloads. For the time being, we don't enrypt such tokens at all, but the feature will be hidden behind a new compat flag (defined in later commits) which will remain strictly experimental. This feature will eventually be replaced with a system that actually stores information about known "grants" in some separate storage, so that they can be audited and revoked.

(And also DurableObjectClass stubs.) For now, serialization for RPC is guarded by the common `experimental` compat flag, and serialization for storage is guarded by the extra flag `allow_irrevocable_stub_storage`.

If an RPC returns a Fetcher (newly allowed by previous commit), it should also accept pipelined calls to the Fetcher's methods.

Adds a test for this bug.

kentonv · 2025-12-19T01:19:36Z

Missed the daily release by 29 minutes. 😠

Oh well.

kentonv requested review from a team as code owners December 14, 2025 03:23

kentonv force-pushed the kenton/serializable-fetchers branch 3 times, most recently from 33c33e0 to c898b53 Compare December 14, 2025 16:00

kentonv requested review from harrishancock and jp4a50 December 14, 2025 21:43