fix(realtime): 던지는 reconnect attempt·waitClosed의 규칙을 적는다
문제: reconnect coordinator는 `attempt`·`waitClosed`가 던지면
PROVIDER_UNAVAILABLE(CONNECT·RECEIVE, retryable)로 보고 backoff로 다시
시도한다. 05330e3 뒤 poll은 같은 던짐을 PROTOCOL_MISMATCH로 끝낸다. 이
차이는 그 커밋 본문에만 있고 타입 주석과 설계 13.1에는 없다. repo의 SSE
bridge 예(`sseAttempt`)는 `attempt` 안에서 연결을 만든다. 그래서
endpoint 설정 오류가 요청 0번, attempt 3번, PROVIDER_UNAVAILABLE
(EXHAUSTED)로 끝나 서버 장애로 보인다(리뷰 실험 04-R2).
고른 방법: 리뷰 선택지 (c). 동작은 그대로 두고 규칙을 적는다.
- `attempt` 주석: 던짐은 transport 실패로 재시도된다. 설정 검사는
`attempt` 밖, 조합 코드가 transport를 만들 때 한다. poll과 다른 이유도
적었다. `waitClosed` 주석: RECEIVE로 같은 규칙.
`classifyClosed`·`confirmTransportBarrier` 주석: 던짐은
PROTOCOL_MISMATCH로 끝나고 재시도하지 않는다.
- 설계 13.1 PROVIDER_UNAVAILABLE·PROTOCOL_MISMATCH 행에 같은 규칙을 적었다.
- 테스트 bridge `sseAttempt`는 만들어질 때 연결 설정을 한 번 검사한다.
연결은 attempt마다 새로 만든다. session `close`가 연결을 끝내므로 한
연결을 여러 attempt에 쓸 수 없다.
- 규칙을 고정하는 테스트를 더했다. attempt·waitClosed 던짐은 3회 재시도 뒤
PROVIDER_UNAVAILABLE(EXHAUSTED), classifyClosed 던짐은 1회로
PROTOCOL_MISMATCH, bridge의 http endpoint는 만들 때 TypeError(fetch 0).
버린 대안:
- (b) reconnect도 던짐을 PROTOCOL_MISMATCH로 끝내기. 연결 실패를 던지는
라이브러리를 감싼 transport가 첫 실패에서 run을 끝내게 되는 공개 동작
변경(BREAKING)이다. 리뷰도 지금 동작이 회복에 유리하다고 봤다.
05330e3이 poll에서 (c)를 버린 이유("결과로 구분한다")는 이번 완료
기준에 없다.
- 연결 하나를 bridge에서 만들고 attempt마다 read만 하기. 위와 같이
session `close`가 연결을 닫아 다음 read가 CLOSED가 된다.
위험·한계:
- 동작이 같으므로 조합 코드가 `attempt` 안에서 연결을 만들면 설정 오류는
여전히 서버 장애로 보인다. 주석과 13.1은 모르고 쓰는 경우만 줄인다.
- 매핑 오류 같은 나머지 던짐도 그대로 재시도되고 원인 예외는 남지 않는다
(닫힌 관측 어휘).
- CHANGELOG 행은 이 커밋에 없다. CHANGELOG 담당이 더한다.
검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/unit/realtime/realtime-reconnect-coordinator.test.ts
- RED 없음. 동작을 바꾸지 않는 커밋이라 새 테스트는 부모 커밋에서도
통과한다. 규칙을 고정하는 테스트다.
- check:types, lint, verify:documentation
Refs: 1106/04-01
This commit is contained in:
@@ -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 |
|
||||
|
||||
@@ -99,9 +99,14 @@ export type RealtimeReconnectCloseClassification =
|
||||
export type RealtimeReconnectSession<
|
||||
ClosedReceipt = RealtimeReconnectOutcome<void>,
|
||||
> = 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<ClosedReceipt>;
|
||||
/** 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<ClosedReceipt>
|
||||
>
|
||||
>;
|
||||
/** 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<void>;
|
||||
|
||||
@@ -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<RealtimeReconnectOutcome<void>>(
|
||||
Object.freeze({
|
||||
classifyClosed: (
|
||||
receipt: RealtimeReconnectOutcome<void>,
|
||||
) => receipt,
|
||||
close: vi.fn(),
|
||||
waitClosed: () => {
|
||||
throw new TypeError("composer defect");
|
||||
},
|
||||
}),
|
||||
);
|
||||
},
|
||||
observe: (observation) => observed.push(observationLabel(observation)),
|
||||
});
|
||||
|
||||
let result: RealtimeResult<void> | 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<RealtimeReconnectOutcome<void>>(
|
||||
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<typeof fetch>();
|
||||
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();
|
||||
});
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user