cloudflare / cloudflare/workerd
Support for Hibernatable RPC Targets in Workers Runtime (Enable `capnweb` hibernation within Durable Objects)
- Dominant language
- C++
- Stars
- 8.7k
- Forks
- 739
- Avg merge
- 2d 20h
- Merged PRs (30d)
- 174
Description
**Summary**
There is a fundamental architectural gap between the Durable Object lifecycle model and high-level RPC frameworks like [`capnweb`](https://github.com/cloudflare/capnweb).
Currently, `capnweb` implementation details prevent Durable Object hibernation by keeping the object active in memory. More importantly, the Workers runtime hibernation mechanism does not support `RpcTarget` objects surviving isolate eviction and reconstruction.
Relevant documentation:
- Durable Object lifecycle (eviction & reconstruction):
https://developers.cloudflare.com/durable-objects/concepts/durable-object-lifecycle/
- Workers RPC API:
https://developers.cloudflare.com/workers/runtime-apis/rpc/
---
## The Problem: Isolate Pinning and RPC Targets
### 1. Active Listener Pinning
`capnweb` registers event listeners directly on the WebSocket transport (see [`src/websocket.ts`](https://github.com/cloudflare/capnweb/blob/main/src/websocket.ts)).
Durable Objects may be evicted and later reconstructed according to the lifecycle model. However, as long as the WebSocket is active and event listeners are registered, the object does not become idle and cannot be hibernated. This effectively pins the isolate in memory.
**In contrast**, the [WebSocket Hibernation API](https://developers.cloudflare.com/durable-objects/best-practices/websockets/#websocket-hibernation-api) was designed precisely for this scenario: calling `ctx.acceptWebSocket(ws)` allows Durable Objects to hibernate while keeping WebSocket connections alive and active, with the runtime transparently reconstructing the object on the next event. However this currently doesn't work for RPC.
---
### 2. Missing Runtime Support for Hibernatable `RpcTarget`s
The Workers runtime currently does not support hibernation of `RpcTarget` objects.
When a Durable Object is evicted, its isolate is destroyed and later reconstructed by re-running the constructor. Any `RpcTarget` instances created within the isolate are tied to that specific runtime instance. There is no mechanism in the Workers RPC layer to preserve, serialize, or transparently rebind `RpcTarget` references across isolate swaps.
As a result:
- Client-held RPC references cannot survive Durable Object hibernation.
- RPC sessions cannot remain logically valid across isolate reconstruction.
- High-level RPC frameworks cannot safely integrate with Durable Object hibernation.
---
## Architectural Requirement
In the [discussion of capnweb issue #36](https://github.com/cloudflare/capnweb/issues/36), it was suggested that solving this class of problems would likely require runtime-level support (see especially the comments validating the need for hibernatable `RpcTarget`s and stub persistence through hibernation). While a workaround could involve introducing a stateless proxy Worker, the architectural objective is to terminate the WebSocket/RPC session directly inside the Durable Object.
To achieve this, the Workers runtime must bridge isolate lifecycle transitions without invalidating RPC targets.
**cc @kentonv**
---
## Proposed Requirements for `workerd`
- **Hibernatable `RpcTarget`s**
The Workers runtime RPC layer should support `RpcTarget` objects that survive isolate eviction, ensuring that client-held references remain valid across isolate swaps.
- **Isolate-Independent RPC Binding**
The runtime should allow a Durable Object to hibernate while an RPC session is idle and transparently rebind `RpcTarget` instances when the object is reconstructed.
---
## Technical Impact
Runtime-level support for hibernatable RPC targets would:
- Enable fully stateful RPC directly inside Durable Objects
- Eliminate the need to keep V8 isolates alive during idle periods
- Prevent protocol breakage caused by isolate reconstruction
- Remove the architectural need for proxy indirection layers
---
## Affected Components
- `workerd` (Durable Object lifecycle & native RPC layer)
- `capnweb`
https://github.com/cloudflare/capnweb
Contributor guide
Assessment
This issue has not been assessed yet.