@statewalker/webrun-streams-libp2p 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -57,7 +57,7 @@ runs (Node or browser).
57
57
  | `duplexOverStream(stream, input, options?)` | The primitive under both: runs one call over one libp2p `Stream`. Returns an `AsyncGenerator<Uint8Array>` of the peer's bytes. |
58
58
  | `PeerGoneError` | What a call fails with when the stream ended before both sides finished it: the peer died, the connection dropped, or the stream was reset after the peer's side ended. `cause` is libp2p's close error, if any. |
59
59
  | `messageTargetOverStream(stream, options?)` | `{ target, signal }`: one stream as a pipe of `Uint8Array` messages for `multiplexPort` / `overPipe`, and an `AbortSignal` that aborts when the stream is over. `options.maxMessageBytes` caps one message. See below. |
60
- | `libp2pPortMux(options)` | Native MessagePorts: a `webrun-rpc` `PortMux` (by shape) whose every port is its own libp2p stream, for `overPorts`. `options`: `node`, `codec` (a value codec: `{ encode: serialize, decode: deserialize }` from `webrun-msgpack`), `peer` (to open ports), `onPort(port, { remotePeer, connection })` (to accept them), `protocol`, `maxMessageSize`, stream limits. See "MessagePorts over libp2p" below. |
60
+ | `libp2pPortMux(options)` | Native MessagePorts: a `webrun-rpc` `PortMux` (by shape) whose every port is its own libp2p stream, for `overPorts`. `options`: `node`, `codec` (a value codec: `{ encode: serialize, decode: deserialize }` from `webrun-msgpack`), `peer` (to open ports), `onPort(port, { remotePeer, connection })` (to accept them), `protocol`, `maxMessageSize`, stream limits, `window`. The port lifecycle (codec wrapping, messages held until a port's first listener, close signals, accept/refuse, the caller's signal, close-all) is the shared `newNativePortMux` from `@statewalker/webrun-streams`; `describePortMux` (`webrun-streams-conformance`) is its contract, run against this transport too. Messages that arrive before a port's first listener are now held for it, as over WebRTC. See "MessagePorts over libp2p" below. |
61
61
  | `DEFAULT_PORT_PROTOCOL`, `DEFAULT_PORT_MAX_MESSAGE_SIZE` | `"/webrun-ports/1.0.0"`, 256 KiB. |
62
62
  | `DEFAULT_PROTOCOL` | `"/webrun-streams/1.0.0"`. |
63
63
  | `DEFAULT_DRAIN_TIMEOUT_MS` | `300_000` (5 minutes). |
@@ -336,6 +336,17 @@ Both pass the shared conformance suite, including L6 at a one-chunk bound
336
336
  | who is calling | `onPort` gets `{ remotePeer, connection }` | the stream's connection, once |
337
337
  | 4 MiB echo, in-process TCP, setup excluded (three runs) | 35–38 MiB/s (64 KiB chunks), 71–88 MiB/s (256 KiB) | 37–48 MiB/s, 79–87 MiB/s |
338
338
 
339
+ **A window per port.** By default the stream tier waits for each chunk's
340
+ confirmation on a native port, so one call moves one chunk (256 KiB) per round
341
+ trip. With `window: n` (bytes) on both ends, a port's stream negotiates
342
+ `windowProtocolOf(protocol)` (`protocol` + `/window`), each end grants the other
343
+ `n` bytes of messages delivered and not yet consumed, and the stream tier
344
+ pipelines its chunks up to the peer's window (statewalker/webrun-wire#153). A
345
+ mux with `window` dials the windowed protocol first and falls back to
346
+ `protocol`, and serves both, so it works against an older peer, unwindowed.
347
+ `describePortWindow` (`webrun-streams-conformance`) and L6 at the window's bound
348
+ run against it (`tests/port-window.test.ts`).
349
+
339
350
  Each native port carries `closeSignal`, aborted when its stream ends, the peer
340
351
  goes, or the port is closed here; `webrun-rpc`'s `getPortCloseSignal` reads it
341
352
  from the port, so a call on a dead stream fails instead of waiting, and this
package/dist/index.js CHANGED
@@ -1,4 +1,4 @@
1
- import { deserializeError, serializeError } from "@statewalker/webrun-streams";
1
+ import { deserializeError, newNativePortMux, serializeError } from "@statewalker/webrun-streams";
2
2
  //#region src/duplex-over-stream.ts
3
3
  const TYPE_DATA = 0;
4
4
  const TYPE_ERROR = 2;
@@ -515,10 +515,11 @@ function connectionOf(node, stream) {
515
515
  * the same peer from the same node, since they share its connection.
516
516
  */
517
517
  async function openGatedStream(node, peer, proto, dialOptions) {
518
+ const protocols = Array.isArray(proto) ? proto : [proto];
518
519
  const gate = streamGateFor(node, peer);
519
520
  while (!isProven(gate)) {
520
521
  if (gate.firstOpening == null) {
521
- const opening = node.dialProtocol(peer, [proto], dialOptions);
522
+ const opening = node.dialProtocol(peer, protocols, dialOptions);
522
523
  gate.firstOpening = opening;
523
524
  try {
524
525
  const stream = await opening;
@@ -530,7 +531,7 @@ async function openGatedStream(node, peer, proto, dialOptions) {
530
531
  }
531
532
  await gate.firstOpening.catch(() => void 0);
532
533
  }
533
- return node.dialProtocol(peer, [proto], dialOptions);
534
+ return node.dialProtocol(peer, protocols, dialOptions);
534
535
  }
535
536
  //#endregion
536
537
  //#region src/connect-serve.ts
@@ -861,6 +862,14 @@ function toBytes(message) {
861
862
  /** The protocol a port's stream negotiates unless told otherwise. */
862
863
  const DEFAULT_PORT_PROTOCOL = "/webrun-ports/1.0.0";
863
864
  /**
865
+ * The protocol a windowed port's stream negotiates, for a mux whose ports
866
+ * negotiate `protocol`: `protocol` with `/window` appended. A mux with
867
+ * `window` dials it first and falls back to `protocol`, and serves both.
868
+ */
869
+ function windowProtocolOf(protocol) {
870
+ return `${protocol}/window`;
871
+ }
872
+ /**
864
873
  * 256 KiB: what one message on a port may carry before `webrun-rpc`'s stream tier chunks a body.
865
874
  * A port waits for each chunk's confirmation, so a larger chunk means fewer round trips; well
866
875
  * under `messageTargetOverStream`'s 64 MiB frame ceiling.
@@ -895,112 +904,60 @@ async function libp2pPortMux(options) {
895
904
  const maxOutboundStreams = options.maxOutboundStreams ?? 1024;
896
905
  const protocol = options.protocol ?? "/webrun-ports/1.0.0";
897
906
  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
- };
907
+ const { window } = options;
908
+ const windowProtocol = windowProtocolOf(protocol);
909
+ /**
910
+ * A stream as a channel: framed bytes, and a reset to break it off (the peer hears it). The
911
+ * protocol it negotiated says whether both ends run the window.
912
+ */
913
+ const channelOf = (stream) => ({
914
+ pipe: messageTargetOverStream(stream, { maxMessageBytes }).target,
915
+ fail: (reason) => stream.abort(reason),
916
+ ...window !== void 0 && stream.protocol === windowProtocol ? { window: "agreed" } : {}
917
+ });
918
+ const dialOptions = { maxOutboundStreams };
919
+ if (runOnLimitedConnection !== void 0) dialOptions.runOnLimitedConnection = runOnLimitedConnection;
944
920
  let handled = false;
921
+ const control = newNativePortMux({
922
+ name: "webrun-streams-libp2p",
923
+ codec,
924
+ maxMessageSize,
925
+ onPort,
926
+ window,
927
+ async open(signal) {
928
+ if (!peer) throw new Error("webrun-streams-libp2p: openPort needs `peer`");
929
+ const stream = await openGatedStream(node, peer, window !== void 0 ? [windowProtocol, protocol] : protocol, {
930
+ ...dialOptions,
931
+ signal
932
+ });
933
+ return channelOf(stream);
934
+ },
935
+ async stopAccepting() {
936
+ if (!handled) return;
937
+ const served = window !== void 0 ? [protocol, windowProtocol] : [protocol];
938
+ await node.unhandle(served).catch(() => void 0);
939
+ }
940
+ });
945
941
  if (onPort) {
946
942
  const handleOptions = {
947
943
  maxInboundStreams,
948
944
  maxOutboundStreams
949
945
  };
950
946
  if (runOnLimitedConnection !== void 0) handleOptions.runOnLimitedConnection = runOnLimitedConnection;
951
- await node.handle(protocol, (stream, connection) => {
952
- if (closed) {
947
+ const served = window !== void 0 ? [protocol, windowProtocol] : [protocol];
948
+ await node.handle(served, (stream, connection) => {
949
+ if (control.closed) {
953
950
  stream.abort(/* @__PURE__ */ new Error("webrun-streams-libp2p: port mux closed"));
954
951
  return;
955
952
  }
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
- }
953
+ control.accept(channelOf(stream), {
954
+ remotePeer: connection.remotePeer,
955
+ connection
956
+ });
970
957
  }, handleOptions);
971
958
  handled = true;
972
959
  }
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
- };
960
+ return control.mux;
1004
961
  }
1005
962
  //#endregion
1006
963
  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 };
@@ -1,34 +1,31 @@
1
1
  import type { Connection, Libp2p, PeerId } from "@libp2p/interface";
2
2
  import type { Multiaddr } from "@multiformats/multiaddr";
3
- import { type StreamMessageTarget } from "./message-target-over-stream.js";
3
+ import { type NativePort, type ValueCodec } from "@statewalker/webrun-streams";
4
+ export type { ValueCodec };
4
5
  /** The protocol a port's stream negotiates unless told otherwise. */
5
6
  export declare const DEFAULT_PORT_PROTOCOL = "/webrun-ports/1.0.0";
7
+ /**
8
+ * The protocol a windowed port's stream negotiates, for a mux whose ports
9
+ * negotiate `protocol`: `protocol` with `/window` appended. A mux with
10
+ * `window` dials it first and falls back to `protocol`, and serves both.
11
+ */
12
+ export declare function windowProtocolOf(protocol: string): string;
6
13
  /**
7
14
  * 256 KiB: what one message on a port may carry before `webrun-rpc`'s stream tier chunks a body.
8
15
  * A port waits for each chunk's confirmation, so a larger chunk means fewer round trips; well
9
16
  * under `messageTargetOverStream`'s 64 MiB frame ceiling.
10
17
  */
11
18
  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
19
  /**
23
20
  * The stream limits a port mux asks libp2p for unless told otherwise: every concurrent call is a
24
21
  * stream, and libp2p's own default (32 per protocol) would reset the 33rd.
25
22
  */
26
23
  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
- };
24
+ /**
25
+ * One port: a libp2p stream as a `MessageTarget` of values, with its close signal on it. Built by
26
+ * the shared native port lifecycle (`newNativePortMux` in `@statewalker/webrun-streams`).
27
+ */
28
+ export type StreamPort = NativePort;
32
29
  /** What the serving side learns about a port the peer opened. */
33
30
  export interface InboundPortInfo {
34
31
  /** The peer libp2p's Noise handshake proved for the connection the stream came on. */
@@ -57,6 +54,19 @@ export interface Libp2pPortMuxOptions {
57
54
  /** Default {@link DEFAULT_PORT_STREAM_LIMIT}. */
58
55
  maxOutboundStreams?: number;
59
56
  runOnLimitedConnection?: boolean;
57
+ /**
58
+ * Per-port flow control, in bytes (off when unset; from 64 KiB,
59
+ * `MIN_PORT_WINDOW` in `@statewalker/webrun-streams`): the most this end holds of a port's messages
60
+ * delivered and not yet consumed (statewalker/webrun-wire#153). A port
61
+ * whose two ends both set it negotiates {@link windowProtocolOf} `protocol`,
62
+ * and `webrun-rpc`'s stream tier then pipelines its chunks, up to the
63
+ * peer's window in flight, instead of waiting for each chunk's
64
+ * confirmation; against a mux without it (an older peer) the port
65
+ * negotiates `protocol` and runs as before. 1-4 MiB is a reasonable range:
66
+ * the most one call moves per round trip, and the most a producer runs
67
+ * ahead of a consumer that stopped reading.
68
+ */
69
+ window?: number;
60
70
  }
61
71
  /** A `webrun-rpc` `PortMux` by shape; this package imports nothing from it. */
62
72
  export interface Libp2pPortMux {
@@ -85,5 +95,4 @@ export interface Libp2pPortMux {
85
95
  * `connect()`. `meta` is not sent: the protocol says what a port is for.
86
96
  */
87
97
  export declare function libp2pPortMux(options: Libp2pPortMuxOptions): Promise<Libp2pPortMux>;
88
- export {};
89
98
  //# sourceMappingURL=port-mux.d.ts.map
@@ -1 +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"}
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;AACzD,OAAO,EAEL,KAAK,UAAU,EAEf,KAAK,UAAU,EAChB,MAAM,6BAA6B,CAAC;AAIrC,YAAY,EAAE,UAAU,EAAE,CAAC;AAE3B,qEAAqE;AACrE,eAAO,MAAM,qBAAqB,wBAAwB,CAAC;AAE3D;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,QAAa,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAE9C;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,UAAU,CAAC;AAEpC,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;IACjC;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;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,CAmEzF"}
@@ -6,5 +6,5 @@ import type { Multiaddr } from "@multiformats/multiaddr";
6
6
  * (`maxEarlyStreams`). Shared by `connect()` and `libp2pPortMux`, and by every caller dialling
7
7
  * the same peer from the same node, since they share its connection.
8
8
  */
9
- export declare function openGatedStream(node: Libp2p, peer: PeerId | Multiaddr, proto: string, dialOptions?: DialProtocolOptions): Promise<Stream>;
9
+ export declare function openGatedStream(node: Libp2p, peer: PeerId | Multiaddr, proto: string | string[], dialOptions?: DialProtocolOptions): Promise<Stream>;
10
10
  //# sourceMappingURL=stream-gate.d.ts.map
@@ -1 +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"}
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,GAAG,MAAM,EAAE,EACxB,WAAW,CAAC,EAAE,mBAAmB,GAChC,OAAO,CAAC,MAAM,CAAC,CAmBjB"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@statewalker/webrun-streams-libp2p",
3
- "version": "0.4.0",
3
+ "version": "0.6.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.4.0"
33
+ "@statewalker/webrun-streams": "^0.6.0"
34
34
  },
35
35
  "peerDependencies": {
36
36
  "@libp2p/interface": "^3.0.0",
@@ -57,9 +57,9 @@
57
57
  "tsx": "^4.23.15",
58
58
  "typescript": "^7.0.2",
59
59
  "vitest": "^5.0.5",
60
- "@statewalker/webrun-msgpack": "^0.11.0",
61
- "@statewalker/webrun-rpc": "^0.12.0",
62
- "@statewalker/webrun-streams-conformance": "^0.5.0"
60
+ "@statewalker/webrun-msgpack": "^0.13.0",
61
+ "@statewalker/webrun-rpc": "^0.14.0",
62
+ "@statewalker/webrun-streams-conformance": "^0.7.0"
63
63
  },
64
64
  "sideEffects": false,
65
65
  "publishConfig": {
package/src/port-mux.ts CHANGED
@@ -7,13 +7,29 @@ import type {
7
7
  StreamHandlerOptions,
8
8
  } from "@libp2p/interface";
9
9
  import type { Multiaddr } from "@multiformats/multiaddr";
10
- import { closeStream } from "./duplex-over-stream.js";
11
- import { messageTargetOverStream, type StreamMessageTarget } from "./message-target-over-stream.js";
10
+ import {
11
+ type NativeChannel,
12
+ type NativePort,
13
+ newNativePortMux,
14
+ type ValueCodec,
15
+ } from "@statewalker/webrun-streams";
16
+ import { messageTargetOverStream } from "./message-target-over-stream.js";
12
17
  import { openGatedStream } from "./stream-gate.js";
13
18
 
19
+ export type { ValueCodec };
20
+
14
21
  /** The protocol a port's stream negotiates unless told otherwise. */
15
22
  export const DEFAULT_PORT_PROTOCOL = "/webrun-ports/1.0.0";
16
23
 
24
+ /**
25
+ * The protocol a windowed port's stream negotiates, for a mux whose ports
26
+ * negotiate `protocol`: `protocol` with `/window` appended. A mux with
27
+ * `window` dials it first and falls back to `protocol`, and serves both.
28
+ */
29
+ export function windowProtocolOf(protocol: string): string {
30
+ return `${protocol}/window`;
31
+ }
32
+
17
33
  /**
18
34
  * 256 KiB: what one message on a port may carry before `webrun-rpc`'s stream tier chunks a body.
19
35
  * A port waits for each chunk's confirmation, so a larger chunk means fewer round trips; well
@@ -21,32 +37,17 @@ export const DEFAULT_PORT_PROTOCOL = "/webrun-ports/1.0.0";
21
37
  */
22
38
  export const DEFAULT_PORT_MAX_MESSAGE_SIZE = 256 * 1024;
23
39
 
24
- /**
25
- * How a port's messages become bytes on its stream and back: any value the stream tier posts
26
- * (objects holding `Uint8Array` chunks, serialised errors). `webrun-msgpack`'s `serialize` and
27
- * `deserialize` fit: `{ encode: serialize, decode: deserialize }`.
28
- */
29
- export interface ValueCodec {
30
- encode(value: unknown): Uint8Array;
31
- decode(bytes: Uint8Array): unknown;
32
- }
33
-
34
- type Listener = (event: MessageEvent) => void | Promise<void>;
35
-
36
40
  /**
37
41
  * The stream limits a port mux asks libp2p for unless told otherwise: every concurrent call is a
38
42
  * stream, and libp2p's own default (32 per protocol) would reset the 33rd.
39
43
  */
40
44
  export const DEFAULT_PORT_STREAM_LIMIT = 1024;
41
45
 
42
- /** One port: a libp2p stream as a `MessageTarget` of values, with its close signal on it. */
43
- export type StreamPort = Omit<
44
- StreamMessageTarget["target"],
45
- "addEventListener" | "removeEventListener"
46
- > & {
47
- addEventListener(type: "message", listener: Listener): void;
48
- removeEventListener(type: "message", listener: Listener): void;
49
- };
46
+ /**
47
+ * One port: a libp2p stream as a `MessageTarget` of values, with its close signal on it. Built by
48
+ * the shared native port lifecycle (`newNativePortMux` in `@statewalker/webrun-streams`).
49
+ */
50
+ export type StreamPort = NativePort;
50
51
 
51
52
  /** What the serving side learns about a port the peer opened. */
52
53
  export interface InboundPortInfo {
@@ -77,6 +78,19 @@ export interface Libp2pPortMuxOptions {
77
78
  /** Default {@link DEFAULT_PORT_STREAM_LIMIT}. */
78
79
  maxOutboundStreams?: number;
79
80
  runOnLimitedConnection?: boolean;
81
+ /**
82
+ * Per-port flow control, in bytes (off when unset; from 64 KiB,
83
+ * `MIN_PORT_WINDOW` in `@statewalker/webrun-streams`): the most this end holds of a port's messages
84
+ * delivered and not yet consumed (statewalker/webrun-wire#153). A port
85
+ * whose two ends both set it negotiates {@link windowProtocolOf} `protocol`,
86
+ * and `webrun-rpc`'s stream tier then pipelines its chunks, up to the
87
+ * peer's window in flight, instead of waiting for each chunk's
88
+ * confirmation; against a mux without it (an older peer) the port
89
+ * negotiates `protocol` and runs as before. 1-4 MiB is a reasonable range:
90
+ * the most one call moves per round trip, and the most a producer runs
91
+ * ahead of a consumer that stopped reading.
92
+ */
93
+ window?: number;
80
94
  }
81
95
 
82
96
  /** A `webrun-rpc` `PortMux` by shape; this package imports nothing from it. */
@@ -110,129 +124,65 @@ export async function libp2pPortMux(options: Libp2pPortMuxOptions): Promise<Libp
110
124
  const maxOutboundStreams = options.maxOutboundStreams ?? DEFAULT_PORT_STREAM_LIMIT;
111
125
  const protocol = options.protocol ?? DEFAULT_PORT_PROTOCOL;
112
126
  const maxMessageSize = options.maxMessageSize ?? DEFAULT_PORT_MAX_MESSAGE_SIZE;
113
- const live = new Set<StreamPort>();
114
- let closed = false;
127
+ // Checked by the shared lifecycle, before the protocols are handled.
128
+ const { window } = options;
129
+ const windowProtocol = windowProtocolOf(protocol);
115
130
 
116
- const wrap = (stream: Stream): StreamPort => {
117
- const { target: inner } = messageTargetOverStream(stream, { maxMessageBytes });
118
- const wrapped = new Map<Listener, Listener>();
119
- // closed here, or the stream ended: a port closed locally is closed at once, not when libp2p
120
- // finishes closing its stream
121
- const local = new AbortController();
122
- const port: StreamPort = {
123
- closeSignal: AbortSignal.any([inner.closeSignal, local.signal]),
124
- get bufferedAmount() {
125
- return inner.bufferedAmount;
126
- },
127
- whenDrained: () => inner.whenDrained(),
128
- postMessage(message: unknown) {
129
- inner.postMessage(codec.encode(message));
130
- },
131
- addEventListener(_type, listener) {
132
- if (wrapped.has(listener)) return;
133
- const decoding: Listener = (event) => {
134
- let data: unknown;
135
- try {
136
- data = codec.decode(event.data as Uint8Array);
137
- } catch (err) {
138
- // a peer speaking another codec, or a corrupt frame: fail the port, as a malformed
139
- // frame fails the stream, rather than drop the message and leave its call waiting
140
- stream.abort(
141
- new Error("webrun-streams-libp2p: a frame the port's codec cannot decode", {
142
- cause: err,
143
- }),
144
- );
145
- return;
146
- }
147
- return listener(new MessageEvent("message", { data }));
148
- };
149
- wrapped.set(listener, decoding);
150
- inner.addEventListener("message", decoding);
151
- },
152
- removeEventListener(_type, listener) {
153
- const decoding = wrapped.get(listener);
154
- if (!decoding) return;
155
- wrapped.delete(listener);
156
- inner.removeEventListener("message", decoding);
157
- },
158
- async close() {
159
- live.delete(port);
160
- if (!local.signal.aborted) local.abort(new Error("webrun-streams-libp2p: port closed"));
161
- await inner.close();
162
- },
163
- };
164
- live.add(port);
165
- inner.closeSignal.addEventListener("abort", () => live.delete(port), { once: true });
166
- return port;
167
- };
131
+ /**
132
+ * A stream as a channel: framed bytes, and a reset to break it off (the peer hears it). The
133
+ * protocol it negotiated says whether both ends run the window.
134
+ */
135
+ const channelOf = (stream: Stream): NativeChannel => ({
136
+ pipe: messageTargetOverStream(stream, { maxMessageBytes }).target,
137
+ fail: (reason) => stream.abort(reason),
138
+ ...(window !== undefined && stream.protocol === windowProtocol
139
+ ? { window: "agreed" as const }
140
+ : {}),
141
+ });
142
+
143
+ const dialOptions: DialProtocolOptions = { maxOutboundStreams };
144
+ if (runOnLimitedConnection !== undefined)
145
+ dialOptions.runOnLimitedConnection = runOnLimitedConnection;
168
146
 
169
147
  let handled = false;
148
+ const control = newNativePortMux<InboundPortInfo>({
149
+ name: "webrun-streams-libp2p",
150
+ codec,
151
+ maxMessageSize,
152
+ onPort,
153
+ window,
154
+ async open(signal) {
155
+ if (!peer) throw new Error("webrun-streams-libp2p: openPort needs `peer`");
156
+ const protocols = window !== undefined ? [windowProtocol, protocol] : protocol;
157
+ const stream = await openGatedStream(node, peer, protocols, { ...dialOptions, signal });
158
+ return channelOf(stream);
159
+ },
160
+ async stopAccepting() {
161
+ if (!handled) return;
162
+ const served = window !== undefined ? [protocol, windowProtocol] : [protocol];
163
+ await node.unhandle(served).catch(() => undefined);
164
+ },
165
+ });
166
+
170
167
  if (onPort) {
171
168
  const handleOptions: StreamHandlerOptions = { maxInboundStreams, maxOutboundStreams };
172
169
  if (runOnLimitedConnection !== undefined)
173
170
  handleOptions.runOnLimitedConnection = runOnLimitedConnection;
171
+ const served = window !== undefined ? [protocol, windowProtocol] : [protocol];
174
172
  await node.handle(
175
- protocol,
173
+ served,
176
174
  (stream: Stream, connection: Connection) => {
177
- if (closed) {
175
+ if (control.closed) {
178
176
  stream.abort(new Error("webrun-streams-libp2p: port mux closed"));
179
177
  return;
180
178
  }
181
- // The port is wrapped and handed over in this tick: `messageTargetOverStream` starts
182
- // reading at once, and a message with no listener yet would be dropped.
183
- const port = wrap(stream);
184
- let accepted = false;
185
- try {
186
- accepted = onPort(port, { remotePeer: connection.remotePeer, connection }) !== false;
187
- } catch {
188
- accepted = false;
189
- }
190
- if (!accepted) {
191
- live.delete(port);
192
- stream.abort(new Error("webrun-streams-libp2p: port refused"));
193
- }
179
+ // The port is built in this tick: `messageTargetOverStream` starts reading at once.
180
+ control.accept(channelOf(stream), { remotePeer: connection.remotePeer, connection });
194
181
  },
195
182
  handleOptions,
196
183
  );
197
184
  handled = true;
198
185
  }
199
186
 
200
- const dialOptions: DialProtocolOptions = { maxOutboundStreams };
201
- if (runOnLimitedConnection !== undefined)
202
- dialOptions.runOnLimitedConnection = runOnLimitedConnection;
203
-
204
- return {
205
- maxMessageSize,
206
- async openPort(_meta, opts) {
207
- if (closed) throw new Error("webrun-streams-libp2p: port mux closed");
208
- if (!peer) throw new Error("webrun-streams-libp2p: openPort needs `peer`");
209
- const stream = await openGatedStream(node, peer, protocol, {
210
- ...dialOptions,
211
- signal: opts?.signal,
212
- });
213
- if (closed) {
214
- await closeStream(stream);
215
- throw new Error("webrun-streams-libp2p: port mux closed");
216
- }
217
- const port = wrap(stream);
218
- const signal = opts?.signal;
219
- if (signal) {
220
- const onAbort = () => void port.close();
221
- signal.addEventListener("abort", onAbort, { once: true });
222
- // the caller's signal may outlive many ports: let go of this one when it closes
223
- port.closeSignal.addEventListener(
224
- "abort",
225
- () => signal.removeEventListener("abort", onAbort),
226
- { once: true },
227
- );
228
- }
229
- return port;
230
- },
231
- async close() {
232
- if (closed) return;
233
- closed = true;
234
- if (handled) await node.unhandle(protocol).catch(() => undefined);
235
- await Promise.allSettled([...live].map((p) => p.close()));
236
- },
237
- };
187
+ return control.mux as Libp2pPortMux;
238
188
  }
@@ -55,13 +55,15 @@ function connectionOf(node: Libp2p, stream: Stream): Connection | null {
55
55
  export async function openGatedStream(
56
56
  node: Libp2p,
57
57
  peer: PeerId | Multiaddr,
58
- proto: string,
58
+ proto: string | string[],
59
59
  dialOptions?: DialProtocolOptions,
60
60
  ): Promise<Stream> {
61
+ // Several: the remote picks the first it speaks (a windowed port's protocol, then the plain one).
62
+ const protocols = Array.isArray(proto) ? proto : [proto];
61
63
  const gate = streamGateFor(node, peer);
62
64
  while (!isProven(gate)) {
63
65
  if (gate.firstOpening == null) {
64
- const opening = node.dialProtocol(peer, [proto], dialOptions);
66
+ const opening = node.dialProtocol(peer, protocols, dialOptions);
65
67
  gate.firstOpening = opening;
66
68
  try {
67
69
  const stream = await opening;
@@ -73,5 +75,5 @@ export async function openGatedStream(
73
75
  }
74
76
  await gate.firstOpening.catch(() => undefined);
75
77
  }
76
- return node.dialProtocol(peer, [proto], dialOptions);
78
+ return node.dialProtocol(peer, protocols, dialOptions);
77
79
  }