@dokebi/websocket-hub 0.2.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/AI.md CHANGED
@@ -1,76 +1,123 @@
1
- # AI 작업 안내 — @dokebi/websocket-hub 0.2.0
1
+ # AI guide — @dokebi/websocket-hub 0.4.0
2
2
 
3
- WebSocket 접속자 목록·방·방송·kick·수신 ACK를 관리하는 허브다(옛 `dokebi-sync`를 대체). 보통 **@dokebi/websocket이 단독으로 쓰고**, 앱 코드는 websocket의 `defineSocket`을 쓴다. 직접 쓰는 일은 운영 상태 조회(`status()`, `dokebi-hub-status`)와 봉인 프레임 재생 방어(`nonces()`) 정도다. Node >=24, core ^0.2.0, peer: @dokebi/redis·@dokebi/nats(cluster 모드). 세부는 [README](README.md)다.
3
+ The hub that manages WebSocket connection lists, rooms, broadcasts and kicks (it replaces the old `dokebi-sync`). A broadcast is **at most once**, with no receipt ACK or resend ([D-0057](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0057-websocket-broadcast-without-ack.md)). Usually **@dokebi/websocket uses it alone**, and app code uses websocket's `defineSocket`. Direct use is mostly operational status (`status()`, `dokebi-hub-status`) and replay defense for sealed frames (`nonces()`). Node >=24, core ^0.4.0, peers: @dokebi/redis, @dokebi/nats (cluster mode). Details are in the [README](README.md).
4
4
 
5
- ## 1. 모드(D-0029)
5
+ ## 1. Modes ([D-0029](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0029-hub-and-cluster-infrastructure.md))
6
6
 
7
- | | `mode: local`(기본) | `mode: cluster` |
7
+ | | `mode: local` (default) | `mode: cluster` |
8
8
  |---|---|---|
9
- | 범위 | 프로세스 하나(메모리) | 여러 프로세스·서버 공유 |
10
- | 필요 | 없음 | Redis(필수), NATS(선택: 리더 변경 즉시 알림, 없으면 Redis 폴링) |
11
- | 장애 | 미완료 메시지는 프로세스와 함께 사라짐 | 모든 워커가 허브 후보, Redis 임대로 리더 선출, 리더가 죽어도 실제 소켓은 유지되고 새 허브로 재접속 |
12
- | cluster 워커 | `HUB_LOCAL_IN_CLUSTER`로 거부(`allowInCluster: true`로만 허용) | 정상 |
9
+ | Scope | one process (memory) | shared by processes and servers |
10
+ | Needs | nothing | Redis (required), NATS (optional: instant leader change notices; otherwise Redis polling) |
11
+ | Failure | state disappears with the process, no handover | every worker is a hub candidate, the leader is elected by a Redis lease, and when the leader dies real sockets stay and reconnect to the new hub |
12
+ | cluster workers | refused with `LOCAL_IN_CLUSTER` (allowed only with `allowInCluster: true`) | normal |
13
13
 
14
- API와 ACK 의미는 두 모드가 같다.
14
+ The API and broadcast semantics (at most once) are the same in both modes. `mode` keeps its name in 0.4.0: it names the deployment style, not a driver ([D-0071](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0071-option-vocabulary.md)).
15
15
 
16
- ## 2. 설정 `options.dokebi-websocket-hub`
16
+ ## 2. Configuration `options.dokebi-websocket-hub`
17
17
 
18
18
  ```yaml
19
19
  dokebi-websocket-hub:
20
20
  mode: cluster
21
- namespace: shop # 같은 namespace의 서버끼리 허브를 공유
22
- serverId: web-a # 서버마다 다르게
23
- host: 0.0.0.0 # 허브 TCP 수신 주소
21
+ namespace: shop # servers of the same namespace share a hub
22
+ serverId: web-a # different per server
23
+ host: 0.0.0.0 # hub TCP listen address
24
24
  port: 0
25
- advertiseHost: web-a.internal # 다른 서버가 이 서버의 허브에 붙을 주소
25
+ advertiseHost: web-a.internal # the address other servers use to reach this server's hub
26
26
  redisConnection: primary
27
- natsConnection: primary # 선택
28
- secret: (32바이트 이상 무작위, dokebi.yaml에만) # 같은 namespace는 같은 secret
27
+ natsConnection: primary # optional
28
+ secret: (32+ random bytes, only in dokebi.yaml) # the same secret for the same namespace
29
29
  ```
30
30
 
31
- | 키 | 기본 | 뜻 |
32
- |---|---|---|
33
- | `leaseMs` / `pollMs` | 3000 / 500 | 리더 임대 / NATS 없을 때 폴링 |
34
- | `ownerTtlMs` / `startupMs` | 15000 / 15000 | 서버 등록 만료 / 시작 대기 |
35
- | `maxFrameBytes` / `maxPayloadBytes` | 1048576 / 65536 | 허브 TCP 프레임 / 메시지 |
36
- | `maxConnections` / `maxOwners` / `maxTotalConnections` | 128 / 64 / 8192 | 서버별·서버 수·전체 연결 |
37
- | `maxPending` / `queueBytes` | 128 / 4194304 | 대기 상한 |
38
- | `deliveryTimeoutMs` / `retryMs` | 60000 / 1000 | 방송 ACK 기한 / 재전송 간격 |
39
- | `maxDeliveries` / `deliveryBytes` | 10000 / 67108864 | 미완료 방송 보관 상한 |
31
+ | Key | Type | Default | Description |
32
+ |---|---|---|---|
33
+ | `mode` | `local` \| `cluster` | `local` | §1 |
34
+ | `allowInCluster` | boolean | false | Allow local mode in a cluster worker |
35
+ | `namespace` / `serverId` | string ≤ 64 | `local` / `local` | Shared area / this server's id (`^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$`) |
36
+ | `redisConnection` / `natsConnection` | string | — | dokebi-redis (required in cluster) / dokebi-nats (optional) connection names |
37
+ | `host` / `advertiseHost` / `port` | string / string / integer 0–65535 | `127.0.0.1` / `127.0.0.1` / 0 | Hub TCP listen address, address announced to peers, port (0 = any) |
38
+ | `secret` | string, secret | — (required in cluster) | 32–256 characters and 32–256 bytes |
39
+ | `leaseMs` / `pollIntervalMs` | integer ms | 3000 / 500 | Leader lease / polling without NATS |
40
+ | `ownerTtlMs` / `startupTimeoutMs` | integer ms | 15000 / 15000 | Server registration expiry / startup wait |
41
+ | `maxFrameBytes` / `maxPayloadBytes` | integer | 1048576 / 65536 | Hub TCP frame / message |
42
+ | `maxConnections` / `maxOwners` / `maxTotalConnections` | integer | 128 / 64 / 8192 | Per server / number of servers / all connections |
43
+ | `maxPending` / `maxPendingBytes` | integer | 128 / 4194304 | Pending limits (more broadcasts in progress than this give `BUSY`) |
44
+
45
+ Keys renamed in 0.4.0 (D-0071). The old name is accepted with the warning `OPTION_DEPRECATED`; old and new together fail with `INVALID_OPTIONS`; 0.5.0 rejects it.
46
+
47
+ | Old key | New key |
48
+ |---|---|
49
+ | `pollMs` | `pollIntervalMs` |
50
+ | `startupMs` | `startupTimeoutMs` |
51
+ | `queueBytes` | `maxPendingBytes` |
52
+
53
+ **Removed options (0.3.0, D-0057)**: `deliveryTimeoutMs`, `retryMs`, `maxDeliveries`, `deliveryBytes`. Start still works when they remain in dokebi.yaml: each key logs warn `OPTION_REMOVED` (`option`, `reason`; since 0.4.0 core logs it at setup) once and the value is ignored (the schema keeps them as deprecated until the next version drops them). Delete them.
54
+
55
+ **Checks (0.4.0, [D-0063](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0063-core-primitives.md))**: the options are one `defineOptions` declaration in `src/options.ts` that is the parser, and `options.schema.json` is generated from it at build time. Rules that only the hand parser used to keep are in the schema now: connection names (`namespace`, `serverId`, `redisConnection`, `natsConnection`) `^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$`, no spaces or control characters in `host` and `advertiseHost`, and the defaults the parser filled in (`namespace` and `serverId` = `local`, `host` and `advertiseHost` = `127.0.0.1`). Cross-field rules are unchanged: `pollIntervalMs × 3 ≤ leaseMs`, `ownerTtlMs ≥ leaseMs × 3`, base64(`maxPayloadBytes`) + 8192 ≤ `maxFrameBytes`, `maxPendingBytes ≥ maxFrameBytes`. `secret` must be 32–256 **characters** and 32–256 **bytes** (the old schema counted characters, the parser only bytes). On failure the core `INVALID_OPTIONS` is the cause of `INVALID_PLUGIN_OPTIONS`, with paths and issue codes in `details.issues` (no values): `REDIS_REQUIRED` in cluster mode without a Redis connection, `SECRET_REQUIRED` when the secret is missing or has the wrong byte count, otherwise `required`, `pattern`, `check` and so on.
56
+
57
+ While a server with different settings (secret, limits) is alive in the same namespace, a new one is refused at once with `CONFIG_MISMATCH`; once every server with the old settings is down, the new settings take over.
40
58
 
41
- 같은 namespace에서 설정(secret·한도)이 다른 서버가 살아 있으면 `CONFIG_MISMATCH`로 즉시 거부하고, 옛 설정의 서버가 모두 내려가면 새 설정으로 바뀐다.
59
+ ## 3. API (`import { dependency } from '@dokebi/websocket-hub/dependency'` → `getDependency`)
42
60
 
43
- ## 3. API(`import { dependency } from '@dokebi/websocket-hub'` → `getDependency`)
61
+ The provider descriptor lives in the subpath `@dokebi/websocket-hub/dependency` (D-0063 §6; a small module that loads neither the hub nor Redis nor NATS), and the package entry's `dependency` is the same object. Plugins and app code that always install the hub use the subpath. When the hub is optional (an optional peer), do not import it; keep `optionalDependency({ name: 'dokebi-websocket-hub', version: '^0.4.0' })` in your own file.
44
62
 
45
- - `state`(starting·ready·recovering·closing·closed), `role`(active·standby), `leader`, `whenReady(timeoutMs)` → boolean.
46
- - `register(...)`·`list(query)`·`broadcast(query, bytes)`·`acknowledge(id, connections)`·`kick(query)`·`events()`: websocket 플러그인이 쓰는 저수준 API. **`events()`의 소비자는 하나뿐**이며 websocket이 쓰고 있으면 따로 읽지 않는다.
47
- - `status()`(D-0038) → `{ mode, state, role, leaseState?, leader?, leaseRemainingMs?, servers?, connections?, serverId? }`. 모르는 값은 0으로 채우지 않고 **빠진다**(Redis 무응답이면 `leaseState: 'unreachable'`).
48
- - `nonces()`(D-0038) → `{ shared, setIfNotExists(key, ttlSeconds) }`. cluster는 Redis `SET NX PX`로 서버들이 공유하고(`shared: true`), local은 프로세스 안(`shared: false`, cluster 워커에서 쓰면 `HUB_NONCES_NOT_SHARED` 경고 한 번). 봉인 프레임의 재생 방어(@dokebi/crypto `SealTerminator`)에 넘긴다.
63
+ - `state` (`starting`, `ready`, `recovering`, `closing`, `closed`), `role` (`active`, `standby`), `ownerEpoch`, `leader`, `whenReady(timeoutMs)` → boolean.
64
+ - `register(...)` → `HubConnection` (`identity`, `join`, `leave`, `updateMetadata`, `close`), `list(query)` → `HubSnapshot`, `broadcast(query, bytes)`, `kick(query)`, `events()`: the low-level API websocket uses. A query (`HubQuery`) is a required `tenant` plus optional `room`, `member`, `connection` (AND). **`events()` has a single consumer**; when websocket uses it, never read it separately. The `message` event (`{ id, connections, data }`) is the whole delivery: there is nothing to confirm (`acknowledge` was removed in 0.3.0).
65
+ - `broadcast` → receipt `HubReceipt` `{ id, recipients }`. Failures: `RECOVERING` (not connected to the leader, or the leader is changing; not sent), `OUTCOME_UNKNOWN` (the connection dropped after sending, before the answer; it may have been sent), `BUSY` (broadcasts in progress reached `maxPending`; in local mode, half of the event queue is still unread). The hub never resends. `kick` → `HubKickReceipt` `{ authorityEpoch, id }` (default code 4403).
66
+ - `status()` (D-0038) → `HubStatus` `{ mode, state, role, leaseState?, leader?, leaseRemainingMs?, servers?, connections?, serverId? }`. Unknown values are **left out**, not filled with 0 (`leaseState: 'unreachable'` when Redis does not answer).
67
+ - `nonces()` (D-0038) → `HubNonceStore` `{ shared, setIfNotExists(key, ttlSeconds) }`. cluster shares it between servers through Redis `SET NX PX` (`shared: true`); local keeps it in the process (`shared: false`; used in a cluster worker it warns `HUB_NONCES_NOT_SHARED` once). Pass it to the replay defense of sealed frames (@dokebi/seal `SealTerminator`). Only the shape matches; seal is never imported.
68
+ - Exports: `createPlugin`, `dependency`, `HubError`, types `HubApi`, `HubConnection`, `HubRegistration`, `HubRecord`, `HubQuery`, `HubLeader`, `HubSnapshot`, `HubReceipt`, `HubKickReceipt`, `HubEvent`, `HubLease`, `HubStatus`, `HubNonceStore`.
49
69
 
50
- ## 4. 운영 명령 `dokebi-hub-status`
70
+ ## 4. Operations command `dokebi-hub-status`
51
71
 
52
72
  ```sh
53
- npx dokebi-hub-status --config dokebi.yaml # 사람이 읽는 형태
54
- npx dokebi-hub-status --config dokebi.yaml --json # 기계용
73
+ npx dokebi-hub-status --config dokebi.yaml # human-readable
74
+ npx dokebi-hub-status --config dokebi.yaml --json # for machines
55
75
  ```
56
76
 
57
- 앱 프로세스 밖에서 Redis만 읽어 리더·lease 남은 시간·살아 있는 서버 수·연결 수를 보여 준다(허브를 시작하거나 선출에 끼지 않는다). Redis 무응답이면 종료 코드 1. local 모드는 프로세스 안에만 상태가 있다고 알린다.
77
+ From outside the app process it reads only Redis and shows the leader, the remaining lease time, the number of live servers and the connection count (it never starts a hub or joins the election). When Redis does not answer it exits with code 1. In local mode it says the state lives only inside the process.
78
+
79
+ ## 5. Delivery semantics (D-0057)
80
+
81
+ - **Success = sent out.** cluster: the leader picks the connections matching right now, writes one message frame to each server (owner) holding them, then gives the sending server a receipt. local: it is done once it is in this process's event queue (read by the websocket gateway). There is no receipt confirmation, resend, deduplication, completion record or deadline wait. It is **at most once**.
82
+ - **receipt** `{ id, recipients }`: `recipients` are the identifiers of the connections matching when it was sent (the SHA-256 of tenant, member and clientId, or of owner and connection without a clientId). **It does not mean they received it.** Connections that were reconnecting, that left before the frame was written, or that were closed with 1013 for being slow do not get it. Connections that arrive later do not get it either (nothing is kept).
83
+ - **Failures come at once and are never resent (no duplicates)**: `RECOVERING`, `OUTCOME_UNKNOWN`, `BUSY`. The caller decides whether to send again (resending after `OUTCOME_UNKNOWN` can deliver twice).
84
+ - **App guideline**: never leave work that must not be missed (order state, payment results) to a broadcast. Store it in the DB and let the page read the latest state from the server when it reconnects. Use broadcasts as "it changed, read again" notices. Work that must happen goes to @dokebi/job.
85
+ - **Protocol between hub servers (protocol 2)**: hello carries `protocol: 2`. The leader refuses other versions with `PROTOCOL_MISMATCH` (warn `Hub peer refused; protocol differs`), and the refused server logs error `Hub protocol differs from the leader; retrying` (`protocol`, `leaderProtocol`) and retries. A 0.3 server connected to a 0.2 leader (no version) is cut with the same error. During a rolling restart a server of another version cannot join the leader (while starting, `STARTUP_TIMEOUT` after `startupTimeoutMs`), so upgrade every server to the same version. The configuration fingerprint stays the same as 0.2 so that this version check, not `CONFIG_MISMATCH`, tells them apart.
86
+ - Broadcasts never go through Redis (only connection registrations and changes are stored in Redis, D-0042). No broadcast record stays in leader memory either.
87
+ - presence events come as the full list per owner (server). After a reconnect or leader change, owners that differ from the snapshot and owners that disappeared are announced again.
88
+
89
+ ## 6. Index and performance ([D-0068](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0068-performance-stage4.md) §3)
90
+
91
+ - `HubIndex` (`src/hub-index.ts`) keeps tenant → member → connections, tenant → room → connections (insertion-ordered sets), owner → connection → record and recipientKey → record. local updates it on every register, change and close; the leader when the server list changes (`setOwner`/`removeOwner`, rebuilt from the snapshot at start).
92
+ - Selection walks only the smallest matching set (a named connection → one; member and room → the smaller; member; room; the whole tenant) and checks each with `matches`, so the answer equals a full scan (receipt semantics, presence and roster unchanged). The `DUPLICATE_CLIENT` check is O(1); `list` and `kick` use the same index.
93
+ - Evidence: a randomized 2000-step test (add, room change, remove, owner swap) compares every filter with the full scan; `benchmarks/scenarios/micro/hub-select.mjs` measures `select`; `websocket-load.bench.mjs 1024 300` passed with no missed, duplicated or misdirected messages and baseline receive p50/p95/p99 6.8/10.8/17.0 ms.
94
+
95
+ ## 7. Errors
96
+
97
+ `HubError` (branch on `code`).
58
98
 
59
- ## 5. 전달 의미
99
+ `HubError` is a `DokebiError` (0.4.0, D-0063): `plugin: 'dokebi-websocket-hub'`, and the message stays `WebSocket hub: <code>`. Codes an operator fixes carry a `fix`.
60
100
 
61
- - broadcast는 대상 연결 전원의 ACK 뒤 끝난다. 못 받으면 `retryMs`마다 재전송, 같은 clientId로 재접속하면 못 받은 것을 받는다. 기한을 넘기면 `DELIVERY_TIMEOUT`.
62
- - 방송 기록은 **리더 메모리에만** 있다(0.2.0, D-0042). 방송·ACK는 Redis를 거치지 않는다(접속자 등록·변경만 Redis에 저장). 리더가 바뀌면 보낸 서버가 같은 ID와 리더가 알려 준 수신자 목록(`accepted`)으로 재전송한다. **보낸 서버와 리더가 동시에 죽으면 그 방송은 사라진다**(성공 응답 전이라 「성공 뒤 유실 없음」은 유지). 반드시 전달돼야 하는 업무는 @dokebi/job.
63
- - `maxDeliveries`·`deliveryBytes`는 리더 메모리 상한이다(진행 중 방송의 본문·수신자 목록 + 끝난 방송의 결과를 기한까지). 넘으면 `OUTBOX_FULL`.
64
- - 0.1.x(Redis outbox)와 0.2.0 서버는 같은 namespace에서 섞이지 않는다(설정 지문 차이로 `CONFIG_MISMATCH`). 판 올림은 namespace의 서버를 함께 바꾼다.
65
- - presence 이벤트는 owner(서버)별 전체 목록으로 온다. 재접속·리더 변경 뒤에는 스냅샷과 달라진 owner와 사라진 owner를 다시 알린다.
66
- - 실제 소비자 없이 acknowledge하지 않는다. 재전송을 업무의 정확히 한 번으로 설명하지 않는다.
101
+ | Code | When |
102
+ |---|---|
103
+ | `LOCAL_IN_CLUSTER` | local mode started in a node:cluster worker (the role comes from core `context.runtime.role`). `fix`: `mode: cluster` or `allowInCluster: true`. Before 0.4.0 this error was HUB_LOCAL_IN_CLUSTER; the error log keeps that code |
104
+ | `LISTEN_FAILED` · `STARTUP_TIMEOUT` | Could not open the hub TCP · could not join the leader within `startupTimeoutMs` (with `fix`) |
105
+ | `CONFIG_MISMATCH` · `PROTOCOL_MISMATCH` · `UNAUTHORIZED` | Different settings, version or secret in the same namespace (with `fix`) |
106
+ | `RECOVERING` · `OUTCOME_UNKNOWN` · `BUSY` | Broadcast failures (§5) |
107
+ | `STORE_UNAVAILABLE` | Redis failure (the cause is in `cause`) |
108
+ | `INVALID_ARGUMENT` · `INVALID_OPTIONS` | Wrong API arguments or hub frame values (frame value codes are compared between servers, so they stay as in 0.3) |
109
+ | `CONNECTION_LIMIT` · `MESSAGE_TOO_LARGE` · `DUPLICATE_CLIENT` · `DUPLICATE_CONNECTION` · `CLOSED` · `EVENT_OVERFLOW` | Limits, duplicates, shutdown |
67
110
 
68
- ## 6. 주의 사항
111
+ ## 8. Cautions
69
112
 
70
- - 클라이언트가 보낸 tenant·member·rooms를 믿지 않는다(인증 함수가 정한다).
71
- - secret은 dokebi.yaml에만, 32바이트 이상 무작위. 같은 namespace의 모든 서버가 같은 secret·옵션·Redis/NATS를 쓴다.
72
- - 서버마다 다른 serverId와 다른 서버에서 접근 가능한 `advertiseHost`·TCP 포트가 필요하다(방화벽).
73
- - 전체 drain 전에 허브·Redis·NATS를 닫지 않는다(core 순서가 지킨다).
74
- - 로그로 리더 연결 끊김(`Hub connection dropped`), 복구 중 실패(`Hub still recovering`), 복구 시간(`Hub recovered`)을 남긴다.
113
+ - Never trust tenant, member or rooms sent by the client (the authentication function decides them).
114
+ - 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.
115
+ - 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.
116
+ - Never close the hub, Redis or NATS before the whole drain (core ordering ensures it).
117
+ - **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`.
118
+ - 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: lost leader connection `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 `Hub transport or store unavailable; recovering`, peer send failure `PEER_SEND_FAILED` (backpressure included), peer socket and frame `PEER_SOCKET_ERROR`, `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`, local event queue overflow `EVENT_OVERFLOW`, 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.
119
+ - debug (`DOKEBI_LOG_LEVEL=debug`): election, leader start and stop, lease loss, leader connection and reconnect (`Hub connected to leader`, ms taken, resync count), server registration, removal and expiry, connection list changes, broadcasts `Hub broadcast sent` (leader and local: `id`, `recipients`, `owners`, `ms`; no body), broadcasts of unknown outcome `OUTCOME_UNKNOWN` (not resent), refusals (`BUSY`, `STALE_*`), failures while still recovering (`Hub still recovering`), and the recovery time at info (`Hub recovered`).
120
+ - `dokebi-hub-status` writes the cause of a Redis failure to stderr (the stdout JSON stays as it is).
121
+ - 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.
75
122
 
76
- 근거: `examples/18-websocket-hub`(실제 TCP 피어·리더 인계), `examples/23-websocket`, `examples/25-playground`, `tests/status.test.ts`(status·nonces·명령), D-0024·D-0025·D-0029·D-0034·D-0038.
123
+ 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).
package/README.md CHANGED
@@ -1,21 +1,21 @@
1
1
  # @dokebi/websocket-hub
2
2
 
3
- Node >=24, 0.1.1(npm 공개 패키지). Dokebi `@dokebi/core ^0.2.0`의 선택 플러그인. 기존 `@dokebi/sync`를 대체하는 TCP 허브다.
4
-
5
- 모드는 두 가지다([D-0029](../../docs/decisions/D-0029-hub-and-cluster-infrastructure.md)).
6
-
7
- - **`mode: local`(기본):** 프로세스 하나의 허브다. Redis·NATS 없이 접속 목록·방·방송·kick·수신 ACK를 메모리에서 처리한다.
8
- - API와 ACK 의미는 cluster 모드와 같다. 방송은 전원 ACK 뒤에 끝나고, `retryMs`마다 재전송하며, 같은 clientId로 재접속하면 못 받은 것을 받는다.
9
- - 다만 미완료 메시지는 프로세스와 함께 사라지고 장애 인계도 없다.
10
- - `node:cluster` 워커에서 쓰면 워커끼리 접속자를 공유하지 못하므로 `HUB_LOCAL_IN_CLUSTER`로 시작을 거부한다. 의도적으로 쓸 때만 `allowInCluster: true`로 허용한다.
11
- - **`mode: cluster`:** 여러 프로세스·서버가 접속자를 공유한다.
12
- - 모든 WebSocket 워커가 허브 후보가 되고, Redis 임대로 하나를 선출한다. TCP로 유저 등록·snapshot·전체/대상 메시지·kick을 전달하고, Redis에 접속 목록을 보관한다.
13
- - `namespace`·`serverId`·`redisConnection`·`secret`이 필요하다.
14
- - NATS(`natsConnection`)는 선택이다. 있으면 리더 변경을 즉시 알리고, 없으면 다른 서버가 Redis 폴링(`pollMs`)으로 알아챈다.
15
- - 허브가 죽어도 정상 서버의 실제 WebSocket은 유지되고 새 허브로 재접속한다.
16
- - **설치 검사:** 설치 모듈의 check가 모드를 보고 요구 플러그인을 알린다. cluster면 Redis를, NATS 연결이 있으면 NATS도 요구한다.
17
- - **`whenReady(timeoutMs)`(D-0034):** 준비되면 true, 시간이 지나거나 닫히면 false다. websocket은 업그레이드를 받을 때 이것으로 짧은 재연결을 기다린다. 리더 연결이 끊긴 이유(`Hub connection dropped`), 복구가 이어지는 동안의 실패(`Hub still recovering`), 복구 시간(`Hub recovered`)을 로그로 남긴다.
18
- - **presence 이벤트:** 연결이 들고 날 때 owner(서버)별 전체 목록으로 온다. 피어가 재접속하거나 리더가 바뀌면 스냅샷과 달라진 owner와 사라진 owner를 presence 이벤트로 다시 알린다. 그래서 소비자는 그사이 나간 연결을 놓치지 않는다.
3
+ Node >=24, version 0.4.0 (unpublished). An optional plugin of Dokebi `@dokebi/core ^0.4.0`: a TCP hub that replaces the former `@dokebi/sync`. AI agents start with [AI.md](AI.md).
4
+
5
+ There are two modes ([D-0029](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0029-hub-and-cluster-infrastructure.md)).
6
+
7
+ - **`mode: local` (default):** a hub for one process. It handles connection lists, rooms, broadcasts and kicks in memory, without Redis or NATS.
8
+ - The API and broadcast semantics are those of cluster mode (at most once, "Broadcast" below). A broadcast is done once it is in the event queue websocket reads. When half of that queue is still unread it is refused with `BUSY` (leaving room for presence and kicks).
9
+ - There is no failover.
10
+ - In `node:cluster` workers the workers cannot share connections, so start is refused with `LOCAL_IN_CLUSTER`. Allow it with `allowInCluster: true` only on purpose.
11
+ - **`mode: cluster`:** connections are shared by processes and servers.
12
+ - Every WebSocket worker is a hub candidate, and a Redis lease elects one. TCP carries user registrations, snapshots, broadcast and targeted messages and kicks, and Redis keeps the connection list.
13
+ - `namespace`, `serverId`, `redisConnection` and `secret` are required.
14
+ - NATS (`natsConnection`) is optional. With it, leader changes are announced at once; without it other servers notice through Redis polling (`pollIntervalMs`).
15
+ - When the hub dies, the real WebSockets of healthy servers stay and reconnect to the new hub.
16
+ - **Install check:** the install module's `check` looks at the mode and reports the required plugins: Redis in cluster mode, and NATS too when a NATS connection is set.
17
+ - **`whenReady(timeoutMs)` (D-0034):** true once ready, false when the time passes or it closes. websocket uses it to wait out short reconnects when accepting upgrades. It logs why the leader connection dropped (`Hub connection dropped`), failures while recovery continues (`Hub still recovering`) and the recovery time (`Hub recovered`).
18
+ - **presence events:** they come as the full list per owner (server) when connections come and go. When a peer reconnects or the leader changes, owners that differ from the snapshot and owners that disappeared are announced again as presence events, so consumers never miss connections that left meanwhile.
19
19
 
20
20
  ```yaml
21
21
  schemaVersion: 1
@@ -39,9 +39,9 @@ options:
39
39
  secret: replace-with-your-random-secret-at-least-32-bytes
40
40
  ```
41
41
 
42
- serverId/advertiseHost는 서버별 설정, namespace/secret/공유 저장소·분산 한도는 같은 영역에서 일치해야 한다. 워커마다 별도 TCP 포트를 연다(port 기본0). 해당 포트가 다른 서버에서 접근 가능해야 한다. TCP는 TLS를 내장하지 않으므로 신뢰된 사설망/암호화 터널을 사용한다.
42
+ `serverId`/`advertiseHost` are per server; `namespace`, `secret`, shared stores and distributed limits must match across the area. Each worker opens its own TCP port (`port` default 0), which must be reachable from other servers. The TCP has no built-in TLS, so use a trusted private network or an encrypted tunnel.
43
43
 
44
- ```ts
44
+ ```ts snippet
45
45
  import { Application, loadConfig } from '@dokebi/core';
46
46
  import { createPlugin } from '@dokebi/websocket-hub';
47
47
  const config = await loadConfig('./dokebi.yaml');
@@ -51,52 +51,80 @@ app.register(plugin);
51
51
  await app.start();
52
52
  const hub = app.get(plugin);
53
53
  const connection = await hub.register({tenant:'demo',member:'alice',connection:'socket-1'});
54
- // websocket 플러그인을 사용하면 이것 대신 해당 플러그인이 단독 소비한다.
54
+ // With the websocket plugin, that plugin is the sole consumer instead.
55
55
  const consumer = (async () => {
56
56
  for await (const event of hub.events()) {
57
- if (event.kind === 'message') {
58
- await deliverAndWaitForClientAck(event); // 앱이 제공하는 실제 수신 ACK 처리
59
- hub.acknowledge(event.id, event.connections);
60
- }
57
+ // the message event is the whole delivery: write event.data to this server's event.connections (no ACK).
58
+ if (event.kind === 'message') writeToSockets(event.connections, event.data);
61
59
  }
62
60
  })();
63
61
  const snapshot = await hub.list({tenant:'demo'});
64
62
  const receipt = await hub.broadcast({tenant:'demo',member:'alice'}, new TextEncoder().encode('hello'));
63
+ // receipt: { id, recipients } — connections matching when sent (not a confirmation of receipt)
65
64
  await connection.close();
66
65
  await app.stop();
67
66
  await consumer;
68
67
  ```
69
68
 
70
- HubConnection: identity(ownerEpoch/connection), join(room), leave(room), updateMetadata(record), close(). HubApi: state, role, ownerEpoch, leader, register, list, broadcast, kick, events. query는 필수tenant와 선택room/member/connection의 AND다. events는 presence/message/kick의 단일 async iterator다. kick 기본코드4403, 사용자 수신 ACK가 아닌 TCP 요청이다.
69
+ `HubConnection`: `identity` (ownerEpoch/connection), `join(room)`, `leave(room)`, `updateMetadata(record)`, `close()`. `HubApi`: `state`, `role`, `ownerEpoch`, `leader`, `register`, `list`, `broadcast`, `kick`, `events`, `whenReady`, `status`, `nonces`. A query is the AND of a required `tenant` and optional `room`/`member`/`connection`. `events` is the single async iterator of presence, message and kick events. kick (default code 4403) is a TCP request that returns `{ authorityEpoch, id }`.
71
70
 
72
- 기본 lease3000ms/poll500ms/ownerTTL15000ms. maxOwners64, 워커 접속128, 총8192, 프레임1MiB, payload64KiB, pending128, queue4MiB. 전체 snapshot도 프레임 한도를 지킨다. [옵션 스키마](options.schema.json)를 확인한다. poll×3≤lease, ownerTTL≥lease×3을 요구한다.
71
+ | Key | Type | Default | Description |
72
+ |---|---|---|---|
73
+ | `leaseMs` | integer ms | 3000 | Leader lease |
74
+ | `pollIntervalMs` | integer ms | 500 | Polling without NATS |
75
+ | `ownerTtlMs` | integer ms | 15000 | Server registration expiry |
76
+ | `startupTimeoutMs` | integer ms | 15000 | Startup wait |
77
+ | `maxOwners` | integer | 64 | Servers |
78
+ | `maxConnections` | integer | 128 | Connections per worker |
79
+ | `maxTotalConnections` | integer | 8192 | All connections |
80
+ | `maxFrameBytes` | integer | 1048576 | Hub TCP frame |
81
+ | `maxPayloadBytes` | integer | 65536 | Message |
82
+ | `maxPending` | integer | 128 | Broadcasts in progress |
83
+ | `maxPendingBytes` | integer | 4194304 | Queue bytes |
73
84
 
74
- broadcast는 리더 메모리에 본문·대상 스냅샷을 두고, 대상 전원의 수신 ACK 뒤 `{authorityEpoch,id,recipients}`를 반환한다(0.2.0, [D-0042](../../docs/decisions/D-0042-hub-broadcast-in-memory.md)). 방송·ACK는 Redis를 거치지 않는다. 리더는 정한 수신자 목록을 보낸 서버에 `accepted`로 알리고, 허브 교체 시 보낸 서버가 동일 ID·수신자 목록으로 재전송한다. 보낸 서버와 리더가 함께 죽으면 그 방송은 사라진다(아직 성공 응답 전이다). events 소비자는 실제 수신 확인 뒤 `acknowledge(event.id, event.connections)`를 호출한다. `clientId`는 인증된 기기별 재접속 식별자이며 생략 시 소켓 소실 후 복구할 수 없다. 기본 기한60초·재전송1초, 리더 메모리 상한 10000건/64MiB(완료 기록은 본문 없이 기한까지 포함). DELIVERY_TIMEOUT/OUTBOX_FULL은 성공이 아니다. 일부 소비 후 실패할 수 있으므로 새 ID로 무조건 재실행하지 않는다. 페이지 재시작의 업무 exactly-once는 제공하지 않는다. 0.1.x(Redis outbox)와 0.2.0은 같은 namespace에서 섞이지 않는다(설정 지문이 달라 `CONFIG_MISMATCH`).
85
+ A full snapshot also stays within the frame limit. Check the [option schema](options.schema.json). It requires `pollIntervalMs × 3 ≤ leaseMs` and `ownerTtlMs ≥ leaseMs × 3`. 0.4.0 renamed `pollMs` → `pollIntervalMs`, `startupMs` → `startupTimeoutMs` and `queueBytes` → `maxPendingBytes` ([D-0071](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0071-option-vocabulary.md)); the old names still work in 0.4.0 with an `OPTION_DEPRECATED` warning.
75
86
 
76
- ## 운영 상태와 재생 방어 (D-0038)
87
+ ## Broadcast: at most once (0.3.0, [D-0057](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0057-websocket-broadcast-without-ack.md))
77
88
 
78
- - **`status()`:** 이 프로세스(`mode`·`state`·`role`·`serverId`)와 Redis 가 말하는 허브(`leaseState`·`leader`·`leaseRemainingMs`·`servers`·`connections`)를 함께 준다. 계산은 순수 함수 `hubStatus` 한 자리다. 모르는 값은 0 으로 채우지 않고 뺀다 — `leaseState: 'unreachable'`(Redis 가 답하지 않음)이면 `servers`·`connections` 가 없다. `none` 은 리더가 없다(장애 인계 중이거나 아무 서버도 안 떴다).
79
- - **`dokebi-hub-status --config dokebi.yaml [--json]`:** 앱 밖에서 같은 질문에 답한다. Redis 플러그인만 띄워 리더 기록과 소유자 기록을 읽고, 선출에 끼거나 등록하지 않는다. Redis 가 답하지 않으면 exit 1 이다. local 모드는 상태가 프로세스 안에만 있다고 말한다.
80
- - **`nonces()`:** 봉인 프레임의 1회용 nonce 저장소다(@dokebi/crypto `SealTerminator` 의 `nonces` 에 그대로 넣는다 · 모양만 맞추고 crypto 를 import 하지 않는다). cluster 모드는 Redis `SET NX PX`(`shared: true`)라 다른 서버로 재전송한 프레임도 거절된다. local 모드는 프로세스 안(`shared: false`)이고, cluster 워커에서 쓰면 처음 한 번 `HUB_NONCES_NOT_SHARED` 경고를 낸다.
89
+ - **Success = sent out.** In cluster mode the leader picks the connections matching right now, writes one message frame to each server holding them, then gives the sending server the receipt `{ id, recipients }`. local is done once it is in the event queue. There is no client ACK, resend, deduplication, completion record or deadline wait. Broadcasts never go through Redis and never stay in leader memory.
90
+ - **`recipients` of the receipt** are the identifiers of the connections matching when it was sent (the SHA-256 of tenant, member and clientId, or of owner and connection without a clientId). It is not a confirmation of receipt. Connections that were reconnecting, that left before the frame was written or that were closed with 1013 for being slow do not get it, and connections arriving later do not get it.
91
+ - **Failures are reported at once and never resent.** `RECOVERING`: not connected to the leader (leader change included) — not sent. `OUTCOME_UNKNOWN`: the connection dropped after sending the request, before the answer — it may have been sent. `BUSY`: broadcasts in progress reached `maxPending`. The caller decides whether to send again.
92
+ - **App guideline:** never leave work that must not be missed (order state, payment results) to a broadcast. Store it in the DB and let the page read the latest state from the server when it reconnects. Use broadcasts as "it changed, read again" notices. Work that must happen goes to @dokebi/job.
93
+ - **Removed options:** `deliveryTimeoutMs`, `retryMs`, `maxDeliveries`, `deliveryBytes`. Start still works when they remain; each key logs warn `OPTION_REMOVED` once and is ignored. The schema keeps them as deprecated (removed in the next version).
94
+ - **Version between hub servers:** hello carries `protocol: 2`. The leader refuses servers of another version with `PROTOCOL_MISMATCH` (warn), and the refused server logs an error with both versions and retries. A 0.3 server connected to a 0.2 leader is cut too. When versions mix during a rolling restart, old servers cannot join the new leader, so upgrade every server of the namespace to the same version. The configuration fingerprint stays the same as 0.2 so the version check tells them apart (against a 0.1.x Redis outbox it is still `CONFIG_MISMATCH`).
95
+ - `clientId` is an identifier per authenticated device or tab. A concurrent registration of the same `(tenant, member, clientId)` is refused with `DUPLICATE_CLIENT`.
81
96
 
82
- ## 팩토리와 의존성(플러그인 계약 v2)
97
+ ## Operational status and replay defense (D-0038)
83
98
 
84
- 팩토리 입력은 `{ app, options? }`이고 `app`은 필수다. 옵션을 생략하면 `app.config['dokebi-websocket-hub']`를 읽는다. `dependencies` 레코드나 Redis·NATS 인스턴스 입력은 받지 않는다([D-0028](../../docs/decisions/D-0028-plugin-contract-v2.md)).
99
+ - **`status()`:** returns this process (`mode`, `state`, `role`, `serverId`) together with the hub as Redis sees it (`leaseState`, `leader`, `leaseRemainingMs`, `servers`, `connections`). The calculation is one pure function, `hubStatus`. Unknown values are left out, not filled with 0 — with `leaseState: 'unreachable'` (Redis does not answer) there are no `servers` or `connections`. `none` means no leader (failover in progress, or no server is up).
100
+ - **`dokebi-hub-status --config dokebi.yaml [--json]`:** answers the same question from outside the app. It starts only the Redis plugin and reads the leader and owner records, without joining the election or registering. When Redis does not answer it exits with 1. In local mode it says the state lives only inside the process.
101
+ - **`nonces()`:** the one-time nonce store for sealed frames (passed as is to `nonces` of @dokebi/seal `SealTerminator`; only the shape matches and seal is never imported). cluster mode uses Redis `SET NX PX` (`shared: true`), so a frame replayed to another server is refused too. local mode keeps it in the process (`shared: false`) and warns `HUB_NONCES_NOT_SHARED` once when used in a cluster worker.
85
102
 
86
- - Redis·NATS는 `dokebi-redis`·`dokebi-nats` 공급자 descriptor로 연결한다. 같은 이름의 플러그인이 등록되어 있으면 그것을 재사용하고, 없으면 `@dokebi/redis`·`@dokebi/nats` 패키지에서 `app.config`로 만든다. 직접 지정하려면 `app.register(createRedis({ app: app.view }))`처럼 먼저 등록한다.
87
- - `@dokebi/redis`·`@dokebi/nats`는 `peerDependencies`다. 앱이 두 패키지를 함께 설치해야 한다.
88
- - 다른 플러그인은 `import { dependency } from '@dokebi/websocket-hub'`를 `metadata.dependencies`에 넣고 `context.getDependency(dependency)`로 API를 얻는다.
89
- - Redis 권한 스크립트는 저장소마다 `redis.script()`로 한 번 만들고 `EVALSHA`로 실행한다. 서버에 스크립트가 없을 때(`NOSCRIPT`)만 `EVAL`을 한 번 다시 보낸다.
103
+ ## Factory and dependencies (plugin contract v2)
90
104
 
91
- CLI에서는 YAML을 준비하고 `dokebi add @dokebi/redis` → `@dokebi/nats` → `@dokebi/websocket-hub` 순서로 등록한다. manifest는 schemaVersion 2이고 설치 모듈은 없다(만드는 파일이 없다). 설치는 서버 연결을 만들지 않는다. 허브는 drain 훅이 없고, 앱 drain이 끝난 뒤 cleanup에서 자원을 닫는다.
105
+ The factory input is `{ app, options? }`; `app` is required. Without options it reads `app.config['dokebi-websocket-hub']`. It takes no `dependencies` record and no Redis or NATS instance inputs ([D-0028](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0028-plugin-contract-v2.md)).
92
106
 
93
- 저장소 예제18은 공개 API·로컬 TCP 기준선, 예제23은 두 Docker 서버·네 워커·허브/서버 장애·실제 DB drain을 검증한다. 전체 XFramework 부가 media/nonce 이식이나 운영 전체 인증을 뜻하지 않는다.
107
+ - Redis and NATS are wired through the `dokebi-redis` and `dokebi-nats` provider descriptors. A plugin registered under the same name is reused; otherwise it is created from the `@dokebi/redis` or `@dokebi/nats` package with `app.config`. To choose one, register it first, e.g. `app.register(createRedis({ app: app.view }))`.
108
+ - `@dokebi/redis` and `@dokebi/nats` are `peerDependencies`. The app installs both packages.
109
+ - Other plugins put `import { dependency } from '@dokebi/websocket-hub/dependency'` (the provider descriptor, the same object as the package entry's `dependency`) in `metadata.dependencies` and get the API with `context.getDependency(dependency)`. Plugins for which the hub is optional keep their own `optionalDependency`.
110
+ - The Redis authority script is created once per store with `redis.script()` and runs as `EVALSHA`. Only when the server lacks the script (`NOSCRIPT`) is `EVAL` sent once more.
94
111
 
95
- ## 설정 지문 (2026-10-14)
112
+ With the CLI, prepare the YAML and register in the order `npx dokebi add @dokebi/redis` → `@dokebi/nats` → `@dokebi/websocket-hub`. The manifest is schemaVersion 2, and its install module (`dist/install.js`) only reports required plugins; it creates no files. Installing makes no server connections. The hub has no drain hook and closes its resources in cleanup after the app drain finished.
96
113
 
97
- 같은 namespace의 서버들은 secret·임대·한도 설정이 같아야 한다(Redis의 설정 지문). 다른 설정의 서버가 살아 있는 동안 새 서버는 `CONFIG_MISMATCH`로 즉시 시작에 실패하고 error 로그(`code: CONFIG_MISMATCH`)를 남긴다. 옛 설정의 리더·소유자가 모두 사라지면(전체 재시작) 새 설정이 지문을 대체한다. 그래서 비밀값 교체는 전체를 내렸다 올리면 되고 Redis 키를 지울 필요가 없다([ISSUE-0005](../../docs/issues/ISSUE-0005-playground-findings.md) PG-16).
114
+ Example 18 in the repository covers the public API and a local TCP baseline; example 23 verifies two Docker servers, four workers, hub and server faults and a real DB drain. That does not mean a full port of XFramework's extra media and nonce features or full operational certification.
98
115
 
99
- ## 종료 정리와 시작 로그 (2026-10-14)
116
+ ## Configuration fingerprint (2026-10-14)
100
117
 
101
- - 노드가 정상 종료하면 자기 소유자 기록을 Redis에서 직접 지운다(`leave`: 리더 없이, 같은 세션일 때만). 전체를 동시에 꺼도 기록이 ownerTtlMs까지 남지 않아, 설정을 바꾼 즉시 재시작할 수 있다(PG-21).
102
- - 시작 중의 재시도(아직 열리지 않은 리더 TCP에 접속 등)는 경고를 남기지 않는다. 시작 기한(`startupMs`)을 넘기면 error 로그 `STARTUP_TIMEOUT`에 마지막 오류 코드(`lastError`)를 남긴다. 시작 뒤의 장애 경고에는 `code`가 붙는다(PG-19).
118
+ Servers of one namespace need the same secret, lease and limit settings (the configuration fingerprint in Redis). While a server with different settings is alive, a new server fails to start at once with `CONFIG_MISMATCH` and logs an error (`code: CONFIG_MISMATCH`). Once every leader and owner with the old settings is gone (a full restart), the new settings replace the fingerprint. So rotating the secret is a full stop and start, without deleting Redis keys ([ISSUE-0005](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/issues/ISSUE-0005-playground-findings.md) PG-16).
119
+
120
+ ## Shutdown cleanup and startup logs (2026-10-14)
121
+
122
+ - On a normal shutdown a node deletes its own owner record from Redis directly (`leave`: without the leader, only for the same session). Even when everything stops at once, records do not stay until `ownerTtlMs`, so a restart right after a settings change works (PG-21).
123
+ - Retries during startup (such as connecting to a leader TCP that is not open yet) log no warnings. Past the startup deadline (`startupTimeoutMs`) the error log `STARTUP_TIMEOUT` records the last error code (`lastError`). Fault warnings after start carry a `code` (PG-19).
124
+
125
+ ## 0.4.0 shared base (D-0063)
126
+
127
+ - The options are one declaration in `src/options.ts` that is both the parser and `options.schema.json` (generated at build time; `npm run check:options` compares bytes). The connection name and host rules and defaults that only the hand parser kept are in the schema now, and `secret` counts characters and bytes together. Core logs the warn `OPTION_REMOVED` for removed options.
128
+ - `HubError` is a `DokebiError` (`plugin`, `fix` for codes an operator fixes). Log helpers and repeat suppression use core `diagnostics` (`describeError`, `Repeats`).
129
+ - The cluster worker check uses core `context.runtime.role` instead of `node:cluster` (`LOCAL_IN_CLUSTER`, `HUB_NONCES_NOT_SHARED`). The cluster error code was `HUB_LOCAL_IN_CLUSTER` before 0.4.0 (D-0071); the error log keeps that code.
130
+ - The hub index ([D-0068](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0068-performance-stage4.md) §3: per tenant, member, room, owner and recipient key, so selection walks the smallest matching set) and the delivery semantics are unchanged. Possible future extension hooks are listed 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).
@@ -1,51 +1,17 @@
1
- import { type HubOptions } from './options.js';
2
- import { type HubRecord } from './types.js';
1
+ import type { HubQuery, HubRecord } from './types.js';
2
+ /**
3
+ * The identity of a connection in a broadcast receipt: SHA-256 (base64url) of tenant, member and
4
+ * clientId, or of the owner and connection when the client has no clientId.
5
+ */
3
6
  export declare function recipientKey(record: HubRecord): string;
4
- type Reply = (ok: boolean, recipients: readonly string[]) => void;
5
- interface Delivery {
6
- readonly id: string;
7
- readonly producer: string;
8
- readonly digest: string;
9
- readonly data: string;
10
- readonly expiresAt: number;
11
- readonly recipients: readonly string[];
12
- readonly remaining: Set<string>;
13
- readonly bytes: number;
14
- lastSent: number;
15
- }
16
- interface Finished {
17
- readonly producer: string;
18
- readonly digest: string;
19
- readonly ok: boolean;
20
- readonly recipients: readonly string[];
21
- readonly expiresAt: number;
22
- readonly bytes: number;
7
+ export interface Selection {
8
+ /** Identities of the matching connections, once each (the receipt). */
9
+ readonly recipients: string[];
10
+ /** Matching connections by the server (owner epoch) that holds them: one frame per owner. */
11
+ readonly owners: Map<string, string[]>;
23
12
  }
24
13
  /**
25
- * Broadcasts of the current hub leader, kept in its memory (D-0042). A broadcast succeeds only
26
- * when every recipient acknowledged (D-0025); until then it is resent every retryMs. Nothing is
27
- * written to Redis: when the leader dies, each producer resends its unfinished broadcasts with
28
- * the same id and the recipient list this leader announced (`accepted`), and the next leader
29
- * carries on from there. Finished broadcasts keep a small record (no payload) until their
30
- * deadline so a resent id is answered with its result instead of being delivered again.
14
+ * The recipients of a broadcast (D-0057): the connections that match `filter` now. Nothing is
15
+ * remembered; a connection that comes later, or leaves before its frame is written, misses it.
31
16
  */
32
- export declare class Deliveries {
33
- #private;
34
- readonly options: HubOptions;
35
- readonly connections: () => readonly HubRecord[];
36
- readonly send: (owner: string, frame: Record<string, unknown>) => boolean;
37
- readonly pending: Map<string, Delivery>;
38
- readonly finished: Map<string, Finished>;
39
- readonly waiters: Map<string, Map<string, Reply>>;
40
- constructor(options: HubOptions, connections: () => readonly HubRecord[], send: (owner: string, frame: Record<string, unknown>) => boolean);
41
- /** Bytes the outbox holds now (payloads and recipient lists), bounded by deliveryBytes. */
42
- get bytes(): number;
43
- /**
44
- * Takes a broadcast from `producer`. `accepted` is told the recipient list once, so the
45
- * producer can resend it to the next leader; `reply` is told the result.
46
- */
47
- accept(producer: string, frame: Record<string, unknown>, reply: Reply, accepted?: (recipients: readonly string[]) => void): void;
48
- acknowledge(input: unknown, records: readonly HubRecord[]): void;
49
- tick(): void;
50
- }
51
- export {};
17
+ export declare function select(records: Iterable<HubRecord>, filter: HubQuery): Selection;