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가 아니다.
|
`navigator.onLine`은 실제 backend reachability authority가 아니다.
|
||||||
offline 대기 시간은 elapsed budget에 넣지 않는다. online으로 돌아오면
|
offline 대기 시간은 elapsed budget에 넣지 않는다. online으로 돌아오면
|
||||||
elapsed budget을 다시 시작하고 attempt 상한은 유지한다
|
elapsed budget을 다시 시작하고 attempt 상한은 유지한다
|
||||||
(`reconnect-coordinator.ts:553-562`). 이 대기는 환경 신호가 offline일 때만
|
(`reconnect-coordinator.ts:556-568`). 이 대기는 환경 신호가 offline일 때만
|
||||||
한다. transport가 보고한 `OFFLINE` 실패는 환경이 online이면 다른 retryable
|
한다. 서버만 내려가면 online event가 오지 않는다. 그래서 템플릿 transport는
|
||||||
실패처럼 backoff로 재시도한다. 서버만 내려가면 online event가 오지 않는다.
|
서버에 닿지 않은 실패를 `PROVIDER_UNAVAILABLE`로 보고하고, coordinator는 이를
|
||||||
|
backoff로 재시도한다(1103/04-04). 조합 코드가 만든 transport가 `OFFLINE`을
|
||||||
|
보고해도 환경이 online이면 같은 backoff로 재시도한다.
|
||||||
- auth expiry는 session owner의 single-flight recovery를 한 번 요청한다.
|
- auth expiry는 session owner의 single-flight recovery를 한 번 요청한다.
|
||||||
실패하면 `AUTH_REQUIRED`로 멈춘다.
|
실패하면 `AUTH_REQUIRED`로 멈춘다.
|
||||||
- protocol/schema/forbidden/policy failure는 retry하지 않는다.
|
- protocol/schema/forbidden/policy failure는 retry하지 않는다.
|
||||||
@@ -1905,13 +1907,13 @@ credential을 보호할 수 있다고 주장하지 않는다.
|
|||||||
| --- | --- | --- |
|
| --- | --- | --- |
|
||||||
| `ABORTED` | lifecycle/user cancellation | retry 없음 |
|
| `ABORTED` | lifecycle/user cancellation | retry 없음 |
|
||||||
| `UNSUPPORTED` | browser capability 없음 | declared fallback |
|
| `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 |
|
| `CONNECT_TIMEOUT` | open deadline 초과 | bounded reconnect |
|
||||||
| `IDLE_TIMEOUT` | transport: heartbeat/byte/unsubscribe deadline 초과(operation `RECEIVE`·`SUBSCRIBE`). 내부 task 마감에는 쓰지 않는다 | close + bounded reconnect |
|
| `IDLE_TIMEOUT` | transport: heartbeat/byte/unsubscribe deadline 초과(operation `RECEIVE`·`SUBSCRIBE`). 내부 task 마감에는 쓰지 않는다 | close + bounded reconnect |
|
||||||
| `AUTH_REQUIRED` | session expired/recovery 실패 | sign-in UX |
|
| `AUTH_REQUIRED` | session expired/recovery 실패 | sign-in UX |
|
||||||
| `FORBIDDEN` | stream/resource 거절 | retry 없음 |
|
| `FORBIDDEN` | stream/resource 거절 | retry 없음 |
|
||||||
| `RATE_LIMITED` | connection/request/provider limit | bounded server hint |
|
| `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 |
|
| `PROTOCOL_MISMATCH` | version/subprotocol/content type | terminal/rollout rollback |
|
||||||
| `MALFORMED_EVENT` | state-bearing syntax/schema/exact-key 실패 | cursor 미진행, freshness `UNKNOWN`, close + registered recovery |
|
| `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 |
|
| `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") {
|
if (attemptOutcome.kind === "VALUE") {
|
||||||
result = attemptOutcome.value;
|
result = attemptOutcome.value;
|
||||||
} else if (attemptOutcome.kind === "REJECTED") {
|
} else if (attemptOutcome.kind === "REJECTED") {
|
||||||
|
// 1103/04-04. No server answered; OFFLINE is the environment's.
|
||||||
result = realtimeFailure(
|
result = realtimeFailure(
|
||||||
controller.signal.aborted ? "ABORTED" : "OFFLINE",
|
controller.signal.aborted ? "ABORTED" : "PROVIDER_UNAVAILABLE",
|
||||||
"POLL",
|
"POLL",
|
||||||
!controller.signal.aborted,
|
!controller.signal.aborted,
|
||||||
);
|
);
|
||||||
@@ -389,8 +390,8 @@ export function createBoundedPollCoordinator<Value>(
|
|||||||
!result.error.retryable ||
|
!result.error.retryable ||
|
||||||
!isPollRetryableFailureKind(result.error.kind)
|
!isPollRetryableFailureKind(result.error.kind)
|
||||||
) {
|
) {
|
||||||
// OFFLINE (a thrown executor included) ends this lease but stays
|
// OFFLINE ends this lease but stays retryable, like every other
|
||||||
// retryable, like every other OFFLINE here.
|
// OFFLINE here.
|
||||||
return pollFailure(
|
return pollFailure(
|
||||||
result.error.kind,
|
result.error.kind,
|
||||||
result.error.kind === "OFFLINE" && result.error.retryable,
|
result.error.kind === "OFFLINE" && result.error.retryable,
|
||||||
|
|||||||
@@ -214,9 +214,11 @@ export function createFetchSseConnection(
|
|||||||
controller.abort();
|
controller.abort();
|
||||||
return failed("CONNECT_TIMEOUT", "CONNECT", true);
|
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") {
|
if (responseResult.kind === "REJECTED") {
|
||||||
return failed(
|
return failed(
|
||||||
controller.signal.aborted ? "ABORTED" : "OFFLINE",
|
controller.signal.aborted ? "ABORTED" : "PROVIDER_UNAVAILABLE",
|
||||||
"CONNECT",
|
"CONNECT",
|
||||||
!controller.signal.aborted,
|
!controller.signal.aborted,
|
||||||
);
|
);
|
||||||
@@ -399,7 +401,7 @@ export function createFetchSseConnection(
|
|||||||
}
|
}
|
||||||
if (readResult.kind === "REJECTED") {
|
if (readResult.kind === "REJECTED") {
|
||||||
return failed(
|
return failed(
|
||||||
controller.signal.aborted ? "ABORTED" : "OFFLINE",
|
controller.signal.aborted ? "ABORTED" : "PROVIDER_UNAVAILABLE",
|
||||||
"RECEIVE",
|
"RECEIVE",
|
||||||
!controller.signal.aborted,
|
!controller.signal.aborted,
|
||||||
);
|
);
|
||||||
|
|||||||
@@ -10,6 +10,7 @@ import {
|
|||||||
createBoundedPollCoordinator,
|
createBoundedPollCoordinator,
|
||||||
type BoundedPollAttemptResult,
|
type BoundedPollAttemptResult,
|
||||||
type BoundedPollEnvironment,
|
type BoundedPollEnvironment,
|
||||||
|
type BoundedPollObservation,
|
||||||
} from "../../../src/adapters/realtime/polling/bounded-poll-coordinator.ts";
|
} from "../../../src/adapters/realtime/polling/bounded-poll-coordinator.ts";
|
||||||
import { TEST_LIST_HTTP_CONTRACT } from "../../helpers/external-contract-fixture.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 clock = new ManualClock();
|
||||||
|
const observations: BoundedPollObservation[] = [];
|
||||||
|
const execute = vi.fn(async (): Promise<BoundedPollAttemptResult<string>> => {
|
||||||
|
throw new TypeError("Failed to fetch");
|
||||||
|
});
|
||||||
const coordinator = createBoundedPollCoordinator<string>({
|
const coordinator = createBoundedPollCoordinator<string>({
|
||||||
policy,
|
policy,
|
||||||
operation,
|
operation,
|
||||||
environment: new MutableEnvironment(),
|
environment: new MutableEnvironment(),
|
||||||
clock,
|
clock,
|
||||||
execute: async () => {
|
random: () => 0.5,
|
||||||
throw new TypeError("Failed to fetch");
|
execute,
|
||||||
},
|
observe: (observation) => observations.push(observation),
|
||||||
});
|
});
|
||||||
const running = coordinator.run();
|
|
||||||
clock.advance(5_000);
|
let result: unknown = null;
|
||||||
await expect(running).resolves.toEqual({
|
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,
|
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
|
// 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 () => {
|
it("retries an SSE fetch rejection with backoff while the browser stays online", async () => {
|
||||||
const clock = new ManualClock();
|
const clock = new ManualClock();
|
||||||
const fetcher = vi
|
const fetcher = vi
|
||||||
@@ -2120,15 +2121,19 @@ describe("transport failures through the reconnect coordinator", () => {
|
|||||||
]);
|
]);
|
||||||
expect(result).toEqual({
|
expect(result).toEqual({
|
||||||
ok: false,
|
ok: false,
|
||||||
error: { kind: "OFFLINE", operation: "CONNECT", retryable: true },
|
error: {
|
||||||
|
kind: "PROVIDER_UNAVAILABLE",
|
||||||
|
operation: "CONNECT",
|
||||||
|
retryable: true,
|
||||||
|
},
|
||||||
});
|
});
|
||||||
expect(observed).toEqual([
|
expect(observed).toEqual([
|
||||||
"ATTEMPT_STARTED",
|
"ATTEMPT_STARTED",
|
||||||
"RETRY_SCHEDULED:OFFLINE",
|
"RETRY_SCHEDULED:PROVIDER_UNAVAILABLE",
|
||||||
"ATTEMPT_STARTED",
|
"ATTEMPT_STARTED",
|
||||||
"RETRY_SCHEDULED:OFFLINE",
|
"RETRY_SCHEDULED:PROVIDER_UNAVAILABLE",
|
||||||
"ATTEMPT_STARTED",
|
"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(fetcher).toHaveBeenCalledTimes(3);
|
||||||
expect(result).toEqual({
|
expect(result).toEqual({
|
||||||
ok: false,
|
ok: false,
|
||||||
error: { kind: "OFFLINE", operation: "CONNECT", retryable: true },
|
error: {
|
||||||
|
kind: "PROVIDER_UNAVAILABLE",
|
||||||
|
operation: "CONNECT",
|
||||||
|
retryable: true,
|
||||||
|
},
|
||||||
});
|
});
|
||||||
expect(observed).toEqual([
|
expect(observed).toEqual([
|
||||||
"ATTEMPT_STARTED",
|
"ATTEMPT_STARTED",
|
||||||
"SESSION_OPENED",
|
"SESSION_OPENED",
|
||||||
"SESSION_CLOSED",
|
"SESSION_CLOSED",
|
||||||
"RETRY_SCHEDULED:OFFLINE",
|
"RETRY_SCHEDULED:PROVIDER_UNAVAILABLE",
|
||||||
"ATTEMPT_STARTED",
|
"ATTEMPT_STARTED",
|
||||||
"RETRY_SCHEDULED:OFFLINE",
|
"RETRY_SCHEDULED:PROVIDER_UNAVAILABLE",
|
||||||
"ATTEMPT_STARTED",
|
"ATTEMPT_STARTED",
|
||||||
"RUN_ENDED:OFFLINE:EXHAUSTED",
|
"RUN_ENDED:PROVIDER_UNAVAILABLE:EXHAUSTED",
|
||||||
]);
|
]);
|
||||||
});
|
});
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user