diff --git a/docs/architecture/realtime-events-web-push-and-bounded-polling.md b/docs/architecture/realtime-events-web-push-and-bounded-polling.md index 6a8ad5f1..d8701328 100644 --- a/docs/architecture/realtime-events-web-push-and-bounded-polling.md +++ b/docs/architecture/realtime-events-web-push-and-bounded-polling.md @@ -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을 하나로 만드는 기능은 diff --git a/src/adapters/realtime/reconnect-coordinator.ts b/src/adapters/realtime/reconnect-coordinator.ts index 0c529a58..664c1b43 100644 --- a/src/adapters/realtime/reconnect-coordinator.ts +++ b/src/adapters/realtime/reconnect-coordinator.ts @@ -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; 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; }>; diff --git a/src/contracts/realtime-streams.ts b/src/contracts/realtime-streams.ts index 42675281..d920640e 100644 --- a/src/contracts/realtime-streams.ts +++ b/src/contracts/realtime-streams.ts @@ -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;