1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
// `WebSocketStream` — the stream-shaped WebSocket API (WHATWG WebSockets
// Standard, "WebSocketStream"; shipped in Chromium since 124).
//
// WHY THIS EXISTS HERE, ON TOP OF THE NATIVE `WebSocket`
//
// It is not a nicety. The concrete consumer this whole module was written for
// — `@argon-chat/ion.webcore`, the RPC layer the Argon meet app's entire
// control plane runs on — opens EVERY streaming call with
//
// if (typeof WebSocketStream > "u")
// throw new Error("WebSocketStream is not supported in this browser");
// const s = new WebSocketStream(url, { signal, protocols: [...] });
// const { readable, writable } = await s.opened;
//
// so a runtime with `WebSocket` and without `WebSocketStream` fails that check
// and no RPC is possible at all. Shipping the classic API alone would have
// been a milestone that looks complete and unblocks nothing.
//
// It is JS rather than Rust because it is genuinely a *composition*: every
// byte still goes through the native `WebSocket` above, and the queueing,
// backpressure and cancellation are the native `ReadableStream` /
// `WritableStream` cores. There is no I/O here to move off-thread.
//
// TWO HONEST NARROWINGS, both about backpressure:
//
// * A browser stops READING from the socket when the readable stream's queue
// is full. Our reader thread always drains the socket, so a consumer that
// stops reading grows a queue in memory instead of pushing back on TCP.
// * A write's promise resolves as soon as the bytes are queued, unless
// `bufferedAmount` is already over HIGH_WATER — then it waits for the
// socket to drain below it. That is real backpressure driven by the real
// `bufferedAmount`, but it is coarser than a browser's per-chunk accounting.
(function (g) {
"use strict";
if (typeof g.WebSocket !== "function" || typeof g.ReadableStream !== "function") return;
if (typeof g.WebSocketStream === "function") return;
// Bytes allowed to sit in the socket's send queue before `writer.write()`
// stops resolving immediately. Small RPC frames never touch this path.
var HIGH_WATER = 1 << 20;
var DRAIN_POLL_MS = 4;
// The spec's "a new `name` DOMException" — the real class, installed by redjs
// before this script runs, captured so a page that reassigns the global
// cannot change what this throws.
var DOMEx = g.DOMException;
function named(name, message) {
return new DOMEx(message, name);
}
// Marks a promise handled so an unobserved `closed` rejection is not noise;
// a `.catch()` the caller attaches later still receives it.
function quiet(p) {
p.catch(function () {});
return p;
}
function drained(ws) {
if (ws.bufferedAmount <= HIGH_WATER) return undefined;
return new Promise(function (resolve) {
var tick = function () {
if (ws.readyState !== WebSocket.OPEN || ws.bufferedAmount <= HIGH_WATER) resolve();
else setTimeout(tick, DRAIN_POLL_MS);
};
setTimeout(tick, DRAIN_POLL_MS);
});
}
class WebSocketStream {
constructor(url, options) {
options = options || {};
var protocols = options.protocols === undefined ? [] : options.protocols;
var signal = options.signal;
// Constructing the socket is what validates the URL and the protocol
// list, so a bad argument throws the same named error it would from
// `new WebSocket(...)` — synchronously, as in Chromium.
var ws = new WebSocket(url, protocols);
// The readable yields ArrayBuffers for binary frames; that is what
// Chromium delivers and what consumers brand-check against.
ws.binaryType = "arraybuffer";
this._ws = ws;
this._url = ws.url;
var openedResolve, openedReject, closedResolve, closedReject;
var settledOpen = false;
this.opened = new Promise(function (res, rej) {
openedResolve = res;
openedReject = rej;
});
this.closed = quiet(
new Promise(function (res, rej) {
closedResolve = res;
closedReject = rej;
})
);
var controller = null;
var readable = new ReadableStream({
start: function (c) {
controller = c;
},
// Cancelling the read side closes the socket, per the spec's
// "cancel the WebSocketStream".
cancel: function () {
try {
ws.close();
} catch (e) {}
},
});
var writable = new WritableStream({
write: function (chunk) {
if (ws.readyState !== WebSocket.OPEN) {
throw named("InvalidStateError", "WebSocketStream: the socket is not open");
}
ws.send(chunk);
return drained(ws);
},
close: function () {
try {
ws.close();
} catch (e) {}
},
abort: function () {
try {
ws.close();
} catch (e) {}
},
});
ws.onopen = function () {
settledOpen = true;
openedResolve({
readable: readable,
writable: writable,
protocol: ws.protocol,
extensions: ws.extensions,
});
};
ws.onmessage = function (e) {
if (controller) controller.enqueue(e.data);
};
ws.onclose = function (e) {
var info = { closeCode: e.code, reason: e.reason };
if (!settledOpen) {
settledOpen = true;
// The connection never came up: `opened` is the promise that has to
// say so, and it must not resolve with half a stream pair.
openedReject(named("NetworkError", "WebSocketStream: the connection could not be established"));
}
if (e.wasClean) {
if (controller) {
try {
controller.close();
} catch (err) {}
}
closedResolve(info);
} else {
var err = named("NetworkError", "WebSocketStream: the connection closed abnormally (" + e.code + ")");
if (controller) {
try {
controller.error(err);
} catch (e2) {}
}
closedReject(err);
}
};
// `error` needs no handler of its own: it is always followed by `close`,
// which is where both promises settle. Registering one only keeps the
// event from looking unhandled.
ws.onerror = function () {};
if (signal) {
if (signal.aborted) {
try {
ws.close();
} catch (e) {}
} else {
signal.addEventListener(
"abort",
function () {
try {
ws.close();
} catch (e) {}
},
{ once: true }
);
}
}
}
get url() {
return this._url;
}
close(closeInfo) {
closeInfo = closeInfo || {};
var reason = closeInfo.reason === undefined ? "" : closeInfo.reason;
try {
if (closeInfo.closeCode === undefined) this._ws.close(undefined, reason);
else this._ws.close(closeInfo.closeCode, reason);
} catch (e) {
// A double close, or a close after the socket is gone, is a no-op —
// and the consumer above calls `close()` from several catch paths.
if (e && (e.name === "InvalidAccessError" || e.name === "SyntaxError")) throw e;
}
}
}
Object.defineProperty(WebSocketStream.prototype, Symbol.toStringTag, {
value: "WebSocketStream",
configurable: true,
});
Object.defineProperty(g, "WebSocketStream", {
value: WebSocketStream,
writable: true,
enumerable: false,
configurable: true,
});
})(globalThis);