@dokebi/sse 0.1.0 → 0.4.1

package/AI.md

@@ -1,69 +1,74 @@
-# AI 작업 안내 — @dokebi/sse 0.1.0
+# AI guide — @dokebi/sse 0.4.0
 
-@dokebi/web 앱의 서버 전송 이벤트(SSE)다. 서버는 인증한 스트림에 이벤트를 쓰고, `bus`를 주면 @dokebi/event-bus로 다른 워커·서버의 스트림에도 보낸다. 브라우저 클라이언트는 같은 패키지의 `./client`(+ `./client/vue`, `./client/react`, `./client/bundle`). 많아야 한 번(ACK·재전송·보관 없음). Node >=24.0.0, core ^0.2.0, @dokebi/web(필수), @dokebi/event-bus(`bus`일 때만), @dokebi/health(있으면 check `sse`). 근거는 [D-0060](../../docs/decisions/D-0060-sse.md), 사람용 설명은 [README](README.md).
+Server-sent events (SSE) for @dokebi/web apps. The server writes events to authenticated streams and, with `eventBus`, sends them through @dokebi/event-bus to the streams of other workers and servers too. The browser client is `./client` of the same package (plus `./client/vue`, `./client/react`, `./client/bundle`). At most once (no ACK, no resending, no retention). Node >=24.0.0, core ^0.4.0, @dokebi/web (required), @dokebi/event-bus (only with `eventBus`), @dokebi/health (check `sse` when present). The decision is [D-0060](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0060-sse.md); the human-oriented description is the [README](README.md).
 
-## 1. 설치
+## 1. Install
 
 ```sh
 npx dokebi add @dokebi/sse
 ```
 
-- `bus`를 쓰면 CLI가 dokebi-event-bus를 요구한다(설치 모듈 `requires`). 버스는 `dokebi-event-bus.buses.<이름>`에 정의한다. 여러 워커·서버는 `transport: nats`.
-- 같은 프로세스 하나만이면 `bus` 없이 쓴다(publish는 이 프로세스 스트림에만).
+> `npx dokebi` is the @dokebi/cli installed in the project (`dokebi init` adds it to devDependencies). The npm package `dokebi` is not this CLI, so never use `npx -y dokebi`. Without an installed CLI use `npx -y @dokebi/cli …`.
 
-## 2. 설정 `options.dokebi-sse`
+- With `eventBus` the CLI requires dokebi-event-bus (install module `requires`). Define the bus in `dokebi-event-bus.buses.<name>`. For several workers or servers use `driver: nats`.
+- For a single process, leave out `eventBus` (publish then reaches only this process's streams).
 
-| 키 | 기본 | 뜻 |
-|---|---|---|
-| `bus` | 없음 | event-bus 버스 이름. 다른 프로세스로 퍼뜨린다 |
-| `busEvent` | `dokebi.sse` | 버스 이벤트 이름 |
-| `allowInCluster` | `false` | cluster 워커에서 NATS 버스 없이 시작 허용(워커 하나일 때만) |
-| `retryMs` | 3000 | 처음 보내는 `retry:`(브라우저 재접속 간격). 클라이언트 백오프의 최소값 |
-| `heartbeatMs` | 15000 | `: ping` 주석 간격. 프락시 idle 제한보다 짧게 |
-| `maxConnections` | 1024 | 프로세스(워커)당 스트림. 넘으면 503 `CAPACITY` |
-| `maxBufferedBytes` | 1048576 | 스트림 하나에 쌓인 송신 바이트 상한. 넘으면 끊고 warn `SLOW_CONSUMER` |
-| `maxRooms` | 32 | 스트림 하나의 방 수 |
-| `maxEventBytes` | 65536 | 이벤트 data(JSON) 바이트 상한. 버스 `maxPayloadBytes`보다 작게 |
-| `closeTimeoutMs` | 2000 | drain이 `dokebi-restart` 뒤 스트림 종료를 기다리는 시간 |
+## 2. Options `options.dokebi-sse`
 
-**cluster 검사(`SSE_LOCAL_IN_CLUSTER`)**: node:cluster 워커에서 `bus`가 없거나 그 버스의 transport가 `nats`가 아니면 error 로그(`fix` 포함)와 함께 시작이 실패한다. event-bus API는 transport를 알려 주지 않으므로 **앱 설정 `dokebi-event-bus.buses.<bus>.transport`를 읽는다**. event-bus 옵션을 코드로만 넘겼으면 transport를 알 수 없어(`unknown`) 거절된다. 그때는 설정 파일로 옮기거나, 정말 워커 하나면 `allowInCluster: true`.
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `eventBus` | string | none | event-bus bus name that carries publications to other processes (named `bus` before 0.4.0, D-0071) |
+| `bus` | string | — | deprecated name of `eventBus`: warns `OPTION_DEPRECATED`; setting both is `INVALID_OPTIONS` |
+| `busEvent` | string | `dokebi.sse` | the bus event name |
+| `allowInCluster` | boolean | `false` | allow starting in a cluster worker without a NATS bus (only for a single worker) |
+| `retryMs` | integer | 3000 | the first `retry:` sent (browser reconnect delay); also the client backoff's minimum |
+| `heartbeatMs` | integer | 15000 | interval of the `: ping` comment. Keep it shorter than the proxy idle limit |
+| `maxConnections` | integer | 1024 | streams per process (worker). Beyond it 503 `CAPACITY` |
+| `maxBufferedBytes` | integer | 1048576 | bytes waiting to be sent on one stream. Beyond it the stream is cut with warn `SLOW_CONSUMER` |
+| `maxRooms` | integer | 32 | rooms per stream |
+| `maxEventBytes` | integer | 65536 | bytes of an event's data (JSON). Keep it below the bus `maxPayloadBytes` |
+| `shutdownTimeoutMs` | integer | 2000 | how long drain waits for streams to end after `dokebi-restart` (named `closeTimeoutMs` before 0.4.0) |
+| `closeTimeoutMs` | integer | — | deprecated name of `shutdownTimeoutMs` (D-0071) |
 
-## 3. 서버 API
+**Cluster check (`LOCAL_IN_CLUSTER`)**: in a node:cluster worker, the start fails with an error log (with `fix`) when there is no `eventBus` or its driver is not `nats`. The event-bus API does not report the driver, so **the app setting `dokebi-event-bus.buses.<eventBus>.driver` is read (and the old name `transport`)**. When the event-bus options were passed only in code, the driver is unknown (`unknown`) and the start is refused. Move them to the configuration file, or, if there really is only one worker, set `allowInCluster: true`.
 
-```ts
+## 3. Server API
+
+```ts snippet
 import { createPlugin, dependency, type SseApi } from '@dokebi/sse';
-const sse = context.getDependency(dependency);          // 없으면 이 패키지로 만든다
+const sse = context.getDependency(dependency);          // created from this package when missing
 sse.route({
-  path: '/events',                                       // GET만(HEAD 없음)
-  constraints: { dokebiApp: 'shop' },                    // 선택: @dokebi/app 도메인 라우팅
-  origins: ['https://admin.example.com'],                // 선택: 다른 출처 허용(CORS+credentials). '*'는 credentials 없이
-  version: APP_VERSION,                                  // 선택: D-0033
+  path: '/events',                                       // GET only (no HEAD)
+  constraints: { dokebiApp: 'shop' },                    // optional: @dokebi/app domain routing
+  origins: ['https://admin.example.com'],                // optional: allow other origins (CORS + credentials); '*' without credentials
+  version: APP_VERSION,                                  // optional: D-0033
   authenticate: (request) => ({ tenant, member, rooms: ['r1'] }),  // undefined → 401
   onOpen: (stream) => { stream.join(`user:${stream.member}`); stream.send('snapshot', data); },
-  onClose: (stream, reason) => {},                       // CLIENT_CLOSED·SERVER_CLOSED·SLOW_CONSUMER·DRAIN·ON_OPEN_FAILED·WRITE_FAILED
+  onClose: (stream, reason) => {},                       // CLIENT_CLOSED, SERVER_CLOSED, SLOW_CONSUMER, DRAIN, ON_OPEN_FAILED, WRITE_FAILED
 });
-const { id, local } = await sse.publish({ tenant, member?, room? }, 'order.changed', { id: 42 });
-sse.connections({ tenant, room });                       // 이 워커의 수
+const { id, local } = await sse.publish({ tenant, member, room }, 'order.changed', { id: 42 });  // member and room are optional
+sse.connections({ tenant, room });                       // the count on this worker
 ```
 
-- `route`는 setup에서만(`FROZEN`). `authenticate`·`onOpen`은 다시 접속할 때마다 돈다.
-- 대상: `{tenant}` 전체, `{tenant, member}` 한 사람의 모든 탭, `{tenant, room}` 방, `{tenant, room, member}` 방 안의 그 사람. 문자열은 1~256자.
-- 접두 대상(D-0061): `tenant` 대신 `tenantPrefix`(둘 중 정확히 하나, 아니면 `INVALID_TARGET`)면 이름이 그 접두로 시작하는 모든 tenant(+ 같은 `member`·`room` 규칙). 버스로 가는 메시지도 같은 대상을 싣고, 프로세스마다 자기 tenant 색인을 한 번 훑는다. @dokebi/app의 네임스페이스 `<ns>:`가 쓴다.
-- 이벤트 이름: `^[A-Za-z][A-Za-z0-9._:-]{0,63}$`, `dokebi-`로 시작 금지(플러그인 예약). data는 JSON 한 줄(`undefined`는 `null`), 함수·BigInt·순환은 `INVALID_DATA`.
-- `publish` 순서: 대상·이름·data 검사 → 버스가 `ready`가 아니면 `BUS_UNAVAILABLE`(아무 데도 안 감, error 로그) → 이 프로세스 스트림에 쓰기 → 버스 발행. 버스 발행 실패는 `BUS_PUBLISH_FAILED`(`cause`·`id`·`local`; 이 프로세스는 이미 받음, 다른 곳은 모름; error 로그에 전체 오류). 다시 보낼지는 호출자가 정한다(중복 가능).
-- 보낸 프로세스는 자기 버스 메시지를 건너뛴다(`origin`): 로컬·NATS 어느 버스든 그 프로세스 스트림은 한 번만 받는다.
-- `stream.send`는 한 연결에만, 쓴 경우 true(닫혔거나 느려서 끊겼으면 false). 이 프로세스에서 순서대로 증가하는 `id`가 붙는다.
-- 방은 연결마다다. 다시 접속하면 비어 있으니 `authenticate`의 `rooms`나 `onOpen`에서 넣는다.
+- `route` works only in setup (`FROZEN` afterwards). `authenticate` and `onOpen` run on every reconnect.
+- Targets: `{tenant}` everyone, `{tenant, member}` all tabs of one person, `{tenant, room}` a room, `{tenant, room, member}` that person in the room. Strings are 1 to 256 characters (any characters). A target only ever reaches streams of its own tenant.
+- Prefix targets (D-0061): with `tenantPrefix` instead of `tenant` (exactly one of them, otherwise `INVALID_TARGET`), every tenant whose name starts with that prefix (with the same `member` and `room` rules). Bus messages carry the same target, and each process scans its own tenant index once. @dokebi/app's namespaces `<ns>:` use it.
+- Event names: `^[A-Za-z][A-Za-z0-9._:-]{0,63}$`, not starting with `dokebi-` (reserved for the plugin). data is one line of JSON (`undefined` becomes `null`); functions, BigInt and cycles are `INVALID_DATA`.
+- `publish` order: check target, name and data → when the bus is not `ready`, `BUS_UNAVAILABLE` (nothing is sent anywhere, error log) → write to this process's streams → publish on the bus. A failed bus publish is `BUS_PUBLISH_FAILED` (`cause`, `id`, `local`; this process already received it, other places are unknown; the error log has the full error). Whether to send again is the caller's choice (duplicates possible).
+- The sending process skips its own bus messages (`origin`): with a local or a NATS bus, that process's streams receive each event once.
+- `stream.send` writes to one connection only and returns true when written (false when closed or cut for being slow). Events get an `id` that increases in order within this process.
+- Rooms are per connection. After a reconnect they are empty, so join in `authenticate`'s `rooms` or in `onOpen`.
+- `parseOptions` (the options parser) and the API types (`SseApi`, `SseRoute`, `SseStream`, …) are exported too.
 
-## 3a. @dokebi/app에 붙이기 (D-0061)
+## 3a. Mounting on @dokebi/app (D-0061)
 
-```ts
+```ts snippet
 export default defineApp({
   events: (app) => [{
     path: '/events',
     authenticate: async (request) => {
       const user = await userOf(request);
-      return user && { tenant: user.shop, member: user.id };   // namespace?: 앱 목록 중 하나(기본 첫째)
+      return user && { tenant: user.shop, member: user.id };   // namespace?: one of the app's list (default the first)
     },
     onOpen: (stream) => stream.send('hello', { tenant: stream.tenant }),   // 'front:shop-1'
   }],
@@ -73,60 +78,71 @@ export default defineApp({
 });
 ```
 
-- 앱 도메인에만 붙고(제약 `dokebiApp`), 모듈 접두사 규칙은 소켓과 같다(모듈의 `events` 훅, @dokebi/module 0.1.3). tenant는 `<네임스페이스>:<tenant>`(기본 네임스페이스는 앱 이름), 인증의 `namespace`가 앱 목록 밖이면 401과 warn `NAMESPACE_FORBIDDEN`. `namespace`는 앱이 지우므로 `stream.identity`에 없다.
-- 이 패키지가 없는데 앱에 `events`가 있으면 시작 실패(`has event streams; add @dokebi/sse`). `app.realtime().publish`는 `REALTIME_UNAVAILABLE`.
+- Streams attach only to the app's domains (constraint `dokebiApp`), with the same module prefix rules as sockets (the module `events` hook, @dokebi/module 0.1.3). The tenant is `<namespace>:<tenant>` (the default namespace is the app name). An authenticated `namespace` outside the app's list gets 401 and warn `NAMESPACE_FORBIDDEN`. app removes `namespace`, so it is not in `stream.identity`.
+- Realtime contribution point `dokebi-web:realtime` (D-0063 §5, `realtime` of `@dokebi/web/points`): in setup this plugin contributes `{ kind: 'sse', mount(route, scope), handle(namespace) }`. `mount` adds `scope.path` and `scope.constraints`, turns the `authenticate` result into `scope.identity` and registers the route; `handle(ns).publish({ tenant?, member?, room? }, event, data)` sends with the `<ns>:` prefix. Until @dokebi/app collects the point it is unused and nothing changes.
+- The cluster worker check (`LOCAL_IN_CLUSTER`) uses core's `context.runtime.role === 'worker'` (it never reads `node:cluster` itself).
+- When an app has `events` but this package is missing, the start fails (`has event streams; add @dokebi/sse`), and `app.realtime().publish` throws `REALTIME_UNAVAILABLE`.
 
-## 4. 연결 수명
+## 4. Connection lifetime
 
-- 응답: 200 `text/event-stream; charset=utf-8`, `Cache-Control: no-cache, no-transform`, `X-Accel-Buffering: no`, `Connection: keep-alive`. 첫 줄은 `retry: <retryMs>`와 `event: dokebi-open`(data `{"retryMs":…}`). Fastify 응답을 hijack해 직접 쓰므로 압축 훅이 붙지 않는다(dokebi-web은 압축하지 않는다).
-- 거절: 다른 출처(목록 밖) 403 `ORIGIN_FORBIDDEN`, 시작 전·정지 중 503(dokebi-web `STARTING`·`DRAINING`, 이 플러그인 `CLOSING`), 가득 참 503 `CAPACITY`(`Retry-After: 5`), 인증 없음 401. EventSource는 이 상태를 보지 못한다(아래 클라이언트가 탐침으로 구분).
-- `?dokebiProbe=1`: 출처·용량·인증만 검사하고 204로 답한다(스트림을 열지 않음). 브라우저 클라이언트가 실패 원인을 알아낼 때 쓴다.
-- 버전(D-0033): 라우트 `version`과 질의 `dokebiVersion`(또는 `x-dokebi-version` 헤더)이 다르면 `retry: 60000` + `event: dokebi-reload`(data `{"version":…}`)를 보내고 끝낸다.
-- `Last-Event-ID` 헤더(브라우저가 스스로 다시 접속할 때) 또는 질의 `lastEventId`(클라이언트가 직접 다시 열 때)를 `stream.lastEventId`로 준다. 서버는 이벤트를 보관하지 않는다.
-- heartbeat: `heartbeatMs`마다 `: ping`. 느린 수신자: 쌓인 바이트 + 새 이벤트가 `maxBufferedBytes`를 넘으면 그 스트림을 끊는다(`SLOW_CONSUMER`, 다른 스트림은 영향 없음).
-- drain(정지·롤링 재시작): 새 스트림 거절 → 버스 구독 해제 → 모든 스트림에 `event: dokebi-restart`(data `{"retryMs":…}`) → 종료 → `closeTimeoutMs`(또는 core drain 기한) 뒤 남은 연결 끊기 → onClose 대기. dokebi-web보다 먼저 drain된다.
-- health: dokebi-health가 있으면 필수 아닌 check `sse`를 등록한다. 버스가 `ready`가 아니면 `failed`(`BUS_UNAVAILABLE`, warn 로그), 돌아오면 `ready`(info 로그). readiness를 떨어뜨리지 않는다.
+- Response: 200 `text/event-stream; charset=utf-8`, `Cache-Control: no-cache, no-transform`, `X-Accel-Buffering: no`, `Connection: keep-alive`. The first lines are `retry: <retryMs>` and `event: dokebi-open` (data `{"retryMs":…}`). The Fastify response is hijacked and written directly, so no compression hook applies (dokebi-web does not compress).
+- Refusals: another origin (not listed) 403 `ORIGIN_FORBIDDEN`; before start or while stopping 503 (dokebi-web `STARTING`, `DRAINING`; this plugin `CLOSING`); full 503 `CAPACITY` (`Retry-After: 5`); no authentication 401. EventSource cannot see these statuses (the client below tells them apart with a probe).
+- `?dokebiProbe=1`: checks only origin, capacity and authentication and answers 204 (no stream is opened). The browser client uses it to find out why a connection failed.
+- Version (D-0033): when the route's `version` differs from the query `dokebiVersion` (or the `x-dokebi-version` header), it sends `retry: 60000` + `event: dokebi-reload` (data `{"version":…}`) and ends.
+- The `Last-Event-ID` header (when the browser reconnects by itself) or the query `lastEventId` (when the client reopens itself) becomes `stream.lastEventId`. The server keeps no events.
+- Heartbeat: `: ping` every `heartbeatMs`. Slow receivers: when the waiting bytes plus a new event exceed `maxBufferedBytes`, that stream is cut (`SLOW_CONSUMER`; other streams are unaffected).
+- Drain (stop, rolling restart): refuse new streams → unsubscribe from the bus → send `event: dokebi-restart` (data `{"retryMs":…}`) to every stream → end them → cut the remaining connections after `shutdownTimeoutMs` (or the core drain deadline) → wait for onClose. It drains before dokebi-web.
+- Health: with dokebi-health it registers the non-required check `sse`. When the bus is not `ready` the check is `failed` (`BUS_UNAVAILABLE`, warn log), and `ready` again when it returns (info log). It never drops readiness.
 
-## 5. 브라우저 클라이언트
+## 5. Browser client
 
-```ts
+```ts snippet
 import { connectEvents } from '@dokebi/sse/client';
 const events = connectEvents({
-  path: '/events',                 // 또는 url: 'https://…'
+  path: '/events',                 // or url: 'https://…'
   query: { tab: 'orders' },
-  version: APP_VERSION,            // dokebiVersion 질의
-  withCredentials: false,          // 다른 출처에 쿠키를 보낼 때(서버 origins에 그 출처)
-  onReload: () => location.reload(),          // 기본값
-  reconnect: { minMs: 1000, maxMs: 30000 },   // false면 실패 시 닫힌 채로
+  version: APP_VERSION,            // the dokebiVersion query
+  withCredentials: false,          // send cookies to another origin (that origin must be in the server's origins)
+  onReload: () => location.reload(),          // the default
+  reconnect: { minMs: 1000, maxMs: 30000 },   // false stays closed after a failure
 });
 const off = events.on<Order>('order.changed', (order, { id }) => {});
 events.onStatus((status) => {});   // connecting · open · reconnecting · paused · closed
-events.onError((error) => {});     // { code: UNAUTHORIZED·FORBIDDEN·UNAVAILABLE·CONNECTION_FAILED·BAD_DATA·HANDLER_FAILED·NO_EVENTSOURCE, status? }
+events.onError((error) => {});     // { code: UNAUTHORIZED, FORBIDDEN, UNAVAILABLE, CONNECTION_FAILED, BAD_DATA, HANDLER_FAILED, NO_EVENTSOURCE, status? }
 events.close(); events.reconnect();
 ```
 
-- import만으로는 window·EventSource를 건드리지 않는다(SSR 안전). `connectEvents`를 부를 때 연다.
-- 이벤트 이름마다 처음 `on` 할 때만 EventSource에 리스너를 단다. data는 JSON으로 읽는다(실패는 `BAD_DATA`).
-- `dokebi-reload` → `onReload`(기본 `location.reload()`), 다시 연결하지 않는다.
-- `dokebi-restart` → 닫고 백오프+지터(`max(minMs, 서버 retry)`부터 2배씩, `maxMs`까지, 그 값의 50~100%) 뒤 다시 연다.
-- EventSource가 스스로 다시 접속하는 경우(스트림이 끝남·네트워크): 그대로 둔다(`reconnecting`, 브라우저가 `Last-Event-ID`를 보낸다).
-- EventSource가 포기한 경우(HTTP 오류·잘못된 형식, readyState CLOSED): 닫고 `?dokebiProbe=1`로 원인을 묻는다. 401·403이면 `closed`(영구), 그 밖은 백오프 뒤 다시 연다. 직접 다시 열 때는 마지막 id를 `lastEventId` 질의로 보낸다(듣고 있는 이벤트의 id만 안다).
-- bfcache: `pagehide`(persisted)에 닫고(`paused`) `pageshow`(persisted)에 다시 연다.
-- Vue `useEvents(options)` → `{ status, client, on, close, reconnect }`(마운트 때 연결, 스코프 끝에 닫음, 컴포넌트 밖이면 바로 연결), `useEvent(events, name, handler)`.
-- React `useEvents(options)` → `{ status, client }`(같은 url·path·query·version·withCredentials는 EventSource 하나를 참조 계수로 공유, 마지막 사용자가 사라진 다음 틱에 닫음; 콜백은 처음 연 쪽 설정), `useEvent(name, handler, events?)`(없으면 가까운 `<EventsProvider options>`).
-- 번들: `@dokebi/sse/client/bundle` = `dist/browser/sse-client.js`(의존 없는 ES 모듈). 정적 파일로 내보내 `<script type="module">`이나 import map에서 쓴다.
+- Importing touches neither window nor EventSource (SSR safe). It opens when you call `connectEvents`.
+- A listener is added to the EventSource only on the first `on` per event name. data is read as JSON (a failure is `BAD_DATA`).
+- `dokebi-reload` → `onReload` (default `location.reload()`); it does not reconnect.
+- `dokebi-restart` → close, then reopen after backoff with jitter (starting at `max(minMs, server retry)`, doubling up to `maxMs`, 50–100% of that value).
+- When EventSource reconnects by itself (the stream ended, network): left alone (`reconnecting`; the browser sends `Last-Event-ID`).
+- When EventSource gave up (HTTP error, wrong format, readyState CLOSED): close and ask why with `?dokebiProbe=1`. 401 or 403 → `closed` (permanent); anything else reopens after backoff. When reopening itself it sends the last id as the `lastEventId` query (it knows only the ids of events it listens to).
+- bfcache: closes on `pagehide` (persisted) (`paused`) and reopens on `pageshow` (persisted).
+- Vue `useEvents(options)` → `{ status, client, on, close, reconnect }` (connects on mount, closes at the end of the scope; outside a component it connects at once), `useEvent(events, name, handler)`.
+- React `useEvents(options)` → `{ status, client }` (the same url, path, query, version and withCredentials share one EventSource with reference counting; it closes on the tick after the last user is gone; the callbacks are those of whoever opened it first), `useEvent(name, handler, events?)` (without `events`, the nearest `<EventsProvider options>`).
+- Bundle: `@dokebi/sse/client/bundle` = `dist/browser/sse-client.js` (an ES module without dependencies). Serve it as a static file and use it from `<script type="module">` or an import map.
+
+## 5a. Seal hosts (D-0062)
+
+On streams of a seal host (@dokebi/app `domains.<host>.seal: true`) or of a `seal: true` web route, **the data of every event** (including `dokebi-open`, `dokebi-reload` and `dokebi-restart`) is sealed with that stream's path (`E:<ts>:<b64>`, dokebi-web `sealOf`). Event names and ids stay plain. Plain streams share one buffer; only sealed streams seal per receiver. A failed seal ends that stream (`SEAL_ENCODE_FAILED`; never sent in plain text). Browser: `connectEvents({ ..., seal: currentSealBridge() })` (`@dokebi/seal/http`; undefined on plain pages, so the same code works). With a bridge, plain data is refused as `SEAL_FAILED`; without one, sealed data is refused as `SEAL_BRIDGE_MISSING` (neither reaches the handler).
+
+## 6. Several workers and servers
+
+- No sticky sessions needed. A NATS bus is required. `maxConnections` is per worker.
+- Order: per publisher order is kept; there is no global order. During a NATS outage publish fails with `BUS_UNAVAILABLE`/`BUS_PUBLISH_FAILED` and that event is lost.
+- Rolling restart: streams of the stopping worker get `dokebi-restart`, and clients reconnect to other workers with jitter.
+- HTTP/1.1 browsers allow 6 connections per origin (one stream per tab) → with many tabs use HTTP/2 (TLS) at the proxy. Proxy idle limit > `heartbeatMs`, and turn response buffering off.
 
-## 5a. 봉인 호스트 (D-0062)
+## 7. Logs (D-0047)
 
-seal 호스트(@dokebi/app `domains.<host>.seal: true`)나 `seal: true` 웹 라우트의 스트림은 **모든 이벤트의 data**(`dokebi-open`·`dokebi-reload`·`dokebi-restart` 포함)가 그 스트림 경로로 봉인된다(`E:<ts>:<b64>`, dokebi-web `sealOf`). 이벤트 이름·id는 평문이다. 평문 스트림은 버퍼 하나를 나눠 쓰고 봉인 스트림만 받는 쪽마다 봉인한다. 봉인 실패는 그 스트림을 끝낸다(`SEAL_ENCODE_FAILED`, 평문으로 보내지 않음). 브라우저: `connectEvents({ ..., seal: currentSealBridge() })`(`@dokebi/seal/http`; 평문 페이지면 undefined라 같은 코드). 다리가 있으면 평문 data를 `SEAL_FAILED`로, 다리가 없으면 봉인 data를 `SEAL_BRIDGE_MISSING`으로 거절한다(처리기에 가지 않는다).
+debug: route registration, stream open and close (reason, ms, open count), refusal reasons, version refusals, room join and leave, publish (id, local), bus deliveries received, drain begin and end. warn: `SLOW_CONSUMER`, `BUS_UNAVAILABLE` (state change). error (the full error; repeats once per 10 seconds with `repeated`): `BUS_PUBLISH_FAILED`, `BUS_UNAVAILABLE` (publish refused), `BUS_MESSAGE_INVALID`, `SSE_ON_OPEN_FAILED`, `SSE_ON_CLOSE_FAILED`, `STREAM_WRITE_FAILED`, `BUS_UNSUBSCRIBE_FAILED`, `SSE_LOCAL_IN_CLUSTER`. A bad `authenticate` result (`INVALID_IDENTITY`) is logged by dokebi-web as 500 with `WEB_REQUEST_FAILED`.
 
-## 6. 여러 워커·서버
+## 8. Errors
 
-- sticky 세션 불필요. NATS 버스 필수. `maxConnections`는 워커마다.
-- 순서: 같은 발행자 순서는 지켜지고 전체 순서는 없다. NATS 장애 중 publish는 `BUS_UNAVAILABLE`/`BUS_PUBLISH_FAILED`, 그 이벤트는 잃는다.
-- 롤링 재시작: 내려가는 워커의 스트림은 `dokebi-restart`를 받고, 클라이언트는 지터를 두고 다른 워커로 다시 붙는다.
-- HTTP/1.1 브라우저는 출처당 연결 6개(탭마다 스트림 하나) → 탭이 많으면 프락시에 HTTP/2(TLS). 프락시 idle 제한 > `heartbeatMs`, 응답 버퍼링 끄기.
+`SseError` (branch on `code`; never `instanceof`).
 
-## 7. 로그(D-0047)
+<!-- docs-check: complete-error-codes SseErrorCode -->
+Configuration and registration: `INVALID_OPTIONS`, `INVALID_ROUTE` (`path`, `origins` and so on), `FROZEN` (`route` after setup), `LOCAL_IN_CLUSTER` (§2; `SSE_LOCAL_IN_CLUSTER` before 0.4.0, D-0071). Connections: `INVALID_IDENTITY` (a bad `authenticate` result, 500). Sending: `INVALID_TARGET`, `INVALID_EVENT` (event name), `INVALID_DATA`, `EVENT_TOO_LARGE` (`maxEventBytes`), `INVALID_ROOM`, `ROOM_LIMIT` (`maxRooms`), `BUS_UNAVAILABLE`, `BUS_PUBLISH_FAILED` (`cause`, `id`, `local`, §3), `CLOSED` (`publish` after the app stopped).
 
-debug: 라우트 등록, 스트림 열림/닫힘(이유·ms·열린 수), 거절 이유, 버전 거절, 방 가입/탈퇴, publish(id·local), 버스 수신 전달 수, drain 시작/끝. warn: `SLOW_CONSUMER`, `BUS_UNAVAILABLE`(상태 바뀜). error(전체 오류, 반복은 10초에 한 번 `repeated`): `BUS_PUBLISH_FAILED`, `BUS_UNAVAILABLE`(publish 거절), `BUS_MESSAGE_INVALID`, `SSE_ON_OPEN_FAILED`, `SSE_ON_CLOSE_FAILED`, `STREAM_WRITE_FAILED`, `BUS_UNSUBSCRIBE_FAILED`, `SSE_LOCAL_IN_CLUSTER`. 잘못된 `authenticate` 결과(`INVALID_IDENTITY`)는 dokebi-web이 500과 `WEB_REQUEST_FAILED`로 남긴다.
+`SseError` is a `DokebiError` (D-0063): `plugin: 'dokebi-sse'` and a `fix` that says how to repair it. `INVALID_OPTIONS` carries per-path problems in `details.issues` (no values). The `defineOptions` declaration in `src/options.ts` is the parser, and the build writes `options.schema.json` from it (D-0063 §3; never edit it by hand).

package/README.md

@@ -1,84 +1,88 @@
 # @dokebi/sse
 
-도깨비 웹 앱(@dokebi/web)의 서버 전송 이벤트(SSE, `text/event-stream`). 인증한 사용자마다 스트림을 열고, tenant·member·room을 골라 이벤트를 보낸다. @dokebi/event-bus의 NATS 버스를 주면 다른 워커·서버의 스트림에도 간다. 브라우저 클라이언트(`@dokebi/sse/client`, Vue·React 훅, 빌드 없이 쓰는 번들)가 같은 패키지에 있다. Node >=24.0.0, @dokebi/core ^0.2.0. 결정 기록은 [D-0060](../../docs/decisions/D-0060-sse.md).
+Server-sent events (SSE, `text/event-stream`) for Dokebi web apps (@dokebi/web). It opens a stream per authenticated user and sends events chosen by tenant, member and room. Given a NATS bus of @dokebi/event-bus, events also reach the streams of other workers and servers. The browser client (`@dokebi/sse/client`, Vue and React hooks, a bundle usable without a build) is in the same package. Node >=24.0.0, @dokebi/core ^0.4.0. The decision record is [D-0060](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0060-sse.md).
 
-보장은 **많아야 한 번**이다(ACK·재전송·보관 없음, [D-0057](../../docs/decisions/D-0057-websocket-broadcast-without-ack.md)과 같다). 놓치면 안 되는 상태는 DB에 두고, 이벤트는 「바뀌었으니 다시 읽어라」 알림으로 쓴다.
+The guarantee is **at most once** (no ACK, no resending, no retention; the same as [D-0057](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0057-websocket-broadcast-without-ack.md)). Keep state that must not be missed in a DB and use events as "it changed, read it again" notices.
 
-## 설치
+## Install
 
 ```sh
 npx dokebi add @dokebi/sse
 ```
 
-한 프로세스면 설정이 없어도 된다. 워커가 여럿이거나 서버가 여럿이면 NATS 버스가 필요하다:
+> `npx dokebi` is the @dokebi/cli installed in the project (`dokebi init` adds it to devDependencies). The npm package `dokebi` is not this CLI, so never use `npx -y dokebi`. Without an installed CLI use `npx -y @dokebi/cli …`.
+
+A single process needs no settings. With several workers or servers a NATS bus is required:
 
 ```yaml
 options:
   dokebi-nats:
     connections: { main: { servers: [nats://127.0.0.1:4222] } }
   dokebi-event-bus:
-    buses: { sse: { transport: nats, connection: main } }
+    buses: { sse: { driver: nats, connection: main } }
   dokebi-sse:
-    bus: sse
+    eventBus: sse
 ```
 
-## 서버
+Before 0.4.0 the key was `bus` (and `closeTimeoutMs` is now `shutdownTimeoutMs`); the old names still work with an `OPTION_DEPRECATED` warning ([D-0071](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0071-option-vocabulary.md)).
+
+## Server
 
-```ts
-const events = context.get(sse);   // 또는 context.getDependency(dependency)
+```ts snippet
+const events = context.get(sse);   // or context.getDependency(dependency)
 events.route({
   path: '/events',
-  version: APP_VERSION,                         // 다르면 dokebi-reload (D-0033)
-  authenticate: async (request) => {            // undefined면 401
+  version: APP_VERSION,                         // a different one gets dokebi-reload (D-0033)
+  authenticate: async (request) => {            // undefined → 401
     const user = await request.session.get('user');
     return user ? { tenant: user.shop, member: user.id, rooms: [`shop:${user.shop}`] } : undefined;
   },
   onOpen: (stream) => stream.send('snapshot', { unread: 3 }),
 });
 
-await events.publish({ tenant: 'shop-1' }, 'order.changed', { id: 42 });               // tenant 전체
-await events.publish({ tenant: 'shop-1', member: 'u7' }, 'notice', { text: '안녕' });   // 한 사람
-await events.publish({ tenant: 'shop-1', room: 'order:42' }, 'order.changed', { id: 42 }); // 방
-await events.publish({ tenantPrefix: 'front:' }, 'notice', { text: '점검' });            // 접두가 맞는 모든 tenant
+await events.publish({ tenant: 'shop-1' }, 'order.changed', { id: 42 });               // the whole tenant
+await events.publish({ tenant: 'shop-1', member: 'u7' }, 'notice', { text: 'Hello' }); // one person
+await events.publish({ tenant: 'shop-1', room: 'order:42' }, 'order.changed', { id: 42 }); // a room
+await events.publish({ tenantPrefix: 'front:' }, 'notice', { text: 'Maintenance' });   // every tenant with the prefix
 ```
 
-| API | 뜻 |
+| API | Meaning |
 |---|---|
-| `route({ path, constraints?, origins?, version?, authenticate, onOpen?, onClose? })` | setup 때만. GET 스트림 라우트 |
-| `publish(target, event, data)` | `{ id, local }`. 모든 프로세스의 맞는 스트림에(보낸 프로세스는 한 번). 대상은 `{ tenant }` 또는 `{ tenantPrefix }`(정확히 하나) + `member?`·`room?` |
-| `connections(filter?)` | 이 프로세스(워커)의 열린 스트림 수. `{ tenant?, member?, room?, path? }` |
-| `stream.send(event, data)` · `join(room)` · `leave(room)` · `close()` | 한 연결만 |
+| `route({ path, constraints?, origins?, version?, authenticate, onOpen?, onClose? })` | setup only. A GET stream route |
+| `publish(target, event, data)` | `{ id, local }`. To matching streams of every process (the sending process once). The target is `{ tenant }` or `{ tenantPrefix }` (exactly one) plus `member?` and `room?` |
+| `connections(filter?)` | the number of open streams of this process (worker). `{ tenant?, member?, room?, path? }` |
+| `stream.send(event, data)` · `join(room)` · `leave(room)` · `close()` | one connection only |
 
-**@dokebi/app과 함께(D-0061):** 앱의 `events: (app) => [route, …]`로 앱 도메인에만 붙인다(라우트 제약 `dokebiApp`). 스트림 tenant는 `<네임스페이스>:<tenant>`이고, `authenticate`가 `namespace`를 돌려주면 그 앱의 네임스페이스 중에서 고른다(목록 밖은 401). 서버 코드는 `app.realtime(namespace).publish({ tenant?, member?, room? }, event, data)`로 그 공간에 발행한다(tenant를 빼면 `tenantPrefix: '<네임스페이스>:'`). 자세한 것은 @dokebi/app README의 「실시간 네임스페이스」.
+**With @dokebi/app (D-0061):** an app's `events: (app) => [route, …]` attaches streams only to the app's domains (route constraint `dokebiApp`). The stream tenant is `<namespace>:<tenant>`; when `authenticate` returns `namespace`, it is chosen from the app's namespaces (outside the list: 401). Server code publishes to that space with `app.realtime(namespace).publish({ tenant?, member?, room? }, event, data)` (without a tenant it is `tenantPrefix: '<namespace>:'`). See "Realtime namespaces" in the @dokebi/app README.
 
-오류는 `code`로 본다: `INVALID_EVENT`(이름 규칙·`dokebi-` 접두사), `INVALID_DATA`, `EVENT_TOO_LARGE`, `INVALID_TARGET`, `ROOM_LIMIT`, `BUS_UNAVAILABLE`(아무 데도 안 보냄), `BUS_PUBLISH_FAILED`(이 프로세스엔 보냄, 다른 곳은 모름; `id`·`local` 포함).
+Branch on error `code`s: `INVALID_EVENT` (naming rule, `dokebi-` prefix), `INVALID_DATA`, `EVENT_TOO_LARGE`, `INVALID_TARGET`, `ROOM_LIMIT`, `BUS_UNAVAILABLE` (sent nowhere), `BUS_PUBLISH_FAILED` (sent to this process, other places unknown; with `id` and `local`).
 
-## 브라우저
+## Browser
 
-```ts
+```ts snippet
 import { connectEvents } from '@dokebi/sse/client';
 const events = connectEvents({ path: '/events', version: APP_VERSION });
-const off = events.on('order.changed', (order) => refresh(order.id));   // data는 JSON으로 읽은 값
+const off = events.on('order.changed', (order) => refresh(order.id));   // data parsed as JSON
 events.onStatus((status) => badge(status));   // connecting · open · reconnecting · paused · closed
 ```
 
-- Vue: `import { useEvents, useEvent } from '@dokebi/sse/client/vue'` — 마운트 때 열고 스코프가 끝나면 닫는다(SSR에서는 열지 않는다).
-- React: `import { useEvents, useEvent, EventsProvider } from '@dokebi/sse/client/react'` — 같은 설정의 훅들은 EventSource 하나를 나눠 쓴다(StrictMode 안전).
-- 빌드 없는 페이지: `@dokebi/sse/client/bundle`(`dist/browser/sse-client.js`, 의존 없는 ES 모듈 하나)을 정적 파일로 내보내고 `<script type="module">import { connectEvents } from '/sse-client.js'</script>`.
-- 표준 EventSource만 쓸 때: `es.addEventListener('dokebi-reload', () => location.reload())`, `dokebi-restart`를 받으면 잠시 뒤 다시 연다.
+- Vue: `import { useEvents, useEvent } from '@dokebi/sse/client/vue'`. Opens on mount and closes when the scope ends (never opens during SSR).
+- React: `import { useEvents, useEvent, EventsProvider } from '@dokebi/sse/client/react'`. Hooks with the same settings share one EventSource (StrictMode safe).
+- Pages without a build: serve `@dokebi/sse/client/bundle` (`dist/browser/sse-client.js`, a single ES module without dependencies) as a static file and use `<script type="module">import { connectEvents } from '/sse-client.js'</script>`.
+- With the standard EventSource only: `es.addEventListener('dokebi-reload', () => location.reload())`, and reopen a little later after `dokebi-restart`.
 
-## 여러 워커·서버
+## Several workers and servers
 
-- 끈적 세션(sticky)이 필요 없다. 아무 워커에 붙어도 NATS 버스로 같은 이벤트를 받는다.
-- 워커가 여럿이면 `bus`(transport `nats`)가 필수다. 없으면 cluster 워커는 `SSE_LOCAL_IN_CLUSTER`로 시작하지 않는다(일부러 워커 하나면 `allowInCluster: true`).
-- `maxConnections`는 워커마다다.
-- 방(room)은 그 연결의 것이다. 다시 접속하면 없다: `authenticate`의 `rooms`나 `onOpen`에서 다시 넣는다.
-- 순서: 한 발행자가 보낸 것은 순서대로, 여러 발행자 사이 전체 순서는 없다. NATS가 끊기면 `publish`가 코드 있는 오류로 실패하고 그 이벤트는 사라진다.
-- 브라우저는 HTTP/1.1에서 출처당 연결 6개다. 탭이 많으면 프락시에서 HTTP/2(TLS)를 쓴다.
-- 프락시 idle 제한 시간은 `heartbeatMs`(기본 15초)보다 길어야 한다. nginx는 `X-Accel-Buffering: no`를 따른다.
+- No sticky sessions needed. Whatever worker a client connects to, it receives the same events through the NATS bus.
+- With several workers, `eventBus` (driver `nats`) is required. Without it a cluster worker does not start (`LOCAL_IN_CLUSTER`; with a deliberate single worker set `allowInCluster: true`).
+- `maxConnections` is per worker.
+- Rooms belong to their connection and are gone after a reconnect: join again in `authenticate`'s `rooms` or in `onOpen`.
+- Order: what one publisher sends arrives in order; there is no global order across publishers. When NATS is down, `publish` fails with a coded error and that event is lost.
+- Browsers allow 6 connections per origin over HTTP/1.1. With many tabs use HTTP/2 (TLS) at the proxy.
+- The proxy idle limit must be longer than `heartbeatMs` (default 15 seconds). nginx honours `X-Accel-Buffering: no`.
 
-자세한 설정·동작은 [AI.md](AI.md)와 [개발 문서](../../docs/plugins/dokebi-sse/README.md), 실행 예는 [examples/27-sse](../../examples/27-sse/README.md).
+Detailed settings and behaviour are in [AI.md](AI.md) and the [design notes](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/plugins/dokebi-sse/README.md); a runnable example is [examples/27-sse](https://git.nyx-zone.com/dokebi/framework/-/blob/main/examples/27-sse/README.md).
 
-## 봉인 호스트 (D-0062)
+## Seal hosts (D-0062)
 
-seal 호스트의 스트림은 모든 이벤트의 data가 봉인된다. 브라우저는 `connectEvents({ path, seal: currentSealBridge() })`(`@dokebi/seal/http`)로 연다. 자세한 것은 [AI.md](AI.md) §5a와 [D-0062](../../docs/decisions/D-0062-http-seal.md).
+On a seal host the data of every event is sealed. The browser opens it with `connectEvents({ path, seal: currentSealBridge() })` (`@dokebi/seal/http`). See [AI.md](AI.md) §5a and [D-0062](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0062-http-seal.md).

package/dist/errors.d.ts

@@ -1,12 +1,14 @@
-export type SseErrorCode = 'INVALID_OPTIONS' | 'INVALID_ROUTE' | 'INVALID_IDENTITY' | 'INVALID_EVENT' | 'INVALID_DATA' | 'INVALID_TARGET' | 'INVALID_ROOM' | 'EVENT_TOO_LARGE' | 'ROOM_LIMIT' | 'FROZEN' | 'CLOSED' | 'BUS_UNAVAILABLE' | 'BUS_PUBLISH_FAILED' | 'SSE_LOCAL_IN_CLUSTER';
+import { DokebiError } from '@dokebi/core';
+export type SseErrorCode = 'INVALID_OPTIONS' | 'INVALID_ROUTE' | 'INVALID_IDENTITY' | 'INVALID_EVENT' | 'INVALID_DATA' | 'INVALID_TARGET' | 'INVALID_ROOM' | 'EVENT_TOO_LARGE' | 'ROOM_LIMIT' | 'FROZEN' | 'CLOSED' | 'BUS_UNAVAILABLE' | 'BUS_PUBLISH_FAILED' | 'LOCAL_IN_CLUSTER';
 /** Errors of @dokebi/sse; compare `code`, not the class (another copy of the package may throw). */
-export declare class SseError extends Error {
-    readonly code: SseErrorCode;
+export declare class SseError extends DokebiError<SseErrorCode> {
     /** BUS_PUBLISH_FAILED: the event id and how many streams of this process already got it. */
     readonly id?: string;
     readonly local?: number;
-    constructor(code: SseErrorCode, message: string, options?: ErrorOptions & {
+    constructor(code: SseErrorCode, message: string, options?: {
+        readonly cause?: unknown;
         readonly id?: string;
         readonly local?: number;
+        readonly details?: unknown;
     });
 }

package/dist/errors.js

@@ -1,12 +1,32 @@
+import { DokebiError } from '@dokebi/core';
+const FIX = {
+    INVALID_OPTIONS: "Correct options.dokebi-sse in dokebi.yaml; details.issues names the paths and the plugin's options.schema.json lists what is allowed.",
+    INVALID_ROUTE: 'Give route a path starting with / (no query), an authenticate function, and optional onOpen/onClose functions, version text, constraints object and origins (* or exact https://host origins).',
+    INVALID_IDENTITY: 'Return { tenant, member, rooms? } from authenticate, with strings of 1 to 256 characters (or undefined to refuse with 401).',
+    INVALID_EVENT: 'Name events with a letter first and up to 64 of A-Z a-z 0-9 . _ : -, not starting with dokebi-.',
+    INVALID_DATA: 'Send data that JSON.stringify accepts (no BigInt, functions or cycles).',
+    INVALID_TARGET: 'Target { tenant, member?, room? } or { tenantPrefix, member?, room? } with strings of 1 to 256 characters.',
+    INVALID_ROOM: 'Rooms are strings of 1 to 256 characters.',
+    EVENT_TOO_LARGE: 'Send less data per event, or raise options.dokebi-sse.maxEventBytes (keep it below the bus maxPayloadBytes).',
+    ROOM_LIMIT: 'Join fewer rooms per stream, or raise options.dokebi-sse.maxRooms.',
+    FROZEN: 'Register SSE routes during setup (a plugin, module or app setup), not after start.',
+    CLOSED: 'Publish only while the application runs; this SSE plugin has been closed.',
+    BUS_UNAVAILABLE: 'The event bus is not connected; retry after it recovers (warn BUS_UNAVAILABLE and info "SSE bus available again" in the log).',
+    BUS_PUBLISH_FAILED: 'This process delivered the event (local), the bus did not take it: retry, or check the bus connection; the cause has its error.',
+    LOCAL_IN_CLUSTER: 'Set options.dokebi-sse.eventBus to a dokebi-event-bus bus with driver nats, or allowInCluster: true for a deliberate single-worker cluster.',
+};
 /** Errors of @dokebi/sse; compare `code`, not the class (another copy of the package may throw). */
-export class SseError extends Error {
-    code;
+export class SseError extends DokebiError {
     /** BUS_PUBLISH_FAILED: the event id and how many streams of this process already got it. */
     id;
     local;
     constructor(code, message, options) {
-        super(message, options);
-        this.code = code;
+        super(code, message, {
+            plugin: 'dokebi-sse',
+            fix: FIX[code],
+            ...(options?.cause === undefined ? {} : { cause: options.cause }),
+            ...(options?.details === undefined ? {} : { details: options.details }),
+        });
         this.name = 'SseError';
         if (options?.id !== undefined)
             this.id = options.id;