@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.
- package/README.md +252 -116
- package/package.json +11 -7
package/README.md
CHANGED
|
@@ -1,158 +1,294 @@
|
|
|
1
1
|
# @statewalker/webrun-streams-libp2p
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
## What it is
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
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
|
-
|
|
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
|
-
|
|
31
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
34
|
+
## How to use
|
|
40
35
|
|
|
41
|
-
```
|
|
42
|
-
|
|
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
|
-
|
|
40
|
+
Runtime dependency: `@statewalker/webrun-streams`. Peer dependencies:
|
|
53
41
|
|
|
54
|
-
|
|
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
|
-
| `
|
|
63
|
-
| `
|
|
64
|
-
| `
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
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
|
-
|
|
72
|
-
|
|
73
|
-
|
|
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
|
-
|
|
74
|
+
`ServeLibp2pParams`: `node`, `protocol`, `drainTimeoutMs`,
|
|
75
|
+
`maxOutboundStreams` and `runOnLimitedConnection` as above (passed to
|
|
76
|
+
`node.handle`), plus `maxInboundStreams` (libp2p default 32).
|
|
76
77
|
|
|
77
|
-
|
|
78
|
+
`ConnectionContext`: `{ remotePeer: PeerId }`.
|
|
79
|
+
`ServeConnectionsHandler`: `(context: ConnectionContext) => Duplex`.
|
|
78
80
|
|
|
79
|
-
`
|
|
81
|
+
`DuplexOverStreamOptions`:
|
|
80
82
|
|
|
81
|
-
|
|
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
|
-
|
|
89
|
+
## Examples
|
|
84
90
|
|
|
85
|
-
|
|
91
|
+
### Serve and call between two nodes
|
|
86
92
|
|
|
87
|
-
|
|
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
|
-
|
|
90
|
-
|
|
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
|
-
|
|
105
|
+
const stop = await serve({ node: server }, async function* echo(input) {
|
|
106
|
+
for await (const chunk of input) yield chunk;
|
|
107
|
+
});
|
|
93
108
|
|
|
94
|
-
|
|
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
|
-
|
|
113
|
+
await close();
|
|
114
|
+
await stop();
|
|
115
|
+
await client.stop();
|
|
116
|
+
await server.stop();
|
|
117
|
+
```
|
|
97
118
|
|
|
98
|
-
|
|
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
|
-
|
|
121
|
+
```ts
|
|
122
|
+
import { serveConnections } from "@statewalker/webrun-streams-libp2p";
|
|
123
|
+
import type { Libp2p } from "@libp2p/interface";
|
|
110
124
|
|
|
111
|
-
|
|
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
|
-
|
|
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
|
-
|
|
138
|
+
### Raising stream limits
|
|
123
139
|
|
|
124
|
-
|
|
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
|
-
|
|
127
|
-
|
|
128
|
-
|
|
145
|
+
declare const node: Libp2p;
|
|
146
|
+
declare const peer: PeerId;
|
|
147
|
+
declare const handler: Duplex;
|
|
129
148
|
|
|
130
|
-
|
|
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
|
-
|
|
133
|
-
[Flow control](#flow-control-and-what-libp2p-3x-does-not-give-you-for-free).
|
|
153
|
+
## Internals
|
|
134
154
|
|
|
135
|
-
|
|
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
|
-
|
|
143
|
-
|
|
144
|
-
|
|
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
|
-
|
|
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
|
|
294
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,10 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@statewalker/webrun-streams-libp2p",
|
|
3
|
-
"version": "0.1.
|
|
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
|
-
"
|
|
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
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
59
|
+
"@statewalker/webrun-streams-conformance": "^0.3.3"
|
|
56
60
|
},
|
|
57
61
|
"sideEffects": false,
|
|
58
62
|
"publishConfig": {
|