docs(realtime): heartbeat를 멈춘 WebSocket이 예산을 새로 받지 못함을 적는다

문제
heartbeatEligible()이 false면 WebSocket 연결은 HEARTBEAT를 보내지
않는다. 그러면 HEARTBEAT_ACK가 없고, 이벤트도 없는 조용한 stream은
유효 신호가 없어 reconnect 예산이 초기화되지 않는다(0929 실험 E7).
훅에 주석이 없어 채택자가 이 결과를 코드 두 곳(heartbeat 송신,
isReconnectAttemptResetEligible)을 같이 읽어야 안다.

고른 방법
- 0929/04-04의 최소 방향대로 훅 옆에 주석을 달고 설계 5.3 예산 문단에
  같은 문장을 더한다. hidden 연결은 닫거나 visible 복귀 때 새 run을
  만들라고 적는다. 동작은 바꾸지 않는다.

위험·한계
- 동작 변경이 없다. 주석이 코드와 어긋나면 잡는 검사는 없다.

검증
- 바꾼 파일 eslint 통과. 주석만 바꿨다.

Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 2절 0929/04-04
This commit is contained in:
DongHyeonka
2026-11-04 20:31:51 +09:00
parent 5b2106df25
commit 5d0f5ad7f8
2 changed files with 11 additions and 1 deletions
@@ -810,7 +810,10 @@ effectiveDelay = max(localDelay, validServerNotBefore)
`waitClosed` throw를 포함한 session의 모든 종료 경로에서 한다
(`reconnect-coordinator.ts:888-902`). valid heartbeat는 SSE `onComment`와
WebSocket `HEARTBEAT_ACK` 관측이다. 조합 코드가 이를
`markValidHeartbeatOrEvent`로 넘긴다.
`markValidHeartbeatOrEvent`로 넘긴다. WebSocket `heartbeatEligible()`이
false인 동안(hidden 탭)은 heartbeat를 보내지 않아 ACK가 없다. 조용한
stream은 그동안 예산을 새로 받지 못한다. hidden 연결은 닫거나 visible
복귀 때 새 run을 만든다(0929/04-04).
- stream reconnect는 realtime recovery coordinator, credential recovery는
session owner, Poll attempt 사이 cadence는 poll coordinator가 각각 소유한다.
Poll-bound REST transport retry와 Query retry는 끈다. 같은 logical recovery의
@@ -179,6 +179,13 @@ export type WebSocketConnectionDependencies = Readonly<{
| RealtimeResult<void>
| Promise<RealtimeResult<void>>;
onRecoveryRequired(request: WebSocketRecoveryRequest): void;
/**
* False pauses sending HEARTBEAT (e.g. a hidden tab, design 6.4); absent or
* true sends it. While paused no HEARTBEAT_ACK arrives, so a quiet stream
* has no valid signal and the reconnect budget is never reset
* (`isReconnectAttemptResetEligible`). Close a hidden connection, or start a
* new run when the tab is visible again (0929/04-04).
*/
heartbeatEligible?(): boolean;
observe?(observation: WebSocketConnectionObservation): void;
verifyCursorRotation?(input: Readonly<{