@statewalker/webrun-streams-libp2p 0.1.6 → 0.1.8

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.
Files changed (2) hide show
  1. package/README.md +252 -116
  2. package/package.json +11 -7
package/README.md CHANGED
@@ -1,158 +1,294 @@
1
1
  # @statewalker/webrun-streams-libp2p
2
2
 
3
- libp2p native multi-stream `Connect` / `Serve` adapter. Each `call(input)` opens a new libp2p `Stream` via `node.dialProtocol(peer, [protocol])`; the responder registers via `node.handle(protocol, ...)`. Default protocol id: `/webrun-streams/1.0.0`. Targets libp2p 3.x.
3
+ ## What it is
4
4
 
5
- ## Why it exists
6
-
7
- libp2p already solves the hard parts of peer-to-peer — transport negotiation,
8
- NAT traversal, circuit relaying, and an authenticated peer identity from the
9
- Noise handshake. What it hands an application is a `Stream`, not a request.
10
-
11
- This adapter binds that stream to the [`webrun-streams`](../webrun-streams)
12
- `Duplex` seam, so a handler written for a `MessagePort` or a WebSocket runs
13
- unchanged across a libp2p network. Because libp2p multiplexes natively, this
14
- adapter is one of two in the family (with
15
- [`webrun-streams-webrtc`](../webrun-streams-webrtc)) that needs no `emulateMux`
16
- — one `call` is one real libp2p stream.
17
-
18
- ## Install
19
-
20
- ```sh
21
- npm install @statewalker/webrun-streams-libp2p libp2p @libp2p/interface @multiformats/multiaddr
22
- ```
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.
23
12
 
24
- `libp2p` (`^3.0.0`), `@libp2p/interface` (`^3.0.0`) and `@multiformats/multiaddr`
25
- (`^13.0.0`) are **peer dependencies** — you build and own the node, including
26
- its transports, encryption and muxers.
27
-
28
- ## Getting started
13
+ ## Why it exists
29
14
 
30
- ```ts
31
- import { connect, serve } from "@statewalker/webrun-streams-libp2p";
15
+ libp2p solves transport negotiation, NAT traversal, relaying and authenticated
16
+ peer identity. What it gives an application is a `Stream`, not a request. This
17
+ adapter binds a stream to the `Duplex` shape, so a handler written once runs
18
+ over libp2p as it does over any other adapter. Because libp2p multiplexes
19
+ natively, there is no `emulateMux`: one call is one real libp2p stream.
32
20
 
33
- const { call, close } = await connect({ node, peer, protocol: "/my-app/1.0.0" });
34
- const stop = await serve({ node, protocol: "/my-app/1.0.0" }, handler);
35
- ```
21
+ What the adapter adds on top of a raw stream:
36
22
 
37
- ## Knowing who is calling
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.
30
+ - **A guard against a burst of calls on a fresh connection**, which would
31
+ otherwise kill the connection's muxer.
32
+ - **Caller identity** for the serving side, through `serveConnections`.
38
33
 
39
- `Duplex` is bytes-only and gains no new parameter, so the serving side exposes identity through a separate entry point: `serveConnections` builds a handler **per inbound stream** and hands it the connection libp2p authenticated.
34
+ ## How to use
40
35
 
41
- ```ts
42
- import { serveConnections } from "@statewalker/webrun-streams-libp2p";
43
-
44
- const stop = await serveConnections({ node }, (context) => {
45
- const who = context.remotePeer; // PeerId, from the Noise handshake
46
- return async function* handler(input) {
47
- for await (const chunk of input) yield respondTo(who, chunk);
48
- };
49
- });
36
+ ```sh
37
+ pnpm add @statewalker/webrun-streams-libp2p @libp2p/interface @multiformats/multiaddr
50
38
  ```
51
39
 
52
- `context.remotePeer` is `connection.remotePeer` — the peer id libp2p proved when the connection was encrypted. It is the one identity claim on the serving side a request payload cannot forge, and it reaches the handler by closure rather than by argument, so no caller can influence it. Build any per-peer state inside `makeHandler`, not outside it: the function runs once per stream, and reusing one handler for every connection is exactly how identity-by-closure gets broken.
40
+ Runtime dependency: `@statewalker/webrun-streams`. Peer dependencies:
53
41
 
54
- `serve` is `serveConnections` with the context ignored, so both share the same framing, teardown and failure handling.
55
-
56
- ## Stream limits
57
-
58
- libp2p caps how many streams for one protocol may be open at once **per connection**, and past the cap a new stream is reset rather than queued. This adapter opens one stream per `call`, so a caller with more concurrent requests than the cap starts seeing rejected calls with no other symptom. The three knobs below are passed straight through to `node.dialProtocol` / `node.handle` — this package sets no defaults of its own, and an option left unset is omitted from the options object entirely so libp2p's own default applies.
59
-
60
- | Option | On | libp2p default (3.3.8) |
42
+ | Peer | Range | Required |
61
43
  | --- | --- | --- |
62
- | `maxInboundStreams` | `serve` / `serveConnections` | **32** |
63
- | `maxOutboundStreams` | `connect`, `serve` / `serveConnections` | **64** |
64
- | `runOnLimitedConnection` | `connect`, `serve` / `serveConnections` | unset — libp2p refuses this protocol on a limited connection |
65
-
66
- ```ts
67
- const stop = await serve({ node, maxInboundStreams: 128 }, handler);
68
- const { call } = await connect({ node, peer, maxOutboundStreams: 128 });
69
- ```
44
+ | `@libp2p/interface` | `^3.0.0` | yes (types: `Libp2p`, `PeerId`, `Stream`, `Connection`) |
45
+ | `@multiformats/multiaddr` | `^13.0.0` | yes (type: `Multiaddr` dial targets) |
46
+ | `libp2p` | `^3.0.0` | optional; you build and own the node, with its transports, encryption and muxers |
47
+
48
+ Both required peers are used for types only; at runtime the package calls the
49
+ node you pass in. One entry point, `.`. It runs wherever your libp2p node
50
+ runs (Node or browser).
51
+
52
+ | Export | What it gives |
53
+ | --- | --- |
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
+ | `DEFAULT_PROTOCOL` | `"/webrun-streams/1.0.0"`. |
59
+ | `DEFAULT_DRAIN_TIMEOUT_MS` | `300_000` (5 minutes). |
60
+ | `DEFAULT_CLOSE_TIMEOUT_MS` | `300_000` (5 minutes), the bound on a graceful close. |
61
+ | `ConnectLibp2pParams`, `ServeLibp2pParams`, `ConnectionContext`, `ServeConnectionsHandler`, `DuplexOverStreamOptions` | Types, below. |
62
+
63
+ `ConnectLibp2pParams`:
70
64
 
71
- `runOnLimitedConnection` opts in to running over a connection with limits on how much data can be transferred or how long it can stay open — a relayed circuit being the usual case. This package does not decide that trade-off for you; it only exposes the knob. `tests/stream-limits.test.ts` pins both halves: a raised `maxInboundStreams` really does admit more than 32 concurrent streams, and an unconfigured server still stops at exactly 32.
72
-
73
- ## Framing
65
+ | Field | Type | Default | Meaning |
66
+ | --- | --- | --- | --- |
67
+ | `node` | `Libp2p` | required | The local node. Only `dialProtocol` is required; `getConnections` is used when present. |
68
+ | `peer` | `PeerId \| Multiaddr` | required | Who to dial. |
69
+ | `protocol` | `string` | `DEFAULT_PROTOCOL` | Protocol id. |
70
+ | `drainTimeoutMs` | `number` | `300_000` | How long a backpressured send waits for `'drain'`. |
71
+ | `maxOutboundStreams` | `number` | libp2p's (64) | Passed to `dialProtocol`. |
72
+ | `runOnLimitedConnection` | `boolean` | unset | Passed to `dialProtocol`. Allows relayed or otherwise limited connections. |
74
73
 
75
- The adapter puts a small frame on top of the libp2p stream:
74
+ `ServeLibp2pParams`: `node`, `protocol`, `drainTimeoutMs`,
75
+ `maxOutboundStreams` and `runOnLimitedConnection` as above (passed to
76
+ `node.handle`), plus `maxInboundStreams` (libp2p default 32).
76
77
 
77
- [type:1][length:varint][payload]
78
+ `ConnectionContext`: `{ remotePeer: PeerId }`.
79
+ `ServeConnectionsHandler`: `(context: ConnectionContext) => Duplex`.
78
80
 
79
- `DATA` (`0x00`) carries body bytes; `ERROR` (`0x02`) carries a JSON-serialised `Error`. The error frame exists because yamux's native `StreamResetError` discards the message — without it, a handler that throws reaches the caller as an anonymous reset. Normal end-of-input is libp2p's own `close()`, not a frame.
81
+ `DuplexOverStreamOptions`:
80
82
 
81
- ## Flow control, and what libp2p 3.x does not give you for free
83
+ | Field | Meaning |
84
+ | --- | --- |
85
+ | `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. |
86
+ | `onSourceCompleted?()` | Called only when the peer's side ended normally. `connect` uses it to choose a graceful close over an abort. |
87
+ | `drainTimeoutMs?` | As above. |
82
88
 
83
- libp2p 3.x streams are **push-based**: `stream.send(chunk)` returns `false` when the write buffer is full, and the stream emits `'drain'` when it can take more. (2.x's pull-based `sink(AsyncIterable)` is gone, and with it the illusion that yamux's credit window applies backpressure to a source on its own.) The outbound pump therefore honours `send()`'s return value and waits for the real `'drain'` event.
89
+ ## Examples
84
90
 
85
- It deliberately does **not** use `stream.onDrain()`: that method memoises one promise for the stream's whole lifetime and never clears it (`@libp2p/utils@7.3.2`), so past the first backpressure cycle it resolves immediately while the buffer is still full — a write loop built on it floods the buffer without bound. `tests/backpressure.test.ts` is a regression test for exactly that.
91
+ ### Serve and call between two nodes
86
92
 
87
- Two bounds keep a misbehaving peer from parking a long-lived server:
93
+ ```ts
94
+ import { noise } from "@chainsafe/libp2p-noise";
95
+ import { yamux } from "@chainsafe/libp2p-yamux";
96
+ import { tcp } from "@libp2p/tcp";
97
+ import { collectBytes } from "@statewalker/webrun-streams";
98
+ import { connect, serve } from "@statewalker/webrun-streams-libp2p";
99
+ import { createLibp2p } from "libp2p";
88
100
 
89
- - **Drain timeout** — `DEFAULT_DRAIN_TIMEOUT_MS` (5 minutes), overridable per connection via `drainTimeoutMs` on `connect`/`serve`/`serveConnections` params. A peer that requests something and then stops reading, without closing or resetting, produces no event at all; unbounded, it parks the serving side's pump, the handler and everything buffered behind it forever. The bound is generous on purpose — resetting a slow-but-alive peer is the thing backpressure exists to avoid — and expiry is logged, then unwound by aborting the stream.
90
- - **Close timeout** — 5 s (2.x's own `DEFAULT_SEND_CLOSE_WRITE_TIMEOUT`) around the graceful `stream.close()`, falling back to `abort()`. Because the pump awaits drain before every `send()`, at most the final chunk is outstanding at close time. A trip is logged, including that the peer may see truncated data.
101
+ const options = { transports: [tcp()], connectionEncrypters: [noise()], streamMuxers: [yamux()] };
102
+ const server = await createLibp2p({ ...options, addresses: { listen: ["/ip4/127.0.0.1/tcp/0"] } });
103
+ const client = await createLibp2p(options);
91
104
 
92
- ## Failure handling
105
+ const stop = await serve({ node: server }, async function* echo(input) {
106
+ for await (const chunk of input) yield chunk;
107
+ });
93
108
 
94
- One inbound stream failing never takes down the serving process. `duplexOverStream` rejects on the read side when a peer sends an `ERROR` frame or resets mid-request — which happens in ordinary use, a browser tab closed mid-request being enough — and `serveConnections` catches that per stream and logs it. Callers see their own errors as usual: cancelling a `call` (i.e. `.return()` on the returned generator) sends a reset, and `close()` on the connection aborts every stream it still holds open.
109
+ const { call, close } = await connect({ node: client, peer: server.getMultiaddrs()[0] });
110
+ const reply = await collectBytes(call([new TextEncoder().encode("ping")]));
111
+ console.log(new TextDecoder().decode(reply)); // "ping"
95
112
 
96
- ## API
113
+ await close();
114
+ await stop();
115
+ await client.stop();
116
+ await server.stop();
117
+ ```
97
118
 
98
- | Export | Kind | Purpose |
99
- | --- | --- | --- |
100
- | `connect(params)` | `Connect<ConnectLibp2pParams>` | Dials `peer` and resolves `{ call, close }`. Each `call` opens one libp2p stream. |
101
- | `serve(params, handler)` | `Serve<ServeLibp2pParams>` | Registers `handler` on `protocol`. Returns an idempotent teardown. |
102
- | `serveConnections(params, makeHandler)` | function | Like `serve`, but builds a handler per inbound stream and passes it the authenticated `ConnectionContext`. |
103
- | `ServeConnectionsHandler` | type | `(context: ConnectionContext) => Duplex` — the factory `serveConnections` takes. |
104
- | `duplexOverStream(stream, options?)` | function | Wraps one libp2p `Stream` as a `Duplex`, applying the framing and flow control described above. |
105
- | `closeStream(stream, ...)` | function | The graceful-close-then-abort sequence, with the 5 s close timeout. |
106
- | `DEFAULT_PROTOCOL` | const | `"/webrun-streams/1.0.0"` — used when `protocol` is unset. |
107
- | `DEFAULT_DRAIN_TIMEOUT_MS` | const | `300_000` — the default drain bound (5 minutes). |
119
+ ### Knowing who is calling
108
120
 
109
- ### `ConnectLibp2pParams`
121
+ ```ts
122
+ import { serveConnections } from "@statewalker/webrun-streams-libp2p";
123
+ import type { Libp2p } from "@libp2p/interface";
110
124
 
111
- | Field | Type | Default | Meaning |
112
- | --- | --- | --- | --- |
113
- | `node` | `Libp2p` | — | The local node. |
114
- | `peer` | `PeerId \| Multiaddr` | — | Who to dial. |
115
- | `protocol` | `string` | `DEFAULT_PROTOCOL` | libp2p protocol id. |
116
- | `drainTimeoutMs` | `number` | `300_000` | Backpressure drain bound before dropping the peer. |
117
- | `maxOutboundStreams` | `number` | libp2p's (64) | Passed through to `dialProtocol`. |
118
- | `runOnLimitedConnection` | `boolean` | unset | Opt in to relayed / limited connections. |
125
+ declare const node: Libp2p;
119
126
 
120
- ### `ServeLibp2pParams`
127
+ const stop = await serveConnections({ node }, ({ remotePeer }) => {
128
+ const who = remotePeer.toString(); // proven by the connection's encryption handshake
129
+ return async function* handler(input) {
130
+ for await (const _ of input) {
131
+ /* read the request */
132
+ }
133
+ yield new TextEncoder().encode(`hello ${who}`);
134
+ };
135
+ });
136
+ ```
121
137
 
122
- As above minus `peer`, plus `maxInboundStreams` (libp2p default **32**).
138
+ ### Raising stream limits
123
139
 
124
- ### `ConnectionContext`
140
+ ```ts
141
+ import { connect, serve } from "@statewalker/webrun-streams-libp2p";
142
+ import type { Libp2p, PeerId } from "@libp2p/interface";
143
+ import type { Duplex } from "@statewalker/webrun-streams";
125
144
 
126
- | Field | Type | Meaning |
127
- | --- | --- | --- |
128
- | `remotePeer` | `PeerId` | The peer id proved by the Noise handshake. Unforgeable by the request payload. |
145
+ declare const node: Libp2p;
146
+ declare const peer: PeerId;
147
+ declare const handler: Duplex;
129
148
 
130
- ### `DuplexOverStreamOptions`
149
+ const stop = await serve({ node, protocol: "/my-app/1.0.0", maxInboundStreams: 128 }, handler);
150
+ const { call } = await connect({ node, peer, protocol: "/my-app/1.0.0", maxOutboundStreams: 128 });
151
+ ```
131
152
 
132
- `onPeerInputEnd(err?)`, `onSourceCompleted()` and `drainTimeoutMs` — see
133
- [Flow control](#flow-control-and-what-libp2p-3x-does-not-give-you-for-free).
153
+ ## Internals
134
154
 
135
- ## Tests
155
+ ### Frames on the stream
136
156
 
137
- ```bash
138
- pnpm test # backpressure, drain timeout, identity, resilience
139
- WEBRUN_STREAMS_LIBP2P=1 pnpm test # + the framing/conformance suite
140
157
  ```
158
+ +--------+-----------------+-----------------+
159
+ | type | length | payload |
160
+ | 1 byte | varint (LEB128) | length bytes |
161
+ +--------+-----------------+-----------------+
141
162
 
142
- The conformance suite is opt-in because it spins up two real libp2p TCP nodes in-process.
143
-
144
- ## Dependencies
145
-
146
- | Dependency | Kind | Why |
147
- | --- | --- | --- |
148
- | [`@statewalker/webrun-streams`](../webrun-streams) | runtime | The `Duplex` seam and error serialisation. |
149
- | `libp2p` | **peer** (`^3.0.0`) | The node you build and own. |
150
- | `@libp2p/interface` | **peer** (`^3.0.0`) | `Libp2p`, `PeerId`, `Stream` types. |
151
- | `@multiformats/multiaddr` | **peer** (`^13.0.0`) | `Multiaddr` dial targets. |
152
- | `@chainsafe/libp2p-noise`, `@chainsafe/libp2p-yamux`, `@libp2p/tcp`, `@libp2p/utils` | dev | Two real in-process nodes for the test suite. |
163
+ DATA 0x00 body bytes
164
+ ERROR 0x02 JSON of serializeError(err)
165
+ ```
153
166
 
154
- No runtime dependencies outside the workspace. ESM only (`"type": "module"`).
167
+ A libp2p stream is a byte stream, so frames carry a length and are reassembled
168
+ from whatever chunks arrive. Normal end of input is libp2p's own
169
+ `close()` (close-write), not a frame. The `ERROR` frame exists because a yamux
170
+ reset carries only "stream reset"; without it, a handler that throws would
171
+ reach the caller as an anonymous reset. Frames of other types are skipped.
172
+
173
+ ### Why identity reaches the handler by closure
174
+
175
+ `Duplex` is bytes-only, so `serveConnections` passes identity to a factory
176
+ instead of to the handler. `remotePeer` is `connection.remotePeer`, the peer id
177
+ libp2p proved when the connection was encrypted. It is the one identity claim
178
+ on the serving side that a request payload cannot forge, and no caller can
179
+ influence it. `makeHandler` runs once per inbound stream; keep per-peer state
180
+ inside it. Reusing one handler built outside it for every connection is how
181
+ identity-by-closure gets broken. `serve` is `serveConnections` with the context
182
+ ignored, so both share framing, teardown and failure handling.
183
+
184
+ ### Why sends wait for the `'drain'` event
185
+
186
+ libp2p 3.x streams are push-based: `stream.send(chunk)` returns `false` when
187
+ the write buffer is full, and the stream emits `'drain'` when it can take
188
+ more. The outbound pump honours that return value and waits for the real
189
+ `'drain'` event. It does not use `stream.onDrain()`: in `@libp2p/utils` (7.4.1
190
+ at the time of writing) that method creates one promise and never clears it,
191
+ so after the first backpressure cycle it resolves immediately while the buffer
192
+ is still full, and a write loop built on it fills the buffer without bound.
193
+ `tests/backpressure.test.ts` covers this.
194
+
195
+ ### Why both timeouts are minutes, not seconds
196
+
197
+ - **Drain timeout** (`DEFAULT_DRAIN_TIMEOUT_MS`, 5 minutes, `drainTimeoutMs`
198
+ per call site). A peer that requests something and then stops reading,
199
+ without closing or resetting, produces no event. Unbounded, it would park
200
+ the serving side's pump, the handler and everything buffered behind it.
201
+ 5 minutes covers a peer draining a full yamux receive window (256 KiB by
202
+ default) at under 1 KiB/s; a tighter bound would reset slow but alive peers,
203
+ which is what backpressure exists to avoid. On expiry it logs
204
+ `[webrun-streams-libp2p] waitForDrain: peer on protocol <p> did not accept more data within <ms>ms and never closed the stream; dropping it so this side's pump is not parked forever`
205
+ and aborts the stream.
206
+ - **Close timeout** (`DEFAULT_CLOSE_TIMEOUT_MS`, 5 minutes). `stream.close()`
207
+ waits for the write queue to drain, and that queue is shared by every stream
208
+ on the muxer, so under many concurrent transfers a healthy close can take a
209
+ long time. When the bound trips the stream is aborted, which truncates data
210
+ in flight. With a 5-second bound, 18 concurrent 3.5 MB transfers over one
211
+ connection mostly arrived truncated; minutes catch a peer that will never
212
+ close just as well. On a trip it logs
213
+ `[webrun-streams-libp2p] closeStream: graceful close of protocol <p> failed (bound <ms>ms), aborting instead (peer may see truncated data): <reason>`.
214
+ The close timeout is not configurable through `connect` / `serve` params.
215
+
216
+ ### Why a burst of calls is serialised on a fresh connection
217
+
218
+ With no connection to the peer yet, every call dials and they all share the
219
+ one connection libp2p establishes. Their streams can reach the remote while it
220
+ is still upgrading that connection. yamux counts those as early streams and,
221
+ past `maxEarlyStreams` (10 by default), aborts the whole muxer: every stream
222
+ on the connection dies, the remote sees EOF during protocol negotiation, and
223
+ this side sees `StreamResetError`. Raising the limit on your own nodes would
224
+ not help against other peers.
225
+
226
+ So until one stream has negotiated its protocol on an open connection, calls
227
+ open their streams one at a time; after that they open concurrently. If the
228
+ proven connection closes, the next burst is gated again (this re-check needs
229
+ `node.getConnections`; a node that offers only `dialProtocol` stays proven
230
+ after its first stream). The state is shared by every `connect()` to the same
231
+ peer from the same node, because callers often `connect()` per request.
232
+
233
+ ### Stream limits
234
+
235
+ libp2p caps the number of open streams for one protocol per connection, and
236
+ past the cap a new stream is reset, not queued. One call is one stream, so a
237
+ caller with more concurrent calls than the cap sees calls rejected with no
238
+ other symptom. `maxInboundStreams`, `maxOutboundStreams` and
239
+ `runOnLimitedConnection` are passed through unchanged; an unset option is left
240
+ out of the options object so libp2p's own default applies (inbound 32,
241
+ outbound 64, limited connections refused). `tests/stream-limits.test.ts`
242
+ checks both that a raised `maxInboundStreams` admits more than 32 concurrent
243
+ streams and that an unconfigured server stops at 32.
244
+
245
+ ### How calls end
246
+
247
+ - **Normal end.** Both sides finished: the stream is closed gracefully,
248
+ bounded by the close timeout.
249
+ - **Caller cancels** (`.return()` on the call's generator). The adapter aborts
250
+ the stream with `call cancelled` before the generator's own cleanup runs,
251
+ because by then the stream is already marked closed and `abort` would do
252
+ nothing. The caller's input iterator is returned without waiting: `.return()`
253
+ on a generator parked in its own `next()` is queued behind that `next()`, and
254
+ awaiting it would hang teardown.
255
+ - **Consumer of `duplexOverStream` stops early.** The stream is aborted with
256
+ `duplexOverStream: consumer cancelled`, and the input is returned without
257
+ waiting, as above.
258
+ - **Handler throws.** The error is sent as an `ERROR` frame; the caller's
259
+ `for await` throws it with `message`, `stack` and custom fields.
260
+ - **Caller leaves mid-request on the serving side** (a tab closed, a reset).
261
+ `serveConnections` catches the failure per stream and logs
262
+ `[webrun-streams-libp2p] serve: inbound stream on protocol <p> failed: <message>`,
263
+ so one failed stream never becomes an unhandled rejection that terminates
264
+ the serving process. The handler's output is returned, so its `finally` runs.
265
+
266
+ ### Constraints
267
+
268
+ - On the serving side, request bytes are queued for the handler without a
269
+ bound; backpressure applies to the handler's output, not to its input.
270
+ - `duplexOverStream` must start reading the stream without an intervening
271
+ `await`: end of input arrives as an event, and one delivered before the
272
+ iterator subscribes is lost. Every path inside the package keeps this.
273
+
274
+ ### Tests
275
+
276
+ `pnpm test` runs the backpressure, drain and close timeout, cancellation,
277
+ identity, burst, stream-limit and serving-resilience tests against two real
278
+ in-process TCP nodes. The shared conformance suite is opt-in because it spins
279
+ up more nodes: `WEBRUN_STREAMS_LIBP2P=1 pnpm test`. It runs with
280
+ `skipHugeBody`, and L6's small window does not apply (there is no
281
+ `emulateMux`), so L6 is an integrity check.
282
+
283
+ ### Dependencies
284
+
285
+ - `@statewalker/webrun-streams` (`workspace:^`): the seam types and
286
+ `serializeError` / `deserializeError`.
287
+ - `@libp2p/interface`, `@multiformats/multiaddr` (peers, types only) and
288
+ `libp2p` (optional peer). Dev dependencies `@chainsafe/libp2p-noise`,
289
+ `@chainsafe/libp2p-yamux`, `@libp2p/tcp` and `@libp2p/utils` build the test
290
+ nodes.
155
291
 
156
292
  ## License
157
293
 
158
- MIT © statewalker — see [LICENSE](../../LICENSE).
294
+ MIT
package/package.json CHANGED
@@ -1,10 +1,13 @@
1
1
  {
2
2
  "name": "@statewalker/webrun-streams-libp2p",
3
- "version": "0.1.6",
3
+ "version": "0.1.8",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "libp2p native multi-stream Connect/Serve adapter in the webrun-streams-* family",
7
- "homepage": "https://github.com/statewalker/webrun-wire",
7
+ "bugs": {
8
+ "url": "https://github.com/statewalker/webrun-wire/issues"
9
+ },
10
+ "homepage": "https://github.com/statewalker/webrun-wire/tree/main/packages/webrun-streams-libp2p#readme",
8
11
  "author": {
9
12
  "name": "Mikhail Kotelnikov",
10
13
  "email": "mikhail.kotelnikov@gmail.com"
@@ -12,7 +15,8 @@
12
15
  "license": "MIT",
13
16
  "repository": {
14
17
  "type": "git",
15
- "url": "git@github.com:statewalker/webrun-wire.git"
18
+ "url": "git+https://github.com/statewalker/webrun-wire.git",
19
+ "directory": "packages/webrun-streams-libp2p"
16
20
  },
17
21
  "exports": {
18
22
  ".": {
@@ -26,7 +30,7 @@
26
30
  "src"
27
31
  ],
28
32
  "dependencies": {
29
- "@statewalker/webrun-streams": "^0.2.1"
33
+ "@statewalker/webrun-streams": "^0.2.3"
30
34
  },
31
35
  "peerDependencies": {
32
36
  "@libp2p/interface": "^3.0.0",
@@ -42,17 +46,17 @@
42
46
  "@biomejs/biome": "^2.5.15",
43
47
  "@chainsafe/libp2p-noise": "^17.0.0",
44
48
  "@chainsafe/libp2p-yamux": "^8.0.1",
45
- "@libp2p/interface": "^3.3.0",
49
+ "@libp2p/interface": "^3.0.0",
46
50
  "@libp2p/tcp": "^11.0.28",
47
51
  "@libp2p/utils": "^7.4.1",
48
52
  "@multiformats/multiaddr": "^13.0.3",
49
53
  "@types/node": "^26.6.4",
50
- "libp2p": "^3.3.11",
54
+ "libp2p": "^3.0.0",
51
55
  "rimraf": "^6.1.3",
52
56
  "rolldown": "^1.2.12",
53
57
  "typescript": "^7.0.2",
54
58
  "vitest": "^5.0.3",
55
- "@statewalker/webrun-streams-conformance": "^0.3.1"
59
+ "@statewalker/webrun-streams-conformance": "^0.3.3"
56
60
  },
57
61
  "sideEffects": false,
58
62
  "publishConfig": {