capnweb 0.0.0-952a541 → 0.0.0-9751a4e
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 +67 -2
- package/dist/index-bun.cjs +475 -109
- package/dist/index-bun.cjs.map +1 -1
- package/dist/index-bun.d.cts +158 -19
- package/dist/index-bun.d.ts +158 -19
- package/dist/index-bun.js +473 -110
- package/dist/index-bun.js.map +1 -1
- package/dist/index-workers.cjs +475 -109
- package/dist/index-workers.cjs.map +1 -1
- package/dist/index-workers.d.cts +154 -18
- package/dist/index-workers.d.ts +154 -18
- package/dist/index-workers.js +473 -110
- package/dist/index-workers.js.map +1 -1
- package/dist/index.cjs +475 -109
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +154 -18
- package/dist/index.d.ts +154 -18
- package/dist/index.js +473 -110
- package/dist/index.js.map +1 -1
- package/package.json +6 -5
package/README.md
CHANGED
|
@@ -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
204
|
* `Blob`
|
|
205
205
|
* `ReadableStream` and `WritableStream`, with automatic flow control.
|
|
206
|
+
* `URL`
|
|
206
207
|
* `Headers`, `Request`, and `Response` from the Fetch API.
|
|
207
208
|
|
|
208
209
|
The following types are not supported as of this writing, but may be added in the future:
|
|
209
210
|
* `Map` and `Set`
|
|
210
|
-
* `ArrayBuffer` and typed arrays other than `Uint8Array`
|
|
211
211
|
* `RegExp`
|
|
212
212
|
|
|
213
213
|
The following are intentionally NOT supported:
|
|
@@ -267,6 +267,28 @@ let profile = await api.getUserProfile(user.id);
|
|
|
267
267
|
|
|
268
268
|
Whenever an `RpcPromise` is passed in the parameters to an RPC, or returned as part of the result, the promise will be replaced with its resolution before delivery to the receiving application. So, you can use an `RpcPromise<T>` anywhere where a `T` is required!
|
|
269
269
|
|
|
270
|
+
#### Constructing `RpcPromise` from a `Promise`
|
|
271
|
+
|
|
272
|
+
You can construct an `RpcPromise<T>` directly from a regular `Promise<T>`, allowing you to perform promise pipelining on a regular local promise. Pipelined calls will wait until the inner promise resolves, then will be delivered, in-order, to the resolution. This is useful when you plan to obtain some stub in the future, but you want to allow code to start queuing calls on it immediately.
|
|
273
|
+
|
|
274
|
+
Wrapping a `Promise<T>` in this way is semantically identical to creating a local-loopback RPC and then invoking it. That is:
|
|
275
|
+
|
|
276
|
+
```ts
|
|
277
|
+
// this...
|
|
278
|
+
let rpcPromise = new RpcPromise(myPromise);
|
|
279
|
+
|
|
280
|
+
// is semantically the same as this...
|
|
281
|
+
let rpcFunc = new RpcStub(() => myPromise);
|
|
282
|
+
let rpcPromise = rpcFunc();
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
In other words, this means:
|
|
286
|
+
* The result of the promise must be serializable.
|
|
287
|
+
* If the promise resolution contains `RpcTarget`s or `Function`s, the `RpcPromise`'s resolution will replace them with stubs.
|
|
288
|
+
* Ownership of any stubs in the Promise result is transferred away. If you want to keep your own copies, you need to `dup()` them.
|
|
289
|
+
* If the promise rejects, the rejection propagates to all pipelined calls.
|
|
290
|
+
* etc.
|
|
291
|
+
|
|
270
292
|
### The magic `map()` method
|
|
271
293
|
|
|
272
294
|
Every RPC promise has a special method `.map()` which can be used to remotely transform a value, without pulling it back locally. Here's an example:
|
|
@@ -379,6 +401,40 @@ Sometimes you need to pass a stub somewhere where it will be disposed, but also
|
|
|
379
401
|
|
|
380
402
|
Hint: You can call `.dup()` on a property of a stub or promise, in order to create a stub backed by that property. This is particularly useful when you know in advance that the property is going to resolve to a stub: calling `.dup()` on it gives you a stub you can start using immediately, that otherwise behaves exactly the same as the eventual stub would if you awaited it.
|
|
381
403
|
|
|
404
|
+
#### Holding on to a callback past the call that delivered it
|
|
405
|
+
|
|
406
|
+
A common bidirectional-calling pattern is for the client to pass a callback to the server, which the server then invokes later (for example from a timer, an event handler, or a subsequent RPC). Because the callback parameter is a stub, and stubs in params are implicitly disposed when the call returns, the server must duplicate the stub with `.dup()` if it wants to invoke the callback after the call completes:
|
|
407
|
+
|
|
408
|
+
```ts
|
|
409
|
+
import { type RpcStub, RpcTarget } from 'capnweb';
|
|
410
|
+
|
|
411
|
+
// A callback the client passes in: a stub wrapping a function.
|
|
412
|
+
type Listener = RpcStub<(msg: string) => void>;
|
|
413
|
+
|
|
414
|
+
class Api extends RpcTarget {
|
|
415
|
+
#listener?: Listener;
|
|
416
|
+
|
|
417
|
+
// Stubs passed as params are disposed when the call returns, so `.dup()`
|
|
418
|
+
// to keep a reference that outlives registerListener().
|
|
419
|
+
registerListener(listener: Listener) {
|
|
420
|
+
this.#listener?.[Symbol.dispose](); // release any previous listener
|
|
421
|
+
this.#listener = listener.dup();
|
|
422
|
+
}
|
|
423
|
+
|
|
424
|
+
// A *later* call can invoke the retained callback -- still valid thanks to .dup().
|
|
425
|
+
notify(msg: string) {
|
|
426
|
+
this.#listener?.(msg);
|
|
427
|
+
}
|
|
428
|
+
|
|
429
|
+
// Dispose our duplicate when done so the client-side stub can be freed.
|
|
430
|
+
[Symbol.dispose]() {
|
|
431
|
+
this.#listener?.[Symbol.dispose]();
|
|
432
|
+
}
|
|
433
|
+
}
|
|
434
|
+
```
|
|
435
|
+
|
|
436
|
+
The same rule applies in the other direction: if the server returns a stub to the client and the client wants to keep using it after disposing the result, the client should `.dup()` the stub before the result is disposed.
|
|
437
|
+
|
|
382
438
|
### Listening for disposal
|
|
383
439
|
|
|
384
440
|
An `RpcTarget` may declare a `Symbol.dispose` method. If it does, the RPC system will automatically invoke it when a stub pointing at it (and all its duplicates) has been disposed.
|
|
@@ -405,6 +461,8 @@ If anything happens to the stub that would cause all further method calls and pr
|
|
|
405
461
|
|
|
406
462
|
* 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.
|
|
407
463
|
|
|
464
|
+
* 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.
|
|
465
|
+
|
|
408
466
|
* 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.
|
|
409
467
|
|
|
410
468
|
## Setting up a session
|
|
@@ -776,3 +834,10 @@ let stub: RemoteMainInterface = session.getRemoteMain();
|
|
|
776
834
|
```
|
|
777
835
|
|
|
778
836
|
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.
|
|
837
|
+
|
|
838
|
+
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:
|
|
839
|
+
|
|
840
|
+
* `"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.
|
|
841
|
+
* `"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).
|
|
842
|
+
* `"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.
|
|
843
|
+
* `"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.
|