From 5d0f5ad7f837b6ef17796f507e77f5dbfff17b99 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 4 Nov 2026 20:31:51 +0900 Subject: [PATCH] =?UTF-8?q?docs(realtime):=20heartbeat=EB=A5=BC=20?= =?UTF-8?q?=EB=A9=88=EC=B6=98=20WebSocket=EC=9D=B4=20=EC=98=88=EC=82=B0?= =?UTF-8?q?=EC=9D=84=20=EC=83=88=EB=A1=9C=20=EB=B0=9B=EC=A7=80=20=EB=AA=BB?= =?UTF-8?q?=ED=95=A8=EC=9D=84=20=EC=A0=81=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 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 --- .../realtime-events-web-push-and-bounded-polling.md | 5 ++++- src/adapters/realtime/websocket/websocket-connection.ts | 7 +++++++ 2 files changed, 11 insertions(+), 1 deletion(-) 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 93317107..4659ab70 100644 --- a/docs/architecture/realtime-events-web-push-and-bounded-polling.md +++ b/docs/architecture/realtime-events-web-push-and-bounded-polling.md @@ -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의 diff --git a/src/adapters/realtime/websocket/websocket-connection.ts b/src/adapters/realtime/websocket/websocket-connection.ts index 0417c313..db99cd95 100644 --- a/src/adapters/realtime/websocket/websocket-connection.ts +++ b/src/adapters/realtime/websocket/websocket-connection.ts @@ -179,6 +179,13 @@ export type WebSocketConnectionDependencies = Readonly<{ | RealtimeResult | Promise>; 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<{