@statewalker/webrun-streams-signaling 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -281,8 +281,9 @@ that joins, and ends at `leave()`. Departures are not reported. Only the most re
281
281
 
282
282
  ### Dependencies
283
283
 
284
- Zero runtime dependencies: the bundle imports nothing, and `ByteChannel` is declared here.
285
- `@statewalker/webrun-rpc`, `-msgpack`, `-streams` and `-streams-conformance` are dev dependencies of the tests:
284
+ One runtime dependency, `@statewalker/webrun-streams` at runtime, for `newMessagePipe`: the pipe module every transport adapter shares (listeners, delivery, life, the byte check, the frame ceiling, drain, close), so a pipe rule is fixed once for all of them (#151). The target is a `MessageTarget` by shape and carries its own `closeSignal` and `maxMessageSize`, so `overPipe(target, { codec, side })` needs nothing else. `ByteChannel` is declared here, and `messageTargetOverByteChannel`
285
+ takes an optional `maxFrameBytes`.
286
+ `@statewalker/webrun-rpc`, `-msgpack` and `-streams-conformance` are dev dependencies of the tests:
286
287
  `tests/conformance.test.ts` runs the conformance suite over `messageTargetOverByteChannel` and the
287
288
  port stack, on `byteChannelFromDataChannel` and on `byteChannelFromRoom` (in-process stand-ins for
288
289
  the data channel and the room). `livekit-client` is an optional peer, used only through the
package/dist/index.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { newMessagePipe } from "@statewalker/webrun-streams";
1
2
  //#region src/byte-queue.ts
2
3
  /**
3
4
  * Minimal eager push/pull byte queue backing the `recv` side of the
@@ -287,6 +288,8 @@ function byteChannelFromRoom(room, peerId, options = {}) {
287
288
  * reliable packets silently.
288
289
  */
289
290
  const DEFAULT_MAX_MESSAGE_SIZE = 16128;
291
+ /** How long a closed channel's `recv` may take to hand over what it still holds before the pipe ends. */
292
+ const CLOSE_DRAIN_MS = 50;
290
293
  /**
291
294
  * A `ByteChannel` this package hands back (`PeerManager`, `QrSignaling`,
292
295
  * `RoomManager`) as a pipe for `webrun-rpc`'s port stack:
@@ -304,67 +307,38 @@ const DEFAULT_MAX_MESSAGE_SIZE = 16128;
304
307
  * Messages already received when the channel closes are still delivered.
305
308
  */
306
309
  function messageTargetOverByteChannel(channel, options = {}) {
307
- const listeners = /* @__PURE__ */ new Set();
308
- const life = new AbortController();
309
- let closedHere = false;
310
- const end = (reason) => {
311
- if (!life.signal.aborted) life.abort(reason);
312
- };
313
- channel.closed.then(() => end(/* @__PURE__ */ new Error("webrun-streams-signaling: the channel closed")));
314
- (async () => {
315
- for await (const bytes of channel.recv) {
316
- if (closedHere) break;
317
- const event = new MessageEvent("message", { data: bytes.slice() });
318
- for (const listener of [...listeners]) try {
319
- Promise.resolve(listener(event)).catch(() => void 0);
310
+ const control = newMessagePipe({
311
+ send: (bytes) => channel.send(bytes),
312
+ bufferedAmount: () => channel.bufferedAmount ?? 0,
313
+ ...channel.whenDrained ? {
314
+ isDrained: () => false,
315
+ whenDrained: () => channel.whenDrained?.() ?? Promise.resolve()
316
+ } : { isDrained: () => true },
317
+ close: (local) => {
318
+ if (!local) return;
319
+ try {
320
+ channel.close();
320
321
  } catch {}
321
322
  }
322
- end(/* @__PURE__ */ new Error("webrun-streams-signaling: the channel closed"));
323
- })().catch((err) => end(err instanceof Error ? err : new Error(String(err), { cause: err })));
324
- return {
325
- signal: life.signal,
323
+ }, {
324
+ name: "webrun-streams-signaling",
326
325
  maxMessageSize: options.maxMessageSize ?? 16128,
327
- target: {
328
- addEventListener: (_type, listener) => {
329
- listeners.add(listener);
330
- },
331
- removeEventListener: (_type, listener) => {
332
- listeners.delete(listener);
333
- },
334
- postMessage(message) {
335
- const bytes = message instanceof Uint8Array ? message : message instanceof ArrayBuffer ? new Uint8Array(message) : ArrayBuffer.isView(message) ? new Uint8Array(message.buffer, message.byteOffset, message.byteLength) : void 0;
336
- if (!bytes) throw new TypeError(`webrun-streams-signaling: a byte pipe carries Uint8Array, ArrayBuffer or a view, got ${Object.prototype.toString.call(message)}`);
337
- if (life.signal.aborted) return;
338
- channel.send(bytes.slice());
339
- },
340
- async close() {
341
- listeners.clear();
342
- closedHere = true;
343
- end(/* @__PURE__ */ new Error("webrun-streams-signaling: closed locally"));
344
- try {
345
- channel.close();
346
- } catch {}
347
- },
348
- get bufferedAmount() {
349
- return channel.bufferedAmount ?? 0;
350
- },
351
- whenDrained() {
352
- if (life.signal.aborted || !channel.whenDrained) return Promise.resolve();
353
- const signal = life.signal;
354
- return new Promise((resolve, reject) => {
355
- const done = () => {
356
- signal.removeEventListener("abort", done);
357
- resolve();
358
- };
359
- signal.addEventListener("abort", done);
360
- channel.whenDrained?.().then(done, (err) => {
361
- signal.removeEventListener("abort", done);
362
- reject(err);
363
- });
364
- });
365
- }
326
+ maxFrameBytes: options.maxFrameBytes,
327
+ copyOnSend: true,
328
+ copyOnDeliver: true
329
+ });
330
+ const closedMessage = "webrun-streams-signaling: the channel closed";
331
+ (async () => {
332
+ for await (const bytes of channel.recv) {
333
+ if (control.ended) break;
334
+ control.deliver(bytes);
366
335
  }
367
- };
336
+ })().then(() => control.end(/* @__PURE__ */ new Error(closedMessage)), (err) => control.end(err instanceof Error ? err : new Error(String(err), { cause: err }), true));
337
+ channel.closed.then(() => {
338
+ if (control.ended) return;
339
+ setTimeout(() => control.end(/* @__PURE__ */ new Error(closedMessage)), CLOSE_DRAIN_MS).unref?.();
340
+ });
341
+ return control.pipe;
368
342
  }
369
343
  //#endregion
370
344
  //#region src/peer-connection.ts
@@ -1,5 +1,5 @@
1
+ import { type MessagePipe, type MessagePipeTarget } from "@statewalker/webrun-streams";
1
2
  import type { ByteChannel } from "./types.js";
2
- type Listener = (event: MessageEvent) => void | Promise<void>;
3
3
  /**
4
4
  * The payload ceiling for a channel over an `RTCDataChannel` (`PeerManager`,
5
5
  * `QrSignaling`, `PeerConnection`): 16 KiB, the message size every browser
@@ -10,23 +10,14 @@ type Listener = (event: MessageEvent) => void | Promise<void>;
10
10
  */
11
11
  export declare const DEFAULT_MAX_MESSAGE_SIZE: number;
12
12
  /** What `messageTargetOverByteChannel` gives: a pipe of bytes, its life, and its payload ceiling. */
13
- export interface ByteChannelMessageTarget {
14
- /** A `MessageTarget` (as `@statewalker/webrun-rpc` defines it) of bytes, one channel message each. */
15
- target: {
16
- addEventListener(type: "message", listener: Listener): void;
17
- removeEventListener(type: "message", listener: Listener): void;
18
- /** Sends one message; `TypeError` for anything but bytes. */
19
- postMessage(message: unknown): void;
20
- /** Closes the channel. */
21
- close(): Promise<void>;
22
- /** The channel's `bufferedAmount`; 0 where it cannot tell. */
23
- readonly bufferedAmount: number;
24
- /**
25
- * The channel's `whenDrained`: resolves once it can take more, or the pipe
26
- * ended. Resolves at once over a channel without one.
27
- */
28
- whenDrained(): Promise<void>;
29
- };
13
+ export interface ByteChannelMessageTarget extends MessagePipe {
14
+ /**
15
+ * A `MessageTarget` (as `@statewalker/webrun-rpc` defines it) of bytes, one
16
+ * channel message each. `bufferedAmount` is the channel's (0 where it cannot
17
+ * tell); `whenDrained` is the channel's, or resolves at once over a channel
18
+ * without one.
19
+ */
20
+ target: MessagePipeTarget;
30
21
  /** Aborts when the channel closes. Pass it as `overPipe`'s `signal`. */
31
22
  signal: AbortSignal;
32
23
  /** Pass as `overPipe`'s `maxMessageSize`. */
@@ -50,6 +41,6 @@ export interface ByteChannelMessageTarget {
50
41
  */
51
42
  export declare function messageTargetOverByteChannel(channel: ByteChannel, options?: {
52
43
  maxMessageSize?: number;
44
+ maxFrameBytes?: number;
53
45
  }): ByteChannelMessageTarget;
54
- export {};
55
46
  //# sourceMappingURL=message-target.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"message-target.d.ts","sourceRoot":"","sources":["../src/message-target.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,KAAK,QAAQ,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE9D;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,QAAkB,CAAC;AAExD,qGAAqG;AACrG,MAAM,WAAW,wBAAwB;IACvC,sGAAsG;IACtG,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,6DAA6D;QAC7D,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;QACpC,0BAA0B;QAC1B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;QACvB,8DAA8D;QAC9D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;QAChC;;;WAGG;QACH,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;KAC9B,CAAC;IACF,wEAAwE;IACxE,MAAM,EAAE,WAAW,CAAC;IACpB,6CAA6C;IAC7C,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,WAAW,EACpB,OAAO,GAAE;IAAE,cAAc,CAAC,EAAE,MAAM,CAAA;CAAO,GACxC,wBAAwB,CA+E1B"}
1
+ {"version":3,"file":"message-target.d.ts","sourceRoot":"","sources":["../src/message-target.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EAEvB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,QAAkB,CAAC;AAExD,qGAAqG;AACrG,MAAM,WAAW,wBAAyB,SAAQ,WAAW;IAC3D;;;;;OAKG;IACH,MAAM,EAAE,iBAAiB,CAAC;IAC1B,wEAAwE;IACxE,MAAM,EAAE,WAAW,CAAC;IACpB,6CAA6C;IAC7C,cAAc,EAAE,MAAM,CAAC;CACxB;AAKD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,WAAW,EACpB,OAAO,GAAE;IAAE,cAAc,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAO,GAChE,wBAAwB,CAoD1B"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@statewalker/webrun-streams-signaling",
3
- "version": "0.3.0",
3
+ "version": "0.4.0",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "Generic P2P signaling/connection-setup (PeerManager, QrSignaling, RoomManager) yielding ByteChannels",
@@ -37,6 +37,9 @@
37
37
  "optional": true
38
38
  }
39
39
  },
40
+ "dependencies": {
41
+ "@statewalker/webrun-streams": "^0.5.0"
42
+ },
40
43
  "devDependencies": {
41
44
  "@biomejs/biome": "^2.5.15",
42
45
  "@types/node": "^26.6.4",
@@ -45,10 +48,9 @@
45
48
  "rolldown": "^1.2.12",
46
49
  "typescript": "^7.0.2",
47
50
  "vitest": "^5.0.5",
48
- "@statewalker/webrun-msgpack": "^0.11.0",
49
- "@statewalker/webrun-streams": "^0.4.0",
50
- "@statewalker/webrun-rpc": "^0.12.0",
51
- "@statewalker/webrun-streams-conformance": "^0.5.0"
51
+ "@statewalker/webrun-msgpack": "^0.12.0",
52
+ "@statewalker/webrun-rpc": "^0.13.0",
53
+ "@statewalker/webrun-streams-conformance": "^0.6.0"
52
54
  },
53
55
  "sideEffects": false,
54
56
  "publishConfig": {
@@ -1,7 +1,10 @@
1
+ import {
2
+ type MessagePipe,
3
+ type MessagePipeTarget,
4
+ newMessagePipe,
5
+ } from "@statewalker/webrun-streams";
1
6
  import type { ByteChannel } from "./types.js";
2
7
 
3
- type Listener = (event: MessageEvent) => void | Promise<void>;
4
-
5
8
  /**
6
9
  * The payload ceiling for a channel over an `RTCDataChannel` (`PeerManager`,
7
10
  * `QrSignaling`, `PeerConnection`): 16 KiB, the message size every browser
@@ -13,29 +16,23 @@ type Listener = (event: MessageEvent) => void | Promise<void>;
13
16
  export const DEFAULT_MAX_MESSAGE_SIZE = 16 * 1024 - 256;
14
17
 
15
18
  /** What `messageTargetOverByteChannel` gives: a pipe of bytes, its life, and its payload ceiling. */
16
- export interface ByteChannelMessageTarget {
17
- /** A `MessageTarget` (as `@statewalker/webrun-rpc` defines it) of bytes, one channel message each. */
18
- target: {
19
- addEventListener(type: "message", listener: Listener): void;
20
- removeEventListener(type: "message", listener: Listener): void;
21
- /** Sends one message; `TypeError` for anything but bytes. */
22
- postMessage(message: unknown): void;
23
- /** Closes the channel. */
24
- close(): Promise<void>;
25
- /** The channel's `bufferedAmount`; 0 where it cannot tell. */
26
- readonly bufferedAmount: number;
27
- /**
28
- * The channel's `whenDrained`: resolves once it can take more, or the pipe
29
- * ended. Resolves at once over a channel without one.
30
- */
31
- whenDrained(): Promise<void>;
32
- };
19
+ export interface ByteChannelMessageTarget extends MessagePipe {
20
+ /**
21
+ * A `MessageTarget` (as `@statewalker/webrun-rpc` defines it) of bytes, one
22
+ * channel message each. `bufferedAmount` is the channel's (0 where it cannot
23
+ * tell); `whenDrained` is the channel's, or resolves at once over a channel
24
+ * without one.
25
+ */
26
+ target: MessagePipeTarget;
33
27
  /** Aborts when the channel closes. Pass it as `overPipe`'s `signal`. */
34
28
  signal: AbortSignal;
35
29
  /** Pass as `overPipe`'s `maxMessageSize`. */
36
30
  maxMessageSize: number;
37
31
  }
38
32
 
33
+ /** How long a closed channel's `recv` may take to hand over what it still holds before the pipe ends. */
34
+ const CLOSE_DRAIN_MS = 50;
35
+
39
36
  /**
40
37
  * A `ByteChannel` this package hands back (`PeerManager`, `QrSignaling`,
41
38
  * `RoomManager`) as a pipe for `webrun-rpc`'s port stack:
@@ -54,84 +51,57 @@ export interface ByteChannelMessageTarget {
54
51
  */
55
52
  export function messageTargetOverByteChannel(
56
53
  channel: ByteChannel,
57
- options: { maxMessageSize?: number } = {},
54
+ options: { maxMessageSize?: number; maxFrameBytes?: number } = {},
58
55
  ): ByteChannelMessageTarget {
59
- const listeners = new Set<Listener>();
60
- const life = new AbortController();
61
- let closedHere = false;
62
- const end = (reason: Error): void => {
63
- if (!life.signal.aborted) life.abort(reason);
64
- };
65
- void channel.closed.then(() => end(new Error("webrun-streams-signaling: the channel closed")));
66
- void (async () => {
67
- for await (const bytes of channel.recv) {
68
- // The channel closing ends `recv` after what it already holds; only a
69
- // close on this side stops delivery at once.
70
- if (closedHere) break;
71
- const event = new MessageEvent("message", { data: bytes.slice() });
72
- for (const listener of [...listeners]) {
73
- try {
74
- Promise.resolve(listener(event)).catch(() => undefined);
75
- } catch {}
76
- }
77
- }
78
- end(new Error("webrun-streams-signaling: the channel closed"));
79
- })().catch((err: unknown) =>
80
- end(err instanceof Error ? err : new Error(String(err), { cause: err })),
81
- );
82
- return {
83
- signal: life.signal,
84
- maxMessageSize: options.maxMessageSize ?? DEFAULT_MAX_MESSAGE_SIZE,
85
- target: {
86
- addEventListener: (_type, listener) => {
87
- listeners.add(listener);
88
- },
89
- removeEventListener: (_type, listener) => {
90
- listeners.delete(listener);
91
- },
92
- postMessage(message) {
93
- const bytes =
94
- message instanceof Uint8Array
95
- ? message
96
- : message instanceof ArrayBuffer
97
- ? new Uint8Array(message)
98
- : ArrayBuffer.isView(message)
99
- ? new Uint8Array(message.buffer, message.byteOffset, message.byteLength)
100
- : undefined;
101
- if (!bytes) {
102
- throw new TypeError(
103
- `webrun-streams-signaling: a byte pipe carries Uint8Array, ArrayBuffer or a view, got ${Object.prototype.toString.call(message)}`,
104
- );
105
- }
106
- if (life.signal.aborted) return; // `signal` says so
107
- channel.send(bytes.slice());
108
- },
109
- async close() {
110
- listeners.clear();
111
- closedHere = true;
112
- end(new Error("webrun-streams-signaling: closed locally"));
56
+ const control = newMessagePipe(
57
+ {
58
+ send: (bytes) => channel.send(bytes),
59
+ bufferedAmount: () => channel.bufferedAmount ?? 0,
60
+ ...(channel.whenDrained
61
+ ? {
62
+ isDrained: () => false,
63
+ whenDrained: () => channel.whenDrained?.() ?? Promise.resolve(),
64
+ }
65
+ : { isDrained: () => true }),
66
+ close: (local) => {
67
+ if (!local) return;
113
68
  try {
114
69
  channel.close();
115
70
  } catch {}
116
71
  },
117
- get bufferedAmount() {
118
- return channel.bufferedAmount ?? 0;
119
- },
120
- whenDrained() {
121
- if (life.signal.aborted || !channel.whenDrained) return Promise.resolve();
122
- const signal = life.signal;
123
- return new Promise<void>((resolve, reject) => {
124
- const done = (): void => {
125
- signal.removeEventListener("abort", done);
126
- resolve();
127
- };
128
- signal.addEventListener("abort", done);
129
- channel.whenDrained?.().then(done, (err: unknown) => {
130
- signal.removeEventListener("abort", done);
131
- reject(err);
132
- });
133
- });
134
- },
135
72
  },
136
- };
73
+ {
74
+ name: "webrun-streams-signaling",
75
+ maxMessageSize: options.maxMessageSize ?? DEFAULT_MAX_MESSAGE_SIZE,
76
+ maxFrameBytes: options.maxFrameBytes,
77
+ // The channel may queue what is sent, and reuse what it hands out.
78
+ copyOnSend: true,
79
+ copyOnDeliver: true,
80
+ },
81
+ );
82
+ const closedMessage = "webrun-streams-signaling: the channel closed";
83
+ const reading = (async () => {
84
+ for await (const bytes of channel.recv) {
85
+ // The channel closing ends `recv` after what it already holds; only a
86
+ // close on this side stops delivery at once.
87
+ if (control.ended) break;
88
+ control.deliver(bytes);
89
+ }
90
+ })();
91
+ reading.then(
92
+ () => control.end(new Error(closedMessage)),
93
+ // A `recv` that fails leaves the channel open: end as local, which closes it.
94
+ (err: unknown) =>
95
+ control.end(err instanceof Error ? err : new Error(String(err), { cause: err }), true),
96
+ );
97
+ // What `recv` still holds when the channel closes is delivered first; a
98
+ // channel whose `recv` never ends still ends the pipe, shortly after.
99
+ void channel.closed.then(() => {
100
+ if (control.ended) return;
101
+ const timer = setTimeout(() => control.end(new Error(closedMessage)), CLOSE_DRAIN_MS) as {
102
+ unref?: () => void;
103
+ };
104
+ timer.unref?.();
105
+ });
106
+ return control.pipe as ByteChannelMessageTarget;
137
107
  }