@dokebi/websocket-hub 0.3.0 → 0.4.1

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.1',
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,17 +1,22 @@
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;
14
+ /** The JSON of a presence event around its connections: kind, revision, ownerEpoch, brackets. */
15
+ const PRESENCE_ENVELOPE_BYTES = 96;
16
+ /** The JSON size of one record, as the event queue's own sizing would count it. */
17
+ function recordBytes(record) {
18
+ return Buffer.byteLength(JSON.stringify(record));
19
+ }
15
20
  /**
16
21
  * The hub of one process (D-0029, `mode: 'local'`): the same HubApi as the cluster hub, kept in
17
22
  * memory. A broadcast is handed to the event queue the websocket gateway reads and resolves at
@@ -20,24 +25,38 @@ const BROADCAST_SHARE = 0.5;
20
25
  export class LocalHub {
21
26
  options;
22
27
  logger;
28
+ worker;
23
29
  api;
24
30
  ownerEpoch = randomUUID();
25
31
  #authority = randomUUID();
26
32
  #records = new Map();
33
+ /** The same records by tenant, member and room: selection without a scan (D-0068). */
34
+ #index = new HubIndex();
27
35
  #events;
28
36
  #revision = 0;
29
37
  #closed = false;
38
+ /**
39
+ * JSON bytes of every record, kept as records come, change and go: the size of a presence
40
+ * event without serializing the roster on every change (review PERF-B).
41
+ */
42
+ #rosterBytes = 0;
43
+ #sizes = new WeakMap();
44
+ /** A presence event is due at the end of this tick (changes of one tick share one event). */
45
+ #presenceDue = false;
30
46
  /** Decisions on per-message paths (refusals), once per interval with a count. */
31
47
  #throttle;
32
48
  constructor(options,
33
49
  /** The plugin logger; the console default keeps failures visible. */
34
- logger = new ConsoleLogger()) {
50
+ logger = new ConsoleLogger(),
51
+ /** This process is a node:cluster worker (`context.runtime.role`, D-0063 §4). */
52
+ worker = false) {
35
53
  this.options = options;
36
54
  this.logger = logger;
37
- this.#throttle = new LogThrottle(logger);
38
- this.#events = new EventQueue(options.maxPending, options.queueBytes);
55
+ this.worker = worker;
56
+ this.#throttle = new diagnostics.Repeats({ logger });
57
+ this.#events = new EventQueue(options.maxPending, options.maxPendingBytes);
39
58
  const self = this;
40
- const nonces = new LocalNonceStore();
59
+ const nonces = new LocalNonceStore({ logger });
41
60
  let warned = false;
42
61
  this.api = Object.freeze({
43
62
  get state() {
@@ -59,7 +78,7 @@ export class LocalHub {
59
78
  nonces: () => {
60
79
  // A local hub in a node:cluster worker (allowInCluster) keeps nonces per worker: a frame
61
80
  // replayed to another worker passes. Say it once, where the defence is asked for.
62
- if (cluster.isWorker && !warned) {
81
+ if (this.worker && !warned) {
63
82
  warned = true;
64
83
  this.logger.log('warn', 'Replay nonces are per worker with a local hub', {
65
84
  code: 'HUB_NONCES_NOT_SHARED',
@@ -70,30 +89,57 @@ export class LocalHub {
70
89
  },
71
90
  });
72
91
  }
73
- #push(event) {
92
+ #push(event, bytes) {
74
93
  try {
75
- this.#events.push(event);
94
+ this.#events.push(event, bytes);
76
95
  }
77
96
  catch (error) {
78
97
  // The consumer fell too far behind: end the stream like the cluster client does. Its
79
98
  // reader (the websocket plugin) sees the error; the hub is closed from here on.
80
99
  this.logger.log('error', 'Local hub event queue overflowed; hub closed', {
81
100
  code: 'EVENT_OVERFLOW',
82
- error: errorText(error),
101
+ error: diagnostics.describeError(error),
83
102
  maxPending: this.options.maxPending,
84
103
  });
85
104
  this.#events.finish(error);
86
105
  this.#closed = true;
87
106
  }
88
107
  }
108
+ #track(record) {
109
+ const bytes = recordBytes(record);
110
+ this.#sizes.set(record, bytes);
111
+ this.#rosterBytes += bytes;
112
+ }
113
+ #untrack(record) {
114
+ this.#rosterBytes -= this.#sizes.get(record) ?? 0;
115
+ this.#sizes.delete(record);
116
+ }
117
+ /**
118
+ * One more revision. Its presence event (the whole roster, like every hub's) goes out at the
119
+ * end of the tick, so changes of one tick (a burst of reconnects) share one event and one copy
120
+ * of the roster, like the cluster client's group commit; a broadcast or kick flushes it first,
121
+ * so events keep the order of the calls.
122
+ */
89
123
  #changed() {
90
124
  this.#revision++;
125
+ if (this.#presenceDue)
126
+ return;
127
+ this.#presenceDue = true;
128
+ queueMicrotask(() => this.#flushPresence());
129
+ }
130
+ #flushPresence() {
131
+ if (!this.#presenceDue)
132
+ return;
133
+ this.#presenceDue = false;
134
+ if (this.#closed)
135
+ return;
136
+ const connections = Object.freeze([...this.#records.values()]);
91
137
  this.#push({
92
138
  kind: 'presence',
93
139
  revision: this.#revision,
94
140
  ownerEpoch: this.ownerEpoch,
95
- connections: Object.freeze([...this.#records.values()]),
96
- });
141
+ connections,
142
+ }, PRESENCE_ENVELOPE_BYTES + this.#rosterBytes + connections.length);
97
143
  }
98
144
  #ensureOpen() {
99
145
  if (this.#closed)
@@ -104,14 +150,14 @@ export class LocalHub {
104
150
  const value = record(input, this.ownerEpoch);
105
151
  if (this.#records.has(value.connection))
106
152
  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');
153
+ if (this.#index.client(value))
154
+ throw new HubError('DUPLICATE_CLIENT');
111
155
  if (this.#records.size >= this.options.maxConnections ||
112
156
  this.#records.size >= this.options.maxTotalConnections)
113
157
  throw new HubError('CONNECTION_LIMIT');
114
158
  this.#records.set(value.connection, value);
159
+ this.#index.add(value);
160
+ this.#track(value);
115
161
  this.#changed();
116
162
  if (this.logger.isEnabled('debug'))
117
163
  this.logger.log('debug', 'Hub connection registered', {
@@ -125,6 +171,9 @@ export class LocalHub {
125
171
  throw new HubError('UNKNOWN_CONNECTION');
126
172
  const updated = next(current);
127
173
  this.#records.set(value.connection, updated);
174
+ this.#index.add(updated);
175
+ this.#untrack(current);
176
+ this.#track(updated);
128
177
  this.#changed();
129
178
  if (this.logger.isEnabled('debug'))
130
179
  this.logger.log('debug', 'Hub connection changed', {
@@ -141,6 +190,11 @@ export class LocalHub {
141
190
  if (closed)
142
191
  return;
143
192
  closed = true;
193
+ const current = this.#records.get(value.connection);
194
+ if (current) {
195
+ this.#index.remove(current);
196
+ this.#untrack(current);
197
+ }
144
198
  if (this.#records.delete(value.connection) && !this.#closed) {
145
199
  this.#changed();
146
200
  if (this.logger.isEnabled('debug'))
@@ -158,7 +212,7 @@ export class LocalHub {
158
212
  return Object.freeze({
159
213
  authorityEpoch: this.#authority,
160
214
  revision: this.#revision,
161
- connections: Object.freeze([...this.#records.values()].filter((r) => matches(r, filter))),
215
+ connections: Object.freeze([...this.#index.matching(filter)]),
162
216
  });
163
217
  }
164
218
  #broadcast(input, data) {
@@ -175,7 +229,9 @@ export class LocalHub {
175
229
  return Promise.reject(error);
176
230
  }
177
231
  const id = randomUUID();
178
- const { recipients, owners } = select(this.#records.values(), filter);
232
+ // Presence changes made before this call reach the gateway before this message.
233
+ this.#flushPresence();
234
+ const { recipients, owners } = this.#index.select(filter);
179
235
  const connections = owners.get(this.ownerEpoch) ?? [];
180
236
  // The caller may reuse its buffer once this resolves; the gateway reads the event later.
181
237
  if (connections.length &&
@@ -186,7 +242,7 @@ export class LocalHub {
186
242
  data: Uint8Array.from(data),
187
243
  }, BROADCAST_SHARE)) {
188
244
  // 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, {
245
+ this.#throttle.log('debug', 'Hub broadcast refused; event queue busy', 'BUSY', undefined, {
190
246
  maxPending: this.options.maxPending,
191
247
  });
192
248
  return Promise.reject(new HubError('BUSY'));
@@ -208,9 +264,8 @@ export class LocalHub {
208
264
  if (Buffer.byteLength(identifier(reason)) > 123)
209
265
  throw new HubError('INVALID_ARGUMENT');
210
266
  const id = randomUUID();
211
- const connections = [...this.#records.values()]
212
- .filter((r) => matches(r, filter))
213
- .map((r) => r.connection);
267
+ const connections = Array.from(this.#index.matching(filter), (r) => r.connection);
268
+ this.#flushPresence();
214
269
  if (connections.length)
215
270
  this.#push({ kind: 'kick', id, connections: Object.freeze(connections), code, reason });
216
271
  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>;