Also unlike Cap'n Proto, Cap'n Web's underlying serialization is human-readable. It's just
JSON, with a little pre- and post-processing.
It works over HTTP, WebSocket, and postMessage() out of the box, and can be extended to other
transports easily.
It works in all major browsers, Cloudflare Workers, Node.js, Bun, Deno, and other modern
JavaScript runtimes.
The whole thing compresses (minify + gzip) to under 16 kB with no dependencies.
Cap'n Web is more expressive than almost every other RPC system, because it implements an
object-capability RPC model. That means it supports bidirectional calling, passing functions
and objects by reference, promise pipelining (chaining dependent calls into a single network
round trip), and capability-based security patterns, where holding a reference is the
permission to use it.
There is no build step, no schema compiler, and no code generation.
import { RpcTarget, newWebSocketRpcSession } from "capnweb";
To use using declarations, your tsconfig.json needs "target": "esnext" and matching libs.
See Installation.
Example
A client looks like this:
import { newWebSocketRpcSession } from "capnweb";// One-line setup.let api = newWebSocketRpcSession("wss://example.com/api");// Call a method on the server!let result = await api.hello("World");console.log(result);
Here's the server:
import { RpcTarget, newWorkersRpcResponse } from "capnweb";// This is the server implementation.class MyApiServer extends RpcTarget { hello(name) { return `Hello, ${name}!` }}// Standard Cloudflare Workers HTTP handler.//// (Node, Deno, Bun and other runtimes are supported too.)export default { fetch(request, env, ctx) { // Parse URL for routing. let url = new URL(request.url); // Serve API at `/api`. if (url.pathname === "/api") { return newWorkersRpcResponse(request, new MyApiServer());
And here is the part that makes it interesting. Three dependent calls, one round trip:
using api = newHttpBatchRpcSession<Api>("https://example.com/api");// No awaits, so no round trips yet.using authed = api.authenticate(apiToken);let friendIds = authed.getFriendIds();// One await. One round trip. Everything above travelled together.let friends = await friendIds.map(id => api.getUserProfile(id));
Documentation
The documentation site is the source of truth. It is an Astro + Starlight site
under packages/docs/, and every page is readable as Markdown directly on GitHub.
worker-react: a React app against a Cap'n Web Worker, with runtime
validation at the RPC boundary.
session-recovery: a WebSocket session with a button that kills
it, showing what a disconnect destroys and what it takes to resume without a gap.
Related packages
capnweb-validate: generates runtime validators from your
TypeScript types at build time, since TypeScript types are erased and a malicious peer can send
anything.
Security
Cap'n Web gives you strong authorization tools, but a few things are your responsibility:
authenticating in-band rather than with cookies, rate-limiting because pipelining is cheap for
attackers, setting transport payload limits, and validating types at runtime. Read
Security considerations before exposing a
service to untrusted peers.
Bug reports and pull requests are welcome. Note that packages/docs/ is the source of truth for
user-facing documentation; behaviour changes should update the relevant page there.