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:
@@ -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",
|
||||
]);
|
||||
});
|
||||
|
||||
|
||||
Reference in New Issue
Block a user