fix(realtime)!: 서버에 닿지 않은 SSE·poll 실패를 PROVIDER_UNAVAILABLE로 낸다

문제
브라우저는 online인데 서버·프록시만 닿지 않을 때 실패 이름이
transport마다 다르다. SSE는 fetch·reader 거절을 OFFLINE, poll은
execute 거절을 OFFLINE, WebSocket은 error를 PROVIDER_UNAVAILABLE로
낸다. reconnect coordinator는 transport OFFLINE을 backoff로 재시도하고
예산을 다 쓰면 online인데도 OFFLINE으로 끝낸다. 설계 13.1의 OFFLINE
행은 "online hint 뒤 bounded check"라 5.3과 다른 말을 한다. kind로
화면 문구나 조합 판단을 고르면 같은 서버 장애가 SSE에서는 "오프라인",
WS에서는 "서비스 이용 불가"가 되고, "OFFLINE이면 online 이벤트를
기다린다"는 조합 코드는 다시 멈춘다(0929/04-01의 모양).

고른 방법
- 리뷰 5.3절 판단대로 어휘를 맞춘다. SSE fetch 거절(CONNECT)과 reader
  거절(RECEIVE), poll execute 거절을 PROVIDER_UNAVAILABLE(retryable)로
  바꾼다. 이제 OFFLINE은 환경 신호에서만 나온다.
- poll은 PROVIDER_UNAVAILABLE을 lease 안에서 재시도하므로, 던지는
  execute는 바로 끝나지 않고 backoff로 maxAttempts까지 다시 시도한다.
  executor가 PROVIDER_UNAVAILABLE을 돌려준 경우와 같은 처리다.
- 설계 13.1의 OFFLINE·PROVIDER_UNAVAILABLE 행과 5.3 문단을 고친다.
- 버린 대안: 13.1에 OFFLINE의 두 뜻을 적기만 하기. 비용은 1행이지만
  조합자가 navigator.onLine을 따로 봐야 원인을 안다. 운영 중인 제품이
  없는 지금 어휘를 바꾸는 비용이 가장 작다(리뷰 5.3).

위험·한계
- 배럴로 공개된 SSE 연결·poll coordinator의 결과 kind가 바뀐다. repo
  안 소비자는 테스트뿐이다.
- 던지는 execute(조합 코드의 버그 포함)는 이제 lease 예산만큼 다시
  불린다. 상한은 maxAttempts·maxElapsed 그대로다.
- 환경 신호가 늦게 offline이 되는 경우 첫 실패는 PROVIDER_UNAVAILABLE로
  보인다. offline 대기는 kind가 아니라 환경 신호로 걸리므로 멈춤은 없다
  (before/after 테스트 그대로 통과).

검증
- 바꾼 기대값 3건을 옛 코드에 돌림: 3건 실패(RED). 새 코드: realtime
  단위 241건 통과.
- check:types 통과, 바꾼 파일 eslint 통과.

BREAKING CHANGE: SSE 연결의 fetch·reader 거절과 bounded poll의 execute
거절이 OFFLINE 대신 PROVIDER_UNAVAILABLE(retryable)로 끝난다. poll은
던지는 execute를 lease 안에서 재시도한다. OFFLINE을 서버 장애로 읽던
조합 코드는 PROVIDER_UNAVAILABLE을 함께 본다.

Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-04
This commit is contained in:
DongHyeonka
2026-11-04 20:23:21 +09:00
parent a65df74046
commit af000673ef
5 changed files with 68 additions and 28 deletions
@@ -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 |
@@ -320,8 +320,9 @@ export function createBoundedPollCoordinator<Value>(
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<Value>(
!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,
@@ -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,
);
@@ -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<BoundedPollAttemptResult<string>> => {
throw new TypeError("Failed to fetch");
});
const coordinator = createBoundedPollCoordinator<string>({
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" },
});
});
@@ -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",
]);
});