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 b5071c30..c7d70955 100644 --- a/docs/architecture/realtime-events-web-push-and-bounded-polling.md +++ b/docs/architecture/realtime-events-web-push-and-bounded-polling.md @@ -780,9 +780,11 @@ effectiveDelay = max(localDelay, validServerNotBefore) `navigator.onLine`은 실제 backend reachability authority가 아니다. offline 대기 시간은 elapsed budget에 넣지 않는다. online으로 돌아오면 elapsed budget을 다시 시작하고 attempt 상한은 유지한다 - (`reconnect-coordinator.ts:553-562`). 이 대기는 환경 신호가 offline일 때만 - 한다. transport가 보고한 `OFFLINE` 실패는 환경이 online이면 다른 retryable - 실패처럼 backoff로 재시도한다. 서버만 내려가면 online event가 오지 않는다. + (`reconnect-coordinator.ts:556-568`). 이 대기는 환경 신호가 offline일 때만 + 한다. 서버만 내려가면 online event가 오지 않는다. 그래서 템플릿 transport는 + 서버에 닿지 않은 실패를 `PROVIDER_UNAVAILABLE`로 보고하고, coordinator는 이를 + backoff로 재시도한다(1103/04-04). 조합 코드가 만든 transport가 `OFFLINE`을 + 보고해도 환경이 online이면 같은 backoff로 재시도한다. - auth expiry는 session owner의 single-flight recovery를 한 번 요청한다. 실패하면 `AUTH_REQUIRED`로 멈춘다. - protocol/schema/forbidden/policy failure는 retry하지 않는다. @@ -1905,13 +1907,13 @@ credential을 보호할 수 있다고 주장하지 않는다. | --- | --- | --- | | `ABORTED` | lifecycle/user cancellation | retry 없음 | | `UNSUPPORTED` | browser capability 없음 | declared fallback | -| `OFFLINE` | network hint/attempt failure | online hint 뒤 bounded check | +| `OFFLINE` | 환경 신호(`navigator.onLine` 등 조합 코드가 넘긴 `online()`)가 offline이다. 템플릿 transport는 이 kind를 내지 않는다(1103/04-04) | timer 없이 online hint를 기다린 뒤 bounded check. poll lease는 끝나고 `retryable: true`다 | | `CONNECT_TIMEOUT` | open deadline 초과 | bounded reconnect | | `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`). 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()`가 성공한다 | +| `PROVIDER_UNAVAILABLE` | backend/push/hosting unavailable. 환경은 online인데 서버·프록시에 닿지 않은 것(SSE fetch·reader 거절, WebSocket `error`, poll `execute` 거절)도 세 transport 모두 이 kind다(1103/04-04, `retryable: true`). 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 | diff --git a/src/adapters/realtime/polling/bounded-poll-coordinator.ts b/src/adapters/realtime/polling/bounded-poll-coordinator.ts index 18804a90..c92908d3 100644 --- a/src/adapters/realtime/polling/bounded-poll-coordinator.ts +++ b/src/adapters/realtime/polling/bounded-poll-coordinator.ts @@ -320,8 +320,9 @@ export function createBoundedPollCoordinator( if (attemptOutcome.kind === "VALUE") { result = attemptOutcome.value; } else if (attemptOutcome.kind === "REJECTED") { + // 1103/04-04. No server answered; OFFLINE is the environment's. result = realtimeFailure( - controller.signal.aborted ? "ABORTED" : "OFFLINE", + controller.signal.aborted ? "ABORTED" : "PROVIDER_UNAVAILABLE", "POLL", !controller.signal.aborted, ); @@ -389,8 +390,8 @@ export function createBoundedPollCoordinator( !result.error.retryable || !isPollRetryableFailureKind(result.error.kind) ) { - // OFFLINE (a thrown executor included) ends this lease but stays - // retryable, like every other OFFLINE here. + // OFFLINE ends this lease but stays retryable, like every other + // OFFLINE here. return pollFailure( result.error.kind, result.error.kind === "OFFLINE" && result.error.retryable, diff --git a/src/adapters/realtime/sse/fetch-sse-connection.ts b/src/adapters/realtime/sse/fetch-sse-connection.ts index e7fcd788..bd920d5b 100644 --- a/src/adapters/realtime/sse/fetch-sse-connection.ts +++ b/src/adapters/realtime/sse/fetch-sse-connection.ts @@ -214,9 +214,11 @@ export function createFetchSseConnection( controller.abort(); return failed("CONNECT_TIMEOUT", "CONNECT", true); } + // 1103/04-04. A rejected fetch says no server answered, not that the + // device is offline: PROVIDER_UNAVAILABLE, as WebSocket reports it. if (responseResult.kind === "REJECTED") { return failed( - controller.signal.aborted ? "ABORTED" : "OFFLINE", + controller.signal.aborted ? "ABORTED" : "PROVIDER_UNAVAILABLE", "CONNECT", !controller.signal.aborted, ); @@ -399,7 +401,7 @@ export function createFetchSseConnection( } if (readResult.kind === "REJECTED") { return failed( - controller.signal.aborted ? "ABORTED" : "OFFLINE", + controller.signal.aborted ? "ABORTED" : "PROVIDER_UNAVAILABLE", "RECEIVE", !controller.signal.aborted, ); diff --git a/tests/unit/realtime/bounded-poll-coordinator.test.ts b/tests/unit/realtime/bounded-poll-coordinator.test.ts index b5412809..c2c9cfd3 100644 --- a/tests/unit/realtime/bounded-poll-coordinator.test.ts +++ b/tests/unit/realtime/bounded-poll-coordinator.test.ts @@ -10,6 +10,7 @@ import { createBoundedPollCoordinator, type BoundedPollAttemptResult, type BoundedPollEnvironment, + type BoundedPollObservation, } from "../../../src/adapters/realtime/polling/bounded-poll-coordinator.ts"; import { TEST_LIST_HTTP_CONTRACT } from "../../helpers/external-contract-fixture.ts"; @@ -902,22 +903,47 @@ describe("bounded poll coordinator", () => { }); }); - it("ends a run whose executor throws with a retryable OFFLINE", async () => { + // 1103/04-04. A rejected executor means the request did not reach a server + // that answered. It is PROVIDER_UNAVAILABLE, retried within the lease like + // one the executor reports; OFFLINE comes only from the environment. + it("retries a throwing executor as PROVIDER_UNAVAILABLE within the lease", async () => { const clock = new ManualClock(); + const observations: BoundedPollObservation[] = []; + const execute = vi.fn(async (): Promise> => { + throw new TypeError("Failed to fetch"); + }); const coordinator = createBoundedPollCoordinator({ policy, operation, environment: new MutableEnvironment(), clock, - execute: async () => { - throw new TypeError("Failed to fetch"); - }, + random: () => 0.5, + execute, + observe: (observation) => observations.push(observation), }); - const running = coordinator.run(); - clock.advance(5_000); - await expect(running).resolves.toEqual({ + + let result: unknown = null; + void coordinator.run().then((value) => { + result = value; + }); + for (let turn = 0; turn < 120 && result === null; turn += 1) { + clock.advance(1_000); + await flush(); + } + + expect(execute).toHaveBeenCalledTimes(policy.maxAttempts); + expect( + observations + .filter((observation) => observation.kind === "ATTEMPT_FINISHED") + .map((observation) => observation.outcome), + ).toEqual([ + "PROVIDER_UNAVAILABLE", + "PROVIDER_UNAVAILABLE", + "PROVIDER_UNAVAILABLE", + ]); + expect(result).toMatchObject({ ok: false, - error: { kind: "OFFLINE", operation: "POLL", retryable: true }, + error: { kind: "POLL_BUDGET_EXHAUSTED", operation: "POLL" }, }); }); diff --git a/tests/unit/realtime/realtime-reconnect-coordinator.test.ts b/tests/unit/realtime/realtime-reconnect-coordinator.test.ts index 7a7b1b63..abf6b80e 100644 --- a/tests/unit/realtime/realtime-reconnect-coordinator.test.ts +++ b/tests/unit/realtime/realtime-reconnect-coordinator.test.ts @@ -2088,9 +2088,10 @@ describe("transport failures through the reconnect coordinator", () => { }, ); - // The SSE adapter reports a rejected fetch or read as OFFLINE, but // navigator.onLine stays true when only the server is down, so no online - // event ever arrives (0929/04-01). + // event ever arrives (0929/04-01). The SSE adapter reports a rejected fetch + // or read as PROVIDER_UNAVAILABLE, as WebSocket does; OFFLINE comes only + // from the environment signal (1103/04-04). it("retries an SSE fetch rejection with backoff while the browser stays online", async () => { const clock = new ManualClock(); const fetcher = vi @@ -2120,15 +2121,19 @@ describe("transport failures through the reconnect coordinator", () => { ]); expect(result).toEqual({ ok: false, - error: { kind: "OFFLINE", operation: "CONNECT", retryable: true }, + error: { + kind: "PROVIDER_UNAVAILABLE", + operation: "CONNECT", + retryable: true, + }, }); expect(observed).toEqual([ "ATTEMPT_STARTED", - "RETRY_SCHEDULED:OFFLINE", + "RETRY_SCHEDULED:PROVIDER_UNAVAILABLE", "ATTEMPT_STARTED", - "RETRY_SCHEDULED:OFFLINE", + "RETRY_SCHEDULED:PROVIDER_UNAVAILABLE", "ATTEMPT_STARTED", - "RUN_ENDED:OFFLINE:EXHAUSTED", + "RUN_ENDED:PROVIDER_UNAVAILABLE:EXHAUSTED", ]); }); @@ -2175,17 +2180,21 @@ describe("transport failures through the reconnect coordinator", () => { expect(fetcher).toHaveBeenCalledTimes(3); expect(result).toEqual({ ok: false, - error: { kind: "OFFLINE", operation: "CONNECT", retryable: true }, + error: { + kind: "PROVIDER_UNAVAILABLE", + operation: "CONNECT", + retryable: true, + }, }); expect(observed).toEqual([ "ATTEMPT_STARTED", "SESSION_OPENED", "SESSION_CLOSED", - "RETRY_SCHEDULED:OFFLINE", + "RETRY_SCHEDULED:PROVIDER_UNAVAILABLE", "ATTEMPT_STARTED", - "RETRY_SCHEDULED:OFFLINE", + "RETRY_SCHEDULED:PROVIDER_UNAVAILABLE", "ATTEMPT_STARTED", - "RUN_ENDED:OFFLINE:EXHAUSTED", + "RUN_ENDED:PROVIDER_UNAVAILABLE:EXHAUSTED", ]); });