@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/README.md +152 -120
- package/dist/index.d.ts +1 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +95 -134
- package/dist/message-target.d.ts +68 -0
- package/dist/message-target.d.ts.map +1 -0
- package/dist/websocket-like.d.ts +4 -0
- package/dist/websocket-like.d.ts.map +1 -1
- package/package.json +6 -6
- package/src/index.ts +7 -3
- package/src/message-target.ts +224 -0
- package/src/websocket-like.ts +4 -0
- package/dist/byte-channel.d.ts +0 -12
- package/dist/byte-channel.d.ts.map +0 -1
- package/dist/connect.d.ts +0 -28
- package/dist/connect.d.ts.map +0 -1
- package/dist/serve.d.ts +0 -29
- package/dist/serve.d.ts.map +0 -1
- package/src/byte-channel.ts +0 -122
- package/src/connect.ts +0 -76
- package/src/serve.ts +0 -44
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/
|
|
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
|
-
*
|
|
13
|
-
*
|
|
14
|
-
* `
|
|
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
|
-
*
|
|
17
|
-
*
|
|
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
|
|
20
|
-
if (ws.readyState !== WS_READY_STATE.OPEN) throw new Error(`
|
|
21
|
-
|
|
22
|
-
const
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
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
|
|
51
|
-
if (
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
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
|
|
62
|
-
if (
|
|
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
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
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
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
});
|
|
90
|
-
if (
|
|
91
|
-
|
|
92
|
-
|
|
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
|
-
|
|
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
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
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
|
|
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
|
-
|
|
122
|
-
|
|
123
|
-
|
|
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
|
-
|
|
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"}
|
package/dist/websocket-like.d.ts
CHANGED
|
@@ -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.
|
|
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.
|
|
39
|
+
"vitest": "^5.0.5",
|
|
43
40
|
"ws": "^8.22.0",
|
|
44
|
-
"@statewalker/webrun-streams-conformance": "^0.
|
|
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 {
|
|
2
|
-
|
|
3
|
-
|
|
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
|
+
}
|
package/src/websocket-like.ts
CHANGED
|
@@ -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;
|
package/dist/byte-channel.d.ts
DELETED
|
@@ -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"}
|