@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 +12 -1
- package/dist/index.js +53 -96
- package/dist/port-mux.d.ts +26 -17
- package/dist/port-mux.d.ts.map +1 -1
- package/dist/stream-gate.d.ts +1 -1
- package/dist/stream-gate.d.ts.map +1 -1
- package/package.json +5 -5
- package/src/port-mux.ts +79 -129
- package/src/stream-gate.ts +5 -3
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,
|
|
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,
|
|
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
|
|
899
|
-
|
|
900
|
-
|
|
901
|
-
|
|
902
|
-
|
|
903
|
-
|
|
904
|
-
|
|
905
|
-
|
|
906
|
-
|
|
907
|
-
|
|
908
|
-
|
|
909
|
-
|
|
910
|
-
|
|
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
|
-
|
|
952
|
-
|
|
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
|
-
|
|
957
|
-
|
|
958
|
-
|
|
959
|
-
|
|
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
|
-
|
|
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 };
|
package/dist/port-mux.d.ts
CHANGED
|
@@ -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
|
|
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
|
-
/**
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
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
|
package/dist/port-mux.d.ts.map
CHANGED
|
@@ -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;
|
|
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"}
|
package/dist/stream-gate.d.ts
CHANGED
|
@@ -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,
|
|
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.
|
|
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.
|
|
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.
|
|
61
|
-
"@statewalker/webrun-rpc": "^0.
|
|
62
|
-
"@statewalker/webrun-streams-conformance": "^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 {
|
|
11
|
-
|
|
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
|
-
/**
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
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
|
-
|
|
114
|
-
|
|
127
|
+
// Checked by the shared lifecycle, before the protocols are handled.
|
|
128
|
+
const { window } = options;
|
|
129
|
+
const windowProtocol = windowProtocolOf(protocol);
|
|
115
130
|
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
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
|
-
|
|
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
|
|
182
|
-
|
|
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
|
-
|
|
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
|
}
|
package/src/stream-gate.ts
CHANGED
|
@@ -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,
|
|
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,
|
|
78
|
+
return node.dialProtocol(peer, protocols, dialOptions);
|
|
77
79
|
}
|