@statewalker/webrun-streams-webrtc 0.1.6 → 0.4.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,46 @@ 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. The receiver enforces the window too: a
+peer that sends more than the window plus the credit it was returned fails the
+call. The receiver drops what it queued, closes the channel, and its side of
+the call throws (on the responder, the handler's input throws).
+
+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,14 +176,55 @@ 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
 cannot express "stop". When the caller leaves early (`.return()` on the call's
-generator, or an error), `duplexOverDataChannel` waits for its own outbound
-pump to settle and then closes the channel. On the responder, the channel's
-`close` event ends the inbound side with `TransportClosedError`, which closes
-the handler's input and runs the handler's `finally`.
+generator, or an error), `duplexOverDataChannel` closes the channel and then
+waits for its own outbound pump to settle. On the responder, the channel's
+`close` event ends the inbound side with `TransportClosedError`; a caller whose
+input throws sends `ERROR` instead, which ends it with that error. Either way
+the handler's input ends with the error (its next read throws it, so a handler
+never takes a truncated upload for a complete one) before the responder waits
+for its own outbound pump, which may be waiting for the handler's next output.
+The handler's `finally` then runs, whether it was reading its input or
+producing output.
 
 On a normal finish the outbound pump is not awaited. The responder feeds the
 handler's input from this generator and closes that input only when the
@@ -173,6 +251,7 @@ SDP, must be opened before `serve` is registered or on a different connection.
 | Channel closes before it opens | `DataChannel closed before open` |
 | Channel error before it opens | `DataChannel error: <message or "unknown">` |
 | Channel closes before the peer sent `END` | `TransportClosedError` (`transport closed`) |
+| The peer sends past the receive window without credit | `webrun-streams-webrtc: the peer sent past the receive window (4194304 bytes) without credit` |
 | Handler throws | The caller's `for await` throws the deserialised error, with `message`, `stack` and custom fields |
 
 On the responder, a channel task that fails (usually a caller that cancelled)
@@ -180,14 +259,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;AAS1E,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,CA+CrC,CAAC"}

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

@@ -1,3 +1,25 @@
+/**
+ * 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.
+ *
+ * The receiver enforces it: a peer that sends more than the window plus the credit returned fails
+ * the call (the queued payload is dropped, the stream throws, the channel is closed).
+ */
+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,11 +28,24 @@
  *
  * 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
  * closed once both sides have ended.
  */
 export declare function duplexOverDataChannel(dc: RTCDataChannel, input: AsyncIterable<Uint8Array>): AsyncGenerator<Uint8Array>;
+export interface RunStreamHooks {
+    /**
+     * Called once when the inbound side fails (the peer's `ERROR`, the channel closing, a peer
+     * past the receive window), before the stream waits for its outbound pump to settle. A
+     * responder ends its handler's input here: the pump may be waiting for the handler's next
+     * output while the handler waits for its next input.
+     */
+    onInboundFailed?(err: Error): void;
+}
+/** {@link duplexOverDataChannel}, with hooks for `serve` */
+export declare function runStream(dc: RTCDataChannel, input: AsyncIterable<Uint8Array> | Iterable<Uint8Array>, hooks?: RunStreamHooks): AsyncGenerator<Uint8Array>;
 //# sourceMappingURL=duplex-over-data-channel.d.ts.map

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;;;;;;;;;;GAUG;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;AAED,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,eAAe,CAAC,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,CAAC;CACpC;AAED,4DAA4D;AAC5D,wBAAuB,SAAS,CAC9B,EAAE,EAAE,cAAc,EAClB,KAAK,EAAE,aAAa,CAAC,UAAU,CAAC,GAAG,QAAQ,CAAC,UAAU,CAAC,EACvD,KAAK,GAAE,cAAmB,GACzB,cAAc,CAAC,UAAU,CAAC,CA4O5B"}

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"}