capnweb 0.1.0 → 0.2.0

package/README.md

@@ -16,6 +16,14 @@ Cap'n Web is more expressive than almost every other RPC system, because it impl
 * Supports promise pipelining. When you start an RPC, you get back a promise. Instead of awaiting it, you can immediately use the promise in dependent RPCs, thus performing a chain of calls in a single network round trip.
 * Supports capability-based security patterns.
 
+## Installation
+
+[Cap'n Web is an npm package.](https://www.npmjs.com/package/capnweb)
+
+```
+npm i capnweb
+```
+
 ## Example
 
 A client looks like this:
@@ -138,7 +146,7 @@ let friendsPromise = authedApi.getFriendIds();
 // too, so use the magic .map() function to get them, too! Still one round
 // trip.
 let friendProfilesPromise = friendsPromise.map((id: RpcPromise<number>) => {
-  return { id, profile: api.getUserProfile(id); };
+  return { id, profile: api.getUserProfile(id) };
 });
 
 // Now await the promises. The batch is sent at this point. It's important
@@ -165,7 +173,7 @@ import { newWebSocketRpcSession } from "capnweb";
 // feature, part of the "explicit resource management" spec. Alternatively,
 // we could declare `api` with `let` or `const` and make sure to call
 // `api[Symbol.dispose]()` to dispose it and close the connection later.
-using api = newWebSocketRpcSession<PublicApi>("https://example.com/api");
+using api = newWebSocketRpcSession<PublicApi>("wss://example.com/api");
 
 // Usage is exactly the same, except we don't have to await all the promises
 // at once.
@@ -297,13 +305,30 @@ The trick here is record-replay: On the calling side, Cap'n Web will invoke your
 
 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.
 
+### Cloudflare Workers RPC interoperability
+
+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.
+
+To facilitate interoperability:
+* On Workers, the `RpcTarget` class exported by "capnweb" is just an alias of the built-in one, so you can use them interchangeably.
+* RPC stubs and promises originating from one RPC system can be passed over the other. This will automatically set up proxying.
+* You can also send Workers Service Bindings and Durable Object stubs over Cap'n Web -- again, this sets up proxying.
+
+So basically, it "just works".
+
+With that said, as of this writing, the feature set is not exactly the same between the two. We aim to fix this over time, by adding missing features to both sides until they match. In particular, as of this writing:
+* Workers RPC supports some types that Cap'n Web does not yet, like `Map`, streams, etc.
+* Workers RPC supports sending values that contain aliases and cycles. This can actually cause problems, so we actually plan to *remove* this feature from Workers RPC (with a compatibility flag, of course).
+* Workers RPC does not yet support placing an `RpcPromise` into the parameters of a request, to be replaced by its resolution.
+* Workers RPC does not yet support the magic `.map()` method.
+
 ## Resource Management and Disposal
 
 Unfortunately, garbage collection does not work well when remote resources are involved, for two reasons:
 
 1. Many JavaScript runtimes only run the garbage collector when they sense "memory pressure" -- if memory is not running low, then they figure there's no need to try to reclaim any. However, the runtime has no way to know if the other side of an RPC connection is suffering memory pressure.
 
-2. Garbage collectors need to trace the full object graph in order to detect which objects are unreachable, especially when those objects contain cyclic refereces. However, the garbage collector can only see local objects; it has no ability to trace through the remote graph to discover cycles that may cross RPC connections.
+2. Garbage collectors need to trace the full object graph in order to detect which objects are unreachable, especially when those objects contain cyclic references. However, the garbage collector can only see local objects; it has no ability to trace through the remote graph to discover cycles that may cross RPC connections.
 
 Both of these problems might be solvable with sufficient work, but the problem seems exceedingly difficult. We make no attempt to solve it in this library.
 
@@ -313,6 +338,8 @@ Instead, you may choose one of two strategies:
 
 2. Use short-lived sessions. When the session ends, all stubs are implicitly disposed. In particular, when using HTTP batch request, there's generally no need to dispose stubs. When using long-lived WebSocket sessions, however, disposal may be important.
 
+Note: We might extend Cap'n Web to use `FinalizationRegistry` to automatically dispose abandoned stubs in the future, but even if we do, it should not be relied upon, due to problems discussed above.
+
 ### How to dispose
 
 Stubs integrate with JavaScript's [explicit resource management](https://v8.dev/features/explicit-resource-management), which became widely available in mid-2025 (and has been supported via transpilers and polyfills going back a few years earlier). In short:
@@ -328,7 +355,7 @@ The basic principle is: **The caller is responsible for disposing all stubs.** T
 * Stubs passed in the params of a call remain property of the caller, and must be disposed by the caller, not by the callee.
 * Stubs returned in the result of a call have their ownership transferred from the callee to the caller, and must be disposed by the caller.
 
-In practice, though, the callee and caller do not actually share the same stubs. When stubs are passed over RPC, they are _duplicated_, and the the target object is only disposed when all duplicates of the stub are disposed. Thus, to achieve the rule that only the caller needs to dispose stubs, the RPC system implicitly disposes the callee's duplicates of all stubs when the call completes. That is:
+In practice, though, the callee and caller do not actually share the same stubs. When stubs are passed over RPC, they are _duplicated_, and the target object is only disposed when all duplicates of the stub are disposed. Thus, to achieve the rule that only the caller needs to dispose stubs, the RPC system implicitly disposes the callee's duplicates of all stubs when the call completes. That is:
 * Any stubs the callee receives in the parameters are implicitly disposed when the call completes.
 * Any stubs returned in the results are implicitly disposed some time after the call completes. (Specifically, the RPC system will dispose them once it knows there will be no more pipelined calls.)
 
@@ -355,7 +382,7 @@ Note that if you pass the same `RpcTarget` instance to RPC multiple times -- thu
 
 ### Listening for disconnect
 
-You can monitor any stub for "brokennness" with its `onRpcBroken()` method:
+You can monitor any stub for "brokenness" with its `onRpcBroken()` method:
 
 ```ts
 stub.onRpcBroken((error: any) => {
@@ -508,7 +535,7 @@ A server on Node.js is a bit more involved, due to the awkward handling of WebSo
 ```ts
 import http from "node:http";
 import { WebSocketServer } from 'ws';  // npm package
-import { RpcTarget, newWebSocketRpcSession, nodeHttpBatchRpcResponse } from "capnpweb";
+import { RpcTarget, newWebSocketRpcSession, nodeHttpBatchRpcResponse } from "capnweb";
 
 class MyApiImpl extends RpcTarget implements MyApi {
   // ... define API, same as above ...
@@ -524,7 +551,7 @@ httpServer = http.createServer(async (request, response) => {
   // Accept Cap'n Web requests at `/api`.
   if (request.url === "/api") {
     try {
-      nodeHttpBatchRpcResponse(request, response, new MyApiImpl(), {
+      await nodeHttpBatchRpcResponse(request, response, new MyApiImpl(), {
         // If you are accepting WebSockets, then you might as well accept cross-origin HTTP, since
         // WebSockets always permit cross-origin request anyway. But, see security considerations
         // for further discussion.
@@ -555,6 +582,42 @@ wsServer.on('connection', (ws) => {
 httpServer.listen(8080);
 ```
 
+### HTTP server on Deno
+```ts
+import {
+  newHttpBatchRpcResponse,
+  newWebSocketRpcSession,
+  RpcTarget,
+} from "npm:capnweb";
+
+// This is the server implementation.
+class MyApiImpl extends RpcTarget implements MyApi {
+  // ... define API, same as above ...
+}
+
+Deno.serve(async (req) => {
+  const url = new URL(req.url);
+  if (url.pathname === "/api") {
+    if (req.headers.get("upgrade") === "websocket") {
+      const { socket, response } = Deno.upgradeWebSocket(req);
+      socket.addEventListener("open", () => {
+        newWebSocketRpcSession(socket, new MyApiImpl());
+      });
+      return response;
+    } else {
+      const response = await newHttpBatchRpcResponse(req, new MyApiImpl());
+      // If you are accepting WebSockets, then you might as well accept cross-origin HTTP, since
+      // WebSockets always permit cross-origin request anyway. But, see security considerations
+      // for further discussion.
+      response.headers.set("Access-Control-Allow-Origin", "*");
+      return response;
+    }
+  }
+
+  return new Response("Not Found", { status: 404 });
+});
+```
+
 ### HTTP server on other runtimes
 
 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:
@@ -645,7 +708,7 @@ You can then set up a connection over it:
 let transport: RpcTransport = new MyTransport();
 
 // Create the main interface we will expose to the other end.
-let localMain: RpcTarget = new MyMainInterface():
+let localMain: RpcTarget = new MyMainInterface();
 
 // Start the session.
 let session = new RpcSession<RemoteMainInterface>(transport, localMain);