From 05880d12faa726fdab5e582961d9acb4dffbc319 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 22:06:38 +0900 Subject: [PATCH] =?UTF-8?q?docs(realtime):=20VD-28=EA=B3=BC=20=EC=84=A4?= =?UTF-8?q?=EA=B3=84=203=EC=A0=88=EC=9D=98=20poll=20=EA=B7=9C=EC=B9=99?= =?UTF-8?q?=EC=9D=84=20V3=20descriptor=EB=A1=9C=20=EA=B3=A0=EC=B9=9C?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: VD-28은 poll 규칙을 지운 V2 실행 예산으로 적는다. "operation은 registered terminal·replay-safe REST `QUERY`", "Poll-bound VD-23 budget은 `maxAttempts=1`, `authRecoveryCount=0`, `maxCumulativeSleepMs=0`"이다. 설계 3절도 "REST `QUERY` operation"과 "REST operation registry"라고 적는다. V2 실행 경로는 2026-11-03에 지웠고(VD-23 상태 줄), 지금 규칙은 V3 descriptor의 `frontend.retryBudget: 0`이다(설계 9.2, 1103/04-01). a65df74가 9.2만 고쳤다. 고른 방법: VD-28 1절 끝 문장과 11절 목록, 설계 3절 두 항목을 지금 규칙으로 바꾼다. GET·HEAD, SAFE·IDEMPOTENT인 V3 descriptor, `retryBudget` 0이 아니면 생성 때 거절, 실행기가 그 칸에서 재시도 상한을 읽어 한 attempt가 요청 하나라는 것이다. 상세는 9.2를 가리킨다. 설계 3절의 "REST operation registry의 credential, conditional request, ... 재사용"은 주어를 V3 실행기로 바꾸면서 conditional request를 뺐다. V3 실행기에는 ETag 처리가 없고(`http-execution-v3.ts`에 If-None-Match 없음), VD-23 상태 줄이 conditional execution을 `DESIGNED_NOT_IMPLEMENTED`로 적는다. 위험·한계: 문서만 바꿨다. VD-28 11절의 "ETag/`If-None-Match` 또는 server cursor 사용" 목표 줄은 결정 내용이라 그대로 두었다. 검증: 문서 전용이라 RED 없음. desktop batch에서 확인. - pnpm verify:documentation - `git grep -n "authRecoveryCount\|maxCumulativeSleepMs" -- docs/architecture/decisions/VD-28*` 0건(로컬 확인) Refs: 1105/04-03 --- ...altime-events-web-push-and-bounded-polling.md | 16 +++++++++------- ...altime-events-web-push-and-bounded-polling.md | 14 ++++++++------ 2 files changed, 17 insertions(+), 13 deletions(-) diff --git a/docs/architecture/decisions/VD-28-realtime-events-web-push-and-bounded-polling.md b/docs/architecture/decisions/VD-28-realtime-events-web-push-and-bounded-polling.md index 402365a4..45414d1b 100644 --- a/docs/architecture/decisions/VD-28-realtime-events-web-push-and-bounded-polling.md +++ b/docs/architecture/decisions/VD-28-realtime-events-web-push-and-bounded-polling.md @@ -114,9 +114,10 @@ protocol-specific terminal proof와 protobuf decode/schema/mapper를 끝낸 runtime-wide notification branch에서만 공통 scope/gap/resync coordinator를 재사용한다. frame/media/trailer, reconnect와 operation deadline owner를 SSE/WebSocket adapter로 합치거나 protobuf message를 -`REALTIME_EVENT_V1` JSON으로 다시 감싸지 않는다. Polling의 개별 attempt는 VD-23의 -terminal·replay-safe REST `QUERY` execution contract를 재사용하되 transport/Query -retry는 끄고, 이 결정은 attempt 사이 bounded lease만 소유한다. +`REALTIME_EVENT_V1` JSON으로 다시 감싸지 않는다. Polling의 개별 attempt는 V3 +contract executor가 실행하는 V3 REST descriptor 하나다(GET·HEAD, SAFE·IDEMPOTENT, +`frontend.retryBudget: 0`, 상세 설계 9.2). transport/Query retry는 끄고, 이 결정은 +attempt 사이 bounded lease만 소유한다. ### 2. source of truth는 서버다 @@ -438,10 +439,11 @@ Service Worker를 선택해도 offline fetch, PWA shell cache나 background sync 각 lease는 operation owner, minimum/success/max interval, max attempts, max elapsed, response byte cap, visible-only policy와 terminal states를 가진다. -- operation은 registered terminal·replay-safe REST `QUERY`여야 함 -- Poll `maxAttempts`는 physical request 하나인 logical completion을 셈 -- Poll-bound VD-23 budget은 `maxAttempts=1`, `authRecoveryCount=0`, - `maxCumulativeSleepMs=0`; TanStack Query retry도 끔 +- operation은 설치된 V3 REST descriptor(`InstalledHttpContract`)로, method가 + GET·HEAD이고 `retrySemantics`가 SAFE·IDEMPOTENT여야 함 +- descriptor의 `frontend.retryBudget`은 0이어야 함. 아니면 poll coordinator 생성이 + 거절한다(상세 설계 9.2, 1103/04-01). V3 실행기는 재시도 상한을 이 칸에서 읽으므로 + Poll `maxAttempts`의 한 attempt가 physical request 하나다. TanStack Query retry도 끔 - completion-chained timeout으로 single-flight - hidden/offline/pagehide/unmount/scope change/user cancel에서 stop - ETag/`If-None-Match` 또는 server cursor 사용 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 c2dd5e3f..dd8d6398 100644 --- a/docs/architecture/realtime-events-web-push-and-bounded-polling.md +++ b/docs/architecture/realtime-events-web-push-and-bounded-polling.md @@ -362,12 +362,14 @@ Connect/gRPC-Web server stream과 향후 GraphQL subscription은 이 문서의 S VD-29/VD-27 규칙을 우선한다. - API operation registry의 현재 `SERVER_STREAM`은 `CONNECT_HTTP | GRPC_WEB + rpcKind=SERVER_STREAM`만 허용한다. SSE, WebSocket과 Web Push는 - realtime registry가 소유하고, bounded polling은 terminal·replay-safe REST - `QUERY` operation에 적용하는 scheduling policy다. -- bounded polling의 한 logical attempt는 REST operation registry의 credential, - conditional request, schema/mapper와 deadline을 재사용한다. Poll 전용 - operation은 transport retry를 끄며 이 문서는 완료된 attempt 사이 cadence와 - failure backoff만 소유한다. + realtime registry가 소유하고, bounded polling은 V3 REST descriptor 중 + GET·HEAD이고 SAFE·IDEMPOTENT인 읽기 operation에 적용하는 scheduling policy다. +- bounded polling의 한 logical attempt는 V3 contract executor가 실행하고, 그 + 실행기의 credential, schema/mapper와 deadline을 재사용한다. conditional + request(ETag)는 V3 실행기에 아직 없다(VD-23 conditional execution + `DESIGNED_NOT_IMPLEMENTED`). Poll 전용 + operation은 `frontend.retryBudget: 0`으로 transport retry를 끈다(9.2). 이 문서는 + 완료된 attempt 사이 cadence와 failure backoff만 소유한다. 같은 stream을 Connect/gRPC-Web과 SSE로 자동 failover하지 않는다. wire와 resume 의미가 같다는 backend contract와 별도 rollout evidence가 있을 때만 명시된 fallback으로