@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/dist/status.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { HubError } from './types.js';
1
2
  /**
2
3
  * The one place that turns facts into a status (D-0038 · original x-hubserver `hubStatus`).
3
4
  * `HubApi.status()` and `dokebi-hub-status` both call it, so a health check, a dashboard and the
@@ -32,31 +33,126 @@ export function hubStatus(input) {
32
33
  connections: lease.connections,
33
34
  });
34
35
  }
35
- /** In-process nonce store for local mode: correct for one process only (`shared: false`). */
36
+ /**
37
+ * A min-heap of [expires, key] pairs by expiry (ISSUE-0006 recheck: a scan of the oldest
38
+ * insertions missed expired entries further back when TTLs differ). Pairs of keys that were
39
+ * renewed or removed since are skipped when they reach the top.
40
+ */
41
+ class ExpiryHeap {
42
+ #items = [];
43
+ push(expires, key) {
44
+ const items = this.#items;
45
+ items.push([expires, key]);
46
+ let index = items.length - 1;
47
+ while (index > 0) {
48
+ const parent = (index - 1) >> 1;
49
+ const above = items[parent];
50
+ const here = items[index];
51
+ if (above[0] <= here[0])
52
+ break;
53
+ items[parent] = here;
54
+ items[index] = above;
55
+ index = parent;
56
+ }
57
+ }
58
+ peek() {
59
+ return this.#items[0];
60
+ }
61
+ pop() {
62
+ const items = this.#items;
63
+ const last = items.pop();
64
+ if (last === undefined || items.length === 0)
65
+ return;
66
+ items[0] = last;
67
+ let index = 0;
68
+ for (;;) {
69
+ const left = 2 * index + 1;
70
+ const right = left + 1;
71
+ let smallest = index;
72
+ if (left < items.length &&
73
+ items[left][0] < items[smallest][0])
74
+ smallest = left;
75
+ if (right < items.length &&
76
+ items[right][0] < items[smallest][0])
77
+ smallest = right;
78
+ if (smallest === index)
79
+ break;
80
+ const moved = items[smallest];
81
+ items[smallest] = items[index];
82
+ items[index] = moved;
83
+ index = smallest;
84
+ }
85
+ }
86
+ }
87
+ const WARN_EVERY_MS = 10_000;
88
+ const FULL_FIX = 'More sealed frames arrived within 2 x drift than the local nonce store keeps: use mode: cluster (Redis, no such limit), or lower the seal drift window (dokebi-websocket sealDriftMs).';
89
+ /**
90
+ * In-process nonce store for local mode: correct for one process only (`shared: false`).
91
+ *
92
+ * Full of **live** nonces it refuses a new one with `NONCE_STORE_FULL` instead of forgetting a
93
+ * live one (D-0075, fail closed: a forgotten nonce lets its captured frame be replayed). Seal turns
94
+ * the refusal into a retryable `SEAL_REPLAY_CAPACITY`; room returns as the nonces expire.
95
+ */
36
96
  export class LocalNonceStore {
37
- max;
38
97
  shared = false;
98
+ max;
39
99
  #entries = new Map();
100
+ #expiry = new ExpiryHeap();
101
+ #now;
102
+ #logger;
40
103
  #inserts = 0;
41
- constructor(max = 100_000) {
42
- this.max = max;
104
+ #warnedAt = Number.NEGATIVE_INFINITY;
105
+ #refused = 0;
106
+ constructor(options = {}) {
107
+ this.max = options.max ?? 100_000;
108
+ this.#now = options.now ?? Date.now;
109
+ this.#logger = options.logger;
43
110
  }
44
111
  async setIfNotExists(key, ttlSeconds) {
45
- const now = Date.now();
112
+ const now = this.#now();
46
113
  const existing = this.#entries.get(key);
47
- if (existing !== undefined && existing > now)
48
- return false;
114
+ if (existing !== undefined) {
115
+ if (existing > now)
116
+ return false;
117
+ // Expired: deleted first, so the renewed entry moves to the end (insertion order = age).
118
+ this.#entries.delete(key);
119
+ }
120
+ // Full: expired entries make room (earliest expiry first). A live nonce is never forgotten.
121
+ if (this.#entries.size >= this.max && !this.#evictExpired(now))
122
+ this.#full(now);
49
123
  this.#entries.set(key, now + ttlSeconds * 1000);
124
+ this.#expiry.push(now + ttlSeconds * 1000, key);
50
125
  if (++this.#inserts % 500 === 0)
51
- for (const [entry, expires] of this.#entries)
52
- if (expires <= now)
53
- this.#entries.delete(entry);
54
- // Beyond the cap the oldest go first: a thinner defence beats running out of memory.
55
- for (const entry of this.#entries.keys()) {
56
- if (this.#entries.size <= this.max)
57
- break;
58
- this.#entries.delete(entry);
59
- }
126
+ this.#evictExpired(now);
60
127
  return true;
61
128
  }
129
+ /** Deletes every expired entry, earliest expiry first (each pair is popped once); true when that made room. */
130
+ #evictExpired(now) {
131
+ for (let top = this.#expiry.peek(); top !== undefined && top[0] <= now; top = this.#expiry.peek()) {
132
+ this.#expiry.pop();
133
+ // A renewed key has a newer pair; only the pair that matches the stored expiry deletes it.
134
+ if (this.#entries.get(top[1]) === top[0])
135
+ this.#entries.delete(top[1]);
136
+ }
137
+ return this.#entries.size < this.max;
138
+ }
139
+ #full(now) {
140
+ // Per frame: counted, and said once per interval with the count (D-0047).
141
+ this.#refused += 1;
142
+ if (this.#logger && now - this.#warnedAt >= WARN_EVERY_MS) {
143
+ this.#logger.log('warn', 'Replay nonce store full; sealed frames refused', {
144
+ code: 'NONCE_STORE_FULL',
145
+ max: this.max,
146
+ live: this.#entries.size,
147
+ repeated: this.#refused - 1,
148
+ fix: FULL_FIX,
149
+ });
150
+ this.#warnedAt = now;
151
+ this.#refused = 0;
152
+ }
153
+ throw new HubError('NONCE_STORE_FULL', {
154
+ fix: FULL_FIX,
155
+ details: { max: this.max },
156
+ });
157
+ }
62
158
  }
package/dist/store.js CHANGED
@@ -74,7 +74,7 @@ export class HubStore {
74
74
  // D-0042: broadcasts live in leader memory; servers of the Redis-outbox version must
75
75
  // not share a namespace with this one.
76
76
  'delivery-memory-v2',
77
- options.secret,
77
+ options.secret ?? '',
78
78
  options.leaseMs,
79
79
  options.ownerTtlMs,
80
80
  options.maxConnections,
package/dist/types.d.ts CHANGED
@@ -1,6 +1,10 @@
1
- export declare class HubError extends Error {
2
- readonly code: string;
3
- constructor(code: string, options?: ErrorOptions);
1
+ import { DokebiError, type DokebiErrorOptions } from '@dokebi/core';
2
+ /**
3
+ * Errors of @dokebi/websocket-hub (D-0063): a DokebiError with `plugin: 'dokebi-websocket-hub'`
4
+ * and the message `WebSocket hub: <code>`. Classify by `code`, never with `instanceof` alone.
5
+ */
6
+ export declare class HubError extends DokebiError {
7
+ constructor(code: string, options?: DokebiErrorOptions);
4
8
  }
5
9
  export interface HubRegistration {
6
10
  readonly tenant: string;
@@ -104,8 +108,9 @@ export interface HubStatus {
104
108
  readonly servers?: number;
105
109
  readonly connections?: number;
106
110
  }
107
- /** One-time nonce store for sealed frames (structurally the @dokebi/crypto NonceStore · D-0038). */
111
+ /** One-time nonce store for sealed frames (structurally the @dokebi/seal NonceStore · D-0038, D-0059). */
108
112
  export interface HubNonceStore {
113
+ /** false for a nonce seen before; rejects `NONCE_STORE_FULL` when a local store is full of live nonces (D-0075). */
109
114
  setIfNotExists(key: string, ttlSeconds: number): Promise<boolean>;
110
115
  /** true only when every server of the namespace shares it (cluster mode). */
111
116
  readonly shared: boolean;
package/dist/types.js CHANGED
@@ -1,8 +1,25 @@
1
- export class HubError extends Error {
2
- code;
3
- constructor(code, options) {
4
- super(`WebSocket hub: ${code}`, options);
5
- this.code = code;
1
+ import { DokebiError } from '@dokebi/core';
2
+ /** Repair advice of the codes a developer or operator fixes (the others are runtime outcomes). */
3
+ const FIXES = Object.freeze({
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
+ 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
+ STARTUP_TIMEOUT: 'Check that Redis (redisConnection) answers and that peers reach advertiseHost:port; raise startupTimeoutMs for slow networks.',
7
+ UNAUTHORIZED: 'Give every server of the namespace the same options.dokebi-websocket-hub.secret.',
8
+ 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
+ });
11
+ /**
12
+ * Errors of @dokebi/websocket-hub (D-0063): a DokebiError with `plugin: 'dokebi-websocket-hub'`
13
+ * and the message `WebSocket hub: <code>`. Classify by `code`, never with `instanceof` alone.
14
+ */
15
+ export class HubError extends DokebiError {
16
+ constructor(code, options = {}) {
17
+ const fix = options.fix ?? FIXES[code];
18
+ super(code, `WebSocket hub: ${code}`, {
19
+ ...options,
20
+ plugin: options.plugin ?? 'dokebi-websocket-hub',
21
+ ...(fix === undefined ? {} : { fix }),
22
+ });
6
23
  this.name = 'HubError';
7
24
  }
8
25
  }
@@ -0,0 +1,4 @@
1
+ /** Own enumerable data properties of a plain object; Proxies and accessors are refused. */
2
+ export declare function object(value: unknown): Record<string, unknown>;
3
+ export declare function keys(value: Record<string, unknown>, allowed: readonly string[]): void;
4
+ export declare function integer(v: unknown, min: number, max: number): number;
package/dist/values.js ADDED
@@ -0,0 +1,32 @@
1
+ import { types } from 'node:util';
2
+ import { HubError } from './types.js';
3
+ /*
4
+ * Checks of values in hub frames and API calls. They lived in the 0.3 hand option parser, whose
5
+ * code they keep: a refused value is `INVALID_OPTIONS` on the wire as before (peers of the same
6
+ * protocol compare that code). Options themselves are parsed by the declaration in options.ts.
7
+ */
8
+ /** Own enumerable data properties of a plain object; Proxies and accessors are refused. */
9
+ export function object(value) {
10
+ if (!value ||
11
+ typeof value !== 'object' ||
12
+ types.isProxy(value) ||
13
+ ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
14
+ throw new HubError('INVALID_OPTIONS');
15
+ const result = Object.create(null);
16
+ for (const key of Reflect.ownKeys(value)) {
17
+ const desc = Object.getOwnPropertyDescriptor(value, key);
18
+ if (typeof key !== 'string' || !desc || !('value' in desc) || !desc.enumerable)
19
+ throw new HubError('INVALID_OPTIONS');
20
+ result[key] = desc.value;
21
+ }
22
+ return result;
23
+ }
24
+ export function keys(value, allowed) {
25
+ if (Object.keys(value).some((k) => !allowed.includes(k)))
26
+ throw new HubError('INVALID_OPTIONS');
27
+ }
28
+ export function integer(v, min, max) {
29
+ if (typeof v !== 'number' || !Number.isSafeInteger(v) || v < min || v > max)
30
+ throw new HubError('INVALID_OPTIONS');
31
+ return v;
32
+ }
@@ -5,7 +5,10 @@
5
5
  "properties": {
6
6
  "mode": {
7
7
  "type": "string",
8
- "enum": ["local", "cluster"],
8
+ "enum": [
9
+ "local",
10
+ "cluster"
11
+ ],
9
12
  "default": "local",
10
13
  "description": "local: one process, in memory (no Redis/NATS). cluster: several processes or servers share presence through Redis (D-0029)."
11
14
  },
@@ -17,34 +20,44 @@
17
20
  "namespace": {
18
21
  "type": "string",
19
22
  "minLength": 1,
20
- "maxLength": 64
23
+ "maxLength": 64,
24
+ "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$",
25
+ "default": "local"
21
26
  },
22
27
  "serverId": {
23
28
  "type": "string",
24
29
  "minLength": 1,
25
- "maxLength": 64
30
+ "maxLength": 64,
31
+ "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$",
32
+ "default": "local"
26
33
  },
27
34
  "redisConnection": {
28
35
  "type": "string",
29
36
  "minLength": 1,
30
37
  "maxLength": 64,
38
+ "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$",
31
39
  "description": "Required in cluster mode."
32
40
  },
33
41
  "natsConnection": {
34
42
  "type": "string",
35
43
  "minLength": 1,
36
44
  "maxLength": 64,
37
- "description": "Optional in cluster mode: leader-change notifications; without it peers notice by Redis polling (pollMs)."
45
+ "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$",
46
+ "description": "Optional in cluster mode: leader-change notifications; without it peers notice by Redis polling (pollIntervalMs)."
38
47
  },
39
48
  "host": {
40
49
  "type": "string",
41
50
  "minLength": 1,
42
- "maxLength": 253
51
+ "maxLength": 253,
52
+ "pattern": "^[^\\s\\x00-\\x1f]+$",
53
+ "default": "127.0.0.1"
43
54
  },
44
55
  "advertiseHost": {
45
56
  "type": "string",
46
57
  "minLength": 1,
47
- "maxLength": 253
58
+ "maxLength": 253,
59
+ "pattern": "^[^\\s\\x00-\\x1f]+$",
60
+ "default": "127.0.0.1"
48
61
  },
49
62
  "secret": {
50
63
  "type": "string",
@@ -65,24 +78,38 @@
65
78
  "maximum": 60000,
66
79
  "default": 3000
67
80
  },
68
- "pollMs": {
81
+ "pollIntervalMs": {
69
82
  "type": "integer",
70
83
  "minimum": 25,
71
84
  "maximum": 10000,
72
85
  "default": 500
73
86
  },
87
+ "pollMs": {
88
+ "type": "integer",
89
+ "minimum": 25,
90
+ "maximum": 10000,
91
+ "deprecated": true,
92
+ "description": "Deprecated name of pollIntervalMs; use that key."
93
+ },
74
94
  "ownerTtlMs": {
75
95
  "type": "integer",
76
96
  "minimum": 1500,
77
97
  "maximum": 120000,
78
98
  "default": 15000
79
99
  },
80
- "startupMs": {
100
+ "startupTimeoutMs": {
81
101
  "type": "integer",
82
102
  "minimum": 1000,
83
103
  "maximum": 120000,
84
104
  "default": 15000
85
105
  },
106
+ "startupMs": {
107
+ "type": "integer",
108
+ "minimum": 1000,
109
+ "maximum": 120000,
110
+ "deprecated": true,
111
+ "description": "Deprecated name of startupTimeoutMs; use that key."
112
+ },
86
113
  "maxFrameBytes": {
87
114
  "type": "integer",
88
115
  "minimum": 16384,
@@ -119,12 +146,19 @@
119
146
  "maximum": 4096,
120
147
  "default": 128
121
148
  },
122
- "queueBytes": {
149
+ "maxPendingBytes": {
123
150
  "type": "integer",
124
151
  "minimum": 16384,
125
152
  "maximum": 67108864,
126
153
  "default": 4194304
127
154
  },
155
+ "queueBytes": {
156
+ "type": "integer",
157
+ "minimum": 16384,
158
+ "maximum": 67108864,
159
+ "deprecated": true,
160
+ "description": "Deprecated name of maxPendingBytes; use that key."
161
+ },
128
162
  "deliveryTimeoutMs": {
129
163
  "type": "integer",
130
164
  "deprecated": true,
@@ -146,21 +180,68 @@
146
180
  "description": "Removed in 0.3.0 with client ACKs (D-0057). Ignored: the hub logs warn OPTION_REMOVED once and starts. Delete it from dokebi.yaml."
147
181
  }
148
182
  },
149
- "if": {
150
- "properties": {
151
- "mode": {
152
- "const": "cluster"
183
+ "allOf": [
184
+ {
185
+ "if": {
186
+ "properties": {
187
+ "mode": {
188
+ "const": "cluster"
189
+ }
190
+ },
191
+ "required": [
192
+ "mode"
193
+ ]
194
+ },
195
+ "then": {
196
+ "properties": {
197
+ "namespace": true,
198
+ "serverId": true
199
+ },
200
+ "required": [
201
+ "namespace",
202
+ "serverId"
203
+ ]
153
204
  }
154
205
  },
155
- "required": ["mode"]
156
- },
157
- "then": {
158
- "properties": {
159
- "namespace": true,
160
- "serverId": true,
161
- "redisConnection": true,
162
- "secret": true
163
- },
164
- "required": ["namespace", "serverId", "redisConnection", "secret"]
165
- }
206
+ {
207
+ "if": {
208
+ "properties": {
209
+ "mode": {
210
+ "const": "cluster"
211
+ }
212
+ },
213
+ "required": [
214
+ "mode"
215
+ ]
216
+ },
217
+ "then": {
218
+ "properties": {
219
+ "redisConnection": true
220
+ },
221
+ "required": [
222
+ "redisConnection"
223
+ ]
224
+ }
225
+ },
226
+ {
227
+ "if": {
228
+ "properties": {
229
+ "mode": {
230
+ "const": "cluster"
231
+ }
232
+ },
233
+ "required": [
234
+ "mode"
235
+ ]
236
+ },
237
+ "then": {
238
+ "properties": {
239
+ "secret": true
240
+ },
241
+ "required": [
242
+ "secret"
243
+ ]
244
+ }
245
+ }
246
+ ]
166
247
  }
package/package.json CHANGED
@@ -1,6 +1,14 @@
1
1
  {
2
2
  "name": "@dokebi/websocket-hub",
3
- "version": "0.3.0",
3
+ "version": "0.4.1",
4
+ "description": "WebSocket hub for Dokebi: connection roster, rooms, broadcast and kick across workers and servers.",
5
+ "keywords": [
6
+ "dokebi",
7
+ "dokebi-plugin",
8
+ "websocket",
9
+ "hub",
10
+ "realtime"
11
+ ],
4
12
  "private": false,
5
13
  "type": "module",
6
14
  "license": "MIT",
@@ -13,6 +21,10 @@
13
21
  ".": {
14
22
  "types": "./dist/index.d.ts",
15
23
  "import": "./dist/index.js"
24
+ },
25
+ "./dependency": {
26
+ "types": "./dist/dependency.d.ts",
27
+ "import": "./dist/dependency.js"
16
28
  }
17
29
  },
18
30
  "files": [
@@ -26,32 +38,32 @@
26
38
  "node": ">=24.0.0"
27
39
  },
28
40
  "scripts": {
29
- "build": "tsc -p tsconfig.json",
41
+ "build": "tsc -p tsconfig.json && node -e \"import('./dist/options.js').then(async (m) => { const { renderOptionsSchema } = await import('@dokebi/core'); process.stdout.write(renderOptionsSchema(m.options)); })\" > options.schema.json",
30
42
  "typecheck": "tsc -p tsconfig.test.json --noEmit",
31
- "test": "tsc -p tsconfig.test.json && node --test \".tmp/tests/tests/*.test.js\""
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\""
32
44
  },
33
45
  "peerDependencies": {
34
- "@dokebi/core": "^0.2.0",
35
- "@dokebi/nats": "^0.1.0",
36
- "@dokebi/redis": "^0.1.0 || ^0.2.0"
46
+ "@dokebi/core": "^0.4.0",
47
+ "@dokebi/nats": "^0.4.0",
48
+ "@dokebi/redis": "^0.4.0"
37
49
  },
38
50
  "devDependencies": {
39
- "@dokebi/nats": "0.1.2",
40
- "@dokebi/redis": "0.2.1"
51
+ "@dokebi/nats": "0.4.0",
52
+ "@dokebi/redis": "0.4.0"
41
53
  },
42
54
  "dokebi": {
43
55
  "schemaVersion": 2,
44
56
  "id": "dokebi-websocket-hub",
45
- "core": "^0.2.0",
57
+ "core": "^0.4.0",
46
58
  "dependencies": [
47
59
  {
48
60
  "name": "dokebi-redis",
49
- "version": "^0.1.0 || ^0.2.0",
61
+ "version": "^0.4.0",
50
62
  "optional": true
51
63
  },
52
64
  {
53
65
  "name": "dokebi-nats",
54
- "version": "^0.1.0",
66
+ "version": "^0.4.0",
55
67
  "optional": true
56
68
  }
57
69
  ],
@@ -59,6 +71,18 @@
59
71
  "documentation": "AI.md",
60
72
  "installModule": "dist/install.js"
61
73
  },
74
+ "dokebiCatalog": {
75
+ "kind": "plugin",
76
+ "summary": "Hub of WebSocket clients, rooms, broadcast and kick (usually used through @dokebi/websocket)",
77
+ "maturity": "preview",
78
+ "provides": [
79
+ "realtime.hub"
80
+ ],
81
+ "doesNot": [
82
+ "No delivery ACK or redelivery"
83
+ ],
84
+ "recipes": []
85
+ },
62
86
  "publishConfig": {
63
87
  "access": "public",
64
88
  "registry": "https://registry.npmjs.org/"
package/dist/log.d.ts DELETED
@@ -1,24 +0,0 @@
1
- import type { LogFields, Logger, LogLevel } from '@dokebi/core';
2
- /**
3
- * The full text of a caught value for the `error` log field (D-0047): name, whole message and
4
- * stack, then each `cause` the same way. Only credentials in URLs (`//user:password@`) are
5
- * removed; a text over 16 KB is cut and marked.
6
- */
7
- export declare function errorText(error: unknown): string;
8
- /** A stable code of an error (hub, Redis, NATS or errno code), or `fallback`. */
9
- export declare function errorCode(error: unknown, fallback: string): string;
10
- /**
11
- * Logs a repeating event once per interval (D-0047): the first occurrence at once, the following
12
- * ones of the same message and code are counted and reported together (`repeated`) when the
13
- * interval ends. Hot paths (per message, per frame) can report every failure without a burst
14
- * flooding the log. Field and error text are built only for lines that are written.
15
- */
16
- export declare class LogThrottle {
17
- #private;
18
- readonly logger: Logger;
19
- readonly intervalMs: number;
20
- constructor(logger: Logger, intervalMs?: number);
21
- report(level: LogLevel, message: string, code: string, error?: unknown, fields?: LogFields): void;
22
- /** Writes the counts still pending (on close), so a burst at shutdown is not lost. */
23
- flush(): void;
24
- }
package/dist/log.js DELETED
@@ -1,101 +0,0 @@
1
- const CODE = /^[A-Z][A-Z0-9_]{0,63}$/;
2
- /**
3
- * The full text of a caught value for the `error` log field (D-0047): name, whole message and
4
- * stack, then each `cause` the same way. Only credentials in URLs (`//user:password@`) are
5
- * removed; a text over 16 KB is cut and marked.
6
- */
7
- export function errorText(error) {
8
- const parts = [];
9
- let current = error;
10
- for (let depth = 0; current !== undefined && depth < 5; depth++) {
11
- let text;
12
- if (current instanceof Error)
13
- text = current.stack ?? `${current.name}: ${current.message}`;
14
- else if (typeof current === 'string')
15
- text = current;
16
- else {
17
- try {
18
- text = `NonError: ${JSON.stringify(current)}`;
19
- }
20
- catch {
21
- text = `NonError: ${String(current)}`; // not serialisable (cycle, BigInt): its string form
22
- }
23
- }
24
- parts.push(depth ? `Caused by: ${text}` : text);
25
- current = current instanceof Error ? current.cause : undefined;
26
- }
27
- const text = parts.join('\n').replace(/\/\/[^\s/@]*@/g, '//***@');
28
- return text.length > 16_384
29
- ? `${text.slice(0, 16_384)}… [truncated ${text.length - 16_384} characters]`
30
- : text;
31
- }
32
- /** A stable code of an error (hub, Redis, NATS or errno code), or `fallback`. */
33
- export function errorCode(error, fallback) {
34
- const code = error?.code;
35
- return typeof code === 'string' && CODE.test(code) ? code : fallback;
36
- }
37
- /**
38
- * Logs a repeating event once per interval (D-0047): the first occurrence at once, the following
39
- * ones of the same message and code are counted and reported together (`repeated`) when the
40
- * interval ends. Hot paths (per message, per frame) can report every failure without a burst
41
- * flooding the log. Field and error text are built only for lines that are written.
42
- */
43
- export class LogThrottle {
44
- logger;
45
- intervalMs;
46
- #entries = new Map();
47
- constructor(logger, intervalMs = 10_000) {
48
- this.logger = logger;
49
- this.intervalMs = intervalMs;
50
- }
51
- report(level, message, code, error, fields) {
52
- if (!this.logger.isEnabled(level))
53
- return;
54
- const key = `${level}\u0000${code}\u0000${message}`;
55
- const entry = this.#entries.get(key);
56
- if (entry) {
57
- entry.count++;
58
- entry.error = error;
59
- entry.fields = fields;
60
- return;
61
- }
62
- this.#write(level, message, code, error, fields, 0);
63
- const value = {
64
- count: 0,
65
- error: undefined,
66
- fields: undefined,
67
- timer: setTimeout(() => this.#elapsed(key, value, level, message, code), this.intervalMs),
68
- };
69
- value.timer.unref();
70
- this.#entries.set(key, value);
71
- }
72
- #elapsed(key, entry, level, message, code) {
73
- if (!entry.count) {
74
- this.#entries.delete(key);
75
- return;
76
- }
77
- this.#write(level, message, code, entry.error, entry.fields, entry.count);
78
- entry.count = 0;
79
- entry.timer = setTimeout(() => this.#elapsed(key, entry, level, message, code), this.intervalMs);
80
- entry.timer.unref();
81
- }
82
- #write(level, message, code, error, fields, repeated) {
83
- this.logger.log(level, message, {
84
- ...fields,
85
- code,
86
- ...(error === undefined ? {} : { error: errorText(error) }),
87
- ...(repeated ? { repeated, intervalMs: this.intervalMs } : {}),
88
- });
89
- }
90
- /** Writes the counts still pending (on close), so a burst at shutdown is not lost. */
91
- flush() {
92
- for (const [key, entry] of this.#entries) {
93
- clearTimeout(entry.timer);
94
- if (entry.count) {
95
- const [level, code, message] = key.split('\u0000');
96
- this.#write(level, message, code, entry.error, entry.fields, entry.count);
97
- }
98
- }
99
- this.#entries.clear();
100
- }
101
- }