From 17fa8d1f653e59ea1fdb75162e3cf973ef8b8da2 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Tue, 3 Nov 2026 20:21:30 +0900 Subject: [PATCH] =?UTF-8?q?fix(realtime):=20live-poll=20handoff=20?= =?UTF-8?q?=EB=A7=88=EA=B0=90=20=EC=8B=A4=ED=8C=A8=EB=A5=BC=2013.1?= =?UTF-8?q?=EC=9D=98=20kind=EB=A1=9C=20=EB=B3=B4=EA=B3=A0=ED=95=9C?= =?UTF-8?q?=EB=8B=A4=20(04-02)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 1196b86은 stream coordinator의 마감 실패만 13.1 어휘로 바꿨다. live↔Poll handoff coordinator는 아직 네 마감을 모두 `IDLE_TIMEOUT`으로 보고한다. 설계 13.1에서 `IDLE_TIMEOUT`은 전송 idle(heartbeat/byte deadline → close + bounded reconnect)이다. 그래서 관측에서 "서버가 조용함"과 "우리 effect·checkpoint가 멈춤"을 kind로 나눌 수 없다. - switchToPoll quiescence 마감: IDLE_TIMEOUT/RECOVER - activateProbe quiescence 마감: IDLE_TIMEOUT/RECOVER - checkpoint 마감: IDLE_TIMEOUT/RECOVER - close drain 마감: IDLE_TIMEOUT/CLOSE 고른 방법: 결정 (a)를 1196b86과 같은 방식으로 적용한다. kind만 바꾸고 operation, retryable(전과 같이 true), fail-close 동작은 그대로 둔다. - quiescence 마감 → APPLY_FAILED/RECOVER. 기다리는 것은 이전 writer의 apply effect tail이다. stream coordinator의 effect 마감과 같은 kind다. APPLY_FAILED의 기본 retryable은 false라 true를 명시했다. 두 곳의 같은 분기를 `quiescenceFailure` 하나로 합쳤다. - checkpoint 마감 → PROVIDER_UNAVAILABLE/RECOVER. checkpoint authority가 throw할 때와 같은 kind다. - close drain 마감 → PROVIDER_UNAVAILABLE/CLOSE. stream·reconnect coordinator의 drain 상한과 같다. 이전부터 timer 실패도 같은 값이라 두 분기를 하나로 합쳤다. - 13.1 표: IDLE_TIMEOUT 행에서 handoff를 빼고 "내부 task 마감에는 쓰지 않는다"로 적었다. APPLY_FAILED·PROVIDER_UNAVAILABLE 행에 handoff 마감과 retryable 값, 뒤 동작을 적었다. 남은 IDLE_TIMEOUT 생성 지점은 SSE·WS의 RECEIVE·SUBSCRIBE(전송 idle)뿐이다. 버린 대안: - retryable도 kind 기본값으로(quiescence가 false가 됨): 결정 범위는 어휘다. 재시도 판단 변경은 따로 정한다. - close 마감에 CLOSED: 1196b86과 같은 이유로 버렸다. 아직 writer가 settle하지 않았는데 "닫힘"으로 읽힌다. 위험·한계: - 배럴로 공개된 handoff coordinator 결과의 kind가 바뀐다. IDLE_TIMEOUT을 보던 조합 코드는 APPLY_FAILED·PROVIDER_UNAVAILABLE을 봐야 한다. repo 안에 소비자는 없다(AVAILABLE_NOT_COMPOSED). - handoff에는 observer가 없어 관측 reason은 바뀌는 것이 없다. - 같은 APPLY_FAILED라도 stream coordinator는 retryable:false, handoff는 true다. 13.1 표에 둘 다 적었다. - realtime 레시피 gzip 40,902 → 40,878 B(한도 42,200). 검증: - RED: 기대값을 먼저 바꾸고 activateProbe quiescence 마감 테스트를 새로 넣은 뒤 live-poll-handoff-coordinator.test.ts 실행 → 7 failed | 9 passed. 7건 모두 received kind IDLE_TIMEOUT(close 4건, switchToPoll quiescence, activateProbe quiescence, checkpoint). - GREEN: `node scripts/run-vitest.ts run tests/unit/realtime` 14 files, 231 passed. - tsc app·test·recipes 통과, 바꾼 두 파일 eslint 통과, `check-optional-recipes`(source) PASS, `verify-documentation-readiness` PASS_SCOPED, `check-adapter-inventory` PASS. - 미실행: `check:architecture`(pnpm 필요). Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.1 04-02, 14.4 --- ...ime-events-web-push-and-bounded-polling.md | 6 +-- .../realtime/live-poll-handoff-coordinator.ts | 46 +++++++++++-------- .../live-poll-handoff-coordinator.test.ts | 43 ++++++++++++++--- 3 files changed, 65 insertions(+), 30 deletions(-) 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 fd1db869..0f192bd5 100644 --- a/docs/architecture/realtime-events-web-push-and-bounded-polling.md +++ b/docs/architecture/realtime-events-web-push-and-bounded-polling.md @@ -1895,11 +1895,11 @@ credential을 보호할 수 있다고 주장하지 않는다. | `UNSUPPORTED` | browser capability 없음 | declared fallback | | `OFFLINE` | network hint/attempt failure | online hint 뒤 bounded check | | `CONNECT_TIMEOUT` | open deadline 초과 | bounded reconnect | -| `IDLE_TIMEOUT` | transport: heartbeat/byte/unsubscribe deadline 초과(operation `RECEIVE`·`SUBSCRIBE`). handoff coordinator의 quiescence·checkpoint·close deadline 초과(operation `RECOVER`·`CLOSE`) | transport: close + bounded reconnect. handoff 마감은 재연결로 풀리지 않는다: 그 전환을 fail-close한다(결과는 kind 기본값대로 retryable). 두 뜻은 `operation`으로 구분한다 | +| `IDLE_TIMEOUT` | transport: heartbeat/byte/unsubscribe deadline 초과(operation `RECEIVE`·`SUBSCRIBE`). 내부 task 마감에는 쓰지 않는다 | close + bounded reconnect | | `AUTH_REQUIRED` | session expired/recovery 실패 | sign-in UX | | `FORBIDDEN` | stream/resource 거절 | retry 없음 | | `RATE_LIMITED` | connection/request/provider limit | bounded server hint | -| `PROVIDER_UNAVAILABLE` | backend/push/hosting unavailable. stream coordinator의 recovery deadline 초과(operation `RECOVER`)와 close drain deadline 초과(operation `CLOSE`)도 이 kind다(`retryable: false`) | bounded retry 또는 degraded. stream coordinator 마감은 재연결로 풀리지 않는다: task가 settle할 때까지 `DRAINING`을 유지한다. settle 뒤 recovery 마감은 다음 event가 recovery부터 하고, close 마감은 `CLOSED`가 된다 | +| `PROVIDER_UNAVAILABLE` | backend/push/hosting unavailable. stream coordinator의 recovery deadline 초과(operation `RECOVER`)와 close drain deadline 초과(operation `CLOSE`)도 이 kind다(`retryable: false`). live↔Poll handoff coordinator의 checkpoint deadline 초과(operation `RECOVER`)와 close drain deadline 초과(operation `CLOSE`)도 이 kind다(`retryable: true`) | bounded retry 또는 degraded. stream coordinator 마감은 재연결로 풀리지 않는다: task가 settle할 때까지 `DRAINING`을 유지한다. settle 뒤 recovery 마감은 다음 event가 recovery부터 하고, close 마감은 `CLOSED`가 된다. handoff checkpoint 마감은 그 전환을 fail-close하므로 새 handoff만 돌 수 있다. handoff close 마감 뒤에는 writer·checkpoint task가 settle하면 다시 부른 `close()`가 성공한다 | | `PROTOCOL_MISMATCH` | version/subprotocol/content type | terminal/rollout rollback | | `MALFORMED_EVENT` | state-bearing syntax/schema/exact-key 실패 | cursor 미진행, freshness `UNKNOWN`, close + registered recovery | | `MAPPING_CONTRACT_VIOLATION` | validated DTO의 registered mapper 실패 | effect/cache/cursor write 0, close + registered recovery | @@ -1910,7 +1910,7 @@ credential을 보호할 수 있다고 주장하지 않는다. | `SEQUENCE_GAP` | missing event | snapshot resync | | `CURSOR_EXPIRED` | replay retention 밖 | snapshot reset | | `QUEUE_OVERFLOW` | backpressure ceiling | close + registered snapshot/session rebuild | -| `APPLY_FAILED` | feature effect 실패. stream coordinator의 effect deadline 초과(operation `APPLY`, `retryable: false`)도 이 kind다 | cursor 미commit, bounded registered recovery. deadline 초과는 recovery를 바로 하지 않는다: task가 settle할 때까지 `DRAINING`을 유지하고, settle 뒤 다음 event가 recovery부터 한다 | +| `APPLY_FAILED` | feature effect 실패. stream coordinator의 effect deadline 초과(operation `APPLY`, `retryable: false`)도 이 kind다. live↔Poll handoff coordinator에서 이전 writer의 effect가 quiescence deadline 안에 끝나지 않은 것(operation `RECOVER`, `retryable: true`)도 이 kind다 | cursor 미commit, bounded registered recovery. deadline 초과는 recovery를 바로 하지 않는다: task가 settle할 때까지 `DRAINING`을 유지하고, settle 뒤 다음 event가 recovery부터 한다. handoff quiescence 마감은 그 전환을 fail-close하므로 새 handoff만 돌 수 있다 | | `POLL_BUDGET_EXHAUSTED` | lease 한도 도달 | stale/manual retry | | `PUSH_PERMISSION_DENIED` | 사용자 거절 | foreground fallback | | `PUSH_SUBSCRIPTION_STALE` | rotation/expiry/provider gone | bounded re-registration | diff --git a/src/adapters/realtime/live-poll-handoff-coordinator.ts b/src/adapters/realtime/live-poll-handoff-coordinator.ts index 5ab77f7c..9dbb9b83 100644 --- a/src/adapters/realtime/live-poll-handoff-coordinator.ts +++ b/src/adapters/realtime/live-poll-handoff-coordinator.ts @@ -398,12 +398,7 @@ export function createLivePollHandoffCoordinator( } if (quiescence !== "QUIESCED") { failClosed(); - return handoffFailure( - quiescence === "TIMED_OUT" - ? "IDLE_TIMEOUT" - : "PROVIDER_UNAVAILABLE", - "RECOVER", - ); + return quiescenceFailure(quiescence); } quiescing = null; const checkpoint = await establishCheckpoint( @@ -497,12 +492,7 @@ export function createLivePollHandoffCoordinator( } if (quiescence !== "QUIESCED") { failClosed(); - return handoffFailure( - quiescence === "TIMED_OUT" - ? "IDLE_TIMEOUT" - : "PROVIDER_UNAVAILABLE", - "RECOVER", - ); + return quiescenceFailure(quiescence); } quiescing = null; const checkpoint = await establishCheckpoint( @@ -588,8 +578,10 @@ export function createLivePollHandoffCoordinator( return handoffFailure("ABORTED", "RECOVER"); } if (selected.kind === "TIMEOUT") { + // 1101/04-02. Design 13.1: the checkpoint authority did not answer in + // time, the same kind as when it throws. candidate.controller.abort(); - return handoffFailure("IDLE_TIMEOUT", "RECOVER"); + return handoffFailure("PROVIDER_UNAVAILABLE", "RECOVER"); } if (selected.kind !== "VALUE") { candidate.controller.abort(); @@ -691,13 +683,12 @@ export function createLivePollHandoffCoordinator( quiescing = null; transitionCandidate = null; transitioning = false; - if (outcomes.includes("TIMED_OUT")) { - return handoffFailure("IDLE_TIMEOUT", "CLOSE"); - } - if (outcomes.includes("TIMER_FAILED")) { - return handoffFailure("PROVIDER_UNAVAILABLE", "CLOSE"); - } - return realtimeSuccess(undefined); + // 1101/04-02. A drain past its bound is PROVIDER_UNAVAILABLE/CLOSE, as in + // the stream and reconnect coordinators, never the transport's + // IDLE_TIMEOUT. + return outcomes.every((outcome) => outcome === "QUIESCED") + ? realtimeSuccess(undefined) + : handoffFailure("PROVIDER_UNAVAILABLE", "CLOSE"); } function inspect(): LivePollHandoffInspection { @@ -871,6 +862,21 @@ function handoffFailure( : realtimeFailure(kind, operation, retryable); } +/** + * 1101/04-02. Design 13.1: a prior writer that does not quiesce in time is a + * stalled effect, APPLY_FAILED, never the transport's IDLE_TIMEOUT. Retryable + * as before: the handoff fail-closes and only a new one can run. + */ +function quiescenceFailure( + outcome: Exclude, +): Extract, { ok: false }> { + return handoffFailure( + outcome === "TIMED_OUT" ? "APPLY_FAILED" : "PROVIDER_UNAVAILABLE", + "RECOVER", + true, + ); +} + function remapFailure( failure: RealtimeFailure, operation: RealtimeOperation, diff --git a/tests/unit/realtime/live-poll-handoff-coordinator.test.ts b/tests/unit/realtime/live-poll-handoff-coordinator.test.ts index 49a1eacd..410757d6 100644 --- a/tests/unit/realtime/live-poll-handoff-coordinator.test.ts +++ b/tests/unit/realtime/live-poll-handoff-coordinator.test.ts @@ -266,7 +266,7 @@ describe("live/poll authoritative writer handoff", () => { harness.clock.advance(100); await expect(closing).resolves.toMatchObject({ ok: false, - error: { kind: "IDLE_TIMEOUT", operation: "CLOSE" }, + error: { kind: "PROVIDER_UNAVAILABLE", operation: "CLOSE", retryable: true }, }); release?.(realtimeSuccess(undefined)); @@ -356,9 +356,11 @@ describe("live/poll authoritative writer handoff", () => { expect(harness.clock.sleepers).toHaveLength(1); harness.clock.advance(100); + // 1101/04-02. The prior writer's effect stalled (design 13.1), not the + // transport's IDLE_TIMEOUT. await expect(transition).resolves.toMatchObject({ ok: false, - error: { kind: "IDLE_TIMEOUT", operation: "RECOVER" }, + error: { kind: "APPLY_FAILED", operation: "RECOVER", retryable: true }, }); expect(harness.recover).not.toHaveBeenCalled(); expect(harness.coordinator.inspect()).toMatchObject({ @@ -367,6 +369,32 @@ describe("live/poll authoritative writer handoff", () => { }); }); + it("fails a probe activation closed when poll cannot quiesce before the bound", async () => { + const harness = createHarness({ + initial: "POLL", + apply: vi.fn(async ({ writer }) => + writer === "POLL" + ? await new Promise>(() => {}) + : realtimeSuccess(undefined), + ), + }); + void harness.coordinator.currentWriter()!.write("hung-poll", 4); + const live = expectProbe(harness.coordinator.beginLiveProbe()); + await flush(); + + const activation = live.activate(); + await flush(); + expect(harness.clock.sleepers).toHaveLength(1); + harness.clock.advance(100); + + await expect(activation).resolves.toMatchObject({ + ok: false, + error: { kind: "APPLY_FAILED", operation: "RECOVER", retryable: true }, + }); + expect(harness.recover).not.toHaveBeenCalled(); + expect(harness.coordinator.inspect().state).toBe("CLOSED"); + }); + it("keeps poll authoritative while probing, then recovers and drains live values serially", async () => { const firstLive = deferred>(); const order: string[] = []; @@ -550,9 +578,10 @@ describe("live/poll authoritative writer handoff", () => { expect(harness.clock.sleepers).toHaveLength(1); harness.clock.advance(100); + // 1101/04-02. The checkpoint authority did not answer in time. await expect(transition).resolves.toMatchObject({ ok: false, - error: { kind: "IDLE_TIMEOUT", operation: "RECOVER" }, + error: { kind: "PROVIDER_UNAVAILABLE", operation: "RECOVER", retryable: true }, }); expect(checkpointIsCurrent?.()).toBe(false); expect(harness.coordinator.inspect().state).toBe("CLOSED"); @@ -579,7 +608,7 @@ describe("live/poll authoritative writer handoff", () => { harness.clock.advance(100); await expect(closing).resolves.toMatchObject({ ok: false, - error: { kind: "IDLE_TIMEOUT", operation: "CLOSE" }, + error: { kind: "PROVIDER_UNAVAILABLE", operation: "CLOSE", retryable: true }, }); // RT-RR-03. A second close re-runs rather than replaying a cached verdict. // The writer is still hung, so it still reports a timeout. @@ -588,7 +617,7 @@ describe("live/poll authoritative writer handoff", () => { harness.clock.advance(100); await expect(second).resolves.toMatchObject({ ok: false, - error: { kind: "IDLE_TIMEOUT", operation: "CLOSE" }, + error: { kind: "PROVIDER_UNAVAILABLE", operation: "CLOSE", retryable: true }, }); }); @@ -616,7 +645,7 @@ describe("live/poll authoritative writer handoff", () => { harness.clock.advance(100); await expect(first).resolves.toMatchObject({ ok: false, - error: { kind: "IDLE_TIMEOUT", operation: "CLOSE" }, + error: { kind: "PROVIDER_UNAVAILABLE", operation: "CLOSE", retryable: true }, }); // The writer finishes after the first close gave up. @@ -654,7 +683,7 @@ describe("live/poll authoritative writer handoff", () => { harness.clock.advance(100); await expect(closing).resolves.toMatchObject({ ok: false, - error: { kind: "IDLE_TIMEOUT", operation: "CLOSE" }, + error: { kind: "PROVIDER_UNAVAILABLE", operation: "CLOSE", retryable: true }, }); harness.clock.advance(100);