From 54e6bce9d2cc11b8ddff17ae9613da2b3416a29b Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 24 Sep 2026 13:16:02 +0900 Subject: [PATCH] fix(realtime): reset the retry budget only after a signal on a stable open (Q-6.4-7) isReconnectAttemptResetEligible returned true on either a valid heartbeat/event or stableOpenMs elapsed. A server or proxy that sends one `:` comment and drops kept attemptIndex at 0, so the delay stayed in [0, baseDelay) and maxAttempts/maxElapsed were never reached (many clients reconnecting in lockstep). Both conditions are now required. The reconnect coordinator uses this helper at both close paths, so no coordinator change is needed. The two design docs that stated "or" now say "and". Existing tests encoded the old "either" rule (policy unit test and the coordinator "resets a spent retry" test) and are rewritten. RED: the policy test (heartbeat-only returned true) and the coordinator test (heartbeat on an instant close still reset: 3 attempts, expected 2) failed before the fix. Gates: architecture, types app/test, lint, adapter-inventory, test:unit, test:component pass. Co-Authored-By: Claude Opus 5.5 --- ...igned-implementation-closed-deep-design.md | 2 +- ...ime-events-web-push-and-bounded-polling.md | 5 +-- src/adapters/realtime/reconnect-policy.ts | 8 ++++- .../realtime-reconnect-coordinator.test.ts | 36 +++++++++++-------- .../realtime-reconnect-policy.test.ts | 32 ++++++----------- 5 files changed, 43 insertions(+), 40 deletions(-) diff --git a/docs/architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md b/docs/architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md index cd0c5d76..a7bec984 100644 --- a/docs/architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md +++ b/docs/architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md @@ -2604,7 +2604,7 @@ export const DEFAULT_REALTIME_RECONNECT_POLICY = Object.freeze({ - remaining episode budget 초과 hint: reconnect 종료; - attempts/exhausted: `DEGRADED`, explicit recovery action; - automatic new episode cooldown: 300,000ms; -- valid event/heartbeat 또는 60s stable open 후 attempt counter reset; +- valid event/heartbeat를 받고 60s stable open도 지난 뒤에만 attempt counter reset; - offline state에서는 timer 대신 `online` signal을 기다림. ### 14.4 error classification 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 3f65fbc5..fc581c94 100644 --- a/docs/architecture/realtime-events-web-push-and-bounded-polling.md +++ b/docs/architecture/realtime-events-web-push-and-bounded-polling.md @@ -764,8 +764,9 @@ effectiveDelay = max(localDelay, validServerNotBefore) bound로 취급한다. `effectiveDelay`가 implementation max delay나 남은 elapsed budget을 넘으면 낮춰 clamp하지 않고 reconnect/poll을 종료해 `DEGRADED`/`STALE`로 전환한다. -- connection이 잠깐 열렸다는 이유로 attempt를 0으로 만들지 않는다. stable-open - window 또는 valid heartbeat/event 뒤에만 reset한다. +- connection이 잠깐 열렸다는 이유로 attempt를 0으로 만들지 않는다. valid + heartbeat/event를 받았고 stable-open window도 지났을 때만 reset한다(둘 중 + 하나만으로는 reset하지 않는다). - 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/reconnect-policy.ts b/src/adapters/realtime/reconnect-policy.ts index 7bc62312..c3edc53c 100644 --- a/src/adapters/realtime/reconnect-policy.ts +++ b/src/adapters/realtime/reconnect-policy.ts @@ -126,14 +126,20 @@ export function reconnectBudgetRemaining( return Math.max(0, policy.maxElapsedMs - (nowMs - startedAtMs)); } +/** + * A connection earns a fresh retry budget only when it both proved itself + * with a valid heartbeat/event and stayed open for `stableOpenMs`. Either + * alone lets a server that sends one comment and drops keep the budget at + * zero forever. + */ export function isReconnectAttemptResetEligible(input: Readonly<{ policy: ReconnectPolicy; openedAtMs: number; nowMs: number; observedValidHeartbeatOrEvent: boolean; }>): boolean { - if (input.observedValidHeartbeatOrEvent) return true; return ( + input.observedValidHeartbeatOrEvent && Number.isFinite(input.openedAtMs) && Number.isFinite(input.nowMs) && input.nowMs - input.openedAtMs >= input.policy.stableOpenMs diff --git a/tests/unit/realtime/realtime-reconnect-coordinator.test.ts b/tests/unit/realtime/realtime-reconnect-coordinator.test.ts index 6d337439..1eb73cb1 100644 --- a/tests/unit/realtime/realtime-reconnect-coordinator.test.ts +++ b/tests/unit/realtime/realtime-reconnect-coordinator.test.ts @@ -433,8 +433,8 @@ describe("realtime reconnect coordinator", () => { expect(result).toBe(terminal); }); - it("resets a spent retry only after policy eligibility", async () => { - const runScenario = async (markValid: boolean) => { + it("resets a spent retry only after a valid signal and a stable open", async () => { + const runScenario = async (markValid: boolean, openMs: number) => { const clock = new ManualClock(); const firstFailure = realtimeFailure( "CONNECT_TIMEOUT", @@ -452,6 +452,7 @@ describe("realtime reconnect coordinator", () => { false, ); const closeSession = vi.fn(); + const closing = deferred>(); let attempts = 0; const coordinator = createRealtimeReconnectCoordinator({ policy: policy({ maxAttempts: 1 }), @@ -474,8 +475,7 @@ describe("realtime reconnect coordinator", () => { receipt: RealtimeReconnectOutcome, ) => receipt, close: closeSession, - waitClosed: () => - failed(sessionFailure, 0), + waitClosed: () => closing.promise, }), ); } @@ -486,12 +486,12 @@ describe("realtime reconnect coordinator", () => { const running = coordinator.run(); await flush(); clock.advance(0); + await flushUntil(() => attempts === 2); await flush(); - if (markValid) { - await flushUntil(() => clock.sleepCalls.length === 2); - expect(clock.sleepCalls).toEqual([0, 0]); - clock.advance(0); - } + clock.advance(openMs); + closing.resolve(failed(sessionFailure, 0)); + await flushUntil(() => clock.sleepCalls.length === 2); + clock.advance(0); const result = await running; return { attempts, @@ -502,12 +502,20 @@ describe("realtime reconnect coordinator", () => { }; }; - const unstable = await runScenario(false); - expect(unstable.attempts).toBe(2); - expect(unstable.result).toBe(unstable.sessionFailure); - expect(unstable.closeSession).toHaveBeenCalledOnce(); + // A heartbeat on a short-lived connection, or a quiet long one, keeps + // the spent budget; only both together reset it. + for (const [markValid, openMs] of [ + [false, 0], + [true, 499], + [false, 500], + ] as const) { + const spent = await runScenario(markValid, openMs); + expect(spent.attempts).toBe(2); + expect(spent.result).toBe(spent.sessionFailure); + expect(spent.closeSession).toHaveBeenCalledOnce(); + } - const eligible = await runScenario(true); + const eligible = await runScenario(true, 500); expect(eligible.attempts).toBe(3); expect(eligible.result).toBe(eligible.terminal); expect(eligible.closeSession).toHaveBeenCalledOnce(); diff --git a/tests/unit/realtime/realtime-reconnect-policy.test.ts b/tests/unit/realtime/realtime-reconnect-policy.test.ts index 4e4de156..b95a6562 100644 --- a/tests/unit/realtime/realtime-reconnect-policy.test.ts +++ b/tests/unit/realtime/realtime-reconnect-policy.test.ts @@ -80,31 +80,19 @@ describe("realtime reconnect policy", () => { expect(parseRetryAfterDelay("-1", 0)).toBeNull(); }); - it("resets attempts only after stable open or a valid signal", () => { - expect( + it("resets attempts only after a valid signal on a stable open", () => { + const eligible = (nowMs: number, observed: boolean) => isReconnectAttemptResetEligible({ policy, openedAtMs: 10, - nowMs: 29_000, - observedValidHeartbeatOrEvent: false, - }), - ).toBe(false); - expect( - isReconnectAttemptResetEligible({ - policy, - openedAtMs: 10, - nowMs: 30_010, - observedValidHeartbeatOrEvent: false, - }), - ).toBe(true); - expect( - isReconnectAttemptResetEligible({ - policy, - openedAtMs: 10, - nowMs: 11, - observedValidHeartbeatOrEvent: true, - }), - ).toBe(true); + nowMs, + observedValidHeartbeatOrEvent: observed, + }); + expect(eligible(29_000, false)).toBe(false); + expect(eligible(30_010, false)).toBe(false); + expect(eligible(11, true)).toBe(false); + expect(eligible(30_009, true)).toBe(false); + expect(eligible(30_010, true)).toBe(true); expect(reconnectBudgetRemaining(policy, 1_000, 2_000)).toBe( 299_000, );