@dokebi/websocket-hub 0.4.2 → 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 +3 -3
- package/dist/index.js +13 -2
- package/dist/leader.js +11 -4
- 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.
|
|
@@ -128,4 +128,4 @@ Without `--config` it reads the file `DOKEBI_CONFIG` names (the one the app read
|
|
|
128
128
|
- `dokebi-hub-status` writes the cause of a Redis failure to stderr (the stdout JSON stays as it is).
|
|
129
129
|
- Extension hooks for the hub are listed as candidates in [D-0064](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0064-extension-contract.md) §9; there is no extension class yet.
|
|
130
130
|
|
|
131
|
-
Evidence: `
|
|
131
|
+
Evidence: `tests/integration.test.ts` (real TCP peers, leader handover), `examples/23-websocket`, `examples/25-playground`, `tests/status.test.ts` (status, nonces, the command), D-0024, D-0029, D-0034, D-0038, D-0057 (replacing the ACK and resend of D-0025 and D-0042).
|
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).
|
package/dist/leader.js
CHANGED
|
@@ -122,8 +122,15 @@ export class Leader {
|
|
|
122
122
|
throw new HubError('STALE_LEADER');
|
|
123
123
|
return now;
|
|
124
124
|
}
|
|
125
|
-
|
|
126
|
-
|
|
125
|
+
/**
|
|
126
|
+
* Runs `fn` after the requests before it. `maxPending` bounds what peers ask for (BUSY); the
|
|
127
|
+
* leader's `own` work — its lease tick, and removing a server whose socket closed — waits its
|
|
128
|
+
* turn whatever the queue holds: refused as BUSY it read as a lost lease, and the node stopped
|
|
129
|
+
* its leader and dropped every peer in the middle of the load (audit R9-g11-3). It is bounded
|
|
130
|
+
* by itself: one tick at a time (the node), one removal per peer socket (`maxOwners`).
|
|
131
|
+
*/
|
|
132
|
+
#queue(fn, own = false) {
|
|
133
|
+
if (!own && this.#pending >= this.options.maxPending) {
|
|
127
134
|
this.#throttle.log('debug', 'Hub leader queue full; request refused', 'BUSY', undefined, {
|
|
128
135
|
pending: this.#pending,
|
|
129
136
|
});
|
|
@@ -187,7 +194,7 @@ export class Leader {
|
|
|
187
194
|
void this.#queue(async () => {
|
|
188
195
|
await this.#renew();
|
|
189
196
|
await this.#remove(peer.owner, peer.session);
|
|
190
|
-
}).catch((error) => {
|
|
197
|
+
}, true).catch((error) => {
|
|
191
198
|
// Lease lost or Redis down: another server takes over and expires the owner.
|
|
192
199
|
this.logger.log('error', 'Hub leader could not remove a disconnected server', {
|
|
193
200
|
code: 'OWNER_REMOVE_FAILED',
|
|
@@ -691,7 +698,7 @@ export class Leader {
|
|
|
691
698
|
return this.#queue(async () => {
|
|
692
699
|
const now = await this.#renew();
|
|
693
700
|
await this.#expire(now);
|
|
694
|
-
});
|
|
701
|
+
}, true);
|
|
695
702
|
}
|
|
696
703
|
async stop() {
|
|
697
704
|
if (this.#active)
|
|
@@ -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,
|