@dokebi/websocket 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/router.js CHANGED
@@ -1,6 +1,8 @@
1
+ import { DokebiError, isDokebiError } from '@dokebi/core';
2
+ import { diagnostics } from '@dokebi/core/libraries';
3
+ import { WebsocketError } from './errors.js';
1
4
  const TYPE = /^[A-Za-z][A-Za-z0-9._:-]{0,63}$/;
2
5
  const ID = /^[A-Za-z0-9._:-]{1,64}$/;
3
- const CODE = /^[A-Z][A-Z0-9_]{0,63}$/;
4
6
  const encoder = new TextEncoder();
5
7
  const decoder = new TextDecoder('utf-8', { fatal: true });
6
8
  function frame(value) {
@@ -14,9 +16,24 @@ function context(session) {
14
16
  broadcast: (type, value, target) => session.broadcast(encoder.encode(frame(value === undefined ? { type } : { type, data: value })), target),
15
17
  });
16
18
  }
17
- function errorCode(error) {
18
- const code = error?.code;
19
- return typeof code === 'string' && CODE.test(code) ? code : 'HANDLER_FAILED';
19
+ /**
20
+ * What an error frame says about a handler failure (D-0063 §1): the code always; for a Dokebi
21
+ * error (a DokebiError, or that shape naming its plugin) also `message` and `hint`, and `fix`
22
+ * outside production. Other errors send their code only: messages and stacks stay in the log.
23
+ */
24
+ function errorFields(error, production) {
25
+ const code = diagnostics.errorCode(error, 'HANDLER_FAILED');
26
+ const known = error instanceof DokebiError || (isDokebiError(error) && typeof error.plugin === 'string')
27
+ ? error
28
+ : undefined;
29
+ if (!known)
30
+ return { code };
31
+ return {
32
+ code,
33
+ message: known.message,
34
+ ...(known.hint === undefined ? {} : { hint: known.hint }),
35
+ ...(production || known.fix === undefined ? {} : { fix: known.fix }),
36
+ };
20
37
  }
21
38
  /**
22
39
  * A WebSocket message router. Messages are JSON `{ type, data?, id? }`. A handler's return value
@@ -28,13 +45,14 @@ function errorCode(error) {
28
45
  export function defineSocket(definition) {
29
46
  const handlers = new Map();
30
47
  if (!definition || typeof definition.on !== 'object' || definition.on === null)
31
- throw new TypeError('Invalid socket definition');
48
+ throw new WebsocketError('INVALID_ROUTE', 'Invalid socket definition');
32
49
  const presence = definition.presence;
50
+ const production = process.env.NODE_ENV === 'production';
33
51
  if (presence !== undefined && typeof presence !== 'boolean' && typeof presence !== 'function')
34
- throw new TypeError('Invalid socket presence');
52
+ throw new WebsocketError('INVALID_ROUTE', 'Invalid socket presence');
35
53
  for (const [type, handler] of Object.entries(definition.on)) {
36
54
  if (!TYPE.test(type) || type === 'reply' || type === 'error' || typeof handler !== 'function')
37
- throw new TypeError('Invalid socket handler: ' + type);
55
+ throw new WebsocketError('INVALID_ROUTE', 'Invalid socket handler: ' + type);
38
56
  handlers.set(type, handler);
39
57
  }
40
58
  return Object.freeze({
@@ -93,9 +111,13 @@ export function defineSocket(definition) {
93
111
  catch (error) {
94
112
  // The client gets the code only; the whole error goes to the session's reporter (the
95
113
  // gateway logs it, D-0047). A session without a reporter is used outside the gateway.
96
- const code = errorCode(error);
97
- session.reportError?.(error, { source: 'handler', code, type: message.type });
98
- return session.send(frame({ type: 'error', ...(id ? { id } : {}), code }));
114
+ const fields = errorFields(error, production);
115
+ session.reportError?.(error, {
116
+ source: 'handler',
117
+ code: fields.code,
118
+ type: message.type,
119
+ });
120
+ return session.send(frame({ type: 'error', ...(id ? { id } : {}), ...fields }));
99
121
  }
100
122
  if (id)
101
123
  await session.send(frame(result === undefined ? { type: 'reply', id } : { type: 'reply', id, data: result }));
@@ -0,0 +1,30 @@
1
+ import type { Logger } from '@dokebi/core';
2
+ import type { WebRealtimeTransport } from '@dokebi/web/points';
3
+ import type { WebsocketApi, WebsocketConnectionInfo, WebsocketKickReceipt, WebsocketPresence, WebsocketReceipt, WebsocketRoute } from './types.js';
4
+ /** Whom a namespace call is about (D-0061): a tenant of the namespace, or all of them. */
5
+ export interface WebsocketNamespaceTarget {
6
+ readonly tenant?: string;
7
+ readonly member?: string;
8
+ readonly room?: string;
9
+ }
10
+ /**
11
+ * The WebSocket operations on one realtime namespace (the hub tenants `<namespace>:<tenant>`):
12
+ * targets name tenants without the prefix and results come back without it.
13
+ */
14
+ export interface WebsocketNamespaceHandle {
15
+ readonly namespace: string;
16
+ list(target?: WebsocketNamespaceTarget): Promise<readonly WebsocketConnectionInfo[]>;
17
+ send(target: WebsocketNamespaceTarget, type: string, data?: unknown): Promise<WebsocketReceipt>;
18
+ kick(target: WebsocketNamespaceTarget, code?: number, reason?: string): Promise<WebsocketKickReceipt>;
19
+ onPresence(listener: (change: WebsocketPresence) => unknown): () => void;
20
+ }
21
+ /** The `websocket` transport contributed to `dokebi-web:realtime` (D-0063 §5). */
22
+ export type WebsocketTransport = WebRealtimeTransport<WebsocketRoute, WebsocketNamespaceHandle> & {
23
+ readonly kind: 'websocket';
24
+ };
25
+ /**
26
+ * What dokebi-app needs to mount WebSocket routes of apps and modules and to reach a namespace,
27
+ * built on the public API: `mount` adds the scope's path, constraints, seal rule and tenant rule
28
+ * to a route; `handle` prefixes targets with `<namespace>:` and strips it from results.
29
+ */
30
+ export declare function websocketTransport(api: WebsocketApi, logger: Logger): WebsocketTransport;
@@ -0,0 +1,72 @@
1
+ import { WebsocketError } from './errors.js';
2
+ const NAMESPACE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
3
+ function target(value) {
4
+ if (value === null || typeof value !== 'object')
5
+ throw new WebsocketError('INVALID_TARGET', 'A namespace target is { tenant?, member?, room? }.');
6
+ return value;
7
+ }
8
+ /**
9
+ * What dokebi-app needs to mount WebSocket routes of apps and modules and to reach a namespace,
10
+ * built on the public API: `mount` adds the scope's path, constraints, seal rule and tenant rule
11
+ * to a route; `handle` prefixes targets with `<namespace>:` and strips it from results.
12
+ */
13
+ export function websocketTransport(api, logger) {
14
+ return Object.freeze({
15
+ kind: 'websocket',
16
+ mount(route, scope) {
17
+ if (route === null || typeof route !== 'object' || typeof route.authenticate !== 'function')
18
+ throw new WebsocketError('INVALID_ROUTE', 'Invalid websocket route');
19
+ const own = route.seal;
20
+ const sealed = scope.seal;
21
+ api.route({
22
+ ...route,
23
+ path: scope.path,
24
+ constraints: { ...(route.constraints ?? {}), ...scope.constraints },
25
+ // The request's host decides (D-0059 §4) besides the route's own setting.
26
+ ...(sealed
27
+ ? {
28
+ seal: (request) => sealed(request) || own === true || (typeof own === 'function' && own(request)),
29
+ }
30
+ : {}),
31
+ authenticate: async (request) => {
32
+ const identity = await route.authenticate(request);
33
+ return identity ? scope.identity(identity) : undefined;
34
+ },
35
+ });
36
+ if (logger.isEnabled('debug'))
37
+ logger.log('debug', 'WebSocket route mounted by the realtime point', {
38
+ path: scope.path,
39
+ sealed: sealed !== undefined,
40
+ });
41
+ },
42
+ handle(namespace) {
43
+ if (typeof namespace !== 'string' || !NAMESPACE.test(namespace))
44
+ throw new WebsocketError('INVALID_TARGET', 'A realtime namespace is a name of 1 to 64 characters.');
45
+ const prefix = `${namespace}:`;
46
+ const filter = (input) => {
47
+ const { tenant, member, room } = target(input);
48
+ return {
49
+ ...(tenant === undefined ? { tenantPrefix: prefix } : { tenant: prefix + tenant }),
50
+ ...(room === undefined ? {} : { room }),
51
+ ...(member === undefined ? {} : { member }),
52
+ };
53
+ };
54
+ return Object.freeze({
55
+ namespace,
56
+ list: async (input = {}) => {
57
+ const connections = await api.list(filter(input));
58
+ return Object.freeze(connections.map((connection) => Object.freeze({ ...connection, tenant: connection.tenant.slice(prefix.length) })));
59
+ },
60
+ send: async (input, type, data) => api.send(filter(input), type, data),
61
+ kick: async (input, code, reason) => api.kick(filter(input), code, reason),
62
+ onPresence: (listener) => {
63
+ if (typeof listener !== 'function')
64
+ throw new WebsocketError('INVALID_ARGUMENT', 'Invalid presence listener');
65
+ return api.onPresence((change) => change.tenant.startsWith(prefix)
66
+ ? listener(Object.freeze({ ...change, tenant: change.tenant.slice(prefix.length) }))
67
+ : undefined);
68
+ },
69
+ });
70
+ },
71
+ });
72
+ }
@@ -3,41 +3,68 @@
3
3
  "type": "object",
4
4
  "additionalProperties": false,
5
5
  "properties": {
6
+ "maxPayloadBytes": {
7
+ "type": "integer",
8
+ "minimum": 1,
9
+ "maximum": 67108864,
10
+ "default": 65536,
11
+ "description": "Largest incoming frame in bytes."
12
+ },
6
13
  "maxPayload": {
7
14
  "type": "integer",
8
15
  "minimum": 1,
9
16
  "maximum": 67108864,
10
- "default": 65536
17
+ "deprecated": true,
18
+ "description": "Deprecated name of maxPayloadBytes; use that key."
11
19
  },
12
20
  "maxConnections": {
13
21
  "type": "integer",
14
22
  "minimum": 1,
15
23
  "maximum": 67108864,
16
- "default": 128
24
+ "default": 128,
25
+ "description": "Open connections this process accepts at most."
26
+ },
27
+ "maxPending": {
28
+ "type": "integer",
29
+ "minimum": 1,
30
+ "maximum": 67108864,
31
+ "default": 32,
32
+ "description": "Messages of one connection waiting for its handler at most."
17
33
  },
18
34
  "maxPendingMessages": {
19
35
  "type": "integer",
20
36
  "minimum": 1,
21
37
  "maximum": 67108864,
22
- "default": 32
38
+ "deprecated": true,
39
+ "description": "Deprecated name of maxPending; use that key."
23
40
  },
24
41
  "maxBufferedBytes": {
25
42
  "type": "integer",
26
43
  "minimum": 1,
27
44
  "maximum": 67108864,
28
- "default": 1048576
45
+ "default": 1048576,
46
+ "description": "Bytes waiting to be sent to one connection at most; a slower client is closed (SLOW_CONSUMER)."
47
+ },
48
+ "shutdownTimeoutMs": {
49
+ "type": "integer",
50
+ "minimum": 1,
51
+ "maximum": 67108864,
52
+ "default": 2000,
53
+ "description": "How long drain waits for closing connections (1012) before it cuts them, in ms."
29
54
  },
30
55
  "closeTimeoutMs": {
31
56
  "type": "integer",
32
57
  "minimum": 1,
33
58
  "maximum": 67108864,
34
- "default": 2000
59
+ "deprecated": true,
60
+ "description": "Deprecated name of shutdownTimeoutMs; use that key."
35
61
  },
36
62
  "heartbeatMs": {
37
63
  "type": "integer",
38
64
  "minimum": 1,
39
65
  "maximum": 67108864,
40
- "default": 10000
66
+ "default": 10000,
67
+ "description": "Interval of WebSocket pings, in ms."
41
68
  },
42
69
  "idleTimeoutMs": {
43
70
  "type": "integer",
package/package.json CHANGED
@@ -1,6 +1,14 @@
1
1
  {
2
2
  "name": "@dokebi/websocket",
3
- "version": "0.3.0",
3
+ "version": "0.4.0",
4
+ "description": "WebSocket routes on @dokebi/web with rooms and broadcast across servers through @dokebi/websocket-hub.",
5
+ "keywords": [
6
+ "dokebi",
7
+ "dokebi-plugin",
8
+ "web",
9
+ "websocket",
10
+ "realtime"
11
+ ],
4
12
  "private": false,
5
13
  "type": "module",
6
14
  "license": "MIT",
@@ -23,45 +31,60 @@
23
31
  "node": ">=24.0.0"
24
32
  },
25
33
  "scripts": {
26
- "build": "tsc -p tsconfig.json",
34
+ "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",
27
35
  "typecheck": "tsc -p tsconfig.test.json --noEmit",
28
- "test": "tsc -p tsconfig.test.json && node --test \".tmp/tests/tests/*.test.js\""
36
+ "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\""
29
37
  },
30
38
  "dependencies": {
31
39
  "@fastify/websocket": "11.3.4",
32
40
  "ws": "8.22.0"
33
41
  },
34
42
  "peerDependencies": {
35
- "@dokebi/core": "^0.2.0",
36
- "@dokebi/web": "^0.1.0 || ^0.2.0",
37
- "@dokebi/websocket-hub": "^0.3.0"
43
+ "@dokebi/core": "^0.4.0",
44
+ "@dokebi/web": "^0.4.0",
45
+ "@dokebi/websocket-hub": "^0.4.0"
38
46
  },
39
47
  "devDependencies": {
40
- "@dokebi/web": "0.2.0",
41
- "@dokebi/websocket-hub": "0.3.0"
48
+ "@dokebi/web": "0.4.0",
49
+ "@dokebi/websocket-hub": "0.4.0"
42
50
  },
43
51
  "dokebi": {
44
52
  "schemaVersion": 2,
45
53
  "id": "dokebi-websocket",
46
- "core": "^0.2.0",
54
+ "core": "^0.4.0",
47
55
  "dependencies": [
48
56
  {
49
57
  "name": "dokebi-websocket-hub",
50
- "version": "^0.3.0"
58
+ "version": "^0.4.0"
51
59
  },
52
60
  {
53
61
  "name": "dokebi-web",
54
- "version": "^0.1.0 || ^0.2.0"
62
+ "version": "^0.4.0"
55
63
  },
56
64
  {
57
65
  "name": "dokebi-seal",
58
- "version": "^0.1.0",
66
+ "version": "^0.4.0",
59
67
  "optional": true
60
68
  }
61
69
  ],
70
+ "contributes": [
71
+ "dokebi-web:realtime"
72
+ ],
62
73
  "optionsSchema": "options.schema.json",
63
74
  "documentation": "AI.md"
64
75
  },
76
+ "dokebiCatalog": {
77
+ "kind": "plugin",
78
+ "summary": "WebSocket routes, rooms and broadcast on top of dokebi-web (at most once)",
79
+ "maturity": "preview",
80
+ "provides": [
81
+ "realtime.websocket"
82
+ ],
83
+ "doesNot": [
84
+ "No delivery ACK or redelivery"
85
+ ],
86
+ "recipes": []
87
+ },
65
88
  "publishConfig": {
66
89
  "access": "public",
67
90
  "registry": "https://registry.npmjs.org/"
package/dist/log.d.ts DELETED
@@ -1,25 +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, ws 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 (and `group`, when given) are counted and reported together
13
- * (`repeated`) when the interval ends. `group` must come from a bounded set (e.g. registered
14
- * handler types), never from client input, since each value keeps an entry for an interval. Hot paths (per message, per frame) can report every failure without a burst
15
- * flooding the log. Field and error text are built only for lines that are written.
16
- */
17
- export declare class LogThrottle {
18
- #private;
19
- readonly logger: Logger;
20
- readonly intervalMs: number;
21
- constructor(logger: Logger, intervalMs?: number);
22
- report(level: LogLevel, message: string, code: string, error?: unknown, fields?: LogFields, group?: string): void;
23
- /** Writes the counts still pending (on close), so a burst at shutdown is not lost. */
24
- flush(): void;
25
- }
package/dist/log.js DELETED
@@ -1,102 +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, ws 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 (and `group`, when given) are counted and reported together
40
- * (`repeated`) when the interval ends. `group` must come from a bounded set (e.g. registered
41
- * handler types), never from client input, since each value keeps an entry for an interval. Hot paths (per message, per frame) can report every failure without a burst
42
- * flooding the log. Field and error text are built only for lines that are written.
43
- */
44
- export class LogThrottle {
45
- logger;
46
- intervalMs;
47
- #entries = new Map();
48
- constructor(logger, intervalMs = 10_000) {
49
- this.logger = logger;
50
- this.intervalMs = intervalMs;
51
- }
52
- report(level, message, code, error, fields, group) {
53
- if (!this.logger.isEnabled(level))
54
- return;
55
- const key = `${level}\u0000${code}\u0000${message}${group === undefined ? '' : `\u0000${group}`}`;
56
- const entry = this.#entries.get(key);
57
- if (entry) {
58
- entry.count++;
59
- entry.error = error;
60
- entry.fields = fields;
61
- return;
62
- }
63
- this.#write(level, message, code, error, fields, 0);
64
- const value = {
65
- count: 0,
66
- error: undefined,
67
- fields: undefined,
68
- timer: setTimeout(() => this.#elapsed(key, value, level, message, code), this.intervalMs),
69
- };
70
- value.timer.unref();
71
- this.#entries.set(key, value);
72
- }
73
- #elapsed(key, entry, level, message, code) {
74
- if (!entry.count) {
75
- this.#entries.delete(key);
76
- return;
77
- }
78
- this.#write(level, message, code, entry.error, entry.fields, entry.count);
79
- entry.count = 0;
80
- entry.timer = setTimeout(() => this.#elapsed(key, entry, level, message, code), this.intervalMs);
81
- entry.timer.unref();
82
- }
83
- #write(level, message, code, error, fields, repeated) {
84
- this.logger.log(level, message, {
85
- ...fields,
86
- code,
87
- ...(error === undefined ? {} : { error: errorText(error) }),
88
- ...(repeated ? { repeated, intervalMs: this.intervalMs } : {}),
89
- });
90
- }
91
- /** Writes the counts still pending (on close), so a burst at shutdown is not lost. */
92
- flush() {
93
- for (const [key, entry] of this.#entries) {
94
- clearTimeout(entry.timer);
95
- if (entry.count) {
96
- const [level, code, message] = key.split('\u0000');
97
- this.#write(level, message, code, entry.error, entry.fields, entry.count);
98
- }
99
- }
100
- this.#entries.clear();
101
- }
102
- }