@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.
package/dist/index.js CHANGED
@@ -121,7 +121,7 @@ async function* duplexOverStream(stream, input, opts = {}) {
121
121
  try {
122
122
  let peerError;
123
123
  try {
124
- for await (const frame of parseFrames(stream)) if (frame.type === TYPE_DATA) yield frame.payload;
124
+ for await (const frame of parseFrames(pacedSource(stream, opts.readHighWaterBytes ?? 65536))) if (frame.type === TYPE_DATA) yield frame.payload;
125
125
  else if (frame.type === TYPE_ERROR) {
126
126
  peerError = decodeError(frame.payload);
127
127
  firePeerInputEnd(peerError);
@@ -245,6 +245,93 @@ async function* framedOutbound(iterator) {
245
245
  Promise.resolve(iterator.return?.(void 0)).catch(() => void 0);
246
246
  }
247
247
  }
248
+ /**
249
+ * The stream's inbound bytes, read at the consumer's pace. libp2p's own
250
+ * iterator moves every message into an unbounded queue as it arrives, and
251
+ * yamux grants its peer more receive window on arrival, not on consumption: a
252
+ * consumer that stopped reading let the producer run 22-24 MiB ahead until
253
+ * libp2p's read buffer killed the stream (L6). Here the queue is bounded: past
254
+ * `highWater` bytes the stream is paused (yamux then withholds window updates,
255
+ * libp2p keeps what still arrives in its read buffer, undispatched), and it is
256
+ * resumed once the consumer has read the queue down to half.
257
+ *
258
+ * Ends as libp2p's iterator does: on the peer's `remoteCloseWrite`, or on
259
+ * `close` (throwing its error, if any). Subscribes on the first pull, like it.
260
+ */
261
+ async function* pacedSource(stream, highWater) {
262
+ if (stream.readStatus !== "readable" && stream.readStatus !== "paused") return;
263
+ const window = stream.maxStreamWindowSize;
264
+ const paced = typeof window === "number";
265
+ if (paced && stream.maxReadBufferLength < window + highWater) stream.maxReadBufferLength = window + highWater;
266
+ const queue = [];
267
+ let queued = 0;
268
+ let ended = false;
269
+ let error;
270
+ let resuming = false;
271
+ let wake;
272
+ const notify = () => {
273
+ const w = wake;
274
+ wake = void 0;
275
+ w?.();
276
+ };
277
+ const pauseIfFull = () => {
278
+ if (paced && queued >= highWater && stream.readStatus === "readable") try {
279
+ stream.pause();
280
+ } catch {}
281
+ };
282
+ const onMessage = (evt) => {
283
+ const chunk = normalizeChunk(evt.data);
284
+ if (chunk.byteLength === 0) return;
285
+ for (let at = 0; at < chunk.byteLength; at += highWater) queue.push(chunk.subarray(at, Math.min(at + highWater, chunk.byteLength)));
286
+ queued += chunk.byteLength;
287
+ if (!resuming) pauseIfFull();
288
+ notify();
289
+ };
290
+ const resume = () => {
291
+ resuming = true;
292
+ try {
293
+ stream.resume();
294
+ } catch {} finally {
295
+ resuming = false;
296
+ }
297
+ pauseIfFull();
298
+ };
299
+ const onClose = (evt) => {
300
+ ended = true;
301
+ error ??= evt.error;
302
+ notify();
303
+ };
304
+ const onRemoteCloseWrite = () => {
305
+ ended = true;
306
+ notify();
307
+ };
308
+ stream.addEventListener("message", onMessage);
309
+ stream.addEventListener("close", onClose);
310
+ stream.addEventListener("remoteCloseWrite", onRemoteCloseWrite);
311
+ if (stream.readStatus === "paused") resume();
312
+ try {
313
+ for (;;) {
314
+ const chunk = queue.shift();
315
+ if (chunk) {
316
+ queued -= chunk.byteLength;
317
+ if (queued <= highWater / 2 && stream.readStatus === "paused") resume();
318
+ yield chunk;
319
+ continue;
320
+ }
321
+ if (ended) {
322
+ if (error) throw error;
323
+ return;
324
+ }
325
+ await new Promise((resolve) => {
326
+ wake = resolve;
327
+ });
328
+ }
329
+ } finally {
330
+ stream.removeEventListener("message", onMessage);
331
+ stream.removeEventListener("close", onClose);
332
+ stream.removeEventListener("remoteCloseWrite", onRemoteCloseWrite);
333
+ }
334
+ }
248
335
  async function* parseFrames(source) {
249
336
  let buf = /* @__PURE__ */ new Uint8Array(0);
250
337
  for await (const item of source) {
@@ -335,26 +422,7 @@ function decodeVarint(buf, start) {
335
422
  throw new Error("decodeVarint: truncated");
336
423
  }
337
424
  //#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
- }
425
+ //#region src/stream-gate.ts
358
426
  const streamGates = /* @__PURE__ */ new WeakMap();
359
427
  function streamGateFor(node, peer) {
360
428
  let gates = streamGates.get(node);
@@ -386,31 +454,63 @@ function connectionOf(node, stream) {
386
454
  if (typeof node.getConnections !== "function") return null;
387
455
  return node.getConnections().find((connection) => connection.streams.includes(stream)) ?? null;
388
456
  }
389
- const connect = async ({ node, peer, protocol, drainTimeoutMs, maxOutboundStreams, runOnLimitedConnection }) => {
457
+ /**
458
+ * Opens a stream to `peer` for `proto`, one at a time until the remote has proven ready: a burst
459
+ * of streams on a connection the remote is still upgrading makes yamux abort the whole muxer
460
+ * (`maxEarlyStreams`). Shared by `connect()` and `libp2pPortMux`, and by every caller dialling
461
+ * the same peer from the same node, since they share its connection.
462
+ */
463
+ async function openGatedStream(node, peer, proto, dialOptions) {
464
+ const gate = streamGateFor(node, peer);
465
+ while (!isProven(gate)) {
466
+ if (gate.firstOpening == null) {
467
+ const opening = node.dialProtocol(peer, [proto], dialOptions);
468
+ gate.firstOpening = opening;
469
+ try {
470
+ const stream = await opening;
471
+ gate.proven = { connection: connectionOf(node, stream) };
472
+ return stream;
473
+ } finally {
474
+ gate.firstOpening = null;
475
+ }
476
+ }
477
+ await gate.firstOpening.catch(() => void 0);
478
+ }
479
+ return node.dialProtocol(peer, [proto], dialOptions);
480
+ }
481
+ //#endregion
482
+ //#region src/connect-serve.ts
483
+ const DEFAULT_PROTOCOL = "/webrun-streams/1.0.0";
484
+ /**
485
+ * Builds the options object passed to `node.dialProtocol`/`node.handle`,
486
+ * omitting any field the caller didn't supply rather than setting it to
487
+ * `undefined` — so an unset field falls back to libp2p's own default instead
488
+ * of an explicit `undefined` overriding it.
489
+ */
490
+ function definedOptions(fields) {
491
+ const options = {};
492
+ let any = false;
493
+ for (const key of Object.keys(fields)) {
494
+ const value = fields[key];
495
+ if (value !== void 0) {
496
+ options[key] = value;
497
+ any = true;
498
+ }
499
+ }
500
+ return any ? options : void 0;
501
+ }
502
+ /**
503
+ * Caller-side: each `call(input)` opens a new libp2p `Stream` via
504
+ * `node.dialProtocol(peer, [protocol])` and runs the call over it.
505
+ */
506
+ const connect = async ({ node, peer, protocol, drainTimeoutMs, readHighWaterBytes, maxOutboundStreams, runOnLimitedConnection }) => {
390
507
  const proto = protocol ?? "/webrun-streams/1.0.0";
391
508
  const dialOptions = definedOptions({
392
509
  maxOutboundStreams,
393
510
  runOnLimitedConnection
394
511
  });
395
512
  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
- };
513
+ const openStream = () => openGatedStream(node, peer, proto, dialOptions);
414
514
  const call = (input) => {
415
515
  let streamRef = null;
416
516
  const gen = (async function* () {
@@ -421,6 +521,7 @@ const connect = async ({ node, peer, protocol, drainTimeoutMs, maxOutboundStream
421
521
  try {
422
522
  yield* duplexOverStream(stream, input, {
423
523
  drainTimeoutMs,
524
+ readHighWaterBytes,
424
525
  onSourceCompleted: () => {
425
526
  sourceCompleted = true;
426
527
  }
@@ -458,7 +559,7 @@ const serve = async (params, handler) => serveConnections(params, () => handler)
458
559
  * Like `serve`, but the handler is built per inbound stream and is told which
459
560
  * peer libp2p proved on that connection.
460
561
  */
461
- async function serveConnections({ node, protocol, drainTimeoutMs, maxInboundStreams, maxOutboundStreams, runOnLimitedConnection }, makeHandler) {
562
+ async function serveConnections({ node, protocol, drainTimeoutMs, readHighWaterBytes, maxInboundStreams, maxOutboundStreams, runOnLimitedConnection }, makeHandler) {
462
563
  const proto = protocol ?? "/webrun-streams/1.0.0";
463
564
  const handleOptions = definedOptions({
464
565
  maxInboundStreams,
@@ -469,16 +570,17 @@ async function serveConnections({ node, protocol, drainTimeoutMs, maxInboundStre
469
570
  let requestComplete = false;
470
571
  (async () => {
471
572
  const handler = makeHandler({ remotePeer: connection.remotePeer });
472
- const inputQueue = makeInputQueue();
473
- const output = handler(inputQueue.iter());
573
+ const inputQueue = makeInputQueue(readHighWaterBytes ?? 65536);
574
+ const output = endsWith(handler(inputQueue.iter()), () => inputQueue.abandon());
474
575
  try {
475
576
  for await (const chunk of duplexOverStream(stream, output, {
476
577
  drainTimeoutMs,
578
+ readHighWaterBytes,
477
579
  onPeerInputEnd: (err) => {
478
580
  if (err === void 0) requestComplete = true;
479
581
  inputQueue.done(err);
480
582
  }
481
- })) inputQueue.push(chunk);
583
+ })) await inputQueue.push(chunk);
482
584
  } finally {
483
585
  inputQueue.done();
484
586
  await closeStream(stream);
@@ -497,13 +599,38 @@ async function serveConnections({ node, protocol, drainTimeoutMs, maxInboundStre
497
599
  await node.unhandle(proto);
498
600
  };
499
601
  }
500
- function makeInputQueue() {
602
+ /** `source`, calling `onEnd` once when it ends, fails or is returned. */
603
+ function endsWith(source, onEnd) {
604
+ return (async function* () {
605
+ try {
606
+ yield* source;
607
+ } finally {
608
+ onEnd();
609
+ }
610
+ })();
611
+ }
612
+ function makeInputQueue(limit) {
501
613
  const slots = [];
502
614
  let wake = null;
503
615
  let closed = false;
616
+ let pulled = false;
617
+ let queued = 0;
618
+ let room = null;
619
+ const makeRoom = () => {
620
+ const r = room;
621
+ room = null;
622
+ r?.();
623
+ };
624
+ const release = () => {
625
+ slots.length = 0;
626
+ queued = 0;
627
+ makeRoom();
628
+ };
504
629
  return {
505
630
  iter() {
506
631
  return (async function* () {
632
+ if (closed) return;
633
+ pulled = true;
507
634
  try {
508
635
  while (true) {
509
636
  if (slots.length === 0) {
@@ -518,20 +645,28 @@ function makeInputQueue() {
518
645
  if (s.err) throw s.err;
519
646
  return;
520
647
  }
648
+ queued -= s.value.byteLength;
649
+ if (queued <= limit) makeRoom();
521
650
  yield s.value;
522
651
  }
523
652
  } finally {
524
653
  closed = true;
654
+ release();
525
655
  }
526
656
  })();
527
657
  },
528
658
  push(chunk) {
529
- if (closed) return;
659
+ if (closed) return Promise.resolve();
530
660
  slots.push({
531
661
  type: "value",
532
662
  value: chunk
533
663
  });
664
+ queued += chunk.byteLength;
534
665
  wake?.();
666
+ if (queued <= limit) return Promise.resolve();
667
+ return new Promise((resolve) => {
668
+ room = resolve;
669
+ });
535
670
  },
536
671
  done(err) {
537
672
  if (closed) return;
@@ -540,6 +675,12 @@ function makeInputQueue() {
540
675
  err
541
676
  });
542
677
  wake?.();
678
+ },
679
+ abandon() {
680
+ if (pulled) return;
681
+ closed = true;
682
+ release();
683
+ wake?.();
543
684
  }
544
685
  };
545
686
  }
@@ -566,7 +707,7 @@ const DEFAULT_MAX_MESSAGE_BYTES = 67108864;
566
707
  function messageTargetOverStream(stream, { maxMessageBytes = DEFAULT_MAX_MESSAGE_BYTES } = {}) {
567
708
  const listeners = /* @__PURE__ */ new Set();
568
709
  const life = new AbortController();
569
- let peerClosedWrite = false;
710
+ let peerClosedWrite = stream.remoteWriteStatus === "closed";
570
711
  const onRemoteCloseWrite = () => {
571
712
  peerClosedWrite = true;
572
713
  };
@@ -577,6 +718,7 @@ function messageTargetOverStream(stream, { maxMessageBytes = DEFAULT_MAX_MESSAGE
577
718
  };
578
719
  stream.addEventListener("remoteCloseWrite", onRemoteCloseWrite);
579
720
  stream.addEventListener("close", onClose, { once: true });
721
+ if (stream.status !== void 0 && stream.status !== "open") life.abort(new PeerGoneError());
580
722
  const deliver = (data) => {
581
723
  const event = new MessageEvent("message", { data });
582
724
  for (const listener of [...listeners]) try {
@@ -622,6 +764,7 @@ function messageTargetOverStream(stream, { maxMessageBytes = DEFAULT_MAX_MESSAGE
622
764
  return {
623
765
  signal: life.signal,
624
766
  target: {
767
+ closeSignal: life.signal,
625
768
  addEventListener: (_type, listener) => {
626
769
  listeners.add(listener);
627
770
  },
@@ -670,4 +813,150 @@ function readLength(bytes) {
670
813
  }
671
814
  }
672
815
  //#endregion
673
- export { DEFAULT_CLOSE_TIMEOUT_MS, DEFAULT_DRAIN_TIMEOUT_MS, DEFAULT_MAX_MESSAGE_BYTES, DEFAULT_PROTOCOL, PeerGoneError, connect, duplexOverStream, messageTargetOverStream, serve, serveConnections };
816
+ //#region src/port-mux.ts
817
+ /** The protocol a port's stream negotiates unless told otherwise. */
818
+ const DEFAULT_PORT_PROTOCOL = "/webrun-ports/1.0.0";
819
+ /**
820
+ * 256 KiB: what one message on a port may carry before `webrun-rpc`'s stream tier chunks a body.
821
+ * A port waits for each chunk's confirmation, so a larger chunk means fewer round trips; well
822
+ * under `messageTargetOverStream`'s 64 MiB frame ceiling.
823
+ */
824
+ const DEFAULT_PORT_MAX_MESSAGE_SIZE = 262144;
825
+ /**
826
+ * The stream limits a port mux asks libp2p for unless told otherwise: every concurrent call is a
827
+ * stream, and libp2p's own default (32 per protocol) would reset the 33rd.
828
+ */
829
+ const DEFAULT_PORT_STREAM_LIMIT = 1024;
830
+ /**
831
+ * Native MessagePorts over libp2p: every port is its own libp2p stream, which yamux multiplexes
832
+ * with its own per-stream flow control, framed as messages by `messageTargetOverStream`. Hand it
833
+ * to `webrun-rpc` as a port source and its stream tier runs one call per port, with its tested
834
+ * backpressure — a producer stays one confirmed chunk ahead of its consumer — instead of
835
+ * libp2p's own buffering, which lets a producer run tens of megabytes ahead of a consumer that
836
+ * stopped reading:
837
+ *
838
+ * ```ts
839
+ * const codec = { encode: serialize, decode: deserialize }; // webrun-msgpack
840
+ * await serve({ mux: overPorts((onPort) => libp2pPortMux({ node, codec, onPort })) }, handler);
841
+ * const { call } = await connect({ mux: overPorts(() => libp2pPortMux({ node, codec, peer })) });
842
+ * ```
843
+ *
844
+ * Each port carries `closeSignal`, aborted when its stream ends or its peer goes, so a call on a
845
+ * dead stream fails instead of waiting. Streams are opened through the same early-stream gate as
846
+ * `connect()`. `meta` is not sent: the protocol says what a port is for.
847
+ */
848
+ async function libp2pPortMux(options) {
849
+ const { node, peer, codec, onPort, maxMessageBytes, runOnLimitedConnection } = options;
850
+ const maxInboundStreams = options.maxInboundStreams ?? 1024;
851
+ const maxOutboundStreams = options.maxOutboundStreams ?? 1024;
852
+ const protocol = options.protocol ?? "/webrun-ports/1.0.0";
853
+ const maxMessageSize = options.maxMessageSize ?? 262144;
854
+ const live = /* @__PURE__ */ new Set();
855
+ let closed = false;
856
+ const wrap = (stream) => {
857
+ const { target: inner } = messageTargetOverStream(stream, { maxMessageBytes });
858
+ const wrapped = /* @__PURE__ */ new Map();
859
+ const local = new AbortController();
860
+ const port = {
861
+ closeSignal: AbortSignal.any([inner.closeSignal, local.signal]),
862
+ get bufferedAmount() {
863
+ return inner.bufferedAmount;
864
+ },
865
+ whenDrained: () => inner.whenDrained(),
866
+ postMessage(message) {
867
+ inner.postMessage(codec.encode(message));
868
+ },
869
+ addEventListener(_type, listener) {
870
+ if (wrapped.has(listener)) return;
871
+ const decoding = (event) => {
872
+ let data;
873
+ try {
874
+ data = codec.decode(event.data);
875
+ } catch (err) {
876
+ stream.abort(new Error("webrun-streams-libp2p: a frame the port's codec cannot decode", { cause: err }));
877
+ return;
878
+ }
879
+ return listener(new MessageEvent("message", { data }));
880
+ };
881
+ wrapped.set(listener, decoding);
882
+ inner.addEventListener("message", decoding);
883
+ },
884
+ removeEventListener(_type, listener) {
885
+ const decoding = wrapped.get(listener);
886
+ if (!decoding) return;
887
+ wrapped.delete(listener);
888
+ inner.removeEventListener("message", decoding);
889
+ },
890
+ async close() {
891
+ live.delete(port);
892
+ if (!local.signal.aborted) local.abort(/* @__PURE__ */ new Error("webrun-streams-libp2p: port closed"));
893
+ await inner.close();
894
+ }
895
+ };
896
+ live.add(port);
897
+ inner.closeSignal.addEventListener("abort", () => live.delete(port), { once: true });
898
+ return port;
899
+ };
900
+ let handled = false;
901
+ if (onPort) {
902
+ const handleOptions = {
903
+ maxInboundStreams,
904
+ maxOutboundStreams
905
+ };
906
+ if (runOnLimitedConnection !== void 0) handleOptions.runOnLimitedConnection = runOnLimitedConnection;
907
+ await node.handle(protocol, (stream, connection) => {
908
+ if (closed) {
909
+ stream.abort(/* @__PURE__ */ new Error("webrun-streams-libp2p: port mux closed"));
910
+ return;
911
+ }
912
+ const port = wrap(stream);
913
+ let accepted = false;
914
+ try {
915
+ accepted = onPort(port, {
916
+ remotePeer: connection.remotePeer,
917
+ connection
918
+ }) !== false;
919
+ } catch {
920
+ accepted = false;
921
+ }
922
+ if (!accepted) {
923
+ live.delete(port);
924
+ stream.abort(/* @__PURE__ */ new Error("webrun-streams-libp2p: port refused"));
925
+ }
926
+ }, handleOptions);
927
+ handled = true;
928
+ }
929
+ const dialOptions = { maxOutboundStreams };
930
+ if (runOnLimitedConnection !== void 0) dialOptions.runOnLimitedConnection = runOnLimitedConnection;
931
+ return {
932
+ maxMessageSize,
933
+ async openPort(_meta, opts) {
934
+ if (closed) throw new Error("webrun-streams-libp2p: port mux closed");
935
+ if (!peer) throw new Error("webrun-streams-libp2p: openPort needs `peer`");
936
+ const stream = await openGatedStream(node, peer, protocol, {
937
+ ...dialOptions,
938
+ signal: opts?.signal
939
+ });
940
+ if (closed) {
941
+ await closeStream(stream);
942
+ throw new Error("webrun-streams-libp2p: port mux closed");
943
+ }
944
+ const port = wrap(stream);
945
+ const signal = opts?.signal;
946
+ if (signal) {
947
+ const onAbort = () => void port.close();
948
+ signal.addEventListener("abort", onAbort, { once: true });
949
+ port.closeSignal.addEventListener("abort", () => signal.removeEventListener("abort", onAbort), { once: true });
950
+ }
951
+ return port;
952
+ },
953
+ async close() {
954
+ if (closed) return;
955
+ closed = true;
956
+ if (handled) await node.unhandle(protocol).catch(() => void 0);
957
+ await Promise.allSettled([...live].map((p) => p.close()));
958
+ }
959
+ };
960
+ }
961
+ //#endregion
962
+ export { DEFAULT_CLOSE_TIMEOUT_MS, DEFAULT_DRAIN_TIMEOUT_MS, 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 };
@@ -18,6 +18,8 @@ export interface StreamMessageTarget {
18
18
  * closed; at once when it can now.
19
19
  */
20
20
  whenDrained(): Promise<void>;
21
+ /** `signal` again, on the target: `webrun-rpc`'s `getPortCloseSignal` reads it from a port. */
22
+ readonly closeSignal: AbortSignal;
21
23
  };
22
24
  /**
23
25
  * Aborts when the stream is over, after every message the peer sent has
@@ -1 +1 @@
1
- {"version":3,"file":"message-target-over-stream.d.ts","sourceRoot":"","sources":["../src/message-target-over-stream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAoB,MAAM,mBAAmB,CAAC;AASlE,KAAK,QAAQ,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE9D,uEAAuE;AACvE,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,MAAM,EAAE;QACN,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;QAC5D,mBAAmB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;QAC/D,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;QACpC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;QACvB,2CAA2C;QAC3C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;QAChC;;;WAGG;QACH,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;KAC9B,CAAC;IACF;;;;;;;OAOG;IACH,MAAM,EAAE,WAAW,CAAC;CACrB;AAED,mDAAmD;AACnD,MAAM,WAAW,8BAA8B;IAC7C;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,6EAA6E;AAC7E,eAAO,MAAM,yBAAyB,QAAmB,CAAC;AAE1D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,EAAE,eAA2C,EAAE,GAAE,8BAAmC,GACnF,mBAAmB,CAkHrB"}
1
+ {"version":3,"file":"message-target-over-stream.d.ts","sourceRoot":"","sources":["../src/message-target-over-stream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAoB,MAAM,mBAAmB,CAAC;AASlE,KAAK,QAAQ,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE9D,uEAAuE;AACvE,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,MAAM,EAAE;QACN,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;QAC5D,mBAAmB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;QAC/D,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;QACpC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;QACvB,2CAA2C;QAC3C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;QAChC;;;WAGG;QACH,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;QAC7B,+FAA+F;QAC/F,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;KACnC,CAAC;IACF;;;;;;;OAOG;IACH,MAAM,EAAE,WAAW,CAAC;CACrB;AAED,mDAAmD;AACnD,MAAM,WAAW,8BAA8B;IAC7C;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,6EAA6E;AAC7E,eAAO,MAAM,yBAAyB,QAAmB,CAAC;AAE1D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,EAAE,eAA2C,EAAE,GAAE,8BAAmC,GACnF,mBAAmB,CAwHrB"}
@@ -0,0 +1,89 @@
1
+ import type { Connection, Libp2p, PeerId } from "@libp2p/interface";
2
+ import type { Multiaddr } from "@multiformats/multiaddr";
3
+ import { type StreamMessageTarget } from "./message-target-over-stream.js";
4
+ /** The protocol a port's stream negotiates unless told otherwise. */
5
+ export declare const DEFAULT_PORT_PROTOCOL = "/webrun-ports/1.0.0";
6
+ /**
7
+ * 256 KiB: what one message on a port may carry before `webrun-rpc`'s stream tier chunks a body.
8
+ * A port waits for each chunk's confirmation, so a larger chunk means fewer round trips; well
9
+ * under `messageTargetOverStream`'s 64 MiB frame ceiling.
10
+ */
11
+ export declare const DEFAULT_PORT_MAX_MESSAGE_SIZE: number;
12
+ /**
13
+ * How a port's messages become bytes on its stream and back: any value the stream tier posts
14
+ * (objects holding `Uint8Array` chunks, serialised errors). `webrun-msgpack`'s `serialize` and
15
+ * `deserialize` fit: `{ encode: serialize, decode: deserialize }`.
16
+ */
17
+ export interface ValueCodec {
18
+ encode(value: unknown): Uint8Array;
19
+ decode(bytes: Uint8Array): unknown;
20
+ }
21
+ type Listener = (event: MessageEvent) => void | Promise<void>;
22
+ /**
23
+ * The stream limits a port mux asks libp2p for unless told otherwise: every concurrent call is a
24
+ * stream, and libp2p's own default (32 per protocol) would reset the 33rd.
25
+ */
26
+ export declare const DEFAULT_PORT_STREAM_LIMIT = 1024;
27
+ /** One port: a libp2p stream as a `MessageTarget` of values, with its close signal on it. */
28
+ export type StreamPort = Omit<StreamMessageTarget["target"], "addEventListener" | "removeEventListener"> & {
29
+ addEventListener(type: "message", listener: Listener): void;
30
+ removeEventListener(type: "message", listener: Listener): void;
31
+ };
32
+ /** What the serving side learns about a port the peer opened. */
33
+ export interface InboundPortInfo {
34
+ /** The peer libp2p's Noise handshake proved for the connection the stream came on. */
35
+ remotePeer: PeerId;
36
+ connection: Connection;
37
+ }
38
+ export interface Libp2pPortMuxOptions {
39
+ node: Libp2p;
40
+ /** Encodes each message as one frame; see {@link ValueCodec}. Both ends must agree. */
41
+ codec: ValueCodec;
42
+ /** The protocol each port's stream negotiates. Default {@link DEFAULT_PORT_PROTOCOL}. */
43
+ protocol?: string;
44
+ /** Whom `openPort` dials. Required to open ports; a serving-only mux leaves it out. */
45
+ peer?: PeerId | Multiaddr;
46
+ /**
47
+ * Called for each port the peer opens (each inbound stream). Return `false` to refuse it: the
48
+ * stream is aborted. Leave it out to accept none (the protocol is not handled).
49
+ */
50
+ onPort?: (port: StreamPort, info: InboundPortInfo) => boolean | undefined;
51
+ /** Reported as `maxMessageSize`. Default {@link DEFAULT_PORT_MAX_MESSAGE_SIZE}. */
52
+ maxMessageSize?: number;
53
+ /** The largest frame accepted on a port's stream (see `messageTargetOverStream`). */
54
+ maxMessageBytes?: number;
55
+ /** Default {@link DEFAULT_PORT_STREAM_LIMIT}. */
56
+ maxInboundStreams?: number;
57
+ /** Default {@link DEFAULT_PORT_STREAM_LIMIT}. */
58
+ maxOutboundStreams?: number;
59
+ runOnLimitedConnection?: boolean;
60
+ }
61
+ /** A `webrun-rpc` `PortMux` by shape; this package imports nothing from it. */
62
+ export interface Libp2pPortMux {
63
+ openPort(meta?: unknown, options?: {
64
+ signal?: AbortSignal;
65
+ }): Promise<StreamPort>;
66
+ close(reason?: unknown): Promise<void>;
67
+ readonly maxMessageSize: number;
68
+ }
69
+ /**
70
+ * Native MessagePorts over libp2p: every port is its own libp2p stream, which yamux multiplexes
71
+ * with its own per-stream flow control, framed as messages by `messageTargetOverStream`. Hand it
72
+ * to `webrun-rpc` as a port source and its stream tier runs one call per port, with its tested
73
+ * backpressure — a producer stays one confirmed chunk ahead of its consumer — instead of
74
+ * libp2p's own buffering, which lets a producer run tens of megabytes ahead of a consumer that
75
+ * stopped reading:
76
+ *
77
+ * ```ts
78
+ * const codec = { encode: serialize, decode: deserialize }; // webrun-msgpack
79
+ * await serve({ mux: overPorts((onPort) => libp2pPortMux({ node, codec, onPort })) }, handler);
80
+ * const { call } = await connect({ mux: overPorts(() => libp2pPortMux({ node, codec, peer })) });
81
+ * ```
82
+ *
83
+ * Each port carries `closeSignal`, aborted when its stream ends or its peer goes, so a call on a
84
+ * dead stream fails instead of waiting. Streams are opened through the same early-stream gate as
85
+ * `connect()`. `meta` is not sent: the protocol says what a port is for.
86
+ */
87
+ export declare function libp2pPortMux(options: Libp2pPortMuxOptions): Promise<Libp2pPortMux>;
88
+ export {};
89
+ //# sourceMappingURL=port-mux.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"port-mux.d.ts","sourceRoot":"","sources":["../src/port-mux.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EAEV,MAAM,EACN,MAAM,EAGP,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD,OAAO,EAA2B,KAAK,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAGpG,qEAAqE;AACrE,eAAO,MAAM,qBAAqB,wBAAwB,CAAC;AAE3D;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,QAAa,CAAC;AAExD;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAAC;IACnC,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC;CACpC;AAED,KAAK,QAAQ,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE9D;;;GAGG;AACH,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAE9C,6FAA6F;AAC7F,MAAM,MAAM,UAAU,GAAG,IAAI,CAC3B,mBAAmB,CAAC,QAAQ,CAAC,EAC7B,kBAAkB,GAAG,qBAAqB,CAC3C,GAAG;IACF,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC5D,mBAAmB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;CAChE,CAAC;AAEF,iEAAiE;AACjE,MAAM,WAAW,eAAe;IAC9B,sFAAsF;IACtF,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,uFAAuF;IACvF,KAAK,EAAE,UAAU,CAAC;IAClB,yFAAyF;IACzF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uFAAuF;IACvF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,eAAe,KAAK,OAAO,GAAG,SAAS,CAAC;IAC1E,mFAAmF;IACnF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qFAAqF;IACrF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iDAAiD;IACjD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iDAAiD;IACjD,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,+EAA+E;AAC/E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAClF,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,aAAa,CAAC,CAmIzF"}
@@ -0,0 +1,10 @@
1
+ import type { DialProtocolOptions, Libp2p, PeerId, Stream } from "@libp2p/interface";
2
+ import type { Multiaddr } from "@multiformats/multiaddr";
3
+ /**
4
+ * Opens a stream to `peer` for `proto`, one at a time until the remote has proven ready: a burst
5
+ * of streams on a connection the remote is still upgrading makes yamux abort the whole muxer
6
+ * (`maxEarlyStreams`). Shared by `connect()` and `libp2pPortMux`, and by every caller dialling
7
+ * the same peer from the same node, since they share its connection.
8
+ */
9
+ export declare function openGatedStream(node: Libp2p, peer: PeerId | Multiaddr, proto: string, dialOptions?: DialProtocolOptions): Promise<Stream>;
10
+ //# sourceMappingURL=stream-gate.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"stream-gate.d.ts","sourceRoot":"","sources":["../src/stream-gate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,mBAAmB,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AACjG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AA+CzD;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,KAAK,EAAE,MAAM,EACb,WAAW,CAAC,EAAE,mBAAmB,GAChC,OAAO,CAAC,MAAM,CAAC,CAiBjB"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@statewalker/webrun-streams-libp2p",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "libp2p native multi-stream Connect/Serve adapter in the webrun-streams-* family",
@@ -30,7 +30,7 @@
30
30
  "src"
31
31
  ],
32
32
  "dependencies": {
33
- "@statewalker/webrun-streams": "^0.2.3"
33
+ "@statewalker/webrun-streams": "^0.3.0"
34
34
  },
35
35
  "peerDependencies": {
36
36
  "@libp2p/interface": "^3.0.0",
@@ -56,10 +56,10 @@
56
56
  "rolldown": "^1.2.12",
57
57
  "tsx": "^4.23.15",
58
58
  "typescript": "^7.0.2",
59
- "vitest": "^5.0.3",
60
- "@statewalker/webrun-msgpack": "^0.6.0",
61
- "@statewalker/webrun-rpc": "^0.7.0",
62
- "@statewalker/webrun-streams-conformance": "^0.3.3"
59
+ "vitest": "^5.0.5",
60
+ "@statewalker/webrun-rpc": "^0.11.0",
61
+ "@statewalker/webrun-msgpack": "^0.10.0",
62
+ "@statewalker/webrun-streams-conformance": "^0.4.0"
63
63
  },
64
64
  "sideEffects": false,
65
65
  "publishConfig": {