@statewalker/webrun-streams-libp2p 0.2.0 → 0.4.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/dist/index.js CHANGED
@@ -49,6 +49,19 @@ const DEFAULT_DRAIN_TIMEOUT_MS = 3e5;
49
49
  */
50
50
  const DEFAULT_CLOSE_TIMEOUT_MS = DEFAULT_DRAIN_TIMEOUT_MS;
51
51
  /**
52
+ * Default for {@link DuplexOverStreamOptions.maxFrameBytes}: the largest frame payload accepted
53
+ * from the peer. Generous, because a sender before this package's outbound chunking sent each
54
+ * producer chunk as one frame; short of letting a peer declare a 4 GiB frame.
55
+ */
56
+ const DEFAULT_MAX_FRAME_BYTES = 67108864;
57
+ /**
58
+ * The largest payload this side puts in one outbound frame: a larger producer chunk crosses as
59
+ * several frames (they are self-delimiting, so a receiver of any version reassembles the bytes).
60
+ */
61
+ const OUTBOUND_FRAME_BYTES = 65536;
62
+ /** The peer sent bytes that are not this framing: a malformed or oversized frame header. */
63
+ var FramingError = class extends Error {};
64
+ /**
52
65
  * The stream ended before the call finished: the peer died, the connection
53
66
  * dropped, or the stream was reset or refused before both sides ended it.
54
67
  * Distinct from a clean end on purpose — a response cut short must never read
@@ -121,7 +134,7 @@ async function* duplexOverStream(stream, input, opts = {}) {
121
134
  try {
122
135
  let peerError;
123
136
  try {
124
- for await (const frame of parseFrames(stream)) if (frame.type === TYPE_DATA) yield frame.payload;
137
+ for await (const frame of parseFrames(pacedSource(stream, opts.readHighWaterBytes ?? 65536), opts.maxFrameBytes ?? 67108864)) if (frame.type === TYPE_DATA) yield frame.payload;
125
138
  else if (frame.type === TYPE_ERROR) {
126
139
  peerError = decodeError(frame.payload);
127
140
  firePeerInputEnd(peerError);
@@ -129,6 +142,10 @@ async function* duplexOverStream(stream, input, opts = {}) {
129
142
  }
130
143
  } catch (err) {
131
144
  if (err === peerError) throw err;
145
+ if (err instanceof FramingError) {
146
+ firePeerInputEnd(err);
147
+ throw err;
148
+ }
132
149
  const gone = new PeerGoneError(err);
133
150
  firePeerInputEnd(gone);
134
151
  throw gone;
@@ -237,7 +254,8 @@ async function* framedOutbound(iterator) {
237
254
  for (;;) {
238
255
  const next = await iterator.next();
239
256
  if (next.done === true) return;
240
- yield frameData(normalizeChunk(next.value));
257
+ const chunk = normalizeChunk(next.value);
258
+ for (let at = 0; at < chunk.byteLength; at += OUTBOUND_FRAME_BYTES) yield frameData(chunk.subarray(at, Math.min(at + OUTBOUND_FRAME_BYTES, chunk.byteLength)));
241
259
  }
242
260
  } catch (err) {
243
261
  yield frameError(err instanceof Error ? err : new Error(String(err)));
@@ -245,37 +263,160 @@ async function* framedOutbound(iterator) {
245
263
  Promise.resolve(iterator.return?.(void 0)).catch(() => void 0);
246
264
  }
247
265
  }
248
- async function* parseFrames(source) {
249
- let buf = /* @__PURE__ */ new Uint8Array(0);
266
+ /**
267
+ * The stream's inbound bytes, read at the consumer's pace. libp2p's own
268
+ * iterator moves every message into an unbounded queue as it arrives, and
269
+ * yamux grants its peer more receive window on arrival, not on consumption: a
270
+ * consumer that stopped reading let the producer run 22-24 MiB ahead until
271
+ * libp2p's read buffer killed the stream (L6). Here the queue is bounded: past
272
+ * `highWater` bytes the stream is paused (yamux then withholds window updates,
273
+ * libp2p keeps what still arrives in its read buffer, undispatched), and it is
274
+ * resumed once the consumer has read the queue down to half.
275
+ *
276
+ * Ends as libp2p's iterator does: on the peer's `remoteCloseWrite`, or on
277
+ * `close` (throwing its error, if any). Subscribes on the first pull, like it.
278
+ */
279
+ async function* pacedSource(stream, highWater) {
280
+ if (stream.readStatus !== "readable" && stream.readStatus !== "paused") return;
281
+ const window = stream.maxStreamWindowSize;
282
+ const paced = typeof window === "number";
283
+ if (paced && stream.maxReadBufferLength < window + highWater) stream.maxReadBufferLength = window + highWater;
284
+ const queue = [];
285
+ let queued = 0;
286
+ let ended = false;
287
+ let error;
288
+ let resuming = false;
289
+ let wake;
290
+ const notify = () => {
291
+ const w = wake;
292
+ wake = void 0;
293
+ w?.();
294
+ };
295
+ const pauseIfFull = () => {
296
+ if (paced && queued >= highWater && stream.readStatus === "readable") try {
297
+ stream.pause();
298
+ } catch {}
299
+ };
300
+ const onMessage = (evt) => {
301
+ const chunk = normalizeChunk(evt.data);
302
+ if (chunk.byteLength === 0) return;
303
+ for (let at = 0; at < chunk.byteLength; at += highWater) queue.push(chunk.subarray(at, Math.min(at + highWater, chunk.byteLength)));
304
+ queued += chunk.byteLength;
305
+ if (!resuming) pauseIfFull();
306
+ notify();
307
+ };
308
+ const resume = () => {
309
+ resuming = true;
310
+ try {
311
+ stream.resume();
312
+ } catch {} finally {
313
+ resuming = false;
314
+ }
315
+ pauseIfFull();
316
+ };
317
+ const onClose = (evt) => {
318
+ ended = true;
319
+ error ??= evt.error;
320
+ notify();
321
+ };
322
+ const onRemoteCloseWrite = () => {
323
+ ended = true;
324
+ notify();
325
+ };
326
+ stream.addEventListener("message", onMessage);
327
+ stream.addEventListener("close", onClose);
328
+ stream.addEventListener("remoteCloseWrite", onRemoteCloseWrite);
329
+ if (stream.readStatus === "paused") resume();
330
+ try {
331
+ for (;;) {
332
+ const chunk = queue.shift();
333
+ if (chunk) {
334
+ queued -= chunk.byteLength;
335
+ if (queued <= highWater / 2 && stream.readStatus === "paused") resume();
336
+ yield chunk;
337
+ continue;
338
+ }
339
+ if (ended) {
340
+ if (error) throw error;
341
+ return;
342
+ }
343
+ await new Promise((resolve) => {
344
+ wake = resolve;
345
+ });
346
+ }
347
+ } finally {
348
+ stream.removeEventListener("message", onMessage);
349
+ stream.removeEventListener("close", onClose);
350
+ stream.removeEventListener("remoteCloseWrite", onRemoteCloseWrite);
351
+ }
352
+ }
353
+ /**
354
+ * Frames out of the stream's chunks, as they complete. Unread bytes sit in a {@link ByteBuffer},
355
+ * which grows by doubling, so a large frame arriving in many chunks is copied a bounded number
356
+ * of times. A header whose length is malformed or past `maxFrameBytes` throws a `FramingError`.
357
+ */
358
+ async function* parseFrames(source, maxFrameBytes = DEFAULT_MAX_FRAME_BYTES) {
359
+ const buf = new ByteBuffer();
250
360
  for await (const item of source) {
251
361
  const incoming = normalizeChunk(item);
252
362
  if (incoming.byteLength === 0) continue;
253
- if (buf.byteLength === 0) buf = new Uint8Array(incoming);
254
- else {
255
- const merged = new Uint8Array(buf.byteLength + incoming.byteLength);
256
- merged.set(buf, 0);
257
- merged.set(incoming, buf.byteLength);
258
- buf = merged;
259
- }
260
- while (buf.byteLength > 0) {
261
- if (buf.byteLength < 2) break;
262
- const type = buf[0];
263
- let lenInfo;
264
- try {
265
- lenInfo = decodeVarint(buf, 1);
266
- } catch {
267
- break;
268
- }
269
- const total = lenInfo.offset + lenInfo.value;
270
- if (buf.byteLength < total) break;
363
+ buf.push(incoming);
364
+ for (;;) {
365
+ const bytes = buf.unread();
366
+ if (bytes.byteLength < 2) break;
367
+ const type = bytes[0];
368
+ const header = readLength(bytes.subarray(1), "frame");
369
+ if (header === void 0) break;
370
+ if (header.value > maxFrameBytes) throw new FramingError(`webrun-streams-libp2p: a ${header.value}-byte frame exceeds maxFrameBytes (${maxFrameBytes})`);
371
+ const total = 1 + header.offset + header.value;
372
+ if (bytes.byteLength < total) break;
373
+ const payload = bytes.slice(1 + header.offset, total);
374
+ buf.consume(total);
271
375
  yield {
272
376
  type,
273
- payload: new Uint8Array(buf.subarray(lenInfo.offset, total))
377
+ payload
274
378
  };
275
- buf = buf.byteLength === total ? /* @__PURE__ */ new Uint8Array(0) : new Uint8Array(buf.subarray(total));
276
379
  }
277
380
  }
278
381
  }
382
+ /** Unread bytes `buf[start, end)` of a buffer that grows by doubling. */
383
+ var ByteBuffer = class {
384
+ buf = /* @__PURE__ */ new Uint8Array(0);
385
+ start = 0;
386
+ end = 0;
387
+ push(incoming) {
388
+ if (this.end + incoming.byteLength > this.buf.byteLength) {
389
+ const size = this.end - this.start + incoming.byteLength;
390
+ const next = new Uint8Array(Math.max(size, this.buf.byteLength * 2));
391
+ next.set(this.buf.subarray(this.start, this.end), 0);
392
+ this.buf = next;
393
+ this.end -= this.start;
394
+ this.start = 0;
395
+ }
396
+ this.buf.set(incoming, this.end);
397
+ this.end += incoming.byteLength;
398
+ }
399
+ /** a view of the unread bytes, valid until the next `push` */
400
+ unread() {
401
+ return this.buf.subarray(this.start, this.end);
402
+ }
403
+ consume(n) {
404
+ this.start += n;
405
+ if (this.start === this.end) this.start = this.end = 0;
406
+ }
407
+ };
408
+ /**
409
+ * The varint length prefix at the start of `bytes`, or `undefined` while it is incomplete; throws
410
+ * a `FramingError` when it is malformed (no varint of this framing runs past 5 bytes).
411
+ */
412
+ function readLength(bytes, what) {
413
+ try {
414
+ return decodeVarint(bytes, 0);
415
+ } catch (err) {
416
+ if (bytes.byteLength < 5) return void 0;
417
+ throw new FramingError(`webrun-streams-libp2p: a malformed ${what} length`, { cause: err });
418
+ }
419
+ }
279
420
  function normalizeChunk(item) {
280
421
  if (item instanceof Uint8Array) return item;
281
422
  const asList = item;
@@ -335,26 +476,7 @@ function decodeVarint(buf, start) {
335
476
  throw new Error("decodeVarint: truncated");
336
477
  }
337
478
  //#endregion
338
- //#region src/connect-serve.ts
339
- const DEFAULT_PROTOCOL = "/webrun-streams/1.0.0";
340
- /**
341
- * Builds the options object passed to `node.dialProtocol`/`node.handle`,
342
- * omitting any field the caller didn't supply rather than setting it to
343
- * `undefined` — so an unset field falls back to libp2p's own default instead
344
- * of an explicit `undefined` overriding it.
345
- */
346
- function definedOptions(fields) {
347
- const options = {};
348
- let any = false;
349
- for (const key of Object.keys(fields)) {
350
- const value = fields[key];
351
- if (value !== void 0) {
352
- options[key] = value;
353
- any = true;
354
- }
355
- }
356
- return any ? options : void 0;
357
- }
479
+ //#region src/stream-gate.ts
358
480
  const streamGates = /* @__PURE__ */ new WeakMap();
359
481
  function streamGateFor(node, peer) {
360
482
  let gates = streamGates.get(node);
@@ -386,31 +508,63 @@ function connectionOf(node, stream) {
386
508
  if (typeof node.getConnections !== "function") return null;
387
509
  return node.getConnections().find((connection) => connection.streams.includes(stream)) ?? null;
388
510
  }
389
- const connect = async ({ node, peer, protocol, drainTimeoutMs, maxOutboundStreams, runOnLimitedConnection }) => {
511
+ /**
512
+ * Opens a stream to `peer` for `proto`, one at a time until the remote has proven ready: a burst
513
+ * of streams on a connection the remote is still upgrading makes yamux abort the whole muxer
514
+ * (`maxEarlyStreams`). Shared by `connect()` and `libp2pPortMux`, and by every caller dialling
515
+ * the same peer from the same node, since they share its connection.
516
+ */
517
+ async function openGatedStream(node, peer, proto, dialOptions) {
518
+ const gate = streamGateFor(node, peer);
519
+ while (!isProven(gate)) {
520
+ if (gate.firstOpening == null) {
521
+ const opening = node.dialProtocol(peer, [proto], dialOptions);
522
+ gate.firstOpening = opening;
523
+ try {
524
+ const stream = await opening;
525
+ gate.proven = { connection: connectionOf(node, stream) };
526
+ return stream;
527
+ } finally {
528
+ gate.firstOpening = null;
529
+ }
530
+ }
531
+ await gate.firstOpening.catch(() => void 0);
532
+ }
533
+ return node.dialProtocol(peer, [proto], dialOptions);
534
+ }
535
+ //#endregion
536
+ //#region src/connect-serve.ts
537
+ const DEFAULT_PROTOCOL = "/webrun-streams/1.0.0";
538
+ /**
539
+ * Builds the options object passed to `node.dialProtocol`/`node.handle`,
540
+ * omitting any field the caller didn't supply rather than setting it to
541
+ * `undefined` — so an unset field falls back to libp2p's own default instead
542
+ * of an explicit `undefined` overriding it.
543
+ */
544
+ function definedOptions(fields) {
545
+ const options = {};
546
+ let any = false;
547
+ for (const key of Object.keys(fields)) {
548
+ const value = fields[key];
549
+ if (value !== void 0) {
550
+ options[key] = value;
551
+ any = true;
552
+ }
553
+ }
554
+ return any ? options : void 0;
555
+ }
556
+ /**
557
+ * Caller-side: each `call(input)` opens a new libp2p `Stream` via
558
+ * `node.dialProtocol(peer, [protocol])` and runs the call over it.
559
+ */
560
+ const connect = async ({ node, peer, protocol, drainTimeoutMs, readHighWaterBytes, maxFrameBytes, maxOutboundStreams, runOnLimitedConnection }) => {
390
561
  const proto = protocol ?? "/webrun-streams/1.0.0";
391
562
  const dialOptions = definedOptions({
392
563
  maxOutboundStreams,
393
564
  runOnLimitedConnection
394
565
  });
395
566
  const open = /* @__PURE__ */ new Set();
396
- const gate = streamGateFor(node, peer);
397
- const openStream = async () => {
398
- while (!isProven(gate)) {
399
- if (gate.firstOpening == null) {
400
- const opening = node.dialProtocol(peer, [proto], dialOptions);
401
- gate.firstOpening = opening;
402
- try {
403
- const stream = await opening;
404
- gate.proven = { connection: connectionOf(node, stream) };
405
- return stream;
406
- } finally {
407
- gate.firstOpening = null;
408
- }
409
- }
410
- await gate.firstOpening.catch(() => void 0);
411
- }
412
- return node.dialProtocol(peer, [proto], dialOptions);
413
- };
567
+ const openStream = () => openGatedStream(node, peer, proto, dialOptions);
414
568
  const call = (input) => {
415
569
  let streamRef = null;
416
570
  const gen = (async function* () {
@@ -421,6 +575,8 @@ const connect = async ({ node, peer, protocol, drainTimeoutMs, maxOutboundStream
421
575
  try {
422
576
  yield* duplexOverStream(stream, input, {
423
577
  drainTimeoutMs,
578
+ readHighWaterBytes,
579
+ maxFrameBytes,
424
580
  onSourceCompleted: () => {
425
581
  sourceCompleted = true;
426
582
  }
@@ -458,7 +614,7 @@ const serve = async (params, handler) => serveConnections(params, () => handler)
458
614
  * Like `serve`, but the handler is built per inbound stream and is told which
459
615
  * peer libp2p proved on that connection.
460
616
  */
461
- async function serveConnections({ node, protocol, drainTimeoutMs, maxInboundStreams, maxOutboundStreams, runOnLimitedConnection }, makeHandler) {
617
+ async function serveConnections({ node, protocol, drainTimeoutMs, readHighWaterBytes, maxFrameBytes, maxInboundStreams, maxOutboundStreams, runOnLimitedConnection }, makeHandler) {
462
618
  const proto = protocol ?? "/webrun-streams/1.0.0";
463
619
  const handleOptions = definedOptions({
464
620
  maxInboundStreams,
@@ -469,16 +625,18 @@ async function serveConnections({ node, protocol, drainTimeoutMs, maxInboundStre
469
625
  let requestComplete = false;
470
626
  (async () => {
471
627
  const handler = makeHandler({ remotePeer: connection.remotePeer });
472
- const inputQueue = makeInputQueue();
473
- const output = handler(inputQueue.iter());
628
+ const inputQueue = makeInputQueue(readHighWaterBytes ?? 65536);
629
+ const output = endsWith(handler(inputQueue.iter()), () => inputQueue.abandon());
474
630
  try {
475
631
  for await (const chunk of duplexOverStream(stream, output, {
476
632
  drainTimeoutMs,
633
+ readHighWaterBytes,
634
+ maxFrameBytes,
477
635
  onPeerInputEnd: (err) => {
478
636
  if (err === void 0) requestComplete = true;
479
637
  inputQueue.done(err);
480
638
  }
481
- })) inputQueue.push(chunk);
639
+ })) await inputQueue.push(chunk);
482
640
  } finally {
483
641
  inputQueue.done();
484
642
  await closeStream(stream);
@@ -497,13 +655,38 @@ async function serveConnections({ node, protocol, drainTimeoutMs, maxInboundStre
497
655
  await node.unhandle(proto);
498
656
  };
499
657
  }
500
- function makeInputQueue() {
658
+ /** `source`, calling `onEnd` once when it ends, fails or is returned. */
659
+ function endsWith(source, onEnd) {
660
+ return (async function* () {
661
+ try {
662
+ yield* source;
663
+ } finally {
664
+ onEnd();
665
+ }
666
+ })();
667
+ }
668
+ function makeInputQueue(limit) {
501
669
  const slots = [];
502
670
  let wake = null;
503
671
  let closed = false;
672
+ let pulled = false;
673
+ let queued = 0;
674
+ let room = null;
675
+ const makeRoom = () => {
676
+ const r = room;
677
+ room = null;
678
+ r?.();
679
+ };
680
+ const release = () => {
681
+ slots.length = 0;
682
+ queued = 0;
683
+ makeRoom();
684
+ };
504
685
  return {
505
686
  iter() {
506
687
  return (async function* () {
688
+ if (closed) return;
689
+ pulled = true;
507
690
  try {
508
691
  while (true) {
509
692
  if (slots.length === 0) {
@@ -518,20 +701,28 @@ function makeInputQueue() {
518
701
  if (s.err) throw s.err;
519
702
  return;
520
703
  }
704
+ queued -= s.value.byteLength;
705
+ if (queued <= limit) makeRoom();
521
706
  yield s.value;
522
707
  }
523
708
  } finally {
524
709
  closed = true;
710
+ release();
525
711
  }
526
712
  })();
527
713
  },
528
714
  push(chunk) {
529
- if (closed) return;
715
+ if (closed) return Promise.resolve();
530
716
  slots.push({
531
717
  type: "value",
532
718
  value: chunk
533
719
  });
720
+ queued += chunk.byteLength;
534
721
  wake?.();
722
+ if (queued <= limit) return Promise.resolve();
723
+ return new Promise((resolve) => {
724
+ room = resolve;
725
+ });
535
726
  },
536
727
  done(err) {
537
728
  if (closed) return;
@@ -540,6 +731,12 @@ function makeInputQueue() {
540
731
  err
541
732
  });
542
733
  wake?.();
734
+ },
735
+ abandon() {
736
+ if (pulled) return;
737
+ closed = true;
738
+ release();
739
+ wake?.();
543
740
  }
544
741
  };
545
742
  }
@@ -566,7 +763,7 @@ const DEFAULT_MAX_MESSAGE_BYTES = 67108864;
566
763
  function messageTargetOverStream(stream, { maxMessageBytes = DEFAULT_MAX_MESSAGE_BYTES } = {}) {
567
764
  const listeners = /* @__PURE__ */ new Set();
568
765
  const life = new AbortController();
569
- let peerClosedWrite = false;
766
+ let peerClosedWrite = stream.remoteWriteStatus === "closed";
570
767
  const onRemoteCloseWrite = () => {
571
768
  peerClosedWrite = true;
572
769
  };
@@ -577,6 +774,7 @@ function messageTargetOverStream(stream, { maxMessageBytes = DEFAULT_MAX_MESSAGE
577
774
  };
578
775
  stream.addEventListener("remoteCloseWrite", onRemoteCloseWrite);
579
776
  stream.addEventListener("close", onClose, { once: true });
777
+ if (stream.status !== void 0 && stream.status !== "open") life.abort(new PeerGoneError());
580
778
  const deliver = (data) => {
581
779
  const event = new MessageEvent("message", { data });
582
780
  for (const listener of [...listeners]) try {
@@ -584,29 +782,19 @@ function messageTargetOverStream(stream, { maxMessageBytes = DEFAULT_MAX_MESSAGE
584
782
  } catch {}
585
783
  };
586
784
  (async () => {
587
- let buf = /* @__PURE__ */ new Uint8Array(0);
588
- let start = 0;
589
- let end = 0;
785
+ const buf = new ByteBuffer();
590
786
  for await (const item of stream) {
591
- const incoming = normalizeChunk(item);
592
- if (end + incoming.byteLength > buf.byteLength) {
593
- const size = end - start + incoming.byteLength;
594
- const next = new Uint8Array(Math.max(size, buf.byteLength * 2));
595
- next.set(buf.subarray(start, end), 0);
596
- buf = next;
597
- end -= start;
598
- start = 0;
599
- }
600
- buf.set(incoming, end);
601
- end += incoming.byteLength;
787
+ buf.push(normalizeChunk(item));
602
788
  for (;;) {
603
- const header = readLength(buf.subarray(start, end));
789
+ const bytes = buf.unread();
790
+ const header = readLength(bytes, "message");
604
791
  if (header === void 0) break;
605
792
  if (header.value > maxMessageBytes) throw new Error(`webrun-streams-libp2p: a ${header.value}-byte message exceeds maxMessageBytes (${maxMessageBytes})`);
606
- const stop = start + header.offset + header.value;
607
- if (end < stop) break;
608
- deliver(buf.slice(start + header.offset, stop));
609
- start = stop;
793
+ const stop = header.offset + header.value;
794
+ if (bytes.byteLength < stop) break;
795
+ const message = bytes.slice(header.offset, stop);
796
+ buf.consume(stop);
797
+ deliver(message);
610
798
  }
611
799
  }
612
800
  if (peerClosedWrite) {
@@ -622,6 +810,7 @@ function messageTargetOverStream(stream, { maxMessageBytes = DEFAULT_MAX_MESSAGE
622
810
  return {
623
811
  signal: life.signal,
624
812
  target: {
813
+ closeSignal: life.signal,
625
814
  addEventListener: (_type, listener) => {
626
815
  listeners.add(listener);
627
816
  },
@@ -629,7 +818,8 @@ function messageTargetOverStream(stream, { maxMessageBytes = DEFAULT_MAX_MESSAGE
629
818
  listeners.delete(listener);
630
819
  },
631
820
  postMessage(message) {
632
- const payload = normalizeChunk(message);
821
+ const payload = toBytes(message);
822
+ if (!payload) throw new TypeError(`webrun-streams-libp2p: a byte pipe carries Uint8Array, ArrayBuffer or a view, got ${Object.prototype.toString.call(message)}`);
633
823
  const header = encodeVarint(payload.byteLength);
634
824
  const frame = new Uint8Array(header.byteLength + payload.byteLength);
635
825
  frame.set(header, 0);
@@ -660,14 +850,157 @@ function messageTargetOverStream(stream, { maxMessageBytes = DEFAULT_MAX_MESSAGE
660
850
  }
661
851
  };
662
852
  }
663
- /** The length prefix of `bytes`, or `undefined` while it is incomplete; throws when malformed. */
664
- function readLength(bytes) {
665
- try {
666
- return decodeVarint(bytes, 0);
667
- } catch (err) {
668
- if (bytes.byteLength < 5) return void 0;
669
- throw new Error("webrun-streams-libp2p: a malformed message length", { cause: err });
853
+ /** `message` as bytes, or `undefined` when it is not bytes */
854
+ function toBytes(message) {
855
+ if (message instanceof Uint8Array) return message;
856
+ if (message instanceof ArrayBuffer) return new Uint8Array(message);
857
+ if (ArrayBuffer.isView(message)) return new Uint8Array(message.buffer, message.byteOffset, message.byteLength);
858
+ }
859
+ //#endregion
860
+ //#region src/port-mux.ts
861
+ /** The protocol a port's stream negotiates unless told otherwise. */
862
+ const DEFAULT_PORT_PROTOCOL = "/webrun-ports/1.0.0";
863
+ /**
864
+ * 256 KiB: what one message on a port may carry before `webrun-rpc`'s stream tier chunks a body.
865
+ * A port waits for each chunk's confirmation, so a larger chunk means fewer round trips; well
866
+ * under `messageTargetOverStream`'s 64 MiB frame ceiling.
867
+ */
868
+ const DEFAULT_PORT_MAX_MESSAGE_SIZE = 262144;
869
+ /**
870
+ * The stream limits a port mux asks libp2p for unless told otherwise: every concurrent call is a
871
+ * stream, and libp2p's own default (32 per protocol) would reset the 33rd.
872
+ */
873
+ const DEFAULT_PORT_STREAM_LIMIT = 1024;
874
+ /**
875
+ * Native MessagePorts over libp2p: every port is its own libp2p stream, which yamux multiplexes
876
+ * with its own per-stream flow control, framed as messages by `messageTargetOverStream`. Hand it
877
+ * to `webrun-rpc` as a port source and its stream tier runs one call per port, with its tested
878
+ * backpressure — a producer stays one confirmed chunk ahead of its consumer — instead of
879
+ * libp2p's own buffering, which lets a producer run tens of megabytes ahead of a consumer that
880
+ * stopped reading:
881
+ *
882
+ * ```ts
883
+ * const codec = { encode: serialize, decode: deserialize }; // webrun-msgpack
884
+ * await serve({ mux: overPorts((onPort) => libp2pPortMux({ node, codec, onPort })) }, handler);
885
+ * const { call } = await connect({ mux: overPorts(() => libp2pPortMux({ node, codec, peer })) });
886
+ * ```
887
+ *
888
+ * Each port carries `closeSignal`, aborted when its stream ends or its peer goes, so a call on a
889
+ * dead stream fails instead of waiting. Streams are opened through the same early-stream gate as
890
+ * `connect()`. `meta` is not sent: the protocol says what a port is for.
891
+ */
892
+ async function libp2pPortMux(options) {
893
+ const { node, peer, codec, onPort, maxMessageBytes, runOnLimitedConnection } = options;
894
+ const maxInboundStreams = options.maxInboundStreams ?? 1024;
895
+ const maxOutboundStreams = options.maxOutboundStreams ?? 1024;
896
+ const protocol = options.protocol ?? "/webrun-ports/1.0.0";
897
+ const maxMessageSize = options.maxMessageSize ?? 262144;
898
+ const live = /* @__PURE__ */ new Set();
899
+ let closed = false;
900
+ const wrap = (stream) => {
901
+ const { target: inner } = messageTargetOverStream(stream, { maxMessageBytes });
902
+ const wrapped = /* @__PURE__ */ new Map();
903
+ const local = new AbortController();
904
+ const port = {
905
+ closeSignal: AbortSignal.any([inner.closeSignal, local.signal]),
906
+ get bufferedAmount() {
907
+ return inner.bufferedAmount;
908
+ },
909
+ whenDrained: () => inner.whenDrained(),
910
+ postMessage(message) {
911
+ inner.postMessage(codec.encode(message));
912
+ },
913
+ addEventListener(_type, listener) {
914
+ if (wrapped.has(listener)) return;
915
+ const decoding = (event) => {
916
+ let data;
917
+ try {
918
+ data = codec.decode(event.data);
919
+ } catch (err) {
920
+ stream.abort(new Error("webrun-streams-libp2p: a frame the port's codec cannot decode", { cause: err }));
921
+ return;
922
+ }
923
+ return listener(new MessageEvent("message", { data }));
924
+ };
925
+ wrapped.set(listener, decoding);
926
+ inner.addEventListener("message", decoding);
927
+ },
928
+ removeEventListener(_type, listener) {
929
+ const decoding = wrapped.get(listener);
930
+ if (!decoding) return;
931
+ wrapped.delete(listener);
932
+ inner.removeEventListener("message", decoding);
933
+ },
934
+ async close() {
935
+ live.delete(port);
936
+ if (!local.signal.aborted) local.abort(/* @__PURE__ */ new Error("webrun-streams-libp2p: port closed"));
937
+ await inner.close();
938
+ }
939
+ };
940
+ live.add(port);
941
+ inner.closeSignal.addEventListener("abort", () => live.delete(port), { once: true });
942
+ return port;
943
+ };
944
+ let handled = false;
945
+ if (onPort) {
946
+ const handleOptions = {
947
+ maxInboundStreams,
948
+ maxOutboundStreams
949
+ };
950
+ if (runOnLimitedConnection !== void 0) handleOptions.runOnLimitedConnection = runOnLimitedConnection;
951
+ await node.handle(protocol, (stream, connection) => {
952
+ if (closed) {
953
+ stream.abort(/* @__PURE__ */ new Error("webrun-streams-libp2p: port mux closed"));
954
+ return;
955
+ }
956
+ const port = wrap(stream);
957
+ let accepted = false;
958
+ try {
959
+ accepted = onPort(port, {
960
+ remotePeer: connection.remotePeer,
961
+ connection
962
+ }) !== false;
963
+ } catch {
964
+ accepted = false;
965
+ }
966
+ if (!accepted) {
967
+ live.delete(port);
968
+ stream.abort(/* @__PURE__ */ new Error("webrun-streams-libp2p: port refused"));
969
+ }
970
+ }, handleOptions);
971
+ handled = true;
670
972
  }
973
+ const dialOptions = { maxOutboundStreams };
974
+ if (runOnLimitedConnection !== void 0) dialOptions.runOnLimitedConnection = runOnLimitedConnection;
975
+ return {
976
+ maxMessageSize,
977
+ async openPort(_meta, opts) {
978
+ if (closed) throw new Error("webrun-streams-libp2p: port mux closed");
979
+ if (!peer) throw new Error("webrun-streams-libp2p: openPort needs `peer`");
980
+ const stream = await openGatedStream(node, peer, protocol, {
981
+ ...dialOptions,
982
+ signal: opts?.signal
983
+ });
984
+ if (closed) {
985
+ await closeStream(stream);
986
+ throw new Error("webrun-streams-libp2p: port mux closed");
987
+ }
988
+ const port = wrap(stream);
989
+ const signal = opts?.signal;
990
+ if (signal) {
991
+ const onAbort = () => void port.close();
992
+ signal.addEventListener("abort", onAbort, { once: true });
993
+ port.closeSignal.addEventListener("abort", () => signal.removeEventListener("abort", onAbort), { once: true });
994
+ }
995
+ return port;
996
+ },
997
+ async close() {
998
+ if (closed) return;
999
+ closed = true;
1000
+ if (handled) await node.unhandle(protocol).catch(() => void 0);
1001
+ await Promise.allSettled([...live].map((p) => p.close()));
1002
+ }
1003
+ };
671
1004
  }
672
1005
  //#endregion
673
- export { DEFAULT_CLOSE_TIMEOUT_MS, DEFAULT_DRAIN_TIMEOUT_MS, DEFAULT_MAX_MESSAGE_BYTES, DEFAULT_PROTOCOL, PeerGoneError, connect, duplexOverStream, messageTargetOverStream, serve, serveConnections };
1006
+ export { DEFAULT_CLOSE_TIMEOUT_MS, DEFAULT_DRAIN_TIMEOUT_MS, DEFAULT_MAX_FRAME_BYTES, DEFAULT_MAX_MESSAGE_BYTES, DEFAULT_PORT_MAX_MESSAGE_SIZE, DEFAULT_PORT_PROTOCOL, DEFAULT_PORT_STREAM_LIMIT, DEFAULT_PROTOCOL, PeerGoneError, connect, duplexOverStream, libp2pPortMux, messageTargetOverStream, serve, serveConnections };