@dokebi/websocket-hub 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/leader.js CHANGED
@@ -1,49 +1,90 @@
1
1
  import { randomUUID, timingSafeEqual } from 'node:crypto';
2
- import { Deliveries, recipientKey } from './delivery.js';
3
- import { integer } from './options.js';
4
- import { encode, epoch, identifier, matches, query, records } from './protocol.js';
2
+ import { diagnostics } from '@dokebi/core/libraries';
3
+ import { recipientKey } from './delivery.js';
4
+ import { HubIndex } from './hub-index.js';
5
+ import { encode, epoch, identifier, PROTOCOL, payload, query, records } from './protocol.js';
5
6
  import { HubError } from './types.js';
7
+ import { integer } from './values.js';
6
8
  import { Wire } from './wire.js';
7
9
  export class Leader {
8
10
  identity;
9
11
  store;
10
12
  options;
13
+ logger;
11
14
  #peers = new Map();
12
15
  #sockets = new Set();
13
16
  #owners = new Map();
17
+ /** Every owner's connections by tenant, member and room (D-0068); follows #owners. */
18
+ #index = new HubIndex();
14
19
  #revision = 0;
15
- #deliveries;
16
20
  #tail = Promise.resolve();
17
21
  #pending = 0;
18
22
  #active = true;
19
23
  #deadline = 0;
20
- constructor(identity, store, options) {
24
+ /** Failures and refusals on per-frame paths, logged once per interval with a count. */
25
+ #throttle;
26
+ constructor(identity, store, options, logger) {
21
27
  this.identity = identity;
22
28
  this.store = store;
23
29
  this.options = options;
24
- this.#deliveries = new Deliveries(options, () => [...this.#owners.values()].flatMap((owner) => owner.connections), (owner, frame) => {
25
- const peer = this.#peers.get(owner);
26
- if (!peer)
27
- return false;
28
- try {
29
- this.#send(peer, frame);
30
- return true;
31
- }
32
- catch {
33
- peer.wire.close();
34
- return false;
35
- }
30
+ this.logger = logger;
31
+ this.#throttle = new diagnostics.Repeats({ logger });
32
+ }
33
+ /**
34
+ * A frame to a peer could not be written (its socket is gone, its send queue passed maxPendingBytes,
35
+ * or this leader's lease lapsed): the peer is dropped and reconnects (D-0047: never silent).
36
+ */
37
+ #sendFailed(peer, frame, error) {
38
+ // A leader that is stopping closes every peer itself; a reply that no longer fits is not a
39
+ // fault (the peers reconnect to the next leader).
40
+ this.#throttle.log(this.#active ? 'error' : 'debug', 'Hub frame to a peer failed; peer dropped', 'PEER_SEND_FAILED', error, {
41
+ frame,
42
+ reason: diagnostics.errorCode(error, 'UNKNOWN'),
43
+ owner: peer.owner ?? null,
44
+ });
45
+ peer.wire.close();
46
+ }
47
+ /**
48
+ * A request refused with a reply. Hub errors are expected refusals (debug); anything else is a
49
+ * fault, and a store failure carries the Redis cause only here (error).
50
+ */
51
+ #refused(op, error) {
52
+ if (error instanceof HubError && error.code !== 'STORE_UNAVAILABLE') {
53
+ if (this.logger.isEnabled('debug'))
54
+ this.#throttle.log('debug', 'Hub request refused', error.code, undefined, {
55
+ op: typeof op === 'string' ? op.slice(0, 16) : null,
56
+ });
57
+ return;
58
+ }
59
+ this.#throttle.log('error', 'Hub leader request failed', 'LEADER_REQUEST_FAILED', error, {
60
+ op: typeof op === 'string' ? op.slice(0, 16) : null,
61
+ });
62
+ }
63
+ #wireError(peer) {
64
+ return (code, error) => this.#throttle.log('error', 'Hub peer connection failed', code, error, {
65
+ owner: peer.owner ?? null,
36
66
  });
37
67
  }
38
68
  get active() {
39
69
  return this.#active && performance.now() < this.#deadline;
40
70
  }
41
71
  async start() {
72
+ const started = performance.now();
42
73
  await this.#renew();
43
74
  const snapshot = await this.store.snapshot(this.identity.epoch);
44
75
  this.#owners = snapshot.owners;
76
+ this.#index.clear();
77
+ for (const [ownerId, owner] of this.#owners)
78
+ this.#index.setOwner(ownerId, owner.connections);
45
79
  this.#revision = snapshot.revision;
46
80
  await this.#expire(snapshot.now);
81
+ this.logger.log('debug', 'Hub leader started', {
82
+ epoch: this.identity.epoch,
83
+ serverId: this.identity.serverId,
84
+ owners: this.#owners.size,
85
+ revision: this.#revision,
86
+ ms: Math.round(performance.now() - started),
87
+ });
47
88
  }
48
89
  async #renew() {
49
90
  const start = performance.now();
@@ -54,8 +95,12 @@ export class Leader {
54
95
  return now;
55
96
  }
56
97
  #queue(fn) {
57
- if (this.#pending >= this.options.maxPending)
98
+ if (this.#pending >= this.options.maxPending) {
99
+ this.#throttle.log('debug', 'Hub leader queue full; request refused', 'BUSY', undefined, {
100
+ pending: this.#pending,
101
+ });
58
102
  return Promise.reject(new HubError('BUSY'));
103
+ }
59
104
  this.#pending++;
60
105
  const work = this.#tail.then(async () => {
61
106
  if (!this.#active)
@@ -71,18 +116,23 @@ export class Leader {
71
116
  }
72
117
  accept(socket) {
73
118
  if (!this.active || this.#sockets.size >= this.options.maxOwners) {
119
+ this.logger.log('debug', 'Hub peer refused', {
120
+ reason: this.active ? 'MAX_OWNERS' : 'NOT_LEADER',
121
+ peers: this.#sockets.size,
122
+ });
74
123
  socket.destroy();
75
124
  return;
76
125
  }
77
126
  const peer = {
78
- wire: new Wire(socket, this.options.maxFrameBytes, this.options.queueBytes, (frame) => {
79
- // Broadcasts and ACKs stay in memory (D-0042): no Redis round trip and no wait behind
80
- // owner updates. The lease is checked against its local deadline.
81
- if (frame.op === 'broadcast' || frame.op === 'ack') {
82
- this.#deliver(peer, frame);
127
+ wire: new Wire(socket, this.options.maxFrameBytes, this.options.maxPendingBytes, (frame) => {
128
+ // Broadcasts never touch Redis and do not wait behind owner updates (D-0042): the
129
+ // lease is checked against its local deadline.
130
+ if (frame.op === 'broadcast') {
131
+ this.#broadcast(peer, frame);
83
132
  return;
84
133
  }
85
134
  void this.#queue(() => this.#handle(peer, frame)).catch((error) => {
135
+ this.#refused(frame.op, error);
86
136
  try {
87
137
  peer.wire.send({
88
138
  kind: 'reply',
@@ -90,28 +140,57 @@ export class Leader {
90
140
  epoch: this.identity.epoch,
91
141
  ok: false,
92
142
  code: error instanceof HubError ? error.code : 'STORE_UNAVAILABLE',
143
+ // A refused hello says which protocol this leader speaks (D-0057).
144
+ ...(frame.op === 'hello' ? { protocol: PROTOCOL } : {}),
93
145
  });
94
146
  }
95
- catch { }
96
- if (!peer.owner || !this.active)
97
- peer.wire.close();
147
+ catch (failure) {
148
+ this.#sendFailed(peer, 'reply', failure);
149
+ }
150
+ this.#drop(peer);
98
151
  });
99
152
  }, () => {
100
153
  this.#sockets.delete(peer);
101
154
  if (peer.owner && this.#peers.get(peer.owner) === peer) {
102
155
  this.#peers.delete(peer.owner);
156
+ this.logger.log('debug', 'Hub peer disconnected', { owner: peer.owner });
103
157
  if (this.#active)
104
158
  void this.#queue(async () => {
105
159
  await this.#renew();
106
160
  await this.#remove(peer.owner, peer.session);
107
- }).catch(() => this.stop());
161
+ }).catch((error) => {
162
+ // Lease lost or Redis down: another server takes over and expires the owner.
163
+ this.logger.log('error', 'Hub leader could not remove a disconnected server', {
164
+ code: 'OWNER_REMOVE_FAILED',
165
+ error: diagnostics.describeError(error),
166
+ owner: peer.owner ?? null,
167
+ });
168
+ return this.stop();
169
+ });
108
170
  }
109
- }),
171
+ }, (code, error) => this.#wireError(peer)(code, error)),
110
172
  };
111
173
  this.#sockets.add(peer);
112
174
  socket.setTimeout(this.options.ownerTtlMs, () => socket.destroy());
113
175
  }
114
- #deliver(peer, f) {
176
+ /**
177
+ * A peer whose request was refused: one that never said hello gets the reply before its
178
+ * socket ends (an old protocol or a wrong secret is then logged by that peer), and every peer
179
+ * of a leader that lost its lease is dropped.
180
+ */
181
+ #drop(peer) {
182
+ if (!peer.owner)
183
+ peer.wire.end(1000);
184
+ else if (!this.active)
185
+ peer.wire.close();
186
+ }
187
+ /**
188
+ * One broadcast (D-0057): the recipients are the connections that match now; each server that
189
+ * holds some gets one message frame, then the producer gets the receipt. Nothing is kept: no
190
+ * client ACK, no resend, so a frame that cannot be written is lost with the peer it was for.
191
+ */
192
+ #broadcast(peer, f) {
193
+ const started = performance.now();
115
194
  let id;
116
195
  try {
117
196
  id = integer(f.id, 1, Number.MAX_SAFE_INTEGER);
@@ -123,38 +202,46 @@ export class Leader {
123
202
  const owner = this.#owners.get(ownerId);
124
203
  if (!owner || owner.session !== peer.session)
125
204
  throw new HubError('STALE_PEER');
126
- if (f.op === 'ack') {
127
- this.#deliveries.acknowledge(f.acks, owner.connections);
128
- this.#send(peer, { kind: 'reply', id, ok: true, result: {} });
129
- return;
130
- }
131
- const reply = id;
132
- this.#deliveries.accept(ownerId, f, (ok, recipients) => {
205
+ const filter = query(f.query);
206
+ payload(f.data, this.options.maxPayloadBytes);
207
+ const messageId = randomUUID();
208
+ const selection = this.#index.select(filter);
209
+ let owners = 0;
210
+ for (const [target, connections] of selection.owners) {
211
+ const destination = this.#peers.get(target);
212
+ // A server whose socket is gone gets nothing; its connections miss this message.
213
+ if (!destination)
214
+ continue;
133
215
  try {
134
- this.#send(peer, {
135
- kind: 'reply',
136
- id: reply,
137
- ok,
138
- ...(ok
139
- ? { result: { authorityEpoch: this.identity.epoch, id: f.messageId, recipients } }
140
- : { code: 'DELIVERY_TIMEOUT' }),
141
- });
142
- }
143
- catch {
144
- peer.wire.close();
216
+ this.#send(destination, { kind: 'message', id: messageId, data: f.data, connections });
217
+ owners++;
145
218
  }
146
- },
147
- // The producer keeps the recipient list to resend it to the next leader.
148
- (recipients) => {
149
- try {
150
- this.#send(peer, { kind: 'accepted', id: f.messageId, recipients });
219
+ catch (error) {
220
+ this.#sendFailed(destination, 'message', error);
151
221
  }
152
- catch {
153
- peer.wire.close();
154
- }
155
- });
222
+ }
223
+ if (this.logger.isEnabled('debug'))
224
+ this.logger.log('debug', 'Hub broadcast sent', {
225
+ id: messageId,
226
+ recipients: selection.recipients.length,
227
+ owners,
228
+ ms: Math.round((performance.now() - started) * 1000) / 1000,
229
+ });
230
+ try {
231
+ this.#send(peer, {
232
+ kind: 'reply',
233
+ id,
234
+ ok: true,
235
+ result: { id: messageId, recipients: selection.recipients },
236
+ });
237
+ }
238
+ catch (error) {
239
+ // The producer sees the drop as OUTCOME_UNKNOWN: the message was sent.
240
+ this.#sendFailed(peer, 'reply', error);
241
+ }
156
242
  }
157
243
  catch (error) {
244
+ this.#refused(f.op, error);
158
245
  try {
159
246
  peer.wire.send({
160
247
  kind: 'reply',
@@ -164,9 +251,10 @@ export class Leader {
164
251
  code: error instanceof HubError ? error.code : 'PROTOCOL_ERROR',
165
252
  });
166
253
  }
167
- catch { }
168
- if (!peer.owner || !this.active)
169
- peer.wire.close();
254
+ catch (failure) {
255
+ this.#sendFailed(peer, 'reply', failure);
256
+ }
257
+ this.#drop(peer);
170
258
  }
171
259
  }
172
260
  #send(peer, value) {
@@ -179,8 +267,8 @@ export class Leader {
179
267
  try {
180
268
  this.#send(peer, { kind: 'presence', revision: this.#revision, owner, connections });
181
269
  }
182
- catch {
183
- peer.wire.close();
270
+ catch (error) {
271
+ this.#sendFailed(peer, 'presence', error);
184
272
  }
185
273
  }
186
274
  }
@@ -211,19 +299,27 @@ export class Leader {
211
299
  this.#revision = result[0];
212
300
  value.expires = result[1];
213
301
  this.#owners.set(ownerId, value);
302
+ this.#index.setOwner(ownerId, value.connections);
214
303
  this.#notify(ownerId, value.connections);
215
304
  }
216
305
  async #remove(ownerId, session) {
217
306
  const rev = Number(await this.store.run('remove', this.identity.epoch, '', session, ownerId));
218
307
  if (rev) {
219
308
  this.#owners.delete(ownerId);
309
+ this.#index.removeOwner(ownerId);
220
310
  this.#revision = rev;
311
+ this.logger.log('debug', 'Hub server removed', { owner: ownerId, revision: rev });
221
312
  this.#notify(ownerId, []);
222
313
  }
223
314
  }
224
315
  async #expire(now) {
225
316
  for (const [ownerId, owner] of this.#owners)
226
317
  if (owner.expires <= now) {
318
+ this.logger.log('debug', 'Hub server expired', {
319
+ owner: ownerId,
320
+ serverId: owner.serverId,
321
+ connections: owner.connections.length,
322
+ });
227
323
  this.#peers.get(ownerId)?.wire.close();
228
324
  await this.#remove(ownerId, owner.session);
229
325
  }
@@ -235,9 +331,19 @@ export class Leader {
235
331
  if (f.op === 'hello') {
236
332
  if (peer.owner)
237
333
  throw new HubError('ALREADY_REGISTERED');
238
- const supplied = typeof f.secret === 'string' ? Buffer.from(f.secret) : Buffer.alloc(0), expected = Buffer.from(this.options.secret);
334
+ const supplied = typeof f.secret === 'string' ? Buffer.from(f.secret) : Buffer.alloc(0), expected = Buffer.from(this.options.secret ?? '');
239
335
  if (supplied.length !== expected.length || !timingSafeEqual(supplied, expected))
240
336
  throw new HubError('UNAUTHORIZED');
337
+ if (f.protocol !== PROTOCOL) {
338
+ // A server of another version (rolling restart): it retries and logs an error itself;
339
+ // a 0.2 server does not know this code, so say it here as well (D-0057).
340
+ this.#throttle.log('warn', 'Hub peer refused; protocol differs', 'PROTOCOL_MISMATCH', undefined, {
341
+ protocol: PROTOCOL,
342
+ peerProtocol: typeof f.protocol === 'number' ? f.protocol : null,
343
+ serverId: typeof f.serverId === 'string' ? f.serverId.slice(0, 64) : null,
344
+ });
345
+ throw new HubError('PROTOCOL_MISMATCH');
346
+ }
241
347
  const owner = epoch(f.owner), session = epoch(f.session);
242
348
  const values = records(f.connections, owner, this.options.maxConnections);
243
349
  const value = {
@@ -253,7 +359,15 @@ export class Leader {
253
359
  peer.session = session;
254
360
  this.#peers.set(owner, peer);
255
361
  previous?.wire.close();
362
+ this.logger.log('debug', 'Hub server registered', {
363
+ owner,
364
+ serverId: value.serverId,
365
+ connections: values.length,
366
+ replaced: previous !== undefined,
367
+ servers: this.#owners.size,
368
+ });
256
369
  result = {
370
+ protocol: PROTOCOL,
257
371
  revision: this.#revision,
258
372
  owners: [...this.#owners].map(([key, v]) => [key, v.connections]),
259
373
  };
@@ -266,16 +380,21 @@ export class Leader {
266
380
  if (!owner || owner.session !== peer.session)
267
381
  throw new HubError('STALE_PEER');
268
382
  if (f.op === 'set') {
269
- await this.#save(ownerId, {
270
- ...owner,
271
- connections: records(f.connections, ownerId, this.options.maxConnections),
272
- });
383
+ const connections = records(f.connections, ownerId, this.options.maxConnections);
384
+ await this.#save(ownerId, { ...owner, connections });
385
+ if (this.logger.isEnabled('debug'))
386
+ this.logger.log('debug', 'Hub connections changed', {
387
+ owner: ownerId,
388
+ connections: connections.length,
389
+ revision: this.#revision,
390
+ });
273
391
  }
274
392
  else if (f.op === 'ping') {
275
393
  owner.expires = Number(await this.store.run('touch', this.identity.epoch, String(this.options.ownerTtlMs), owner.session, ownerId));
276
394
  result = { revision: this.#revision };
277
395
  }
278
396
  else if (f.op === 'bye') {
397
+ this.logger.log('debug', 'Hub server said goodbye', { owner: ownerId });
279
398
  await this.#remove(ownerId, owner.session);
280
399
  this.#peers.delete(ownerId);
281
400
  }
@@ -285,12 +404,9 @@ export class Leader {
285
404
  const reason = f.op === 'kick' ? identifier(f.reason) : undefined;
286
405
  if (reason && Buffer.byteLength(reason) > 123)
287
406
  throw new HubError('INVALID_ARGUMENT');
288
- for (const [key, target] of this.#owners) {
289
- const selected = target.connections
290
- .filter((r) => matches(r, filter))
291
- .map((r) => r.connection);
292
- if (!selected.length)
293
- continue;
407
+ let kicked = 0;
408
+ for (const [key, selected] of this.#index.select(filter).owners) {
409
+ kicked += selected.length;
294
410
  const destination = this.#peers.get(key);
295
411
  if (!destination)
296
412
  throw new HubError('OUTCOME_UNKNOWN');
@@ -303,11 +419,12 @@ export class Leader {
303
419
  reason,
304
420
  });
305
421
  }
306
- catch {
307
- destination.wire.close();
422
+ catch (error) {
423
+ this.#sendFailed(destination, 'kick', error);
308
424
  throw new HubError('OUTCOME_UNKNOWN');
309
425
  }
310
426
  }
427
+ this.logger.log('debug', 'Hub kick sent', { id: messageId, connections: kicked, code });
311
428
  result = { authorityEpoch: this.identity.epoch, id: messageId };
312
429
  }
313
430
  else
@@ -319,13 +436,35 @@ export class Leader {
319
436
  return this.#queue(async () => {
320
437
  const now = await this.#renew();
321
438
  await this.#expire(now);
322
- this.#deliveries.tick();
323
439
  });
324
440
  }
325
441
  async stop() {
442
+ if (this.#active)
443
+ this.logger.log('debug', 'Hub leader stopped', {
444
+ epoch: this.identity.epoch,
445
+ peers: this.#sockets.size,
446
+ });
447
+ // A planned stop tells the peers first, so they reconnect (debug) instead of reporting a
448
+ // dropped leader (error): a whole cluster stopping or a rolling restart is not an outage.
449
+ // Peers before 0.3.0 are refused at hello (protocol 2) and never get this frame and fail the connection, as the close would.
450
+ const leaving = this.#active;
326
451
  this.#active = false;
327
- for (const peer of this.#sockets)
452
+ for (const peer of this.#sockets) {
453
+ if (leaving && peer.owner)
454
+ try {
455
+ peer.wire.send({ kind: 'leaving', epoch: this.identity.epoch });
456
+ peer.wire.end(1000);
457
+ continue;
458
+ }
459
+ catch (error) {
460
+ this.logger.log('debug', 'Hub leaving notice not sent', {
461
+ owner: peer.owner,
462
+ error: diagnostics.describeError(error),
463
+ });
464
+ }
328
465
  peer.wire.close();
466
+ }
329
467
  await this.#tail;
468
+ this.#throttle.flush();
330
469
  }
331
470
  }
package/dist/local.d.ts CHANGED
@@ -1,20 +1,24 @@
1
+ import { type Logger } from '@dokebi/core';
1
2
  import type { HubOptions } from './options.js';
2
3
  import { type HubApi } from './types.js';
3
4
  /**
4
5
  * The hub of one process (D-0029, `mode: 'local'`): the same HubApi as the cluster hub, kept in
5
- * memory. Broadcasts still resolve only after every recipient acknowledged (D-0025) and are
6
- * resent every retryMs until then; a recipient with a clientId that reconnects receives what it
7
- * missed. Undelivered messages are lost with the process, and there is no failover.
6
+ * memory. A broadcast is handed to the event queue the websocket gateway reads and resolves at
7
+ * once, at most once (D-0057): no ACK, no resend. There is no failover.
8
8
  */
9
9
  export declare class LocalHub {
10
10
  #private;
11
11
  readonly options: HubOptions;
12
- /** Told once when replay nonces are used where they cannot be shared (D-0038). */
13
- readonly warn: (message: string, data: Record<string, unknown>) => void;
12
+ /** The plugin logger; the console default keeps failures visible. */
13
+ readonly logger: Logger;
14
+ /** This process is a node:cluster worker (`context.runtime.role`, D-0063 §4). */
15
+ readonly worker: boolean;
14
16
  readonly api: HubApi;
15
17
  readonly ownerEpoch: `${string}-${string}-${string}-${string}-${string}`;
16
18
  constructor(options: HubOptions,
17
- /** Told once when replay nonces are used where they cannot be shared (D-0038). */
18
- warn?: (message: string, data: Record<string, unknown>) => void);
19
+ /** The plugin logger; the console default keeps failures visible. */
20
+ logger?: Logger,
21
+ /** This process is a node:cluster worker (`context.runtime.role`, D-0063 §4). */
22
+ worker?: boolean);
19
23
  close(): Promise<void>;
20
24
  }