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
@@ -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,
);