@dokebi/websocket-hub 0.3.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.
@@ -0,0 +1,146 @@
1
+ import { recipientKey } from './delivery.js';
2
+ import { matches } from './protocol.js';
3
+ function addTo(map, key, record) {
4
+ const set = map.get(key);
5
+ if (set)
6
+ set.add(record);
7
+ else
8
+ map.set(key, new Set([record]));
9
+ }
10
+ function removeFrom(map, key, record) {
11
+ const set = map.get(key);
12
+ if (!set)
13
+ return;
14
+ set.delete(record);
15
+ if (!set.size)
16
+ map.delete(key);
17
+ }
18
+ /**
19
+ * The hub's connections indexed for selection (D-0068): tenant → member → connections, tenant →
20
+ * room → connections, and owner → connection → record. A targeted send (member, connection)
21
+ * costs O(1) plus its recipients and a room or tenant broadcast O(recipients), instead of a scan
22
+ * of every connection. Every candidate is still checked with `matches`, so the answer is the
23
+ * same as filtering all records (D-0057).
24
+ */
25
+ export class HubIndex {
26
+ #tenants = new Map();
27
+ #owners = new Map();
28
+ /** recipientKey → record: the DUPLICATE_CLIENT check without a scan. */
29
+ #clients = new Map();
30
+ #size = 0;
31
+ get size() {
32
+ return this.#size;
33
+ }
34
+ /** The record of a connection, or undefined. */
35
+ get(ownerEpoch, connection) {
36
+ return this.#owners.get(ownerEpoch)?.get(connection);
37
+ }
38
+ /** The record already registered under the same recipient identity, if any. */
39
+ client(record) {
40
+ return this.#clients.get(recipientKey(record));
41
+ }
42
+ /** Adds a record; a record of the same owner and connection is replaced. */
43
+ add(record) {
44
+ const previous = this.get(record.ownerEpoch, record.connection);
45
+ if (previous)
46
+ this.remove(previous);
47
+ let owner = this.#owners.get(record.ownerEpoch);
48
+ if (!owner) {
49
+ owner = new Map();
50
+ this.#owners.set(record.ownerEpoch, owner);
51
+ }
52
+ owner.set(record.connection, record);
53
+ let tenant = this.#tenants.get(record.tenant);
54
+ if (!tenant) {
55
+ tenant = { all: new Set(), members: new Map(), rooms: new Map() };
56
+ this.#tenants.set(record.tenant, tenant);
57
+ }
58
+ tenant.all.add(record);
59
+ addTo(tenant.members, record.member, record);
60
+ for (const room of record.rooms)
61
+ addTo(tenant.rooms, room, record);
62
+ this.#clients.set(recipientKey(record), record);
63
+ this.#size++;
64
+ }
65
+ /** Removes a record (by identity); false when it is not indexed. */
66
+ remove(record) {
67
+ const owner = this.#owners.get(record.ownerEpoch);
68
+ if (owner?.get(record.connection) !== record)
69
+ return false;
70
+ owner.delete(record.connection);
71
+ if (!owner.size)
72
+ this.#owners.delete(record.ownerEpoch);
73
+ const tenant = this.#tenants.get(record.tenant);
74
+ tenant.all.delete(record);
75
+ removeFrom(tenant.members, record.member, record);
76
+ for (const room of record.rooms)
77
+ removeFrom(tenant.rooms, room, record);
78
+ if (!tenant.all.size)
79
+ this.#tenants.delete(record.tenant);
80
+ const key = recipientKey(record);
81
+ if (this.#clients.get(key) === record)
82
+ this.#clients.delete(key);
83
+ this.#size--;
84
+ return true;
85
+ }
86
+ /** Replaces every record of one owner (a cluster server's full list). */
87
+ setOwner(ownerEpoch, records) {
88
+ this.removeOwner(ownerEpoch);
89
+ for (const record of records)
90
+ this.add(record);
91
+ }
92
+ removeOwner(ownerEpoch) {
93
+ const owner = this.#owners.get(ownerEpoch);
94
+ if (!owner)
95
+ return;
96
+ for (const record of [...owner.values()])
97
+ this.remove(record);
98
+ }
99
+ clear() {
100
+ this.#tenants.clear();
101
+ this.#owners.clear();
102
+ this.#clients.clear();
103
+ this.#size = 0;
104
+ }
105
+ /** The smallest indexed set that holds every match of `filter` (still to be checked). */
106
+ #candidates(filter) {
107
+ if (filter.connection) {
108
+ const record = this.get(filter.connection.ownerEpoch, filter.connection.connection);
109
+ return record ? [record] : [];
110
+ }
111
+ const tenant = this.#tenants.get(filter.tenant);
112
+ if (!tenant)
113
+ return [];
114
+ const member = filter.member === undefined ? undefined : tenant.members.get(filter.member);
115
+ const room = filter.room === undefined ? undefined : tenant.rooms.get(filter.room);
116
+ if (filter.member !== undefined && !member)
117
+ return [];
118
+ if (filter.room !== undefined && !room)
119
+ return [];
120
+ if (member && room)
121
+ return member.size <= room.size ? member : room;
122
+ return member ?? room ?? tenant.all;
123
+ }
124
+ /** The records that match `filter`, in the order they were indexed. */
125
+ *matching(filter) {
126
+ for (const record of this.#candidates(filter))
127
+ if (matches(record, filter))
128
+ yield record;
129
+ }
130
+ /** What `select` of delivery.ts returns for all indexed records, without the scan. */
131
+ select(filter) {
132
+ const recipients = new Set();
133
+ const owners = new Map();
134
+ for (const record of this.#candidates(filter)) {
135
+ if (!matches(record, filter))
136
+ continue;
137
+ recipients.add(recipientKey(record));
138
+ const connections = owners.get(record.ownerEpoch);
139
+ if (connections)
140
+ connections.push(record.connection);
141
+ else
142
+ owners.set(record.ownerEpoch, [record.connection]);
143
+ }
144
+ return { recipients: [...recipients], owners };
145
+ }
146
+ }
package/dist/index.d.ts CHANGED
@@ -1,7 +1,9 @@
1
- import { type PluginDependency } from '@dokebi/core';
2
1
  import { type HubApi } from './types.js';
3
2
  export * from './types.js';
4
3
  /** Factory input: `{ app, options? }`. Options default to `app.config['dokebi-websocket-hub']`. */
5
4
  export declare const createPlugin: import("@dokebi/core").PluginFactory<HubApi>;
6
- /** Use with `context.getDependency(dependency)`; a registered `dokebi-websocket-hub` instance is reused. */
7
- export declare const dependency: PluginDependency<HubApi>;
5
+ /**
6
+ * Use with `context.getDependency(dependency)`; a registered `dokebi-websocket-hub` instance is
7
+ * reused. Also `@dokebi/websocket-hub/dependency` (D-0063 §6), the same object.
8
+ */
9
+ export { dependency } from './dependency.js';
package/dist/index.js CHANGED
@@ -1,19 +1,21 @@
1
- import cluster from 'node:cluster';
2
- import { definePlugin, providerDependency, } from '@dokebi/core';
1
+ import { definePlugin, providerDependency } from '@dokebi/core';
3
2
  import { LocalHub } from './local.js';
4
3
  import { HubNode } from './node.js';
5
- import { parseOptions } from './options.js';
4
+ import { options as declaration } from './options.js';
6
5
  import { HubError } from './types.js';
7
6
  export * from './types.js';
7
+ // Local descriptors, not '@dokebi/redis/dependency' or '@dokebi/nats/dependency': both are
8
+ // optional in the manifest (only cluster mode needs them, D-0029), so they may be absent and
9
+ // cannot be imported statically (D-0063 §6; check-providers enforces it).
8
10
  const redis = providerDependency({
9
11
  name: 'dokebi-redis',
10
- version: '^0.1.0 || ^0.2.0',
12
+ version: '^0.4.0',
11
13
  packageName: '@dokebi/redis',
12
14
  load: () => import('@dokebi/redis'),
13
15
  });
14
16
  const nats = providerDependency({
15
17
  name: 'dokebi-nats',
16
- version: '^0.1.0',
18
+ version: '^0.4.0',
17
19
  packageName: '@dokebi/nats',
18
20
  load: () => import('@dokebi/nats'),
19
21
  });
@@ -24,23 +26,19 @@ class HubRuntime {
24
26
  }
25
27
  async setup(context) {
26
28
  const options = this.#options;
27
- // D-0057 removed these with client ACKs; an old dokebi.yaml still starts.
28
- for (const option of options.removedOptions)
29
- context.logger.log('warn', 'Hub option removed; ignored', {
30
- code: 'OPTION_REMOVED',
31
- option,
32
- fix: `Delete ${option} from the dokebi-websocket-hub settings (D-0057)`,
33
- });
29
+ // Options removed by D-0057 (client ACKs) are reported by core as warn OPTION_REMOVED, once
30
+ // per key at setup (the declaration's `removed` nodes): an old dokebi.yaml still starts.
34
31
  if (options.mode === 'local') {
35
32
  // Workers of node:cluster would each hold their own presence list, so a broadcast would
36
33
  // reach only the users of one worker (D-0029 §5).
37
- if (cluster.isWorker && !options.allowInCluster) {
34
+ const worker = context.runtime.role === 'worker';
35
+ if (worker && !options.allowInCluster) {
38
36
  context.logger.log('error', 'Local WebSocket hub in a cluster worker', {
39
37
  code: 'HUB_LOCAL_IN_CLUSTER',
40
38
  });
41
- throw new HubError('HUB_LOCAL_IN_CLUSTER');
39
+ throw new HubError('LOCAL_IN_CLUSTER');
42
40
  }
43
- const hub = new LocalHub(options, context.logger);
41
+ const hub = new LocalHub(options, context.logger, worker);
44
42
  context.defer(() => hub.close());
45
43
  context.logger.log('debug', 'Local WebSocket hub started', {
46
44
  maxConnections: options.maxConnections,
@@ -59,19 +57,17 @@ class HubRuntime {
59
57
  /** Factory input: `{ app, options? }`. Options default to `app.config['dokebi-websocket-hub']`. */
60
58
  export const createPlugin = definePlugin({
61
59
  name: 'dokebi-websocket-hub',
62
- version: '0.3.0',
63
- core: '^0.2.0',
64
- options: parseOptions,
60
+ version: '0.4.0',
61
+ core: '^0.4.0',
62
+ options: declaration,
65
63
  // local: nothing. cluster: Redis, and NATS only when natsConnection is set (D-0029).
66
64
  dependencies: ({ options }) => options.mode === 'local'
67
65
  ? []
68
66
  : [redis, ...(options.natsConnection === undefined ? [] : [nats])],
69
67
  instance: ({ options }) => new HubRuntime(options),
70
68
  });
71
- /** Use with `context.getDependency(dependency)`; a registered `dokebi-websocket-hub` instance is reused. */
72
- export const dependency = providerDependency({
73
- name: 'dokebi-websocket-hub',
74
- version: '^0.3.0',
75
- packageName: '@dokebi/websocket-hub',
76
- load: () => import('./index.js'),
77
- });
69
+ /**
70
+ * Use with `context.getDependency(dependency)`; a registered `dokebi-websocket-hub` instance is
71
+ * reused. Also `@dokebi/websocket-hub/dependency` (D-0063 §6), the same object.
72
+ */
73
+ export { dependency } from './dependency.js';
package/dist/leader.js CHANGED
@@ -1,9 +1,10 @@
1
1
  import { randomUUID, timingSafeEqual } from 'node:crypto';
2
- import { recipientKey, select } from './delivery.js';
3
- import { errorCode, errorText, LogThrottle } from './log.js';
4
- import { integer } from './options.js';
5
- import { encode, epoch, identifier, matches, PROTOCOL, payload, 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';
6
6
  import { HubError } from './types.js';
7
+ import { integer } from './values.js';
7
8
  import { Wire } from './wire.js';
8
9
  export class Leader {
9
10
  identity;
@@ -13,6 +14,8 @@ export class Leader {
13
14
  #peers = new Map();
14
15
  #sockets = new Set();
15
16
  #owners = new Map();
17
+ /** Every owner's connections by tenant, member and room (D-0068); follows #owners. */
18
+ #index = new HubIndex();
16
19
  #revision = 0;
17
20
  #tail = Promise.resolve();
18
21
  #pending = 0;
@@ -25,18 +28,18 @@ export class Leader {
25
28
  this.store = store;
26
29
  this.options = options;
27
30
  this.logger = logger;
28
- this.#throttle = new LogThrottle(logger);
31
+ this.#throttle = new diagnostics.Repeats({ logger });
29
32
  }
30
33
  /**
31
- * A frame to a peer could not be written (its socket is gone, its send queue passed queueBytes,
34
+ * A frame to a peer could not be written (its socket is gone, its send queue passed maxPendingBytes,
32
35
  * or this leader's lease lapsed): the peer is dropped and reconnects (D-0047: never silent).
33
36
  */
34
37
  #sendFailed(peer, frame, error) {
35
38
  // A leader that is stopping closes every peer itself; a reply that no longer fits is not a
36
39
  // 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, {
40
+ this.#throttle.log(this.#active ? 'error' : 'debug', 'Hub frame to a peer failed; peer dropped', 'PEER_SEND_FAILED', error, {
38
41
  frame,
39
- reason: errorCode(error, 'UNKNOWN'),
42
+ reason: diagnostics.errorCode(error, 'UNKNOWN'),
40
43
  owner: peer.owner ?? null,
41
44
  });
42
45
  peer.wire.close();
@@ -48,17 +51,17 @@ export class Leader {
48
51
  #refused(op, error) {
49
52
  if (error instanceof HubError && error.code !== 'STORE_UNAVAILABLE') {
50
53
  if (this.logger.isEnabled('debug'))
51
- this.#throttle.report('debug', 'Hub request refused', error.code, undefined, {
54
+ this.#throttle.log('debug', 'Hub request refused', error.code, undefined, {
52
55
  op: typeof op === 'string' ? op.slice(0, 16) : null,
53
56
  });
54
57
  return;
55
58
  }
56
- this.#throttle.report('error', 'Hub leader request failed', 'LEADER_REQUEST_FAILED', error, {
59
+ this.#throttle.log('error', 'Hub leader request failed', 'LEADER_REQUEST_FAILED', error, {
57
60
  op: typeof op === 'string' ? op.slice(0, 16) : null,
58
61
  });
59
62
  }
60
63
  #wireError(peer) {
61
- return (code, error) => this.#throttle.report('error', 'Hub peer connection failed', code, error, {
64
+ return (code, error) => this.#throttle.log('error', 'Hub peer connection failed', code, error, {
62
65
  owner: peer.owner ?? null,
63
66
  });
64
67
  }
@@ -70,6 +73,9 @@ export class Leader {
70
73
  await this.#renew();
71
74
  const snapshot = await this.store.snapshot(this.identity.epoch);
72
75
  this.#owners = snapshot.owners;
76
+ this.#index.clear();
77
+ for (const [ownerId, owner] of this.#owners)
78
+ this.#index.setOwner(ownerId, owner.connections);
73
79
  this.#revision = snapshot.revision;
74
80
  await this.#expire(snapshot.now);
75
81
  this.logger.log('debug', 'Hub leader started', {
@@ -90,7 +96,7 @@ export class Leader {
90
96
  }
91
97
  #queue(fn) {
92
98
  if (this.#pending >= this.options.maxPending) {
93
- this.#throttle.report('debug', 'Hub leader queue full; request refused', 'BUSY', undefined, {
99
+ this.#throttle.log('debug', 'Hub leader queue full; request refused', 'BUSY', undefined, {
94
100
  pending: this.#pending,
95
101
  });
96
102
  return Promise.reject(new HubError('BUSY'));
@@ -118,7 +124,7 @@ export class Leader {
118
124
  return;
119
125
  }
120
126
  const peer = {
121
- wire: new Wire(socket, this.options.maxFrameBytes, this.options.queueBytes, (frame) => {
127
+ wire: new Wire(socket, this.options.maxFrameBytes, this.options.maxPendingBytes, (frame) => {
122
128
  // Broadcasts never touch Redis and do not wait behind owner updates (D-0042): the
123
129
  // lease is checked against its local deadline.
124
130
  if (frame.op === 'broadcast') {
@@ -156,7 +162,7 @@ export class Leader {
156
162
  // Lease lost or Redis down: another server takes over and expires the owner.
157
163
  this.logger.log('error', 'Hub leader could not remove a disconnected server', {
158
164
  code: 'OWNER_REMOVE_FAILED',
159
- error: errorText(error),
165
+ error: diagnostics.describeError(error),
160
166
  owner: peer.owner ?? null,
161
167
  });
162
168
  return this.stop();
@@ -199,7 +205,7 @@ export class Leader {
199
205
  const filter = query(f.query);
200
206
  payload(f.data, this.options.maxPayloadBytes);
201
207
  const messageId = randomUUID();
202
- const selection = select([...this.#owners.values()].flatMap((value) => value.connections), filter);
208
+ const selection = this.#index.select(filter);
203
209
  let owners = 0;
204
210
  for (const [target, connections] of selection.owners) {
205
211
  const destination = this.#peers.get(target);
@@ -293,12 +299,14 @@ export class Leader {
293
299
  this.#revision = result[0];
294
300
  value.expires = result[1];
295
301
  this.#owners.set(ownerId, value);
302
+ this.#index.setOwner(ownerId, value.connections);
296
303
  this.#notify(ownerId, value.connections);
297
304
  }
298
305
  async #remove(ownerId, session) {
299
306
  const rev = Number(await this.store.run('remove', this.identity.epoch, '', session, ownerId));
300
307
  if (rev) {
301
308
  this.#owners.delete(ownerId);
309
+ this.#index.removeOwner(ownerId);
302
310
  this.#revision = rev;
303
311
  this.logger.log('debug', 'Hub server removed', { owner: ownerId, revision: rev });
304
312
  this.#notify(ownerId, []);
@@ -323,13 +331,13 @@ export class Leader {
323
331
  if (f.op === 'hello') {
324
332
  if (peer.owner)
325
333
  throw new HubError('ALREADY_REGISTERED');
326
- 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 ?? '');
327
335
  if (supplied.length !== expected.length || !timingSafeEqual(supplied, expected))
328
336
  throw new HubError('UNAUTHORIZED');
329
337
  if (f.protocol !== PROTOCOL) {
330
338
  // A server of another version (rolling restart): it retries and logs an error itself;
331
339
  // 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, {
340
+ this.#throttle.log('warn', 'Hub peer refused; protocol differs', 'PROTOCOL_MISMATCH', undefined, {
333
341
  protocol: PROTOCOL,
334
342
  peerProtocol: typeof f.protocol === 'number' ? f.protocol : null,
335
343
  serverId: typeof f.serverId === 'string' ? f.serverId.slice(0, 64) : null,
@@ -397,12 +405,7 @@ export class Leader {
397
405
  if (reason && Buffer.byteLength(reason) > 123)
398
406
  throw new HubError('INVALID_ARGUMENT');
399
407
  let kicked = 0;
400
- for (const [key, target] of this.#owners) {
401
- const selected = target.connections
402
- .filter((r) => matches(r, filter))
403
- .map((r) => r.connection);
404
- if (!selected.length)
405
- continue;
408
+ for (const [key, selected] of this.#index.select(filter).owners) {
406
409
  kicked += selected.length;
407
410
  const destination = this.#peers.get(key);
408
411
  if (!destination)
@@ -456,7 +459,7 @@ export class Leader {
456
459
  catch (error) {
457
460
  this.logger.log('debug', 'Hub leaving notice not sent', {
458
461
  owner: peer.owner,
459
- error: errorText(error),
462
+ error: diagnostics.describeError(error),
460
463
  });
461
464
  }
462
465
  peer.wire.close();
package/dist/local.d.ts CHANGED
@@ -11,10 +11,14 @@ export declare class LocalHub {
11
11
  readonly options: HubOptions;
12
12
  /** The plugin logger; the console default keeps failures visible. */
13
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
19
  /** The plugin logger; the console default keeps failures visible. */
18
- logger?: Logger);
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
  }
package/dist/local.js CHANGED
@@ -1,14 +1,13 @@
1
- import cluster from 'node:cluster';
2
1
  import { randomUUID } from 'node:crypto';
3
2
  import { ConsoleLogger } from '@dokebi/core';
4
- import { recipientKey, select } from './delivery.js';
3
+ import { diagnostics } from '@dokebi/core/libraries';
5
4
  import { EventQueue } from './event-queue.js';
6
- import { errorText, LogThrottle } from './log.js';
7
- import { identifier, matches, metadata, query, record } from './protocol.js';
5
+ import { HubIndex } from './hub-index.js';
6
+ import { identifier, metadata, query, record } from './protocol.js';
8
7
  import { hubStatus, LocalNonceStore } from './status.js';
9
8
  import { HubError, } from './types.js';
10
9
  /**
11
- * Share of the event queue (maxPending events, queueBytes) that broadcasts may fill before they
10
+ * Share of the event queue (maxPending events, maxPendingBytes) that broadcasts may fill before they
12
11
  * are refused with BUSY; the rest stays for presence and kick events, which cannot be refused.
13
12
  */
14
13
  const BROADCAST_SHARE = 0.5;
@@ -20,10 +19,13 @@ const BROADCAST_SHARE = 0.5;
20
19
  export class LocalHub {
21
20
  options;
22
21
  logger;
22
+ worker;
23
23
  api;
24
24
  ownerEpoch = randomUUID();
25
25
  #authority = randomUUID();
26
26
  #records = new Map();
27
+ /** The same records by tenant, member and room: selection without a scan (D-0068). */
28
+ #index = new HubIndex();
27
29
  #events;
28
30
  #revision = 0;
29
31
  #closed = false;
@@ -31,11 +33,14 @@ export class LocalHub {
31
33
  #throttle;
32
34
  constructor(options,
33
35
  /** The plugin logger; the console default keeps failures visible. */
34
- logger = new ConsoleLogger()) {
36
+ logger = new ConsoleLogger(),
37
+ /** This process is a node:cluster worker (`context.runtime.role`, D-0063 §4). */
38
+ worker = false) {
35
39
  this.options = options;
36
40
  this.logger = logger;
37
- this.#throttle = new LogThrottle(logger);
38
- this.#events = new EventQueue(options.maxPending, options.queueBytes);
41
+ this.worker = worker;
42
+ this.#throttle = new diagnostics.Repeats({ logger });
43
+ this.#events = new EventQueue(options.maxPending, options.maxPendingBytes);
39
44
  const self = this;
40
45
  const nonces = new LocalNonceStore();
41
46
  let warned = false;
@@ -59,7 +64,7 @@ export class LocalHub {
59
64
  nonces: () => {
60
65
  // A local hub in a node:cluster worker (allowInCluster) keeps nonces per worker: a frame
61
66
  // replayed to another worker passes. Say it once, where the defence is asked for.
62
- if (cluster.isWorker && !warned) {
67
+ if (this.worker && !warned) {
63
68
  warned = true;
64
69
  this.logger.log('warn', 'Replay nonces are per worker with a local hub', {
65
70
  code: 'HUB_NONCES_NOT_SHARED',
@@ -79,7 +84,7 @@ export class LocalHub {
79
84
  // reader (the websocket plugin) sees the error; the hub is closed from here on.
80
85
  this.logger.log('error', 'Local hub event queue overflowed; hub closed', {
81
86
  code: 'EVENT_OVERFLOW',
82
- error: errorText(error),
87
+ error: diagnostics.describeError(error),
83
88
  maxPending: this.options.maxPending,
84
89
  });
85
90
  this.#events.finish(error);
@@ -104,14 +109,13 @@ export class LocalHub {
104
109
  const value = record(input, this.ownerEpoch);
105
110
  if (this.#records.has(value.connection))
106
111
  throw new HubError('DUPLICATE_CONNECTION');
107
- const key = recipientKey(value);
108
- for (const existing of this.#records.values())
109
- if (recipientKey(existing) === key)
110
- throw new HubError('DUPLICATE_CLIENT');
112
+ if (this.#index.client(value))
113
+ throw new HubError('DUPLICATE_CLIENT');
111
114
  if (this.#records.size >= this.options.maxConnections ||
112
115
  this.#records.size >= this.options.maxTotalConnections)
113
116
  throw new HubError('CONNECTION_LIMIT');
114
117
  this.#records.set(value.connection, value);
118
+ this.#index.add(value);
115
119
  this.#changed();
116
120
  if (this.logger.isEnabled('debug'))
117
121
  this.logger.log('debug', 'Hub connection registered', {
@@ -125,6 +129,7 @@ export class LocalHub {
125
129
  throw new HubError('UNKNOWN_CONNECTION');
126
130
  const updated = next(current);
127
131
  this.#records.set(value.connection, updated);
132
+ this.#index.add(updated);
128
133
  this.#changed();
129
134
  if (this.logger.isEnabled('debug'))
130
135
  this.logger.log('debug', 'Hub connection changed', {
@@ -141,6 +146,9 @@ export class LocalHub {
141
146
  if (closed)
142
147
  return;
143
148
  closed = true;
149
+ const current = this.#records.get(value.connection);
150
+ if (current)
151
+ this.#index.remove(current);
144
152
  if (this.#records.delete(value.connection) && !this.#closed) {
145
153
  this.#changed();
146
154
  if (this.logger.isEnabled('debug'))
@@ -158,7 +166,7 @@ export class LocalHub {
158
166
  return Object.freeze({
159
167
  authorityEpoch: this.#authority,
160
168
  revision: this.#revision,
161
- connections: Object.freeze([...this.#records.values()].filter((r) => matches(r, filter))),
169
+ connections: Object.freeze([...this.#index.matching(filter)]),
162
170
  });
163
171
  }
164
172
  #broadcast(input, data) {
@@ -175,7 +183,7 @@ export class LocalHub {
175
183
  return Promise.reject(error);
176
184
  }
177
185
  const id = randomUUID();
178
- const { recipients, owners } = select(this.#records.values(), filter);
186
+ const { recipients, owners } = this.#index.select(filter);
179
187
  const connections = owners.get(this.ownerEpoch) ?? [];
180
188
  // The caller may reuse its buffer once this resolves; the gateway reads the event later.
181
189
  if (connections.length &&
@@ -186,7 +194,7 @@ export class LocalHub {
186
194
  data: Uint8Array.from(data),
187
195
  }, BROADCAST_SHARE)) {
188
196
  // The gateway has not taken the earlier messages yet: the caller backs off.
189
- this.#throttle.report('debug', 'Hub broadcast refused; event queue busy', 'BUSY', undefined, {
197
+ this.#throttle.log('debug', 'Hub broadcast refused; event queue busy', 'BUSY', undefined, {
190
198
  maxPending: this.options.maxPending,
191
199
  });
192
200
  return Promise.reject(new HubError('BUSY'));
@@ -208,9 +216,7 @@ export class LocalHub {
208
216
  if (Buffer.byteLength(identifier(reason)) > 123)
209
217
  throw new HubError('INVALID_ARGUMENT');
210
218
  const id = randomUUID();
211
- const connections = [...this.#records.values()]
212
- .filter((r) => matches(r, filter))
213
- .map((r) => r.connection);
219
+ const connections = Array.from(this.#index.matching(filter), (r) => r.connection);
214
220
  if (connections.length)
215
221
  this.#push({ kind: 'kick', id, connections: Object.freeze(connections), code, reason });
216
222
  this.logger.log('debug', 'Hub kick sent', { id, connections: connections.length, code });
package/dist/node.d.ts CHANGED
@@ -10,13 +10,13 @@ export declare class HubNode {
10
10
  readonly context: PluginContext;
11
11
  readonly options: HubOptions;
12
12
  readonly redis: RedisConnection;
13
- /** Optional (D-0029): without NATS, peers notice a new leader by Redis polling (pollMs). */
13
+ /** Optional (D-0029): without NATS, peers notice a new leader by Redis polling (pollIntervalMs). */
14
14
  readonly nats: NatsConnectionApi | undefined;
15
15
  readonly api: HubApi;
16
16
  readonly store: HubStore;
17
17
  readonly client: PeerClient;
18
18
  constructor(context: PluginContext, options: HubOptions, redis: RedisConnection,
19
- /** Optional (D-0029): without NATS, peers notice a new leader by Redis polling (pollMs). */
19
+ /** Optional (D-0029): without NATS, peers notice a new leader by Redis polling (pollIntervalMs). */
20
20
  nats: NatsConnectionApi | undefined);
21
21
  start(): Promise<void>;
22
22
  close(): Promise<void>;