@statewalker/webrun-streams-ws 0.2.3 → 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
@@ -1,4 +1,3 @@
1
- import { emulateMux, normalizeToUint8Array } from "@statewalker/webrun-streams";
2
1
  //#region src/websocket-like.ts
3
2
  const WS_READY_STATE = {
4
3
  CONNECTING: 0,
@@ -7,129 +6,119 @@ const WS_READY_STATE = {
7
6
  CLOSED: 3
8
7
  };
9
8
  //#endregion
10
- //#region src/byte-channel.ts
9
+ //#region src/message-target.ts
10
+ /** How often `whenDrained` looks at `bufferedAmount`: a WebSocket has no drain event. */
11
+ const DRAIN_POLL_MS = 5;
11
12
  /**
12
- * Wrap an open `WebSocket` (or any `WebSocketLike` — Node `ws` works) into a
13
- * `ByteChannel` consumable by `emulateMux`. The socket MUST already be in the
14
- * `OPEN` state; the adapter does not perform handshakes.
13
+ * `whenDrained` resolves once `bufferedAmount` is at most this: the socket can
14
+ * take more. Waiting for zero would make a sender that waits before every
15
+ * frame (`overPipe`'s `frameSize`) pause a poll interval per frame.
16
+ */
17
+ const DRAIN_LOW_WATER = 262144;
18
+ const encoder = new TextEncoder();
19
+ /**
20
+ * One open WebSocket as a pipe of messages, for a multiplexer to run over:
21
+ *
22
+ * ```ts
23
+ * const { target, signal } = messageTargetOverWebSocket(ws);
24
+ * const { call } = await connect({
25
+ * mux: overPipe(target, { codec: msgpackCodec, side: "initiator", signal }),
26
+ * });
27
+ * ```
15
28
  *
16
- * Inbound binary frames are normalised to `Uint8Array`. Text frames are also
17
- * accepted (rare on this transport) and surfaced as their UTF-8 bytes.
29
+ * The socket must be `OPEN`. Binary messages arrive as `Uint8Array`, in order:
30
+ * a browser socket still on the default `binaryType` "blob" is switched to
31
+ * "arraybuffer", because reading a `Blob` is asynchronous and would let a later
32
+ * message overtake it. A text message arrives as its UTF-8 bytes. Messages
33
+ * reaching no listener are dropped, as on a `MessagePort`. The adapter imports
34
+ * nothing from this repository; the target is a `MessageTarget` by shape.
18
35
  */
19
- function byteChannelFromWebSocket(ws) {
20
- if (ws.readyState !== WS_READY_STATE.OPEN) throw new Error(`byteChannelFromWebSocket: WebSocket is in readyState ${ws.readyState}, expected OPEN (1)`);
21
- let closedResolve;
22
- const closed = new Promise((r) => {
23
- closedResolve = r;
24
- });
25
- let isClosed = false;
26
- const queue = [];
27
- let pending = null;
28
- const onMessage = (event) => {
29
- if (isClosed) return;
30
- const data = event.data;
31
- let normalised;
32
- if (data instanceof Uint8Array) normalised = data;
33
- else if (data instanceof ArrayBuffer) normalised = new Uint8Array(data);
34
- else if (ArrayBuffer.isView(data)) {
35
- const view = data;
36
- normalised = new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
37
- } else if (typeof Blob !== "undefined" && data instanceof Blob) {
38
- data.arrayBuffer().then((buf) => deliver(new Uint8Array(buf)));
39
- return;
40
- } else if (typeof data === "string") {
41
- const n = normalizeToUint8Array(data);
42
- if (n instanceof Uint8Array) normalised = n;
43
- else {
44
- n.then(deliver);
45
- return;
46
- }
47
- } else return;
48
- deliver(normalised);
36
+ function messageTargetOverWebSocket(ws) {
37
+ if (ws.readyState !== WS_READY_STATE.OPEN) throw new Error(`messageTargetOverWebSocket: WebSocket is in readyState ${ws.readyState}, expected OPEN (1)`);
38
+ if (ws.binaryType !== void 0 && ws.binaryType !== "arraybuffer" && ws.binaryType !== "nodebuffer") ws.binaryType = "arraybuffer";
39
+ const listeners = /* @__PURE__ */ new Set();
40
+ const life = new AbortController();
41
+ const deliver = (data) => {
42
+ const event = new MessageEvent("message", { data });
43
+ for (const listener of [...listeners]) try {
44
+ Promise.resolve(listener(event)).catch(() => void 0);
45
+ } catch {}
49
46
  };
50
- const deliver = (bytes) => {
51
- if (isClosed) return;
52
- if (pending) {
53
- const r = pending;
54
- pending = null;
55
- r({
56
- value: bytes,
57
- done: false
58
- });
59
- } else queue.push(bytes);
47
+ const onMessage = (event) => {
48
+ if (life.signal.aborted) return;
49
+ const bytes = toBytes(event.data);
50
+ if (bytes) deliver(bytes);
51
+ else if (typeof event.data === "string") deliver(encoder.encode(event.data));
52
+ else {
53
+ end(/* @__PURE__ */ new TypeError(`webrun-streams-ws: a message arrived as ${Object.prototype.toString.call(event.data)}; set binaryType to "arraybuffer" or "nodebuffer"`));
54
+ try {
55
+ ws.close();
56
+ } catch {}
57
+ }
60
58
  };
61
- const onClose = () => {
62
- if (isClosed) return;
63
- isClosed = true;
59
+ const end = (reason) => {
60
+ if (life.signal.aborted) return;
64
61
  ws.removeEventListener("message", onMessage);
65
62
  ws.removeEventListener("close", onClose);
66
- if (pending) {
67
- const r = pending;
68
- pending = null;
69
- r({
70
- value: void 0,
71
- done: true
72
- });
73
- }
74
- closedResolve();
63
+ life.abort(reason);
64
+ };
65
+ const onClose = (event) => {
66
+ const code = event?.code;
67
+ end(/* @__PURE__ */ new Error(`webrun-streams-ws: the WebSocket closed${code ? ` (code ${code})` : ""}`));
75
68
  };
76
69
  ws.addEventListener("message", onMessage);
77
70
  ws.addEventListener("close", onClose);
78
71
  return {
79
- send(bytes) {
80
- if (isClosed) return;
81
- if (ws.readyState !== WS_READY_STATE.OPEN) return;
82
- ws.send(bytes);
83
- },
84
- recv: { [Symbol.asyncIterator]() {
85
- return { next() {
86
- if (queue.length > 0) return Promise.resolve({
87
- value: queue.shift(),
88
- done: false
89
- });
90
- if (isClosed) return Promise.resolve({
91
- value: void 0,
92
- done: true
93
- });
72
+ signal: life.signal,
73
+ target: {
74
+ addEventListener: (_type, listener) => {
75
+ listeners.add(listener);
76
+ },
77
+ removeEventListener: (_type, listener) => {
78
+ listeners.delete(listener);
79
+ },
80
+ postMessage(message) {
81
+ const bytes = toBytes(message);
82
+ if (!bytes) throw new TypeError(`webrun-streams-ws: a byte pipe carries Uint8Array, ArrayBuffer or a view, got ${Object.prototype.toString.call(message)}`);
83
+ if (life.signal.aborted || ws.readyState !== WS_READY_STATE.OPEN) return;
84
+ ws.send(bytes);
85
+ },
86
+ async close() {
87
+ listeners.clear();
88
+ end(/* @__PURE__ */ new Error("webrun-streams-ws: closed locally"));
89
+ try {
90
+ ws.close();
91
+ } catch {}
92
+ },
93
+ get bufferedAmount() {
94
+ return ws.bufferedAmount ?? 0;
95
+ },
96
+ whenDrained() {
94
97
  return new Promise((resolve) => {
95
- pending = resolve;
98
+ const check = () => {
99
+ if (life.signal.aborted || (ws.bufferedAmount ?? 0) <= 262144) resolve();
100
+ else setTimeout(check, DRAIN_POLL_MS).unref?.();
101
+ };
102
+ check();
96
103
  });
97
- } };
98
- } },
99
- closed,
100
- close() {
101
- if (isClosed) return;
102
- try {
103
- ws.close();
104
- } catch {}
105
- onClose();
104
+ }
106
105
  }
107
106
  };
108
107
  }
109
- //#endregion
110
- //#region src/connect.ts
111
- /**
112
- * Open a WebSocket to `params.url`, wrap it as a `ByteChannel`, and run it
113
- * through `emulateMux`. Returns `{ call, close }` where `call` is the
114
- * caller-side `Duplex`.
115
- */
116
- const connect = async (params) => {
108
+ function toBytes(data) {
109
+ if (data instanceof Uint8Array) return data;
110
+ if (data instanceof ArrayBuffer) return new Uint8Array(data);
111
+ if (ArrayBuffer.isView(data)) return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
112
+ }
113
+ /** Opens a WebSocket and resolves once it is `OPEN`; rejects if it fails or closes first. */
114
+ async function openWebSocket(params) {
117
115
  const Ctor = params.WebSocketCtor ?? globalThis.WebSocket;
118
- if (!Ctor) throw new Error("webrun-streams-ws connect: no WebSocket constructor available. Pass `params.WebSocketCtor` (e.g. the `ws` package's WebSocket in Node).");
116
+ if (!Ctor) throw new Error("webrun-streams-ws: no WebSocket constructor available. Pass `WebSocketCtor` (e.g. the `ws` package's WebSocket in Node).");
119
117
  const ws = new Ctor(params.url, params.protocols);
120
118
  await waitForOpen(ws);
121
- const channel = byteChannelFromWebSocket(ws);
122
- const mux = emulateMux(channel, {
123
- ...params.mux,
124
- side: "initiator"
125
- });
126
- return {
127
- call: mux.call,
128
- async close() {
129
- await mux.close();
130
- }
131
- };
132
- };
119
+ return ws;
120
+ }
121
+ /** Resolves once `ws` is `OPEN`; rejects if it fails or closes first. */
133
122
  function waitForOpen(ws) {
134
123
  if (ws.readyState === WS_READY_STATE.OPEN) return Promise.resolve();
135
124
  return new Promise((resolve, reject) => {
@@ -156,32 +145,4 @@ function waitForOpen(ws) {
156
145
  });
157
146
  }
158
147
  //#endregion
159
- //#region src/serve.ts
160
- /**
161
- * Register a `Duplex` handler against an inbound-WebSocket source. The
162
- * `onConnection` callback is invoked once per accepted connection; the
163
- * adapter wraps each in `emulateMux` and binds the handler.
164
- *
165
- * Returns an idempotent teardown that unregisters the connection listener.
166
- * Open `emulateMux` instances continue running until their underlying
167
- * WebSocket closes.
168
- */
169
- async function serve(params, handler) {
170
- const off = params.onConnection((ws) => {
171
- const channel = byteChannelFromWebSocket(ws);
172
- const mux = emulateMux(channel, {
173
- ...params.mux,
174
- side: "responder"
175
- });
176
- mux.serve(handler);
177
- channel.closed.then(() => mux.close());
178
- });
179
- let torn = false;
180
- return async () => {
181
- if (torn) return;
182
- torn = true;
183
- off();
184
- };
185
- }
186
- //#endregion
187
- export { WS_READY_STATE, byteChannelFromWebSocket, connect, serve };
148
+ export { DRAIN_LOW_WATER, WS_READY_STATE, messageTargetOverWebSocket, openWebSocket };
@@ -0,0 +1,68 @@
1
+ import { type WebSocketLike } from "./websocket-like.js";
2
+ type Listener = (event: MessageEvent) => void | Promise<void>;
3
+ /** What `messageTargetOverWebSocket` gives: a pipe of bytes, and its life. */
4
+ export interface WebSocketMessageTarget {
5
+ /**
6
+ * A `MessageTarget` (as `@statewalker/webrun-rpc` defines it) whose messages
7
+ * are `Uint8Array`s, one WebSocket message each.
8
+ */
9
+ target: {
10
+ addEventListener(type: "message", listener: Listener): void;
11
+ removeEventListener(type: "message", listener: Listener): void;
12
+ /** Sends one binary message. Throws `TypeError` for anything but bytes. */
13
+ postMessage(message: unknown): void;
14
+ /** Closes the socket. */
15
+ close(): Promise<void>;
16
+ /** The socket's `bufferedAmount`: bytes sent and not yet written out. */
17
+ readonly bufferedAmount: number;
18
+ /** Resolves once `bufferedAmount` is at most {@link DRAIN_LOW_WATER}, or the socket has closed. */
19
+ whenDrained(): Promise<void>;
20
+ };
21
+ /**
22
+ * Aborts when the socket closes, with an `Error` saying how. Pass it as
23
+ * `multiplexPort`'s / `overPipe`'s `signal`, so a dead peer closes the
24
+ * multiplexer and every port on it at once instead of leaving them open.
25
+ */
26
+ signal: AbortSignal;
27
+ }
28
+ /**
29
+ * `whenDrained` resolves once `bufferedAmount` is at most this: the socket can
30
+ * take more. Waiting for zero would make a sender that waits before every
31
+ * frame (`overPipe`'s `frameSize`) pause a poll interval per frame.
32
+ */
33
+ export declare const DRAIN_LOW_WATER: number;
34
+ /**
35
+ * One open WebSocket as a pipe of messages, for a multiplexer to run over:
36
+ *
37
+ * ```ts
38
+ * const { target, signal } = messageTargetOverWebSocket(ws);
39
+ * const { call } = await connect({
40
+ * mux: overPipe(target, { codec: msgpackCodec, side: "initiator", signal }),
41
+ * });
42
+ * ```
43
+ *
44
+ * The socket must be `OPEN`. Binary messages arrive as `Uint8Array`, in order:
45
+ * a browser socket still on the default `binaryType` "blob" is switched to
46
+ * "arraybuffer", because reading a `Blob` is asynchronous and would let a later
47
+ * message overtake it. A text message arrives as its UTF-8 bytes. Messages
48
+ * reaching no listener are dropped, as on a `MessagePort`. The adapter imports
49
+ * nothing from this repository; the target is a `MessageTarget` by shape.
50
+ */
51
+ export declare function messageTargetOverWebSocket(ws: WebSocketLike): WebSocketMessageTarget;
52
+ export interface OpenWebSocketParams {
53
+ /** WebSocket URL (`ws://` or `wss://`). */
54
+ url: string;
55
+ /** Optional subprotocol(s) passed to the WebSocket constructor. */
56
+ protocols?: string | string[];
57
+ /**
58
+ * WebSocket constructor. Defaults to the global `WebSocket` when present;
59
+ * pass the `ws` package's `WebSocket` in Node versions without one.
60
+ */
61
+ WebSocketCtor?: new (url: string, protocols?: string | string[]) => WebSocketLike;
62
+ }
63
+ /** Opens a WebSocket and resolves once it is `OPEN`; rejects if it fails or closes first. */
64
+ export declare function openWebSocket(params: OpenWebSocketParams): Promise<WebSocketLike>;
65
+ /** Resolves once `ws` is `OPEN`; rejects if it fails or closes first. */
66
+ export declare function waitForOpen(ws: WebSocketLike): Promise<void>;
67
+ export {};
68
+ //# sourceMappingURL=message-target.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"message-target.d.ts","sourceRoot":"","sources":["../src/message-target.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAkB,MAAM,qBAAqB,CAAC;AAEzE,KAAK,QAAQ,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE9D,8EAA8E;AAC9E,MAAM,WAAW,sBAAsB;IACrC;;;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,2EAA2E;QAC3E,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;QACpC,yBAAyB;QACzB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;QACvB,yEAAyE;QACzE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;QAChC,mGAAmG;QACnG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;KAC9B,CAAC;IACF;;;;OAIG;IACH,MAAM,EAAE,WAAW,CAAC;CACrB;AAID;;;;GAIG;AACH,eAAO,MAAM,eAAe,QAAa,CAAC;AAI1C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,0BAA0B,CAAC,EAAE,EAAE,aAAa,GAAG,sBAAsB,CAsGpF;AAUD,MAAM,WAAW,mBAAmB;IAClC,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC9B;;;OAGG;IACH,aAAa,CAAC,EAAE,KACd,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,KAC1B,aAAa,CAAC;CACpB;AAED,6FAA6F;AAC7F,wBAAsB,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,aAAa,CAAC,CAUvF;AAED,yEAAyE;AACzE,wBAAgB,WAAW,CAAC,EAAE,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAwB5D"}
@@ -5,6 +5,10 @@
5
5
  */
6
6
  export interface WebSocketLike {
7
7
  readonly readyState: number;
8
+ /** Bytes queued by `send` and not yet written out. */
9
+ readonly bufferedAmount?: number;
10
+ /** How binary messages arrive: "blob" or "arraybuffer" in browsers, "nodebuffer" in `ws`. */
11
+ binaryType?: string;
8
12
  send(data: string | ArrayBuffer | Blob | Uint8Array): void;
9
13
  close(): void;
10
14
  addEventListener(type: "message", listener: (event: MessageEvent) => void): void;
@@ -1 +1 @@
1
- {"version":3,"file":"websocket-like.d.ts","sourceRoot":"","sources":["../src/websocket-like.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,GAAG,UAAU,GAAG,IAAI,CAAC;IAC3D,KAAK,IAAI,IAAI,CAAC;IACd,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,IAAI,CAAC;IACjF,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC3D,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC5D,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC5D,mBAAmB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,IAAI,CAAC;IACpF,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC9D,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC/D,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CAChE;AAED,eAAO,MAAM,cAAc;aACzB,UAAU,EAAE,CAAC;aACb,IAAI,EAAE,CAAC;aACP,OAAO,EAAE,CAAC;aACV,MAAM,EAAE,CAAC;CACD,CAAC"}
1
+ {"version":3,"file":"websocket-like.d.ts","sourceRoot":"","sources":["../src/websocket-like.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,sDAAsD;IACtD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,6FAA6F;IAC7F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,GAAG,UAAU,GAAG,IAAI,CAAC;IAC3D,KAAK,IAAI,IAAI,CAAC;IACd,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,IAAI,CAAC;IACjF,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC3D,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC5D,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC5D,mBAAmB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,IAAI,CAAC;IACpF,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC9D,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC/D,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CAChE;AAED,eAAO,MAAM,cAAc;aACzB,UAAU,EAAE,CAAC;aACb,IAAI,EAAE,CAAC;aACP,OAAO,EAAE,CAAC;aACV,MAAM,EAAE,CAAC;CACD,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@statewalker/webrun-streams-ws",
3
- "version": "0.2.3",
3
+ "version": "0.3.0",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "WebSocket-backed Connect/Serve adapter in the webrun-streams-* family",
@@ -29,9 +29,6 @@
29
29
  "dist",
30
30
  "src"
31
31
  ],
32
- "dependencies": {
33
- "@statewalker/webrun-streams": "^0.2.2"
34
- },
35
32
  "devDependencies": {
36
33
  "@biomejs/biome": "^2.5.15",
37
34
  "@types/node": "^26.6.4",
@@ -39,9 +36,12 @@
39
36
  "rimraf": "^6.1.3",
40
37
  "rolldown": "^1.2.12",
41
38
  "typescript": "^7.0.2",
42
- "vitest": "^5.0.3",
39
+ "vitest": "^5.0.5",
43
40
  "ws": "^8.22.0",
44
- "@statewalker/webrun-streams-conformance": "^0.3.2"
41
+ "@statewalker/webrun-streams-conformance": "^0.4.0",
42
+ "@statewalker/webrun-msgpack": "^0.10.0",
43
+ "@statewalker/webrun-streams": "^0.3.0",
44
+ "@statewalker/webrun-rpc": "^0.11.0"
45
45
  },
46
46
  "sideEffects": false,
47
47
  "publishConfig": {
package/src/index.ts CHANGED
@@ -1,4 +1,8 @@
1
- export { byteChannelFromWebSocket } from "./byte-channel.js";
2
- export { type ConnectWsParams, connect } from "./connect.js";
3
- export { type ServeWsParams, serve } from "./serve.js";
1
+ export {
2
+ DRAIN_LOW_WATER,
3
+ messageTargetOverWebSocket,
4
+ type OpenWebSocketParams,
5
+ openWebSocket,
6
+ type WebSocketMessageTarget,
7
+ } from "./message-target.js";
4
8
  export { type WebSocketLike, WS_READY_STATE } from "./websocket-like.js";
@@ -0,0 +1,224 @@
1
+ import { type WebSocketLike, WS_READY_STATE } from "./websocket-like.js";
2
+
3
+ type Listener = (event: MessageEvent) => void | Promise<void>;
4
+
5
+ /** What `messageTargetOverWebSocket` gives: a pipe of bytes, and its life. */
6
+ export interface WebSocketMessageTarget {
7
+ /**
8
+ * A `MessageTarget` (as `@statewalker/webrun-rpc` defines it) whose messages
9
+ * are `Uint8Array`s, one WebSocket message each.
10
+ */
11
+ target: {
12
+ addEventListener(type: "message", listener: Listener): void;
13
+ removeEventListener(type: "message", listener: Listener): void;
14
+ /** Sends one binary message. Throws `TypeError` for anything but bytes. */
15
+ postMessage(message: unknown): void;
16
+ /** Closes the socket. */
17
+ close(): Promise<void>;
18
+ /** The socket's `bufferedAmount`: bytes sent and not yet written out. */
19
+ readonly bufferedAmount: number;
20
+ /** Resolves once `bufferedAmount` is at most {@link DRAIN_LOW_WATER}, or the socket has closed. */
21
+ whenDrained(): Promise<void>;
22
+ };
23
+ /**
24
+ * Aborts when the socket closes, with an `Error` saying how. Pass it as
25
+ * `multiplexPort`'s / `overPipe`'s `signal`, so a dead peer closes the
26
+ * multiplexer and every port on it at once instead of leaving them open.
27
+ */
28
+ signal: AbortSignal;
29
+ }
30
+
31
+ /** How often `whenDrained` looks at `bufferedAmount`: a WebSocket has no drain event. */
32
+ const DRAIN_POLL_MS = 5;
33
+ /**
34
+ * `whenDrained` resolves once `bufferedAmount` is at most this: the socket can
35
+ * take more. Waiting for zero would make a sender that waits before every
36
+ * frame (`overPipe`'s `frameSize`) pause a poll interval per frame.
37
+ */
38
+ export const DRAIN_LOW_WATER = 256 * 1024;
39
+
40
+ const encoder = new TextEncoder();
41
+
42
+ /**
43
+ * One open WebSocket as a pipe of messages, for a multiplexer to run over:
44
+ *
45
+ * ```ts
46
+ * const { target, signal } = messageTargetOverWebSocket(ws);
47
+ * const { call } = await connect({
48
+ * mux: overPipe(target, { codec: msgpackCodec, side: "initiator", signal }),
49
+ * });
50
+ * ```
51
+ *
52
+ * The socket must be `OPEN`. Binary messages arrive as `Uint8Array`, in order:
53
+ * a browser socket still on the default `binaryType` "blob" is switched to
54
+ * "arraybuffer", because reading a `Blob` is asynchronous and would let a later
55
+ * message overtake it. A text message arrives as its UTF-8 bytes. Messages
56
+ * reaching no listener are dropped, as on a `MessagePort`. The adapter imports
57
+ * nothing from this repository; the target is a `MessageTarget` by shape.
58
+ */
59
+ export function messageTargetOverWebSocket(ws: WebSocketLike): WebSocketMessageTarget {
60
+ if (ws.readyState !== WS_READY_STATE.OPEN) {
61
+ throw new Error(
62
+ `messageTargetOverWebSocket: WebSocket is in readyState ${ws.readyState}, expected OPEN (1)`,
63
+ );
64
+ }
65
+ // "arraybuffer" (browsers) and "nodebuffer" (`ws`) arrive as bytes at once;
66
+ // anything else — "blob" (read asynchronously, so a later message could
67
+ // overtake it), `ws`'s "fragments" (an array of Buffers) — is switched.
68
+ if (
69
+ ws.binaryType !== undefined &&
70
+ ws.binaryType !== "arraybuffer" &&
71
+ ws.binaryType !== "nodebuffer"
72
+ )
73
+ ws.binaryType = "arraybuffer";
74
+ const listeners = new Set<Listener>();
75
+ const life = new AbortController();
76
+
77
+ const deliver = (data: Uint8Array): void => {
78
+ const event = new MessageEvent("message", { data });
79
+ for (const listener of [...listeners]) {
80
+ try {
81
+ // One listener's fault, thrown or rejected, must not stop delivery.
82
+ Promise.resolve(listener(event)).catch(() => undefined);
83
+ } catch {}
84
+ }
85
+ };
86
+ const onMessage = (event: MessageEvent): void => {
87
+ if (life.signal.aborted) return;
88
+ const bytes = toBytes(event.data);
89
+ if (bytes) deliver(bytes);
90
+ else if (typeof event.data === "string") deliver(encoder.encode(event.data));
91
+ else {
92
+ // Dropping it would lose a multiplexer envelope and hang its call: fail loudly.
93
+ end(
94
+ new TypeError(
95
+ `webrun-streams-ws: a message arrived as ${Object.prototype.toString.call(event.data)}; set binaryType to "arraybuffer" or "nodebuffer"`,
96
+ ),
97
+ );
98
+ try {
99
+ ws.close();
100
+ } catch {}
101
+ }
102
+ };
103
+ const end = (reason: Error): void => {
104
+ if (life.signal.aborted) return;
105
+ ws.removeEventListener("message", onMessage);
106
+ ws.removeEventListener("close", onClose);
107
+ life.abort(reason);
108
+ };
109
+ const onClose = (event?: unknown): void => {
110
+ const code = (event as { code?: number } | undefined)?.code;
111
+ end(new Error(`webrun-streams-ws: the WebSocket closed${code ? ` (code ${code})` : ""}`));
112
+ };
113
+ ws.addEventListener("message", onMessage);
114
+ // A failing socket fires `error` and then always `close`: `close` alone ends it.
115
+ ws.addEventListener("close", onClose);
116
+
117
+ return {
118
+ signal: life.signal,
119
+ target: {
120
+ addEventListener: (_type, listener) => {
121
+ listeners.add(listener);
122
+ },
123
+ removeEventListener: (_type, listener) => {
124
+ listeners.delete(listener);
125
+ },
126
+ postMessage(message) {
127
+ const bytes = toBytes(message);
128
+ if (!bytes) {
129
+ throw new TypeError(
130
+ `webrun-streams-ws: a byte pipe carries Uint8Array, ArrayBuffer or a view, got ${Object.prototype.toString.call(message)}`,
131
+ );
132
+ }
133
+ if (life.signal.aborted || ws.readyState !== WS_READY_STATE.OPEN) return; // `signal` says so
134
+ ws.send(bytes);
135
+ },
136
+ async close() {
137
+ listeners.clear();
138
+ end(new Error("webrun-streams-ws: closed locally"));
139
+ try {
140
+ ws.close();
141
+ } catch {}
142
+ },
143
+ get bufferedAmount() {
144
+ return ws.bufferedAmount ?? 0;
145
+ },
146
+ whenDrained() {
147
+ return new Promise<void>((resolve) => {
148
+ const check = (): void => {
149
+ if (life.signal.aborted || (ws.bufferedAmount ?? 0) <= DRAIN_LOW_WATER) resolve();
150
+ else {
151
+ // A peer that stops reading but never closes must not keep Node alive.
152
+ const timer = setTimeout(check, DRAIN_POLL_MS) as { unref?: () => void };
153
+ timer.unref?.();
154
+ }
155
+ };
156
+ check();
157
+ });
158
+ },
159
+ },
160
+ };
161
+ }
162
+
163
+ function toBytes(data: unknown): Uint8Array | undefined {
164
+ if (data instanceof Uint8Array) return data;
165
+ if (data instanceof ArrayBuffer) return new Uint8Array(data);
166
+ if (ArrayBuffer.isView(data))
167
+ return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
168
+ return undefined;
169
+ }
170
+
171
+ export interface OpenWebSocketParams {
172
+ /** WebSocket URL (`ws://` or `wss://`). */
173
+ url: string;
174
+ /** Optional subprotocol(s) passed to the WebSocket constructor. */
175
+ protocols?: string | string[];
176
+ /**
177
+ * WebSocket constructor. Defaults to the global `WebSocket` when present;
178
+ * pass the `ws` package's `WebSocket` in Node versions without one.
179
+ */
180
+ WebSocketCtor?: new (
181
+ url: string,
182
+ protocols?: string | string[],
183
+ ) => WebSocketLike;
184
+ }
185
+
186
+ /** Opens a WebSocket and resolves once it is `OPEN`; rejects if it fails or closes first. */
187
+ export async function openWebSocket(params: OpenWebSocketParams): Promise<WebSocketLike> {
188
+ const Ctor = params.WebSocketCtor ?? (globalThis as { WebSocket?: typeof WebSocket }).WebSocket;
189
+ if (!Ctor) {
190
+ throw new Error(
191
+ "webrun-streams-ws: no WebSocket constructor available. Pass `WebSocketCtor` (e.g. the `ws` package's WebSocket in Node).",
192
+ );
193
+ }
194
+ const ws = new Ctor(params.url, params.protocols) as WebSocketLike;
195
+ await waitForOpen(ws);
196
+ return ws;
197
+ }
198
+
199
+ /** Resolves once `ws` is `OPEN`; rejects if it fails or closes first. */
200
+ export function waitForOpen(ws: WebSocketLike): Promise<void> {
201
+ if (ws.readyState === WS_READY_STATE.OPEN) return Promise.resolve();
202
+ return new Promise<void>((resolve, reject) => {
203
+ const cleanup = (): void => {
204
+ ws.removeEventListener("open", onOpen);
205
+ ws.removeEventListener("error", onError);
206
+ ws.removeEventListener("close", onCloseEarly);
207
+ };
208
+ const onOpen = (): void => {
209
+ cleanup();
210
+ resolve();
211
+ };
212
+ const onError = (): void => {
213
+ cleanup();
214
+ reject(new Error("WebSocket error before open"));
215
+ };
216
+ const onCloseEarly = (): void => {
217
+ cleanup();
218
+ reject(new Error("WebSocket closed before it opened"));
219
+ };
220
+ ws.addEventListener("open", onOpen);
221
+ ws.addEventListener("error", onError);
222
+ ws.addEventListener("close", onCloseEarly);
223
+ });
224
+ }
@@ -5,6 +5,10 @@
5
5
  */
6
6
  export interface WebSocketLike {
7
7
  readonly readyState: number;
8
+ /** Bytes queued by `send` and not yet written out. */
9
+ readonly bufferedAmount?: number;
10
+ /** How binary messages arrive: "blob" or "arraybuffer" in browsers, "nodebuffer" in `ws`. */
11
+ binaryType?: string;
8
12
  send(data: string | ArrayBuffer | Blob | Uint8Array): void;
9
13
  close(): void;
10
14
  addEventListener(type: "message", listener: (event: MessageEvent) => void): void;
@@ -1,12 +0,0 @@
1
- import { type ByteChannel } from "@statewalker/webrun-streams";
2
- import { type WebSocketLike } from "./websocket-like.js";
3
- /**
4
- * Wrap an open `WebSocket` (or any `WebSocketLike` — Node `ws` works) into a
5
- * `ByteChannel` consumable by `emulateMux`. The socket MUST already be in the
6
- * `OPEN` state; the adapter does not perform handshakes.
7
- *
8
- * Inbound binary frames are normalised to `Uint8Array`. Text frames are also
9
- * accepted (rare on this transport) and surfaced as their UTF-8 bytes.
10
- */
11
- export declare function byteChannelFromWebSocket(ws: WebSocketLike): ByteChannel;
12
- //# sourceMappingURL=byte-channel.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"byte-channel.d.ts","sourceRoot":"","sources":["../src/byte-channel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAyB,MAAM,6BAA6B,CAAC;AACtF,OAAO,EAAE,KAAK,aAAa,EAAkB,MAAM,qBAAqB,CAAC;AAEzE;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,aAAa,GAAG,WAAW,CA8GvE"}