@dokebi/websocket-hub 0.4.3 → 0.4.4
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 +2 -2
- package/dist/index.js +13 -2
- package/dist/server-id.d.ts +21 -0
- package/dist/server-id.js +25 -0
- package/package.json +3 -3
package/AI.md
CHANGED
|
@@ -20,7 +20,7 @@ The API and broadcast semantics (at most once) are the same in both modes. `mode
|
|
|
20
20
|
dokebi-websocket-hub:
|
|
21
21
|
mode: cluster
|
|
22
22
|
namespace: shop # servers of the same namespace share a hub
|
|
23
|
-
serverId: web-a # different per server
|
|
23
|
+
serverId: web-a # different per server; cluster workers append -w<slot>
|
|
24
24
|
host: 0.0.0.0 # hub TCP listen address
|
|
25
25
|
port: 0
|
|
26
26
|
advertiseHost: web-a.internal # the address other servers use to reach this server's hub
|
|
@@ -119,7 +119,7 @@ Without `--config` it reads the file `DOKEBI_CONFIG` names (the one the app read
|
|
|
119
119
|
|
|
120
120
|
- Never trust tenant, member or rooms sent by the client (the authentication function decides them).
|
|
121
121
|
- The secret lives only in dokebi.yaml, at least 32 random bytes. Every server of a namespace uses the same secret, options and Redis/NATS.
|
|
122
|
-
- Each server needs a different `serverId` and an `advertiseHost` and TCP port reachable from other servers (firewalls). The hub TCP has no built-in TLS; use a trusted private network or an encrypted tunnel.
|
|
122
|
+
- Each server needs a different `serverId` and an `advertiseHost` and TCP port reachable from other servers (firewalls). The workers of one server share its `serverId` in dokebi.yaml; since 0.4.4 each worker in cluster mode uses `<serverId>-w<slot>`, so `status()`, `dokebi-hub-status` and the logs count and name every worker: the slot of @dokebi/cluster (`DOKEBI_CLUSTER_SLOT`, kept by the worker that replaces another one), a pm2 instance (`NODE_APP_INSTANCE` with pm2's `pm_id`; a single instance keeps the plain id), or the worker id of a plain node:cluster worker. One process keeps the configured id; a worker logs debug `WebSocket hub serverId of this worker` (`configured`, `serverId`). A serverId already set per worker gets the suffix as well. The hub TCP has no built-in TLS; use a trusted private network or an encrypted tunnel.
|
|
123
123
|
- Never close the hub, Redis or NATS before the whole drain (core ordering ensures it).
|
|
124
124
|
- **Operations ([D-0049](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0049-redis-rejections-and-eviction.md))**: Redis for cluster mode uses `maxmemory-policy noeviction`. With an evicting policy the leader key gets evicted and the hub goes through `STALE_LEADER` and `RECOVERING` (OPS-002 G). Put caches on a separate Redis (`allkeys-lru`). At node start it reads `CONFIG GET maxmemory*` once; with `maxmemory > 0` and a policy other than `noeviction` it logs **error `REDIS_EVICTION_UNSAFE`** (`policy`, `maxmemory`, `connection`) and **starts anyway** (an operator may accept the risk). When safe, debug `REDIS_EVICTION_CHECKED`; a managed Redis or ACL that blocks CONFIG gives debug `REDIS_EVICTION_CHECK_SKIPPED` (`reason: rejected` + the full `error`); an older @dokebi/redis the same code (`reason: unsupported`); any other failure error `REDIS_EVICTION_CHECK_FAILED`. Redis error replies (OOM and so on) now stay as `COMMAND_REJECTED` with the server reply in the cause of `STORE_UNAVAILABLE`.
|
|
125
125
|
- Logs ([D-0047](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0047-logging-and-no-silent-errors.md)): exceptions are never dropped silently. Failures that cannot be turned into a defined error or response code are logged at `error`: a fixed English message + `code` + `error` (the full original error: name, whole message, stack and `Caused by: …` for each cause, address, port and errno text included; only URL credentials masked as `//***@`; cut only beyond 16 KB). Examples: a lost leader connection other than a closed socket `Hub connection dropped` (debug when the node itself closed it with `RECOVERING` or `CLOSED`, during `bye`, or after the leader announced `leaving` — D-0056), recovery start after a Redis or protocol failure `Hub transport or store unavailable; recovering`, a failover that takes longer than its bound (below), peer send failure `PEER_SEND_FAILED` (backpressure included), peer socket and frame `PEER_SOCKET_ERROR` (on the leader side; on the leader connection of a peer it becomes the cause of the failover's `DISCONNECTED`), `PEER_FRAME_REJECTED` (a socket error before hello is debug `Hub peer connection failed before it was established`, and the startup retry or recovery log reports it with the cause), when the leader vanished first and `bye` could not be sent but Redis `leave` worked, debug `Hub goodbye not delivered; left through Redis` (a successful stop), a leader of another version `PROTOCOL_MISMATCH` (error; the refusing leader logs warn), removed options `OPTION_REMOVED` (warn, once per key at start), NATS `NATS_PUBLISH_FAILED`, `NATS_SUBSCRIPTION_FAILED` (the control subscription that a full connection buffer or an oversized message ended is opened again at once, followed by a poll, and logged once per `logRepeatWindowMs` with `reason` and `repeated`; any other end leaves Redis polling alone), local event queue overflow `EVENT_OVERFLOW`, a roster change the leader answered that this server could not take (its `Replaced` kick did not fit the event queue) `ROSTER_COMMIT_FAILED` (the changes of that batch are refused, never left waiting, and the server reconnects unless it is closing), a Redis failure of `status()` `STATUS_UNREACHABLE`. Redis failures stay as the `cause` of `STORE_UNAVAILABLE`. Places that run per frame or message write the same message and code once per interval (10 seconds) and group the rest as a `repeated` count (the remaining count is written at shutdown too). Bodies, secrets and tokens are never logged.
|
package/dist/index.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { definePlugin, providerDependency } from '@dokebi/core';
|
|
2
2
|
import { LocalHub } from './local.js';
|
|
3
3
|
import { options as declaration } from './options.js';
|
|
4
|
+
import { workerServerId } from './server-id.js';
|
|
4
5
|
import { HubError } from './types.js';
|
|
5
6
|
export * from './types.js';
|
|
6
7
|
// Local descriptors, not '@dokebi/redis/dependency' or '@dokebi/nats/dependency': both are
|
|
@@ -57,7 +58,17 @@ class HubRuntime {
|
|
|
57
58
|
}
|
|
58
59
|
// Cluster mode only: the node, its leader and peer client load here, not with the local hub.
|
|
59
60
|
const { HubNode } = await import('./node.js');
|
|
60
|
-
|
|
61
|
+
// The workers of one server share dokebi.yaml and so its serverId: each takes its own
|
|
62
|
+
// (`-w<slot>`), so status, metrics and logs tell them apart (shop 2026-11-21).
|
|
63
|
+
const serverId = workerServerId(options.serverId, process.env, context.runtime.role === 'worker'
|
|
64
|
+
? process.getBuiltinModule('node:cluster').worker?.id
|
|
65
|
+
: undefined);
|
|
66
|
+
if (serverId !== options.serverId)
|
|
67
|
+
context.logger.log('debug', 'WebSocket hub serverId of this worker', {
|
|
68
|
+
configured: options.serverId,
|
|
69
|
+
serverId,
|
|
70
|
+
});
|
|
71
|
+
const node = new HubNode(context, serverId === options.serverId ? options : { ...options, serverId }, context.getDependency(redis).connection(options.redisConnection), options.natsConnection === undefined
|
|
61
72
|
? undefined
|
|
62
73
|
: context.getDependency(nats).connection(options.natsConnection));
|
|
63
74
|
context.defer(() => node.close());
|
|
@@ -75,7 +86,7 @@ class HubRuntime {
|
|
|
75
86
|
/** Factory input: `{ app, options? }`. Options default to `app.config['dokebi-websocket-hub']`. */
|
|
76
87
|
export const createPlugin = definePlugin({
|
|
77
88
|
name: 'dokebi-websocket-hub',
|
|
78
|
-
version: '0.4.
|
|
89
|
+
version: '0.4.4',
|
|
79
90
|
core: '^0.4.2',
|
|
80
91
|
options: declaration,
|
|
81
92
|
// local: nothing. cluster: Redis, and NATS only when natsConnection is set (D-0029).
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
/** Environment values that say where this process stands among the workers of one server. */
|
|
2
|
+
export interface WorkerEnv {
|
|
3
|
+
readonly DOKEBI_CLUSTER_SLOT?: string | undefined;
|
|
4
|
+
readonly NODE_APP_INSTANCE?: string | undefined;
|
|
5
|
+
readonly pm_id?: string | undefined;
|
|
6
|
+
readonly instances?: string | undefined;
|
|
7
|
+
}
|
|
8
|
+
/**
|
|
9
|
+
* The serverId this process uses in cluster mode (shop 2026-11-21). The workers of one server
|
|
10
|
+
* read the same dokebi.yaml, so they share its `serverId`; the hub status would count them as one
|
|
11
|
+
* server. Each worker therefore appends its place, `-w<slot>`, the same way @dokebi/logger names
|
|
12
|
+
* its files:
|
|
13
|
+
* - @dokebi/cluster: `DOKEBI_CLUSTER_SLOT` (0 to workers − 1, kept by the worker that replaces
|
|
14
|
+
* another one, so a restarted worker takes its predecessor's name);
|
|
15
|
+
* - pm2: `NODE_APP_INSTANCE` together with pm2's own `pm_id` (an app may set NODE_APP_INSTANCE
|
|
16
|
+
* itself); a single pm2 instance is one process and keeps the configured id;
|
|
17
|
+
* - a plain node:cluster worker: its worker id (it grows with every restart).
|
|
18
|
+
* One process keeps the configured id. The peer protocol takes ids up to 256 bytes, so the
|
|
19
|
+
* suffix fits behind the 64 characters the option allows.
|
|
20
|
+
*/
|
|
21
|
+
export declare function workerServerId(serverId: string, env: WorkerEnv, clusterWorkerId: number | undefined): string;
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
const SLOT = /^\d{1,6}$/;
|
|
2
|
+
/**
|
|
3
|
+
* The serverId this process uses in cluster mode (shop 2026-11-21). The workers of one server
|
|
4
|
+
* read the same dokebi.yaml, so they share its `serverId`; the hub status would count them as one
|
|
5
|
+
* server. Each worker therefore appends its place, `-w<slot>`, the same way @dokebi/logger names
|
|
6
|
+
* its files:
|
|
7
|
+
* - @dokebi/cluster: `DOKEBI_CLUSTER_SLOT` (0 to workers − 1, kept by the worker that replaces
|
|
8
|
+
* another one, so a restarted worker takes its predecessor's name);
|
|
9
|
+
* - pm2: `NODE_APP_INSTANCE` together with pm2's own `pm_id` (an app may set NODE_APP_INSTANCE
|
|
10
|
+
* itself); a single pm2 instance is one process and keeps the configured id;
|
|
11
|
+
* - a plain node:cluster worker: its worker id (it grows with every restart).
|
|
12
|
+
* One process keeps the configured id. The peer protocol takes ids up to 256 bytes, so the
|
|
13
|
+
* suffix fits behind the 64 characters the option allows.
|
|
14
|
+
*/
|
|
15
|
+
export function workerServerId(serverId, env, clusterWorkerId) {
|
|
16
|
+
const slot = env.DOKEBI_CLUSTER_SLOT;
|
|
17
|
+
if (slot !== undefined && SLOT.test(slot))
|
|
18
|
+
return `${serverId}-w${slot}`;
|
|
19
|
+
const instance = env.NODE_APP_INSTANCE;
|
|
20
|
+
if (env.pm_id !== undefined && instance !== undefined && SLOT.test(instance))
|
|
21
|
+
return env.instances === '1' ? serverId : `${serverId}-w${instance}`;
|
|
22
|
+
if (clusterWorkerId !== undefined)
|
|
23
|
+
return `${serverId}-w${clusterWorkerId}`;
|
|
24
|
+
return serverId;
|
|
25
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@dokebi/websocket-hub",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.4",
|
|
4
4
|
"description": "WebSocket hub for Dokebi: connection roster, rooms, broadcast and kick across workers and servers.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"dokebi",
|
|
@@ -48,8 +48,8 @@
|
|
|
48
48
|
"@dokebi/redis": "^0.4.0"
|
|
49
49
|
},
|
|
50
50
|
"devDependencies": {
|
|
51
|
-
"@dokebi/nats": "0.4.
|
|
52
|
-
"@dokebi/redis": "0.4.
|
|
51
|
+
"@dokebi/nats": "0.4.3",
|
|
52
|
+
"@dokebi/redis": "0.4.2"
|
|
53
53
|
},
|
|
54
54
|
"dokebi": {
|
|
55
55
|
"schemaVersion": 2,
|