@statewalker/webrun-streams-webrtc 0.1.5 → 0.3.0

package/README.md

@@ -12,7 +12,7 @@ between the two peers with no server in the data path.
 ## Why it exists
 
 WebRTC can open as many data channels as needed, so concurrency comes from the
-transport and this adapter does not use `emulateMux`. What an
+transport and this adapter needs no multiplexer over it. What an
 `RTCDataChannel` lacks is what request/response needs:
 
 1. **No half-close.** A channel is open or closed. There is no way to say "I
@@ -44,6 +44,8 @@ below.
 | `serve({ pc }, handler)` | `Serve<WebRtcParams>`. Listens for `datachannel` events on `pc` and runs `handler` on each channel. Resolves to an idempotent teardown that stops accepting new channels; calls in flight continue. |
 | `duplexOverDataChannel(dc, input)` | The primitive under both: runs one call over one data channel. Sends `input` framed, and returns an `AsyncGenerator<Uint8Array>` of the peer's bytes. |
 | `WebRtcParams` | `{ pc: RTCPeerConnection }`. |
+| `webrtcPortMux(options)` | Native MessagePorts: a `webrun-rpc` `PortMux` (by shape) whose every port is its own data channel (labelled `webrun-port/…`), for `overPorts`. `options`: `pc`, `codec` (a value codec: `{ encode: serialize, decode: deserialize }` from `webrun-msgpack`), `onPort(port)` (to accept ports), `maxMessageSize`, `maxFrameBytes`. See "MessagePorts over WebRTC" below. |
+| `DEFAULT_PORT_MAX_FRAME_BYTES`, `DEFAULT_PORT_MAX_MESSAGE_SIZE`, `PORT_DRAIN_LOW_WATER`, `PORT_LABEL_PREFIX` | 16 KiB, 16 KiB − 256, 256 KiB, `"webrun-port/"`. |
 
 ## Examples
 
@@ -121,11 +123,43 @@ for await (const chunk of duplexOverDataChannel(dc, request())) {
 | 1 byte | rest of the message       |
 +--------+---------------------------+
 
-DATA  0x00  body bytes, at most 16 KiB - 1 per message
-END   0x01  this side has finished sending (half-close)
-ERROR 0x02  JSON of serializeError(err): message, stack, custom fields
+DATA   0x00  body bytes, at most 16 KiB - 1 per message
+END    0x01  this side has finished sending (half-close)
+ERROR  0x02  JSON of serializeError(err): message, stack, custom fields
+CREDIT 0x03  big-endian u32: payload bytes the receiver's consumer pulled
 ```
 
+### Flow control
+
+Two limits keep memory bounded whatever the speed of either side:
+
+- **Send buffer.** Before each `DATA` message the sender waits while the
+  channel holds more than `HIGH_WATER_MARK` (1 MiB) unsent
+  (`bufferedAmount`), until `bufferedamountlow` fires at `LOW_WATER_MARK`
+  (256 KiB).
+- **Receive window.** A sender may have at most `RECEIVE_WINDOW` (4 MiB) of
+  payload outstanding that the receiving consumer has not pulled. The receiver
+  returns credit with `CREDIT` frames as its consumer pulls, half a window at a
+  time. On the responder, the next chunk is pulled only once the handler took
+  the previous one, so a slow handler stalls the caller.
+
+Both ends must speak `CREDIT`: a sender facing a peer that never returns
+credit stops after the first window.
+
+Each side keeps listening for `CREDIT` until both directions are done, so a
+reply larger than the window, sent after the input ended, still flows. When
+the responder's handler finishes (or throws) without reading all its input,
+the rest of the caller's upload is read and dropped, so the caller's upload
+finishes rather than waiting for credit. A caller that cancels, or gets an
+error, stops its own upload and closes the channel at once.
+
+A finished call's channel is closed by the caller, once it has the
+responder's `END` or `ERROR`: a responder that closed right after sending them
+could lose them in flight. Each side also holds the frames that arrive before
+its stream starts listening, so a responder that answers at once (a handler
+that throws, a reply with no input to wait for) is not faster than the
+caller's listener.
+
 ```
 caller                          responder
   | createDataChannel("webrun/…")  |  datachannel event -> handler(input)
@@ -139,6 +173,42 @@ is at most 16 KiB, a size that every browser's SCTP implementation accepts. The
 channel's `binaryType` is set to `"arraybuffer"`; text messages and empty
 messages are ignored. The channel is closed once both directions have ended.
 
+### MessagePorts over WebRTC, and the port stack on them
+
+`connect` / `serve` above run their own framing and credit window per data
+channel, so a consumer that stops reading lets its producer get up to 4 MiB
+ahead (L6). `webrtcPortMux` gives `webrun-rpc`'s port stack a data channel per
+port instead, and its stream tier keeps a producer within one confirmed chunk:
+
+```ts
+import { deserialize, serialize } from "@statewalker/webrun-msgpack";
+import { connect, overPorts, serve } from "@statewalker/webrun-rpc";
+import { webrtcPortMux } from "@statewalker/webrun-streams-webrtc";
+
+const codec = { encode: serialize, decode: deserialize };
+await serve({ mux: overPorts((onPort) => webrtcPortMux({ pc, codec, onPort })) }, handler);
+const { call } = await connect({ mux: overPorts(() => webrtcPortMux({ pc: other, codec })) });
+```
+
+Ports are ordered, reliable channels labelled `webrun-port/…`; a mux ignores
+inbound channels without that label, and this package's `serve()` ignores
+channels with it, so ports share a connection with `connect` / `serve` and with
+anyone else's channels. On one connection, a mux without `onPort` (a caller's)
+leaves inbound ports to the serving mux, so both directions can call; of
+several serving muxes, the first takes each port. Each message is one
+data channel message, so `maxMessageSize` defaults to 16 KiB − 256 (Firefox to
+Chrome cuts off at 16 KiB; the port stack's framing needs the margin), and a
+message past `maxFrameBytes` fails the port with a `RangeError` instead of
+being dropped. Each port carries `closeSignal`, aborted when its channel closes
+or errs, the connection becomes `failed` or `closed`, or the port is closed
+here. A refused port (`onPort` returning `false`) is closed, so the opener's
+call fails. Messages that arrive before a port's first listener are held for
+it, delivered after that tick to every listener added by then. A connection
+that has failed already makes `openPort` reject, as does an aborted `signal`.
+`whenDrained()` waits on `bufferedamountlow` (256 KiB). The suite runs a
+second conformance pair over these ports (`tests/port-mux.test.ts`), with L6 at
+a one-chunk bound.
+
 ### How cancellation reaches the handler
 
 `END` means "I am done sending", and the peer answers it by carrying on, so it
@@ -180,14 +250,13 @@ is caught, so it does not become an unhandled rejection.
 
 ### Constraints
 
-- **No flow control in the adapter.** Outbound messages go to `dc.send` as
-  fast as `input` yields; `bufferedAmount` is not checked, and the inbound
-  queue is not bounded. Very large or fast bodies rely on the browser's send
-  buffer, which closes the channel when it overflows.
-- Conformance runs in Chromium through Playwright: `pnpm run test:browser`.
+- Conformance and the flow-control tests (100 MiB under the high-water mark;
+  a sleeping reader stalls the sender within the window) run in Chromium
+  through Playwright: `pnpm run test:browser`, also in CI.
   Under `pnpm test` (Node) the suite is registered as skipped, because Node
-  has no `RTCPeerConnection`. L6's small window does not apply here (there is
-  no `emulateMux`), so L6 is an integrity check.
+  has no `RTCPeerConnection`. L6 asserts the per-channel window: a consumer
+  that stops reading lets the producer get at most `RECEIVE_WINDOW` (4 MiB)
+  ahead, measured at exactly that.
 
 ### Dependencies
 

package/dist/connect-serve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connect-serve.d.ts","sourceRoot":"","sources":["../src/connect-serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAU,KAAK,EAAE,MAAM,6BAA6B,CAAC;AAG1E,MAAM,WAAW,YAAY;IAC3B,wGAAwG;IACxG,EAAE,EAAE,iBAAiB,CAAC;CACvB;AAED;;;;GAIG;AACH,eAAO,MAAM,OAAO,EAAE,OAAO,CAAC,YAAY,CAyCzC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,YAAY,CA4BrC,CAAC"}
+{"version":3,"file":"connect-serve.d.ts","sourceRoot":"","sources":["../src/connect-serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAU,KAAK,EAAE,MAAM,6BAA6B,CAAC;AAI1E,MAAM,WAAW,YAAY;IAC3B,wGAAwG;IACxG,EAAE,EAAE,iBAAiB,CAAC;CACvB;AAED;;;;GAIG;AACH,eAAO,MAAM,OAAO,EAAE,OAAO,CAAC,YAAY,CA0CzC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,YAAY,CA0CrC,CAAC"}

package/dist/duplex-over-data-channel.d.ts

@@ -1,3 +1,22 @@
+/**
+ * Send-side backpressure: a sender waits while the DataChannel holds more than this many bytes
+ * unsent (`bufferedAmount`), until it drains to {@link LOW_WATER_MARK} (`bufferedamountlow`).
+ * Without it a fast producer fills the browser's send queue (Chrome fails `send` past 16 MiB).
+ */
+export declare const HIGH_WATER_MARK: number;
+export declare const LOW_WATER_MARK: number;
+/**
+ * Receive-side backpressure: a sender may have at most this many payload bytes outstanding that
+ * the receiving consumer has not yet pulled. The receiver returns credit (`CREDIT` frames) as its
+ * consumer pulls, half a window at a time. A DataChannel delivers every message as it arrives,
+ * whether or not anyone reads, so without credit a slow reader's queue grows without bound. The
+ * window is larger than the send buffer's high-water mark so a long round trip does not throttle a
+ * fast link: the buffer limit is what bounds the sender's memory.
+ */
+export declare const RECEIVE_WINDOW: number;
+export declare function markAnswering(dc: RTCDataChannel): void;
+/** starts holding a channel's events until {@link duplexOverDataChannel} takes them */
+export declare function holdEvents(dc: RTCDataChannel): void;
 /**
  * Drive one `Duplex` over one `RTCDataChannel`. The DataChannel hosts a tiny
  * in-band framing protocol:
@@ -6,7 +25,9 @@
  *
  * Types are `DATA` (0x00, body bytes), `END` (0x01, signals half-close — the
  * sender is done emitting; the channel stays open for the other direction),
- * and `ERROR` (0x02, followed by a serialised `Error`).
+ * `ERROR` (0x02, followed by a serialised `Error`) and `CREDIT` (0x03, a
+ * big-endian u32: payload bytes the receiver's consumer has pulled, which the
+ * sender may now send again; see {@link RECEIVE_WINDOW}).
  *
  * `RTCDataChannel` has no native half-close, so `END` is emitted by the
  * sender once its input iterator exhausts; the channel is only physically

package/dist/duplex-over-data-channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"duplex-over-data-channel.d.ts","sourceRoot":"","sources":["../src/duplex-over-data-channel.ts"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,cAAc,EAClB,KAAK,EAAE,aAAa,CAAC,UAAU,CAAC,GAC/B,cAAc,CAAC,UAAU,CAAC,CAE5B"}
+{"version":3,"file":"duplex-over-data-channel.d.ts","sourceRoot":"","sources":["../src/duplex-over-data-channel.ts"],"names":[],"mappings":"AAcA;;;;GAIG;AACH,eAAO,MAAM,eAAe,QAAc,CAAC;AAC3C,eAAO,MAAM,cAAc,QAAa,CAAC;AACzC;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,QAAkB,CAAC;AAoB9C,wBAAgB,aAAa,CAAC,EAAE,EAAE,cAAc,GAAG,IAAI,CAEtD;AAED,uFAAuF;AACvF,wBAAgB,UAAU,CAAC,EAAE,EAAE,cAAc,GAAG,IAAI,CAUnD;AAWD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,cAAc,EAClB,KAAK,EAAE,aAAa,CAAC,UAAU,CAAC,GAC/B,cAAc,CAAC,UAAU,CAAC,CAE5B"}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { connect, serve, type WebRtcParams } from "./connect-serve.js";
 export { duplexOverDataChannel } from "./duplex-over-data-channel.js";
+export { type DataChannelPort, DEFAULT_PORT_MAX_FRAME_BYTES, DEFAULT_PORT_MAX_MESSAGE_SIZE, PORT_DRAIN_LOW_WATER, PORT_LABEL_PREFIX, type ValueCodec, type WebRtcPortMux, type WebRtcPortMuxOptions, webrtcPortMux, } from "./port-mux.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvE,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvE,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EACL,KAAK,eAAe,EACpB,4BAA4B,EAC5B,6BAA6B,EAC7B,oBAAoB,EACpB,iBAAiB,EACjB,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,aAAa,GACd,MAAM,eAAe,CAAC"}