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 <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
f329cc8042
commit
0e54e838c6
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user