@statewalker/webrun-rpc 0.8.0 → 0.10.0

package/README.md

@@ -78,7 +78,7 @@ Port multiplexing:
 | `PortMux` | `openPort(meta?, { signal }?)`, `close(reason?)`, `ports?()`, `maxMessageSize`. |
 | `portBufferedAmount(port)`, `whenPortReady(port, below?)` | A windowed port's queued bytes, and a promise for room. See below. |
 | `PortInfo`, `OpenPortOptions` | What `ports()` reports per port (`id`, `meta`, `openedAt`, `lastActivity`); `openPort`'s options. |
-| `PortCodec`, `PortEnvelope` | The wire seam: `post(port, envelope, transfer?)`, `read(event)`, and optionally `encode(envelope)` / `decode(data)` for byte codecs (exact window sizes, frames). |
+| `PortCodec`, `PortEnvelope` | The wire seam: `post(port, envelope, transfer?)`, `read(event)`, and optionally `encode(envelope)` / `decode(data)` for byte codecs (exact window sizes, frames) and `halfClose: true` for a codec that reads `end`. |
 | `structuredCodec` | Envelopes passed through unencoded. |
 | `DEFAULT_MAX_PORTS` | `1024`. |
 | `PORT_TRANSFER` | `"webrun-rpc:port-transfer"`, the `type` of the message that carries a port. |
@@ -344,6 +344,44 @@ each end counts bytes but holds nothing back, so a port to an older peer, or ove
 keeps running without flow control, as it always did; `ports()` reports `window` only once it is
 in force. A peer's `window` that is not a positive integer is ignored.
 
+**A windowed port agrees capabilities in its handshake.** A windowed `open` also lists
+`caps: ["pipeline", "end"]` (`end` only over a codec that declares it, below), what this mux
+speaks on the port, and the responder's ack answers with the
+subset both speak, only to an opener that listed some: an older peer never receives a `caps` it
+could misread. There is no option to offer fewer. `duplexOverPort` reads the agreement (see "Flow
+control is one chunk, or the window where both ends pipeline" below); nothing else changes
+meaning. The responder still holds its own sends back only once the opener has answered its ack,
+as above: a responder over a codec that drops credit envelopes would otherwise wedge its own port
+after one window.
+
+**Where `end` is agreed, each direction of a port can end on its own.** An `end` envelope leaves
+behind everything already posted on that port: it is a size-0 item in the port's window queue, so
+it needs no credit, and with `frameSize` it takes its turn in the port's queue behind the frames of
+the last message. So the peer has every byte before it sees the end, even of a last message larger
+than the window. Anything posted on that side afterwards is dropped. A port closed while its `end`
+still waits in the queue sends its `close` alone: an abandoned port never looks finished. The other
+direction keeps sending, and both keep returning credit, until it ends too. Once both directions have ended, each
+end frees the id on its own, with no `close` on the wire, and the port's close signal aborts with
+`webrun-rpc: the port ended in both directions`. `duplexOverPort` sends it when a stream ends
+normally (see "A stream that ends normally ends its port" below); no exported function sends it
+directly. An `end` from a peer where it was not agreed (no window, or not in the handshake) is a
+protocol violation: the port closes, with `close` reason `"protocol"`, and its close signal aborts
+with `webrun-rpc: the peer ended a port where end was not agreed`. So is a `message` or `frame`
+from a peer after its own `end` (`webrun-rpc: the peer sent on a port after its end`): an honest
+sender drops whatever it posts after ending, and delivering it would hand the consumer data after
+it was told its input was over.
+
+**A codec must declare that it reads `end`, or `end` is never offered.** `PortCodec.halfClose:
+true` says the codec's `read` (and `decode`) accept the `end` envelope; `structuredCodec` and
+`msgpackCodec` set it. A mux over a codec without it offers only `pipeline` and agrees `end` with
+nobody, so its ports close. The flag exists because the failure it prevents is silent: a codec
+whose `read` accepts a fixed list of envelope types, without `end`, would let both muxes agree
+`end` and then lose it on the way in. The sender frees the id; the receiver never sees the end,
+and the port stays in its `ports()` after a normal finish until the mux closes, with no error,
+until a full table refuses new ports with `maxPorts (<n>) reached`. A codec spread from a
+built-in, `{ ...structuredCodec, read: myRead }`, inherits `halfClose: true`: `myRead` must then
+accept `end`, or the codec must leave the flag out.
+
 **Closing does not wait for credit.** A port closed with messages still queued sends them at once,
 then its close, regardless of the window: a peer that stopped returning credit (a listener that
 never settles) must still learn the port is closed, and nothing is kept for a port nobody holds.
@@ -415,18 +453,20 @@ the consumer that filled it (`"?"` counts ports without a kind). A duplicate `op
 peer is ignored rather than replacing a live port, and a local `openPort` skips ids the peer
 already claimed with the wrong parity.
 
-`PortEnvelope` is `{ type: "open", id, meta?, window?, exact? }`, `{ type: "message", id, payload }`,
-`{ type: "close", id, reason? }`, with a window `{ type: "credit", id, bytes, exact? }`, with
+`PortEnvelope` is `{ type: "open", id, meta?, window?, exact?, caps? }`,
+`{ type: "message", id, payload }`, `{ type: "close", id, reason? }`, with a window
+`{ type: "credit", id, bytes, exact?, caps? }` and, where agreed, `{ type: "end", id }`, with
 `frameSize` `{ type: "frame", id, data, last? }`, and with `keepalive` `{ type: "ping", id }` /
 `{ type: "pong", id }` (on `Number.MAX_SAFE_INTEGER`). The codecs' `read` accept only objects with a non-negative integer `id`
-and one of those seven types, so other traffic on a shared port is
+and one of those eight types, so other traffic on a shared port is
 ignored.
 `structuredCodec` passes envelopes through unencoded, so `ArrayBuffer`s move zero-copy through the
 transfer list; it omits an empty transfer list because some implementations reject one.
 
 ### A port lives until its transport or its user lets go
 
-A port leaves the table only when one side closes it or the mux closes. Nothing else frees it, and
+A port leaves the table only when one side closes it, both directions end (`end`, above) or the mux
+closes. Nothing else frees it, and
 a full table refuses every new port. So both lifetimes are wired in explicitly:
 
 - **The transport.** A `MessagePort`, a terminated worker or a dead libp2p stream gives no close
@@ -548,7 +588,7 @@ caller declines inbound ports. Whichever side called the factory owns the mux an
 that is built and dropped costs the peer nothing. Every port it opens carries `meta`
 `{ kind: "stream" }`, so a peer running other things over the same mux can tell stream ports apart.
 
-### Flow control is a window of one chunk
+### Flow control is one chunk, or the window where both ends pipeline
 
 `duplexOverPort` sends each direction as one `callPort` per chunk on its own channel (`"in"` for
 the caller's input, `"out"` for the handler's output). The reply to a chunk call is the
@@ -564,8 +604,64 @@ A peer that sends a second chunk before the first is confirmed gets `response:er
 closed. Other ports on the mux are untouched.
 
 The cost: single-stream throughput is `chunk ÷ RTT`. In-process that is negligible; over a 50 ms
-round trip, a 10 MiB body in 12 KiB chunks is 854 sequential round trips, about 43 s. Concurrency
-comes from running many streams, one port each, not from pipelining one.
+round trip, a 10 MiB body in 12 KiB chunks is 854 sequential round trips, about 43 s.
+
+**On a port whose window both ends speak, chunks are pipelined.** Once the port's handshake has
+agreed `pipeline` (see "A windowed port agrees capabilities in its handshake" above) and the
+window holds this end's sends, each chunk leaves as a plain message,
+`{ type: "webrun-rpc:chunk", channelName, chunk }`, with no confirmation of its own; the sender
+waits only for `whenPortReady`. The receiver's listener settles once its consumer pulls past the
+chunk, so the window's credit is the confirmation, and a stalled reader holds about one window:
+`tests/duplex-pipelining-stall.test.ts` measures the producer stopping about one window ahead,
+and the memory held staying within twice the window above an unwindowed link. Nor does a stalled
+stream slow the others on its link: `pnpm bench` (kept out of `pnpm test`, so that a loaded
+machine cannot fail the suite) measures ping p99 beside a stalled reader with a 256 KiB window
+and with none, in one run, median of 3 each, and fails when the window's p99 is above twice the
+other's plus 1 ms.
+
+Until the agreement is known (the opener learns it from the ack; the responder's own sends wait
+for the opener's answer) chunks go as confirmed calls, so the handshake adds no round trip to the
+first chunk. Chunks, results and errors are the same either way, an error still in the last
+chunk. Over `overPipe` without `window`, over `transferPortMux` and with a peer that answers no
+capabilities, every chunk is a confirmed call.
+
+**A chunk travels as its own bytes.** Structured clone carries a typed array's whole
+`ArrayBuffer`, while the window counts only the view. A producer yielding `subarray`s of one large
+buffer (`toChunks` does, and so do Node `Buffer` slices) would otherwise ship, and a stalled
+reader hold, the whole buffer once per chunk: 4 KiB views of a 4 MiB buffer behind a 256 KiB
+window held about 248 MiB, which looks like a leak and is not one. So every chunk is sent as a
+plain `Uint8Array` that owns its buffer, in both modes: a view on a larger buffer, a Node
+`Buffer`, another typed array or a `DataView` is copied, and an `ArrayBuffer` is wrapped. The
+copy is made with the `Uint8Array` constructor, because a `Buffer`'s `slice()` is another view on
+the same memory. A plain `Uint8Array` that covers its whole buffer is sent as it is. Anything else
+ends the stream with the producer's own error, which reaches the peer like a handler's:
+`webrun-rpc: a stream chunk must be bytes (a typed array, a DataView or an ArrayBuffer), got
+<type>`.
+
+The receiver copies again, confirmed or pipelined, whatever the peer sent: what is held is what is
+counted. Over `msgpackCodec` that is one copy of every received chunk, because its decoder returns
+views of the frame (and over a Node transport, views of a frame `Buffer`). The copy stays: without
+it, a chunk would keep its whole frame alive, and a hostile frame of one byte of chunk beside 1 MiB
+of padding would hold that 1 MiB while counting 33 bytes.
+
+A pipelining peer is held to these rules, each failing that stream and closing its port, holding
+nothing more:
+
+- a pipelined chunk where `pipeline` was not agreed:
+  `webrun-rpc: peer sent a pipelined chunk where pipelining was not agreed`;
+- one that arrives while the receiver already holds more than the window unconsumed (each chunk
+  counted as its bytes plus 32, less than either codec's window counts for it, so an honest sender
+  never trips it): `webrun-rpc: peer sent past the window (<n> bytes) without waiting for credit;
+  the stream port is closed`;
+- a confirmed chunk while pipelined ones are held, or a pipelined one while a confirmed one is:
+  `webrun-rpc: peer mixed confirmed and pipelined chunks; the stream port is closed` (an honest
+  sender switches to pipelining once, after its last confirmed chunk was answered);
+- a pipelined chunk whose value is not a typed array or `DataView`:
+  `webrun-rpc: peer sent a pipelined chunk whose value is not bytes`.
+
+So the receiver holds at most the window plus one chunk of a stream's bytes. A hostile peer can
+still make it receive a large buffer per message, briefly: the copy on receipt frees it once that
+message is handled, so it costs time, not memory held.
 
 **One stream per port.** Nothing enforces it: invoking the same `duplexOverPort` result twice on
 one port makes both invocations cross-talk on the same two channel names. Open a port per call.
@@ -589,8 +685,58 @@ direction resets it, and elapsing aborts the stream with `webrun-rpc: stream idl
 Unset, zero or non-finite means none.
 
 Know what you buy if you set it. The clock resets only when a chunk call returns, and that reply
-is withheld until the consumer has pulled past the value. The clock cannot tell "slow" from "dead":
-a consumer slower than the timeout **is** failed.
+is withheld until the consumer has pulled past the value (a pipelined chunk resets it when sent
+and when received, and the window holds the next one back the same way). The clock cannot tell
+"slow" from "dead": a consumer slower than the timeout **is** failed.
+
+### A stream that ends normally ends its port
+
+Where both ends agreed `end`, a stream that ends normally in both directions frees its port on
+both ends with no `close` on the wire, and `ports()` no longer lists it. So the port's life
+follows the stream's own end, not a `close()` someone has to remember: a side that forgets it, or
+a relay that sees the stream end and still holds the port, no longer keeps an id until the mux
+closes. Each side posts its last chunk (`done`), then ends its direction:
+
+- **The caller** ends once the handler's last chunk arrived without an error and its own last
+  chunk left without one: posted when pipelined, confirmed when not.
+- **The serving side** ends once the handler's last chunk left without an error and no more input
+  is coming: the caller's last chunk arrived without an error, or the caller ended its direction.
+  The second is a handler that returned without reading all its pipelined input; that input is
+  dropped, as a close would drop it. A confirmed chunk the handler never read is never confirmed,
+  so the caller's own end never left: that stream is closed (below). It happens to input sent
+  before the handshake settled, so a short request whose handler ignores its body closes.
+
+Nothing either side still owes the other is lost behind its `end`, after which anything it posts
+is dropped: each side's last confirmation leaves before its `end`, and the caller ends only once
+its own last chunk was confirmed, so the serving side owes it nothing more. Freeing the port
+aborts its close signal with `webrun-rpc: the port ended in both directions` once both sides have
+finished, so no result or chunk in flight fails, and neither the caller nor the handler sees an
+error.
+
+A side that only waits for its peer's `end` (a handler that returned without reading all its
+input, its last chunk already out) keeps its port by itself: the watcher that waits for that `end`
+is a listener of the port, and so reachable from the mux. Nothing else of the stream may still
+hold the port then, and a port nobody holds is collected and reported by `onLeak` instead of
+ending (`tests/duplex-end.test.ts` forces a collection there). A close drops the watcher with the
+port's other listeners, so an abandoned stream leaves nothing waiting.
+
+A peer that ends its direction without its last chunk, or behind a last chunk that carries an
+error, is breaking the stream: its consumer would wait for a chunk that cannot come, or take an
+input that failed for one that finished. The input fails with `webrun-rpc: the peer ended its
+direction without finishing it; the stream port is closed`, and this side posts its notice and
+closes the port. The caller's side learns of the agreement from the ack, so it watches for this
+from the handler's first chunk on: a handler that ends having sent no chunk at all leaves the
+caller waiting, as any silent peer does, until its `timeout`.
+
+Anything else is an abandonment, closed with the notice first (below): the caller returning
+early, a timeout, a teardown, and a last chunk that carries an error, from the handler or from the
+caller's input. Without `end` (no window, a peer or a codec that does not offer it) the caller
+closes a normally finished stream too, notice and then `close()`, and the serving side waits for
+that close.
+
+A peer that stops before it ends its own direction keeps the port in both ends' `ports()` until
+the port or a mux closes. A stream's `timeout` has stopped on the side that already ended, so it
+takes the transport's `signal` or `keepalive` to notice, as for any peer that goes silent.
 
 ### How an abandoned stream is reported
 

package/dist/duplex-over-port.d.ts

@@ -35,7 +35,9 @@ export interface DuplexOverPortOptions {
  * same way on the other channel. Within each direction the next chunk is never
  * sent until the previous one has been delivered *and* pulled past by the
  * consumer (spec D11) — the reply to a chunk call *is* the confirmation, and
- * `listenPort` withholds it until then.
+ * `listenPort` withholds it until then. On a port whose window both ends
+ * speak and that agreed `pipeline`, chunks go as plain messages instead, and
+ * the window's credit is the confirmation: up to a window is in flight.
  *
  * A stream port carries exactly one invocation. To make several calls, open
  * several ports: `mux.openPort({ kind: "stream" })` per call.

package/dist/duplex-over-port.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"duplex-over-port.d.ts","sourceRoot":"","sources":["../src/duplex-over-port.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,MAAM,EAOZ,MAAM,6BAA6B,CAAC;AAIrC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAIzD;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,4BAA4B,CAAC;AActD,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CACpC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,GAAE,qBAA0B,GAAG,MAAM,CAE/F;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,qBAA0B,GAClC,MAAM,IAAI,CA8BZ"}
+{"version":3,"file":"duplex-over-port.d.ts","sourceRoot":"","sources":["../src/duplex-over-port.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,MAAM,EAOZ,MAAM,6BAA6B,CAAC;AAIrC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAWzD;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,4BAA4B,CAAC;AA2FtD,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CACpC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,GAAE,qBAA0B,GAAG,MAAM,CAE/F;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,qBAA0B,GAClC,MAAM,IAAI,CA4CZ"}