From 5b3f5b0eb3f8e4d986e0c0ca0ca803653d2d3290 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 1 Nov 2026 22:06:59 +0900 Subject: [PATCH] =?UTF-8?q?docs(realtime):=2013.1=EC=97=90=20=EB=82=B4?= =?UTF-8?q?=EB=B6=80=20task=20=EB=A7=88=EA=B0=90=EC=9D=98=20IDLE=5FTIMEOUT?= =?UTF-8?q?=20=EB=9C=BB=EC=9D=84=20=EC=A0=81=EB=8A=94=EB=8B=A4=20(04-02)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 설계 13.1은 IDLE_TIMEOUT을 "heartbeat/byte deadline 초과 -> close + bounded reconnect" 한 뜻으로만 적는다. 코드는 같은 kind를 내부 task 마감에도 쓴다. stream coordinator는 effect·recovery·close drain 마감을 IDLE_TIMEOUT/APPLY·RECOVER·CLOSE(retryable false)로, handoff coordinator는 quiescence·checkpoint·close 마감을 IDLE_TIMEOUT/RECOVER·CLOSE(기본값 retryable)로 보고한다. 13.1만 보고 조합 코드를 쓰면 내부 마감도 재연결 대상으로 읽는다. RED(문서-코드 대조): 13.1 행은 transport 뜻 하나. 코드에서 IDLE_TIMEOUT을 만드는 곳은 transport 3곳(SSE RECEIVE, WS RECEIVE· SUBSCRIBE)과 내부 task 7곳(stream-coordinator.ts 3곳, live-poll-handoff-coordinator.ts 4곳). stream coordinator close() 주석은 "IDLE_TIMEOUT이면 아직 DRAINING"을 공개 계약으로 적는다. 고른 방법: 리뷰의 (b). 13.1 IDLE_TIMEOUT 행을 코드에 맞춰 두 뜻, operation으로 구분하는 법, 각 경우의 recovery, 관측에서 구분되지 않는다는 한계를 적는다. 코드는 바꾸지 않는다. 버린 대안: (a) stream coordinator의 마감을 APPLY_FAILED· PROVIDER_UNAVAILABLE로 바꾸기. 리뷰는 코드 3곳으로 봤지만 같은 관례가 handoff coordinator 4곳에도 있고, stream coordinator close()의 IDLE_TIMEOUT은 주석에 적힌 공개 계약이다. 바꾸려면 두 coordinator의 마감 어휘를 함께 정해야 하므로 별도 결정으로 남긴다. 위험·한계: - 리뷰 완료 기준 중 "effect 마감과 전송 idle을 관측에서 구분"은 충족하지 못했다. reconnect 관측(RUN_ENDED)에 operation이 없다. (a) 또는 관측에 operation 추가가 필요하다. - handoff 마감 결과가 retryable true(kind 기본값)이고 stream coordinator는 false인 차이는 문서에 적기만 했다. 검증: - `node scripts/verify-documentation-readiness.ts` -> PASS_SCOPED. - 코드 변경 없음. 테스트 미실행(해당 없음). Refs: docs/reviews/2026-11-01-maturity-review/04-adapters-realtime.md 04-02, 6.3절 --- .../realtime-events-web-push-and-bounded-polling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/architecture/realtime-events-web-push-and-bounded-polling.md b/docs/architecture/realtime-events-web-push-and-bounded-polling.md index b679641f..3038cacb 100644 --- a/docs/architecture/realtime-events-web-push-and-bounded-polling.md +++ b/docs/architecture/realtime-events-web-push-and-bounded-polling.md @@ -1890,7 +1890,7 @@ credential을 보호할 수 있다고 주장하지 않는다. | `UNSUPPORTED` | browser capability 없음 | declared fallback | | `OFFLINE` | network hint/attempt failure | online hint 뒤 bounded check | | `CONNECT_TIMEOUT` | open deadline 초과 | bounded reconnect | -| `IDLE_TIMEOUT` | heartbeat/byte deadline 초과 | close + bounded reconnect | +| `IDLE_TIMEOUT` | transport: heartbeat/byte/unsubscribe deadline 초과(operation `RECEIVE`·`SUBSCRIBE`). 내부 task: stream·handoff coordinator의 effect·recovery·quiescence·close deadline 초과(operation `APPLY`·`RECOVER`·`CLOSE`) | transport: close + bounded reconnect. 내부 task는 재연결로 풀리지 않는다: stream coordinator는 `retryable: false`로 보고하고 task가 settle할 때까지 `DRAINING`을 유지하며, handoff는 그 전환을 fail-close한다(결과는 kind 기본값대로 retryable). 두 뜻은 kind가 아니라 `operation`으로 구분한다. reconnect 관측(`RUN_ENDED failureKind`)에는 `operation`이 없어 구분되지 않는다 | | `AUTH_REQUIRED` | session expired/recovery 실패 | sign-in UX | | `FORBIDDEN` | stream/resource 거절 | retry 없음 | | `RATE_LIMITED` | connection/request/provider limit | bounded server hint |