@statewalker/webrun-rpc 0.4.2 → 0.5.0

package/README.md

@@ -1,90 +1,115 @@
 # @statewalker/webrun-rpc
 
-Ports and RPC over them, in the `webrun-streams-*` family: two port
-multiplexers that turn one `MessageTarget` into many, a `Duplex` stream tier
-that runs one stream over one port, a `Connect` / `Serve` adapter over any
-single port, and a typed-JSON RPC tier that runs over any `MessageTarget`.
-
-## What this is
-
-Four pieces, one dependency:
-
-- **Port multiplexing** (`multiplexPort` / `PortMux`, and `transferPortMux`) —
-  turns one `MessageTarget` into many virtual ones. Each virtual port is itself
-  a `MessageTarget`, so a multiplexer composes over another multiplexer's port,
-  and everything below can run directly on top of it. `multiplexPort` emulates
-  multiplexing over any single port; `transferPortMux` hands the peer real
-  transferred `MessagePort`s where the platform provides them. See
-  [Port multiplexing](#port-multiplexing) and
-  [Transferring ports](#transferring-ports).
-- **Stream tier** (`duplexOverPort` / `serveDuplexOverPort`) — one
-  [`webrun-streams`](../webrun-streams) `Duplex` over one port, with
-  backpressure that is a property of the protocol rather than a configured
-  buffer. **This is what new code should use.** See
-  [Streams over a port](#streams-over-a-port).
-- **Connect/serve adapter** (`connect` / `serve`) — the `webrun-streams`
-  `Connect` / `Serve` seam over a single port, so a port pair drops into the
-  same slot as a socket or a data channel. It is the two pieces above wired
-  together and nothing else: `multiplexPort` allocates one virtual port per
-  call and `duplexOverPort` runs the call on it, which is why it inherits the
-  stream tier's bounded memory rather than a buffer ceiling of its own. See
-  [Connect and serve](#connect-and-serve).
-- **Typed-JSON RPC tier** (`callPort` / `listenPort` / `callBidi` /
-  `listenBidi` / `ioSend` / `ioHandle` / `send` / `recieve`) — request/response
-  with typed JSON arguments per call, relocated here from the retired
-  `webrun-streams-port` package. It types against `MessageTarget` rather than
-  `MessagePort`, so it also runs directly over a virtual port from
-  `multiplexPort` — one raw port fans out into many independent RPC channels
-  with no byte-stream layer in between. Use this when you want plain JSON
-  messaging and do not need byte-stream semantics.
-
-All four are exported from the package root. The only runtime dependency is
-[`@statewalker/webrun-streams`](../webrun-streams).
+## What it is
+
+Ports and RPC over them. The package has four layers, all exported from the root: **port
+multiplexers** (`multiplexPort`, `transferPortMux`) that turn one `MessageTarget` into many virtual
+ones; a **stream tier** (`duplexOverPort` / `serveDuplexOverPort`) that runs one
+`@statewalker/webrun-streams` `Duplex` over one port with backpressure built into the protocol; a
+**`connect` / `serve` adapter** that plugs a source of ports into the `webrun-streams` `Connect` /
+`Serve` shape; and a **typed-JSON RPC tier** (`callPort` / `listenPort`, `callBidi` / `listenBidi`,
+`ioSend` / `ioHandle`, `send` / `recieve`) for request/response and iterator exchange over any
+`MessageTarget`.
 
 ## Why it exists
 
-`MessagePort` is the browser's universal in-process seam — Workers,
-SharedWorkers, ServiceWorkers, iframes, `MessageChannel` pipes between two
-modules in the same tab. It is also the most primitive: `postMessage` fires and
-forgets. There is no request, no correlation, no backpressure, no half-close,
-and an exception on the far side simply never arrives.
+`MessagePort` is the browser's universal in-process seam: Workers, SharedWorkers, ServiceWorkers,
+iframes, a `MessageChannel` between two modules in one tab. It is also the most primitive one.
+`postMessage` fires and forgets. There is no request, no correlation, no backpressure, no
+half-close, and an exception on the far side never arrives.
 
-The stream tier makes a port indistinguishable from any other transport in
-this family, which is what lets an in-browser back-end be tested in-process and
-then moved behind a real socket unchanged. The RPC tier exists because a lot of
-port traffic is not a byte stream at all — it is one typed call with one typed
-answer, and forcing that through a `Duplex` is more machinery than the job
-needs. The multiplexer exists because a single `MessagePort` is usually the
-only pipe you're handed — one `MessageChannel` per logical stream doesn't
-scale — so `multiplexPort` fans it out into as many independent
-`MessageTarget`s as the RPC tier or byte-stream tier need.
+- The **stream tier** makes a port behave like any other `webrun-streams` transport, so a back-end
+  running in a worker can be tested in-process and later moved behind a real socket unchanged.
+- The **multiplexer** exists because one port is usually all you are handed. One `MessageChannel`
+  per logical stream does not scale, and over a WebSocket or a data channel there is no second
+  channel to be had.
+- The **RPC tier** exists because much port traffic is not a byte stream at all. It is one typed
+  call with one typed answer, and a `Duplex` is more machinery than that needs. It types against
+  `MessageTarget`, not `MessagePort`, so it runs directly over a virtual port too.
 
-## Install
+## How to use
 
 ```sh
-npm install @statewalker/webrun-rpc
+pnpm add @statewalker/webrun-rpc
 ```
 
-No peer dependencies. `MessagePort` and `MessageChannel` are platform globals in
-browsers and in Node ≥ 15 (`node:worker_threads`).
+No peer dependencies. ESM only. One entry point, `.`. Runs in browsers, workers and Node: the
+examples use the global `MessageChannel`, which Node also provides. `transferPortMux` needs
+structured clone with transferables, so it works only where real `MessagePort`s can be transferred
+(browsers, workers, iframes, Node `worker_threads`).
 
-## Getting started
+### Choosing a source of ports
 
-### Connect and serve
+`connect` and `serve` take a **port factory** (`PortMuxFactory`), not a port. They ask it for one
+port per call and run one stream on it. How ports are made belongs to whoever knows the transport:
 
-Reach for this when you want the family's `Connect` / `Serve` shape over a
-source of ports; reach for [Streams over a port](#streams-over-a-port) directly
-when you are already holding a port per call.
+| Transport | Factory | Id table? |
+| --- | --- | --- |
+| one pipe (`MessagePort`, worker, WebSocket, data channel) | `overPipe(pipe, { codec })` | yes: there is no second port to be had |
+| a transferable boundary | `overPorts((onPort) => transferPortMux(target, { onPort }))` | no: the platform moves real ports |
+| a transport that multiplexes already | `overPorts((onPort) => yourMux({ onPort }))` | no: the transport did the work |
 
-`connect` and `serve` take a **port factory**, not a port. They ask it for one
-port per call and run a stream on it — so *how* ports are made belongs to
-whoever knows the transport:
+`codec` is `structuredCodec` (exported here) where messages are structured values, or
+`msgpackCodec` from `@statewalker/webrun-msgpack` where they are bytes.
 
-| Transport | Factory | Id table? |
-|---|---|---|
-| one pipe of bytes (`MessagePort`, worker, WebSocket) | `overPipe(pipe, { codec })` | **yes** — there is no second port to be had |
-| a transferable boundary | `overPorts((onPort) => transferPortMux(target, { onPort }))` | no — the platform moves real ports |
-| a transport that multiplexes already (libp2p's yamux) | `overPorts((onPort) => yourMux({ onPort }))` | no — it did the work |
+### Exports
+
+Stream tier and adapter:
+
+| Export | Purpose |
+| --- | --- |
+| `connect(params: PortParams)` | Resolves `{ call, close }`. One port per call, opened on the consumer's first pull. |
+| `serve(params: PortParams, handler)` | Registers a `Duplex` handler. Resolves an idempotent teardown that abandons live streams, then closes the mux. |
+| `PortParams` | `{ mux: PortMuxFactory; timeout?: number }`. |
+| `PortMuxFactory`, `OnPort` | `(onPort?: OnPort) => PortMux \| Promise<PortMux>`; `(port, meta?) => boolean \| undefined`, `false` rejects. |
+| `overPipe(pipe, options: OverPipeOptions)` | A factory over one pipe via `multiplexPort`. Options: `codec`, `side`, `maxPorts`, `maxMessageSize`. |
+| `overPorts(factory)` | Pass-through, for a mux this package knows nothing about. |
+| `duplexOverPort(port, options?)` | A `Duplex` running one stream on `port`. |
+| `serveDuplexOverPort(port, handler, options?)` | The serving half. Returns an idempotent teardown that abandons the stream and notifies the peer. |
+| `DuplexOverPortOptions` | `maxMessageSize`, `timeout`, `log`. |
+| `STREAM_ABORT` | `"webrun-rpc:stream-abort"`, the `type` of the abandonment notice. |
+
+Port multiplexing:
+
+| Export | Purpose |
+| --- | --- |
+| `multiplexPort(port, options: PortMuxOptions)` | Emulated multiplexing over one port. |
+| `transferPortMux(target, options?: TransferPortMuxOptions)` | Multiplexing with real transferred `MessagePort`s. |
+| `PortMux` | `openPort(meta?)`, `close()`, `maxMessageSize`. |
+| `PortCodec`, `PortEnvelope` | The wire seam: `post(port, envelope, transfer?)`, `read(event)`. |
+| `structuredCodec` | Envelopes passed through unencoded. |
+| `DEFAULT_MAX_PORTS` | `1024`. |
+| `PORT_TRANSFER` | `"webrun-rpc:port-transfer"`, the `type` of the message that carries a port. |
+
+Typed-JSON RPC:
+
+| Export | Purpose |
+| --- | --- |
+| `callPort(port, params, options?)` | One typed call, one typed answer. |
+| `listenPort(port, handler, options?)` | Answers `callPort`. Returns an unsubscribe. |
+| `callBidi(port, input, args?)` / `listenBidi(port, action, accept?)` | Streaming call: send an iterable, receive an async generator. |
+| `ioSend(port, output, options?)` / `ioHandle(port, handler, options?)` | The full-duplex iterator exchange `callBidi` / `listenBidi` run on. |
+| `send(port, output, options?)` / `recieve(port, options?)` | One `callPort` per iterator chunk, and its receiving side. |
+| `NO_TIMEOUT` | `Number.POSITIVE_INFINITY`; as `callPort`'s `timeout`, installs no deadline. |
+| `CallPortOptions` | `timeout` (default 1000 ms), `channelName`, `log`, `newCallId`, `signal`. |
+| `CallBidiOptions`, `CallBidiArgs` | Adds `bidiTimeout` (default 2147483647 ms) for the outer call. |
+| `ListenPortOptions`, `PortHandler`, `BidiHandler`, `IoSendOptions`, `RecieveOptions`, `SendOptions` | Supporting types. |
+| `postCancelChannel(port, channelName)` / `listenCancelChannel(port, channelName, onCancel)` / `CANCEL_CHANNEL_TYPE` | The `"cancel-channel"` message `ioSend` posts when its consumer stops early. |
+| `getPortCloseSignal(port)` / `setPortCloseSignal(port, signal)` | An `AbortSignal` per port that marks its transport closed; `callPort` combines it with its own `signal`. |
+
+Message passing (types only): `MessageTarget` (`MessageSource` + `MessageSink` + optional
+`close()`), `MessageSource` (`addEventListener` / `removeEventListener` for `"message"`, optional
+`start()`), `MessageSink` (`postMessage(message, transfer?)`), `MessageListener`. A `MessagePort`
+satisfies `MessageTarget` structurally.
+
+`byteChannelFromMessagePort(port)` wraps a `MessageTarget` as a `webrun-streams` `ByteChannel`
+(bytes out through `postMessage`, `Uint8Array` / `ArrayBuffer` / views in, everything else
+ignored), for driving `webrun-streams`' `emulateMux` yourself. Nothing else in this package uses
+it.
+
+## Examples
+
+### `connect` and `serve` over a `MessageChannel`
 
 ```ts
 import { connect, overPipe, serve, structuredCodec } from "@statewalker/webrun-rpc";
@@ -117,85 +142,12 @@ Across a Worker boundary, transfer one end and keep the other:
 const { port1, port2 } = new MessageChannel();
 worker.postMessage({ port: port2 }, [port2]);
 const { call } = await connect({ mux: overPipe(port1, { codec: structuredCodec }) });
+// inside the worker: serve({ mux: overPipe(port, { codec: structuredCodec, side: "responder" }) }, handler)
 ```
 
-#### Why a factory and not a `PortMux`
-
-Every mux decides accept-or-reject **synchronously**, inside the `open`
-envelope, and tells the peer on the spot — `multiplexPort` posts
-`{type:"close", reason:"rejected"}` before returning. There is no "decide
-later", and layer 1 refuses to queue what it cannot deliver.
-
-So handing `serve` a mux that already exists would leave a window between its
-construction and its handler being attached, and a port arriving in that window
-is rejected outright — **measured: zero messages delivered**, with the peer told
-`rejected` for a call whose only fault was being early. A factory closes the
-window by construction: the mux cannot exist before the thing that answers it.
-`port-factory-no-race.test.ts` measures both halves.
-
-`connect` passes no handler, which is how a caller declines inbound ports —
-your factory receives `undefined`. Whichever of the two called the factory owns
-the mux and closes it.
-
-#### Port-id sides
-
-`side: "initiator" | "responder"` belongs to `overPipe`, because it is
-`multiplexPort`'s id parity: initiator takes even port ids, responder odd. The
-two ends of one pipe must disagree, or their ids collide on the first
-concurrent call. A transport that multiplexes on its own has no ids and no
-parity, which is why this is not a `connect`/`serve` option any more.
-
-#### Tuning
-
-`overPipe` takes `maxPorts` (concurrent in-flight calls) and `maxMessageSize`
-(payload split size, if the transport caps a message); `connect`/`serve` take
-`timeout` (per-stream inactivity, off by default). `maxMessageSize` is
-*reported* by the mux to the stream tier, so a transport with no message
-ceiling — a libp2p stream — simply does not set one and nothing is split.
-There is deliberately **no buffer size**. The stream tier withholds a chunk's confirmation until the
-consumer has pulled past it, so a producer is at most one chunk ahead of its
-consumer and the ceiling is one chunk per open port — a number there is nothing
-to tune. `connect-serve-backpressure.test.ts` measures it: a 5000-chunk
-producer against a handler that reads one chunk and stops gets exactly one
-chunk out.
-
-### Typed-JSON RPC tier
-
-```ts
-import { callPort, listenPort } from "@statewalker/webrun-rpc";
-
-// Responder
-const off = listenPort(port2, async ({ a, b }) => ({ sum: a + b }));
-
-// Caller
-const { sum } = await callPort(port1, { a: 2, b: 3 }, { timeout: 2000 });
-```
-
-`callBidi` / `listenBidi` extend this to a streaming outer call, and `ioSend` /
-`ioHandle` carry an async iterator across the port.
-
-### Carrying HTTP over a port
+### A stream over a virtual port, wired by hand
 
 ```ts
-import { fetchOverDuplex } from "@statewalker/webrun-http-streams";
-
-const response = await fetchOverDuplex(call, new Request("http://local/api/todo"));
-```
-
-## Streams over a port
-
-`duplexOverPort(port, options)` runs one `Duplex` over one port;
-`serveDuplexOverPort(port, handler, options)` is its serving half. Each
-direction is one `callPort` per chunk on its own channel (`"in"` for the
-caller's input, `"out"` for the handler's output), and the reply to a chunk
-*is* the confirmation that the consumer pulled past it.
-
-**One stream per port.** A stream port carries exactly one invocation — open
-one port per call. Nothing enforces this: invoking the same `duplexOverPort`
-result twice on one port makes both invocations cross-talk on the same two
-channel names.
-
-```js
 import {
   duplexOverPort,
   multiplexPort,
@@ -204,8 +156,6 @@ import {
 } from "@statewalker/webrun-rpc";
 
 const channel = new MessageChannel();
-channel.port1.start();
-channel.port2.start();
 
 // The serving end: every stream port the peer opens runs one echo handler.
 const server = multiplexPort(channel.port2, {
@@ -219,15 +169,11 @@ const server = multiplexPort(channel.port2, {
 });
 
 // The calling end: one port per stream.
-const client = multiplexPort(channel.port1, {
-  codec: structuredCodec,
-  side: "initiator",
-});
-
+const client = multiplexPort(channel.port1, { codec: structuredCodec, side: "initiator" });
 const streamPort = await client.openPort({ kind: "stream" });
 const call = duplexOverPort(streamPort, { maxMessageSize: client.maxMessageSize });
 
-const parts = [];
+const parts: string[] = [];
 for await (const chunk of call([new TextEncoder().encode("ping")])) {
   parts.push(new TextDecoder().decode(chunk));
 }
@@ -237,313 +183,282 @@ await client.close();
 await server.close();
 ```
 
-### `DuplexOverPortOptions`
-
-| option | type | meaning |
-| --- | --- | --- |
-| `maxMessageSize` | `number` | Largest payload one chunk may carry, normally `PortMux.maxMessageSize`. Bodies are split to fit with `toChunks`. Unset means no limit and no splitting. |
-| `timeout` | `number` | Inactivity timeout for the **whole stream**, in ms. See below. Unset — the default — means no timeout at all. |
-| `log` | `(...args) => void` | Logging hook; defaults to a no-op. |
-
-### Flow control: a window of one
-
-Within one direction the next chunk is never sent until the previous one has
-been delivered **and** pulled past by the consumer. There is no credit window
-and no buffer ceiling to tune, because there is nothing to tune: **one open
-port holds at most one chunk.** Over `multiplexPort` that composes into a
-whole-mux bound of `maxPorts × one chunk`, because `maxPorts` caps concurrent
-ports. `transferPortMux` has no `maxPorts` (see
-[Transferring ports](#transferring-ports)), so the per-port bound is the same
-but the mux-wide one is yours to impose by bounding how many ports you open.
-
-A peer that sends a second chunk before the first is confirmed has that call
-refused and **that port closed** — the penalty is scoped to the offending port
-and every other port on the mux is untouched.
-
-The honest cost, from the design's own numbers: single-stream throughput is
-`chunk ÷ RTT`. In-process that is negligible. Over a 50 ms WAN round trip a
-10 MiB body is **~43 s**, because it is 854 sequential round trips.
-Concurrency does not come from pipelining one stream — it comes from running
-many streams, which are genuinely independent because each owns its own port.
-
-### The timeout
-
-There is **no timeout by default**, and that is deliberate: a per-chunk
-deadline fails a consumer that is merely slow, which is a bug rather than a
-policy. `callPort` gained `NO_TIMEOUT` for the same reason, and the stream tier
-uses it for every chunk call.
-
-The `timeout` option is an inactivity timeout for the whole stream: any chunk
-in either direction resets it, and elapsing aborts the stream.
-
-**Know what you are buying if you set it.** The clock is only reset once a
-chunk call *returns*, and that reply is withheld until the consumer has pulled
-past the value. The inactivity clock therefore cannot distinguish "the peer is
-slow" from "the peer is dead": with an explicit `timeout`, a consumer slower
-than it **is** failed. The default of none is why a slow consumer is safe out
-of the box.
-
-### Cancellation
-
-Layer 1's close is invisible to layer 2 (see
-[Port multiplexing](#port-multiplexing)): a closed port drops its listeners
-silently and is indistinguishable from a working port nobody is answering. So a
-side that abandons a stream posts an out-of-band `STREAM_ABORT` notice on the
-port — which is the only signal the peer can act on.
-
-**Three routes post that notice; two do not.** The notice is posted from
-exactly two places in the implementation — the teardown returned by
-`serveDuplexOverPort`, and the caller's own `finally` as its generator unwinds
-— and everything else that ends a stream simply aborts locally. Measured:
-
-| what ends the stream | notice posted? | what the peer actually observes |
-| --- | --- | --- |
-| the caller stops iterating (`break`, `return`, `throw`) | **yes** | `STREAM_ABORT`; the handler unwinds through `iter.return()` |
-| the caller's inactivity `timeout` elapses | **yes** — the abort rejects the caller's stream, and its `finally` posts on the way out | `STREAM_ABORT` |
-| you call the teardown `serveDuplexOverPort` returned | **yes** | `STREAM_ABORT`; the caller's stream rejects with `the peer abandoned the stream` |
-| the **serve side's** inactivity `timeout` elapses | **no** | nothing on the `out` half — a caller parked there waits forever. A caller still *sending* has its chunk calls answered `webrun-rpc: the stream is closed`, but `duplexOverPort` surfaces only the inbound half, so that rejection never reaches its consumer either |
-| a **window violation** (a second unconfirmed chunk), on either side | **no** | the offender gets `response:error` on the channel it violated, naming the violation. Nothing else: the enforcer closes the port, and that close is exactly the layer 1 signal layer 2 cannot see. A peer parked on the other half waits forever |
-
-So the notice is what makes a *cooperative* abandonment observable. It is not a
-general liveness mechanism, and the two rows without one are a known gap rather
-than a subtlety of the wording: **give the side that must not hang its own
-`timeout`.** A caller with a `timeout` set detects both of the silent rows on
-its own clock; a caller without one does not detect them at all.
-
-**An abort unwinds a producing handler through `iter.return()`, not by
-throwing into it.** A handler's `catch` never sees the abort reason; only its
-`finally` runs. Put cleanup in `finally`.
+### Real transferred ports
 
-## API
-
-### Stream tier — exports
-
-| Export | Kind | Purpose |
-| --- | --- | --- |
-| `duplexOverPort(port, options?)` | function | Returns a `Duplex` running one stream on `port`. |
-| `serveDuplexOverPort(port, handler, options?)` | function | Installs `handler` as the serving half. Returns an idempotent teardown that abandons the stream and notifies the peer. |
-| `STREAM_ABORT` | constant | The `type` of the out-of-band notice a side posts when it abandons a stream. Exported because tests and adapters assert on it. |
-| `DuplexOverPortOptions` | type | `maxMessageSize`, `timeout`, `log` — see [above](#duplexoverportoptions). |
-| `NO_TIMEOUT` | constant | Pass as `callPort`'s `timeout` to install no deadline at all. |
-
-### Connect/serve tier — exports
-
-| Export | Kind | Purpose |
-| --- | --- | --- |
-| `connect(params)` | `Connect<PortParams>` | Resolves `{ call, close }`. One port per call, opened on the consumer's first pull. |
-| `serve(params, handler)` | `Serve<PortParams>` | Registers a `Duplex` handler. Returns an idempotent teardown that abandons the live streams before releasing the mux. |
-| `PortParams` | type | `{ mux: PortMuxFactory; timeout?: number }`. |
-| `PortMuxFactory` | type | `(onPort?) => PortMux \| Promise<PortMux>`. Why a factory: [above](#why-a-factory-and-not-a-portmux). |
-| `overPipe(pipe, options)` | `PortMuxFactory` | Ports over one pipe of bytes, via `multiplexPort`. Takes `codec`, `side`, `maxPorts`, `maxMessageSize`. |
-| `overPorts(factory)` | `PortMuxFactory` | Pass-through, for a mux this package knows nothing about. |
-| `OnPort` | type | `(port, meta?) => boolean \| undefined`. `false` rejects. |
-
-`byteChannelFromMessagePort(port)` is still exported, and is now the only thing
-in the package that touches `ByteChannel`: it wraps a port for driving
-`emulateMux` yourself. Nothing here uses it. It goes away with `emulateMux` in
-Plan C.
-
-### Typed-JSON RPC tier — exports
-
-| Export | Purpose |
-| --- | --- |
-| `callPort(port, args, options?)` | One typed call, one typed answer. |
-| `listenPort(port, handler, options?)` | Answer `callPort` requests. Returns an unsubscribe. |
-| `callBidi(port, args)` / `listenBidi(port, handler)` | Streaming outer call in both directions. |
-| `ioSend(...)` / `ioHandle(...)` | Ship an async iterator across the port. |
-| `send(...)` / `recieve(...)` | The low-level message primitives underneath. |
-| `CallPortOptions` | `timeout` (default 1000 ms; `NO_TIMEOUT`, or any value that is not a finite number above zero, installs no deadline), `channelName`, `log`, `newCallId`, `signal`. |
-| `CallBidiOptions` / `CallBidiArgs` | `bidiTimeout` for the outer stream. |
-| `ListenPortOptions`, `PortHandler`, `BidiHandler`, `IoSendOptions`, `RecieveOptions`, `SendOptions` | Supporting types. |
-
-### Cancellation and close signalling
-
-| Export | Purpose |
-| --- | --- |
-| `postCancelChannel(...)` / `listenCancelChannel(...)` | Out-of-band cancellation for an in-flight call. |
-| `CANCEL_CHANNEL_TYPE` | The reserved message type used for it. |
-| `setPortCloseSignal(port, signal)` / `getPortCloseSignal(port)` | Attach an `AbortSignal` that marks a port as closed, so pending calls reject instead of hanging. |
+```ts
+import { duplexOverPort, serveDuplexOverPort, transferPortMux } from "@statewalker/webrun-rpc";
 
-## Port multiplexing
+const { port1, port2 } = new MessageChannel();
 
-`multiplexPort` turns one message port into many. Each virtual port is itself a
-`MessageTarget` — the same shape as a `MessagePort` — so whatever runs on top
-cannot tell a virtual port from a real one, and a multiplexer composes over
-another multiplexer's port.
+const server = transferPortMux(port2, {
+  onPort: (port, meta) => {
+    // `meta` is `unknown`: the mux never inspects it, so you narrow it.
+    if ((meta as { kind?: string } | undefined)?.kind !== "stream") return false; // reject
+    serveDuplexOverPort(port, async function* (input) {
+      for await (const chunk of input) yield chunk;
+    });
+  },
+});
 
-**A port sends and receives messages. That is all.** No backpressure,
-acknowledgements, credit or buffering ceiling — deliberately, matching
-`MessagePort` semantics. Waiting strategies belong above. The one safety
-property it does hold: **a message for a port with no consumer is dropped, never
-queued**, so a peer flooding an unaccepted port cannot grow memory here.
+const client = transferPortMux(port1);
+const port = await client.openPort({ kind: "stream" });
+for await (const chunk of duplexOverPort(port)([new Uint8Array([1, 2, 3])])) {
+  console.log(chunk); // Uint8Array [1, 2, 3]
+}
 
-### `multiplexPort(port, options): PortMux`
+await client.close();
+await server.close();
+```
 
-The default implementation, which emulates multiplexing over a single port. A
-transport that already multiplexes natively supplies its own `PortMux` instead.
+### One typed call
 
-| option | type | meaning |
-| --- | --- | --- |
-| `codec` | `PortCodec` | How envelopes reach the wire. Required. |
-| `onPort` | `(port, meta?) => boolean \| undefined` | Called when the peer opens a port. Return `false` to reject. **Without it, inbound ports are rejected.** |
-| `side` | `"initiator" \| "responder"` | Id parity — initiator allocates even, responder odd, so both ends may open concurrently. Defaults to `"initiator"`. |
-| `maxPorts` | `number` | Ceiling on **concurrently** open ports. Defaults to `1024`. Closing a port frees its slot immediately, so a long-lived mux can open unboundedly many over its lifetime — this bounds the id table, never the total. It also never delays a message. |
-| `maxMessageSize` | `number` | Largest **payload** a chunk may carry, if the transport has a limit. Reported, not enforced. It bounds the payload, **not the frame**: the layer above chunks the payload to it and the envelope framing is added on top afterwards — measured at 123–128 bytes over `msgpackCodec` (the 128 at a 64 KiB cap), with a modelled ceiling of 134. **Set this ~256 bytes below the transport's real limit**, or a full-size chunk overruns it (a 12 KiB setting was measured producing 12,413-byte frames). |
+```ts
+import { callPort, listenPort } from "@statewalker/webrun-rpc";
 
-### `PortMux`
+const { port1, port2 } = new MessageChannel();
+port1.start();
+port2.start();
 
-| member | meaning |
-| --- | --- |
-| `openPort(meta?)` | Allocate a port, announce it, and return the local end. **Asynchronous** — a natively multiplexed transport cannot produce a port synchronously, and the two must share a shape. Does not wait for the peer to accept. **Rejects** with `RangeError` past `maxPorts`, and rejects on a closed mux — it does not throw synchronously, so a bare `try`/`catch` around the call will not catch either. |
-| `close()` | Close every virtual port, then release the underlying port. |
-| `maxMessageSize` | See above. |
+const off = listenPort<{ a: number; b: number }, { sum: number }>(port2, async ({ a, b }) => ({
+  sum: a + b,
+}));
 
-`openPort` returning a promise that resolves before acceptance is deliberate:
-it keeps layer 1 free of round trips. Messages posted before the peer accepts
-are sent, and dropped at the far end if it rejects; the port becomes inert.
-Guard failures — `maxPorts` exceeded, the mux already closed — reject the
-returned promise rather than throwing synchronously, so a caller wrapping a
-bare `openPort(...)` call in `try`/`catch` will not catch them.
+const { sum } = await callPort<{ sum: number }>(port1, { a: 2, b: 3 }, { timeout: 2000 });
+console.log(sum); // 5
 
-**No close is observable at this layer — not a rejection, and not an orderly close
-either.** `MessageTarget` has no close event and the port you hold exposes no
-queryable state, so when a port closes its listeners are simply cleared and
-`postMessage` becomes a silent no-op. You get no event, no error, and no callback,
-and a `close` envelope's `reason` is discarded rather than delivered. A closed port
-is indistinguishable from a working one that nobody is answering.
+off();
+```
 
-This is deliberate — a real `MessagePort` behaves the same way, and a close event
-would make this something other than a port — but it means **the layer above must
-carry its own end-of-stream signal** as an ordinary message, sent before the port
-closes, rather than relying on the close being seen.
+A handler that throws rejects the caller with the deserialised error. A call with no reply rejects
+after `timeout` with `Call timeout. CallId: "<id>".`
 
-### `structuredCodec`
+### A streaming call
 
-For ports whose messages are structured values. Envelopes pass through
-unencoded, so nothing is serialised and `ArrayBuffer`s move zero-copy through the
-transfer list.
+```ts
+import { callBidi, listenBidi } from "@statewalker/webrun-rpc";
 
-A byte transport needs a codec that encodes; that one ships with
-`@statewalker/webrun-msgpack`, so this package keeps no dependencies.
+const { port1, port2 } = new MessageChannel();
+port1.start();
+port2.start();
 
-### `PortEnvelope`
+const off = listenBidi<number, number>(port2, async function* (input, params) {
+  for await (const n of input) yield n * (params.factor as number);
+});
 
-What crosses the wire: `{ type: "open", id, meta? }`, `{ type: "message", id,
-payload }`, `{ type: "close", id, reason? }`.
+for await (const n of callBidi<number, number>(port1, [1, 2, 3], { factor: 10 })) {
+  console.log(n); // 10, 20, 30
+}
 
-`reason` is opaque: layer 1 never inspects it — and, as implemented, never surfaces
-it either. Setting one accomplishes nothing observable at this layer today; it
-exists so the wire format does not have to change when a layer above starts
-carrying it.
+off();
+```
 
-## Transferring ports
+`callBidi`'s third argument is the parameter bag the handler receives; `options` inside it is
+reserved for `CallBidiOptions`. The optional `accept(params)` predicate on `listenBidi` declines
+calls.
 
-`transferPortMux(target, options)` is a second `PortMux` with the same
-`openPort` / `close` / `maxMessageSize` shape, so the stream tier above it is
-identical — but its ports are **real, transferred `MessagePort`s**. Each
-`openPort` creates a `MessageChannel`, transfers one end to the peer over
-`target`, and returns the other. There is no id table, no `maxPorts` and no
-envelope overhead per message, because the platform does the multiplexing.
+## Internals
 
-```ts
-import { transferPortMux } from "@statewalker/webrun-rpc";
+### Layers
 
-const mux = transferPortMux(worker, {
-  onPort: (port, meta) => {
-    // `meta` is `unknown` — layer 1 never inspects it, so you narrow it.
-    if ((meta as { kind?: string })?.kind !== "stream") return false; // reject
-    serveDuplexOverPort(port, handler);
-  },
-});
+```
+  your code ── Connect / Serve ─────────────────────────────┐
+                    │ connect / serve                       │
+  stream tier ──────┤ duplexOverPort / serveDuplexOverPort  │  layer 2
+                    │ one callPort per chunk, "in" / "out"  │
+  RPC tier ─────────┘ callPort / listenPort                 ┘
+                    │ MessageTarget (a virtual port)
+  port mux ──────── multiplexPort (id table + PortCodec)    ┐  layer 1
+                    or transferPortMux (real MessagePorts)  ┘
+                    │ MessageTarget
+  transport ─────── MessagePort, worker, WebSocket, data channel, ...
 ```
 
-| option | type | meaning |
-| --- | --- | --- |
-| `onPort` | `(port, meta?) => boolean \| undefined` | Called when the peer transfers a port in. Return `false` to reject it — the port is closed and nothing further arrives on it. Any other return value, `undefined` included, accepts. **Without it, inbound ports are rejected**, matching `multiplexPort`. |
-| `maxMessageSize` | `number` | Reported to the layer above, never enforced. A `MessagePort` normally has no limit. |
-
-`PORT_TRANSFER` is the `type` of the envelope that carries a port to the peer.
-A message with that `type` and no attached port is malformed and is dropped, so
-a shared parent port is not corrupted.
-
-**It needs structured clone with transferables**, so it exists in browsers,
-workers and iframes and nowhere else — not over a byte transport. The caller
-selects it explicitly rather than by capability sniffing: use `multiplexPort`
-where the transport is one pipe of bytes.
-
-What it buys over emulation: a transferred port can cross an origin or a worker
-boundary and be handed to code that never saw `target`, which is what a relay
-handing a live connection to a third party needs. An emulated port id is
-meaningless outside its own mux.
-
-`target` must be a full `MessageTarget`. Reaching a send-only `MessageSink` —
-a `ServiceWorkerClient`, say — is a real use of port transfer but needs a
-different entry point, and is not part of this interface.
-
-**Caveat: the issued-port set never shrinks.** Every port `transferPortMux`
-opens or accepts is retained until `close()`, and nothing removes a port from
-that set when it closes. There is no `maxPorts` here for it to exhaust, so
-nothing fails — the set just grows, holding dead `MessagePort` handles for as
-long as the mux lives. Bounding it needs a per-port `close`-event listener, a
-newer platform surface this implementation otherwise avoids; it is a known,
-deliberately deferred gap rather than an oversight. In practice: **scope the
-mux to the lifetime of the thing it multiplexes** — a worker, an iframe, a
-connection — rather than making one process-wide mux and opening streams
-through it forever.
-
-## Message passing
-
-| Export | Kind | Purpose |
-| --- | --- | --- |
-| `MessageTarget` | interface | Full-duplex structural view of a message endpoint — a `MessagePort`, a `Worker`, or a ServiceWorker bridge. Extends `MessageSource` and `MessageSink`. |
-| `MessageSource` | interface | `addEventListener`/`removeEventListener` for `"message"`, plus optional `start()`. |
-| `MessageSink` | interface | `postMessage(message, transfer?)`. |
-| `MessageListener` | type | `(event: MessageEvent) => void \| Promise<void>`. |
+Each virtual port is itself a `MessageTarget`, so a multiplexer composes over another
+multiplexer's port, and the RPC tier runs over a virtual port with no byte-stream layer between.
 
-These are types only — no runtime code — so pulling in just the RPC tier costs
-nothing extra. A `MessagePort` satisfies `MessageTarget` structurally; no
-adapter is needed.
+### A port sends and receives messages, nothing more
 
-## Conformance
+`multiplexPort` has no backpressure, acknowledgements, credit or buffer ceiling. That matches
+`MessagePort` semantics; waiting strategies belong above. The one safety property it holds: **a
+message for a port with no consumer is dropped, never queued**, so a peer flooding an unaccepted
+port cannot grow memory here.
 
-The unmodified L0–L6 suite of
-[`@statewalker/webrun-streams-conformance`](../webrun-streams-conformance) runs
-**twice**, 11 tests each, against two entry points into the same stack:
+`multiplexPort` options:
 
-| run | stack |
+| option | meaning |
 | --- | --- |
-| `webrun-rpc (MessageChannel pair)` | `connect` / `serve` — the adapter, driving both pieces below |
-| `webrun-rpc (multiplexPort + duplexOverPort)` | the two pieces wired by hand in the test |
-
-The suite itself has never been changed to accommodate either run.
+| `codec` | Required. How envelopes reach the wire. |
+| `onPort` | Called when the peer opens a port; return `false` to reject. A throw also rejects. **Without it, inbound ports are rejected**: a port nobody holds has no consumer. |
+| `side` | `"initiator"` (default) allocates even ids, `"responder"` odd, so both ends can open concurrently with no negotiation. The two ends of one pipe must disagree. |
+| `maxPorts` | Ceiling on concurrently open ports, default `DEFAULT_MAX_PORTS` (1024). Closing a port frees its slot. It bounds the id table, never the total over time, and never delays a message. A peer `open` past the limit is answered with `close` reason `"max-ports"`. |
+| `maxMessageSize` | Largest payload a chunk may carry, if the transport has a limit. Reported to the stream tier, never enforced. See below. |
+
+`openPort(meta?)` allocates a port, announces it and returns the local end without waiting for the
+peer to accept. That keeps layer 1 free of round trips: messages posted before a rejection are
+dropped at the far end and the port goes inert. It is asynchronous because a natively multiplexed
+transport cannot produce a port synchronously and both must share one shape. Its guard failures
+are rejections, not synchronous throws: `RangeError: webrun-rpc: maxPorts (<n>) reached` and
+`Error: webrun-rpc: the multiplexer is closed`. A duplicate `open` id from the 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? }`, `{ type: "message", id, payload }` or
+`{ type: "close", id, reason? }`. `structuredCodec.read` accepts only objects with a non-negative
+integer `id` and one of those three 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.
+
+### No close is observable at layer 1
+
+`MessageTarget` has no close event and a virtual port exposes no state. When a port closes, its
+listeners are cleared and `postMessage` becomes a no-op. There is no event, no error, and the
+`close` envelope's `reason` is discarded rather than delivered. A closed port is indistinguishable
+from a working one that nobody answers. A real `MessagePort` behaves the same way, so **the layer
+above carries its own end-of-stream signal** as an ordinary message.
+
+### Why `connect` / `serve` take a factory and not a `PortMux`
+
+Every mux decides accept-or-reject synchronously, inside the `open` envelope, and tells the peer
+on the spot. A mux handed over already built would have a window between its construction and its
+handler being attached, and a port arriving in that window is rejected outright: measured, zero
+messages delivered and the peer told `rejected`. A factory closes the window by construction
+(`tests/port-factory-no-race.test.ts`). `connect` calls the factory with no handler, which is how a
+caller declines inbound ports. Whichever side called the factory owns the mux and closes it.
+
+`connect` opens the port on the consumer's first pull, not when `call` is invoked, so a stream
+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
+
+`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
+confirmation that the consumer pulled past it, and the next chunk is not sent until then. So **one
+open port holds at most one chunk** in each direction, and there is no buffer size to tune. Over
+`multiplexPort` that bounds the whole mux at `maxPorts × one chunk`. `transferPortMux` has no
+`maxPorts`, so bounding how many ports you open is up to you.
+`tests/connect-serve-backpressure.test.ts` measures it: a 5000-chunk producer against a handler
+that reads one chunk and stops gets exactly one chunk out.
+
+A peer that sends a second chunk before the first is confirmed gets `response:error` with
+`webrun-rpc: peer sent a second unconfirmed chunk; the stream port is closed`, and that port is
+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.
+
+**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.
+
+### `maxMessageSize` bounds the payload, not the frame
+
+The stream tier splits payloads to `maxMessageSize` with `toChunks`; the chunk wrapper, the
+`callPort` request, the mux envelope and the codec are added on top. Over `msgpackCodec` that
+framing measured 123–128 bytes (modelled ceiling 134), varying per chunk with the call id's
+length. **Set it at least 256 bytes below the transport's real limit.** Set to the limit exactly,
+a full-size chunk overruns it; a 12 KiB setting produced 12,413-byte frames, and on LiveKit an
+oversized message delivered a body as zero bytes with no error on either side. A transport with no
+ceiling leaves it unset, and nothing is split.
+
+### There is no timeout by default
+
+A per-chunk deadline fails a consumer that is merely slow, so the stream tier calls `callPort`
+with `NO_TIMEOUT` for every chunk. The `timeout` option (on `duplexOverPort`, `serveDuplexOverPort`
+and `connect` / `serve`) is an inactivity timeout for the whole stream: any chunk in either
+direction resets it, and elapsing aborts the stream with `webrun-rpc: stream idle for <n> ms`.
+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.
+
+### How an abandoned stream is reported
+
+Because close is invisible at layer 1, a side that abandons a stream posts an out-of-band
+`{ type: STREAM_ABORT }` message on the port. It is posted from exactly two places: the teardown
+returned by `serveDuplexOverPort` (and so `serve`'s teardown), and the caller's `finally` as its
+generator unwinds.
+
+| what ends the stream | notice posted? | what the peer observes |
+| --- | --- | --- |
+| the caller stops iterating (`break`, `return`, `throw`) | yes | `STREAM_ABORT`; the handler unwinds through `iter.return()` |
+| the caller's `timeout` elapses | yes, from the caller's `finally` | `STREAM_ABORT` |
+| the serve-side teardown is called | yes | the caller's stream rejects with `webrun-rpc: the peer abandoned the stream` |
+| the serve side's `timeout` elapses | **no** | nothing on `"out"`: a caller waiting there waits forever. A caller still sending gets `webrun-rpc: the stream is closed` on its chunk calls, but `duplexOverPort` surfaces only the inbound half, so its consumer never sees it |
+| a window violation, on either side | **no** | the offender gets the `response:error` above; the enforcer closes the port, which the other half cannot see, so a peer waiting on the other half waits forever |
+
+The notice makes cooperative abandonment observable. It is not a liveness mechanism: **give the
+side that must not hang its own `timeout`.** A caller with a `timeout` detects both silent rows; a
+caller without one does not.
+
+An abort unwinds a producing handler through `iter.return()`, not by throwing into it. A handler's
+`catch` never sees the abort reason; only `finally` runs. Put cleanup in `finally`.
+
+### `transferPortMux` moves real ports
+
+Each `openPort` creates a `MessageChannel`, posts `{ type: PORT_TRANSFER, meta }` with one end in
+the transfer list, and returns the other end. There is no id table, no `maxPorts` and no
+per-message envelope, because the platform does the multiplexing. A transferred port can cross an
+origin or worker boundary and be handed to code that never saw `target`, which an emulated port id
+cannot. A `PORT_TRANSFER` message without an attached port is dropped. `onPort` returning `false`
+(or throwing) closes the port; no `onPort` rejects every inbound port. The caller picks this mux
+explicitly; nothing sniffs capabilities. `target` must be a full `MessageTarget`; a send-only
+`MessageSink` such as a `ServiceWorkerClient` is not supported.
+
+**The issued-port set never shrinks.** Every port opened or accepted is kept until `close()`, and
+nothing removes a port when it closes. Bounding it needs a per-port `close` event listener, a newer
+platform surface this implementation avoids. Nothing fails; the set just grows. Scope the mux to the
+lifetime of the thing it multiplexes — a worker, an iframe, a connection — not to the process.
+
+### The typed-JSON RPC tier on the wire
+
+`callPort` posts `{ type: "request", channelName, callId, params }` and waits for
+`{ type: "response:result" | "response:error", channelName, callId, ... }`. `channelName`
+(default `""`) lets several conversations share one port; `callId` defaults to
+`` `call-${Date.now()}-${random}` ``. The default `timeout` is 1000 ms; any value that is not a
+finite number above zero installs no deadline. Errors cross as `webrun-streams`' serialised form
+(`message`, `stack`, and every own enumerable property) and are rebuilt as `Error`s.
+
+`callPort` rejects early when its `signal` aborts, or when the port's close signal fires.
+`getPortCloseSignal(port)` returns the `AbortSignal` registered with `setPortCloseSignal`, or
+`undefined`. A raw `MessagePort` never reports its peer closing, so an adapter that does know when
+its transport closed can register a signal and pending calls reject instead of waiting for their
+timeout. Nothing in this package registers one.
+
+`send` sends an iterable as one `callPort` per chunk and ends with `{ done: true }`; `recieve`
+yields one async generator per inbound stream and never ends on its own. `ioSend` / `ioHandle`
+pair them in both directions, and `ioSend` posts `{ type: "cancel-channel", channelName }` when
+its consumer stops early so the producer stops without waiting for timeouts. `callBidi` picks a
+random sub-channel, announces it with an outer `callPort` (timeout `bidiTimeout`), and runs
+`ioSend` on it; if the outer call rejects, the inner stream is cancelled and the error rethrown.
+
+### Conformance
+
+The unmodified L0–L6 suite of `@statewalker/webrun-streams-conformance` runs against two entry
+points into the same stack: `connect` / `serve` over a `MessageChannel` pair
+(`tests/conformance.test.ts`) and `multiplexPort` + `duplexOverPort` wired by hand
+(`tests/conformance-new-stack.test.ts`).
 
 ```sh
 pnpm --filter @statewalker/webrun-rpc test
 ```
 
-**L6 does not prove flow control on either run.** `PairTuning` is a credit
-window (`mtu`, `maxStreamBuffer`) and this stack has none to size. The
-`connect`/`serve` pair translates `mtu` to `maxMessageSize`, so its L6 at least
-runs the 256 KiB body as 64 frames rather than one, and drops
-`maxStreamBuffer`; the hand-wired pair ignores the tuning outright, and with
-`maxMessageSize` unset its L6 body crosses as exactly one chunk in each
-direction. Both greens say the body round-trips. The bounded-memory property
-is measured in `tests/connect-serve-backpressure.test.ts`, which counts how far
-a 5000-chunk producer gets against a handler that reads one chunk and stops —
-one chunk here, 5000 against the `emulateMux` implementation this replaced.
-The rest of the flow-control coverage is in
-`tests/duplex-over-port-timeout.test.ts` and
-`tests/duplex-over-port-hostile.test.ts`.
-
-## Dependencies
-
-| Dependency | Kind | Why |
-| --- | --- | --- |
-| [`@statewalker/webrun-streams`](../webrun-streams) | runtime | The `Duplex` / `Connect` / `Serve` seam, the iterator primitives underneath the stream tier, and — for `byteChannelFromMessagePort` alone — `ByteChannel` and `emulateMux`. |
+L6 does not prove flow control on either run. The suite's `PairTuning` is a credit window (`mtu`,
+`maxStreamBuffer`), and this stack has none to size. The `connect` / `serve` run maps `mtu` to
+`maxMessageSize`, so its 256 KiB body crosses as 64 frames; the hand-wired run ignores tuning, so
+its body crosses as one chunk each way. Bounded memory is measured in
+`tests/connect-serve-backpressure.test.ts`, `tests/backpressure-both-directions.test.ts`,
+`tests/duplex-over-port-timeout.test.ts` and `tests/duplex-over-port-hostile.test.ts`.
+
+### Dependencies
 
-No runtime dependencies outside the workspace, no peer dependencies. ESM only
-(`"type": "module"`).
+One runtime dependency, `@statewalker/webrun-streams`: the `Duplex` / `Connect` / `Serve` types,
+the iterator primitives under the stream and RPC tiers (`sendIterator`, `recieveIterator`,
+`toChunks`), error serialisation, and the `ByteChannel` type for `byteChannelFromMessagePort`. No
+peer dependencies. The byte-transport codec lives in `@statewalker/webrun-msgpack`, so this package
+stays free of an encoder.
 
 ## License
 
-MIT © statewalker — see [LICENSE](../../LICENSE).
+MIT