Cap'n Web

This example demonstrates a full-stack Cap'n Web implementation:

• Server: A Cloudflare Worker exposing a Cap'n Web API at the /api endpoint (server/worker.ts). It uses @validateRpc() for server-boundary runtime validation.
• Client: A React/Vite application (client/) that uses Cap'n Web client sessions wrapped with validateStub() for explicit client stub validation.
• Validation: wrangler.jsonc is configured to run capnweb-validate build before starting. Worker validation output is located at .wrangler/validate/worker.ts.

The repository includes two primary examples demonstrating different deployment environments and advanced RPC patterns:

1. batch-pipelining: Demonstrates a Node.js server and client setup. It focuses on batching and pipelining, showing how to execute a dependent sequence of RPC calls in a single HTTP round trip to improve performance compared to sequential calls.
2. worker-react: Demonstrates a Cloudflare Worker backend paired with a React frontend. This shows how to implement the same RPC patterns from a browser-based application served by a Worker.

Use newWorkersRpcResponse(request, apiImplementation) to create a Cloudflare Worker handler that supports both HTTP batch and WebSocket APIs simultaneously.

Compatibility Note: Cap'n Web is compatible with Workers' built-in RPC. For best results, set your Workers compatibility date to 2026-01-20 or enable the rpc_params_dup_stubs flag.

import { RpcTarget, newWorkersRpcResponse } from "capnweb";

class MyApiImpl extends RpcTarget implements MyApi {
  getUserInfo(): UserInfo { return this.userInfo; }
  greet(name: string): string { return `Hello, ${name}!`; }
};

export default {
  fetch(request: Request, env, ctx) {
    let url = new URL(request.url);
    if (url.pathname === "/api") {
      return newWorkersRpcResponse(request, new MyApiImpl());
    }
    return new Response("Not found", {status: 404});
  }
}

Apply the @validateRpc() decorator to your service class (e.g., classes extending RpcTarget, WorkerEntrypoint, or DurableObject). This injects validators generated from your TypeScript types.

By default, the RPC surface includes all public string-named methods and RPC-readable getters/properties. To restrict the RPC surface to a specific interface, use @validateRpc<SomeInterface>().

import { newWorkersRpcResponse, RpcTarget } from "capnweb";
import { validateRpc } from "capnweb-validate";

type User = { id: string; name: string };

@validateRpc()
export class Api extends RpcTarget {
  async authenticate(sessionToken: string): Promise<User> {
    // ...
  }
}

export default {
  async fetch(request: Request, env: Env) {
    return newWorkersRpcResponse(request, new Api());
  },
};

You can pass ReadableStream or WritableStream objects over RPC. Cap'n Web automatically handles the following:

• Automatic conversion: Creates equivalent streams at the receiving end.
• Flow control: Uses the bandwidth-delay product to apply backpressure, ensuring high utilization while minimizing buffer bloat.
• Multiplexing: Multiple streams can be sent over the same connection via multiplexing (similar to HTTP/2).

Use the appropriate plugin for your bundler to transform modules in memory. Supported plugins include Vite, Rollup, Webpack, Rspack, Esbuild, and Farm.

import capnwebValidate from "capnweb-validate/vite";     // or
import capnwebValidate from "capnweb-validate/rollup";    // or
import capnwebValidate from "capnweb-validate/webpack";   // or
import capnwebValidate from "capnweb-validate/rspack";   // or
import capnwebValidate from "capnweb-validate/esbuild";   // or
import capnwebValidate from "capnweb-validate/farm";

export default {
  plugins: [capnwebValidate()],
};

Cap'n Web can communicate over MessagePort (e.g., between a browser window and a Web Worker).

1. Create a MessageChannel.
2. Initialize the server using newMessagePortRpcSession(port1, apiImplementation).
3. Initialize the client using newMessagePortRpcSession<T>(port2).

Security Note: Do not use a Window object directly as a port. Always create a MessageChannel and transfer one of its ports via postMessage() to ensure the sender is authenticated.

import { RpcTarget, RpcStub, newMessagePortRpcSession } from "capnweb";

class Greeter extends RpcTarget {
  greet(name: string): string { return `Hello, ${name}!`; }
};

let channel = new MessageChannel();
newMessagePortRpcSession(channel.port1, new Greeter());
using stub: RpcStub<Greeter> = newMessagePortRpcSession<Greeter>(channel.port2);

console.log(await stub.greet("Alice"));

Because decorators are emitted at the class declaration, they cannot specialize validators for different type arguments in generic classes.

1. Known types: Use an explicit interface at the decorator site: @validateRpc<Gatekeeper<GmailSession, number, undefined>>().
2. Unconstrained types: If you use @validateRpc() on a class like ArrayCursor<T>, T defaults to any (with a warning). To validate against a constraint, use <T extends Session>.
3. Silencing warnings: Use @validateRpc<Cursor<any>>() to keep positions permissive without warnings.

@validateRpc<Gatekeeper<GmailSession, number, undefined>>()
class GmailGatekeeper
  extends RpcTarget
  implements Gatekeeper<GmailSession, number, undefined> {
  // ...
}

Cap'n Web is available as an npm package. Install it using the following command:

npm i capnweb