@dokebi/websocket-hub 0.3.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/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.0",
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
- }