@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.
- package/AI.md +96 -49
- package/README.md +71 -43
- package/dist/delivery.d.ts +13 -47
- package/dist/delivery.js +19 -177
- package/dist/dependency.d.ts +4 -0
- package/dist/dependency.js +14 -0
- package/dist/event-queue.d.ts +6 -0
- package/dist/event-queue.js +21 -3
- package/dist/eviction.d.ts +9 -0
- package/dist/eviction.js +57 -0
- 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 +25 -18
- package/dist/leader.d.ts +3 -1
- package/dist/leader.js +215 -76
- package/dist/local.d.ts +11 -7
- package/dist/local.js +94 -107
- package/dist/node.d.ts +2 -2
- package/dist/node.js +83 -21
- package/dist/options.d.ts +32 -34
- package/dist/options.js +115 -120
- package/dist/peer-client.d.ts +13 -4
- package/dist/peer-client.js +290 -172
- package/dist/protocol.d.ts +6 -0
- package/dist/protocol.js +7 -1
- package/dist/status-cli.js +7 -2
- package/dist/store.js +12 -7
- package/dist/types.d.ts +25 -8
- package/dist/types.js +22 -5
- package/dist/values.d.ts +4 -0
- package/dist/values.js +32 -0
- package/dist/wire.d.ts +8 -1
- package/dist/wire.js +14 -3
- package/options.schema.json +113 -36
- package/package.json +35 -11
package/dist/delivery.js
CHANGED
|
@@ -1,8 +1,10 @@
|
|
|
1
1
|
import { createHash } from 'node:crypto';
|
|
2
|
-
import {
|
|
3
|
-
import { array, epoch, matches, payload, query, sequence } from './protocol.js';
|
|
4
|
-
import { HubError } from './types.js';
|
|
2
|
+
import { matches } from './protocol.js';
|
|
5
3
|
const recipientKeys = new WeakMap();
|
|
4
|
+
/**
|
|
5
|
+
* The identity of a connection in a broadcast receipt: SHA-256 (base64url) of tenant, member and
|
|
6
|
+
* clientId, or of the owner and connection when the client has no clientId.
|
|
7
|
+
*/
|
|
6
8
|
export function recipientKey(record) {
|
|
7
9
|
const cached = recipientKeys.get(record);
|
|
8
10
|
if (cached)
|
|
@@ -15,182 +17,22 @@ export function recipientKey(record) {
|
|
|
15
17
|
recipientKeys.set(record, key);
|
|
16
18
|
return key;
|
|
17
19
|
}
|
|
18
|
-
const RECIPIENT = /^[A-Za-z0-9_-]{43}$/;
|
|
19
|
-
/** Remembered bytes of one broadcast besides its payload: ids, digest and bookkeeping. */
|
|
20
|
-
const OVERHEAD = 256;
|
|
21
|
-
/** A pending broadcast holds its recipient keys in a list and a set of those still missing. */
|
|
22
|
-
const PER_RECIPIENT = 48;
|
|
23
|
-
/**
|
|
24
|
-
* A finished broadcast keeps only the list, whose keys are the strings already cached for the
|
|
25
|
-
* connection records (recipientKey): about a pointer each.
|
|
26
|
-
*/
|
|
27
|
-
const PER_FINISHED_RECIPIENT = 8;
|
|
28
20
|
/**
|
|
29
|
-
*
|
|
30
|
-
*
|
|
31
|
-
* written to Redis: when the leader dies, each producer resends its unfinished broadcasts with
|
|
32
|
-
* the same id and the recipient list this leader announced (`accepted`), and the next leader
|
|
33
|
-
* carries on from there. Finished broadcasts keep a small record (no payload) until their
|
|
34
|
-
* deadline so a resent id is answered with its result instead of being delivered again.
|
|
21
|
+
* The recipients of a broadcast (D-0057): the connections that match `filter` now. Nothing is
|
|
22
|
+
* remembered; a connection that comes later, or leaves before its frame is written, misses it.
|
|
35
23
|
*/
|
|
36
|
-
export
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
this.options = options;
|
|
46
|
-
this.connections = connections;
|
|
47
|
-
this.send = send;
|
|
48
|
-
}
|
|
49
|
-
/** Bytes the outbox holds now (payloads and recipient lists), bounded by deliveryBytes. */
|
|
50
|
-
get bytes() {
|
|
51
|
-
return this.#bytes;
|
|
52
|
-
}
|
|
53
|
-
/**
|
|
54
|
-
* Takes a broadcast from `producer`. `accepted` is told the recipient list once, so the
|
|
55
|
-
* producer can resend it to the next leader; `reply` is told the result.
|
|
56
|
-
*/
|
|
57
|
-
accept(producer, frame, reply, accepted = () => { }) {
|
|
58
|
-
const id = epoch(frame.messageId), filter = query(frame.query);
|
|
59
|
-
payload(frame.data, this.options.maxPayloadBytes);
|
|
60
|
-
const expiresAt = sequence(frame.expiresAt), now = Date.now();
|
|
61
|
-
if (expiresAt <= now || expiresAt > now + this.options.deliveryTimeoutMs + 5000)
|
|
62
|
-
throw new HubError('DELIVERY_TIMEOUT');
|
|
63
|
-
const data = String(frame.data);
|
|
64
|
-
const digest = createHash('sha256')
|
|
65
|
-
.update(JSON.stringify([filter, data, expiresAt]))
|
|
66
|
-
.digest('hex');
|
|
67
|
-
const done = this.finished.get(id);
|
|
68
|
-
if (done) {
|
|
69
|
-
if (done.digest !== digest || done.producer !== producer)
|
|
70
|
-
throw new HubError('ID_CONFLICT');
|
|
71
|
-
reply(done.ok, done.recipients);
|
|
72
|
-
return;
|
|
73
|
-
}
|
|
74
|
-
let value = this.pending.get(id);
|
|
75
|
-
if (value) {
|
|
76
|
-
if (value.digest !== digest || value.producer !== producer)
|
|
77
|
-
throw new HubError('ID_CONFLICT');
|
|
78
|
-
}
|
|
79
|
-
else {
|
|
80
|
-
const recipients = frame.recipients === undefined
|
|
81
|
-
? [
|
|
82
|
-
...new Set(this.connections()
|
|
83
|
-
.filter((r) => matches(r, filter))
|
|
84
|
-
.map(recipientKey)),
|
|
85
|
-
]
|
|
86
|
-
: this.#recipients(frame.recipients);
|
|
87
|
-
const bytes = Buffer.byteLength(data) + recipients.length * PER_RECIPIENT + OVERHEAD;
|
|
88
|
-
if (this.pending.size + this.finished.size >= this.options.maxDeliveries ||
|
|
89
|
-
this.#bytes + bytes > this.options.deliveryBytes)
|
|
90
|
-
throw new HubError('OUTBOX_FULL');
|
|
91
|
-
value = {
|
|
92
|
-
id,
|
|
93
|
-
producer,
|
|
94
|
-
digest,
|
|
95
|
-
data,
|
|
96
|
-
expiresAt,
|
|
97
|
-
recipients: Object.freeze(recipients),
|
|
98
|
-
remaining: new Set(recipients),
|
|
99
|
-
bytes,
|
|
100
|
-
lastSent: 0,
|
|
101
|
-
};
|
|
102
|
-
this.pending.set(id, value);
|
|
103
|
-
this.#bytes += bytes;
|
|
104
|
-
}
|
|
105
|
-
const waiters = this.waiters.get(id) ?? new Map();
|
|
106
|
-
waiters.set(producer, reply);
|
|
107
|
-
this.waiters.set(id, waiters);
|
|
108
|
-
accepted(value.recipients);
|
|
109
|
-
if (!value.remaining.size)
|
|
110
|
-
this.#finish(value, true);
|
|
111
|
-
else
|
|
112
|
-
this.#transmit(value, this.connections());
|
|
113
|
-
}
|
|
114
|
-
/** A recipient list resent by a producer after a leader change: well-formed keys only. */
|
|
115
|
-
#recipients(input) {
|
|
116
|
-
const recipients = array(input, this.options.maxTotalConnections);
|
|
117
|
-
if (new Set(recipients).size !== recipients.length ||
|
|
118
|
-
recipients.some((key) => typeof key !== 'string' || !RECIPIENT.test(key)))
|
|
119
|
-
throw new HubError('INVALID_ARGUMENT');
|
|
120
|
-
return recipients;
|
|
121
|
-
}
|
|
122
|
-
#transmit(value, records) {
|
|
123
|
-
const now = Date.now();
|
|
124
|
-
if (now >= value.expiresAt || now - value.lastSent < this.options.retryMs)
|
|
125
|
-
return;
|
|
126
|
-
value.lastSent = now;
|
|
127
|
-
const targets = new Map();
|
|
128
|
-
for (const record of records) {
|
|
129
|
-
if (!value.remaining.has(recipientKey(record)))
|
|
130
|
-
continue;
|
|
131
|
-
const connections = targets.get(record.ownerEpoch) ?? [];
|
|
24
|
+
export function select(records, filter) {
|
|
25
|
+
const recipients = new Set();
|
|
26
|
+
const owners = new Map();
|
|
27
|
+
for (const record of records) {
|
|
28
|
+
if (!matches(record, filter))
|
|
29
|
+
continue;
|
|
30
|
+
recipients.add(recipientKey(record));
|
|
31
|
+
const connections = owners.get(record.ownerEpoch);
|
|
32
|
+
if (connections)
|
|
132
33
|
connections.push(record.connection);
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
for (const [owner, connections] of targets)
|
|
136
|
-
this.send(owner, {
|
|
137
|
-
kind: 'message',
|
|
138
|
-
id: value.id,
|
|
139
|
-
data: value.data,
|
|
140
|
-
expiresAt: value.expiresAt,
|
|
141
|
-
connections,
|
|
142
|
-
});
|
|
143
|
-
}
|
|
144
|
-
acknowledge(input, records) {
|
|
145
|
-
const identities = new Map(records.map((r) => [r.connection, recipientKey(r)]));
|
|
146
|
-
const completed = new Set();
|
|
147
|
-
for (const raw of array(input, 256)) {
|
|
148
|
-
const ack = object(raw), delivery = this.pending.get(epoch(ack.id));
|
|
149
|
-
if (!delivery)
|
|
150
|
-
continue;
|
|
151
|
-
for (const connection of array(ack.connections, this.options.maxConnections)) {
|
|
152
|
-
const recipient = identities.get(String(connection));
|
|
153
|
-
if (recipient)
|
|
154
|
-
delivery.remaining.delete(recipient);
|
|
155
|
-
}
|
|
156
|
-
if (!delivery.remaining.size)
|
|
157
|
-
completed.add(delivery);
|
|
158
|
-
}
|
|
159
|
-
for (const delivery of completed)
|
|
160
|
-
this.#finish(delivery, Date.now() < delivery.expiresAt);
|
|
161
|
-
}
|
|
162
|
-
#finish(value, ok) {
|
|
163
|
-
this.pending.delete(value.id);
|
|
164
|
-
this.#bytes -= value.bytes;
|
|
165
|
-
// The payload is dropped; the result stays until the deadline for producers that resend.
|
|
166
|
-
const bytes = value.recipients.length * PER_FINISHED_RECIPIENT + OVERHEAD;
|
|
167
|
-
this.finished.set(value.id, {
|
|
168
|
-
producer: value.producer,
|
|
169
|
-
digest: value.digest,
|
|
170
|
-
ok,
|
|
171
|
-
recipients: value.recipients,
|
|
172
|
-
expiresAt: value.expiresAt,
|
|
173
|
-
bytes,
|
|
174
|
-
});
|
|
175
|
-
this.#bytes += bytes;
|
|
176
|
-
const waiters = this.waiters.get(value.id);
|
|
177
|
-
this.waiters.delete(value.id);
|
|
178
|
-
for (const reply of waiters?.values() ?? [])
|
|
179
|
-
reply(ok, value.recipients);
|
|
180
|
-
}
|
|
181
|
-
tick() {
|
|
182
|
-
const records = this.connections(), now = Date.now();
|
|
183
|
-
for (const value of this.pending.values()) {
|
|
184
|
-
if (now >= value.expiresAt)
|
|
185
|
-
this.#finish(value, false);
|
|
186
|
-
else
|
|
187
|
-
this.#transmit(value, records);
|
|
188
|
-
}
|
|
189
|
-
// Producers stop resending at the deadline; keep results a little longer for late replies.
|
|
190
|
-
for (const [id, done] of this.finished)
|
|
191
|
-
if (done.expiresAt + 5000 < now) {
|
|
192
|
-
this.finished.delete(id);
|
|
193
|
-
this.#bytes -= done.bytes;
|
|
194
|
-
}
|
|
34
|
+
else
|
|
35
|
+
owners.set(record.ownerEpoch, [record.connection]);
|
|
195
36
|
}
|
|
37
|
+
return { recipients: [...recipients], owners };
|
|
196
38
|
}
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
import type { HubApi } from './types.js';
|
|
2
|
+
export declare const provider: import("@dokebi/core").ProviderDescriptor<HubApi>;
|
|
3
|
+
/** Required: created from @dokebi/websocket-hub when no `dokebi-websocket-hub` plugin is registered. */
|
|
4
|
+
export declare const dependency: import("@dokebi/core").PluginDependency<HubApi>;
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import { defineProvider } from '@dokebi/core';
|
|
2
|
+
/*
|
|
3
|
+
* The one place dokebi-websocket-hub states its name, package and range (D-0063 §6). Plugins and
|
|
4
|
+
* user code that always install @dokebi/websocket-hub import `dependency` from
|
|
5
|
+
* '@dokebi/websocket-hub/dependency' (a small module: it does not load the hub, Redis or NATS).
|
|
6
|
+
*/
|
|
7
|
+
export const provider = defineProvider({
|
|
8
|
+
name: 'dokebi-websocket-hub',
|
|
9
|
+
version: '^0.4.0',
|
|
10
|
+
packageName: '@dokebi/websocket-hub',
|
|
11
|
+
load: () => import('./index.js'),
|
|
12
|
+
});
|
|
13
|
+
/** Required: created from @dokebi/websocket-hub when no `dokebi-websocket-hub` plugin is registered. */
|
|
14
|
+
export const dependency = provider.dependency;
|
package/dist/event-queue.d.ts
CHANGED
|
@@ -5,6 +5,12 @@ export declare class EventQueue implements AsyncIterableIterator<HubEvent> {
|
|
|
5
5
|
readonly maxBytes: number;
|
|
6
6
|
constructor(capacity: number, maxBytes: number);
|
|
7
7
|
[Symbol.asyncIterator](): this;
|
|
8
|
+
/**
|
|
9
|
+
* Pushes `value` unless the queue already holds `share` of its capacity or bytes; false when
|
|
10
|
+
* refused. A waiting reader always takes it. Lets a producer back off (BUSY) and leaves the
|
|
11
|
+
* rest of the queue to events that cannot be refused (presence).
|
|
12
|
+
*/
|
|
13
|
+
offer(value: HubEvent, share: number): boolean;
|
|
8
14
|
push(value: HubEvent): void;
|
|
9
15
|
next(): Promise<IteratorResult<HubEvent>>;
|
|
10
16
|
finish(error?: unknown): void;
|
package/dist/event-queue.js
CHANGED
|
@@ -14,12 +14,30 @@ export class EventQueue {
|
|
|
14
14
|
[Symbol.asyncIterator]() {
|
|
15
15
|
return this;
|
|
16
16
|
}
|
|
17
|
+
#size(value) {
|
|
18
|
+
return value.kind === 'message'
|
|
19
|
+
? value.data.byteLength + value.connections.join('').length
|
|
20
|
+
: Buffer.byteLength(JSON.stringify(value));
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Pushes `value` unless the queue already holds `share` of its capacity or bytes; false when
|
|
24
|
+
* refused. A waiting reader always takes it. Lets a producer back off (BUSY) and leaves the
|
|
25
|
+
* rest of the queue to events that cannot be refused (presence).
|
|
26
|
+
*/
|
|
27
|
+
offer(value, share) {
|
|
28
|
+
if (this.#ended)
|
|
29
|
+
return false;
|
|
30
|
+
if (!this.#waiter &&
|
|
31
|
+
(this.#values.length >= Math.ceil(this.capacity * share) ||
|
|
32
|
+
this.#bytes + this.#size(value) > this.maxBytes * share))
|
|
33
|
+
return false;
|
|
34
|
+
this.push(value);
|
|
35
|
+
return true;
|
|
36
|
+
}
|
|
17
37
|
push(value) {
|
|
18
38
|
if (this.#ended)
|
|
19
39
|
return;
|
|
20
|
-
const bytes = value
|
|
21
|
-
? value.data.byteLength + value.connections.join('').length
|
|
22
|
-
: Buffer.byteLength(JSON.stringify(value));
|
|
40
|
+
const bytes = this.#size(value);
|
|
23
41
|
if (this.#waiter) {
|
|
24
42
|
const w = this.#waiter;
|
|
25
43
|
this.#waiter = undefined;
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import type { Logger } from '@dokebi/core';
|
|
2
|
+
import type { RedisConnection } from '@dokebi/redis';
|
|
3
|
+
/**
|
|
4
|
+
* D-0049: a Redis that evicts keys under maxmemory deletes the hub's leader and owner keys, and
|
|
5
|
+
* the cluster falls into STALE_LEADER/RECOVERING. Read once when a cluster node starts; warns
|
|
6
|
+
* (error, `REDIS_EVICTION_UNSAFE`) and never refuses to start — operators may accept the risk.
|
|
7
|
+
* Never rejects: every outcome is a log entry.
|
|
8
|
+
*/
|
|
9
|
+
export declare function checkEviction(redis: RedisConnection, logger: Logger): Promise<void>;
|
package/dist/eviction.js
ADDED
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
import { diagnostics } from '@dokebi/core/libraries';
|
|
2
|
+
function rejected(error) {
|
|
3
|
+
if (error === null || typeof error !== 'object')
|
|
4
|
+
return false;
|
|
5
|
+
const { plugin, code } = error;
|
|
6
|
+
return plugin === 'dokebi-redis' && code === 'COMMAND_REJECTED';
|
|
7
|
+
}
|
|
8
|
+
/**
|
|
9
|
+
* D-0049: a Redis that evicts keys under maxmemory deletes the hub's leader and owner keys, and
|
|
10
|
+
* the cluster falls into STALE_LEADER/RECOVERING. Read once when a cluster node starts; warns
|
|
11
|
+
* (error, `REDIS_EVICTION_UNSAFE`) and never refuses to start — operators may accept the risk.
|
|
12
|
+
* Never rejects: every outcome is a log entry.
|
|
13
|
+
*/
|
|
14
|
+
export async function checkEviction(redis, logger) {
|
|
15
|
+
const fields = { connection: redis.name };
|
|
16
|
+
if (typeof redis.memoryPolicy !== 'function') {
|
|
17
|
+
logger.log('debug', 'Redis eviction check skipped', {
|
|
18
|
+
code: 'REDIS_EVICTION_CHECK_SKIPPED',
|
|
19
|
+
...fields,
|
|
20
|
+
reason: 'unsupported',
|
|
21
|
+
});
|
|
22
|
+
return;
|
|
23
|
+
}
|
|
24
|
+
try {
|
|
25
|
+
const memory = await redis.memoryPolicy();
|
|
26
|
+
if (memory.evicts)
|
|
27
|
+
logger.log('error', 'Redis evicts keys at maxmemory; the WebSocket hub needs maxmemory-policy noeviction (its leader key can be evicted)', {
|
|
28
|
+
code: 'REDIS_EVICTION_UNSAFE',
|
|
29
|
+
...fields,
|
|
30
|
+
policy: memory.policy,
|
|
31
|
+
maxmemory: memory.maxmemory,
|
|
32
|
+
});
|
|
33
|
+
else
|
|
34
|
+
logger.log('debug', 'Redis eviction policy checked', {
|
|
35
|
+
code: 'REDIS_EVICTION_CHECKED',
|
|
36
|
+
...fields,
|
|
37
|
+
policy: memory.policy,
|
|
38
|
+
maxmemory: memory.maxmemory,
|
|
39
|
+
});
|
|
40
|
+
}
|
|
41
|
+
catch (error) {
|
|
42
|
+
// CONFIG refused (managed Redis, ACL): the check is skipped, the full reply says why.
|
|
43
|
+
if (rejected(error))
|
|
44
|
+
logger.log('debug', 'Redis eviction check skipped', {
|
|
45
|
+
code: 'REDIS_EVICTION_CHECK_SKIPPED',
|
|
46
|
+
...fields,
|
|
47
|
+
reason: 'rejected',
|
|
48
|
+
error: diagnostics.describeError(error),
|
|
49
|
+
});
|
|
50
|
+
else
|
|
51
|
+
logger.log('error', 'Redis eviction check failed', {
|
|
52
|
+
code: 'REDIS_EVICTION_CHECK_FAILED',
|
|
53
|
+
...fields,
|
|
54
|
+
error: diagnostics.describeError(error),
|
|
55
|
+
});
|
|
56
|
+
}
|
|
57
|
+
}
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import { type Selection } from './delivery.js';
|
|
2
|
+
import type { HubQuery, HubRecord } from './types.js';
|
|
3
|
+
/**
|
|
4
|
+
* The hub's connections indexed for selection (D-0068): tenant → member → connections, tenant →
|
|
5
|
+
* room → connections, and owner → connection → record. A targeted send (member, connection)
|
|
6
|
+
* costs O(1) plus its recipients and a room or tenant broadcast O(recipients), instead of a scan
|
|
7
|
+
* of every connection. Every candidate is still checked with `matches`, so the answer is the
|
|
8
|
+
* same as filtering all records (D-0057).
|
|
9
|
+
*/
|
|
10
|
+
export declare class HubIndex {
|
|
11
|
+
#private;
|
|
12
|
+
get size(): number;
|
|
13
|
+
/** The record of a connection, or undefined. */
|
|
14
|
+
get(ownerEpoch: string, connection: string): HubRecord | undefined;
|
|
15
|
+
/** The record already registered under the same recipient identity, if any. */
|
|
16
|
+
client(record: HubRecord): HubRecord | undefined;
|
|
17
|
+
/** Adds a record; a record of the same owner and connection is replaced. */
|
|
18
|
+
add(record: HubRecord): void;
|
|
19
|
+
/** Removes a record (by identity); false when it is not indexed. */
|
|
20
|
+
remove(record: HubRecord): boolean;
|
|
21
|
+
/** Replaces every record of one owner (a cluster server's full list). */
|
|
22
|
+
setOwner(ownerEpoch: string, records: readonly HubRecord[]): void;
|
|
23
|
+
removeOwner(ownerEpoch: string): void;
|
|
24
|
+
clear(): void;
|
|
25
|
+
/** The records that match `filter`, in the order they were indexed. */
|
|
26
|
+
matching(filter: HubQuery): Generator<HubRecord>;
|
|
27
|
+
/** What `select` of delivery.ts returns for all indexed records, without the scan. */
|
|
28
|
+
select(filter: HubQuery): Selection;
|
|
29
|
+
}
|
|
@@ -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,17 +26,24 @@ class HubRuntime {
|
|
|
24
26
|
}
|
|
25
27
|
async setup(context) {
|
|
26
28
|
const options = this.#options;
|
|
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.
|
|
27
31
|
if (options.mode === 'local') {
|
|
28
32
|
// Workers of node:cluster would each hold their own presence list, so a broadcast would
|
|
29
33
|
// reach only the users of one worker (D-0029 §5).
|
|
30
|
-
|
|
34
|
+
const worker = context.runtime.role === 'worker';
|
|
35
|
+
if (worker && !options.allowInCluster) {
|
|
31
36
|
context.logger.log('error', 'Local WebSocket hub in a cluster worker', {
|
|
32
37
|
code: 'HUB_LOCAL_IN_CLUSTER',
|
|
33
38
|
});
|
|
34
|
-
throw new HubError('
|
|
39
|
+
throw new HubError('LOCAL_IN_CLUSTER');
|
|
35
40
|
}
|
|
36
|
-
const hub = new LocalHub(options,
|
|
41
|
+
const hub = new LocalHub(options, context.logger, worker);
|
|
37
42
|
context.defer(() => hub.close());
|
|
43
|
+
context.logger.log('debug', 'Local WebSocket hub started', {
|
|
44
|
+
maxConnections: options.maxConnections,
|
|
45
|
+
maxPending: options.maxPending,
|
|
46
|
+
});
|
|
38
47
|
return hub.api;
|
|
39
48
|
}
|
|
40
49
|
const node = new HubNode(context, options, context.getDependency(redis).connection(options.redisConnection), options.natsConnection === undefined
|
|
@@ -48,19 +57,17 @@ class HubRuntime {
|
|
|
48
57
|
/** Factory input: `{ app, options? }`. Options default to `app.config['dokebi-websocket-hub']`. */
|
|
49
58
|
export const createPlugin = definePlugin({
|
|
50
59
|
name: 'dokebi-websocket-hub',
|
|
51
|
-
version: '0.
|
|
52
|
-
core: '^0.
|
|
53
|
-
options:
|
|
60
|
+
version: '0.4.0',
|
|
61
|
+
core: '^0.4.0',
|
|
62
|
+
options: declaration,
|
|
54
63
|
// local: nothing. cluster: Redis, and NATS only when natsConnection is set (D-0029).
|
|
55
64
|
dependencies: ({ options }) => options.mode === 'local'
|
|
56
65
|
? []
|
|
57
66
|
: [redis, ...(options.natsConnection === undefined ? [] : [nats])],
|
|
58
67
|
instance: ({ options }) => new HubRuntime(options),
|
|
59
68
|
});
|
|
60
|
-
/**
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
load: () => import('./index.js'),
|
|
66
|
-
});
|
|
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.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { Socket } from 'node:net';
|
|
2
|
+
import type { Logger } from '@dokebi/core';
|
|
2
3
|
import type { HubOptions } from './options.js';
|
|
3
4
|
import type { HubStore } from './store.js';
|
|
4
5
|
import { type HubLeader } from './types.js';
|
|
@@ -7,7 +8,8 @@ export declare class Leader {
|
|
|
7
8
|
readonly identity: HubLeader;
|
|
8
9
|
readonly store: HubStore;
|
|
9
10
|
readonly options: HubOptions;
|
|
10
|
-
|
|
11
|
+
readonly logger: Logger;
|
|
12
|
+
constructor(identity: HubLeader, store: HubStore, options: HubOptions, logger: Logger);
|
|
11
13
|
get active(): boolean;
|
|
12
14
|
start(): Promise<void>;
|
|
13
15
|
accept(socket: Socket): void;
|