@dokebi/websocket-hub 0.4.1 → 0.4.2

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/dist/store.js CHANGED
@@ -1,4 +1,5 @@
1
1
  import { createHash } from 'node:crypto';
2
+ import { PEER_LIMITS } from './options.js';
2
3
  import { epoch, identifier, records, sequence } from './protocol.js';
3
4
  import { HubError } from './types.js';
4
5
  // One hash slot, Redis time, and leader-token checks fence every authoritative mutation.
@@ -7,8 +8,12 @@ local op=ARGV[1]
7
8
  local t=redis.call('TIME');local now=tonumber(t[1])*1000+math.floor(tonumber(t[2])/1000)
8
9
  local leader=redis.call('GET',KEYS[1])
9
10
  if op=='elect' or op=='discover' then
10
- local fingerprint=redis.call('GET',KEYS[4])
11
- if fingerprint and fingerprint~=ARGV[5] then
11
+ -- D-0136: only the shared fingerprint (secret, delivery model) must agree; limits may differ.
12
+ -- Servers before it wrote only the full one (KEYS[4]): without a shared one nothing is refused
13
+ -- here, and a wrong secret is refused at hello.
14
+ local full=redis.call('GET',KEYS[4])
15
+ local shared=redis.call('GET',KEYS[5])
16
+ if shared and shared~=ARGV[6] and full~=ARGV[5] then
12
17
  -- A different configuration is refused only while servers of the old one are alive.
13
18
  local alive=leader and true or false
14
19
  if not alive then
@@ -17,11 +22,12 @@ if op=='elect' or op=='discover' then
17
22
  end
18
23
  end
19
24
  if alive then return {'hub-error','CONFIG_MISMATCH'} end
20
- redis.call('DEL',KEYS[4])
25
+ redis.call('DEL',KEYS[4],KEYS[5])
21
26
  end
22
27
  end
23
28
  if op=='elect' then
24
- if not leader then redis.call('SET',KEYS[4],ARGV[5]);redis.call('SET',KEYS[1],ARGV[2],'PX',ARGV[3]);leader=ARGV[2] end
29
+ -- The full fingerprint is kept as older servers wrote it (NX): theirs still match while they run.
30
+ if not leader then redis.call('SET',KEYS[4],ARGV[5],'NX');redis.call('SET',KEYS[5],ARGV[6]);redis.call('SET',KEYS[1],ARGV[2],'PX',ARGV[3]);leader=ARGV[2] end
25
31
  return leader
26
32
  end
27
33
  if op=='discover' then return leader or '' end
@@ -53,22 +59,59 @@ if op=='remove' then
53
59
  end
54
60
  return {'hub-error','INVALID_OPERATION'}
55
61
  `;
62
+ /**
63
+ * The epoch of the nonce keys (seal `NonceStore.lostAt`): a key without expiry holding when it was
64
+ * written (Redis TIME, ms). Its absence means the nonces may be gone with it — a restart without
65
+ * persistence, a FLUSHALL, an eviction — so it is written again with the current time, and sealed
66
+ * frames stamped before it are refused for 2 x drift. Primed at start (`primeNonces`), so the first
67
+ * claim on a new Redis refuses nothing.
68
+ */
69
+ const NONCE_EPOCH = `local epoch=redis.call('GET',KEYS[1])
70
+ local created=0
71
+ if not epoch then
72
+ local now=redis.call('TIME')
73
+ epoch=tostring(tonumber(now[1])*1000+math.floor(tonumber(now[2])/1000))
74
+ redis.call('SET',KEYS[1],epoch)
75
+ created=1
76
+ end`;
77
+ /** One nonce claim (D-0038): the epoch and SET NX PX in one atomic step. { epoch, fresh, created }. */
78
+ const NONCE_CHECK = `${NONCE_EPOCH.replaceAll('KEYS[1]', 'KEYS[2]')}
79
+ local fresh=redis.call('SET',KEYS[1],'1','NX','PX',ARGV[1])
80
+ return {epoch,fresh and 1 or 0,created}`;
81
+ /** The epoch alone (at start). { epoch, created }. */
82
+ const NONCE_PRIME = `${NONCE_EPOCH}
83
+ return {epoch,created}`;
84
+ const EPOCH_MS = /^\d{1,16}$/;
56
85
  export class HubStore {
57
86
  redis;
58
87
  options;
59
88
  keys;
89
+ /** Every shared setting, as servers before D-0136 compared them; kept for them. */
60
90
  fingerprint;
91
+ /** What servers of one namespace must share (D-0136): the secret and the delivery model. */
92
+ sharedFingerprint;
61
93
  // Loaded once per store: calls send the SHA1 and fall back to EVAL only on NOSCRIPT.
62
94
  #script;
95
+ #nonceCheck;
96
+ #noncePrime;
63
97
  #prefix;
98
+ /** The epoch of the nonce keys (undefined before the first claim or `primeNonces`). */
99
+ #noncesLostAt;
100
+ /** Told when the missing epoch key was written: the first start on this Redis, or after a loss. */
101
+ onNoncesLost;
64
102
  constructor(redis, options) {
65
103
  this.redis = redis;
66
104
  this.options = options;
67
105
  this.#script = redis.script(script);
106
+ this.#nonceCheck = redis.script(NONCE_CHECK);
107
+ this.#noncePrime = redis.script(NONCE_PRIME);
68
108
  const hash = createHash('sha256').update(options.namespace).digest('hex');
69
109
  const prefix = `dokebi:websocket-hub:{${hash}}`;
70
110
  this.#prefix = prefix;
71
- this.keys = ['leader', 'owners', 'revision', 'config'].map((x) => `${prefix}:${x}`);
111
+ this.keys = ['leader', 'owners', 'revision', 'config', 'config-shared'].map((x) => `${prefix}:${x}`);
112
+ this.sharedFingerprint = createHash('sha256')
113
+ .update(JSON.stringify(['delivery-memory-v2', options.secret ?? '']))
114
+ .digest('hex');
72
115
  this.fingerprint = createHash('sha256')
73
116
  .update(JSON.stringify([
74
117
  // D-0042: broadcasts live in leader memory; servers of the Redis-outbox version must
@@ -92,11 +135,11 @@ export class HubStore {
92
135
  ]))
93
136
  .digest('hex');
94
137
  }
95
- async run(op, token = '', arg3 = '', arg4 = '', arg5 = '') {
138
+ async run(op, token = '', arg3 = '', arg4 = '', arg5 = '', arg6 = '') {
96
139
  try {
97
140
  const result = await this.#script.run({
98
141
  keys: this.keys,
99
- arguments: [op, token, arg3, arg4, arg5],
142
+ arguments: [op, token, arg3, arg4, arg5, arg6],
100
143
  });
101
144
  if (Array.isArray(result) && result[0] === 'hub-error' && typeof result[1] === 'string')
102
145
  throw new HubError(result[1]);
@@ -140,22 +183,53 @@ export class HubStore {
140
183
  * first server to see a nonce wins and every other one is told it was used.
141
184
  */
142
185
  async claimNonce(key, ttlSeconds) {
186
+ let reply;
143
187
  try {
144
- return await this.redis.set(`${this.#prefix}:nonce:${key}`, '1', {
145
- NX: true,
146
- PX: Math.max(1, ttlSeconds) * 1000,
188
+ reply = await this.#nonceCheck.run({
189
+ keys: [`${this.#prefix}:nonce:${key}`, `${this.#prefix}:nonce-epoch`],
190
+ arguments: [String(Math.max(1, ttlSeconds) * 1000)],
191
+ });
192
+ }
193
+ catch (error) {
194
+ throw new HubError('STORE_UNAVAILABLE', { cause: error });
195
+ }
196
+ if (!Array.isArray(reply) || reply.length !== 3 || !EPOCH_MS.test(String(reply[0])))
197
+ throw new HubError('STORE_UNAVAILABLE', {
198
+ cause: new Error('Redis returned an unexpected nonce claim answer'),
147
199
  });
200
+ const started = Number(reply[0]);
201
+ this.#noncesLostAt = started;
202
+ if (Number(reply[2]) === 1)
203
+ this.onNoncesLost?.(started);
204
+ return Number(reply[1]) === 1;
205
+ }
206
+ /** The epoch of the nonce keys (seal `lostAt`); undefined before a claim or `primeNonces`. */
207
+ noncesLostAt() {
208
+ return this.#noncesLostAt;
209
+ }
210
+ /** Writes the nonce epoch when it is missing, before the first sealed frame (node start). */
211
+ async primeNonces() {
212
+ let reply;
213
+ try {
214
+ reply = await this.#noncePrime.run({ keys: [`${this.#prefix}:nonce-epoch`], arguments: [] });
148
215
  }
149
216
  catch (error) {
150
217
  throw new HubError('STORE_UNAVAILABLE', { cause: error });
151
218
  }
219
+ if (!Array.isArray(reply) || reply.length !== 2 || !EPOCH_MS.test(String(reply[0])))
220
+ throw new HubError('STORE_UNAVAILABLE', {
221
+ cause: new Error('Redis returned an unexpected nonce epoch answer'),
222
+ });
223
+ this.#noncesLostAt = Number(reply[0]);
224
+ if (Number(reply[1]) === 1)
225
+ this.onNoncesLost?.(this.#noncesLostAt);
152
226
  }
153
227
  async discover() {
154
- const v = await this.run('discover', '', '', '', this.fingerprint);
228
+ const v = await this.run('discover', '', '', '', this.fingerprint, this.sharedFingerprint);
155
229
  return v ? Object.freeze(JSON.parse(String(v))) : undefined;
156
230
  }
157
231
  async elect(leader) {
158
- return Object.freeze(JSON.parse(String(await this.run('elect', JSON.stringify(leader), String(this.options.leaseMs), '', this.fingerprint))));
232
+ return Object.freeze(JSON.parse(String(await this.run('elect', JSON.stringify(leader), String(this.options.leaseMs), '', this.fingerprint, this.sharedFingerprint))));
159
233
  }
160
234
  async snapshot(leaderEpoch) {
161
235
  const result = (await this.run('snapshot', leaderEpoch));
@@ -173,12 +247,14 @@ export class HubStore {
173
247
  identifier(owner.serverId);
174
248
  epoch(owner.session);
175
249
  sequence(owner.expires);
176
- owner.connections = records(owner.connections, key, this.options.maxConnections);
250
+ // Saved by a leader whose limits may differ from ours (D-0136): read against what any
251
+ // server may set; our own limits then refuse growth beyond them.
252
+ owner.connections = records(owner.connections, key, PEER_LIMITS.connections);
177
253
  owners.set(key, owner);
178
254
  }
179
- if (owners.size > this.options.maxOwners ||
255
+ if (owners.size > PEER_LIMITS.owners ||
180
256
  [...owners.values()].reduce((sum, owner) => sum + owner.connections.length, 0) >
181
- this.options.maxTotalConnections)
257
+ PEER_LIMITS.totalConnections)
182
258
  throw new HubError('CHECKPOINT_INVALID');
183
259
  return { revision: sequence(Number(result[0])), owners, now: sequence(result[2]) };
184
260
  }
package/dist/types.d.ts CHANGED
@@ -114,6 +114,14 @@ export interface HubNonceStore {
114
114
  setIfNotExists(key: string, ttlSeconds: number): Promise<boolean>;
115
115
  /** true only when every server of the namespace shares it (cluster mode). */
116
116
  readonly shared: boolean;
117
+ /**
118
+ * When the store last started empty or found its nonces gone (epoch ms), or undefined: the
119
+ * local store at its creation (a previous process's nonces are gone), the cluster store at the
120
+ * start of its Redis server when the nonce epoch key had vanished (a restart without
121
+ * persistence). @dokebi/seal refuses a frame stamped before it while the drift check alone would
122
+ * still pass it, since its nonce may be gone (seal `NonceStore.lostAt`).
123
+ */
124
+ lostAt?(): number | undefined;
117
125
  }
118
126
  export interface HubApi {
119
127
  readonly state: 'starting' | 'ready' | 'recovering' | 'closing' | 'closed';
package/dist/types.js CHANGED
@@ -2,11 +2,12 @@ import { DokebiError } from '@dokebi/core';
2
2
  /** Repair advice of the codes a developer or operator fixes (the others are runtime outcomes). */
3
3
  const FIXES = Object.freeze({
4
4
  LOCAL_IN_CLUSTER: 'Use mode: cluster (Redis) in options.dokebi-websocket-hub, or set allowInCluster: true to give every worker its own hub.',
5
+ LOCAL_IN_PRODUCTION: 'Use mode: cluster (Redis) in options.dokebi-websocket-hub: in production a restart or a rolling deploy loses the presence and the replay nonces of a local hub (D-0161).',
5
6
  LISTEN_FAILED: 'Free options.dokebi-websocket-hub.port on host (or use port 0), and check that host is an address of this machine.',
6
7
  STARTUP_TIMEOUT: 'Check that Redis (redisConnection) answers and that peers reach advertiseHost:port; raise startupTimeoutMs for slow networks.',
7
8
  UNAUTHORIZED: 'Give every server of the namespace the same options.dokebi-websocket-hub.secret.',
8
9
  PROTOCOL_MISMATCH: 'Run the same @dokebi/websocket-hub version on every server of a namespace (finish the rolling restart).',
9
- CONFIG_MISMATCH: 'Servers of one namespace need the same secret, leaseMs, ownerTtlMs and size limits; use another namespace for different settings.',
10
+ CONFIG_MISMATCH: 'Servers of one namespace need the same secret (limits may differ between servers); use another namespace for a different secret.',
10
11
  });
11
12
  /**
12
13
  * Errors of @dokebi/websocket-hub (D-0063): a DokebiError with `plugin: 'dokebi-websocket-hub'`
package/dist/wire.d.ts CHANGED
@@ -1,16 +1,31 @@
1
1
  import type { Socket } from 'node:net';
2
+ /** One frame on the wire: the JSON of `value` (at most `limit` bytes) and its newline. */
3
+ export declare function frame(value: unknown, limit: number): Buffer;
2
4
  export declare class Wire {
3
5
  #private;
4
6
  readonly socket: Socket;
7
+ /** The largest frame this side writes. */
5
8
  readonly limit: number;
6
9
  readonly queueBytes: number;
7
- constructor(socket: Socket, limit: number, queueBytes: number, onFrame: (frame: Record<string, unknown>) => void, onClose: () => void,
10
+ /**
11
+ * The largest frame read from the socket (D-0136): `limit` until the owner raises it, for
12
+ * example once a peer has authenticated, to what any hub server may send.
13
+ */
14
+ readLimit: number;
15
+ constructor(socket: Socket,
16
+ /** The largest frame this side writes. */
17
+ limit: number, queueBytes: number, onFrame: (frame: Record<string, unknown>) => void, onClose: () => void,
8
18
  /**
9
19
  * Told why the socket failed (`PEER_SOCKET_ERROR`) or a frame was refused and the socket
10
20
  * dropped (`PEER_FRAME_REJECTED`); the owner logs it (D-0047). `close` always follows.
11
21
  */
12
- onError?: (code: string, error: unknown) => void);
22
+ onError?: (code: string, error: unknown) => void, readLimit?: number);
13
23
  send(value: unknown): void;
24
+ /**
25
+ * Writes a frame made once by `frame()` for several peers (a presence change goes to every
26
+ * server: serializing the roster per peer cost O(peers × roster)). Same checks as `send`.
27
+ */
28
+ sendFrame(bytes: Buffer): void;
14
29
  close(): void;
15
30
  /** Sends what is queued, then FIN; destroyed after `graceMs` if the peer does not close. */
16
31
  end(graceMs: number): void;
package/dist/wire.js CHANGED
@@ -1,5 +1,10 @@
1
1
  import { decode, encode } from './protocol.js';
2
2
  import { HubError } from './types.js';
3
+ const NEWLINE = Buffer.from('\n');
4
+ /** One frame on the wire: the JSON of `value` (at most `limit` bytes) and its newline. */
5
+ export function frame(value, limit) {
6
+ return Buffer.concat([encode(value, limit), NEWLINE]);
7
+ }
3
8
  export class Wire {
4
9
  socket;
5
10
  limit;
@@ -7,15 +12,23 @@ export class Wire {
7
12
  #chunks = [];
8
13
  #bytes = 0;
9
14
  #closed = false;
10
- constructor(socket, limit, queueBytes, onFrame, onClose,
15
+ /**
16
+ * The largest frame read from the socket (D-0136): `limit` until the owner raises it, for
17
+ * example once a peer has authenticated, to what any hub server may send.
18
+ */
19
+ readLimit;
20
+ constructor(socket,
21
+ /** The largest frame this side writes. */
22
+ limit, queueBytes, onFrame, onClose,
11
23
  /**
12
24
  * Told why the socket failed (`PEER_SOCKET_ERROR`) or a frame was refused and the socket
13
25
  * dropped (`PEER_FRAME_REJECTED`); the owner logs it (D-0047). `close` always follows.
14
26
  */
15
- onError = () => { }) {
27
+ onError = () => { }, readLimit = limit) {
16
28
  this.socket = socket;
17
29
  this.limit = limit;
18
30
  this.queueBytes = queueBytes;
31
+ this.readLimit = readLimit;
19
32
  socket.setNoDelay(true);
20
33
  socket.on('error', (error) => onError('PEER_SOCKET_ERROR', error));
21
34
  socket.on('data', (data) => {
@@ -30,7 +43,7 @@ export class Wire {
30
43
  this.#bytes = 0;
31
44
  start = i + 1;
32
45
  if (frame.length)
33
- onFrame(decode(frame, limit));
46
+ onFrame(decode(frame, this.readLimit));
34
47
  }
35
48
  this.#append(data.subarray(start));
36
49
  }
@@ -47,20 +60,31 @@ export class Wire {
47
60
  #append(chunk) {
48
61
  if (!chunk.length)
49
62
  return;
50
- if (this.#bytes + chunk.length > this.limit)
63
+ if (this.#bytes + chunk.length > this.readLimit)
51
64
  throw new HubError('FRAME_LIMIT');
52
65
  this.#chunks.push(Buffer.from(chunk));
53
66
  this.#bytes += chunk.length;
54
67
  }
55
68
  send(value) {
56
- if (this.#closed || this.socket.destroyed)
69
+ if (this.#closed || this.socket.destroyed || this.socket.writableEnded)
70
+ throw new HubError('DISCONNECTED');
71
+ this.sendFrame(frame(value, this.limit));
72
+ }
73
+ /**
74
+ * Writes a frame made once by `frame()` for several peers (a presence change goes to every
75
+ * server: serializing the roster per peer cost O(peers × roster)). Same checks as `send`.
76
+ */
77
+ sendFrame(bytes) {
78
+ // After end() (a leader leaving) the socket still reads, so a frame may still be answered:
79
+ // writing then fails asynchronously (ERR_STREAM_WRITE_AFTER_END as a socket error); refuse it
80
+ // here like a closed socket, for the caller's own handling.
81
+ if (this.#closed || this.socket.destroyed || this.socket.writableEnded)
57
82
  throw new HubError('DISCONNECTED');
58
- const frame = Buffer.concat([encode(value, this.limit), Buffer.from('\n')]);
59
- if (this.socket.writableLength + frame.length > this.queueBytes) {
83
+ if (this.socket.writableLength + bytes.length > this.queueBytes) {
60
84
  this.socket.destroy();
61
85
  throw new HubError('BACKPRESSURE');
62
86
  }
63
- this.socket.write(frame);
87
+ this.socket.write(bytes);
64
88
  }
65
89
  close() {
66
90
  this.socket.destroy();
@@ -89,6 +89,7 @@
89
89
  "minimum": 25,
90
90
  "maximum": 10000,
91
91
  "deprecated": true,
92
+ "x-dokebi-alias-of": "pollIntervalMs",
92
93
  "description": "Deprecated name of pollIntervalMs; use that key."
93
94
  },
94
95
  "ownerTtlMs": {
@@ -108,6 +109,7 @@
108
109
  "minimum": 1000,
109
110
  "maximum": 120000,
110
111
  "deprecated": true,
112
+ "x-dokebi-alias-of": "startupTimeoutMs",
111
113
  "description": "Deprecated name of startupTimeoutMs; use that key."
112
114
  },
113
115
  "maxFrameBytes": {
@@ -157,8 +159,28 @@
157
159
  "minimum": 16384,
158
160
  "maximum": 67108864,
159
161
  "deprecated": true,
162
+ "x-dokebi-alias-of": "maxPendingBytes",
160
163
  "description": "Deprecated name of maxPendingBytes; use that key."
161
164
  },
165
+ "broadcastShare": {
166
+ "type": "number",
167
+ "minimum": 0.05,
168
+ "maximum": 1,
169
+ "default": 0.5,
170
+ "description": "Share of the event queue (maxPending events, maxPendingBytes) broadcasts may fill before they are refused with BUSY; the rest stays for presence and kick events, which are never refused (D-0114). 1 lets broadcasts fill it."
171
+ },
172
+ "maxNonces": {
173
+ "type": "integer",
174
+ "minimum": 1,
175
+ "maximum": 10000000,
176
+ "default": 100000
177
+ },
178
+ "logRepeatWindowMs": {
179
+ "type": "integer",
180
+ "minimum": 1000,
181
+ "maximum": 3600000,
182
+ "default": 10000
183
+ },
162
184
  "deliveryTimeoutMs": {
163
185
  "type": "integer",
164
186
  "deprecated": true,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dokebi/websocket-hub",
3
- "version": "0.4.1",
3
+ "version": "0.4.2",
4
4
  "description": "WebSocket hub for Dokebi: connection roster, rooms, broadcast and kick across workers and servers.",
5
5
  "keywords": [
6
6
  "dokebi",
@@ -43,18 +43,18 @@
43
43
  "test": "node -e \"require('node:fs').rmSync('.tmp/tests',{recursive:true,force:true})\" && tsc -p tsconfig.test.json && node --test \".tmp/tests/tests/*.test.js\""
44
44
  },
45
45
  "peerDependencies": {
46
- "@dokebi/core": "^0.4.0",
46
+ "@dokebi/core": "^0.4.2",
47
47
  "@dokebi/nats": "^0.4.0",
48
48
  "@dokebi/redis": "^0.4.0"
49
49
  },
50
50
  "devDependencies": {
51
- "@dokebi/nats": "0.4.0",
52
- "@dokebi/redis": "0.4.0"
51
+ "@dokebi/nats": "0.4.1",
52
+ "@dokebi/redis": "0.4.1"
53
53
  },
54
54
  "dokebi": {
55
55
  "schemaVersion": 2,
56
56
  "id": "dokebi-websocket-hub",
57
- "core": "^0.4.0",
57
+ "core": "^0.4.2",
58
58
  "dependencies": [
59
59
  {
60
60
  "name": "dokebi-redis",