@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 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: `examples/18-websocket-hub` (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).
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
- const node = new HubNode(context, options, context.getDependency(redis).connection(options.redisConnection), options.natsConnection === undefined
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.2',
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
- #queue(fn) {
126
- if (this.#pending >= this.options.maxPending) {
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.2",
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.1",
52
- "@dokebi/redis": "0.4.1"
51
+ "@dokebi/nats": "0.4.3",
52
+ "@dokebi/redis": "0.4.2"
53
53
  },
54
54
  "dokebi": {
55
55
  "schemaVersion": 2,