@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.
- package/AI.md +96 -53
- package/README.md +69 -48
- package/dist/dependency.d.ts +4 -0
- package/dist/dependency.js +14 -0
- package/dist/event-queue.d.ts +6 -1
- package/dist/event-queue.js +9 -4
- package/dist/eviction.js +5 -5
- package/dist/hub-index.d.ts +29 -0
- package/dist/hub-index.js +146 -0
- package/dist/index.d.ts +5 -3
- package/dist/index.js +21 -25
- package/dist/leader.js +27 -24
- package/dist/local.d.ts +5 -1
- package/dist/local.js +80 -25
- package/dist/node.d.ts +2 -2
- package/dist/node.js +16 -16
- package/dist/options.d.ts +28 -33
- package/dist/options.js +106 -116
- package/dist/peer-client.js +13 -13
- package/dist/protocol.js +1 -1
- package/dist/status-cli.js +3 -3
- package/dist/status.d.ts +16 -4
- package/dist/status.js +112 -16
- package/dist/store.js +1 -1
- package/dist/types.d.ts +9 -4
- package/dist/types.js +22 -5
- package/dist/values.d.ts +4 -0
- package/dist/values.js +32 -0
- package/options.schema.json +105 -24
- package/package.json +35 -11
- package/dist/log.d.ts +0 -24
- package/dist/log.js +0 -101
|
@@ -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
|
-
/**
|
|
7
|
-
|
|
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
|
|
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 {
|
|
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.
|
|
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.
|
|
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
|
-
//
|
|
28
|
-
|
|
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
|
-
|
|
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('
|
|
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.
|
|
63
|
-
core: '^0.
|
|
64
|
-
options:
|
|
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
|
-
/**
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
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 {
|
|
3
|
-
import {
|
|
4
|
-
import {
|
|
5
|
-
import { encode, epoch, identifier,
|
|
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
|
|
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
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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:
|
|
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 =
|
|
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.
|
|
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,
|
|
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:
|
|
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 {
|
|
3
|
+
import { diagnostics } from '@dokebi/core/libraries';
|
|
5
4
|
import { EventQueue } from './event-queue.js';
|
|
6
|
-
import {
|
|
7
|
-
import { identifier,
|
|
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,
|
|
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
|
|
38
|
-
this.#
|
|
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 (
|
|
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:
|
|
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
|
|
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
|
-
|
|
108
|
-
|
|
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.#
|
|
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
|
-
|
|
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.
|
|
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 =
|
|
212
|
-
|
|
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 (
|
|
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 (
|
|
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>;
|