From 0e54e838c652dd54e6c8d8b04e6d13ab63186442 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 22:54:36 +0900 Subject: [PATCH] docs(runbook): bring the HTTP recovery runbook to the V3 code (03-08) The runbook still listed the auth fail-close, total deadline and bounded decoder as not implemented and said an unauthenticated request could be sent. Section 1 is now a status table with code locations, 5.1 and 6.0 describe V3, and 6.3 points at the same-key resend and its limits. Co-Authored-By: Claude Opus 5.5 --- .../api-contract-and-server-state-recovery.md | 93 ++++++++++++------- 1 file changed, 59 insertions(+), 34 deletions(-) diff --git a/docs/operations/api-contract-and-server-state-recovery.md b/docs/operations/api-contract-and-server-state-recovery.md index 55829a0c..dfc7fba4 100644 --- a/docs/operations/api-contract-and-server-state-recovery.md +++ b/docs/operations/api-contract-and-server-state-recovery.md @@ -4,7 +4,7 @@ schema/cache 절차 분리 - backend 구조와 handoff: [Backend API와 Server State contract](../architecture/backend-api-and-server-state-contract.md) -- 기준일: 2026-07-28 +- 기준일: 2026-07-28, 1절·5.1·6.0·6.3은 2026-09-25 V3 코드 기준으로 갱신 - 설계: [API contract, Schema, Mapper와 Server State](../architecture/api-contract-schema-mapper-and-server-state.md) - browser Protobuf/gateway 설계: @@ -12,18 +12,28 @@ ## 1. 적용 범위 -현재 reference REST → Schema → Mapper → TanStack Query vertical은 `COMPOSED`다. -하지만 다음 target delta는 아직 `DESIGNED_NOT_IMPLEMENTED`다. +현재 reference REST → Schema → Mapper → TanStack Query vertical은 V3 contract +executor(`src/adapters/http/http-execution-v3.ts`)로 `COMPOSED`다. 조합 위치는 +`src/bootstrap/runtime-adapters.ts`의 `createContractHttpExecutor`다. 이 문서의 +"current v1"은 V2 client(`src/adapters/http/client.ts`) 시절에 쓴 말이다. V2는 +기본 조합에 없다(`createRuntimeHttpClient` 호출처 없음). -- REST v2 auth fail-close/final invariant -- total logical deadline와 bounded response decoder -- complete cursor/conditional request -- typed schema/mapper registry -- strict query/mutation definition과 concurrency coordinator -- GraphQL reference adapter -- Connect-Web reference adapter -- gRPC-Web reference adapter -- Protobuf REST Gateway +2026-09-25 코드 기준 상태: + +| 항목 | 상태 | 코드 위치 | +| --- | --- | --- | +| auth fail-close / final request invariant | 구현됨. 자격증명 없음·owner 장애·scope 불일치면 fetch 0회. 전송 직전 최종 요청을 다시 검사 | `runtime-adapters.ts` `attachCredentials`, `http-execution-v3.ts` credential patch 처리, `src/adapters/http/http-contract-bridge.ts` `checkFinalInvariants` | +| total logical deadline | 구현됨. 자격증명·lease·fetch·본문·backoff가 마감 하나를 공유. `REQUEST_TIMEOUT_MS`는 상한 | `http-execution-v3.ts` `effectiveDeadlineMs`, lifetime signal | +| bounded response decoder | 구현됨. 선언 길이 → 스트림 바이트 → JSON 구조 → 스키마 순 | `src/adapters/http/bounded-body-reader.ts`, `bounded-json.ts`, `http-execution-v3.ts` `admitResponse` | +| typed schema/mapper | 구현됨. 계약별 input/output/problem validator와 feature mapper | `src/contracts/external-contract-runtime.ts`, `src/adapters/http/feature-http-binding.ts` | +| strict query/mutation definition과 concurrency coordinator | 구현됨 | `src/contracts/server-state.ts` `bindQuery`·`BoundMutation`, `src/presentation/adapters/query/application-query.ts` | +| 결과 불명 command의 같은 키 재전송 | 구현됨. 사용자가 누를 때만 보낸다 | `application-query.ts` `resendUnknownEffect` (6.3) | +| cursor pagination | runtime만 있다. 설치된 operation이 쓰지 않는다 | `src/adapters/query-cache/cursor-pagination-runtime.ts` | +| conditional request | validator store만 조합됐다. V3는 `If-None-Match`/`If-Match`를 보내지 않는다 | `src/adapters/query-cache/conditional-validator-store.ts` | +| GraphQL reference adapter | 구현 안 됨 | 없음 | +| Connect-Web / gRPC-Web reference adapter | provider 중립 Browser RPC runtime만 있다. 조합되지 않았다 | `src/adapters/browser-rpc/` | +| Protobuf REST Gateway | 구현 안 됨 | 없음 | +| operation별 `TrafficAdmission` switch | 구현 안 됨 | 없음 | GraphQL/Connect/gRPC-Web/REST Gateway 절차는 해당 runtime과 actual provider가 구현·조합된 뒤에만 운영 gate로 활성화한다. 문서나 fake fixture만으로 capability를 @@ -142,11 +152,14 @@ artifact에서 access-controlled하게 비교한다. ### 5.1 Auth-required request가 무자격으로 전송됨 -현재 v1은 external auth integration이 unavailable이어도 unchanged request가 -전송될 수 있으므로 target v2 전까지 제품 auth-required traffic을 provider -evidence 없이 활성화하지 않는다. +V3는 자격증명이 없거나(`UNAUTHENTICATED`), auth owner가 장애거나 +(`integration-failed` → `CREDENTIAL_OWNER_UNAVAILABLE`), scope가 준비되지 않았으면 +fetch 없이 끝난다(`src/bootstrap/runtime-adapters.ts` `attachCredentials`, +`src/adapters/http/http-execution-v3.ts` credential patch 처리). 전송 0회 미인증은 +diagnostics에만 남고 `api.request.failed`에는 세지 않는다(03-07). 그래도 무자격 +전송이 보이면 V3가 아닌 경로(V2 client 직접 조합, 외부 SDK)를 먼저 의심한다. -target 점검: +점검: 1. session state가 authenticated인지 확인한다. 2. auth owner가 `CredentialPatch`만 반환하는지 또는 final request invariant를 @@ -179,23 +192,26 @@ target 점검: ## 6. REST incident -### 6.0 Current v1 available checks +### 6.0 V3에서 바로 쓸 수 있는 점검 -1. current per-attempt timeout/bounded retry, Query retry off, AbortSignal과 401 - recovery observation을 확인한다. -2. installed request/envelope/payload Zod schema와 mapper failure kind를 확인하되 - current `Response.json()`이 body cap 증거가 아님을 기록한다. +1. 전체 마감 하나와 재시도 상한 min(계약 `retryBudget`, `MAX_RETRY_ATTEMPTS`, 2)을 + 확인한다. TanStack Query 재시도는 꺼져 있다(`http-execution-v3.ts`, + `src/adapters/query-cache/tanstack-query-cache.ts`). 전송별 차이는 + [backend contract 16.1절](../architecture/backend-api-and-server-state-contract.md) + 표를 본다. +2. 본문은 `bounded-body-reader.ts`가 상한을 적용한 뒤 계약 validator와 feature + mapper를 거친다. 실패 kind로 어느 단계인지 좁힌다. 3. QueryClient/coordinator로 affected read를 cancel/invalidate/clear한다. -4. cursor response/page runtime, APP_ETAG와 total deadline은 아직 없으므로 해당 - control을 실행했다고 기록하지 않는다. -5. command effect는 backend와 reconcile한다. basic optimistic snapshot 문제가 - 의심되면 runtime switch를 가정하지 말고 no-optimistic/known-good release로 - rollback한다. +4. cursor runtime과 conditional request는 설치된 operation에 조합되지 않았으므로 + 해당 control을 실행했다고 기록하지 않는다(1절 표). +5. 문의 식별자는 `AppFailure.requestId`와 diagnostics `correlation_id`로 서버 로그와 + 잇는다(5.2절 6항). -아래 6.1~6.5는 target v2 coordinator가 해당 operation에 composed된 뒤에만 -운영 절차로 활성화한다. +6.1·6.2는 V3 operation에 적용한다. 항목 중 V3에 없는 control은 실행했다고 +기록하지 않는다. 6.4·6.5는 해당 runtime이 operation에 조합된 뒤에만 운영 절차로 +활성화한다. -### 6.1 Timeout/retry storm — target v2 +### 6.1 Timeout/retry storm 1. Query retry가 꺼지고 REST transport 하나만 network retry하는지 확인한다. 2. total logical deadline 안에 auth, fetch, body, mapper, recovery와 sleep이 모두 @@ -210,7 +226,7 @@ target 점검: 7. timer/listener/reader leak가 있는 cohort는 traffic을 닫는다. 8. keyed command는 backend dedupe evidence 없이는 retry를 끈다. -### 6.2 Body/media/schema failure — target v2 +### 6.2 Body/media/schema failure 1. final URL/status/content type을 확인한다. 2. present/valid Content-Length advisory preflight와 actual browser-visible decoded @@ -227,15 +243,24 @@ target 점검: 10. backend/frontend artifact가 coherent하지 않으면 operation traffic을 닫고 N/N-1 compatible set으로 rollback한다. -### 6.3 Idempotency/ambiguous command — target v2 +### 6.3 Idempotency/ambiguous command 1. principal/operation/payload digest/key tuple과 backend TTL/status를 access-controlled evidence에서 확인한다. 2. 같은 key + 다른 payload가 거절되는지 확인한다. 3. concurrent same-key request가 duplicate commit을 만들지 않았는지 확인한다. -4. `UNKNOWN` effect에 새 key를 생성해 retry하지 않는다. -5. backend status/receipt로 `COMMITTED`면 cache reconcile/invalidate한다. -6. `NOT_APPLIED`가 증명된 경우만 정책에 따라 retry한다. +4. `UNKNOWN` effect에 새 key를 생성해 retry하지 않는다. 클라이언트는 결과 불명 + admission의 intent를 보관하고, 같은 canonical input의 재저장과 "같은 요청으로 + 다시 보내기"는 그 intent와 같은 `Idempotency-Key`로 보낸다. 입력이 바뀌면 새 + key다. 자동 재전송은 없다(`src/presentation/adapters/query/application-query.ts` + `submit`·`resendUnknownEffect`, 화면 `src/presentation/components/async-surface.tsx`). +5. backend status/receipt로 `COMMITTED`면 cache reconcile/invalidate한다. 화면의 + "변경됨으로 확인"이 이 경로다. +6. `NOT_APPLIED`가 증명된 경우만 정책에 따라 retry한다. 화면은 근거 없는 + "변경되지 않음" 확정을 주지 않고 목록 새로고침 링크를 준다. +7. 한계: 결과 불명 admission은 메모리에만 있다. 새로고침·로그아웃·계정 전환 뒤 + 같은 입력의 저장은 새 key다. 서버 key 보관 기간이 지난 뒤의 재전송도 중복될 + 수 있다. 두 경우는 backend 도메인 유일성 제약이나 status 조회로 막는다. ### 6.4 Cursor loop — target v2