@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.
@@ -1,12 +1,16 @@
1
1
  import { randomUUID } from 'node:crypto';
2
2
  import { createConnection } from 'node:net';
3
- import { setTimeout as delay } from 'node:timers/promises';
3
+ import { ConsoleLogger } from '@dokebi/core';
4
+ import { diagnostics } from '@dokebi/core/libraries';
4
5
  import { EventQueue } from './event-queue.js';
5
- import { array, epoch, identifier, matches, metadata, payload, query, record, records, sequence, } from './protocol.js';
6
+ import { array, epoch, identifier, matches, metadata, PROTOCOL, payload, query, record, records, sequence, } from './protocol.js';
6
7
  import { HubError, } from './types.js';
7
8
  import { Wire } from './wire.js';
9
+ /** Codes of a leader that refused a broadcast because it is not (or no longer) the leader. */
10
+ const NOT_LEADER = new Set(['STALE_LEADER', 'STALE_PEER']);
8
11
  export class PeerClient {
9
12
  options;
13
+ logger;
10
14
  ownerEpoch = randomUUID();
11
15
  #session;
12
16
  /** Session of the last hello; the owner record in Redis carries the same value. */
@@ -19,28 +23,39 @@ export class PeerClient {
19
23
  #peers = new Map();
20
24
  #revision = 0;
21
25
  #broadcasts = 0;
22
- /** Unfinished broadcasts by message id; the leader's recipient list is added when accepted. */
23
- #outgoing = new Map();
24
- #acks = new Map();
25
- #ackBytes = 0;
26
- #ackTimer;
26
+ /** Protocol a leader named when it refused our hello (PROTOCOL_MISMATCH), for the log. */
27
+ #leaderProtocol;
27
28
  #beforeReady = [];
28
29
  #wire;
29
30
  #leader;
30
31
  #ready = false;
31
32
  #closing = false;
33
+ /** Saying bye: a drop now is this server leaving, not a fault (close() reports the result). */
34
+ #leaving = false;
35
+ /** The leader said it is stopping: the drop that follows is planned. */
36
+ #leaderLeaving = false;
32
37
  #next = 0;
33
38
  #pending = new Map();
34
39
  #tail = Promise.resolve();
35
40
  #queued = 0;
41
+ /**
42
+ * Roster changes waiting for one `set` (group commit). `set` carries the whole list, so the
43
+ * changes that arrive while one is queued or in flight are sent together as the final list:
44
+ * 500 sockets leaving took 500 sequential sets (about 1.8 s per worker, OPS-002) and every
45
+ * broadcast in that window waited the full deadline for connections that were gone.
46
+ */
47
+ #roster = [];
36
48
  #connecting;
37
49
  #readyWaiters = new Set();
38
- /** Told why the connection to the leader was dropped (logged by the hub node). */
39
- #onFail;
40
- constructor(options, onFail = () => { }) {
50
+ /** Failures and decisions on per-message paths, logged once per interval with a count. */
51
+ #throttle;
52
+ constructor(options,
53
+ /** The hub node passes the plugin logger; the console default keeps failures visible. */
54
+ logger = new ConsoleLogger()) {
41
55
  this.options = options;
42
- this.events = new EventQueue(options.maxPending, options.queueBytes);
43
- this.#onFail = onFail;
56
+ this.logger = logger;
57
+ this.events = new EventQueue(options.maxPending, options.maxPendingBytes);
58
+ this.#throttle = new diagnostics.Repeats({ logger });
44
59
  }
45
60
  get ready() {
46
61
  return this.#ready && !this.#closing && !!this.#wire && !this.#wire.socket.destroyed;
@@ -52,13 +67,25 @@ export class PeerClient {
52
67
  return this.#owned;
53
68
  }
54
69
  #fail(error) {
55
- if (this.#ready)
56
- this.#onFail(error instanceof HubError ? error.code : 'UNKNOWN');
70
+ if (this.#ready) {
71
+ const code = error instanceof HubError ? error.code : diagnostics.errorCode(error, 'UNKNOWN');
72
+ // RECOVERING and CLOSED are this server's own decisions (reconnect, shutdown); any other
73
+ // cause (revision gap, stale leader, socket closed) is a failure.
74
+ if (code === 'RECOVERING' || code === 'CLOSED' || this.#leaving || this.#leaderLeaving)
75
+ this.logger.log('debug', 'Hub connection dropped', {
76
+ code,
77
+ leader: this.#leader?.serverId ?? null,
78
+ });
79
+ else
80
+ this.#throttle.log('error', 'Hub connection dropped', code, error, {
81
+ leader: this.#leader?.serverId ?? null,
82
+ });
83
+ }
57
84
  this.#ready = false;
58
85
  this.#wire?.close();
59
86
  for (const p of this.#pending.values()) {
60
87
  clearTimeout(p.timer);
61
- p.reject(error);
88
+ p.reject(p.outcome ? new HubError('OUTCOME_UNKNOWN', { cause: error }) : error);
62
89
  }
63
90
  this.#pending.clear();
64
91
  }
@@ -79,12 +106,19 @@ export class PeerClient {
79
106
  return this.#connecting;
80
107
  }
81
108
  async #connect(leader) {
109
+ const started = performance.now();
82
110
  this.#fail(new HubError('RECOVERING'));
83
111
  await this.#tail;
84
112
  this.#beforeReady = [];
85
113
  this.#leader = leader;
114
+ this.#leaderLeaving = false;
86
115
  const socket = createConnection({ host: leader.host, port: leader.port });
87
- const wire = new Wire(socket, this.options.maxFrameBytes, this.options.queueBytes, (f) => {
116
+ // Before the hello answer the caller owns the failure: startup retries it (debug, a leader
117
+ // that is still opening refuses peers) and recovery logs it as an error, with this socket
118
+ // error as the cause. Only a connection that was up is reported here at error.
119
+ let established = false;
120
+ let socketError;
121
+ const wire = new Wire(socket, this.options.maxFrameBytes, this.options.maxPendingBytes, (f) => {
88
122
  if (this.#wire !== wire)
89
123
  return;
90
124
  try {
@@ -95,7 +129,16 @@ export class PeerClient {
95
129
  }
96
130
  }, () => {
97
131
  if (this.#wire === wire)
98
- this.#fail(new HubError('DISCONNECTED'));
132
+ this.#fail(new HubError('DISCONNECTED', socketError === undefined ? undefined : { cause: socketError }));
133
+ }, (code, error) => {
134
+ if (established) {
135
+ this.#throttle.log('error', 'Hub peer connection failed', code, error, {
136
+ leader: leader.serverId,
137
+ });
138
+ return;
139
+ }
140
+ socketError = error;
141
+ this.#throttle.log('debug', 'Hub peer connection failed before it was established', code, error, { leader: leader.serverId });
99
142
  });
100
143
  this.#wire = wire;
101
144
  const timer = setTimeout(() => socket.destroy(new Error('Connect timeout')), this.options.leaseMs);
@@ -111,13 +154,31 @@ export class PeerClient {
111
154
  await this.#operation(async () => {
112
155
  const session = randomUUID();
113
156
  this.#session = session;
114
- const value = (await this.#rpc('hello', {
115
- owner: this.ownerEpoch,
116
- session,
117
- serverId: this.options.serverId,
118
- secret: this.options.secret,
119
- connections: [...this.#owned.values()],
120
- }));
157
+ this.#leaderProtocol = undefined;
158
+ let value;
159
+ try {
160
+ value = (await this.#rpc('hello', {
161
+ protocol: PROTOCOL,
162
+ owner: this.ownerEpoch,
163
+ session,
164
+ serverId: this.options.serverId,
165
+ secret: this.options.secret ?? '',
166
+ connections: [...this.#owned.values()],
167
+ }));
168
+ }
169
+ catch (error) {
170
+ if (error instanceof HubError && error.code === 'PROTOCOL_MISMATCH')
171
+ this.#protocolMismatch(leader, this.#leaderProtocol, error);
172
+ throw error;
173
+ }
174
+ // A 0.2 leader answers without a protocol: its broadcasts wait for ACKs this server no
175
+ // longer sends, so it is refused here (rolling restart, D-0057).
176
+ if (value.protocol !== PROTOCOL) {
177
+ const error = new HubError('PROTOCOL_MISMATCH');
178
+ this.#protocolMismatch(leader, value.protocol, error);
179
+ wire.close();
180
+ throw error;
181
+ }
121
182
  const peers = new Map();
122
183
  for (const row of array(value.owners, this.options.maxOwners)) {
123
184
  const pair = array(row, 2);
@@ -132,13 +193,28 @@ export class PeerClient {
132
193
  const previous = this.#peers;
133
194
  this.#peers = peers;
134
195
  this.#revision = sequence(value.revision);
196
+ let resynced = 0;
135
197
  for (const [owner, connections] of peers)
136
- if (JSON.stringify(previous.get(owner) ?? []) !== JSON.stringify(connections))
198
+ if (JSON.stringify(previous.get(owner) ?? []) !== JSON.stringify(connections)) {
199
+ resynced++;
137
200
  this.#resync(owner, connections);
201
+ }
138
202
  for (const owner of previous.keys())
139
- if (!peers.has(owner))
203
+ if (!peers.has(owner)) {
204
+ resynced++;
140
205
  this.#resync(owner, []);
206
+ }
207
+ this.logger.log('debug', 'Hub connected to leader', {
208
+ leader: leader.serverId,
209
+ epoch: leader.epoch,
210
+ servers: peers.size,
211
+ connections: this.#owned.size,
212
+ revision: this.#revision,
213
+ resynced,
214
+ ms: Math.round(performance.now() - started),
215
+ });
141
216
  this.#ready = true;
217
+ established = true;
142
218
  for (const resolve of this.#readyWaiters)
143
219
  resolve(true);
144
220
  this.#readyWaiters.clear();
@@ -148,6 +224,18 @@ export class PeerClient {
148
224
  this.#receive(frame);
149
225
  }, true);
150
226
  }
227
+ /**
228
+ * Servers of different versions cannot share a leader (D-0057). Logged at error with both
229
+ * versions, once per interval: the hub keeps retrying until every server runs the same version.
230
+ */
231
+ #protocolMismatch(leader, theirs, error) {
232
+ this.#throttle.log('error', 'Hub protocol differs from the leader; retrying', 'PROTOCOL_MISMATCH', error, {
233
+ protocol: PROTOCOL,
234
+ leaderProtocol: typeof theirs === 'number' ? theirs : null,
235
+ leader: leader.serverId,
236
+ fix: 'Run the same @dokebi/websocket-hub version on every server of the namespace',
237
+ });
238
+ }
151
239
  #resync(owner, connections) {
152
240
  try {
153
241
  this.events.push({
@@ -166,6 +254,13 @@ export class PeerClient {
166
254
  #receive(f) {
167
255
  if (f.epoch !== this.#leader?.epoch)
168
256
  throw new HubError('STALE_LEADER');
257
+ if (f.kind === 'leaving') {
258
+ this.#leaderLeaving = true;
259
+ this.logger.log('debug', 'Hub leader is stopping', {
260
+ leader: this.#leader?.serverId ?? null,
261
+ });
262
+ return;
263
+ }
169
264
  if (f.kind === 'reply') {
170
265
  const id = Number(f.id), pending = this.#pending.get(id);
171
266
  if (!pending)
@@ -174,20 +269,12 @@ export class PeerClient {
174
269
  clearTimeout(pending.timer);
175
270
  if (f.ok === true)
176
271
  pending.resolve(f.result);
177
- else
178
- pending.reject(new HubError(typeof f.code === 'string' ? f.code : 'PROTOCOL_ERROR'));
179
- return;
180
- }
181
- if (f.kind === 'accepted') {
182
- // D-0042: the leader keeps broadcasts in memory only. The recipient list it chose rides
183
- // along when this broadcast is resent to the next leader.
184
- const body = this.#outgoing.get(epoch(f.id));
185
- if (body && body.recipients === undefined)
186
- body.recipients = array(f.recipients, this.options.maxTotalConnections).map((key) => {
187
- if (typeof key !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(key))
188
- throw new HubError('PROTOCOL_ERROR');
189
- return key;
190
- });
272
+ else {
273
+ const code = typeof f.code === 'string' ? f.code : 'PROTOCOL_ERROR';
274
+ if (code === 'PROTOCOL_MISMATCH')
275
+ this.#leaderProtocol = f.protocol;
276
+ pending.reject(new HubError(code));
277
+ }
191
278
  return;
192
279
  }
193
280
  if (f.kind === 'presence') {
@@ -206,6 +293,12 @@ export class PeerClient {
206
293
  this.#peers.set(owner, values);
207
294
  else
208
295
  this.#peers.delete(owner);
296
+ if (this.logger.isEnabled('debug'))
297
+ this.logger.log('debug', 'Hub presence changed', {
298
+ owner,
299
+ connections: values.length,
300
+ revision: rev,
301
+ });
209
302
  this.events.push({ kind: 'presence', revision: rev, ownerEpoch: owner, connections: values });
210
303
  return;
211
304
  }
@@ -217,12 +310,23 @@ export class PeerClient {
217
310
  id,
218
311
  connections,
219
312
  data: payload(f.data, this.options.maxPayloadBytes),
220
- expiresAt: sequence(f.expiresAt),
221
313
  };
222
314
  else if (f.kind === 'kick')
223
315
  event = { kind: 'kick', id, connections, code: Number(f.code), reason: identifier(f.reason) };
224
316
  else
225
317
  throw new HubError('PROTOCOL_ERROR');
318
+ // Broadcasts are at most once (D-0057) and producers no longer wait for ACKs, so a burst can
319
+ // outrun the gateway. A message that finds half the queue unread is dropped (warn, counted)
320
+ // instead of ending the event stream, which would stop this server's hub for good; the rest
321
+ // of the queue stays for presence and kicks, which cannot be dropped.
322
+ if (event.kind === 'message') {
323
+ if (!this.events.offer(event, 0.5))
324
+ this.#throttle.log('warn', 'Hub message dropped; event queue full', 'MESSAGE_DROPPED', undefined, {
325
+ id,
326
+ connections: connections.length,
327
+ });
328
+ return;
329
+ }
226
330
  try {
227
331
  this.events.push(event);
228
332
  }
@@ -232,7 +336,7 @@ export class PeerClient {
232
336
  throw error;
233
337
  }
234
338
  }
235
- #rpc(op, body = {}, timeout = this.options.leaseMs) {
339
+ #rpc(op, body = {}, timeout = this.options.leaseMs, outcome = false) {
236
340
  const wire = this.#wire;
237
341
  if (!wire || wire.socket.destroyed)
238
342
  return Promise.reject(new HubError('RECOVERING'));
@@ -246,7 +350,7 @@ export class PeerClient {
246
350
  this.#fail(new HubError('OUTCOME_UNKNOWN'));
247
351
  reject(new HubError('OUTCOME_UNKNOWN'));
248
352
  }, timeout);
249
- this.#pending.set(id, { resolve, reject, timer });
353
+ this.#pending.set(id, { resolve, reject, timer, outcome });
250
354
  try {
251
355
  wire.send({ id, op, epoch: this.#leader?.epoch, ...body });
252
356
  }
@@ -273,36 +377,99 @@ export class PeerClient {
273
377
  });
274
378
  return result;
275
379
  }
276
- async #replace(id, value) {
380
+ /**
381
+ * Queues one roster change. `apply` checks before it changes anything and throws a HubError to
382
+ * refuse only this change; the batch goes on. `offline` changes (a connection leaving) also
383
+ * work while recovering: they only have to leave the local roster.
384
+ */
385
+ #change(apply, offline = false) {
386
+ if (!offline && !this.ready)
387
+ return Promise.reject(new HubError('RECOVERING'));
388
+ if (this.#roster.length >= this.options.maxConnections + this.options.maxPending)
389
+ return Promise.reject(new HubError('BUSY'));
390
+ return new Promise((resolve, reject) => {
391
+ this.#roster.push({ apply, offline, resolve, reject });
392
+ // The first change of a batch queues the flush; later ones join it until it starts.
393
+ if (this.#roster.length === 1)
394
+ void this.#operation(() => this.#flushRoster(), true);
395
+ });
396
+ }
397
+ async #flushRoster() {
398
+ const batch = this.#roster;
399
+ this.#roster = [];
400
+ const started = performance.now();
401
+ const online = this.ready;
277
402
  const next = new Map(this.#owned);
278
- if (value)
279
- next.set(id, value);
280
- else
281
- next.delete(id);
282
- if (next.size > this.options.maxConnections)
283
- throw new HubError('CONNECTION_LIMIT');
284
- await this.#rpc('set', { connections: [...next.values()] });
403
+ const applied = [];
404
+ for (const change of batch) {
405
+ if (!online && !change.offline) {
406
+ change.reject(new HubError('RECOVERING'));
407
+ continue;
408
+ }
409
+ try {
410
+ change.apply(next);
411
+ applied.push(change);
412
+ }
413
+ catch (error) {
414
+ change.reject(error);
415
+ }
416
+ }
417
+ if (!applied.length)
418
+ return;
419
+ if (online)
420
+ try {
421
+ await this.#rpc('set', { connections: [...next.values()] });
422
+ }
423
+ catch (error) {
424
+ // Leaving connections leave locally anyway and the client reconnects to resync (as a
425
+ // single close did); every other change of the batch is refused with the cause.
426
+ const leaving = applied.filter((change) => change.offline);
427
+ for (const change of leaving)
428
+ change.apply(this.#owned);
429
+ for (const change of applied)
430
+ change.reject(error);
431
+ if (leaving.length)
432
+ this.disconnect();
433
+ return;
434
+ }
285
435
  this.#owned.clear();
286
- for (const [key, v] of next)
287
- this.#owned.set(key, v);
436
+ for (const [key, value] of next)
437
+ this.#owned.set(key, value);
438
+ for (const change of applied)
439
+ change.resolve();
440
+ if (this.logger.isEnabled('debug'))
441
+ this.logger.log('debug', 'Hub roster sent', {
442
+ changes: applied.length,
443
+ refused: batch.length - applied.length,
444
+ connections: next.size,
445
+ sent: online,
446
+ ms: Math.round(performance.now() - started),
447
+ });
288
448
  }
289
- register(input) {
290
- return this.#operation(async () => {
291
- const value = record(input, this.ownerEpoch);
292
- if (this.#owned.has(value.connection))
449
+ async register(input) {
450
+ const value = record(input, this.ownerEpoch);
451
+ await this.#change((next) => {
452
+ if (next.has(value.connection))
293
453
  throw new HubError('DUPLICATE_CONNECTION');
294
- await this.#replace(value.connection, value);
454
+ if (next.size >= this.options.maxConnections)
455
+ throw new HubError('CONNECTION_LIMIT');
456
+ next.set(value.connection, value);
457
+ });
458
+ {
295
459
  const token = Symbol();
296
460
  this.#tokens.set(value.connection, token);
297
461
  let closed = false;
462
+ let left = false;
298
463
  let closing;
299
- const change = (fn) => this.#operation(async () => {
300
- const current = this.#owned.get(value.connection);
464
+ const change = (fn) => this.#change((next) => {
465
+ const current = next.get(value.connection);
301
466
  if (closed || !current || this.#tokens.get(value.connection) !== token)
302
467
  throw new HubError('UNKNOWN_CONNECTION');
303
468
  const replacement = fn(current);
304
- await this.#replace(value.connection, replacement);
305
- if (!replacement) {
469
+ if (replacement)
470
+ next.set(value.connection, replacement);
471
+ else {
472
+ next.delete(value.connection);
306
473
  closed = true;
307
474
  this.#tokens.delete(value.connection);
308
475
  }
@@ -312,24 +479,19 @@ export class PeerClient {
312
479
  join: (room) => change((current) => record({ ...current, rooms: [...new Set([...current.rooms, identifier(room)])] }, this.ownerEpoch)),
313
480
  leave: (room) => change((current) => record({ ...current, rooms: current.rooms.filter((x) => x !== identifier(room)) }, this.ownerEpoch)),
314
481
  updateMetadata: (meta) => change((current) => record({ ...current, metadata: metadata(meta) }, this.ownerEpoch)),
315
- close: () => (closing ??= this.#operation(async () => {
316
- if (closed || this.#tokens.get(value.connection) !== token)
317
- return;
318
- closed = true;
319
- this.#tokens.delete(value.connection);
320
- this.#owned.delete(value.connection);
321
- if (this.ready) {
322
- try {
323
- await this.#rpc('set', { connections: [...this.#owned.values()] });
324
- }
325
- catch (error) {
326
- this.disconnect();
327
- throw error;
328
- }
482
+ close: () => (closing ??= this.#change((next) => {
483
+ // Applied to the batch's list, and again to the local list if the set failed.
484
+ if (!left) {
485
+ if (this.#tokens.get(value.connection) !== token)
486
+ return;
487
+ left = true;
488
+ closed = true;
489
+ this.#tokens.delete(value.connection);
329
490
  }
491
+ next.delete(value.connection);
330
492
  }, true)),
331
493
  });
332
- });
494
+ }
333
495
  }
334
496
  list(input) {
335
497
  if (!this.ready)
@@ -341,113 +503,67 @@ export class PeerClient {
341
503
  connections: Object.freeze([...this.#peers.values()].flat().filter((r) => matches(r, filter))),
342
504
  }));
343
505
  }
506
+ /**
507
+ * One request to the leader, answered once the leader has written the message frames
508
+ * (D-0057). Never resent: not connected is RECOVERING at once, a drop after sending is
509
+ * OUTCOME_UNKNOWN, and the caller decides whether to send again.
510
+ */
344
511
  broadcast(input, data) {
345
512
  if (!(data instanceof Uint8Array) || data.byteLength > this.options.maxPayloadBytes)
346
513
  return Promise.reject(new HubError('INVALID_ARGUMENT'));
347
- const filter = query(input), encoded = Buffer.from(data).toString('base64');
348
- if (this.#broadcasts >= this.options.maxPending)
514
+ let filter;
515
+ try {
516
+ filter = query(input);
517
+ }
518
+ catch (error) {
519
+ return Promise.reject(error);
520
+ }
521
+ if (this.#closing)
522
+ return Promise.reject(new HubError('CLOSED'));
523
+ if (!this.ready)
524
+ return Promise.reject(new HubError('RECOVERING'));
525
+ if (this.#broadcasts >= this.options.maxPending) {
526
+ this.#throttle.log('debug', 'Hub broadcast refused; too many in flight', 'BUSY', undefined, {
527
+ inFlight: this.#broadcasts,
528
+ });
349
529
  return Promise.reject(new HubError('BUSY'));
530
+ }
350
531
  this.#broadcasts++;
351
- const body = {
532
+ const sent = this.#rpc('broadcast', {
352
533
  query: filter,
353
- data: encoded,
354
- messageId: randomUUID(),
355
- expiresAt: Date.now() + this.options.deliveryTimeoutMs,
356
- };
357
- const expiresAt = body.expiresAt;
358
- this.#outgoing.set(body.messageId, body);
359
- return (async () => {
360
- try {
361
- while (!this.#closing && Date.now() < expiresAt) {
362
- try {
363
- if (this.ready)
364
- return (await this.#rpc('broadcast', body, Math.max(1, expiresAt - Date.now())));
365
- }
366
- catch (error) {
367
- if (!(error instanceof HubError) ||
368
- ![
369
- 'RECOVERING',
370
- 'DISCONNECTED',
371
- 'STALE_LEADER',
372
- 'STALE_PEER',
373
- 'STORE_UNAVAILABLE',
374
- 'OUTCOME_UNKNOWN',
375
- 'BUSY',
376
- ].includes(error.code))
377
- throw error;
378
- }
379
- await delay(Math.min(100, Math.max(1, expiresAt - Date.now())));
380
- }
381
- throw new HubError(this.#closing ? 'CLOSED' : 'DELIVERY_TIMEOUT');
382
- }
383
- finally {
384
- this.#broadcasts--;
385
- this.#outgoing.delete(body.messageId);
386
- }
387
- })();
388
- }
389
- acknowledge(id, connections) {
390
- epoch(id);
391
- if (this.#closing)
392
- return;
393
- if (!this.#acks.has(id) && this.#acks.size >= 256)
394
- return; // The durable sender retries unacknowledged deliveries.
395
- const selected = this.#acks.get(id) ?? new Set();
396
- for (const connection of array(connections, this.options.maxConnections).map(identifier)) {
397
- if (this.#owned.has(connection) &&
398
- !selected.has(connection) &&
399
- this.#ackBytes + Buffer.byteLength(connection) + 64 <= this.options.queueBytes) {
400
- selected.add(connection);
401
- this.#ackBytes += Buffer.byteLength(connection) + 64;
402
- }
403
- }
404
- this.#acks.set(id, selected);
405
- if (!this.#ackTimer)
406
- this.#ackTimer = setTimeout(() => {
407
- this.#ackTimer = undefined;
408
- const acks = this.#acks;
409
- this.#acks = new Map();
410
- this.#ackBytes = 0;
411
- if (!this.ready)
412
- return;
413
- // Split at the encoded frame boundary; oversize ACKs must not cause endless full-frame retries.
414
- let batch = [], bytes = 256;
415
- const flush = () => {
416
- if (batch.length)
417
- void this.#rpc('ack', { acks: batch }).catch(() => { });
418
- batch = [];
419
- bytes = 256;
420
- };
421
- for (const [id, connections] of acks) {
422
- let row = { id, connections: [] };
423
- for (const connection of connections) {
424
- const size = Buffer.byteLength(JSON.stringify(connection)) + 1;
425
- if (bytes + size + 128 > this.options.maxFrameBytes || batch.length >= 255) {
426
- if (row.connections.length)
427
- batch.push(row);
428
- flush();
429
- row = { id, connections: [] };
430
- }
431
- if (!row.connections.length)
432
- bytes += 96;
433
- row.connections.push(connection);
434
- bytes += size;
435
- }
436
- if (row.connections.length)
437
- batch.push(row);
438
- }
439
- flush();
440
- }, 10);
534
+ data: Buffer.from(data.buffer, data.byteOffset, data.byteLength).toString('base64'),
535
+ }, this.options.leaseMs, true);
536
+ return sent
537
+ .then((result) => {
538
+ const value = result;
539
+ return Object.freeze({
540
+ id: epoch(value.id),
541
+ recipients: Object.freeze(array(value.recipients, this.options.maxTotalConnections).map((key) => {
542
+ if (typeof key !== 'string')
543
+ throw new HubError('PROTOCOL_ERROR');
544
+ return key;
545
+ })),
546
+ });
547
+ }, (error) => {
548
+ // Refused by a leader that is no longer one, or not written to the socket: nothing
549
+ // was sent, as when not connected.
550
+ const code = error instanceof HubError ? error.code : undefined;
551
+ if (code !== undefined &&
552
+ (NOT_LEADER.has(code) || code === 'DISCONNECTED' || code === 'BACKPRESSURE'))
553
+ throw new HubError('RECOVERING', { cause: error });
554
+ if (code === 'OUTCOME_UNKNOWN')
555
+ this.#throttle.log('debug', 'Hub broadcast outcome unknown; not resent', 'OUTCOME_UNKNOWN', error);
556
+ throw error;
557
+ })
558
+ .finally(() => {
559
+ this.#broadcasts--;
560
+ });
441
561
  }
442
562
  kick(input, code = 4403, reason = 'Disconnected by hub') {
443
563
  const filter = query(input);
444
564
  return this.#operation(async () => (await this.#rpc('kick', { query: filter, code, reason })));
445
565
  }
446
566
  async close() {
447
- if (this.#ackTimer)
448
- clearTimeout(this.#ackTimer);
449
- this.#acks.clear();
450
- this.#ackBytes = 0;
451
567
  if (this.#closing) {
452
568
  this.#fail(new HubError('CLOSED'));
453
569
  this.events.finish();
@@ -456,6 +572,7 @@ export class PeerClient {
456
572
  return;
457
573
  }
458
574
  await this.#tail;
575
+ this.#leaving = true;
459
576
  try {
460
577
  if (this.ready)
461
578
  await this.#rpc('bye');
@@ -466,6 +583,7 @@ export class PeerClient {
466
583
  this.events.finish();
467
584
  for (const resolve of [...this.#readyWaiters])
468
585
  resolve(false);
586
+ this.#throttle.flush();
469
587
  }
470
588
  }
471
589
  disconnect() {
@@ -1,4 +1,10 @@
1
1
  import { type HubQuery, type HubRecord } from './types.js';
2
+ /**
3
+ * Version of the frames hub servers exchange, sent in hello (D-0057). 2: broadcasts without
4
+ * client ACKs (no `accepted`, `ack` or resend). A leader refuses another version with
5
+ * PROTOCOL_MISMATCH; a 0.2 leader answers without it and is refused by the peer.
6
+ */
7
+ export declare const PROTOCOL = 2;
2
8
  export declare function encode(value: unknown, limit: number): Uint8Array;
3
9
  export declare function decode(data: Uint8Array, limit: number): Record<string, unknown>;
4
10
  export declare function identifier(value: unknown): string;