@dokebi/websocket-hub 0.1.1 → 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,50 +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(store, identity.epoch, 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);
47
- await this.#deliveries.start();
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
+ });
48
82
  }
49
83
  async #renew() {
50
84
  const start = performance.now();
@@ -55,8 +89,12 @@ export class Leader {
55
89
  return now;
56
90
  }
57
91
  #queue(fn) {
58
- 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
+ });
59
96
  return Promise.reject(new HubError('BUSY'));
97
+ }
60
98
  this.#pending++;
61
99
  const work = this.#tail.then(async () => {
62
100
  if (!this.#active)
@@ -72,12 +110,23 @@ export class Leader {
72
110
  }
73
111
  accept(socket) {
74
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
+ });
75
117
  socket.destroy();
76
118
  return;
77
119
  }
78
120
  const peer = {
79
121
  wire: new Wire(socket, this.options.maxFrameBytes, this.options.queueBytes, (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);
126
+ return;
127
+ }
80
128
  void this.#queue(() => this.#handle(peer, frame)).catch((error) => {
129
+ this.#refused(frame.op, error);
81
130
  try {
82
131
  peer.wire.send({
83
132
  kind: 'reply',
@@ -85,27 +134,123 @@ export class Leader {
85
134
  epoch: this.identity.epoch,
86
135
  ok: false,
87
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 } : {}),
88
139
  });
89
140
  }
90
- catch { }
91
- if (!peer.owner || !this.active)
92
- peer.wire.close();
141
+ catch (failure) {
142
+ this.#sendFailed(peer, 'reply', failure);
143
+ }
144
+ this.#drop(peer);
93
145
  });
94
146
  }, () => {
95
147
  this.#sockets.delete(peer);
96
148
  if (peer.owner && this.#peers.get(peer.owner) === peer) {
97
149
  this.#peers.delete(peer.owner);
150
+ this.logger.log('debug', 'Hub peer disconnected', { owner: peer.owner });
98
151
  if (this.#active)
99
152
  void this.#queue(async () => {
100
153
  await this.#renew();
101
154
  await this.#remove(peer.owner, peer.session);
102
- }).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
+ });
103
164
  }
104
- }),
165
+ }, (code, error) => this.#wireError(peer)(code, error)),
105
166
  };
106
167
  this.#sockets.add(peer);
107
168
  socket.setTimeout(this.options.ownerTtlMs, () => socket.destroy());
108
169
  }
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();
188
+ let id;
189
+ try {
190
+ id = integer(f.id, 1, Number.MAX_SAFE_INTEGER);
191
+ if (!this.active)
192
+ throw new HubError('STALE_LEADER');
193
+ const ownerId = peer.owner;
194
+ if (!ownerId || this.#peers.get(ownerId) !== peer || f.epoch !== this.identity.epoch)
195
+ throw new HubError('STALE_PEER');
196
+ const owner = this.#owners.get(ownerId);
197
+ if (!owner || owner.session !== peer.session)
198
+ throw new HubError('STALE_PEER');
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;
209
+ try {
210
+ this.#send(destination, { kind: 'message', id: messageId, data: f.data, connections });
211
+ owners++;
212
+ }
213
+ catch (error) {
214
+ this.#sendFailed(destination, 'message', error);
215
+ }
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
+ }
236
+ }
237
+ catch (error) {
238
+ this.#refused(f.op, error);
239
+ try {
240
+ peer.wire.send({
241
+ kind: 'reply',
242
+ id,
243
+ epoch: this.identity.epoch,
244
+ ok: false,
245
+ code: error instanceof HubError ? error.code : 'PROTOCOL_ERROR',
246
+ });
247
+ }
248
+ catch (failure) {
249
+ this.#sendFailed(peer, 'reply', failure);
250
+ }
251
+ this.#drop(peer);
252
+ }
253
+ }
109
254
  #send(peer, value) {
110
255
  if (!this.active)
111
256
  throw new HubError('STALE_LEADER');
@@ -116,8 +261,8 @@ export class Leader {
116
261
  try {
117
262
  this.#send(peer, { kind: 'presence', revision: this.#revision, owner, connections });
118
263
  }
119
- catch {
120
- peer.wire.close();
264
+ catch (error) {
265
+ this.#sendFailed(peer, 'presence', error);
121
266
  }
122
267
  }
123
268
  }
@@ -155,12 +300,18 @@ export class Leader {
155
300
  if (rev) {
156
301
  this.#owners.delete(ownerId);
157
302
  this.#revision = rev;
303
+ this.logger.log('debug', 'Hub server removed', { owner: ownerId, revision: rev });
158
304
  this.#notify(ownerId, []);
159
305
  }
160
306
  }
161
307
  async #expire(now) {
162
308
  for (const [ownerId, owner] of this.#owners)
163
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
+ });
164
315
  this.#peers.get(ownerId)?.wire.close();
165
316
  await this.#remove(ownerId, owner.session);
166
317
  }
@@ -175,6 +326,16 @@ export class Leader {
175
326
  const supplied = typeof f.secret === 'string' ? Buffer.from(f.secret) : Buffer.alloc(0), expected = Buffer.from(this.options.secret);
176
327
  if (supplied.length !== expected.length || !timingSafeEqual(supplied, expected))
177
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
+ }
178
339
  const owner = epoch(f.owner), session = epoch(f.session);
179
340
  const values = records(f.connections, owner, this.options.maxConnections);
180
341
  const value = {
@@ -190,7 +351,15 @@ export class Leader {
190
351
  peer.session = session;
191
352
  this.#peers.set(owner, peer);
192
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
+ });
193
361
  result = {
362
+ protocol: PROTOCOL,
194
363
  revision: this.#revision,
195
364
  owners: [...this.#owners].map(([key, v]) => [key, v.connections]),
196
365
  };
@@ -203,52 +372,38 @@ export class Leader {
203
372
  if (!owner || owner.session !== peer.session)
204
373
  throw new HubError('STALE_PEER');
205
374
  if (f.op === 'set') {
206
- await this.#save(ownerId, {
207
- ...owner,
208
- connections: records(f.connections, ownerId, this.options.maxConnections),
209
- });
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
+ });
210
383
  }
211
384
  else if (f.op === 'ping') {
212
385
  owner.expires = Number(await this.store.run('touch', this.identity.epoch, String(this.options.ownerTtlMs), owner.session, ownerId));
213
386
  result = { revision: this.#revision };
214
387
  }
215
388
  else if (f.op === 'bye') {
389
+ this.logger.log('debug', 'Hub server said goodbye', { owner: ownerId });
216
390
  await this.#remove(ownerId, owner.session);
217
391
  this.#peers.delete(ownerId);
218
392
  }
219
- else if (f.op === 'ack') {
220
- await this.#deliveries.acknowledge(f.acks, owner.connections);
221
- }
222
- else if (f.op === 'broadcast') {
223
- await this.#deliveries.accept(ownerId, f, (ok, recipients) => {
224
- try {
225
- this.#send(peer, {
226
- kind: 'reply',
227
- id,
228
- ok,
229
- ...(ok
230
- ? { result: { authorityEpoch: this.identity.epoch, id: f.messageId, recipients } }
231
- : { code: 'DELIVERY_TIMEOUT' }),
232
- });
233
- }
234
- catch {
235
- peer.wire.close();
236
- }
237
- });
238
- return;
239
- }
240
393
  else if (f.op === 'kick') {
241
394
  const filter = query(f.query), messageId = randomUUID();
242
395
  const code = f.op === 'kick' ? integer(f.code, 4000, 4999) : undefined;
243
396
  const reason = f.op === 'kick' ? identifier(f.reason) : undefined;
244
397
  if (reason && Buffer.byteLength(reason) > 123)
245
398
  throw new HubError('INVALID_ARGUMENT');
399
+ let kicked = 0;
246
400
  for (const [key, target] of this.#owners) {
247
401
  const selected = target.connections
248
402
  .filter((r) => matches(r, filter))
249
403
  .map((r) => r.connection);
250
404
  if (!selected.length)
251
405
  continue;
406
+ kicked += selected.length;
252
407
  const destination = this.#peers.get(key);
253
408
  if (!destination)
254
409
  throw new HubError('OUTCOME_UNKNOWN');
@@ -261,11 +416,12 @@ export class Leader {
261
416
  reason,
262
417
  });
263
418
  }
264
- catch {
265
- destination.wire.close();
419
+ catch (error) {
420
+ this.#sendFailed(destination, 'kick', error);
266
421
  throw new HubError('OUTCOME_UNKNOWN');
267
422
  }
268
423
  }
424
+ this.logger.log('debug', 'Hub kick sent', { id: messageId, connections: kicked, code });
269
425
  result = { authorityEpoch: this.identity.epoch, id: messageId };
270
426
  }
271
427
  else
@@ -277,13 +433,35 @@ export class Leader {
277
433
  return this.#queue(async () => {
278
434
  const now = await this.#renew();
279
435
  await this.#expire(now);
280
- await this.#deliveries.tick();
281
436
  });
282
437
  }
283
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;
284
448
  this.#active = false;
285
- 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
+ }
286
462
  peer.wire.close();
463
+ }
287
464
  await this.#tail;
465
+ this.#throttle.flush();
288
466
  }
289
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
  }