capnweb 0.0.0-6d805d4 → 0.0.0-6f790b5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +69 -5
- package/dist/index-bun.cjs +3230 -0
- package/dist/index-bun.cjs.map +1 -0
- package/dist/index-bun.d.cts +518 -0
- package/dist/index-bun.d.ts +518 -0
- package/dist/index-bun.js +3210 -0
- package/dist/index-bun.js.map +1 -0
- package/dist/index-workers.cjs +3038 -2546
- package/dist/index-workers.cjs.map +1 -1
- package/dist/index-workers.d.cts +397 -2
- package/dist/index-workers.d.ts +397 -2
- package/dist/index-workers.js +3001 -2519
- package/dist/index-workers.js.map +1 -1
- package/dist/index.cjs +3007 -2525
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +227 -194
- package/dist/index.d.ts +227 -194
- package/dist/index.js +2997 -2518
- package/dist/index.js.map +1 -1
- package/package.json +30 -18
package/README.md
CHANGED
|
@@ -6,7 +6,7 @@ Cap'n Web is a spiritual sibling to [Cap'n Proto](https://capnproto.org) (and is
|
|
|
6
6
|
* That said, it integrates nicely with TypeScript.
|
|
7
7
|
* Also unlike Cap'n Proto, Cap'n Web's underlying serialization is human-readable. In fact, it's just JSON, with a little pre-/post-processing.
|
|
8
8
|
* It works over HTTP, WebSocket, and postMessage() out-of-the-box, with the ability to extend it to other transports easily.
|
|
9
|
-
* It works in all major browsers, Cloudflare Workers, Node.js, and other modern JavaScript runtimes.
|
|
9
|
+
* It works in all major browsers, Cloudflare Workers, Node.js, Bun, Deno, and other modern JavaScript runtimes.
|
|
10
10
|
The whole thing compresses (minify+gzip) to under 10kB with no dependencies.
|
|
11
11
|
|
|
12
12
|
Cap'n Web is more expressive than almost every other RPC system, because it implements an object-capability RPC model. That means it:
|
|
@@ -199,15 +199,15 @@ The following types can be passed over RPC (in arguments or return values), and
|
|
|
199
199
|
* Arrays
|
|
200
200
|
* `bigint`
|
|
201
201
|
* `Date`
|
|
202
|
-
* `
|
|
202
|
+
* `ArrayBuffer`, `DataView`, and typed arrays
|
|
203
203
|
* `Error` and its well-known subclasses
|
|
204
|
+
* `Blob`
|
|
205
|
+
* `ReadableStream` and `WritableStream`, with automatic flow control.
|
|
206
|
+
* `Headers`, `Request`, and `Response` from the Fetch API.
|
|
204
207
|
|
|
205
208
|
The following types are not supported as of this writing, but may be added in the future:
|
|
206
209
|
* `Map` and `Set`
|
|
207
|
-
* `ArrayBuffer` and typed arrays other than `Uint8Array`
|
|
208
210
|
* `RegExp`
|
|
209
|
-
* `ReadableStream` and `WritableStream`, with automatic flow control.
|
|
210
|
-
* `Headers`, `Request`, and `Response`
|
|
211
211
|
|
|
212
212
|
The following are intentionally NOT supported:
|
|
213
213
|
* Application-defined classes that do not extend `RpcTarget`.
|
|
@@ -305,6 +305,10 @@ The trick here is record-replay: On the calling side, Cap'n Web will invoke your
|
|
|
305
305
|
|
|
306
306
|
Since all of the not-yet-determined values seen by the callback are represented as `RpcPromise`s, the callback's behavior is deterministic. Any actual computation (arithmetic, branching, etc.) can't possibly use these promises as (meaningful) inputs, so would logically produce the same results for every invocation of the callback. Any such computation will actually end up being performed on the sending side, just once, with the results being imbued into the recording.
|
|
307
307
|
|
|
308
|
+
### Streaming with flow control
|
|
309
|
+
|
|
310
|
+
You may pass a `ReadableStream` or `WritableStream` over RPC. When doing so, the RPC system automatically creates an equivalent stream at the other end and pumps bytes (or arbitrarily-typed chunks) across. This is done in such a way as to ensure the available bandwidth is fully utilized while minimizing buffer bloat, by observing the bandwidth-delay product and applying backpressure when too much is written. Multiple streams can be sent across the same connection -- they will be multiplexed appropriately, similar to HTTP/2 stream multiplexing.
|
|
311
|
+
|
|
308
312
|
### Cloudflare Workers RPC interoperability
|
|
309
313
|
|
|
310
314
|
Cap'n Web works on any JavaScript platform. But, on Cloudflare Workers specifically, it's designed to play nicely with the [the built-in RPC system](https://blog.cloudflare.com/javascript-native-rpc/). The two have basically the same semantics, the only difference being that Workers RPC is a built-in API provided by the Workers Runtime, whereas Cap'n Web is implemented in pure JavaScript.
|
|
@@ -400,6 +404,8 @@ If anything happens to the stub that would cause all further method calls and pr
|
|
|
400
404
|
|
|
401
405
|
* Cap'n Web's pipelining can make it easy for a malicious client to enqueue a large amount of work to occur on a server. To mitigate this, we recommend implementing rate limits on expensive operations. If using Cloudflare Workers, you may also consider configuring [per-request CPU limits](https://developers.cloudflare.com/workers/wrangler/configuration/#limits) to be lower than the default 30s. Note that in stateless Workers (i.e. not Durable Objects), the system considers an entire WebSocket session to be one "request" for CPU limits purposes.
|
|
402
406
|
|
|
407
|
+
* Cap'n Web applies receiver-side resource limits before expensive message processing, including a maximum incoming message size before `JSON.parse`. If your app is exposed to untrusted peers, also configure native transport or socket payload limits where available, such as `ws`'s `maxPayload`, Bun's `maxPayloadLength`, or the runtime's built-in WebSocket cap. Cap'n Web's own check runs after `RpcTransport.receive()` has returned a complete message string, so transport-level limits are still the first line of defense against buffering very large frames.
|
|
408
|
+
|
|
403
409
|
* Cap'n Web currently does not provide any runtime type checking. When using TypeScript, keep in mind that types are checked only at compile time. A malicious client can send types you did not expect, and this could cause you application to behave in unexpected ways. For example, MongoDB uses special property names to express queries; placing attacker-provided values directly into queries can result in query injection vulnerabilities (similar to SQL injection). Of course, JSON has always had the same problem, and there exists tooling to solve it. You might consider using a runtime type-checking framework like Zod to check your inputs. In the future, we hope to explore auto-generating type-checking code based on TypeScript types.
|
|
404
410
|
|
|
405
411
|
## Setting up a session
|
|
@@ -528,6 +534,14 @@ export default {
|
|
|
528
534
|
}
|
|
529
535
|
```
|
|
530
536
|
|
|
537
|
+
#### Compatibility with Workers' built-in RPC
|
|
538
|
+
|
|
539
|
+
Cloudflare Workers has long featured [a built-in RPC system with semantics similar to Cap'n Web](https://developers.cloudflare.com/workers/runtime-apis/rpc/).
|
|
540
|
+
|
|
541
|
+
Cap'n Web is designed to be compatible with Workers RPC, meaning you can pass Cap'n Web RPC stubs over Workers RPC and vice versa. The system will automatically wrap one stub type in the other and arrange to proxy calls.
|
|
542
|
+
|
|
543
|
+
For best compatibility, make sure to set your [Workers compatibilty date](https://developers.cloudflare.com/workers/configuration/compatibility-dates/) to at least `2026-01-20`, or enable the [compatibility flag](https://developers.cloudflare.com/workers/configuration/compatibility-flags/) `rpc_params_dup_stubs`. (As of this writing, `2026-01-20` is in the future, so you will need to use the flag for now.)
|
|
544
|
+
|
|
531
545
|
### HTTP server on Node.js
|
|
532
546
|
|
|
533
547
|
A server on Node.js is a bit more involved, due to the awkward handling of WebSockets in Node's HTTP library.
|
|
@@ -618,6 +632,45 @@ Deno.serve(async (req) => {
|
|
|
618
632
|
});
|
|
619
633
|
```
|
|
620
634
|
|
|
635
|
+
### HTTP server on Bun
|
|
636
|
+
|
|
637
|
+
Bun's server-side WebSocket API uses [callback-based handlers](https://bun.sh/docs/runtime/http/websockets) instead of the standard `addEventListener` interface. Cap'n Web provides `newBunWebSocketRpcHandler()` which returns a handler object you can pass directly to `Bun.serve()`.
|
|
638
|
+
|
|
639
|
+
```ts
|
|
640
|
+
import { RpcTarget, newBunWebSocketRpcHandler, newHttpBatchRpcResponse } from "capnweb";
|
|
641
|
+
|
|
642
|
+
class MyApiImpl extends RpcTarget implements MyApi {
|
|
643
|
+
// ... define API, same as above ...
|
|
644
|
+
}
|
|
645
|
+
|
|
646
|
+
// Create a WebSocket handler that manages RPC sessions automatically.
|
|
647
|
+
// The callback is invoked once per connection to create a fresh API instance.
|
|
648
|
+
let rpcHandler = newBunWebSocketRpcHandler(() => new MyApiImpl());
|
|
649
|
+
|
|
650
|
+
Bun.serve({
|
|
651
|
+
async fetch(req, server) {
|
|
652
|
+
let url = new URL(req.url);
|
|
653
|
+
if (url.pathname === "/api") {
|
|
654
|
+
// Upgrade WebSocket requests.
|
|
655
|
+
if (req.headers.get("upgrade")?.toLowerCase() === "websocket") {
|
|
656
|
+
if (server.upgrade(req)) return;
|
|
657
|
+
return new Response("WebSocket upgrade failed", { status: 500 });
|
|
658
|
+
}
|
|
659
|
+
|
|
660
|
+
// Handle HTTP batch requests.
|
|
661
|
+
let response = await newHttpBatchRpcResponse(req, new MyApiImpl());
|
|
662
|
+
response.headers.set("Access-Control-Allow-Origin", "*");
|
|
663
|
+
return response;
|
|
664
|
+
}
|
|
665
|
+
|
|
666
|
+
return new Response("Not Found", { status: 404 });
|
|
667
|
+
},
|
|
668
|
+
|
|
669
|
+
// Pass the handler directly — no manual wiring needed.
|
|
670
|
+
websocket: rpcHandler,
|
|
671
|
+
});
|
|
672
|
+
```
|
|
673
|
+
|
|
621
674
|
### HTTP server on other runtimes
|
|
622
675
|
|
|
623
676
|
Every runtime does HTTP handling and WebSockets a little differently, although most modern runtimes use the standard `Request` and `Response` types from the Fetch API, as well as the standard `WebSocket` API. You should be able to use these two functions (exported by `capnweb`) to implement both HTTP batch and WebSocket handling on all platforms:
|
|
@@ -642,6 +695,10 @@ function newWebSocketRpcSession(
|
|
|
642
695
|
: Disposable;
|
|
643
696
|
```
|
|
644
697
|
|
|
698
|
+
### HTTP server using Hono
|
|
699
|
+
|
|
700
|
+
If your app is built on [Hono](https://hono.dev/) (on any runtime it supports), check out [`@hono/capnweb`](https://github.com/honojs/middleware/tree/main/packages/capnweb).
|
|
701
|
+
|
|
645
702
|
### MessagePort
|
|
646
703
|
|
|
647
704
|
Cap'n Web can also talk over MessagePorts. This can be used in a browser to talk to Web Workers, iframes, etc.
|
|
@@ -720,3 +777,10 @@ let stub: RemoteMainInterface = session.getRemoteMain();
|
|
|
720
777
|
```
|
|
721
778
|
|
|
722
779
|
Note that sessions are entirely symmetric: neither side is defined as the "client" nor the "server". Each side can optionally expose a "main interface" to the other. In typical scenarios with a logical client and server, the server exposes a main interface but the client does not.
|
|
780
|
+
|
|
781
|
+
By default, `send()` accepts a string, and `receive()` returns a string, with Cap'n Web handling the encoding all the way to and from strings. However, transports that want more control over the serialization can declare the property `encodingLevel` to control how much encoding Cap'n Web does before passing off the message:
|
|
782
|
+
|
|
783
|
+
* `"string"` (default): Full JSON round-trip. The transport deals in strings only. Cap'n Web handles all encoding/decoding. This is what HTTP batch and WebSocket transports use.
|
|
784
|
+
* `"jsonCompatible"`: The transport works with JavaScript value trees, but they must be JSON-compatible. Cap'n Web still encodes special types, but skips the final `JSON.stringify`. The transport is responsible for serialization (e.g. to CBOR, MessagePack).
|
|
785
|
+
* `"jsonCompatibleWithBytes"`: Like `"jsonCompatible"` except that byte arrays are left as `Uint8Array` instead of base64-encoded, avoiding the ~33% base64 size overhead and the encode/decode CPU cost. Handy for use with serializations like CBOR or MessagePack that support this efficiently.
|
|
786
|
+
* `"structuredClonable"`: Messages are structured-clonable values. Cap'n Web passes through native structured-clone types where possible, while still handling RPC-specific values such as stubs. This is useful when the transport is a `MessagePort` or similar.
|