@statewalker/webrun-streams-libp2p 0.2.0 → 0.3.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.
@@ -8,7 +8,13 @@ import type {
8
8
  } from "@libp2p/interface";
9
9
  import type { Multiaddr } from "@multiformats/multiaddr";
10
10
  import type { Connect, Duplex, Serve } from "@statewalker/webrun-streams";
11
- import { closeStream, duplexOverStream, PeerGoneError } from "./duplex-over-stream.js";
11
+ 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";
12
18
 
13
19
  export const DEFAULT_PROTOCOL = "/webrun-streams/1.0.0";
14
20
 
@@ -22,6 +28,11 @@ export interface ConnectLibp2pParams {
22
28
  * peer; defaults to `DEFAULT_DRAIN_TIMEOUT_MS` (5 minutes).
23
29
  */
24
30
  drainTimeoutMs?: number;
31
+ /**
32
+ * Response bytes held while the caller is not reading before the stream is
33
+ * paused; see `DuplexOverStreamOptions.readHighWaterBytes` (default 64 KiB).
34
+ */
35
+ readHighWaterBytes?: number;
25
36
  /**
26
37
  * How many outgoing streams for this protocol libp2p allows to be open at
27
38
  * the same time on one connection; passed through to `node.dialProtocol`.
@@ -49,6 +60,11 @@ export interface ServeLibp2pParams {
49
60
  * closing, since the caller-side `.return`/abort escape does not exist here.
50
61
  */
51
62
  drainTimeoutMs?: number;
63
+ /**
64
+ * Request bytes held while the handler is not reading before the stream is
65
+ * paused; see `DuplexOverStreamOptions.readHighWaterBytes` (default 64 KiB).
66
+ */
67
+ readHighWaterBytes?: number;
52
68
  /**
53
69
  * How many incoming streams for this protocol libp2p allows to be open at
54
70
  * the same time on one connection; passed through to `node.handle`. Left
@@ -97,56 +113,12 @@ function definedOptions<T extends Record<string, unknown>>(fields: T): Partial<T
97
113
  * Caller-side: each `call(input)` opens a new libp2p `Stream` via
98
114
  * `node.dialProtocol(peer, [protocol])` and runs the call over it.
99
115
  */
100
- /** The early-stream guard of `connect()`, per local node and remote peer. */
101
- interface StreamGate {
102
- /**
103
- * A stream has negotiated a protocol on an open connection: the remote is ready.
104
- * `connection` is that connection when the node can tell (`getConnections`), so a
105
- * burst after it closes is gated again; a node that offers only `dialProtocol`
106
- * stays proven.
107
- */
108
- proven: { connection: Connection | null } | null;
109
- /** The stream being opened while no connection is proven; the others wait for it. */
110
- firstOpening: Promise<Stream> | null;
111
- }
112
-
113
- const streamGates = new WeakMap<Libp2p, Map<string, StreamGate>>();
114
-
115
- function streamGateFor(node: Libp2p, peer: PeerId | Multiaddr): StreamGate {
116
- let gates = streamGates.get(node);
117
- if (gates == null) {
118
- gates = new Map();
119
- streamGates.set(node, gates);
120
- }
121
- const key = peer.toString();
122
- let gate = gates.get(key);
123
- if (gate == null) {
124
- gate = { proven: null, firstOpening: null };
125
- gates.set(key, gate);
126
- }
127
- return gate;
128
- }
129
-
130
- function isProven(gate: StreamGate): boolean {
131
- if (gate.proven == null) return false;
132
- return gate.proven.connection == null || gate.proven.connection.status === "open";
133
- }
134
-
135
- /**
136
- * The connection carrying `stream`, when `node` can list its connections.
137
- * Callers may pass a narrow stand-in that offers only `dialProtocol` (httpeers
138
- * routes streams onto a kept relay circuit that way), so nothing else is required.
139
- */
140
- function connectionOf(node: Libp2p, stream: Stream): Connection | null {
141
- if (typeof node.getConnections !== "function") return null;
142
- return node.getConnections().find((connection) => connection.streams.includes(stream)) ?? null;
143
- }
144
-
145
116
  export const connect: Connect<ConnectLibp2pParams> = async ({
146
117
  node,
147
118
  peer,
148
119
  protocol,
149
120
  drainTimeoutMs,
121
+ readHighWaterBytes,
150
122
  maxOutboundStreams,
151
123
  runOnLimitedConnection,
152
124
  }) => {
@@ -173,24 +145,7 @@ export const connect: Connect<ConnectLibp2pParams> = async ({
173
145
  // open concurrently. If that connection closes, the next burst is gated again.
174
146
  // The state is shared by every connect() to the same peer from the same node
175
147
  // (callers often connect() per request), since they all share its connection.
176
- const gate = streamGateFor(node, peer);
177
- const openStream = async (): Promise<Stream> => {
178
- while (!isProven(gate)) {
179
- if (gate.firstOpening == null) {
180
- const opening = node.dialProtocol(peer, [proto], dialOptions);
181
- gate.firstOpening = opening;
182
- try {
183
- const stream = await opening;
184
- gate.proven = { connection: connectionOf(node, stream) };
185
- return stream;
186
- } finally {
187
- gate.firstOpening = null;
188
- }
189
- }
190
- await gate.firstOpening.catch(() => undefined);
191
- }
192
- return node.dialProtocol(peer, [proto], dialOptions);
193
- };
148
+ const openStream = (): Promise<Stream> => openGatedStream(node, peer, proto, dialOptions);
194
149
 
195
150
  const call: Duplex = (input) => {
196
151
  let streamRef: Stream | null = null;
@@ -202,6 +157,7 @@ export const connect: Connect<ConnectLibp2pParams> = async ({
202
157
  try {
203
158
  yield* duplexOverStream(stream, input, {
204
159
  drainTimeoutMs,
160
+ readHighWaterBytes,
205
161
  onSourceCompleted: () => {
206
162
  sourceCompleted = true;
207
163
  },
@@ -285,6 +241,7 @@ export async function serveConnections(
285
241
  node,
286
242
  protocol,
287
243
  drainTimeoutMs,
244
+ readHighWaterBytes,
288
245
  maxInboundStreams,
289
246
  maxOutboundStreams,
290
247
  runOnLimitedConnection,
@@ -304,17 +261,24 @@ export async function serveConnections(
304
261
  let requestComplete = false;
305
262
  void (async () => {
306
263
  const handler = makeHandler({ remotePeer: connection.remotePeer });
307
- const inputQueue = makeInputQueue();
308
- const output = handler(inputQueue.iter());
264
+ const inputQueue = makeInputQueue(readHighWaterBytes ?? DEFAULT_READ_HIGH_WATER_BYTES);
265
+ // once the handler's output has ended, input it never started to read is
266
+ // dropped instead of waited for (input it is reading, perhaps in the
267
+ // background, keeps flowing at its pace)
268
+ const output = endsWith(handler(inputQueue.iter()), () => inputQueue.abandon());
309
269
  try {
310
270
  for await (const chunk of duplexOverStream(stream, output, {
311
271
  drainTimeoutMs,
272
+ readHighWaterBytes,
312
273
  onPeerInputEnd: (err) => {
313
274
  if (err === undefined) requestComplete = true;
314
275
  inputQueue.done(err);
315
276
  },
316
277
  })) {
317
- inputQueue.push(chunk);
278
+ // past readHighWaterBytes queued for the handler, the next chunk is
279
+ // read only once it took this one: a handler that stops reading
280
+ // pauses the stream (see readHighWaterBytes)
281
+ await inputQueue.push(chunk);
318
282
  }
319
283
  } finally {
320
284
  inputQueue.done();
@@ -348,20 +312,61 @@ export async function serveConnections(
348
312
  };
349
313
  }
350
314
 
315
+ /** `source`, calling `onEnd` once when it ends, fails or is returned. */
316
+ function endsWith(
317
+ source: AsyncIterable<Uint8Array>,
318
+ onEnd: () => void,
319
+ ): AsyncGenerator<Uint8Array> {
320
+ return (async function* () {
321
+ try {
322
+ yield* source;
323
+ } finally {
324
+ onEnd();
325
+ }
326
+ })();
327
+ }
328
+
351
329
  interface InputQueue {
352
330
  iter(): AsyncGenerator<Uint8Array>;
353
- push(chunk: Uint8Array): void;
331
+ /**
332
+ * resolves at once while the bytes queued for the handler stay within the
333
+ * limit, else once the handler has read them back down to it (or will never
334
+ * read on)
335
+ */
336
+ push(chunk: Uint8Array): Promise<void>;
354
337
  done(err?: Error): void;
338
+ /**
339
+ * the handler's output ended: if it never started reading its input, pending
340
+ * and later chunks are dropped (an iterator started already is left to its
341
+ * reader, which may go on reading after the output ended)
342
+ */
343
+ abandon(): void;
355
344
  }
356
345
 
357
- function makeInputQueue(): InputQueue {
346
+ function makeInputQueue(limit: number): InputQueue {
358
347
  type Slot = { type: "value"; value: Uint8Array } | { type: "done"; err?: Error };
359
348
  const slots: Slot[] = [];
360
349
  let wake: (() => void) | null = null;
361
350
  let closed = false;
351
+ let pulled = false;
352
+ let queued = 0;
353
+ // the one push waiting for room (the serving loop awaits each push)
354
+ let room: (() => void) | null = null;
355
+ const makeRoom = (): void => {
356
+ const r = room;
357
+ room = null;
358
+ r?.();
359
+ };
360
+ const release = (): void => {
361
+ slots.length = 0;
362
+ queued = 0;
363
+ makeRoom();
364
+ };
362
365
  return {
363
366
  iter(): AsyncGenerator<Uint8Array> {
364
367
  return (async function* () {
368
+ if (closed) return; // abandoned before anyone read: the input was dropped
369
+ pulled = true;
365
370
  try {
366
371
  while (true) {
367
372
  if (slots.length === 0) {
@@ -376,22 +381,36 @@ function makeInputQueue(): InputQueue {
376
381
  if (s.err) throw s.err;
377
382
  return;
378
383
  }
384
+ queued -= s.value.byteLength;
385
+ if (queued <= limit) makeRoom();
379
386
  yield s.value;
380
387
  }
381
388
  } finally {
382
389
  closed = true;
390
+ release();
383
391
  }
384
392
  })();
385
393
  },
386
- push(chunk: Uint8Array): void {
387
- if (closed) return;
394
+ push(chunk: Uint8Array): Promise<void> {
395
+ if (closed) return Promise.resolve();
388
396
  slots.push({ type: "value", value: chunk });
397
+ queued += chunk.byteLength;
389
398
  wake?.();
399
+ if (queued <= limit) return Promise.resolve();
400
+ return new Promise<void>((resolve) => {
401
+ room = resolve;
402
+ });
390
403
  },
391
404
  done(err?: Error): void {
392
405
  if (closed) return;
393
406
  slots.push({ type: "done", err });
394
407
  wake?.();
395
408
  },
409
+ abandon(): void {
410
+ if (pulled) return;
411
+ closed = true;
412
+ release();
413
+ wake?.();
414
+ },
396
415
  };
397
416
  }
@@ -52,6 +52,12 @@ export const DEFAULT_DRAIN_TIMEOUT_MS = 300_000;
52
52
  */
53
53
  export const DEFAULT_CLOSE_TIMEOUT_MS = DEFAULT_DRAIN_TIMEOUT_MS;
54
54
 
55
+ /**
56
+ * Default for {@link DuplexOverStreamOptions.readHighWaterBytes}: received bytes
57
+ * held for a consumer that is not reading before the stream is paused.
58
+ */
59
+ export const DEFAULT_READ_HIGH_WATER_BYTES = 64 * 1024;
60
+
55
61
  /**
56
62
  * The stream ended before the call finished: the peer died, the connection
57
63
  * dropped, or the stream was reset or refused before both sides ended it.
@@ -98,6 +104,18 @@ export interface DuplexOverStreamOptions {
98
104
  * the peer. Defaults to {@link DEFAULT_DRAIN_TIMEOUT_MS}.
99
105
  */
100
106
  drainTimeoutMs?: number;
107
+ /**
108
+ * Received bytes held for a consumer that is not reading before the stream
109
+ * is paused (and resumed once half of them are read). A paused yamux stream
110
+ * stops granting its peer receive window, so the peer's `send()` reports a
111
+ * full buffer and its producer waits: run-ahead is bounded by two receive
112
+ * windows (what libp2p held while paused, and the window granted on resume)
113
+ * plus this — the receiving node's yamux `streamOptions.maxStreamWindowSize`,
114
+ * 16 MiB by default; 1 MiB bounds it at about 2.25 MiB with no loss of
115
+ * one-way throughput measured. Only where the muxer exposes its window.
116
+ * Defaults to {@link DEFAULT_READ_HIGH_WATER_BYTES}.
117
+ */
118
+ readHighWaterBytes?: number;
101
119
  }
102
120
 
103
121
  /**
@@ -212,7 +230,9 @@ export async function* duplexOverStream(
212
230
  // interleave. Inserting an await above would break that.
213
231
  let peerError: Error | undefined;
214
232
  try {
215
- for await (const frame of parseFrames(stream)) {
233
+ for await (const frame of parseFrames(
234
+ pacedSource(stream, opts.readHighWaterBytes ?? DEFAULT_READ_HIGH_WATER_BYTES),
235
+ )) {
216
236
  if (frame.type === TYPE_DATA) {
217
237
  yield frame.payload;
218
238
  } else if (frame.type === TYPE_ERROR) {
@@ -413,6 +433,120 @@ async function* framedOutbound(
413
433
  }
414
434
  }
415
435
 
436
+ /**
437
+ * The stream's inbound bytes, read at the consumer's pace. libp2p's own
438
+ * iterator moves every message into an unbounded queue as it arrives, and
439
+ * yamux grants its peer more receive window on arrival, not on consumption: a
440
+ * consumer that stopped reading let the producer run 22-24 MiB ahead until
441
+ * libp2p's read buffer killed the stream (L6). Here the queue is bounded: past
442
+ * `highWater` bytes the stream is paused (yamux then withholds window updates,
443
+ * libp2p keeps what still arrives in its read buffer, undispatched), and it is
444
+ * resumed once the consumer has read the queue down to half.
445
+ *
446
+ * Ends as libp2p's iterator does: on the peer's `remoteCloseWrite`, or on
447
+ * `close` (throwing its error, if any). Subscribes on the first pull, like it.
448
+ */
449
+ async function* pacedSource(stream: Stream, highWater: number): AsyncGenerator<Uint8Array> {
450
+ if (stream.readStatus !== "readable" && stream.readStatus !== "paused") return;
451
+ // Pausing bounds anything only where the muxer then stops granting its peer
452
+ // window (yamux, which exposes `maxStreamWindowSize`). Elsewhere a pause just
453
+ // moves the data into libp2p's read buffer, which aborts the stream past
454
+ // `maxReadBufferLength`: there the stream is read as libp2p's own iterator
455
+ // reads it, without a bound.
456
+ const window = (stream as { maxStreamWindowSize?: unknown }).maxStreamWindowSize;
457
+ const paced = typeof window === "number";
458
+ // While paused, libp2p holds what the peer may still send (at most the
459
+ // window granted before the pause) and aborts the stream past
460
+ // `maxReadBufferLength`. yamux's default window (16 MiB) exceeds libp2p's
461
+ // default buffer (4 MiB), so the buffer is raised to the window plus what is
462
+ // queued here; yamux itself refuses a peer that sends past its window.
463
+ if (paced && stream.maxReadBufferLength < window + highWater) {
464
+ stream.maxReadBufferLength = window + highWater;
465
+ }
466
+ const queue: Uint8Array[] = [];
467
+ let queued = 0;
468
+ let ended = false;
469
+ let error: unknown;
470
+ let resuming = false;
471
+ let wake: (() => void) | undefined;
472
+ const notify = (): void => {
473
+ const w = wake;
474
+ wake = undefined;
475
+ w?.();
476
+ };
477
+ const pauseIfFull = (): void => {
478
+ if (paced && queued >= highWater && stream.readStatus === "readable") {
479
+ try {
480
+ stream.pause();
481
+ } catch {
482
+ /* closing: nothing more will be granted anyway */
483
+ }
484
+ }
485
+ };
486
+ const onMessage = (evt: { data: unknown }): void => {
487
+ const chunk = normalizeChunk(evt.data);
488
+ if (chunk.byteLength === 0) return;
489
+ // In pieces of at most `highWater` (views, not copies): a resume hands over
490
+ // everything libp2p held as one message, up to a window, and a reader that
491
+ // took it whole would hold that window outside this queue's count.
492
+ for (let at = 0; at < chunk.byteLength; at += highWater) {
493
+ queue.push(chunk.subarray(at, Math.min(at + highWater, chunk.byteLength)));
494
+ }
495
+ queued += chunk.byteLength;
496
+ // Never from inside `resume()`: it dispatches what libp2p held first and
497
+ // tells the muxer to grant window after, so a pause here would leave libp2p
498
+ // paused and yamux granting window for every frame (review of #112).
499
+ if (!resuming) pauseIfFull();
500
+ notify();
501
+ };
502
+ const resume = (): void => {
503
+ resuming = true;
504
+ try {
505
+ stream.resume(); // dispatches what libp2p held meanwhile, synchronously
506
+ } catch {
507
+ /* closing */
508
+ } finally {
509
+ resuming = false;
510
+ }
511
+ pauseIfFull(); // after the muxer's own resume, so the pause holds
512
+ };
513
+ const onClose = (evt: StreamCloseEvent): void => {
514
+ ended = true;
515
+ error ??= evt.error;
516
+ notify();
517
+ };
518
+ const onRemoteCloseWrite = (): void => {
519
+ ended = true;
520
+ notify();
521
+ };
522
+ stream.addEventListener("message", onMessage);
523
+ stream.addEventListener("close", onClose);
524
+ stream.addEventListener("remoteCloseWrite", onRemoteCloseWrite);
525
+ if (stream.readStatus === "paused") resume(); // paused by someone else: nothing here resumes it later
526
+ try {
527
+ for (;;) {
528
+ const chunk = queue.shift();
529
+ if (chunk) {
530
+ queued -= chunk.byteLength;
531
+ if (queued <= highWater / 2 && stream.readStatus === "paused") resume();
532
+ yield chunk;
533
+ continue;
534
+ }
535
+ if (ended) {
536
+ if (error) throw error;
537
+ return;
538
+ }
539
+ await new Promise<void>((resolve) => {
540
+ wake = resolve;
541
+ });
542
+ }
543
+ } finally {
544
+ stream.removeEventListener("message", onMessage);
545
+ stream.removeEventListener("close", onClose);
546
+ stream.removeEventListener("remoteCloseWrite", onRemoteCloseWrite);
547
+ }
548
+ }
549
+
416
550
  async function* parseFrames(
417
551
  source: AsyncIterable<unknown>,
418
552
  ): AsyncGenerator<{ type: number; payload: Uint8Array }> {
package/src/index.ts CHANGED
@@ -21,3 +21,14 @@ export {
21
21
  messageTargetOverStream,
22
22
  type StreamMessageTarget,
23
23
  } from "./message-target-over-stream.js";
24
+ export {
25
+ DEFAULT_PORT_MAX_MESSAGE_SIZE,
26
+ DEFAULT_PORT_PROTOCOL,
27
+ DEFAULT_PORT_STREAM_LIMIT,
28
+ type InboundPortInfo,
29
+ type Libp2pPortMux,
30
+ type Libp2pPortMuxOptions,
31
+ libp2pPortMux,
32
+ type StreamPort,
33
+ type ValueCodec,
34
+ } from "./port-mux.js";
@@ -27,6 +27,8 @@ export interface StreamMessageTarget {
27
27
  * closed; at once when it can now.
28
28
  */
29
29
  whenDrained(): Promise<void>;
30
+ /** `signal` again, on the target: `webrun-rpc`'s `getPortCloseSignal` reads it from a port. */
31
+ readonly closeSignal: AbortSignal;
30
32
  };
31
33
  /**
32
34
  * Aborts when the stream is over, after every message the peer sent has
@@ -75,7 +77,9 @@ export function messageTargetOverStream(
75
77
  ): StreamMessageTarget {
76
78
  const listeners = new Set<Listener>();
77
79
  const life = new AbortController();
78
- let peerClosedWrite = false;
80
+ // The peer may have finished, or reset the stream, before this target was attached (during
81
+ // protocol negotiation): its events are gone then, and only the stream's state tells.
82
+ let peerClosedWrite = stream.remoteWriteStatus === "closed";
79
83
 
80
84
  const onRemoteCloseWrite = (): void => {
81
85
  // The read loop may still hold the peer's last messages; it aborts
@@ -89,6 +93,9 @@ export function messageTargetOverStream(
89
93
  };
90
94
  stream.addEventListener("remoteCloseWrite", onRemoteCloseWrite);
91
95
  stream.addEventListener("close", onClose, { once: true });
96
+ // A stream reset or closed before this target was attached (a peer refusing it during protocol
97
+ // negotiation) fired its `close` unseen: report it now, as a dead peer.
98
+ if (stream.status !== undefined && stream.status !== "open") life.abort(new PeerGoneError());
92
99
 
93
100
  const deliver = (data: Uint8Array): void => {
94
101
  const event = new MessageEvent("message", { data });
@@ -147,6 +154,7 @@ export function messageTargetOverStream(
147
154
  return {
148
155
  signal: life.signal,
149
156
  target: {
157
+ closeSignal: life.signal,
150
158
  addEventListener: (_type, listener) => {
151
159
  listeners.add(listener);
152
160
  },