@statewalker/webrun-streams-libp2p 0.6.0 → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -3,12 +3,18 @@
3
3
  ## What it is
4
4
 
5
5
  A libp2p adapter for the `Duplex` seam from `@statewalker/webrun-streams`.
6
- Each `call(input)` opens one new libp2p `Stream` with
7
- `node.dialProtocol(peer, [protocol])`; the serving side registers with
8
- `node.handle(protocol, …)` and runs a handler per inbound stream. The default
9
- protocol id is `/webrun-streams/1.0.0`. It targets libp2p 3.x. `serveConnections`
10
- additionally tells the handler which peer libp2p authenticated on the
11
- connection.
6
+ Each `call(input)` is one port of a windowed native port mux: one new libp2p
7
+ `Stream`, negotiating `<protocol>/ports/window`, over which `webrun-rpc`'s
8
+ stream tier runs the call. The serving side handles that protocol and runs a
9
+ handler per call. The default `protocol` is `/webrun-streams/1.0.0`. It targets
10
+ libp2p 3.x. `serveConnections` additionally tells the handler which peer libp2p
11
+ authenticated on the connection.
12
+
13
+ Releases up to 0.6.0 ran each call straight on a stream negotiating `protocol`
14
+ itself, with their own flow control. That protocol is **deprecated** and kept,
15
+ on both ends, for one release: a new server still answers old callers on it,
16
+ and a new caller falls back to it against an old server (see "Compatibility
17
+ with 0.6.0 and older").
12
18
 
13
19
  ## Why it exists
14
20
 
@@ -20,13 +26,25 @@ natively, there is no multiplexer on top: one call is one real libp2p stream.
20
26
 
21
27
  What the adapter adds on top of a raw stream:
22
28
 
23
- - **Error fidelity.** A yamux reset carries no message. An in-band `ERROR`
24
- frame carries the handler's `Error` with `message`, `stack` and custom
25
- fields.
26
- - **Backpressure** that follows libp2p 3.x's push-based `send()` / `'drain'`
27
- model, with a bound for peers that stop reading.
28
- - **Cancellation** in both directions: a caller's `.return()` resets the
29
- stream, and the handler's `finally` runs.
29
+ - **One flow control, bounded.** The port's credit window (default 4 MiB) is
30
+ the only flow control: up to a window is in flight per round trip, and a
31
+ producer never runs more than about a window ahead of a consumer that stopped
32
+ reading, whatever libp2p buffers (statewalker/webrun-wire#153). It is the
33
+ same stack every other `webrun-rpc` transport runs.
34
+ - **A bounded send-ahead, and a stall bound** (statewalker/webrun-wire#195). A
35
+ sender runs at most min(the peer's window, its own window) ahead, whatever
36
+ window the peer announces (up to 4 GiB), and writes nothing while the stream
37
+ needs to drain, so a peer that stops reading at the transport holds about one
38
+ frame of this end's memory. A write that has waited for drain longer than
39
+ `drainTimeoutMs` (default 5 minutes) resets the stream; a quiet call (an event
40
+ stream between events) is never timed out. Credit for the peer is held back
41
+ while the stream needs to drain too, and sent as one frame after it, so a peer
42
+ that uploads and never reads cannot grow the buffer with credit frames either;
43
+ it is dropped after the same timeout.
44
+ - **Error fidelity.** A handler's `Error` reaches the caller with `message`,
45
+ `stack` and custom fields.
46
+ - **Cancellation** in both directions: a caller's `.return()` ends the call at
47
+ once, and the handler's `finally` runs.
30
48
  - **A guard against a burst of calls on a fresh connection**, which would
31
49
  otherwise kill the connection's muxer.
32
50
  - **Caller identity** for the serving side, through `serveConnections`.
@@ -37,7 +55,9 @@ What the adapter adds on top of a raw stream:
37
55
  pnpm add @statewalker/webrun-streams-libp2p @libp2p/interface @multiformats/multiaddr
38
56
  ```
39
57
 
40
- Runtime dependency: `@statewalker/webrun-streams`. Peer dependencies:
58
+ Runtime dependencies: `@statewalker/webrun-streams`, `@statewalker/webrun-rpc`
59
+ (the port stack `connect`/`serve` run) and `@statewalker/webrun-msgpack` (the
60
+ calls' wire codec). Peer dependencies:
41
61
 
42
62
  | Peer | Range | Required |
43
63
  | --- | --- | --- |
@@ -51,19 +71,21 @@ runs (Node or browser).
51
71
 
52
72
  | Export | What it gives |
53
73
  | --- | --- |
54
- | `connect(params)` | `Connect<ConnectLibp2pParams>`. Resolves `{ call, close }` immediately (no dial yet). Each `call(input)` dials one stream. `close()` aborts every stream this `connect` still holds open. |
55
- | `serve(params, handler)` | `Serve<ServeLibp2pParams>`. `node.handle(protocol)`; runs `handler` per inbound stream. Resolves to an idempotent teardown that calls `node.unhandle(protocol)`. |
56
- | `serveConnections(params, makeHandler)` | Like `serve`, but `makeHandler(context)` is called once per inbound stream with `{ remotePeer }`, and returns that stream's `Duplex`. |
57
- | `duplexOverStream(stream, input, options?)` | The primitive under both: runs one call over one libp2p `Stream`. Returns an `AsyncGenerator<Uint8Array>` of the peer's bytes. |
58
- | `PeerGoneError` | What a call fails with when the stream ended before both sides finished it: the peer died, the connection dropped, or the stream was reset after the peer's side ended. `cause` is libp2p's close error, if any. |
74
+ | `connect(params)` | `Connect<ConnectLibp2pParams>`. Resolves `{ call, close }` immediately (no dial yet). Each `call(input)` opens one port (one stream). `close()` closes every port this `connect` still holds open. |
75
+ | `serve(params, handler)` | `Serve<ServeLibp2pParams>`. Handles `<protocol>/ports` (with and without `/window`) and, deprecated, `protocol`; runs `handler` per call. Resolves to an idempotent teardown that unhandles all of them. |
76
+ | `serveConnections(params, makeHandler)` | Like `serve`, but `makeHandler(context)` is called once per call with `{ remotePeer }`, and returns that call's `Duplex`. |
77
+ | `DEFAULT_WINDOW` | `4194304` (4 MiB), the port window `connect`/`serve` grant unless told otherwise. See "Sizing the window". |
78
+ | `portProtocolOf(protocol)` | `protocol + "/ports"`: what a call's stream negotiates (with `/window` appended between two windowed ends). |
79
+ | `DEFAULT_PROTOCOL` | `"/webrun-streams/1.0.0"`. |
80
+ | `duplexOverStream(stream, input, options?)` | **Deprecated.** The deprecated protocol's primitive: runs one call over one libp2p `Stream`. Removed in the next release. |
81
+ | `PeerGoneError` | What a call fails with when its stream ended before the call finished: the peer died, the connection dropped, or the stream was reset. `cause` is libp2p's close error, if any. |
59
82
  | `messageTargetOverStream(stream, options?)` | `{ target, signal }`: one stream as a pipe of `Uint8Array` messages for `multiplexPort` / `overPipe`, and an `AbortSignal` that aborts when the stream is over. `options.maxMessageBytes` caps one message. See below. |
60
- | `libp2pPortMux(options)` | Native MessagePorts: a `webrun-rpc` `PortMux` (by shape) whose every port is its own libp2p stream, for `overPorts`. `options`: `node`, `codec` (a value codec: `{ encode: serialize, decode: deserialize }` from `webrun-msgpack`), `peer` (to open ports), `onPort(port, { remotePeer, connection })` (to accept them), `protocol`, `maxMessageSize`, stream limits, `window`. The port lifecycle (codec wrapping, messages held until a port's first listener, close signals, accept/refuse, the caller's signal, close-all) is the shared `newNativePortMux` from `@statewalker/webrun-streams`; `describePortMux` (`webrun-streams-conformance`) is its contract, run against this transport too. Messages that arrive before a port's first listener are now held for it, as over WebRTC. See "MessagePorts over libp2p" below. |
83
+ | `libp2pPortMux(options)` | Native MessagePorts: a `webrun-rpc` `PortMux` (by shape) whose every port is its own libp2p stream, for `overPorts`; what `connect`/`serve` run on. `options`: `node`, `codec` (a value codec: `{ encode: serialize, decode: deserialize }` from `webrun-msgpack`), `peer` (to open ports), `onPort(port, { remotePeer, connection })` (to accept them), `protocol`, `maxMessageSize`, stream limits, `window`, `drainTimeoutMs` (default `DEFAULT_DRAIN_TIMEOUT_MS`). The port lifecycle (codec wrapping, messages held until a port's first listener, close signals, accept/refuse, the caller's signal, close-all) is the shared `newNativePortMux` from `@statewalker/webrun-streams`; `describePortMux` (`webrun-streams-conformance`) is its contract, run against this transport too. See "MessagePorts over libp2p" below. |
61
84
  | `DEFAULT_PORT_PROTOCOL`, `DEFAULT_PORT_MAX_MESSAGE_SIZE` | `"/webrun-ports/1.0.0"`, 256 KiB. |
62
- | `DEFAULT_PROTOCOL` | `"/webrun-streams/1.0.0"`. |
63
- | `DEFAULT_DRAIN_TIMEOUT_MS` | `300_000` (5 minutes). |
64
- | `DEFAULT_CLOSE_TIMEOUT_MS` | `300_000` (5 minutes), the bound on a graceful close. |
85
+ | `DEFAULT_DRAIN_TIMEOUT_MS` | `300_000` (5 minutes): how long a write waits for a stream to drain before the stream is reset (`drainTimeoutMs`). |
86
+ | `DEFAULT_CLOSE_TIMEOUT_MS` | **Deprecated** (the deprecated protocol only). `300_000` (5 minutes), the bound on a graceful close. |
65
87
  | `DEFAULT_MAX_MESSAGE_BYTES` | `67_108_864` (64 MiB), `messageTargetOverStream`'s cap on one message. |
66
- | `DEFAULT_MAX_FRAME_BYTES` | `67_108_864` (64 MiB), `duplexOverStream`'s default cap on one inbound frame's payload (`maxFrameBytes`). |
88
+ | `DEFAULT_MAX_FRAME_BYTES` | `67_108_864` (64 MiB), the default cap on one inbound frame (`maxFrameBytes`). |
67
89
  | `ConnectLibp2pParams`, `ServeLibp2pParams`, `ConnectionContext`, `ServeConnectionsHandler`, `DuplexOverStreamOptions` | Types, below. |
68
90
 
69
91
  `ConnectLibp2pParams`:
@@ -72,26 +94,34 @@ runs (Node or browser).
72
94
  | --- | --- | --- | --- |
73
95
  | `node` | `Libp2p` | required | The local node. Only `dialProtocol` is required; `getConnections` is used when present. |
74
96
  | `peer` | `PeerId \| Multiaddr` | required | Who to dial. |
75
- | `protocol` | `string` | `DEFAULT_PROTOCOL` | Protocol id. |
76
- | `drainTimeoutMs` | `number` | `300_000` | How long a backpressured send waits for `'drain'`. |
77
- | `maxFrameBytes` | `number` | `DEFAULT_MAX_FRAME_BYTES` | The largest frame payload accepted from the peer. Past it, or on a malformed frame length, the call fails and the stream is aborted. |
97
+ | `protocol` | `string` | `DEFAULT_PROTOCOL` | The protocol id both ends are configured with. Calls negotiate `portProtocolOf(protocol)`; `protocol` itself is the deprecated fallback. |
98
+ | `window` | `number` | `DEFAULT_WINDOW` (4 MiB) | The port window in bytes, at least 64 KiB: the most this end holds of a response delivered and not yet read, and the most it sends ahead of the server (min of both ends' windows). See "Sizing the window". |
99
+ | `timeout` | `number` | none | Per-call inactivity timeout in ms, reset by any chunk in either direction. Unset, a slow consumer is throttled, never failed. |
100
+ | `maxFrameBytes` | `number` | `DEFAULT_MAX_FRAME_BYTES` | The largest frame accepted from the peer. Past it, or on a malformed frame length, the call fails and the stream is aborted. |
78
101
  | `maxOutboundStreams` | `number` | libp2p's (64) | Passed to `dialProtocol`. |
79
102
  | `runOnLimitedConnection` | `boolean` | unset | Passed to `dialProtocol`. Allows relayed or otherwise limited connections. |
103
+ | `drainTimeoutMs` | `number` | `DEFAULT_DRAIN_TIMEOUT_MS` (5 min) | How long a write (or credit for the peer's upload) may wait for the stream to drain before the stream is reset and the call fails. Only what is held back for drain counts. Both protocols; on the port protocol 0 or `Infinity` means no bound (the deprecated protocol drops at once on 0). |
104
+ | `readHighWaterBytes` | `number` | 64 KiB | **Deprecated**: the deprecated protocol only (an older server). |
80
105
 
81
- `ServeLibp2pParams`: `node`, `protocol`, `drainTimeoutMs`, `maxFrameBytes`,
106
+ `ServeLibp2pParams`: `node`, `protocol`, `window`, `timeout`, `maxFrameBytes`,
82
107
  `maxOutboundStreams` and `runOnLimitedConnection` as above (passed to
83
- `node.handle`), plus `maxInboundStreams` (libp2p default 32).
108
+ `node.handle` for each served protocol), plus `maxInboundStreams` (libp2p
109
+ default 32), `drainTimeoutMs` as above (a stalled caller is dropped after it),
110
+ and the deprecated `readHighWaterBytes` (older callers only). The server's
111
+ `window` bounds what a call sends ahead of the handler, and what a response
112
+ runs ahead of its caller, whatever window the caller announces.
84
113
 
85
114
  `ConnectionContext`: `{ remotePeer: PeerId }`.
86
115
  `ServeConnectionsHandler`: `(context: ConnectionContext) => Duplex`.
87
116
 
88
- `DuplexOverStreamOptions`:
117
+ `DuplexOverStreamOptions` (**deprecated**, with `duplexOverStream`):
89
118
 
90
119
  | Field | Meaning |
91
120
  | --- | --- |
92
- | `onPeerInputEnd?(err?)` | Called once when the peer's side ends: closed, `ERROR` frame (passed as `err`) or torn down. `serveConnections` uses it to end the handler's input. |
93
- | `onSourceCompleted?()` | Called only when the peer's side ended normally. `connect` uses it to choose a graceful close over an abort. |
94
- | `drainTimeoutMs?` | As above. |
121
+ | `onPeerInputEnd?(err?)` | Called once when the peer's side ends: closed, `ERROR` frame (passed as `err`) or torn down. |
122
+ | `onSourceCompleted?()` | Called only when the peer's side ended normally. |
123
+ | `drainTimeoutMs?` | How long a backpressured send waits for `'drain'`. |
124
+ | `readHighWaterBytes?` | Received bytes held for a consumer that is not reading before the stream is paused. |
95
125
  | `maxFrameBytes?` | As above. |
96
126
 
97
127
  ## Examples
@@ -160,7 +190,85 @@ const { call } = await connect({ node, peer, protocol: "/my-app/1.0.0", maxOutbo
160
190
 
161
191
  ## Internals
162
192
 
163
- ### Frames on the stream
193
+ ### A call is a port
194
+
195
+ `connect` builds a `libp2pPortMux` for `portProtocolOf(protocol)` with
196
+ `window` (default `DEFAULT_WINDOW`) and hands it to `webrun-rpc`'s `connect`
197
+ through `overPorts`; `serve` does the same with `webrun-rpc`'s `serve`. So one
198
+ call is one port, one port is one libp2p stream, and the stream tier
199
+ (`duplexOverPort`) runs the call: its chunks (at most 256 KiB each) go as
200
+ msgpack messages, pipelined up to the peer's window, and the window's credit
201
+ is their confirmation. yamux still multiplexes the streams, but its windows no
202
+ longer bound anything this package promises: the port's credit bounds what is
203
+ in flight per call. There is no flow control of this package's own any more;
204
+ the bespoke yamux pause/resume run-ahead bound of the deprecated protocol goes
205
+ with it in the next release.
206
+
207
+ Both ends of a call between two releases from this one on always run the
208
+ window, so a call's stream negotiates `<protocol>/ports/window`; the mux also
209
+ serves (and dials, second) `<protocol>/ports`, unwindowed.
210
+
211
+ ### Sizing the window
212
+
213
+ A call moves at most one window per round trip, so its throughput is capped at
214
+ `window / RTT`, and a producer runs at most about one window (plus a chunk at
215
+ each end) ahead of a consumer that stopped reading. Size it at least to the
216
+ link's bandwidth-delay product:
217
+
218
+ | Link | BDP | Window |
219
+ | --- | --- | --- |
220
+ | LAN, 1 Gbit/s at 1 ms | 125 KB | the 64 KiB floor would cap it; 1 MiB is ample |
221
+ | 70 Mbit/s at 11 ms | 96 KB | 1 MiB |
222
+ | 200 Mbit/s at 100 ms | 2.5 MB | the 4 MiB default |
223
+ | 1 Gbit/s at 100 ms | 12.5 MB | 16 MiB |
224
+
225
+ Measured over an emulated 100 ms / 200 Mbit/s link (statewalker/webrun-wire#153):
226
+ a 1 MiB window capped a 16 MiB echo at 7.4 MiB/s, the 4 MiB window reached
227
+ 15 MiB/s, as fast as the deprecated protocol. Far above the bottleneck's queue a
228
+ window only adds latency (bufferbloat): on an 11 ms link 4 MiB was slower than
229
+ 1 MiB. Both ends set their own window: the caller's bounds the response, the
230
+ server's the request. Memory per call is bounded by the window, so a server
231
+ with many concurrent calls may want a smaller one.
232
+
233
+ ### Compatibility with 0.6.0 and older
234
+
235
+ Deprecated shims, on both ends, for one release; removed in the next one:
236
+
237
+ - **New server, old caller.** `serve`/`serveConnections` also handle
238
+ `protocol` itself with the deprecated protocol (`legacy-connect-serve.ts`),
239
+ so an old `connect` keeps working.
240
+ - **New caller, old server.** An old server refuses `<protocol>/ports…`
241
+ (libp2p's `UnsupportedProtocolError`, before any of the call's input is
242
+ read), and the call runs on `protocol` instead. The node remembers the
243
+ refusal per peer and protocol for that connection, so later calls, from any
244
+ `connect()` on the node, dial `protocol` directly; a new connection (the peer
245
+ restarted, perhaps upgraded) is probed again. The first call to an old server
246
+ costs one extra protocol negotiation.
247
+
248
+ `tests/interop-0-6.test.ts` runs the conformance suite (L0–L6) and the cases
249
+ above against the published 0.6.0 in both directions.
250
+
251
+ Behaviour that differs from the deprecated protocol:
252
+
253
+ - **A call ends with the peer's output.** When the handler's output ends, the
254
+ call ends: input the caller has not sent yet is abandoned, and a handler
255
+ still reading its input is told the caller abandoned the stream. The
256
+ deprecated protocol kept sending until the input ended too.
257
+ - **The drain timeout counts only a blocked write.** A peer that stops
258
+ consuming holds at most a window per call (its credit stops); one that stops
259
+ reading at the transport holds about one frame, and is dropped after
260
+ `drainTimeoutMs`. Set `timeout` to fail idle calls. `readHighWaterBytes`
261
+ applies to the deprecated protocol only.
262
+ - **Chunks.** A response arrives in chunks of up to 256 KiB (64 KiB before).
263
+ - **Failures on the serving side are not logged**: they reach the handler
264
+ (its input throws) and the caller.
265
+
266
+ ### The deprecated protocol
267
+
268
+ The sections below describe the deprecated protocol, which `serve` still
269
+ answers and `connect` falls back to until the next release.
270
+
271
+ #### Frames on the stream
164
272
 
165
273
  ```
166
274
  +--------+-----------------+-----------------+
@@ -190,7 +298,7 @@ or `webrun-streams-libp2p: a malformed frame length`, and aborts the stream:
190
298
  a peer not speaking this framing would otherwise make the receiver buffer
191
299
  without bound. On the serving side the handler's input throws that error.
192
300
 
193
- ### Why identity reaches the handler by closure
301
+ #### Why identity reaches the handler by closure
194
302
 
195
303
  `Duplex` is bytes-only, so `serveConnections` passes identity to a factory
196
304
  instead of to the handler. `remotePeer` is `connection.remotePeer`, the peer id
@@ -201,7 +309,7 @@ inside it. Reusing one handler built outside it for every connection is how
201
309
  identity-by-closure gets broken. `serve` is `serveConnections` with the context
202
310
  ignored, so both share framing, teardown and failure handling.
203
311
 
204
- ### Why sends wait for the `'drain'` event
312
+ #### Why sends wait for the `'drain'` event
205
313
 
206
314
  libp2p 3.x streams are push-based: `stream.send(chunk)` returns `false` when
207
315
  the write buffer is full, and the stream emits `'drain'` when it can take
@@ -212,7 +320,7 @@ so after the first backpressure cycle it resolves immediately while the buffer
212
320
  is still full, and a write loop built on it fills the buffer without bound.
213
321
  `tests/backpressure.test.ts` covers this.
214
322
 
215
- ### Why both timeouts are minutes, not seconds
323
+ #### Why both timeouts are minutes, not seconds
216
324
 
217
325
  - **Drain timeout** (`DEFAULT_DRAIN_TIMEOUT_MS`, 5 minutes, `drainTimeoutMs`
218
326
  per call site). A peer that requests something and then stops reading,
@@ -233,36 +341,7 @@ is still full, and a write loop built on it fills the buffer without bound.
233
341
  `[webrun-streams-libp2p] closeStream: graceful close of protocol <p> failed (bound <ms>ms), aborting instead (peer may see truncated data): <reason>`.
234
342
  The close timeout is not configurable through `connect` / `serve` params.
235
343
 
236
- ### Why a burst of calls is serialised on a fresh connection
237
-
238
- With no connection to the peer yet, every call dials and they all share the
239
- one connection libp2p establishes. Their streams can reach the remote while it
240
- is still upgrading that connection. yamux counts those as early streams and,
241
- past `maxEarlyStreams` (10 by default), aborts the whole muxer: every stream
242
- on the connection dies, the remote sees EOF during protocol negotiation, and
243
- this side sees `StreamResetError`. Raising the limit on your own nodes would
244
- not help against other peers.
245
-
246
- So until one stream has negotiated its protocol on an open connection, calls
247
- open their streams one at a time; after that they open concurrently. If the
248
- proven connection closes, the next burst is gated again (this re-check needs
249
- `node.getConnections`; a node that offers only `dialProtocol` stays proven
250
- after its first stream). The state is shared by every `connect()` to the same
251
- peer from the same node, because callers often `connect()` per request.
252
-
253
- ### Stream limits
254
-
255
- libp2p caps the number of open streams for one protocol per connection, and
256
- past the cap a new stream is reset, not queued. One call is one stream, so a
257
- caller with more concurrent calls than the cap sees calls rejected with no
258
- other symptom. `maxInboundStreams`, `maxOutboundStreams` and
259
- `runOnLimitedConnection` are passed through unchanged; an unset option is left
260
- out of the options object so libp2p's own default applies (inbound 32,
261
- outbound 64, limited connections refused). `tests/stream-limits.test.ts`
262
- checks both that a raised `maxInboundStreams` admits more than 32 concurrent
263
- streams and that an unconfigured server stops at 32.
264
-
265
- ### How calls end
344
+ #### How calls end
266
345
 
267
346
  - **Normal end.** Both sides finished: the stream is closed gracefully,
268
347
  bounded by the close timeout.
@@ -300,14 +379,43 @@ streams and that an unconfigured server stops at 32.
300
379
  A caller that sent its whole request and then stopped reading the response
301
380
  (`.return()` mid-stream) is ordinary and is not logged.
302
381
 
382
+ ### Why a burst of calls is serialised on a fresh connection
383
+
384
+ With no connection to the peer yet, every call dials and they all share the
385
+ one connection libp2p establishes. Their streams can reach the remote while it
386
+ is still upgrading that connection. yamux counts those as early streams and,
387
+ past `maxEarlyStreams` (10 by default), aborts the whole muxer: every stream
388
+ on the connection dies, the remote sees EOF during protocol negotiation, and
389
+ this side sees `StreamResetError`. Raising the limit on your own nodes would
390
+ not help against other peers.
391
+
392
+ So until one stream has negotiated its protocol on an open connection, calls
393
+ open their streams one at a time; after that they open concurrently. If the
394
+ proven connection closes, the next burst is gated again (this re-check needs
395
+ `node.getConnections`; a node that offers only `dialProtocol` stays proven
396
+ after its first stream). The state is shared by every `connect()` to the same
397
+ peer from the same node, because callers often `connect()` per request.
398
+
399
+ ### Stream limits
400
+
401
+ libp2p caps the number of open streams for one protocol per connection, and
402
+ past the cap a new stream is reset, not queued. One call is one stream, so a
403
+ caller with more concurrent calls than the cap sees calls rejected with no
404
+ other symptom. `maxInboundStreams`, `maxOutboundStreams` and
405
+ `runOnLimitedConnection` are passed through unchanged; an unset option is left
406
+ out of the options object so libp2p's own default applies (inbound 32,
407
+ outbound 64, limited connections refused). `tests/stream-limits.test.ts`
408
+ checks both that a raised `maxInboundStreams` admits more than 32 concurrent
409
+ streams and that an unconfigured server stops at 32.
410
+
303
411
  ### MessagePorts over libp2p, and the port stack on them
304
412
 
305
- `connect` / `serve` above stream each call's bytes straight onto a libp2p
306
- stream, and so inherit libp2p's buffering: a consumer that stops reading does
307
- not slow its producer (see Tests, L6). `webrun-rpc`'s port stack does: each
308
- call's chunk waits for the peer's confirmation that its consumer pulled the
309
- last one, so a producer is never more than a chunk ahead, whatever the
310
- transport buffers underneath. Two ways to put libp2p under it:
413
+ `connect` / `serve` above are the first of the two ways below, with a window
414
+ and msgpack set for you. Use the port mux directly to choose the codec, the
415
+ chunk size or the multiplexing, or to put other port users on the same node.
416
+ `webrun-rpc`'s port stack bounds a producer to its consumer whatever the
417
+ transport buffers underneath: each chunk waits for the peer's confirmation, or,
418
+ on a windowed port, for the window's credit. Two ways to put libp2p under it:
311
419
 
312
420
  ```ts
313
421
  import { deserialize, msgpackCodec, serialize } from "@statewalker/webrun-msgpack";
@@ -349,8 +457,8 @@ run against it (`tests/port-window.test.ts`).
349
457
 
350
458
  Each native port carries `closeSignal`, aborted when its stream ends, the peer
351
459
  goes, or the port is closed here; `webrun-rpc`'s `getPortCloseSignal` reads it
352
- from the port, so a call on a dead stream fails instead of waiting, and this
353
- package still imports nothing from `webrun-rpc`. Ports are opened through the
460
+ from the port, so a call on a dead stream fails instead of waiting, and
461
+ `libp2pPortMux` itself imports nothing from `webrun-rpc`. Ports are opened through the
354
462
  same early-stream gate as `connect()`. A port `onPort` refuses (returns
355
463
  `false`) is aborted: the opener's signal aborts with `PeerGoneError` and a call
356
464
  on it fails. A frame the port's codec cannot decode (a peer speaking another
@@ -401,6 +509,8 @@ reader buffer without bound. Raise it with
401
509
 
402
510
  ### Constraints
403
511
 
512
+ The two below concern the deprecated protocol.
513
+
404
514
  - On the serving side, request bytes are queued for the handler without a
405
515
  bound; backpressure applies to the handler's output, not to its input.
406
516
  - `duplexOverStream` must start reading the stream without an intervening
@@ -416,9 +526,19 @@ its connection in-process and SIGKILLing a forked server
416
526
  (`tests/fixtures/greeting-server.ts`, run with `tsx`), with 100 open channels
417
527
  each; every channel must fail with an error within 1 s. The shared conformance
418
528
  suite (`tests/conformance.test.ts`, about 7 s) runs in the same `pnpm test`, with
419
- `skipHugeBody`.
420
-
421
- **Run-ahead is bounded for `connect` / `serve`** (spec D17, L6;
529
+ `skipHugeBody`, for `connect`/`serve` and for the deprecated protocol on both
530
+ ends.
531
+
532
+ **`connect`/`serve` over the windowed port mux** (`tests/connect-over-ports.test.ts`):
533
+ the protocol ids negotiated, the 4 MiB default window and a 1 MiB `window`
534
+ option holding a producer to the window (L6, in both directions, over yamux's
535
+ 16 MiB stream window), identity per call, and the window floor.
536
+ **Interop** (`tests/interop-0-6.test.ts`): the conformance suite L0–L6 and the
537
+ fallback cases between this release and the published 0.6.0
538
+ (`webrun-streams-libp2p-0-6`, an npm alias), old caller to new server and new
539
+ caller to old server.
540
+
541
+ **Run-ahead is bounded for the deprecated protocol** (spec D17, L6;
422
542
  `tests/run-ahead.test.ts`, always on). L6 first found none: a consumer that
423
543
  stopped reading let the producer run 22-24 MiB ahead until libp2p's 4 MiB read
424
544
  buffer killed the stream. Two things buffered without limit:
@@ -487,13 +607,16 @@ the signal never aborted.
487
607
 
488
608
  ### Dependencies
489
609
 
490
- - `@statewalker/webrun-streams` (`workspace:^`): the seam types and
491
- `serializeError` / `deserializeError`.
610
+ - `@statewalker/webrun-streams` (`workspace:^`): the seam types, the native
611
+ port mux and `serializeError` / `deserializeError`.
612
+ - `@statewalker/webrun-rpc` (`workspace:^`): the port stack `connect`/`serve`
613
+ run (`connect`, `serve`, `overPorts`).
614
+ - `@statewalker/webrun-msgpack` (`workspace:^`): the calls' value codec.
492
615
  - `@libp2p/interface`, `@multiformats/multiaddr` (peers, types only) and
493
616
  `libp2p` (optional peer). Dev dependencies `@chainsafe/libp2p-noise`,
494
617
  `@chainsafe/libp2p-yamux`, `@libp2p/tcp` and `@libp2p/utils` build the test
495
- nodes; `@statewalker/webrun-rpc` and `@statewalker/webrun-msgpack` run the
496
- multiplexer tests, and `tsx` runs the forked server.
618
+ nodes, `webrun-streams-libp2p-0-6` (the published 0.6.0) is the old peer of
619
+ the interop tests, and `tsx` runs the forked server.
497
620
 
498
621
  ## License
499
622