Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions .agents/skills/capnweb/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,15 @@ name: capnweb
description: |
capnweb RPC patterns for this repo, with a heavy focus on stub lifecycle
and disposal. Load when touching anything that crosses the Durable Object
wsd boundary: packages/rpc, packages/workspace, the wsd client, or the
computerd boundary: packages/rpc, packages/computer, the computerd client, or the
Durable Object server. Triggers include "capnweb", "RpcTarget", "stub",
"RPC wire", "promise pipelining", "stub disposal", "RpcPromise".
---

# capnweb in this repo

[capnweb](https://github.com/cloudflare/capnweb) is the RPC framing
between the Durable Object and `wsd`. It's an object-capability RPC
between the Durable Object and `computerd`. It's an object-capability RPC
system with promise pipelining, structured-clone-style transfer of
stubs, and bidirectional calls. The wire format used here is text
JSON over a long-lived WebSocket, with an HTTP batch alternative.
Expand All @@ -23,7 +23,7 @@ JSON over a long-lived WebSocket, with an HTTP batch alternative.
`SyncRPC` and `ShellRPC`. Add new methods here first.
- [`packages/rpc/src/server.ts`](../../../packages/rpc/src/server.ts)
— `Database`-backed implementation. Imported by the Durable Object
and the in-container workspace-server.
and the in-container computerd.
- [`packages/rpc/src/client.ts`](../../../packages/rpc/src/client.ts)
— typed stubs over a WebSocket carrier. The Durable Object uses a
deferred transport so the stub can be created before the upgrade
Expand All @@ -50,7 +50,7 @@ side of the connection.
This matters more here than in many capnweb deployments because the
connection is **long-lived**. HTTP batch sessions auto-dispose
everything when the batch ends, but our WebSocket between the
Durable Object and `wsd` stays up for the lifetime of the workspace.
Durable Object and `computerd` stays up for the lifetime of the workspace.
Every undisposed stub stays alive until that connection drops.

## The caller-disposes rule
Expand Down Expand Up @@ -163,7 +163,7 @@ dispose call per stub. To collapse them into one, wrap the target in
`stub.onRpcBroken(cb)` fires when the stub becomes unusable —
typically because the underlying connection dropped or, for a
promise, because the promise rejected. After the callback runs every
method call on that stub will throw. `packages/workspace` already
method call on that stub will throw. `packages/computer` already
folds `onRpcBroken` into the workspace's closed promise; reuse that
plumbing rather than wiring up a parallel listener.

Expand Down Expand Up @@ -232,7 +232,7 @@ envelope to release every stub it contains.
contain stubs — futureproofing is cheap.
- **Do** call `.dup()` rather than awaiting twice when you need a
stub copy to outlive a callee's auto-dispose.
- **Do** run the leak harness (`script/wsd-stub-soak`) when you
- **Do** run the leak harness (`script/computerd-stub-soak`) when you
change anything around RPC lifecycle, and check
`session.getStats()` for drift.
- **Don't** send binary WebSocket frames. The wire is text JSON.
Expand All @@ -249,11 +249,11 @@ envelope to release every stub it contains.

- Use `enableStubTracking()` + `stubSnapshot()` in a test to assert
no stub survives a round trip you expected to clean up.
- Soak the boundary with `script/wsd-stub-soak` for
- Soak the boundary with `script/computerd-stub-soak` for
disposal-sensitive changes; it reads `session.getStats()` to
detect drift.
- Server-side RPC behavior is tested against the real `Database`
and real driver helpers in `packages/rpc` and `packages/workspace`.
and real driver helpers in `packages/rpc` and `packages/computer`.

## Further reading

Expand Down
10 changes: 5 additions & 5 deletions .agents/skills/cloudflare/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ These three cover almost every change in this repo:

| Skill | Load when |
|---|---|
| [`durable-objects`](https://github.com/cloudflare/skills/tree/main/skills/durable-objects) | Writing or reviewing Durable Object code: RPC methods, SQLite storage, alarms, WebSockets, hibernation. Most work in `packages/dofs` and `packages/workspace` qualifies. |
| [`durable-objects`](https://github.com/cloudflare/skills/tree/main/skills/durable-objects) | Writing or reviewing Durable Object code: RPC methods, SQLite storage, alarms, WebSockets, hibernation. Most work in `packages/dofs` and `packages/computer` qualifies. |
| [`workers-best-practices`](https://github.com/cloudflare/skills/tree/main/skills/workers-best-practices) | Writing or reviewing Worker code: streaming, floating promises, global state, bindings, secrets, observability, `wrangler.jsonc` configuration. |
| [`agents-sdk`](https://github.com/cloudflare/skills/tree/main/skills/agents-sdk) | Building on the Cloudflare Agents SDK: stateful agents, Workflows integration, scheduled tasks, MCP servers. Relevant to [`examples/think`](../../../examples/think). |

Expand All @@ -39,7 +39,7 @@ Load these when their trigger applies:
|---|---|
| [`wrangler`](https://github.com/cloudflare/skills/tree/main/skills/wrangler) | Running `wrangler` commands: deploy, dev, secrets, bindings for KV, R2, D1, Vectorize, Hyperdrive, Queues, Workflows, Containers. |
| [`cloudflare`](https://github.com/cloudflare/skills/tree/main/skills/cloudflare) | General Cloudflare platform questions outside the more specific skills above — KV, R2, D1, Vectorize, networking, security, infrastructure-as-code. |
| [`sandbox-sdk`](https://github.com/cloudflare/skills/tree/main/skills/sandbox-sdk) | Building or reviewing sandboxed-execution code paths. Relevant to [`examples/container`](../../../examples/container) and to the `wsd` container model in general. |
| [`sandbox-sdk`](https://github.com/cloudflare/skills/tree/main/skills/sandbox-sdk) | Building or reviewing sandboxed-execution code paths. Relevant to [`examples/container`](../../../examples/container) and to the `computerd` container model in general. |
| [`web-perf`](https://github.com/cloudflare/skills/tree/main/skills/web-perf) | Profiling page load, Core Web Vitals, or render-blocking issues. Rarely relevant in this repo, but listed for completeness. |
| [`cloudflare-email-service`](https://github.com/cloudflare/skills/tree/main/skills/cloudflare-email-service) | Working with Cloudflare Email Routing or the Email Workers binding. Not currently used in this repo. |

Expand All @@ -50,12 +50,12 @@ Load these when their trigger applies:
before changing storage shape, RPC methods, or alarm handling.
Load [`workers-best-practices`](https://github.com/cloudflare/skills/tree/main/skills/workers-best-practices)
for the surrounding Worker glue.
- **`packages/workspace`** runs inside the Durable Object and
exposes the capnweb `WorkspaceRPC` to `wsd`. Load
- **`packages/computer`** runs inside the Durable Object and
exposes the capnweb `WorkspaceRPC` to `computerd`. Load
[`durable-objects`](https://github.com/cloudflare/skills/tree/main/skills/durable-objects)
for the hosting model and the [`capnweb`](../capnweb/SKILL.md)
skill for the RPC surface itself.
- **`packages/wsd`** runs in a sandbox container, not in a Worker.
- **`packages/computerd`** runs in a sandbox container, not in a Worker.
Load [`sandbox-sdk`](https://github.com/cloudflare/skills/tree/main/skills/sandbox-sdk)
if you're working on the container boundary; the FUSE and
HTTP/WebSocket internals are local to the package.
Expand Down
Loading
Loading