docs(realtime): state that composition code owns hidden, logout and kill-switch closing (04-04)

The registry validates hiddenPolicy, killSwitchId and fallback, but the
reference runtime reads none of them, and isCurrent is checked only at loop
boundaries. The comments and design 5.4-5.6 now say close() is the caller's.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-26 00:19:52 +09:00
co-authored by Claude Opus 5.5
parent 7e37660ba6
commit 1fe9bfdc2d
3 changed files with 36 additions and 2 deletions
@@ -803,6 +803,17 @@ attempt당 상한은 30초다.
### 5.4 Visibility, page lifecycle와 network
5.4~5.6의 "기본 동작"은 조합 코드가 해야 하는 일이다. reference runtime은 이
동작을 강제하지 않는다.
- reconnect coordinator가 따르는 환경 신호는 online 하나다
(`reconnect-coordinator.ts:105-112`). SSE와 WebSocket 연결에는 visibility 입력이
없다. visibility를 직접 듣는 것은 polling뿐이다
(`polling/bounded-poll-coordinator.ts:169-175`).
- registry의 `hiddenPolicy`, `killSwitchId`, `fallback`은 검증만 하고 읽지 않는다
(`src/contracts/realtime-streams.ts:74-79`). hidden·`pagehide`·logout 때 닫기,
kill switch, fallback 전환은 조합 코드가 한다.
| signal | 기본 동작 |
| --- | --- |
| `visibilitychange -> hidden` | 새 Polling 중지, configured grace 뒤 live connection pause/close |
@@ -846,10 +857,17 @@ session authority announces local transition
late socket event, poll response, auth recovery, snapshot, notification handoff와
Service Worker message는 old generation/scope면 적용하지 않는다.
reference runtime에서 위 흐름의 "close SSE/WebSocket"은 조합 코드가 reconnect
coordinator의 `close()`를 불러야 일어난다. `isCurrent`는 attempt·sleep·waitClosed
경계에서만 확인하므로, 열린 채 조용한 session은 다음 event나 server close까지
남는다(`reconnect-coordinator.ts:148-154`). 그동안 도착한 event는 stream
coordinator의 scope fence가 막는다.
long-lived connection은 connect-time authorization만 신뢰하지 않는다. backend는
active subscription의 permission/session revoke를 control event 또는 close로
전파하고, registry-owned `maxConnectionAge`/reauth deadline 안에 current
credential로 재연결하게 한다. SSE처럼 별도 subscribe command가 없는 transport는
credential로 재연결하게 한다. `maxConnectionAge`는 아직 registry 필드가 아니다.
채택하는 제품이 조합 코드에서 정한다. SSE처럼 별도 subscribe command가 없는 transport는
권한 변경 시 server가 stream을 종료해야 한다. server hint는 client hard
connection-age ceiling을 늘릴 수 없다.
@@ -875,7 +893,7 @@ best-effort hint다.
- tab 하나당 selected primary transport physical connection 1개
- WebSocket logical subscription multiplexing 또는 SSE single-feed local dispatch
- hidden tab close/pause 정책
- hidden tab close/pause 정책(조합 코드가 적용한다. 5.4 참조)
- visible 복귀 시 authoritative snapshot
SharedWorker나 leader election으로 origin 전체 connection을 하나로 만드는 기능은
@@ -102,6 +102,10 @@ export type RealtimeReconnectSession<
close(): void;
}>;
/**
* Online is the only environment signal the coordinator follows. Visibility,
* pagehide and the registry's `hiddenPolicy` are composition code's job.
*/
export type RealtimeReconnectEnvironment = Readonly<{
online(): boolean;
subscribeOnline(listener: (online: boolean) => void): () => void;
@@ -141,6 +145,12 @@ export type RealtimeReconnectCoordinatorDependencies<
): RealtimeResult<void>;
clock?: ClockPort;
random?: () => number;
/**
* Checked only at loop boundaries (around attempt, sleep and waitClosed),
* never while a session stays open. On logout or account switch call
* `close()`; otherwise a quiet open session stays open until its next
* event or server close.
*/
isCurrent?: () => boolean;
}>;
+6
View File
@@ -71,6 +71,12 @@ export type RealtimeRecoveryProfile =
rebuildInputId: string;
}>;
/**
* `fallback`, `hiddenPolicy` and `killSwitchId` are validated declarations.
* The reference runtime in `src/adapters/realtime/` does not read or enforce
* them: closing on hidden, pagehide and logout, the kill switch and the
* fallback are composition code's responsibility (design 5.4-5.6).
*/
export type RealtimeStreamRegistration = Readonly<{
id: StreamRegistrationId;
protocol: typeof REALTIME_EVENT_PROTOCOL;