@dokebi/websocket 0.2.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/dist/gateway.js CHANGED
@@ -1,11 +1,66 @@
1
1
  import { isUtf8 } from 'node:buffer';
2
2
  import { randomUUID } from 'node:crypto';
3
3
  import { setTimeout as delay, setImmediate as immediate } from 'node:timers/promises';
4
+ import { diagnostics } from '@dokebi/core/libraries';
4
5
  import fastifyWebsocket from '@fastify/websocket';
5
6
  import { WebSocket } from 'ws';
6
- import { errorCode, errorText, LogThrottle } from './log.js';
7
+ import { WebsocketError } from './errors.js';
8
+ import { PLAIN_PROTOCOL, SEAL_PROTOCOL, } from './types.js';
7
9
  const TEXT = Object.freeze({ binary: false });
8
10
  const BINARY = Object.freeze({ binary: true });
11
+ /** Close codes of sealed connections (D-0059 §4); the client does not reconnect after them. */
12
+ const BAD_FRAME = 4400;
13
+ const SEAL_REQUIRED = 4415;
14
+ /** Why a sealed frame was refused, as a bounded log group (codec reasons look like `replay`). */
15
+ const REASON = /^[a-z][a-z-]{0,31}$/;
16
+ /** Message types of `api.send`, as defineSocket handler types. */
17
+ const TYPE = /^[A-Za-z][A-Za-z0-9._:-]{0,63}$/;
18
+ /** Hub calls a `tenantPrefix` broadcast or kick runs at once. */
19
+ const FAN_OUT = 16;
20
+ const encoder = new TextEncoder();
21
+ const { describeError, errorCode, Repeats } = diagnostics;
22
+ /** A host without its port, lower case; IPv6 literals keep their brackets (like the browser). */
23
+ function withoutPort(host) {
24
+ const raw = host.toLowerCase();
25
+ if (raw.startsWith('['))
26
+ return raw.slice(0, raw.indexOf(']') + 1);
27
+ const colon = raw.lastIndexOf(':');
28
+ return colon === -1 ? raw : raw.slice(0, colon);
29
+ }
30
+ /** A filter string: 1 to 256 bytes (the hub's identifier limit). */
31
+ function filterText(value) {
32
+ return typeof value === 'string' && value.length > 0 && Buffer.byteLength(value) <= 256;
33
+ }
34
+ /** Checks a server-side filter (D-0061): exactly one of tenant and tenantPrefix. */
35
+ function checkFilter(filter) {
36
+ const value = filter;
37
+ if (!value ||
38
+ typeof value !== 'object' ||
39
+ (value.tenant === undefined) === (value.tenantPrefix === undefined) ||
40
+ (value.tenant !== undefined && !filterText(value.tenant)) ||
41
+ (value.tenantPrefix !== undefined && !filterText(value.tenantPrefix)) ||
42
+ (value.room !== undefined && !filterText(value.room)) ||
43
+ (value.member !== undefined && !filterText(value.member)))
44
+ throw new WebsocketError('INVALID_FILTER', 'A websocket filter is { tenant } or { tenantPrefix }, with room? and member?, strings of 1 to 256 bytes');
45
+ return value;
46
+ }
47
+ function connectionInfo(record) {
48
+ return Object.freeze({
49
+ tenant: record.tenant,
50
+ member: record.member,
51
+ connection: record.connection,
52
+ ownerEpoch: record.ownerEpoch,
53
+ ...(record.clientId === undefined ? {} : { clientId: record.clientId }),
54
+ rooms: record.rooms,
55
+ metadata: record.metadata,
56
+ });
57
+ }
58
+ function sealOf(route) {
59
+ const value = route.seal;
60
+ if (value !== undefined && typeof value !== 'boolean' && typeof value !== 'function')
61
+ throw new WebsocketError('INVALID_ROUTE', 'Invalid websocket route');
62
+ return value;
63
+ }
9
64
  /** Allow-list entries must be exact http(s) origins such as `https://app.example.com`. */
10
65
  function parseOrigins(value) {
11
66
  if (value === undefined)
@@ -13,7 +68,7 @@ function parseOrigins(value) {
13
68
  if (value === '*')
14
69
  return '*';
15
70
  if (!Array.isArray(value))
16
- throw new Error('Invalid websocket route');
71
+ throw new WebsocketError('INVALID_ROUTE', 'Invalid websocket route');
17
72
  const result = new Set();
18
73
  for (const item of value) {
19
74
  let url;
@@ -21,10 +76,10 @@ function parseOrigins(value) {
21
76
  url = typeof item === 'string' ? new URL(item) : undefined;
22
77
  }
23
78
  catch (error) {
24
- throw new Error('Invalid websocket route', { cause: error });
79
+ throw new WebsocketError('INVALID_ROUTE', 'Invalid websocket route', { cause: error });
25
80
  }
26
81
  if (!url || (url.protocol !== 'http:' && url.protocol !== 'https:') || url.origin !== item)
27
- throw new Error('Invalid websocket route');
82
+ throw new WebsocketError('INVALID_ROUTE', 'Invalid websocket route');
28
83
  result.add(url.origin);
29
84
  }
30
85
  return result;
@@ -71,6 +126,7 @@ export class Gateway {
71
126
  web;
72
127
  hub;
73
128
  settings;
129
+ codecs;
74
130
  api;
75
131
  #routes = [];
76
132
  #clients = new Map();
@@ -81,33 +137,72 @@ export class Gateway {
81
137
  #sends = 0;
82
138
  #sendsIdle;
83
139
  #identities = new WeakMap();
140
+ /** `api.onPresence` listeners (D-0061). */
141
+ #listeners = new Set();
142
+ /** Upgrades decided as sealed in preValidation, read by handleProtocols and the wsHandler. */
143
+ #sealed = new WeakSet();
84
144
  #frozen = false;
85
145
  #closing = false;
86
146
  #loop;
87
147
  #timer;
88
148
  /** Failures on per-message and per-socket paths, logged once per interval with a count. */
89
149
  #throttle;
90
- constructor(context, web, hub, settings) {
150
+ constructor(context, web, hub, settings, codecs = undefined) {
91
151
  this.context = context;
92
152
  this.web = web;
93
153
  this.hub = hub;
94
154
  this.settings = settings;
155
+ this.codecs = codecs;
95
156
  const self = this;
96
- this.#throttle = new LogThrottle(context.logger);
157
+ this.#throttle = new Repeats({ logger: context.logger });
97
158
  this.api = Object.freeze({
98
159
  get connections() {
99
160
  return self.#clients.size;
100
161
  },
162
+ sealing: codecs !== undefined,
101
163
  route: (route) => {
102
164
  if (this.#frozen || context.app.state !== 'starting')
103
- throw new Error('Register websocket routes during setup');
165
+ throw new WebsocketError('FROZEN', 'Register websocket routes during setup');
104
166
  if (!route.path.startsWith('/') ||
105
167
  typeof route.authenticate !== 'function' ||
106
168
  typeof route.message !== 'function')
107
- throw new Error('Invalid websocket route');
169
+ throw new WebsocketError('INVALID_ROUTE', 'Invalid websocket route');
108
170
  const origins = parseOrigins(route.origins);
171
+ const seal = sealOf(route);
172
+ // Fail closed: a route that may seal must not quietly run in plain text.
173
+ if (seal && !codecs)
174
+ throw new WebsocketError('SEAL_PROVIDER_MISSING', `WebSocket route ${route.path} is sealed; register the dokebi-seal plugin`);
109
175
  this.#routes.push({ route: { ...route }, origins });
110
176
  },
177
+ list: (filter) => this.#list(filter),
178
+ broadcast: (filter, data) => this.#broadcast(filter, data),
179
+ send: (filter, type, data) => {
180
+ if (typeof type !== 'string' || !TYPE.test(type))
181
+ return Promise.reject(new WebsocketError('INVALID_TYPE', 'Message types match ' + TYPE.source));
182
+ let text;
183
+ try {
184
+ text = JSON.stringify(data === undefined ? { type } : { type, data });
185
+ }
186
+ catch (error) {
187
+ return Promise.reject(new WebsocketError('INVALID_DATA', 'Message data is not JSON', { cause: error }));
188
+ }
189
+ return this.#broadcast(filter, text);
190
+ },
191
+ kick: (filter, code, reason) => this.#kick(filter, code, reason),
192
+ onPresence: (listener) => {
193
+ if (typeof listener !== 'function')
194
+ throw new WebsocketError('INVALID_ARGUMENT', 'Invalid presence listener');
195
+ this.#listeners.add(listener);
196
+ context.logger.log('debug', 'WebSocket presence listener added', {
197
+ listeners: this.#listeners.size,
198
+ });
199
+ return () => {
200
+ if (this.#listeners.delete(listener))
201
+ context.logger.log('debug', 'WebSocket presence listener removed', {
202
+ listeners: this.#listeners.size,
203
+ });
204
+ };
205
+ },
111
206
  });
112
207
  // Registered without encapsulation (skip-override) so @fastify/websocket's hooks run for
113
208
  // every upgrade, including ones that match no websocket route: its onResponse hook then
@@ -115,10 +210,22 @@ export class Gateway {
115
210
  const gateway = async (scope) => {
116
211
  this.#frozen = true;
117
212
  await scope.register(fastifyWebsocket, {
118
- options: { maxPayload: settings.maxPayload, perMessageDeflate: false },
213
+ options: {
214
+ maxPayload: settings.maxPayloadBytes,
215
+ perMessageDeflate: false,
216
+ // D-0059 §4: a client with a seal bridge offers `dokebi.seal` and `dokebi.plain`.
217
+ // A sealed upgrade selects `dokebi.seal` only (never plain; not offered: 4415 after the
218
+ // upgrade). A plain upgrade selects `dokebi.plain` when offered (browsers fail a handshake
219
+ // that selects none of the offered protocols), otherwise nothing, as for old clients.
220
+ handleProtocols: (protocols, request) => {
221
+ if (this.#sealed.has(request))
222
+ return protocols.has(SEAL_PROTOCOL) ? SEAL_PROTOCOL : false;
223
+ return protocols.has(PLAIN_PROTOCOL) ? PLAIN_PROTOCOL : false;
224
+ },
225
+ },
119
226
  // A wsHandler that threw: the client gets 1011, the cause goes to the log (D-0047).
120
227
  errorHandler: (error, socket) => {
121
- this.#throttle.report('error', 'WebSocket handler failed', 'SOCKET_FAILURE', error);
228
+ this.#throttle.log('error', 'WebSocket handler failed', 'SOCKET_FAILURE', error);
122
229
  socket.close(1011, 'Socket failure');
123
230
  },
124
231
  });
@@ -150,6 +257,20 @@ export class Gateway {
150
257
  if (!identity)
151
258
  return reply.code(401).send({ error: 'UNAUTHORIZED' });
152
259
  this.#identities.set(request, identity);
260
+ const seal = route.seal;
261
+ if (seal === undefined || seal === false)
262
+ return;
263
+ const sealed = seal === true || seal(request) === true;
264
+ if (sealed)
265
+ this.#sealed.add(request.raw);
266
+ if (this.context.logger.isEnabled('debug'))
267
+ this.context.logger.log('debug', 'WebSocket seal decision', {
268
+ path: route.path,
269
+ sealed,
270
+ offered: String(request.headers['sec-websocket-protocol'] ?? '')
271
+ .split(',')
272
+ .some((value) => value.trim() === SEAL_PROTOCOL),
273
+ });
153
274
  },
154
275
  handler: (_request, reply) => reply.code(426).send({ error: 'WEBSOCKET_REQUIRED' }),
155
276
  wsHandler: (socket, request) => this.#attach(socket, request, route),
@@ -164,13 +285,32 @@ export class Gateway {
164
285
  void task.then(() => this.#tasks.delete(task), () => this.#tasks.delete(task));
165
286
  return task;
166
287
  }
167
- #send(socket, data) {
168
- const bytes = typeof data === 'string' ? Buffer.byteLength(data) : data.byteLength;
288
+ #send(value, data) {
289
+ const socket = value.socket;
169
290
  if (socket.readyState !== WebSocket.OPEN)
170
- return Promise.reject(Object.assign(new Error('Socket closed'), { code: 'SOCKET_CLOSED' }));
291
+ return Promise.reject(new WebsocketError('SOCKET_CLOSED', 'Socket closed'));
292
+ if (value.codec) {
293
+ // Sealed connections carry text only: UTF-8 bytes are sent as text, other bytes refused.
294
+ let text;
295
+ if (typeof data === 'string')
296
+ text = data;
297
+ else {
298
+ const buffer = Buffer.from(data.buffer, data.byteOffset, data.byteLength);
299
+ if (!isUtf8(buffer))
300
+ return Promise.reject(new WebsocketError('SEAL_BINARY_UNSUPPORTED', 'Binary data cannot be sent on a sealed socket'));
301
+ text = buffer.toString();
302
+ }
303
+ try {
304
+ data = value.codec.encode(text);
305
+ }
306
+ catch (error) {
307
+ return Promise.reject(new WebsocketError('SEAL_ENCODE_FAILED', 'Sealing a frame failed', { cause: error }));
308
+ }
309
+ }
310
+ const bytes = typeof data === 'string' ? Buffer.byteLength(data) : data.byteLength;
171
311
  if (socket.bufferedAmount + bytes > this.settings.maxBufferedBytes) {
172
312
  this.#slow(socket);
173
- return Promise.reject(Object.assign(new Error('Socket backpressure'), { code: 'SLOW_CONSUMER' }));
313
+ return Promise.reject(new WebsocketError('SLOW_CONSUMER', 'Socket backpressure'));
174
314
  }
175
315
  return this.#watch(new Promise((resolve, reject) => socket.send(data, (error) => (error ? reject(error) : resolve()))));
176
316
  }
@@ -188,14 +328,15 @@ export class Gateway {
188
328
  #deliver(socket, frame, kind) {
189
329
  if (socket.readyState !== WebSocket.OPEN)
190
330
  return;
191
- if (socket.bufferedAmount + frame.byteLength > this.settings.maxBufferedBytes) {
331
+ const bytes = typeof frame === 'string' ? Buffer.byteLength(frame) : frame.byteLength;
332
+ if (socket.bufferedAmount + bytes > this.settings.maxBufferedBytes) {
192
333
  this.#slow(socket);
193
334
  return;
194
335
  }
195
336
  this.#sends++;
196
337
  socket.send(frame, kind, (error) => {
197
338
  if (error) {
198
- this.#throttle.report('error', 'WebSocket broadcast write failed; socket terminated', 'BROADCAST_WRITE_FAILED', error);
339
+ this.#throttle.log('error', 'WebSocket broadcast write failed; socket terminated', 'BROADCAST_WRITE_FAILED', error);
199
340
  socket.terminate();
200
341
  }
201
342
  if (--this.#sends === 0 && this.#sendsIdle) {
@@ -233,14 +374,54 @@ export class Gateway {
233
374
  return;
234
375
  }
235
376
  }
377
+ const sealed = this.#sealed.has(request.raw);
378
+ // A sealed host never talks plain text: a client that cannot seal is told so (no reconnect).
379
+ if (sealed && socket.protocol !== SEAL_PROTOCOL) {
380
+ this.context.logger.log('debug', 'WebSocket seal required; closed', {
381
+ path: route.path,
382
+ code: 'SEAL_REQUIRED',
383
+ });
384
+ socket.close(SEAL_REQUIRED, 'Seal required');
385
+ return;
386
+ }
236
387
  const identity = this.#identities.get(request);
237
388
  if (!identity || this.#closing || this.#clients.size >= this.settings.maxConnections) {
238
389
  socket.close(1013, 'Unavailable');
239
390
  return;
240
391
  }
241
392
  const id = randomUUID();
393
+ let codec;
394
+ if (sealed) {
395
+ let hello;
396
+ try {
397
+ codec = this.codecs.forConnection({
398
+ host: withoutPort(this.web.requestHost(request)),
399
+ path: request.url.split('?', 1)[0] ?? route.path,
400
+ userAgent: String(request.headers['user-agent'] ?? ''),
401
+ nonces: this.hub.nonces(),
402
+ driftMs: this.settings.sealDriftMs,
403
+ });
404
+ hello = codec.hello();
405
+ }
406
+ catch (error) {
407
+ this.#throttle.log('error', 'WebSocket seal codec failed; closed', 'SEAL_CODEC_FAILED', error, { connection: id });
408
+ socket.close(1011, 'Socket failure');
409
+ return;
410
+ }
411
+ // The first frame of a sealed connection: the client takes its clock offset from it and
412
+ // reports 'open' only after it (D-0059 §4).
413
+ socket.send(hello, TEXT, (error) => {
414
+ if (error)
415
+ this.#throttle.log('warn', 'WebSocket seal hello not sent', 'SEAL_HELLO_FAILED', error, {
416
+ connection: id,
417
+ });
418
+ });
419
+ if (this.context.logger.isEnabled('debug'))
420
+ this.context.logger.log('debug', 'WebSocket seal hello sent', { connection: id });
421
+ }
242
422
  const value = {
243
423
  socket,
424
+ codec,
244
425
  route,
245
426
  session: undefined,
246
427
  tail: Promise.resolve(),
@@ -259,6 +440,7 @@ export class Gateway {
259
440
  member: identity.member,
260
441
  clientId: identity.clientId ?? null,
261
442
  path: route.path,
443
+ sealed: codec !== undefined,
262
444
  remote: `${request.socket.remoteAddress ?? '?'}:${request.socket.remotePort ?? '?'}`,
263
445
  userAgent: String(request.headers['user-agent'] ?? '').slice(0, 160),
264
446
  // Browser context of the upgrade: a prerendered or prefetched page says so here.
@@ -269,14 +451,14 @@ export class Gateway {
269
451
  const session = Object.freeze({
270
452
  id,
271
453
  identity,
272
- send: (data) => this.#send(socket, data),
454
+ send: (data) => this.#send(value, data),
273
455
  broadcast: async (data, target) => {
274
456
  return this.hub.broadcast({ ...target, tenant: identity.tenant }, data);
275
457
  },
276
458
  join: async (room) => {
277
459
  if (!route.authorizeRoom || !(await route.authorizeRoom(identity, room))) {
278
460
  this.context.logger.log('debug', 'WebSocket room refused', { connection: id });
279
- throw new Error('Room access denied');
461
+ throw new WebsocketError('ROOM_FORBIDDEN', 'Room access denied');
280
462
  }
281
463
  await value.registration?.join(room);
282
464
  this.context.logger.log('debug', 'WebSocket room joined', {
@@ -299,18 +481,20 @@ export class Gateway {
299
481
  // repeats are counted per type and reply code; client errors are counted per code only.
300
482
  reportError: (error, details) => {
301
483
  if (details.source === 'handler') {
302
- this.#throttle.report('error', 'WebSocket handler failed.', 'SOCKET_HANDLER_FAILED', error === undefined ? 'NonError: undefined' : error, // `throw undefined` still shows
484
+ this.#throttle.log('error', 'WebSocket handler failed.', 'SOCKET_HANDLER_FAILED', error === undefined ? 'NonError: undefined' : error, // `throw undefined` still shows
303
485
  { type: details.type ?? null, reply: details.code, connection: id }, `${details.type ?? ''}\u0000${details.code}`);
304
486
  return;
305
487
  }
306
- this.#throttle.report('debug', 'WebSocket client message refused', details.code, error, {
488
+ this.#throttle.log('debug', 'WebSocket client message refused', details.code, error, {
307
489
  type: details.type?.slice(0, 64) ?? null,
308
490
  connection: id,
309
491
  });
310
492
  },
311
493
  });
312
494
  value.session = session;
313
- const registration = { ...identity, connection: id };
495
+ // `namespace` belongs to @dokebi/app (D-0061); the hub registers known fields only.
496
+ const { namespace: _namespace, ...fields } = identity;
497
+ const registration = { ...fields, connection: id };
314
498
  value.tail = this.#watch(this.hub.register(registration).then((handle) => {
315
499
  value.registration = handle;
316
500
  if (this.context.logger.isEnabled('debug'))
@@ -322,7 +506,7 @@ export class Gateway {
322
506
  const registered = value.tail;
323
507
  void value.tail.catch((error) => {
324
508
  // Converted to a close code (4409 or 1013) for the client; logged here for the operator.
325
- this.#throttle.report('warn', 'WebSocket registration failed', errorCode(error, 'REGISTRATION_FAILED'), error, { connection: id });
509
+ this.#throttle.log('warn', 'WebSocket registration failed', errorCode(error, 'REGISTRATION_FAILED'), error, { connection: id });
326
510
  value.failed = true;
327
511
  // The same (tenant, member, clientId) is already connected (D-0025): a client error, not
328
512
  // a hub outage. A client that retries with the same clientId is refused again.
@@ -338,79 +522,56 @@ export class Gateway {
338
522
  });
339
523
  // ws emits 'close' after 'error'; the close cleans up, the error is reported here.
340
524
  socket.on('error', (error) => {
341
- this.#throttle.report('error', 'WebSocket socket error', 'SOCKET_ERROR', error, {
525
+ this.#throttle.log('error', 'WebSocket socket error', 'SOCKET_ERROR', error, {
342
526
  reason: errorCode(error, 'UNKNOWN'),
343
527
  });
344
528
  });
345
529
  // Attach synchronously, before awaiting Redis/TCP registration, so early frames are queued.
346
- socket.on('message', (raw) => {
530
+ socket.on('message', (raw, isBinary) => {
347
531
  value.seen = performance.now();
348
- // Control frames are answered here, outside the route's message queue.
349
- const bytes = Array.isArray(raw)
350
- ? Buffer.concat(raw)
351
- : Buffer.from(raw instanceof ArrayBuffer ? new Uint8Array(raw) : raw);
352
- if (bytes[0] === 123) {
353
- let control;
354
- try {
355
- control = JSON.parse(bytes.toString());
356
- }
357
- catch {
358
- /* The route owns non-control payload parsing. */
359
- }
360
- // The page is alive (idleTimeoutMs): nothing else to do.
361
- if (control?.$dokebi === 'ping-v1')
362
- return;
363
- // A page loaded before D-0057 still acknowledges broadcasts: nothing to do, and no
364
- // reason to close it. Counted at debug until it reloads.
365
- if (control?.$dokebi === 'ack-v1') {
366
- this.#throttle.report('debug', 'WebSocket ACK from an old client ignored', 'ACK_IGNORED', undefined, { connection: id });
532
+ // ws hands each message its own Buffer (unmasked once, never reused): take it as it is
533
+ // instead of copying every frame (D-0068). Fragments are joined; an ArrayBuffer is wrapped.
534
+ const bytes = Buffer.isBuffer(raw)
535
+ ? raw
536
+ : Array.isArray(raw)
537
+ ? Buffer.concat(raw)
538
+ : Buffer.from(raw);
539
+ if (codec) {
540
+ // Sealed: the frame is opened in this connection's order chain, then handled like a
541
+ // plain one (control frames, then the route). Nothing is read before it opens.
542
+ if (this.#closing)
367
543
  return;
368
- }
369
- }
370
- if (this.#closing)
371
- return;
372
- if (++value.pending > this.settings.maxPendingMessages) {
373
- value.pending--;
374
- // The server closing a client is worth seeing (like SLOW_CONSUMER): usually a handler
375
- // that waits long (a slow database call) while the client keeps sending.
376
- this.#throttle.report('warn', 'WebSocket message queue full; closed', 'TOO_MANY_MESSAGES', undefined, {
377
- connection: id,
378
- pending: value.pending,
544
+ this.#enqueue(value, id, async () => {
545
+ if (value.failed)
546
+ return; // refused earlier (4400) or not registered: take nothing
547
+ let text;
548
+ try {
549
+ if (isBinary)
550
+ throw Object.assign(new Error('Binary frame'), { reason: 'binary' });
551
+ text = await codec.decode(bytes.toString());
552
+ }
553
+ catch (error) {
554
+ this.#refuse(value, id, error);
555
+ return;
556
+ }
557
+ if (text.charCodeAt(0) === 123 && this.#control(text, id))
558
+ return;
559
+ if (value.failed || !value.registration)
560
+ return;
561
+ return route.message(Buffer.from(text), session);
379
562
  });
380
- socket.close(1013, 'Too many messages');
381
563
  return;
382
564
  }
383
- const data = Array.isArray(raw)
384
- ? Buffer.concat(raw)
385
- : raw instanceof ArrayBuffer
386
- ? Buffer.from(raw)
387
- : Buffer.from(raw);
388
- const work = value.tail.then(() => {
565
+ // Control frames are answered here, outside the route's message queue.
566
+ if (bytes[0] === 123 && this.#control(bytes.toString(), id))
567
+ return;
568
+ if (this.#closing)
569
+ return;
570
+ this.#enqueue(value, id, () => {
389
571
  if (value.failed || !value.registration)
390
572
  return;
391
- return route.message(data, session);
392
- });
393
- value.tail = work
394
- .then(() => { }, (error) => {
395
- value.failed = true;
396
- // A reply that cannot be written because the socket is closing is not a handler
397
- // failure. A slow consumer was logged where it was closed; a client that left is
398
- // counted here as warn, once per interval: the client is gone, nothing on this
399
- // server failed (OPS-002 soak: thousands of these hid the real cause at error).
400
- const code = error?.code;
401
- if (code === 'SLOW_CONSUMER')
402
- return;
403
- if (code === 'SOCKET_CLOSED') {
404
- this.#throttle.report('warn', 'WebSocket reply dropped; socket closed', 'REPLY_DROPPED', error, { connection: id });
405
- return;
406
- }
407
- this.#throttle.report('error', 'WebSocket message handler failed', errorCode(error, 'HANDLER_FAILED'), error, { connection: id });
408
- socket.close(1011, 'Message failed');
409
- })
410
- .finally(() => {
411
- value.pending--;
573
+ return route.message(bytes, session);
412
574
  });
413
- this.#watch(value.tail);
414
575
  });
415
576
  socket.once('close', (code, reason) => {
416
577
  this.context.logger.log('debug', 'WebSocket closed', {
@@ -430,9 +591,81 @@ export class Gateway {
430
591
  });
431
592
  void this.#watch(cleanup).catch((error) => {
432
593
  // The hub drops this connection when it recovers (owner snapshot or expiry).
433
- this.#throttle.report('error', 'WebSocket presence cleanup deferred to hub recovery', 'PRESENCE_CLEANUP_DEFERRED', error, { connection: id });
594
+ this.#throttle.log('error', 'WebSocket presence cleanup deferred to hub recovery', 'PRESENCE_CLEANUP_DEFERRED', error, { connection: id });
595
+ });
596
+ });
597
+ }
598
+ /**
599
+ * Answers a `$dokebi` control frame (ping-v1, ack-v1); false when `text` is not one, so the
600
+ * route gets it.
601
+ */
602
+ #control(text, id) {
603
+ let control;
604
+ try {
605
+ control = JSON.parse(text);
606
+ }
607
+ catch {
608
+ /* The route owns non-control payload parsing. */
609
+ }
610
+ // The page is alive (idleTimeoutMs): nothing else to do.
611
+ if (control?.$dokebi === 'ping-v1')
612
+ return true;
613
+ // A page loaded before D-0057 still acknowledges broadcasts: nothing to do, and no
614
+ // reason to close it. Counted at debug until it reloads.
615
+ if (control?.$dokebi === 'ack-v1') {
616
+ this.#throttle.log('debug', 'WebSocket ACK from an old client ignored', 'ACK_IGNORED', undefined, { connection: id });
617
+ return true;
618
+ }
619
+ return false;
620
+ }
621
+ /**
622
+ * A sealed frame that did not open (plain text, binary, drift, replay, bad seal): 4400 and the
623
+ * connection takes nothing more. The reason goes to the log only, never to the client: telling
624
+ * `replay` from `drift` would let an attacker probe the defence (D-0059 §4).
625
+ */
626
+ #refuse(value, id, error) {
627
+ const given = error?.reason;
628
+ const reason = typeof given === 'string' && REASON.test(given) ? given : 'unknown';
629
+ value.failed = true;
630
+ this.#throttle.log('warn', 'WebSocket sealed frame refused; closed', 'SEAL_FRAME_REFUSED', error, { connection: id, reason }, reason);
631
+ value.socket.close(BAD_FRAME, 'Bad frame');
632
+ }
633
+ /** Runs `work` after this connection's earlier messages and presence calls, in order. */
634
+ #enqueue(value, id, work) {
635
+ const socket = value.socket;
636
+ if (++value.pending > this.settings.maxPending) {
637
+ value.pending--;
638
+ // The server closing a client is worth seeing (like SLOW_CONSUMER): usually a handler
639
+ // that waits long (a slow database call) while the client keeps sending.
640
+ this.#throttle.log('warn', 'WebSocket message queue full; closed', 'TOO_MANY_MESSAGES', undefined, {
641
+ connection: id,
642
+ pending: value.pending,
434
643
  });
644
+ socket.close(1013, 'Too many messages');
645
+ return;
646
+ }
647
+ value.tail = value.tail
648
+ .then(work)
649
+ .then(() => { }, (error) => {
650
+ value.failed = true;
651
+ // A reply that cannot be written because the socket is closing is not a handler
652
+ // failure. A slow consumer was logged where it was closed; a client that left is
653
+ // counted here as warn, once per interval: the client is gone, nothing on this
654
+ // server failed (OPS-002 soak: thousands of these hid the real cause at error).
655
+ const code = error?.code;
656
+ if (code === 'SLOW_CONSUMER')
657
+ return;
658
+ if (code === 'SOCKET_CLOSED') {
659
+ this.#throttle.log('warn', 'WebSocket reply dropped; socket closed', 'REPLY_DROPPED', error, { connection: id });
660
+ return;
661
+ }
662
+ this.#throttle.log('error', 'WebSocket message handler failed', errorCode(error, 'HANDLER_FAILED'), error, { connection: id });
663
+ socket.close(1011, 'Message failed');
664
+ })
665
+ .finally(() => {
666
+ value.pending--;
435
667
  });
668
+ this.#watch(value.tail);
436
669
  }
437
670
  /** Turns one server's new connection list into joins and leaves per tenant, for local routes. */
438
671
  #presence(owner, connections) {
@@ -475,8 +708,11 @@ export class Gateway {
475
708
  tenants: changes.size,
476
709
  joined,
477
710
  left,
711
+ listeners: this.#listeners.size,
478
712
  });
479
713
  }
714
+ if (this.#listeners.size)
715
+ this.#notify(changes);
480
716
  for (const value of this.#clients.values()) {
481
717
  const { route, session } = value;
482
718
  const change = session && changes.get(session.identity.tenant);
@@ -500,13 +736,147 @@ export class Gateway {
500
736
  const code = error?.code;
501
737
  if (code === 'SLOW_CONSUMER')
502
738
  return; // Logged where the socket was closed.
503
- this.#throttle.report(code === 'SOCKET_CLOSED' ? 'warn' : 'error', code === 'SOCKET_CLOSED'
739
+ this.#throttle.log(code === 'SOCKET_CLOSED' ? 'warn' : 'error', code === 'SOCKET_CLOSED'
504
740
  ? 'WebSocket presence dropped; socket closed'
505
741
  : 'WebSocket presence handler failed', code === 'SOCKET_CLOSED' ? 'REPLY_DROPPED' : 'PRESENCE_HANDLER_FAILED', error, { connection: session.id });
506
742
  });
507
743
  this.#watch(value.tail);
508
744
  }
509
745
  }
746
+ /** Records of the presence mirror (every server, as the hub reported them) that match. */
747
+ #mirror(filter) {
748
+ const result = [];
749
+ for (const records of this.#owners.values())
750
+ for (const record of records)
751
+ if ((filter.tenant === undefined
752
+ ? record.tenant.startsWith(filter.tenantPrefix)
753
+ : record.tenant === filter.tenant) &&
754
+ (filter.room === undefined || record.rooms.includes(filter.room)) &&
755
+ (filter.member === undefined || record.member === filter.member))
756
+ result.push(record);
757
+ return result;
758
+ }
759
+ /** One hub query per tenant the filter names: its own, or each known one under the prefix. */
760
+ #queries(filter) {
761
+ const narrow = {
762
+ ...(filter.room === undefined ? {} : { room: filter.room }),
763
+ ...(filter.member === undefined ? {} : { member: filter.member }),
764
+ };
765
+ if (filter.tenant !== undefined)
766
+ return [{ tenant: filter.tenant, ...narrow }];
767
+ const tenants = new Set(this.#mirror(filter).map((record) => record.tenant));
768
+ return [...tenants].map((tenant) => ({ tenant, ...narrow }));
769
+ }
770
+ /** Runs `call` for every query, FAN_OUT at a time; the results and failures in query order. */
771
+ async #fanOut(queries, call) {
772
+ const results = [];
773
+ const failures = [];
774
+ for (let index = 0; index < queries.length; index += FAN_OUT) {
775
+ const settled = await Promise.allSettled(queries.slice(index, index + FAN_OUT).map((query) => call(query)));
776
+ for (const outcome of settled)
777
+ if (outcome.status === 'fulfilled')
778
+ results.push(outcome.value);
779
+ else
780
+ failures.push(outcome.reason);
781
+ }
782
+ return { results, failures };
783
+ }
784
+ async #list(input) {
785
+ const filter = checkFilter(input);
786
+ const started = performance.now();
787
+ let records;
788
+ if (filter.tenant !== undefined) {
789
+ const [query] = this.#queries(filter);
790
+ records = (await this.hub.list(query)).connections;
791
+ }
792
+ else
793
+ records = this.#mirror(filter);
794
+ if (this.context.logger.isEnabled('debug'))
795
+ this.context.logger.log('debug', 'WebSocket connections listed', {
796
+ source: filter.tenant === undefined ? 'presence' : 'hub',
797
+ tenant: filter.tenant?.slice(0, 64) ?? null,
798
+ tenantPrefix: filter.tenantPrefix?.slice(0, 64) ?? null,
799
+ connections: records.length,
800
+ ms: Math.round((performance.now() - started) * 1000) / 1000,
801
+ });
802
+ return Object.freeze(records.map(connectionInfo));
803
+ }
804
+ async #broadcast(input, data) {
805
+ const filter = checkFilter(input);
806
+ if (typeof data !== 'string' && !(data instanceof Uint8Array))
807
+ throw new WebsocketError('INVALID_DATA', 'Broadcast data is a string or a Uint8Array');
808
+ const bytes = typeof data === 'string' ? encoder.encode(data) : data;
809
+ const queries = this.#queries(filter);
810
+ // A single tenant keeps the hub's own error (RECOVERING, BUSY, OUTCOME_UNKNOWN).
811
+ if (filter.tenant !== undefined) {
812
+ const receipt = await this.hub.broadcast(queries[0], bytes);
813
+ if (this.context.logger.isEnabled('debug'))
814
+ this.context.logger.log('debug', 'WebSocket server broadcast sent', {
815
+ id: receipt.id,
816
+ tenants: 1,
817
+ recipients: receipt.recipients.length,
818
+ bytes: bytes.byteLength,
819
+ });
820
+ return Object.freeze({ ids: Object.freeze([receipt.id]), recipients: receipt.recipients });
821
+ }
822
+ const { results, failures } = await this.#fanOut(queries, (query) => this.hub.broadcast(query, bytes));
823
+ const receipt = Object.freeze({
824
+ ids: Object.freeze(results.map((result) => result.id)),
825
+ recipients: Object.freeze(results.flatMap((result) => result.recipients)),
826
+ });
827
+ if (this.context.logger.isEnabled('debug'))
828
+ this.context.logger.log('debug', 'WebSocket server broadcast sent', {
829
+ tenantPrefix: filter.tenantPrefix?.slice(0, 64) ?? null,
830
+ tenants: queries.length,
831
+ failed: failures.length,
832
+ recipients: receipt.recipients.length,
833
+ bytes: bytes.byteLength,
834
+ });
835
+ if (failures.length)
836
+ throw Object.assign(new WebsocketError(errorCode(failures[0], 'BROADCAST_FAILED'), `WebSocket broadcast failed for ${failures.length} of ${queries.length} tenants`, { cause: new AggregateError(failures, 'Hub broadcast failures'), data: { receipt } }), { receipt });
837
+ return receipt;
838
+ }
839
+ async #kick(input, code, reason) {
840
+ const filter = checkFilter(input);
841
+ const queries = this.#queries(filter);
842
+ const { results, failures } = await this.#fanOut(queries, (query) => this.hub.kick(query, code, reason));
843
+ const receipt = Object.freeze({
844
+ ids: Object.freeze(results.map((result) => result.id)),
845
+ });
846
+ this.context.logger.log('debug', 'WebSocket server kick sent', {
847
+ tenant: filter.tenant?.slice(0, 64) ?? null,
848
+ tenantPrefix: filter.tenantPrefix?.slice(0, 64) ?? null,
849
+ tenants: queries.length,
850
+ failed: failures.length,
851
+ code: code ?? null,
852
+ });
853
+ if (failures.length === 1 && queries.length === 1)
854
+ throw failures[0];
855
+ if (failures.length)
856
+ throw Object.assign(new WebsocketError(errorCode(failures[0], 'KICK_FAILED'), `WebSocket kick failed for ${failures.length} of ${queries.length} tenants`, { cause: new AggregateError(failures, 'Hub kick failures'), data: { receipt } }), { receipt });
857
+ return receipt;
858
+ }
859
+ /** Hands each tenant's change to the `api.onPresence` listeners; their failures are logged. */
860
+ #notify(changes) {
861
+ for (const [tenant, change] of changes) {
862
+ const presence = Object.freeze({
863
+ tenant,
864
+ joined: Object.freeze([...change.joined]),
865
+ left: Object.freeze([...change.left]),
866
+ });
867
+ for (const listener of this.#listeners) {
868
+ const failed = (error) => this.#throttle.log('error', 'WebSocket presence listener failed', 'PRESENCE_LISTENER_FAILED', error);
869
+ try {
870
+ const result = listener(presence);
871
+ if (result && typeof result.then === 'function')
872
+ result.then(undefined, failed);
873
+ }
874
+ catch (error) {
875
+ failed(error);
876
+ }
877
+ }
878
+ }
879
+ }
510
880
  start() {
511
881
  const events = this.hub.events();
512
882
  this.#loop = (async () => {
@@ -527,22 +897,49 @@ export class Gateway {
527
897
  }
528
898
  // The broadcast bytes as they are (D-0057): a text frame when they are UTF-8 (the
529
899
  // `{ type, data }` JSON of defineSocket), a binary frame otherwise. One buffer shared
530
- // by every recipient; ws keeps per-socket order in its queue.
900
+ // by every plain recipient; ws keeps per-socket order in its queue. Sealed sockets get
901
+ // their own sealed copy of the text (each key and nonce is per connection and frame).
531
902
  const frame = Buffer.from(event.data.buffer, event.data.byteOffset, event.data.byteLength);
532
903
  const kind = isUtf8(frame) ? TEXT : BINARY;
533
904
  let local = 0;
905
+ let sealed = 0;
906
+ let dropped = 0;
907
+ let text;
534
908
  for (const id of event.connections) {
535
909
  const value = this.#clients.get(id);
536
- if (value) {
537
- local++;
910
+ if (!value)
911
+ continue;
912
+ local++;
913
+ if (!value.codec) {
538
914
  this.#deliver(value.socket, frame, kind);
915
+ continue;
916
+ }
917
+ // A sealed connection carries text only: a binary broadcast is not sent to it.
918
+ if (kind === BINARY) {
919
+ dropped++;
920
+ continue;
921
+ }
922
+ text ??= frame.toString();
923
+ let sealedFrame;
924
+ try {
925
+ sealedFrame = value.codec.encode(text);
926
+ }
927
+ catch (error) {
928
+ this.#throttle.log('error', 'WebSocket broadcast not sealed; socket closed', 'SEAL_ENCODE_FAILED', error, { connection: id });
929
+ value.socket.close(1011, 'Socket failure');
930
+ continue;
539
931
  }
932
+ sealed++;
933
+ this.#deliver(value.socket, sealedFrame, TEXT);
540
934
  }
935
+ if (dropped)
936
+ this.#throttle.log('warn', 'WebSocket binary broadcast not sent to sealed sockets', 'SEAL_BINARY_UNSUPPORTED', undefined, { id: event.id, dropped });
541
937
  if (this.context.logger.isEnabled('debug'))
542
938
  this.context.logger.log('debug', 'WebSocket broadcast delivered', {
543
939
  id: event.id,
544
940
  connections: event.connections.length,
545
941
  local,
942
+ sealed,
546
943
  binary: kind === BINARY,
547
944
  });
548
945
  // Queued events would otherwise be fanned out in one tick, before any socket can flush,
@@ -554,7 +951,7 @@ export class Gateway {
554
951
  // The hub ended its event stream (overflow, closed): every socket gets 1013 and reconnects.
555
952
  this.context.logger.log('error', 'WebSocket hub event stream failed; sockets closed', {
556
953
  code: 'HUB_EVENTS_FAILED',
557
- error: errorText(error),
954
+ error: describeError(error),
558
955
  open: this.#clients.size,
559
956
  });
560
957
  for (const value of this.#clients.values())
@@ -602,7 +999,7 @@ export class Gateway {
602
999
  await this.#idle(signal, stop, false);
603
1000
  for (const value of this.#clients.values())
604
1001
  value.socket.close(1012, 'Server restarting');
605
- const deadline = performance.now() + this.settings.closeTimeoutMs;
1002
+ const deadline = performance.now() + this.settings.shutdownTimeoutMs;
606
1003
  while (this.#clients.size && performance.now() < deadline && !signal.aborted)
607
1004
  await Promise.race([delay(10), stop]);
608
1005
  if (this.#clients.size)