@dokebi/websocket-hub 0.2.0 → 0.3.0

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