@statewalker/webrun-streams-libp2p 0.6.0 → 0.7.0
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 +191 -82
- package/dist/connect-serve.d.ts +114 -67
- package/dist/connect-serve.d.ts.map +1 -1
- package/dist/duplex-over-stream.d.ts +12 -0
- package/dist/duplex-over-stream.d.ts.map +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +278 -20
- package/dist/legacy-connect-serve.d.ts +116 -0
- package/dist/legacy-connect-serve.d.ts.map +1 -0
- package/dist/port-mux.d.ts +7 -1
- package/dist/port-mux.d.ts.map +1 -1
- package/dist/shared.d.ts +26 -0
- package/dist/shared.d.ts.map +1 -0
- package/package.json +4 -3
- package/src/connect-serve.ts +337 -342
- package/src/duplex-over-stream.ts +12 -0
- package/src/index.ts +2 -0
- package/src/legacy-connect-serve.ts +425 -0
- package/src/port-mux.ts +20 -5
- package/src/shared.ts +28 -0
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)`
|
|
7
|
-
`
|
|
8
|
-
|
|
9
|
-
protocol
|
|
10
|
-
additionally tells the handler which peer libp2p
|
|
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,15 @@ 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
|
-
- **
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
- **
|
|
29
|
-
|
|
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
|
+
- **Error fidelity.** A handler's `Error` reaches the caller with `message`,
|
|
35
|
+
`stack` and custom fields.
|
|
36
|
+
- **Cancellation** in both directions: a caller's `.return()` ends the call at
|
|
37
|
+
once, and the handler's `finally` runs.
|
|
30
38
|
- **A guard against a burst of calls on a fresh connection**, which would
|
|
31
39
|
otherwise kill the connection's muxer.
|
|
32
40
|
- **Caller identity** for the serving side, through `serveConnections`.
|
|
@@ -37,7 +45,9 @@ What the adapter adds on top of a raw stream:
|
|
|
37
45
|
pnpm add @statewalker/webrun-streams-libp2p @libp2p/interface @multiformats/multiaddr
|
|
38
46
|
```
|
|
39
47
|
|
|
40
|
-
Runtime
|
|
48
|
+
Runtime dependencies: `@statewalker/webrun-streams`, `@statewalker/webrun-rpc`
|
|
49
|
+
(the port stack `connect`/`serve` run) and `@statewalker/webrun-msgpack` (the
|
|
50
|
+
calls' wire codec). Peer dependencies:
|
|
41
51
|
|
|
42
52
|
| Peer | Range | Required |
|
|
43
53
|
| --- | --- | --- |
|
|
@@ -51,19 +61,21 @@ runs (Node or browser).
|
|
|
51
61
|
|
|
52
62
|
| Export | What it gives |
|
|
53
63
|
| --- | --- |
|
|
54
|
-
| `connect(params)` | `Connect<ConnectLibp2pParams>`. Resolves `{ call, close }` immediately (no dial yet). Each `call(input)`
|
|
55
|
-
| `serve(params, handler)` | `Serve<ServeLibp2pParams>`. `
|
|
56
|
-
| `serveConnections(params, makeHandler)` | Like `serve`, but `makeHandler(context)` is called once per
|
|
57
|
-
| `
|
|
58
|
-
| `
|
|
64
|
+
| `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. |
|
|
65
|
+
| `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. |
|
|
66
|
+
| `serveConnections(params, makeHandler)` | Like `serve`, but `makeHandler(context)` is called once per call with `{ remotePeer }`, and returns that call's `Duplex`. |
|
|
67
|
+
| `DEFAULT_WINDOW` | `4194304` (4 MiB), the port window `connect`/`serve` grant unless told otherwise. See "Sizing the window". |
|
|
68
|
+
| `portProtocolOf(protocol)` | `protocol + "/ports"`: what a call's stream negotiates (with `/window` appended between two windowed ends). |
|
|
69
|
+
| `DEFAULT_PROTOCOL` | `"/webrun-streams/1.0.0"`. |
|
|
70
|
+
| `duplexOverStream(stream, input, options?)` | **Deprecated.** The deprecated protocol's primitive: runs one call over one libp2p `Stream`. Removed in the next release. |
|
|
71
|
+
| `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
72
|
| `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
|
|
73
|
+
| `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`. 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
74
|
| `DEFAULT_PORT_PROTOCOL`, `DEFAULT_PORT_MAX_MESSAGE_SIZE` | `"/webrun-ports/1.0.0"`, 256 KiB. |
|
|
62
|
-
| `
|
|
63
|
-
| `
|
|
64
|
-
| `DEFAULT_CLOSE_TIMEOUT_MS` | `300_000` (5 minutes), the bound on a graceful close. |
|
|
75
|
+
| `DEFAULT_DRAIN_TIMEOUT_MS` | **Deprecated** (the deprecated protocol only). `300_000` (5 minutes). |
|
|
76
|
+
| `DEFAULT_CLOSE_TIMEOUT_MS` | **Deprecated** (the deprecated protocol only). `300_000` (5 minutes), the bound on a graceful close. |
|
|
65
77
|
| `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),
|
|
78
|
+
| `DEFAULT_MAX_FRAME_BYTES` | `67_108_864` (64 MiB), the default cap on one inbound frame (`maxFrameBytes`). |
|
|
67
79
|
| `ConnectLibp2pParams`, `ServeLibp2pParams`, `ConnectionContext`, `ServeConnectionsHandler`, `DuplexOverStreamOptions` | Types, below. |
|
|
68
80
|
|
|
69
81
|
`ConnectLibp2pParams`:
|
|
@@ -72,26 +84,32 @@ runs (Node or browser).
|
|
|
72
84
|
| --- | --- | --- | --- |
|
|
73
85
|
| `node` | `Libp2p` | required | The local node. Only `dialProtocol` is required; `getConnections` is used when present. |
|
|
74
86
|
| `peer` | `PeerId \| Multiaddr` | required | Who to dial. |
|
|
75
|
-
| `protocol` | `string` | `DEFAULT_PROTOCOL` |
|
|
76
|
-
| `
|
|
77
|
-
| `
|
|
87
|
+
| `protocol` | `string` | `DEFAULT_PROTOCOL` | The protocol id both ends are configured with. Calls negotiate `portProtocolOf(protocol)`; `protocol` itself is the deprecated fallback. |
|
|
88
|
+
| `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. See "Sizing the window". |
|
|
89
|
+
| `timeout` | `number` | none | Per-call inactivity timeout in ms, reset by any chunk in either direction. Unset, a slow consumer is throttled, never failed. |
|
|
90
|
+
| `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
91
|
| `maxOutboundStreams` | `number` | libp2p's (64) | Passed to `dialProtocol`. |
|
|
79
92
|
| `runOnLimitedConnection` | `boolean` | unset | Passed to `dialProtocol`. Allows relayed or otherwise limited connections. |
|
|
93
|
+
| `drainTimeoutMs`, `readHighWaterBytes` | `number` | 5 min, 64 KiB | **Deprecated**: the deprecated protocol only (an older server). |
|
|
80
94
|
|
|
81
|
-
`ServeLibp2pParams`: `node`, `protocol`, `
|
|
95
|
+
`ServeLibp2pParams`: `node`, `protocol`, `window`, `timeout`, `maxFrameBytes`,
|
|
82
96
|
`maxOutboundStreams` and `runOnLimitedConnection` as above (passed to
|
|
83
|
-
`node.handle`), plus `maxInboundStreams` (libp2p
|
|
97
|
+
`node.handle` for each served protocol), plus `maxInboundStreams` (libp2p
|
|
98
|
+
default 32), and the deprecated `drainTimeoutMs` and `readHighWaterBytes`
|
|
99
|
+
(older callers only). The server's `window` bounds what a call sends ahead of
|
|
100
|
+
the handler.
|
|
84
101
|
|
|
85
102
|
`ConnectionContext`: `{ remotePeer: PeerId }`.
|
|
86
103
|
`ServeConnectionsHandler`: `(context: ConnectionContext) => Duplex`.
|
|
87
104
|
|
|
88
|
-
`DuplexOverStreamOptions
|
|
105
|
+
`DuplexOverStreamOptions` (**deprecated**, with `duplexOverStream`):
|
|
89
106
|
|
|
90
107
|
| Field | Meaning |
|
|
91
108
|
| --- | --- |
|
|
92
|
-
| `onPeerInputEnd?(err?)` | Called once when the peer's side ends: closed, `ERROR` frame (passed as `err`) or torn down.
|
|
93
|
-
| `onSourceCompleted?()` | Called only when the peer's side ended normally.
|
|
94
|
-
| `drainTimeoutMs?` |
|
|
109
|
+
| `onPeerInputEnd?(err?)` | Called once when the peer's side ends: closed, `ERROR` frame (passed as `err`) or torn down. |
|
|
110
|
+
| `onSourceCompleted?()` | Called only when the peer's side ended normally. |
|
|
111
|
+
| `drainTimeoutMs?` | How long a backpressured send waits for `'drain'`. |
|
|
112
|
+
| `readHighWaterBytes?` | Received bytes held for a consumer that is not reading before the stream is paused. |
|
|
95
113
|
| `maxFrameBytes?` | As above. |
|
|
96
114
|
|
|
97
115
|
## Examples
|
|
@@ -160,7 +178,83 @@ const { call } = await connect({ node, peer, protocol: "/my-app/1.0.0", maxOutbo
|
|
|
160
178
|
|
|
161
179
|
## Internals
|
|
162
180
|
|
|
163
|
-
###
|
|
181
|
+
### A call is a port
|
|
182
|
+
|
|
183
|
+
`connect` builds a `libp2pPortMux` for `portProtocolOf(protocol)` with
|
|
184
|
+
`window` (default `DEFAULT_WINDOW`) and hands it to `webrun-rpc`'s `connect`
|
|
185
|
+
through `overPorts`; `serve` does the same with `webrun-rpc`'s `serve`. So one
|
|
186
|
+
call is one port, one port is one libp2p stream, and the stream tier
|
|
187
|
+
(`duplexOverPort`) runs the call: its chunks (at most 256 KiB each) go as
|
|
188
|
+
msgpack messages, pipelined up to the peer's window, and the window's credit
|
|
189
|
+
is their confirmation. yamux still multiplexes the streams, but its windows no
|
|
190
|
+
longer bound anything this package promises: the port's credit bounds what is
|
|
191
|
+
in flight per call. There is no flow control of this package's own any more;
|
|
192
|
+
the bespoke yamux pause/resume run-ahead bound of the deprecated protocol goes
|
|
193
|
+
with it in the next release.
|
|
194
|
+
|
|
195
|
+
Both ends of a call between two releases from this one on always run the
|
|
196
|
+
window, so a call's stream negotiates `<protocol>/ports/window`; the mux also
|
|
197
|
+
serves (and dials, second) `<protocol>/ports`, unwindowed.
|
|
198
|
+
|
|
199
|
+
### Sizing the window
|
|
200
|
+
|
|
201
|
+
A call moves at most one window per round trip, so its throughput is capped at
|
|
202
|
+
`window / RTT`, and a producer runs at most about one window (plus a chunk at
|
|
203
|
+
each end) ahead of a consumer that stopped reading. Size it at least to the
|
|
204
|
+
link's bandwidth-delay product:
|
|
205
|
+
|
|
206
|
+
| Link | BDP | Window |
|
|
207
|
+
| --- | --- | --- |
|
|
208
|
+
| LAN, 1 Gbit/s at 1 ms | 125 KB | the 64 KiB floor would cap it; 1 MiB is ample |
|
|
209
|
+
| 70 Mbit/s at 11 ms | 96 KB | 1 MiB |
|
|
210
|
+
| 200 Mbit/s at 100 ms | 2.5 MB | the 4 MiB default |
|
|
211
|
+
| 1 Gbit/s at 100 ms | 12.5 MB | 16 MiB |
|
|
212
|
+
|
|
213
|
+
Measured over an emulated 100 ms / 200 Mbit/s link (statewalker/webrun-wire#153):
|
|
214
|
+
a 1 MiB window capped a 16 MiB echo at 7.4 MiB/s, the 4 MiB window reached
|
|
215
|
+
15 MiB/s, as fast as the deprecated protocol. Far above the bottleneck's queue a
|
|
216
|
+
window only adds latency (bufferbloat): on an 11 ms link 4 MiB was slower than
|
|
217
|
+
1 MiB. Both ends set their own window: the caller's bounds the response, the
|
|
218
|
+
server's the request. Memory per call is bounded by the window, so a server
|
|
219
|
+
with many concurrent calls may want a smaller one.
|
|
220
|
+
|
|
221
|
+
### Compatibility with 0.6.0 and older
|
|
222
|
+
|
|
223
|
+
Deprecated shims, on both ends, for one release; removed in the next one:
|
|
224
|
+
|
|
225
|
+
- **New server, old caller.** `serve`/`serveConnections` also handle
|
|
226
|
+
`protocol` itself with the deprecated protocol (`legacy-connect-serve.ts`),
|
|
227
|
+
so an old `connect` keeps working.
|
|
228
|
+
- **New caller, old server.** An old server refuses `<protocol>/ports…`
|
|
229
|
+
(libp2p's `UnsupportedProtocolError`, before any of the call's input is
|
|
230
|
+
read), and the call runs on `protocol` instead. The node remembers the
|
|
231
|
+
refusal per peer and protocol for that connection, so later calls, from any
|
|
232
|
+
`connect()` on the node, dial `protocol` directly; a new connection (the peer
|
|
233
|
+
restarted, perhaps upgraded) is probed again. The first call to an old server
|
|
234
|
+
costs one extra protocol negotiation.
|
|
235
|
+
|
|
236
|
+
`tests/interop-0-6.test.ts` runs the conformance suite (L0–L6) and the cases
|
|
237
|
+
above against the published 0.6.0 in both directions.
|
|
238
|
+
|
|
239
|
+
Behaviour that differs from the deprecated protocol:
|
|
240
|
+
|
|
241
|
+
- **A call ends with the peer's output.** When the handler's output ends, the
|
|
242
|
+
call ends: input the caller has not sent yet is abandoned, and a handler
|
|
243
|
+
still reading its input is told the caller abandoned the stream. The
|
|
244
|
+
deprecated protocol kept sending until the input ended too.
|
|
245
|
+
- **No drain timeout.** A peer that stops reading holds at most a window per
|
|
246
|
+
call; set `timeout` to fail idle calls. `drainTimeoutMs` and
|
|
247
|
+
`readHighWaterBytes` apply to the deprecated protocol only.
|
|
248
|
+
- **Chunks.** A response arrives in chunks of up to 256 KiB (64 KiB before).
|
|
249
|
+
- **Failures on the serving side are not logged**: they reach the handler
|
|
250
|
+
(its input throws) and the caller.
|
|
251
|
+
|
|
252
|
+
### The deprecated protocol
|
|
253
|
+
|
|
254
|
+
The sections below describe the deprecated protocol, which `serve` still
|
|
255
|
+
answers and `connect` falls back to until the next release.
|
|
256
|
+
|
|
257
|
+
#### Frames on the stream
|
|
164
258
|
|
|
165
259
|
```
|
|
166
260
|
+--------+-----------------+-----------------+
|
|
@@ -190,7 +284,7 @@ or `webrun-streams-libp2p: a malformed frame length`, and aborts the stream:
|
|
|
190
284
|
a peer not speaking this framing would otherwise make the receiver buffer
|
|
191
285
|
without bound. On the serving side the handler's input throws that error.
|
|
192
286
|
|
|
193
|
-
|
|
287
|
+
#### Why identity reaches the handler by closure
|
|
194
288
|
|
|
195
289
|
`Duplex` is bytes-only, so `serveConnections` passes identity to a factory
|
|
196
290
|
instead of to the handler. `remotePeer` is `connection.remotePeer`, the peer id
|
|
@@ -201,7 +295,7 @@ inside it. Reusing one handler built outside it for every connection is how
|
|
|
201
295
|
identity-by-closure gets broken. `serve` is `serveConnections` with the context
|
|
202
296
|
ignored, so both share framing, teardown and failure handling.
|
|
203
297
|
|
|
204
|
-
|
|
298
|
+
#### Why sends wait for the `'drain'` event
|
|
205
299
|
|
|
206
300
|
libp2p 3.x streams are push-based: `stream.send(chunk)` returns `false` when
|
|
207
301
|
the write buffer is full, and the stream emits `'drain'` when it can take
|
|
@@ -212,7 +306,7 @@ so after the first backpressure cycle it resolves immediately while the buffer
|
|
|
212
306
|
is still full, and a write loop built on it fills the buffer without bound.
|
|
213
307
|
`tests/backpressure.test.ts` covers this.
|
|
214
308
|
|
|
215
|
-
|
|
309
|
+
#### Why both timeouts are minutes, not seconds
|
|
216
310
|
|
|
217
311
|
- **Drain timeout** (`DEFAULT_DRAIN_TIMEOUT_MS`, 5 minutes, `drainTimeoutMs`
|
|
218
312
|
per call site). A peer that requests something and then stops reading,
|
|
@@ -233,36 +327,7 @@ is still full, and a write loop built on it fills the buffer without bound.
|
|
|
233
327
|
`[webrun-streams-libp2p] closeStream: graceful close of protocol <p> failed (bound <ms>ms), aborting instead (peer may see truncated data): <reason>`.
|
|
234
328
|
The close timeout is not configurable through `connect` / `serve` params.
|
|
235
329
|
|
|
236
|
-
|
|
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
|
|
330
|
+
#### How calls end
|
|
266
331
|
|
|
267
332
|
- **Normal end.** Both sides finished: the stream is closed gracefully,
|
|
268
333
|
bounded by the close timeout.
|
|
@@ -300,14 +365,43 @@ streams and that an unconfigured server stops at 32.
|
|
|
300
365
|
A caller that sent its whole request and then stopped reading the response
|
|
301
366
|
(`.return()` mid-stream) is ordinary and is not logged.
|
|
302
367
|
|
|
368
|
+
### Why a burst of calls is serialised on a fresh connection
|
|
369
|
+
|
|
370
|
+
With no connection to the peer yet, every call dials and they all share the
|
|
371
|
+
one connection libp2p establishes. Their streams can reach the remote while it
|
|
372
|
+
is still upgrading that connection. yamux counts those as early streams and,
|
|
373
|
+
past `maxEarlyStreams` (10 by default), aborts the whole muxer: every stream
|
|
374
|
+
on the connection dies, the remote sees EOF during protocol negotiation, and
|
|
375
|
+
this side sees `StreamResetError`. Raising the limit on your own nodes would
|
|
376
|
+
not help against other peers.
|
|
377
|
+
|
|
378
|
+
So until one stream has negotiated its protocol on an open connection, calls
|
|
379
|
+
open their streams one at a time; after that they open concurrently. If the
|
|
380
|
+
proven connection closes, the next burst is gated again (this re-check needs
|
|
381
|
+
`node.getConnections`; a node that offers only `dialProtocol` stays proven
|
|
382
|
+
after its first stream). The state is shared by every `connect()` to the same
|
|
383
|
+
peer from the same node, because callers often `connect()` per request.
|
|
384
|
+
|
|
385
|
+
### Stream limits
|
|
386
|
+
|
|
387
|
+
libp2p caps the number of open streams for one protocol per connection, and
|
|
388
|
+
past the cap a new stream is reset, not queued. One call is one stream, so a
|
|
389
|
+
caller with more concurrent calls than the cap sees calls rejected with no
|
|
390
|
+
other symptom. `maxInboundStreams`, `maxOutboundStreams` and
|
|
391
|
+
`runOnLimitedConnection` are passed through unchanged; an unset option is left
|
|
392
|
+
out of the options object so libp2p's own default applies (inbound 32,
|
|
393
|
+
outbound 64, limited connections refused). `tests/stream-limits.test.ts`
|
|
394
|
+
checks both that a raised `maxInboundStreams` admits more than 32 concurrent
|
|
395
|
+
streams and that an unconfigured server stops at 32.
|
|
396
|
+
|
|
303
397
|
### MessagePorts over libp2p, and the port stack on them
|
|
304
398
|
|
|
305
|
-
`connect` / `serve` above
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
399
|
+
`connect` / `serve` above are the first of the two ways below, with a window
|
|
400
|
+
and msgpack set for you. Use the port mux directly to choose the codec, the
|
|
401
|
+
chunk size or the multiplexing, or to put other port users on the same node.
|
|
402
|
+
`webrun-rpc`'s port stack bounds a producer to its consumer whatever the
|
|
403
|
+
transport buffers underneath: each chunk waits for the peer's confirmation, or,
|
|
404
|
+
on a windowed port, for the window's credit. Two ways to put libp2p under it:
|
|
311
405
|
|
|
312
406
|
```ts
|
|
313
407
|
import { deserialize, msgpackCodec, serialize } from "@statewalker/webrun-msgpack";
|
|
@@ -349,8 +443,8 @@ run against it (`tests/port-window.test.ts`).
|
|
|
349
443
|
|
|
350
444
|
Each native port carries `closeSignal`, aborted when its stream ends, the peer
|
|
351
445
|
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
|
|
353
|
-
|
|
446
|
+
from the port, so a call on a dead stream fails instead of waiting, and
|
|
447
|
+
`libp2pPortMux` itself imports nothing from `webrun-rpc`. Ports are opened through the
|
|
354
448
|
same early-stream gate as `connect()`. A port `onPort` refuses (returns
|
|
355
449
|
`false`) is aborted: the opener's signal aborts with `PeerGoneError` and a call
|
|
356
450
|
on it fails. A frame the port's codec cannot decode (a peer speaking another
|
|
@@ -401,6 +495,8 @@ reader buffer without bound. Raise it with
|
|
|
401
495
|
|
|
402
496
|
### Constraints
|
|
403
497
|
|
|
498
|
+
The two below concern the deprecated protocol.
|
|
499
|
+
|
|
404
500
|
- On the serving side, request bytes are queued for the handler without a
|
|
405
501
|
bound; backpressure applies to the handler's output, not to its input.
|
|
406
502
|
- `duplexOverStream` must start reading the stream without an intervening
|
|
@@ -416,9 +512,19 @@ its connection in-process and SIGKILLing a forked server
|
|
|
416
512
|
(`tests/fixtures/greeting-server.ts`, run with `tsx`), with 100 open channels
|
|
417
513
|
each; every channel must fail with an error within 1 s. The shared conformance
|
|
418
514
|
suite (`tests/conformance.test.ts`, about 7 s) runs in the same `pnpm test`, with
|
|
419
|
-
`skipHugeBody
|
|
420
|
-
|
|
421
|
-
|
|
515
|
+
`skipHugeBody`, for `connect`/`serve` and for the deprecated protocol on both
|
|
516
|
+
ends.
|
|
517
|
+
|
|
518
|
+
**`connect`/`serve` over the windowed port mux** (`tests/connect-over-ports.test.ts`):
|
|
519
|
+
the protocol ids negotiated, the 4 MiB default window and a 1 MiB `window`
|
|
520
|
+
option holding a producer to the window (L6, in both directions, over yamux's
|
|
521
|
+
16 MiB stream window), identity per call, and the window floor.
|
|
522
|
+
**Interop** (`tests/interop-0-6.test.ts`): the conformance suite L0–L6 and the
|
|
523
|
+
fallback cases between this release and the published 0.6.0
|
|
524
|
+
(`webrun-streams-libp2p-0-6`, an npm alias), old caller to new server and new
|
|
525
|
+
caller to old server.
|
|
526
|
+
|
|
527
|
+
**Run-ahead is bounded for the deprecated protocol** (spec D17, L6;
|
|
422
528
|
`tests/run-ahead.test.ts`, always on). L6 first found none: a consumer that
|
|
423
529
|
stopped reading let the producer run 22-24 MiB ahead until libp2p's 4 MiB read
|
|
424
530
|
buffer killed the stream. Two things buffered without limit:
|
|
@@ -487,13 +593,16 @@ the signal never aborted.
|
|
|
487
593
|
|
|
488
594
|
### Dependencies
|
|
489
595
|
|
|
490
|
-
- `@statewalker/webrun-streams` (`workspace:^`): the seam types
|
|
491
|
-
`serializeError` / `deserializeError`.
|
|
596
|
+
- `@statewalker/webrun-streams` (`workspace:^`): the seam types, the native
|
|
597
|
+
port mux and `serializeError` / `deserializeError`.
|
|
598
|
+
- `@statewalker/webrun-rpc` (`workspace:^`): the port stack `connect`/`serve`
|
|
599
|
+
run (`connect`, `serve`, `overPorts`).
|
|
600
|
+
- `@statewalker/webrun-msgpack` (`workspace:^`): the calls' value codec.
|
|
492
601
|
- `@libp2p/interface`, `@multiformats/multiaddr` (peers, types only) and
|
|
493
602
|
`libp2p` (optional peer). Dev dependencies `@chainsafe/libp2p-noise`,
|
|
494
603
|
`@chainsafe/libp2p-yamux`, `@libp2p/tcp` and `@libp2p/utils` build the test
|
|
495
|
-
nodes
|
|
496
|
-
|
|
604
|
+
nodes, `webrun-streams-libp2p-0-6` (the published 0.6.0) is the old peer of
|
|
605
|
+
the interop tests, and `tsx` runs the forked server.
|
|
497
606
|
|
|
498
607
|
## License
|
|
499
608
|
|
package/dist/connect-serve.d.ts
CHANGED
|
@@ -1,31 +1,60 @@
|
|
|
1
1
|
import type { Libp2p, PeerId } from "@libp2p/interface";
|
|
2
2
|
import type { Multiaddr } from "@multiformats/multiaddr";
|
|
3
|
-
import type { Connect,
|
|
4
|
-
|
|
3
|
+
import type { Connect, Serve } from "@statewalker/webrun-streams";
|
|
4
|
+
import { type ConnectionContext, DEFAULT_PROTOCOL, type ServeConnectionsHandler } from "./shared.js";
|
|
5
|
+
export { type ConnectionContext, DEFAULT_PROTOCOL, type ServeConnectionsHandler };
|
|
6
|
+
/**
|
|
7
|
+
* 4 MiB: the port window `connect`/`serve` grant unless told otherwise — the
|
|
8
|
+
* most one call moves per round trip, and the most a producer runs ahead of a
|
|
9
|
+
* consumer that stopped reading (statewalker/webrun-wire#153).
|
|
10
|
+
*
|
|
11
|
+
* A call moves at most `window / RTT`, so the window should be at least the
|
|
12
|
+
* link's bandwidth-delay product: 4 MiB covers 200 Mbit/s at 100 ms
|
|
13
|
+
* (2.5 MB). Raise it for faster or longer links; lower it (not below 64 KiB)
|
|
14
|
+
* to bound memory per call more tightly where the BDP is small — a window far
|
|
15
|
+
* above the bottleneck's queue only adds latency (bufferbloat).
|
|
16
|
+
*/
|
|
17
|
+
export declare const DEFAULT_WINDOW: number;
|
|
18
|
+
/**
|
|
19
|
+
* The protocol a call's stream negotiates for `connect`/`serve` configured
|
|
20
|
+
* with `protocol`: `protocol` with `/ports` appended, and `/window` after it
|
|
21
|
+
* when both ends run the window (always, between two releases from this one
|
|
22
|
+
* on). `protocol` itself is the deprecated protocol, still served, and dialled
|
|
23
|
+
* when a peer refuses this one.
|
|
24
|
+
*/
|
|
25
|
+
export declare function portProtocolOf(protocol: string): string;
|
|
5
26
|
export interface ConnectLibp2pParams {
|
|
6
27
|
node: Libp2p;
|
|
7
28
|
peer: PeerId | Multiaddr;
|
|
8
|
-
/**
|
|
29
|
+
/**
|
|
30
|
+
* The protocol id both ends are configured with; defaults to
|
|
31
|
+
* {@link DEFAULT_PROTOCOL}. Calls negotiate {@link portProtocolOf} it, and
|
|
32
|
+
* fall back to it (the deprecated protocol) against an older server.
|
|
33
|
+
*/
|
|
9
34
|
protocol?: string;
|
|
10
35
|
/**
|
|
11
|
-
*
|
|
12
|
-
*
|
|
36
|
+
* The port window in bytes (default {@link DEFAULT_WINDOW}, at least 64 KiB):
|
|
37
|
+
* the most this end holds of a call's response delivered and not yet read.
|
|
38
|
+
* The server's window bounds what a call sends ahead of it. Size it at
|
|
39
|
+
* least to the bandwidth-delay product of the link (see
|
|
40
|
+
* {@link DEFAULT_WINDOW}).
|
|
13
41
|
*/
|
|
14
|
-
|
|
42
|
+
window?: number;
|
|
15
43
|
/**
|
|
16
|
-
*
|
|
17
|
-
*
|
|
44
|
+
* Per-call inactivity timeout in ms, reset by any chunk in either direction
|
|
45
|
+
* (`webrun-rpc`'s `timeout`). Unset, the default, means none: a slow
|
|
46
|
+
* consumer is throttled, never failed.
|
|
18
47
|
*/
|
|
19
|
-
|
|
48
|
+
timeout?: number;
|
|
20
49
|
/**
|
|
21
|
-
* The largest frame
|
|
22
|
-
* malformed frame header, the call fails and the stream is aborted.
|
|
23
|
-
*
|
|
50
|
+
* The largest frame accepted from the peer on a call's stream; past it, or
|
|
51
|
+
* on a malformed frame header, the call fails and the stream is aborted.
|
|
52
|
+
* Default 64 MiB.
|
|
24
53
|
*/
|
|
25
54
|
maxFrameBytes?: number;
|
|
26
55
|
/**
|
|
27
|
-
* How many outgoing streams for
|
|
28
|
-
* the same time on one connection; passed through to `node.dialProtocol`.
|
|
56
|
+
* How many outgoing streams for the calls' protocol libp2p allows to be open
|
|
57
|
+
* at the same time on one connection; passed through to `node.dialProtocol`.
|
|
29
58
|
* Left unset, libp2p's own default (64) applies.
|
|
30
59
|
*/
|
|
31
60
|
maxOutboundStreams?: number;
|
|
@@ -33,86 +62,104 @@ export interface ConnectLibp2pParams {
|
|
|
33
62
|
* Opt-in to dialing over a connection with limits on how much data can be
|
|
34
63
|
* transferred or how long it can be open for (e.g. a relayed circuit);
|
|
35
64
|
* passed through to `node.dialProtocol`. Left unset, libp2p refuses to open
|
|
36
|
-
*
|
|
37
|
-
*
|
|
65
|
+
* the calls' streams on such a connection — this package does not decide
|
|
66
|
+
* that trade-off for the caller, it only exposes the knob.
|
|
38
67
|
*/
|
|
39
68
|
runOnLimitedConnection?: boolean;
|
|
40
|
-
}
|
|
41
|
-
export interface ServeLibp2pParams {
|
|
42
|
-
node: Libp2p;
|
|
43
|
-
/** libp2p protocol id; defaults to `/webrun-streams/1.0.0`. */
|
|
44
|
-
protocol?: string;
|
|
45
69
|
/**
|
|
46
|
-
*
|
|
47
|
-
*
|
|
48
|
-
*
|
|
49
|
-
*
|
|
70
|
+
* The deprecated protocol only (an older server): how long to wait for a
|
|
71
|
+
* backpressured stream to drain before dropping the peer; defaults to
|
|
72
|
+
* `DEFAULT_DRAIN_TIMEOUT_MS` (5 minutes).
|
|
73
|
+
*
|
|
74
|
+
* @deprecated Removed with the deprecated protocol, in the next release.
|
|
50
75
|
*/
|
|
51
76
|
drainTimeoutMs?: number;
|
|
52
77
|
/**
|
|
53
|
-
*
|
|
54
|
-
*
|
|
78
|
+
* The deprecated protocol only (an older server): response bytes held while
|
|
79
|
+
* the caller is not reading before the stream is paused (default 64 KiB).
|
|
80
|
+
*
|
|
81
|
+
* @deprecated Removed with the deprecated protocol, in the next release.
|
|
55
82
|
*/
|
|
56
83
|
readHighWaterBytes?: number;
|
|
84
|
+
}
|
|
85
|
+
export interface ServeLibp2pParams {
|
|
86
|
+
node: Libp2p;
|
|
57
87
|
/**
|
|
58
|
-
* The
|
|
59
|
-
*
|
|
60
|
-
*
|
|
88
|
+
* The protocol id both ends are configured with; defaults to
|
|
89
|
+
* {@link DEFAULT_PROTOCOL}. Calls arrive on {@link portProtocolOf} it; the
|
|
90
|
+
* id itself is served too, for older callers (the deprecated protocol).
|
|
61
91
|
*/
|
|
92
|
+
protocol?: string;
|
|
93
|
+
/**
|
|
94
|
+
* The port window in bytes (default {@link DEFAULT_WINDOW}, at least 64 KiB):
|
|
95
|
+
* the most this end holds of a call's request delivered and not yet read by
|
|
96
|
+
* the handler. See {@link ConnectLibp2pParams.window}.
|
|
97
|
+
*/
|
|
98
|
+
window?: number;
|
|
99
|
+
/** Per-call inactivity timeout in ms; see {@link ConnectLibp2pParams.timeout}. */
|
|
100
|
+
timeout?: number;
|
|
101
|
+
/** The largest frame accepted from the peer; see {@link ConnectLibp2pParams.maxFrameBytes}. */
|
|
62
102
|
maxFrameBytes?: number;
|
|
63
103
|
/**
|
|
64
|
-
* How many incoming streams for
|
|
65
|
-
* the same time on one connection; passed through to
|
|
66
|
-
* unset, libp2p's own default (32) applies — past it, a
|
|
67
|
-
* is reset rather than queued, so a caller
|
|
68
|
-
* in
|
|
104
|
+
* How many incoming streams for each served protocol libp2p allows to be
|
|
105
|
+
* open at the same time on one connection; passed through to
|
|
106
|
+
* `node.handle`. Left unset, libp2p's own default (32) applies — past it, a
|
|
107
|
+
* new inbound stream is reset rather than queued, so a caller with more
|
|
108
|
+
* calls in flight starts seeing rejected calls above that count.
|
|
69
109
|
*/
|
|
70
110
|
maxInboundStreams?: number;
|
|
71
111
|
/**
|
|
72
|
-
* How many outgoing streams for
|
|
73
|
-
* the same time on one connection; passed through to `node.handle`.
|
|
74
|
-
* unset, libp2p's own default (64) applies.
|
|
112
|
+
* How many outgoing streams for each served protocol libp2p allows to be
|
|
113
|
+
* open at the same time on one connection; passed through to `node.handle`.
|
|
114
|
+
* Left unset, libp2p's own default (64) applies.
|
|
75
115
|
*/
|
|
76
116
|
maxOutboundStreams?: number;
|
|
77
117
|
/**
|
|
78
|
-
* Opt-in to accepting
|
|
79
|
-
*
|
|
80
|
-
*
|
|
81
|
-
* unset, libp2p refuses to open this protocol's stream on such a
|
|
82
|
-
* connection — this package does not decide that trade-off for the
|
|
83
|
-
* consumer, it only exposes the knob.
|
|
118
|
+
* Opt-in to accepting calls over a connection with limits on how much data
|
|
119
|
+
* can be transferred or how long it can be open for (e.g. a relayed
|
|
120
|
+
* circuit); passed through to `node.handle`.
|
|
84
121
|
*/
|
|
85
122
|
runOnLimitedConnection?: boolean;
|
|
123
|
+
/**
|
|
124
|
+
* The deprecated protocol only (older callers): how long to wait for a
|
|
125
|
+
* backpressured stream to drain before dropping the peer (default 5 minutes).
|
|
126
|
+
*
|
|
127
|
+
* @deprecated Removed with the deprecated protocol, in the next release.
|
|
128
|
+
*/
|
|
129
|
+
drainTimeoutMs?: number;
|
|
130
|
+
/**
|
|
131
|
+
* The deprecated protocol only (older callers): request bytes held while the
|
|
132
|
+
* handler is not reading before the stream is paused (default 64 KiB).
|
|
133
|
+
*
|
|
134
|
+
* @deprecated Removed with the deprecated protocol, in the next release.
|
|
135
|
+
*/
|
|
136
|
+
readHighWaterBytes?: number;
|
|
86
137
|
}
|
|
87
138
|
/**
|
|
88
|
-
* Caller-side: each `call(input)`
|
|
89
|
-
* `
|
|
139
|
+
* Caller-side: each `call(input)` is one port of a windowed native port mux
|
|
140
|
+
* (`libp2pPortMux`): one libp2p stream negotiating {@link portProtocolOf}
|
|
141
|
+
* `protocol` with `/window`, over which `webrun-rpc`'s stream tier runs the
|
|
142
|
+
* call, pipelining up to the server's window per round trip. Streams are
|
|
143
|
+
* opened through the early-stream gate, so a burst of calls on a fresh
|
|
144
|
+
* connection does not kill its muxer.
|
|
145
|
+
*
|
|
146
|
+
* Against an older server, which refuses that protocol, the call falls back to
|
|
147
|
+
* the deprecated protocol on `protocol` itself, and the node remembers that
|
|
148
|
+
* for the connection, so later calls to that peer dial it directly. The
|
|
149
|
+
* fallback is removed in the next release.
|
|
90
150
|
*/
|
|
91
151
|
export declare const connect: Connect<ConnectLibp2pParams>;
|
|
92
152
|
/**
|
|
93
|
-
* Server-side:
|
|
94
|
-
*
|
|
95
|
-
*
|
|
153
|
+
* Server-side: serves each call as one port of a windowed native port mux
|
|
154
|
+
* (`<protocol>/ports`, with and without `/window`), and runs `handler` on it.
|
|
155
|
+
* Older callers are still answered on `protocol` itself, the deprecated
|
|
156
|
+
* protocol, until the next release. Identity-unaware; use `serveConnections`
|
|
157
|
+
* when the handler needs to know who is calling.
|
|
96
158
|
*/
|
|
97
159
|
export declare const serve: Serve<ServeLibp2pParams>;
|
|
98
|
-
/** What the serving side knows about the connection a stream arrived on. */
|
|
99
|
-
export interface ConnectionContext {
|
|
100
|
-
/**
|
|
101
|
-
* The peer id libp2p's Noise handshake proved for this connection. This is
|
|
102
|
-
* the only identity claim on the serving side that cannot be forged by the
|
|
103
|
-
* request payload.
|
|
104
|
-
*/
|
|
105
|
-
remotePeer: PeerId;
|
|
106
|
-
}
|
|
107
|
-
/**
|
|
108
|
-
* Builds a handler for one inbound connection. Called once per stream, so the
|
|
109
|
-
* connection stays reachable in the returned Duplex's closure — `Duplex` is
|
|
110
|
-
* bytes-only (ADR-0004) and gains no new parameter.
|
|
111
|
-
*/
|
|
112
|
-
export type ServeConnectionsHandler = (context: ConnectionContext) => Duplex;
|
|
113
160
|
/**
|
|
114
|
-
* Like `serve`, but the handler is built per
|
|
115
|
-
*
|
|
161
|
+
* Like `serve`, but the handler is built per call and is told which peer
|
|
162
|
+
* libp2p proved on the connection the call came on.
|
|
116
163
|
*/
|
|
117
|
-
export declare function serveConnections(
|
|
164
|
+
export declare function serveConnections(params: ServeLibp2pParams, makeHandler: ServeConnectionsHandler): Promise<() => Promise<void>>;
|
|
118
165
|
//# sourceMappingURL=connect-serve.d.ts.map
|