@statewalker/webrun-streams-libp2p 0.6.0 → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,47 +1,78 @@
1
- import type {
2
- Connection,
3
- DialProtocolOptions,
4
- Libp2p,
5
- PeerId,
6
- Stream,
7
- StreamHandlerOptions,
8
- } from "@libp2p/interface";
1
+ import type { Connection, Libp2p, PeerId } from "@libp2p/interface";
9
2
  import type { Multiaddr } from "@multiformats/multiaddr";
10
- import type { Connect, Duplex, Serve } from "@statewalker/webrun-streams";
3
+ import { deserialize, serialize } from "@statewalker/webrun-msgpack";
4
+ import { overPorts, connect as portConnect, serve as portServe } from "@statewalker/webrun-rpc";
5
+ import type { Connect, Duplex, Serve, ValueCodec } from "@statewalker/webrun-streams";
6
+ import { legacyConnect, legacyServeConnections } from "./legacy-connect-serve.js";
7
+ import { type InboundPortInfo, openLibp2pPortMux } from "./port-mux.js";
11
8
  import {
12
- closeStream,
13
- DEFAULT_READ_HIGH_WATER_BYTES,
14
- duplexOverStream,
15
- PeerGoneError,
16
- } from "./duplex-over-stream.js";
17
- import { openGatedStream } from "./stream-gate.js";
9
+ type ConnectionContext,
10
+ DEFAULT_PROTOCOL,
11
+ type ServeConnectionsHandler,
12
+ } from "./shared.js";
18
13
 
19
- export const DEFAULT_PROTOCOL = "/webrun-streams/1.0.0";
14
+ export { type ConnectionContext, DEFAULT_PROTOCOL, type ServeConnectionsHandler };
15
+
16
+ /**
17
+ * 4 MiB: the port window `connect`/`serve` grant unless told otherwise — the
18
+ * most one call moves per round trip, and the most a producer runs ahead of a
19
+ * consumer that stopped reading (statewalker/webrun-wire#153).
20
+ *
21
+ * A call moves at most `window / RTT`, so the window should be at least the
22
+ * link's bandwidth-delay product: 4 MiB covers 200 Mbit/s at 100 ms
23
+ * (2.5 MB). Raise it for faster or longer links; lower it (not below 64 KiB)
24
+ * to bound memory per call more tightly where the BDP is small — a window far
25
+ * above the bottleneck's queue only adds latency (bufferbloat).
26
+ */
27
+ export const DEFAULT_WINDOW = 4 * 1024 * 1024;
28
+
29
+ /**
30
+ * The protocol a call's stream negotiates for `connect`/`serve` configured
31
+ * with `protocol`: `protocol` with `/ports` appended, and `/window` after it
32
+ * when both ends run the window (always, between two releases from this one
33
+ * on). `protocol` itself is the deprecated protocol, still served, and dialled
34
+ * when a peer refuses this one.
35
+ */
36
+ export function portProtocolOf(protocol: string): string {
37
+ return `${protocol}/ports`;
38
+ }
39
+
40
+ /** What a call's messages are on the wire: msgpack, as `webrun-rpc`'s stream tier posts them. */
41
+ const codec: ValueCodec = { encode: serialize, decode: deserialize };
20
42
 
21
43
  export interface ConnectLibp2pParams {
22
44
  node: Libp2p;
23
45
  peer: PeerId | Multiaddr;
24
- /** libp2p protocol id; defaults to `/webrun-streams/1.0.0`. */
46
+ /**
47
+ * The protocol id both ends are configured with; defaults to
48
+ * {@link DEFAULT_PROTOCOL}. Calls negotiate {@link portProtocolOf} it, and
49
+ * fall back to it (the deprecated protocol) against an older server.
50
+ */
25
51
  protocol?: string;
26
52
  /**
27
- * How long to wait for a backpressured stream to drain before dropping the
28
- * peer; defaults to `DEFAULT_DRAIN_TIMEOUT_MS` (5 minutes).
53
+ * The port window in bytes (default {@link DEFAULT_WINDOW}, at least 64 KiB):
54
+ * the most this end holds of a call's response delivered and not yet read.
55
+ * It is also the most this end sends ahead of the server: a call's request
56
+ * runs at most min(the server's window, this window) ahead
57
+ * (statewalker/webrun-wire#195). Size it at least to the bandwidth-delay
58
+ * product of the link (see {@link DEFAULT_WINDOW}).
29
59
  */
30
- drainTimeoutMs?: number;
60
+ window?: number;
31
61
  /**
32
- * Response bytes held while the caller is not reading before the stream is
33
- * paused; see `DuplexOverStreamOptions.readHighWaterBytes` (default 64 KiB).
62
+ * Per-call inactivity timeout in ms, reset by any chunk in either direction
63
+ * (`webrun-rpc`'s `timeout`). Unset, the default, means none: a slow
64
+ * consumer is throttled, never failed.
34
65
  */
35
- readHighWaterBytes?: number;
66
+ timeout?: number;
36
67
  /**
37
- * The largest frame payload accepted from the peer; past it, or on a
38
- * malformed frame header, the call fails and the stream is aborted. See
39
- * `DuplexOverStreamOptions.maxFrameBytes` (default 64 MiB).
68
+ * The largest frame accepted from the peer on a call's stream; past it, or
69
+ * on a malformed frame header, the call fails and the stream is aborted.
70
+ * Default 64 MiB.
40
71
  */
41
72
  maxFrameBytes?: number;
42
73
  /**
43
- * How many outgoing streams for this protocol libp2p allows to be open at
44
- * the same time on one connection; passed through to `node.dialProtocol`.
74
+ * How many outgoing streams for the calls' protocol libp2p allows to be open
75
+ * at the same time on one connection; passed through to `node.dialProtocol`.
45
76
  * Left unset, libp2p's own default (64) applies.
46
77
  */
47
78
  maxOutboundStreams?: number;
@@ -49,384 +80,366 @@ export interface ConnectLibp2pParams {
49
80
  * Opt-in to dialing over a connection with limits on how much data can be
50
81
  * transferred or how long it can be open for (e.g. a relayed circuit);
51
82
  * passed through to `node.dialProtocol`. Left unset, libp2p refuses to open
52
- * this protocol's stream on such a connection — this package does not
53
- * decide that trade-off for the caller, it only exposes the knob.
83
+ * the calls' streams on such a connection — this package does not decide
84
+ * that trade-off for the caller, it only exposes the knob.
54
85
  */
55
86
  runOnLimitedConnection?: boolean;
56
- }
57
-
58
- export interface ServeLibp2pParams {
59
- node: Libp2p;
60
- /** libp2p protocol id; defaults to `/webrun-streams/1.0.0`. */
61
- protocol?: string;
62
87
  /**
63
- * How long to wait for a backpressured stream to drain before dropping the
64
- * peer; defaults to `DEFAULT_DRAIN_TIMEOUT_MS` (5 minutes). This is the only
65
- * bound on a peer that requests something and then stops reading without
66
- * closing, since the caller-side `.return`/abort escape does not exist here.
88
+ * How long, in ms, a write may wait for a call's stream to drain (the
89
+ * server stopped reading at the transport) before the stream is reset and
90
+ * the call fails; defaults to `DEFAULT_DRAIN_TIMEOUT_MS` (5 minutes). Only
91
+ * a write blocked on drain counts: a quiet call is never timed out. Applies
92
+ * to the port protocol (statewalker/webrun-wire#195) and to the deprecated
93
+ * one. On the port protocol, 0 or `Infinity` means no bound (the deprecated
94
+ * protocol drops a backpressured stream at once on 0).
67
95
  */
68
96
  drainTimeoutMs?: number;
69
97
  /**
70
- * Request bytes held while the handler is not reading before the stream is
71
- * paused; see `DuplexOverStreamOptions.readHighWaterBytes` (default 64 KiB).
98
+ * The deprecated protocol only (an older server): response bytes held while
99
+ * the caller is not reading before the stream is paused (default 64 KiB).
100
+ *
101
+ * @deprecated Removed with the deprecated protocol, in the next release.
72
102
  */
73
103
  readHighWaterBytes?: number;
104
+ }
105
+
106
+ export interface ServeLibp2pParams {
107
+ node: Libp2p;
74
108
  /**
75
- * The largest frame payload accepted from the peer; past it, or on a
76
- * malformed frame header, the call fails and the stream is aborted. See
77
- * `DuplexOverStreamOptions.maxFrameBytes` (default 64 MiB).
109
+ * The protocol id both ends are configured with; defaults to
110
+ * {@link DEFAULT_PROTOCOL}. Calls arrive on {@link portProtocolOf} it; the
111
+ * id itself is served too, for older callers (the deprecated protocol).
78
112
  */
113
+ protocol?: string;
114
+ /**
115
+ * The port window in bytes (default {@link DEFAULT_WINDOW}, at least 64 KiB):
116
+ * the most this end holds of a call's request delivered and not yet read by
117
+ * the handler. It is also the most a response runs ahead of its caller,
118
+ * whatever window the caller announces (up to 4 GiB): min(the caller's
119
+ * window, this window) (statewalker/webrun-wire#195). See
120
+ * {@link ConnectLibp2pParams.window}.
121
+ */
122
+ window?: number;
123
+ /** Per-call inactivity timeout in ms; see {@link ConnectLibp2pParams.timeout}. */
124
+ timeout?: number;
125
+ /** The largest frame accepted from the peer; see {@link ConnectLibp2pParams.maxFrameBytes}. */
79
126
  maxFrameBytes?: number;
80
127
  /**
81
- * How many incoming streams for this protocol libp2p allows to be open at
82
- * the same time on one connection; passed through to `node.handle`. Left
83
- * unset, libp2p's own default (32) applies — past it, a new inbound stream
84
- * is reset rather than queued, so a caller that opens one stream per
85
- * in-flight request will start seeing rejected calls above that count.
128
+ * How many incoming streams for each served protocol libp2p allows to be
129
+ * open at the same time on one connection; passed through to
130
+ * `node.handle`. Left unset, libp2p's own default (32) applies — past it, a
131
+ * new inbound stream is reset rather than queued, so a caller with more
132
+ * calls in flight starts seeing rejected calls above that count.
86
133
  */
87
134
  maxInboundStreams?: number;
88
135
  /**
89
- * How many outgoing streams for this protocol libp2p allows to be open at
90
- * the same time on one connection; passed through to `node.handle`. Left
91
- * unset, libp2p's own default (64) applies.
136
+ * How many outgoing streams for each served protocol libp2p allows to be
137
+ * open at the same time on one connection; passed through to `node.handle`.
138
+ * Left unset, libp2p's own default (64) applies.
92
139
  */
93
140
  maxOutboundStreams?: number;
94
141
  /**
95
- * Opt-in to accepting streams for this protocol over a connection with
96
- * limits on how much data can be transferred or how long it can be open
97
- * for (e.g. a relayed circuit); passed through to `node.handle`. Left
98
- * unset, libp2p refuses to open this protocol's stream on such a
99
- * connection — this package does not decide that trade-off for the
100
- * consumer, it only exposes the knob.
142
+ * Opt-in to accepting calls over a connection with limits on how much data
143
+ * can be transferred or how long it can be open for (e.g. a relayed
144
+ * circuit); passed through to `node.handle`.
101
145
  */
102
146
  runOnLimitedConnection?: boolean;
147
+ /**
148
+ * How long, in ms, a write may wait for a call's stream to drain (the
149
+ * caller stopped reading at the transport) before the stream is reset and
150
+ * the handler's output is abandoned; defaults to `DEFAULT_DRAIN_TIMEOUT_MS`
151
+ * (5 minutes). This bounds what a stalled caller holds on the server: with
152
+ * the window (at most min(the caller's window, `window`) ahead) and the
153
+ * stream's backpressure (nothing written while it needs to drain), a
154
+ * stalled call holds about one frame, for at most this long. Only a write
155
+ * blocked on drain counts: a quiet call (an event stream between events) is
156
+ * never timed out. Credit for the caller's upload is held back while the
157
+ * stream needs to drain, and counts too (a caller that uploads and never
158
+ * reads is dropped). Applies to the port protocol
159
+ * (statewalker/webrun-wire#195) and to the deprecated one. On the port
160
+ * protocol, 0 or `Infinity` means no bound (the deprecated protocol drops a
161
+ * backpressured stream at once on 0).
162
+ */
163
+ drainTimeoutMs?: number;
164
+ /**
165
+ * The deprecated protocol only (older callers): request bytes held while the
166
+ * handler is not reading before the stream is paused (default 64 KiB).
167
+ *
168
+ * @deprecated Removed with the deprecated protocol, in the next release.
169
+ */
170
+ readHighWaterBytes?: number;
103
171
  }
104
172
 
105
173
  /**
106
- * Builds the options object passed to `node.dialProtocol`/`node.handle`,
107
- * omitting any field the caller didn't supply rather than setting it to
108
- * `undefined` — so an unset field falls back to libp2p's own default instead
109
- * of an explicit `undefined` overriding it.
110
- */
111
- function definedOptions<T extends Record<string, unknown>>(fields: T): Partial<T> | undefined {
112
- const options: Partial<T> = {};
113
- let any = false;
114
- for (const key of Object.keys(fields) as (keyof T)[]) {
115
- const value = fields[key];
116
- if (value !== undefined) {
117
- options[key] = value;
118
- any = true;
119
- }
120
- }
121
- return any ? options : undefined;
122
- }
123
-
124
- /**
125
- * Caller-side: each `call(input)` opens a new libp2p `Stream` via
126
- * `node.dialProtocol(peer, [protocol])` and runs the call over it.
174
+ * Caller-side: each `call(input)` is one port of a windowed native port mux
175
+ * (`libp2pPortMux`): one libp2p stream negotiating {@link portProtocolOf}
176
+ * `protocol` with `/window`, over which `webrun-rpc`'s stream tier runs the
177
+ * call, pipelining up to the server's window per round trip. Streams are
178
+ * opened through the early-stream gate, so a burst of calls on a fresh
179
+ * connection does not kill its muxer.
180
+ *
181
+ * Against an older server, which refuses that protocol, the call falls back to
182
+ * the deprecated protocol on `protocol` itself, and the node remembers that
183
+ * for the connection, so later calls to that peer dial it directly. The
184
+ * fallback is removed in the next release.
127
185
  */
128
- export const connect: Connect<ConnectLibp2pParams> = async ({
129
- node,
130
- peer,
131
- protocol,
132
- drainTimeoutMs,
133
- readHighWaterBytes,
134
- maxFrameBytes,
135
- maxOutboundStreams,
136
- runOnLimitedConnection,
137
- }) => {
138
- const proto = protocol ?? DEFAULT_PROTOCOL;
139
- const dialOptions: DialProtocolOptions | undefined = definedOptions({
186
+ export const connect: Connect<ConnectLibp2pParams> = async (params) => {
187
+ const { node, peer, maxFrameBytes, maxOutboundStreams, runOnLimitedConnection } = params;
188
+ const protocol = params.protocol ?? DEFAULT_PROTOCOL;
189
+ const ports = await portConnect({
190
+ mux: overPorts(() =>
191
+ openLibp2pPortMux(
192
+ {
193
+ node,
194
+ peer,
195
+ codec,
196
+ protocol: portProtocolOf(protocol),
197
+ window: params.window ?? DEFAULT_WINDOW,
198
+ drainTimeoutMs: params.drainTimeoutMs,
199
+ maxMessageBytes: maxFrameBytes,
200
+ maxOutboundStreams,
201
+ runOnLimitedConnection,
202
+ },
203
+ undefined,
204
+ ),
205
+ ),
206
+ timeout: params.timeout,
207
+ });
208
+ // The deprecated protocol, for a server that refuses the port protocol.
209
+ const legacy = await legacyConnect({
210
+ node,
211
+ peer,
212
+ protocol,
213
+ drainTimeoutMs: params.drainTimeoutMs,
214
+ readHighWaterBytes: params.readHighWaterBytes,
215
+ maxFrameBytes,
140
216
  maxOutboundStreams,
141
217
  runOnLimitedConnection,
142
218
  });
143
- const open = new Set<Stream>();
144
-
145
- // A burst of calls must not reach the remote before its muxer is ready.
146
- //
147
- // When there is no connection to the peer yet, every call dials it and they
148
- // all share the one connection libp2p establishes. Their streams can arrive
149
- // while the REMOTE side is still upgrading that connection, and yamux counts
150
- // those "early streams": past `maxEarlyStreams` (10 by default) it aborts the
151
- // whole muxer, so every stream on the connection dies — the remote sees EOF
152
- // during protocol negotiation, this side sees `StreamResetError`. Raising the
153
- // limit on our own nodes would not help against any other libp2p peer.
154
- //
155
- // So until one stream has negotiated its protocol on an open connection, the
156
- // calls open their streams one at a time: a completed negotiation means the
157
- // remote has finished its upgrade, and from then on streams are not early and
158
- // open concurrently. If that connection closes, the next burst is gated again.
159
- // The state is shared by every connect() to the same peer from the same node
160
- // (callers often connect() per request), since they all share its connection.
161
- const openStream = (): Promise<Stream> => openGatedStream(node, peer, proto, dialOptions);
162
219
 
163
220
  const call: Duplex = (input) => {
164
- let streamRef: Stream | null = null;
165
- const gen = (async function* () {
166
- const stream = await openStream();
167
- streamRef = stream;
168
- open.add(stream);
169
- let sourceCompleted = false;
170
- try {
171
- yield* duplexOverStream(stream, input, {
172
- drainTimeoutMs,
173
- readHighWaterBytes,
174
- maxFrameBytes,
175
- onSourceCompleted: () => {
176
- sourceCompleted = true;
177
- },
178
- });
179
- } finally {
180
- open.delete(stream);
181
- if (sourceCompleted) {
182
- // Natural end on both sides. Graceful close, bounded so a peer
183
- // that stops reading without resetting can't hang this forever.
184
- await closeStream(stream);
185
- }
186
- // Else: consumer cancelled. The .return override below has already
187
- // called stream.abort to send RST; nothing more to do here.
188
- }
189
- })();
190
-
191
- // Send a yamux RST to peer when the consumer cancels (i.e., calls .return
192
- // on this generator). Doing it here is essential because by the time the
193
- // generator's own finally runs, the for-await teardown chain has already
194
- // marked the stream's status as `closed` — and AbstractStream.abort is a
195
- // no-op on closed streams.
196
- const origReturn = gen.return.bind(gen);
197
- gen.return = async (value: unknown) => {
198
- if (streamRef) {
199
- try {
200
- streamRef.abort(new Error("call cancelled"));
201
- } catch {
202
- /* ignore */
203
- }
204
- }
205
- return origReturn(value as undefined);
206
- };
207
-
208
- return gen;
221
+ if (isLegacyPeer(node, peer, protocol)) return legacy.call(input);
222
+ return withFallback(
223
+ ports.call(input),
224
+ () => legacy.call(input),
225
+ (err) => {
226
+ if (!isUnsupportedProtocol(err)) return false;
227
+ markLegacyPeer(node, peer, protocol);
228
+ return true;
229
+ },
230
+ );
209
231
  };
232
+
210
233
  return {
211
234
  call,
212
235
  async close() {
213
- for (const s of open) {
214
- try {
215
- s.abort(new Error("connection close"));
216
- } catch {
217
- /* ignore */
218
- }
219
- }
236
+ await Promise.allSettled([ports.close(), legacy.close()]);
220
237
  },
221
238
  };
222
239
  };
223
240
 
224
241
  /**
225
- * Server-side: registers `node.handle(protocol, ...)`. Each inbound stream is
226
- * wrapped as a `Duplex` and handed to `handler`. Identity-unaware; use
227
- * `serveConnections` when the handler needs to know who is calling.
242
+ * Server-side: serves each call as one port of a windowed native port mux
243
+ * (`<protocol>/ports`, with and without `/window`), and runs `handler` on it.
244
+ * Older callers are still answered on `protocol` itself, the deprecated
245
+ * protocol, until the next release. Identity-unaware; use `serveConnections`
246
+ * when the handler needs to know who is calling.
228
247
  */
229
248
  export const serve: Serve<ServeLibp2pParams> = async (params, handler: Duplex) =>
230
249
  serveConnections(params, () => handler);
231
250
 
232
- /** What the serving side knows about the connection a stream arrived on. */
233
- export interface ConnectionContext {
234
- /**
235
- * The peer id libp2p's Noise handshake proved for this connection. This is
236
- * the only identity claim on the serving side that cannot be forged by the
237
- * request payload.
238
- */
239
- remotePeer: PeerId;
240
- }
241
-
242
251
  /**
243
- * Builds a handler for one inbound connection. Called once per stream, so the
244
- * connection stays reachable in the returned Duplex's closure — `Duplex` is
245
- * bytes-only (ADR-0004) and gains no new parameter.
246
- */
247
- export type ServeConnectionsHandler = (context: ConnectionContext) => Duplex;
248
-
249
- /**
250
- * Like `serve`, but the handler is built per inbound stream and is told which
251
- * peer libp2p proved on that connection.
252
+ * Like `serve`, but the handler is built per call and is told which peer
253
+ * libp2p proved on the connection the call came on.
252
254
  */
253
255
  export async function serveConnections(
254
- {
255
- node,
256
- protocol,
257
- drainTimeoutMs,
258
- readHighWaterBytes,
259
- maxFrameBytes,
260
- maxInboundStreams,
261
- maxOutboundStreams,
262
- runOnLimitedConnection,
263
- }: ServeLibp2pParams,
256
+ params: ServeLibp2pParams,
264
257
  makeHandler: ServeConnectionsHandler,
265
258
  ): Promise<() => Promise<void>> {
266
- const proto = protocol ?? DEFAULT_PROTOCOL;
267
- const handleOptions: StreamHandlerOptions | undefined = definedOptions({
268
- maxInboundStreams,
269
- maxOutboundStreams,
270
- runOnLimitedConnection,
271
- });
259
+ const { node, maxFrameBytes, maxInboundStreams, maxOutboundStreams, runOnLimitedConnection } =
260
+ params;
261
+ const protocol = params.protocol ?? DEFAULT_PROTOCOL;
272
262
 
273
- const onStream = (stream: Stream, connection: Connection): void => {
274
- // The caller sent its whole request; a stream that dies after that is a
275
- // caller that stopped reading the response — ordinary, not a fault.
276
- let requestComplete = false;
277
- void (async () => {
278
- const handler = makeHandler({ remotePeer: connection.remotePeer });
279
- const inputQueue = makeInputQueue(readHighWaterBytes ?? DEFAULT_READ_HIGH_WATER_BYTES);
280
- // once the handler's output has ended, input it never started to read is
281
- // dropped instead of waited for (input it is reading, perhaps in the
282
- // background, keeps flowing at its pace)
283
- const output = endsWith(handler(inputQueue.iter()), () => inputQueue.abandon());
284
- try {
285
- for await (const chunk of duplexOverStream(stream, output, {
286
- drainTimeoutMs,
287
- readHighWaterBytes,
288
- maxFrameBytes,
289
- onPeerInputEnd: (err) => {
290
- if (err === undefined) requestComplete = true;
291
- inputQueue.done(err);
263
+ // The connection of the port being accepted. The stream tier installs the
264
+ // handler synchronously, inside the mux's `onPort` (`webrun-rpc`'s `serve`
265
+ // calls `serveDuplexOverPort`, which calls the handler at once), so the
266
+ // handler below reads the info of its own port.
267
+ let arriving: InboundPortInfo | undefined;
268
+ const stopPorts = await portServe(
269
+ {
270
+ mux: overPorts((onPort) =>
271
+ openLibp2pPortMux(
272
+ {
273
+ node,
274
+ codec,
275
+ protocol: portProtocolOf(protocol),
276
+ window: params.window ?? DEFAULT_WINDOW,
277
+ drainTimeoutMs: params.drainTimeoutMs,
278
+ maxMessageBytes: maxFrameBytes,
279
+ maxInboundStreams,
280
+ maxOutboundStreams,
281
+ runOnLimitedConnection,
282
+ onPort:
283
+ onPort &&
284
+ ((port, info) => {
285
+ arriving = info;
286
+ try {
287
+ return onPort(port, info);
288
+ } finally {
289
+ arriving = undefined;
290
+ }
291
+ }),
292
292
  },
293
- })) {
294
- // past readHighWaterBytes queued for the handler, the next chunk is
295
- // read only once it took this one: a handler that stops reading
296
- // pauses the stream (see readHighWaterBytes)
297
- await inputQueue.push(chunk);
298
- }
299
- } finally {
300
- inputQueue.done();
301
- await closeStream(stream);
302
- }
303
- })().catch((err: unknown) => {
304
- // One inbound stream failing must not take down the process serving
305
- // every other peer. `duplexOverStream` rejects on the read side
306
- // whenever the peer sends an ERROR frame or resets mid-request — which
307
- // happens in ordinary use, not just under attack (a browser tab closed
308
- // mid-request resets its streams). Without this catch that rejection is
309
- // unhandled, and Node's default for `unhandledRejection` is to
310
- // terminate. Logged rather than rethrown, and never rethrown from here:
311
- // there is no caller left to receive it.
312
- if (requestComplete && err instanceof PeerGoneError) return;
313
- const e = err instanceof Error ? err : new Error(String(err));
314
- console.warn(
315
- `[webrun-streams-libp2p] serve: inbound stream on protocol ${proto} failed: ${e.message}`,
316
- e,
317
- );
318
- });
319
- };
293
+ undefined,
294
+ ),
295
+ ),
296
+ timeout: params.timeout,
297
+ },
298
+ (input) => {
299
+ const info = arriving;
300
+ if (!info) throw new Error("webrun-streams-libp2p: a call arrived without its connection");
301
+ return makeHandler({ remotePeer: info.remotePeer })(input);
302
+ },
303
+ );
320
304
 
321
- await node.handle(proto, onStream, handleOptions);
305
+ // The deprecated protocol, for older callers.
306
+ let stopLegacy: () => Promise<void>;
307
+ try {
308
+ stopLegacy = await legacyServeConnections(
309
+ {
310
+ node,
311
+ protocol,
312
+ drainTimeoutMs: params.drainTimeoutMs,
313
+ readHighWaterBytes: params.readHighWaterBytes,
314
+ maxFrameBytes,
315
+ maxInboundStreams,
316
+ maxOutboundStreams,
317
+ runOnLimitedConnection,
318
+ },
319
+ makeHandler,
320
+ );
321
+ } catch (err) {
322
+ await stopPorts();
323
+ throw err;
324
+ }
322
325
 
323
326
  let torn = false;
324
327
  return async () => {
325
328
  if (torn) return;
326
329
  torn = true;
327
- await node.unhandle(proto);
330
+ await Promise.all([stopPorts(), stopLegacy()]);
328
331
  };
329
332
  }
330
333
 
331
- /** `source`, calling `onEnd` once when it ends, fails or is returned. */
332
- function endsWith(
333
- source: AsyncIterable<Uint8Array>,
334
- onEnd: () => void,
335
- ): AsyncGenerator<Uint8Array> {
336
- return (async function* () {
337
- try {
338
- yield* source;
339
- } finally {
340
- onEnd();
341
- }
342
- })();
343
- }
344
-
345
- interface InputQueue {
346
- iter(): AsyncGenerator<Uint8Array>;
347
- /**
348
- * resolves at once while the bytes queued for the handler stay within the
349
- * limit, else once the handler has read them back down to it (or will never
350
- * read on)
351
- */
352
- push(chunk: Uint8Array): Promise<void>;
353
- done(err?: Error): void;
354
- /**
355
- * the handler's output ended: if it never started reading its input, pending
356
- * and later chunks are dropped (an iterator started already is left to its
357
- * reader, which may go on reading after the output ended)
358
- */
359
- abandon(): void;
334
+ /** Whether `err` says the peer speaks none of the protocols dialled. */
335
+ function isUnsupportedProtocol(err: unknown): boolean {
336
+ return err instanceof Error && err.name === "UnsupportedProtocolError";
360
337
  }
361
338
 
362
- function makeInputQueue(limit: number): InputQueue {
363
- type Slot = { type: "value"; value: Uint8Array } | { type: "done"; err?: Error };
364
- const slots: Slot[] = [];
365
- let wake: (() => void) | null = null;
366
- let closed = false;
367
- let pulled = false;
368
- let queued = 0;
369
- // the one push waiting for room (the serving loop awaits each push)
370
- let room: (() => void) | null = null;
371
- const makeRoom = (): void => {
372
- const r = room;
373
- room = null;
374
- r?.();
375
- };
376
- const release = (): void => {
377
- slots.length = 0;
378
- queued = 0;
379
- makeRoom();
380
- };
381
- return {
382
- iter(): AsyncGenerator<Uint8Array> {
383
- return (async function* () {
384
- if (closed) return; // abandoned before anyone read: the input was dropped
385
- pulled = true;
386
- try {
387
- while (true) {
388
- if (slots.length === 0) {
389
- await new Promise<void>((r) => {
390
- wake = r;
391
- });
392
- wake = null;
393
- continue;
394
- }
395
- const s = slots.shift() as Slot;
396
- if (s.type === "done") {
397
- if (s.err) throw s.err;
398
- return;
399
- }
400
- queued -= s.value.byteLength;
401
- if (queued <= limit) makeRoom();
402
- yield s.value;
403
- }
404
- } finally {
405
- closed = true;
406
- release();
339
+ /**
340
+ * `primary`, except that when its first `next()` rejects with an error
341
+ * `fallBack` accepts — the port protocol refused, before any of the input was
342
+ * read — the call runs on `fallback()` instead. `return()` and `throw()` go
343
+ * straight to the current call, so a consumer that gives up on a pending
344
+ * `next()` is heard at once, as by the call itself.
345
+ */
346
+ function withFallback(
347
+ primary: AsyncGenerator<Uint8Array>,
348
+ fallback: () => AsyncGenerator<Uint8Array>,
349
+ fallBack: (err: unknown) => boolean,
350
+ ): AsyncGenerator<Uint8Array> {
351
+ let current = primary;
352
+ let settled = false;
353
+ const wrapped: Pick<
354
+ AsyncGenerator<Uint8Array>,
355
+ "next" | "return" | "throw" | typeof Symbol.asyncIterator
356
+ > = {
357
+ async next(...args: [] | [unknown]) {
358
+ if (settled) return current.next(...args);
359
+ try {
360
+ const result = await current.next(...args);
361
+ settled = true;
362
+ return result;
363
+ } catch (err) {
364
+ if (settled || !fallBack(err)) {
365
+ settled = true;
366
+ throw err;
407
367
  }
408
- })();
368
+ settled = true;
369
+ current = fallback();
370
+ return current.next(...args);
371
+ }
409
372
  },
410
- push(chunk: Uint8Array): Promise<void> {
411
- if (closed) return Promise.resolve();
412
- slots.push({ type: "value", value: chunk });
413
- queued += chunk.byteLength;
414
- wake?.();
415
- if (queued <= limit) return Promise.resolve();
416
- return new Promise<void>((resolve) => {
417
- room = resolve;
418
- });
373
+ return(value) {
374
+ settled = true;
375
+ return current.return(value);
419
376
  },
420
- done(err?: Error): void {
421
- if (closed) return;
422
- slots.push({ type: "done", err });
423
- wake?.();
377
+ throw(error) {
378
+ settled = true;
379
+ return current.throw(error);
424
380
  },
425
- abandon(): void {
426
- if (pulled) return;
427
- closed = true;
428
- release();
429
- wake?.();
381
+ [Symbol.asyncIterator]() {
382
+ return wrapped as AsyncGenerator<Uint8Array>;
430
383
  },
431
384
  };
385
+ // `await using` ends the call as leaving a `for await` early does.
386
+ const asyncDispose = (Symbol as { asyncDispose?: symbol }).asyncDispose;
387
+ if (asyncDispose) {
388
+ Object.defineProperty(wrapped, asyncDispose, {
389
+ value: async () => {
390
+ await wrapped.return(undefined);
391
+ },
392
+ configurable: true,
393
+ writable: true,
394
+ });
395
+ }
396
+ return wrapped as AsyncGenerator<Uint8Array>;
397
+ }
398
+
399
+ /**
400
+ * Peers known to refuse the port protocol, per local node, by peer and
401
+ * protocol: the connection the refusal came on (`null` when the node cannot
402
+ * tell), so a peer that restarts upgraded is probed again on its next
403
+ * connection.
404
+ */
405
+ const legacyPeers = new WeakMap<Libp2p, Map<string, { connection: Connection | null }>>();
406
+
407
+ const legacyKey = (peer: PeerId | Multiaddr, protocol: string) => `${peer.toString()} ${protocol}`;
408
+
409
+ function isLegacyPeer(node: Libp2p, peer: PeerId | Multiaddr, protocol: string): boolean {
410
+ const peers = legacyPeers.get(node);
411
+ const mark = peers?.get(legacyKey(peer, protocol));
412
+ if (!mark) return false;
413
+ if (mark.connection == null || mark.connection.status === "open") return true;
414
+ peers?.delete(legacyKey(peer, protocol));
415
+ return false;
416
+ }
417
+
418
+ function markLegacyPeer(node: Libp2p, peer: PeerId | Multiaddr, protocol: string): void {
419
+ let peers = legacyPeers.get(node);
420
+ if (!peers) {
421
+ peers = new Map();
422
+ legacyPeers.set(node, peers);
423
+ }
424
+ peers.set(legacyKey(peer, protocol), { connection: connectionTo(node, peer) });
425
+ }
426
+
427
+ /**
428
+ * The open connection to `peer`, when `node` can list its connections (a
429
+ * narrow stand-in may offer only `dialProtocol`).
430
+ */
431
+ function connectionTo(node: Libp2p, peer: PeerId | Multiaddr): Connection | null {
432
+ if (typeof node.getConnections !== "function") return null;
433
+ const target = peer.toString();
434
+ return (
435
+ node
436
+ .getConnections()
437
+ .find(
438
+ (c) =>
439
+ c.status === "open" &&
440
+ (c.remotePeer.toString() === target ||
441
+ c.remoteAddr.toString() === target ||
442
+ target.endsWith(`/p2p/${c.remotePeer.toString()}`)),
443
+ ) ?? null
444
+ );
432
445
  }