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 dd8d6398..cf0a78db 100644 --- a/docs/architecture/realtime-events-web-push-and-bounded-polling.md +++ b/docs/architecture/realtime-events-web-push-and-bounded-polling.md @@ -1963,8 +1963,8 @@ credential을 보호할 수 있다고 주장하지 않는다. | `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. 환경은 online인데 서버·프록시에 닿지 않은 것(SSE fetch·reader 거절, WebSocket `error`)도 이 kind다(1103/04-04, `retryable: true`). poll은 `execute`가 돌려준 결과의 kind를 쓴다. V3 실행기는 fetch 거절을 던지지 않고 `NETWORK_FAILURE` 결과로 돌려주므로, `execute`가 그 결과를 이 kind로 바꾼다. 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. poll `execute`가 던지거나 모양이 틀린 결과를 돌려준 것도 이 kind다. 조합 코드 결함이라 서버 장애로 재시도하지 않는다(1105/04-02, `retryable: false`) | terminal/rollout rollback | +| `PROVIDER_UNAVAILABLE` | backend/push/hosting unavailable. 환경은 online인데 서버·프록시에 닿지 않은 것(SSE fetch·reader 거절, WebSocket `error`)도 이 kind다(1103/04-04, `retryable: true`). poll은 `execute`가 돌려준 결과의 kind를 쓴다. V3 실행기는 fetch 거절을 던지지 않고 `NETWORK_FAILURE` 결과로 돌려주므로, `execute`가 그 결과를 이 kind로 바꾼다. reconnect coordinator는 조합 코드의 `attempt`·`waitClosed`가 던지거나 거절해도 이 kind로 보고 backoff로 재시도한다(operation `CONNECT`·`RECEIVE`, `retryable: true`, 1106/04-01). 연결 실패를 던지는 라이브러리를 감싼 transport도 회복하게 하려는 규칙이다. 그래서 endpoint 같은 설정 검사는 `attempt` 밖, 조합 코드가 bridge를 만들 때 한다. SSE·WebSocket 연결 생성은 틀린 endpoint에 `TypeError`를 던지고, `attempt` 안이면 그 오류가 서버 장애처럼 예산 끝까지 재시도된다. 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. poll `execute`가 던지거나 모양이 틀린 결과를 돌려준 것도 이 kind다. 조합 코드 결함이라 서버 장애로 재시도하지 않는다(1105/04-02, `retryable: false`). reconnect coordinator에서는 `classifyClosed`(operation `CONNECT`)나 `confirmTransportBarrier`(operation `RECOVER`)가 던진 것이 이 kind다. reconnect `attempt`·`waitClosed`의 던짐은 `PROVIDER_UNAVAILABLE`이다(1106/04-01). poll `execute`는 던지지 않는 V3 실행기를 감싸고, `attempt`는 던질 수 있는 연결 API를 감싸기 때문이다 | 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 | | `EVENT_CONFLICT` | 같은 ID/sequence가 다른 event를 가리킴 | terminal protocol conflict + resync/rollback | diff --git a/src/adapters/realtime/reconnect-coordinator.ts b/src/adapters/realtime/reconnect-coordinator.ts index 2e2653a3..e4884e76 100644 --- a/src/adapters/realtime/reconnect-coordinator.ts +++ b/src/adapters/realtime/reconnect-coordinator.ts @@ -99,9 +99,14 @@ export type RealtimeReconnectCloseClassification = export type RealtimeReconnectSession< ClosedReceipt = RealtimeReconnectOutcome, > = Readonly<{ + /** + * 1106/04-01. A throw or rejection reads like a lost connection: + * PROVIDER_UNAVAILABLE on RECEIVE, `retryable: true`, retried with backoff. + */ waitClosed(): | ClosedReceipt | Promise; + /** A throw ends the run with PROTOCOL_MISMATCH and no retry. */ classifyClosed( receipt: ClosedReceipt, ): RealtimeReconnectCloseClassification; @@ -164,6 +169,18 @@ export type RealtimeReconnectCoordinatorDependencies< > = Readonly<{ policy: ReconnectPolicy; environment: RealtimeReconnectEnvironment; + /** + * 1106/04-01. Return every connect failure as a result. A throw or + * rejection is read as a transport failure, not a defect: the attempt ends + * PROVIDER_UNAVAILABLE on CONNECT, `retryable: true`, and is retried with + * backoff, so a transport around a library that throws on a failed connect + * still recovers. The poll coordinator reads a throwing `execute` the other + * way (PROTOCOL_MISMATCH, no retry): the V3 executor it wraps never throws. + * Check the transport's settings outside `attempt`, when composition builds + * it. `createFetchSseConnection` and `createWebSocketConnection` throw a + * TypeError on a wrong endpoint; inside `attempt` that TypeError would be + * retried until the budget ends and look like a server outage. + */ attempt( context: RealtimeReconnectAttemptContext, ): @@ -175,7 +192,10 @@ export type RealtimeReconnectCoordinatorDependencies< RealtimeReconnectAttemptSuccess > >; - /** Build the result with `realtimeSuccess`/`realtimeFailure`. */ + /** + * Build the result with `realtimeSuccess`/`realtimeFailure`. A throw ends + * the run with PROTOCOL_MISMATCH on RECOVER and no retry. + */ confirmTransportBarrier( recovery: RealtimeCommittedRecovery, ): RealtimeResult; diff --git a/tests/unit/realtime/realtime-reconnect-coordinator.test.ts b/tests/unit/realtime/realtime-reconnect-coordinator.test.ts index 5ef1faf7..191a7f6e 100644 --- a/tests/unit/realtime/realtime-reconnect-coordinator.test.ts +++ b/tests/unit/realtime/realtime-reconnect-coordinator.test.ts @@ -1758,16 +1758,29 @@ class FakeWebSocket implements WebSocketFacade { /** * The smallest SSE bridge design 6.3 leaves to composition: the attempt ends * at `onOpen` and the rest of the read is the session. + * + * 1106/04-01. The coordinator retries a throwing attempt as + * PROVIDER_UNAVAILABLE, so the bridge checks its connection settings here, + * when it is built: a wrong endpoint throws before any run. Each attempt + * still makes its own connection, because the session's `close` ends that + * connection for good. */ -function sseAttempt(fetcher: typeof fetch, clock: ManualClock) { +function sseAttempt( + fetcher: typeof fetch, + clock: ManualClock, + endpoint = "https://app.example.test/events", +) { + const settings = Object.freeze({ + endpoint, + applicationOrigin: "https://app.example.test", + recoveryMode: "CURSOR" as const, + fetcher, + clock, + }); + // Creating a connection checks the settings and sends nothing. + createFetchSseConnection(settings).close(); return async (context: RealtimeReconnectAttemptContext) => { - const connection = createFetchSseConnection({ - endpoint: "https://app.example.test/events", - applicationOrigin: "https://app.example.test", - recoveryMode: "CURSOR", - fetcher, - clock, - }); + const connection = createFetchSseConnection(settings); const open = deferred<"OPEN">(); const reading = readSseForReconnect(connection, { resumeCursor: null, @@ -2435,4 +2448,106 @@ describe("results that composition code hands the reconnect coordinator", () => ); expect(clock.sleepCalls).toEqual([]); }); + + // 1106/04-01. The rule the attempt and session types state. A throwing + // attempt or waitClosed is a transport failure and is retried; poll reads a + // throwing execute the other way (1105/04-02). + it.each([ + ["attempt", "CONNECT"], + ["waitClosed", "RECEIVE"], + ] as const)( + "retries a throwing %s as PROVIDER_UNAVAILABLE on %s", + async (thrower, operation) => { + const clock = new ManualClock(); + const observed: string[] = []; + let attempts = 0; + const coordinator = createRealtimeReconnectCoordinator({ + policy: policy(), + environment: new MutableOnlineEnvironment(true), + clock, + random: () => 0.5, + confirmTransportBarrier: confirmationSucceeded, + attempt: () => { + attempts += 1; + if (thrower === "attempt") throw new TypeError("composer defect"); + return opened>( + Object.freeze({ + classifyClosed: ( + receipt: RealtimeReconnectOutcome, + ) => receipt, + close: vi.fn(), + waitClosed: () => { + throw new TypeError("composer defect"); + }, + }), + ); + }, + observe: (observation) => observed.push(observationLabel(observation)), + }); + + let result: RealtimeResult | null = null; + void coordinator.run().then((value) => { + result = value; + }); + await advanceUntil(clock, () => result !== null); + + expect(attempts).toBe(3); + expect(clock.sleepCalls).toEqual([50, 100]); + expect(result).toEqual({ + ok: false, + error: { kind: "PROVIDER_UNAVAILABLE", operation, retryable: true }, + }); + expect( + observed.filter((label) => label.startsWith("RETRY_SCHEDULED")), + ).toEqual([ + "RETRY_SCHEDULED:PROVIDER_UNAVAILABLE", + "RETRY_SCHEDULED:PROVIDER_UNAVAILABLE", + ]); + expect(observed.at(-1)).toBe( + "RUN_ENDED:PROVIDER_UNAVAILABLE:EXHAUSTED", + ); + }, + ); + + it("ends the run without a retry when classifyClosed throws", async () => { + const clock = new ManualClock(); + let attempts = 0; + const coordinator = createRealtimeReconnectCoordinator({ + policy: policy(), + environment: new MutableOnlineEnvironment(true), + clock, + confirmTransportBarrier: confirmationSucceeded, + attempt: () => { + attempts += 1; + return opened>( + Object.freeze({ + classifyClosed: () => { + throw new TypeError("composer defect"); + }, + close: vi.fn(), + waitClosed: closedSuccessfully, + }), + ); + }, + }); + + await expect(coordinator.run()).resolves.toEqual( + realtimeFailure("PROTOCOL_MISMATCH", "CONNECT", false), + ); + expect(attempts).toBe(1); + expect(clock.sleepCalls).toEqual([]); + }); + + // Review 04-R2 built this endpoint's connection inside the attempt: no + // request, three attempts, then PROVIDER_UNAVAILABLE (EXHAUSTED). The bridge + // now checks its settings when it is built, so the run never starts. + it("refuses a wrong SSE endpoint when the bridge is built", () => { + const fetcher = vi.fn(); + const build = () => + sseAttempt(fetcher, new ManualClock(), "http://app.example.test/events"); + + expect(build).toThrow(TypeError); + expect(build).toThrow("SSE endpoint must be fixed same-origin HTTPS."); + expect(fetcher).not.toHaveBeenCalled(); + }); });