문제: 80e7f1d의 isRefusedOnEveryAttempt는 kind가 VALIDATION_REJECTED면 code를 보지 않고 참을 돌려준다. 그 kind는 기능의 mapProblem이 정한다. 생성기는 선언한 <FEATURE>_INVALID를 VALIDATION_REJECTED로 옮기고 (scripts/create-feature-write-slice.ts mapProblem), 참조 기능 gateway는 code와 상관없이 모든 422를 그렇게 옮긴다(reference-http-gateway.ts). 그래서 기능이 선언한 code나 422 IDEMPOTENT_REQUEST_MISMATCH로 끝난 같은 키 재전송이 결과 불명을 푼다. 함수 주석, CHANGELOG, 런북 6.3-4는 이것들이 결과 불명으로 남는다고 적는다. 기존 테스트는 mapProblem 없이 실패를 만들어 이 길을 타지 않았다(최종 리뷰 FR-01). 고른 방법(메인 세션 결정 "D10 보완 2"): 재전송 거절은 짝 백엔드 표의 code일 때만 결과 불명을 푼다. 지금은 400 VALIDATION_FAILED와 400 IDEMPOTENCY_KEY_INVALID다(REFUSALS_OF_EVERY_ATTEMPT, code와 status 함께). kind 줄을 지우고 kind로 입력 검증을 말하던 주석과 런북 6.3-4를 고쳤다. 기능 code는 상태 규칙일 수 있어 mapProblem이 정한 kind를 믿지 않는다. 400 VALIDATION_FAILED는 필드 목록이 있든 없든 전처럼 푼다. 테스트: 훅의 결과 불명 유지 it.each에 mapProblem 모양(VALIDATION_REJECTED + 선언 code, VALIDATION_REJECTED + 422 IDEMPOTENT_REQUEST_MISMATCH) 두 행을 더했다. 참조 페이지에서 422 재전송이 필드 오류와 다시 저장을 보인다던 테스트를, 결과 불명이 남고 확인이 보이는 테스트로 바꿨다. 리뷰가 요청한 대로 다시 마운트한 폼이 다른 값을 보이는 채 재전송해 422 IDEMPOTENT_REQUEST_MISMATCH를 받으면 결과 불명과 확인 버튼이 남는 테스트를 더했다. 버린 대안: kind 줄을 남기고 기능 선언 code만 빼기(실행기는 code가 선언인지 폼과 훅에 알리지 않는다). 위험·한계: 참조 기능처럼 problem details를 읽는 기능의 422 입력 검증은 재전송 뒤 결과 불명으로 남는다. 출구는 결과 불명 화면의 확인이다. 리뷰 실험 03-R1 X1~X3·X5는 그대로 키가 모두 key-1이어야 한다. CHANGELOG는 다음 커밋이 적는다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/component/application-mutation-admission.test.tsx tests/features/reference-feature/reference-page.test.tsx tests/component/form-foundation.test.tsx tests/unit/backend-envelope.test.ts, 리뷰 실험 03-R1 패치를 이 커밋에 적용 Refs: 1106/03-01 (final review FR-01)
34 KiB
API contract와 Server State recovery
- 상태: current REST 절차 + future GraphQL/Connect/gRPC-Web/REST Gateway/ schema/cache 절차 분리
- backend 구조와 handoff: Backend API와 Server State contract
- 기준일: 2026-07-28, 1절·5.1·6.0·6.3은 2026-09-25 V3 코드 기준으로 갱신
- 설계: API contract, Schema, Mapper와 Server State
- browser Protobuf/gateway 설계: Protobuf browser transport와 REST Gateway
1. 적용 범위
현재 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 시절에 쓴 말이다. V2 client는 2026-11-03에 지웠다.
HTTP 경로는 V3 하나다.
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의 같은 키 재전송 | 구현됨. 사용자가 누를 때만 보낸다. 키 없는 command(NEVER)에는 재전송을 주지 않는다 |
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를
AVAILABLE_NOT_COMPOSED, COMPOSED 또는 production-ready라고 기록하지 않는다.
canonical readiness:
Selection
TrafficAdmission
RuntimeHealth
PromotionEvidence
이 readiness model은 target v2 control plane이다. current v1에는 operation별
TrafficAdmission runtime switch가 없다.
| control | current v1 | target v2 |
|---|---|---|
| operation traffic switch | 없음 | provider/family/operation별 TrafficAdmission |
| frontend containment | promotion 중지와 known-good release rollback; feature composition 변경은 재배포 필요 | atomic admission disable |
| provider containment | actual BFF/API owner의 route/kill switch가 있을 때만 사용 | registered provider kill switch와 probe |
| query cleanup | composed QueryClient/coordinator의 cancel·invalidate·local clear | generation fence와 profile-scoped cleanup |
| mutation recovery | backend 상태/idempotency owner와 수동 reconcile | effect certainty + runtime/scope coordinator |
따라서 current v1 incident에서 존재하지 않는 switch를 내렸다고 기록하지 않는다.
target v2가 composed된 operation만 TrafficAdmission을 먼저 내린다. 그 전에는
신규 promotion을 중지하고 known-good release rollback 또는 실제 backend/BFF
route 차단을 owner와 수행한다. primary status나 contract version을 운영자가
임의로 낮춰 현재 상태를 숨기지 않는다.
current v1으로의 fallback은 (1) 해당 operation의 provider/security evidence가 만료되지 않았고, (2) incident class가 v1 또는 shared boundary에 영향이 없으며, (3) auth fail-close/final invariant hardening이 유지되는 경우만 허용한다. 하나라도 증명하지 못하면 v1을 사용하지 않고 safe unavailable 또는 실제 provider route 차단으로 닫는다.
2. 관측 허용과 금지
허용된 bounded aggregate:
- semantic operation/profile/provider ID
- protocol/semantics
- safe failure kind
- HTTP status group, GraphQL safe category, gRPC status bucket
- logical/physical attempt, auth recovery와 deadline bucket
- provider가 측정한 encoded transfer bucket과 browser가 측정한 decoded/result/message/frame/page/item byte/count bucket
- schema/mapper/query profile version과 compatibility outcome
- cache hit/miss/stale/refresh/admission/eviction
- mutation concurrency/optimistic/rollback/conflict/effect/invalidation outcome
- stream terminal/gap/overflow/idle bucket
금지:
- URL/path/search/header/body
- credential, cookie, CSRF, idempotency key
- GraphQL document/hash/variables/data/error message/path/extensions
- protobuf payload/debug JSON/metadata/trailer/status-details
- DTO/application/cache value/optimistic patch
- cursor/snapshot/ETag/revision/resume token
- account/tenant/resource/file ID
- raw backend request/trace/correlation value
incident ticket에 금지 값을 복사하지 않는다. credential/payload 노출 의심이면 일반 contract incident가 아니라 security incident로 분류하고 provider revoke, key/session rotation과 로그 보존 범위를 별도 owner에게 escalate한다.
3. 최초 containment
- 영향 operation family/protocol/provider/browser/release cohort를 safe aggregate로 좁힌다.
- target v2 control이 실제 composed됐으면 해당 operation의
TrafficAdmission을DISABLED또는 안전한 canary cohort로 낮춘다. current v1이면 promotion을 중지하고 known-good release rollback 또는 실제 backend/BFF route control을 사용한다. - query/read는 cancel하고 stream reader를 닫는다.
- command는 무조건 retry/rollback하지 않고 effect certainty를
NOT_APPLIED | COMMITTED | UNKNOWN으로 분류한다. UNKNOWNcommand는 backend idempotency/status/reconcile owner에게 전달한다.- current scope의 suspect query를 invalidate한다. wrong-scope/contract-poison 가능성이 있으면 cancel 후 current runtime cache를 clear한다.
- GraphQL/Connect/gRPC-Web failure를 REST command로 자동 failover하지 않는다.
- contract tuple과 artifact를 확인한다.
frontend release/build
runtime config/API contract version
installed operation registry digest
runtime schema/mapper/query policy digest
REST/OpenAPI artifact
GraphQL schema + persisted manifest
protobuf descriptor/generated artifact
Connect client/server/provider profile
HttpRule/ProtoJSON/OpenAPI/gateway artifact
BFF/router/proxy/backend release
실제 digest 값을 high-cardinality telemetry label로 보내지 않고 incident evidence artifact에서 access-controlled하게 비교한다.
4. 공통 증상 분류
| 증상 | 우선 확인 |
|---|---|
| 특정 release에서 전 operation 실패 | runtime config, provider endpoint, auth owner, contract set |
| schema/mapper mismatch 급증 | backend artifact rollout, unknown/null/enum/scalar 변화, wrong codec |
| retry/traffic 폭증 | retry owner 중복, 401 loop, Retry-After, total deadline |
| stale/wrong account data | scope generation, late result, query key collision, invalidation |
| command duplicate/rollback 이상 | idempotency tuple, input-aware concurrency, optimistic revision |
| list가 반복/무한 증가 | cursor loop/snapshot/page/item/byte ceiling |
| provider 200인데 client 실패 | status/media/envelope/schema/mapper/body cap |
| 로그에서 payload/ID 발견 | redaction/allowlist bypass, diagnostics producer |
5. Auth와 CSRF
5.1 Auth-required request가 무자격으로 전송됨
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가 아닌 경로(외부 SDK 직접 호출)를 먼저 의심한다.
점검:
- session state가 authenticated인지 확인한다.
- auth owner가
CredentialPatch만 반환하는지 또는 final request invariant를 재검증하는지 확인한다. - URL/origin/method/body digest/idempotency/conditional/CSRF가 attach 전후 같은지 확인한다.
- unavailable/integration-failed/attach rejected에서 fetch가 0회인지 증명한다.
- 401 recovery가 logical execution당 1회인지 확인한다.
- concurrent 401이 single-flight recovery를 공유하는지 확인한다.
- non-replayable command가 recovery 뒤 재실행되지 않았는지 확인한다.
의심 시 operation auth traffic을 즉시 닫는다. anonymous fallback을 만들지 않는다.
5.2 CSRF/CORS
- unsafe cookie request의 exact Origin/Fetch Metadata/CSRF proof를 server에서 확인한다.
- SameSite/custom header/preflight 하나만으로 방어했다고 기록하지 않는다.
- cross-origin allow-origin/credentials/method/header/expose가 exact한지 확인한다.
- wildcard credential, redirect와 unexpected origin을 복구한다.
- CSRF token/header 값을 ticket에 기록하지 않는다.
- V3 요청은 논리 실행마다
x-correlation-id하나를 보낸다(재시도도 같은 값,src/adapters/http/http-execution-v3.tscreateRequestId). cross-origin API면 preflightAccess-Control-Allow-Headers에x-correlation-id가 있어야 요청이 나간다. 응답의x-correlation-id를AppFailure.requestId와 diagnosticscorrelation_id로 쓰려면Access-Control-Expose-Headers에도 넣는다 (src/adapters/http/feature-http-binding.tsprojectExecutionOutcome,src/bootstrap/runtime-adapters.tscreateHttpObservationProjector). telemetry에는 넣지 않는다. 반사값이 없으면(마감 초과, 연결 끊김, 헤더를 노출하지 않는 서버나 게이트웨이)requestId는 요청에 보낸 값이다(V3 결과의sentRequestId). 결과 불명 쓰기 화면은 이 값을 "지원 참조"로 보인다(0929/03-04).
6. REST incident
6.0 V3에서 바로 쓸 수 있는 점검
- 전체 마감 하나와 재시도 상한 min(계약
retryBudget,MAX_RETRY_ATTEMPTS, 2)을 확인한다. TanStack Query 재시도는 꺼져 있다(http-execution-v3.ts,src/adapters/query-cache/tanstack-query-cache.ts). 전송별 차이는 backend contract 16.1절 표를 본다. - 본문은
bounded-body-reader.ts가 상한을 적용한 뒤 계약 validator와 feature mapper를 거친다. 실패 kind로 어느 단계인지 좁힌다. - QueryClient/coordinator로 affected read를 cancel/invalidate/clear한다.
- cursor runtime과 conditional request는 설치된 operation에 조합되지 않았으므로 해당 control을 실행했다고 기록하지 않는다(1절 표).
- 문의 식별자는
AppFailure.requestId와 diagnosticscorrelation_id로 서버 로그와 잇는다(5.2절 6항).
6.1·6.2는 V3 operation에 적용한다. 항목 중 V3에 없는 control은 실행했다고 기록하지 않는다. 6.4·6.5는 해당 runtime이 operation에 조합된 뒤에만 운영 절차로 활성화한다.
6.1 Timeout/retry storm
- Query retry가 꺼지고 REST transport 하나만 network retry하는지 확인한다.
- total logical deadline 안에 auth, fetch, body, mapper, recovery와 sleep이 모두 포함되는지 확인한다.
- attempt timeout과 logical deadline exhaustion을 별도 kind로 확인한다.
- 초회/retry/401 replay 모든 provider fetch가 하나의 monotonic physical-attempt cap을 소비하는지 확인한다.
- exact retry status가 network/408/429/502/503/504 중 operation subset인지 확인한다.
- 429/503
Retry-After가 injected clock, max sleep/elapsed ceiling을 지키는지 확인한다. - timer/listener/reader leak가 있는 cohort는 traffic을 닫는다.
- keyed command는 backend dedupe evidence 없이는 retry를 끈다.
6.2 Body/media/schema failure
- final URL/status/content type을 확인한다.
- present/valid Content-Length advisory preflight와 actual browser-visible decoded byte cap을 확인한다.
- actual encoded transfer/decompression ratio cap은 BFF/proxy/CDN evidence에서 확인한다. browser reader가 encoded bytes를 셌다고 가정하지 않는다.
- standard JSON parse profile이면 decoded byte는 pre-parse guard, depth/node/key는 post-parse admission guard인지 확인한다.
- truncated, content encoding/decompression overflow와 invalid UTF-8을 구분한다.
- success status/media/envelope profile이 operation registry와 일치하는지 확인한다.
- schema unknown-field policy와 actual codec fingerprint를 확인한다.
- failure body/value를 출력하지 않는다.
- schema/mapper failure result를 cache하지 않았는지 확인한다.
- backend/frontend artifact가 coherent하지 않으면 operation traffic을 닫고 N/N-1 compatible set으로 rollback한다.
6.3 Idempotency/ambiguous command
- principal/operation/payload digest/key tuple과 backend TTL/status를 access-controlled evidence에서 확인한다.
- 같은 key + 다른 payload가 거절되는지 확인한다.
- concurrent same-key request가 duplicate commit을 만들지 않았는지 확인한다.
UNKNOWNeffect에 새 key를 생성해 retry하지 않는다. 클라이언트는 결과 불명 admission의 intent를 보관하고, 같은 canonical input의 재저장과 "같은 요청으로 다시 보내기"는 그 intent와 같은Idempotency-Key로 보낸다. 입력이 바뀌면 새 key다. 자동 재전송은 없다(src/presentation/adapters/query/application-query.tssubmit·resendUnknownEffect, 화면src/presentation/components/async-surface.tsx). 다시 보낸 요청이 쓰기 전에 거절되거나(429, 401, 403, 503RATE_LIMIT_*, 422IDEMPOTENT_REQUEST_MISMATCH, 기능이 선언한 code) 보내지 못하면(NOT_STARTED) 그 시도만 적용되지 않은 것이다. 결과 불명과 key는 그대로다. 폼은 "잠시 뒤 같은 요청으로 다시 보내 주세요"와 결과 불명 화면(확인, 다시 보내기)을 보이고 저장을 받지 않는다. 401은 다시 로그인 안내가 먼저다. 예외는 같은 요청이 매번 받는 거절이다. 짝 백엔드 표의 400VALIDATION_FAILED(필드 목록이 있든 없든)와 400IDEMPOTENCY_KEY_INVALID만 첫 요청도 거절됐다는 뜻으로 읽어 결과 불명을 풀고, 폼은 필드 오류를 보이고 저장을 다시 받는다. 기능의mapProblem이 정한 kind(VALIDATION_REJECTED)는 보지 않는다. 기능 code는 상태 규칙일 수 있다(1106/03-01,src/contracts/errors.tsisRefusedOnEveryAttempt). 키가 없는 command(NEVER)는 서버가 두 번째 요청을 가려내지 못하므로 재전송 버튼을 그리지 않는다(canResendUnknownEffect, 0929/03-03). 같은 canonical input의 재저장도 보내지 않는다. 훅의submit이NOT_STARTEDDUPLICATE_IN_FLIGHT(codeUNKNOWN_EFFECT_PENDING)를 돌려주고, 결과 불명 요청이 확인될 때까지 그대로다. 폼 밖에서submit을 부르는 화면도 같다. 화면은 상태에unknownEffectResendable: true가 있을 때만 재전송 버튼을 그린다.IDEMPOTENTcommand는 키가 없어도 두 번 적용한 결과가 같아서 재전송과 같은 입력 재저장을 보낸다(정책resendSafe, 1106/03-03).- backend status/receipt로
COMMITTED면 cache reconcile/invalidate한다. 화면의 "변경됨으로 확인"이 이 경로다. NOT_APPLIED가 증명된 경우만 정책에 따라 retry한다. 화면은 근거 없는 "변경되지 않음" 확정을 주지 않고 목록 새로고침 링크를 준다.- 한계: 결과 불명 admission은 메모리에만 있다. 새로고침·로그아웃·계정 전환 뒤 같은 입력의 저장은 새 key다. 서버 key 보관 기간이 지난 뒤의 재전송도 중복될 수 있다. 두 경우는 backend 도메인 유일성 제약이나 status 조회로 막는다.
6.4 Cursor loop — target v2
- query root filters/sort/scope/snapshot을 확인한다.
- same cursor 반복,
hasMore/cursor 모순과 non-progress page를 확인한다. - max pages/items/bytes를 초과했으면 추가 fetch를 중지한다.
- snapshot이 바뀌었으면 old/new pages를 합치지 않고 root부터 재시작한다.
- raw cursor/next URL을 로그에 남기거나 임의 follow하지 않는다.
6.5 Conditional request — target v2
- operation cache owner가
APP_ETAG인지 browser HTTP cache인지 확인한다. - 304에서 exact query/scope/generation/validator binding과 mapped cached value가 모두 있는지 확인한다.
- 304가 same query-entry cache revision CAS를 통과했는지 확인한다.
- cached value가 없으면 304를 success로 만들지 않는다.
- full 200 value와 validator가 atomic하게 교체됐는지 확인한다.
- Query removal/GC, scope/logout와 release/contract/schema/mapper epoch에서 sidecar가 함께 폐기됐는지 확인한다.
- 412 precondition과 409 business conflict를 구분한다.
- ETag/revision 값을 incident ticket에 기록하지 않는다.
7. GraphQL incident
이 절은 VD-26 runtime 조합 후 적용한다.
7.1 Persisted operation mismatch
- frontend schema/operation manifest와 router manifest 호환성을 확인한다.
- operation ID, hash, schema digest와 retirement window를 artifact에서 비교한다.
- full document fallback/APQ miss fallback을 활성화하지 않는다.
- affected GraphQL operation traffic을 닫는다.
- frontend + manifest + router를 coherent N/N-1 set으로 rollback한다.
7.2 HTTP/media + data/errors
- selected GraphQL-over-HTTP revision, persisted-envelope extension,
Accept/response media와 status/body matrix를 확인한다. application/graphql-response+json이면 허용 status에서도 body를 bounded GraphQL envelope로 처리했는지 확인한다. legacyapplication/jsonnon-2xx intermediary body를 GraphQL error로 해석하지 않는다.errors=[], null/absent data + no errors를 envelope mismatch로 닫았는지 확인한다.- data/errors state branch와 operation partial policy를 확인한다.
- raw message/path/extensions를 보지 않고 allowlisted safe code만 확인한다.
- query partial이
ALLOW_TYPED_PARTIAL조건을 모두 만족하는지 확인한다. - unauthorized/contract error field를 previous cache로 자동 채우지 않는다.
- mutation이면 effect certainty/receipt를 확인한다.
- partial/mutation error를 ordinary success로 cache하지 않는다.
7.3 Cost/depth/rate failure
- persisted operation manifest의 max cost/depth/aliases/list와 router 실제 budget을 비교한다.
- variables/response size가 frontend/server 양쪽 ceiling 안인지 확인한다.
- client retry storm을 끈다.
- arbitrary operation 또는 introspection을 허용해 우회하지 않는다.
- field authorization과 cost budget을 별도 확인한다.
7.4 Incremental/subscription
선택된 경우에만:
- exact incremental/subscription protocol/provider revision
- exact Accept/Content-Type parameter와 payload discriminant
- multipart boundary/part/path/terminal/byte/patch count
- truncated/duplicate/out-of-order
- proxy buffering
- sequence/gap/resume/heartbeat
- bounded queue/overflow
- logout/unsubscribe
terminal completeness 전 staging을 complete query cache로 commit하지 않는다.
8. gRPC-Web incident
이 절은 VD-27 runtime 조합 후 적용한다.
8.1 HTTP success인데 RPC 실패/멈춤
- exact client runtime/wire-spec revision/content type/transport/rpc-kind capability matrix를 확인한다. official XHR runtime과 Connect-Web/custom Fetch runtime을 같은 cancel/deadline/frame 관측 경로로 취급하지 않는다.
responseHttpStatusProfileId와 HTTP status/gRPC media/terminal-source 교차 matrix를 확인한다.- custom Fetch framed runtime이면 frame prefix/length/flag/compression을
확인한다. official runtime이면 runtime-owned callback/status API와
ClientReadableStream.cancel()경로를 확인하며 rawReadableStreamparser가 있다고 가정하지 않는다. - body trailer frame 또는 zero-body trailers-only response header 중 terminal status source가 정확히 하나인지 확인한다.
grpc-status가 있으면 canonical decimal0..16으로 exactly once인지, body trailer name lowercase와 rich-details outer code가 맞는지 확인하며 그 status를 authority로 사용한다.grpc-status가 없으면 공식 fallback만 적용한다:400→INTERNAL,401→UNAUTHENTICATED,403→PERMISSION_DENIED,404→UNIMPLEMENTED,429|502|503|504→UNAVAILABLE, 그 외UNKNOWN. 이것을 wire header로 위조하지 않고 internal normalized failure로만 사용한다.- HTTP success만으로 RPC success를 기록하지 않는다. duplicate/conflicting/ malformed terminal source는 provider incompatibility로 traffic을 닫는다.
- Envoy의 upstream HTTP/2, filter order, route/idle/max-stream timeout과 buffering profile을 확인한다. default route timeout으로 long stream이 잘렸는지 확인한다.
- raw grpc-message/status-details를 ticket에 복사하지 않는다.
8.2 Unary response
- OK status에서 response message가 exact 1개인지 확인한다.
google.protobuf.Empty도 zero-length payload data frame 하나여야 한다. trailers-only OK + zero-message unary는 contract mismatch다.- two-or-more message/data-after-trailer/extra bytes를 contract mismatch로 닫는다.
- generated decode 뒤 semantic schema/mapper가 통과했는지 확인한다.
- failure/late generation에서 cache write가 0인지 확인한다.
8.3 Server stream
- message/frame/total bytes/count/idle/total deadline을 확인한다.
- bounded queue와 consumer backpressure를 확인한다.
- duplicate/order/gap/resume token protocol을 확인한다.
- event 전달 뒤 transport-only auto replay가 없었는지 확인한다.
- overflow/gap/truncation에서 current aggregate를 complete success로 쓰지 않는다.
- finite aggregate는 valid OK terminal status/completeness 뒤 atomic cache commit인지 확인한다.
- actual proxy buffering/flush와 affected browser cohort를 확인한다.
8.4 Proxy/CORS
- Envoy/BFF/selected gateway filter와 upstream route
- exact allow/expose headers
- credential/CSRF/Origin
- trailer preservation
- content type
- compression/message/deadline cap
- stream buffering
actual proxy를 복구한다. client decoder를 느슨하게 만들어 provider drift를 수용하지 않는다.
9. Connect와 REST Gateway incident
이 절은 VD-29/VD-30 runtime이 실제 조합된 operation에만 적용한다.
9.1 Connect unary/server stream
- exact Connect-Web package/runtime,
CONNECT | GRPC_WEB, JSON/binary, POST/GET와 rpc kind row를 확인한다. content type으로 다른 protocol을 자동 선택하지 않는다. - Connect unary는 HTTP status + bounded Connect error, stream은 HTTP admission + exactly-one final EndStream을 각각 authority로 사용한다.
- missing/early/duplicate EndStream, terminal 뒤 data, malformed/oversize envelope와 compression mismatch에서 call을 cancel하고 cache write를 막는다.
- stock runtime이 whole unary body를 읽는 profile이면 edge encoded/decompressed cap과 selected version의 actual overflow evidence를 확인한다. interceptor가 raw-byte cap을 제공했다고 기록하지 않는다.
- remaining total deadline이 0 이하면 runtime
timeoutMs=0을 호출하지 않고 local deadline failure로 닫는다. abort 뒤 command는 backend receipt로 reconcile한다. - GET은 descriptor
NO_SIDE_EFFECTS, input classification, URL cap, cache key,Vary와 credential/preflight profile이 모두 일치하는지 확인한다. - raw Connect message/metadata/detail/debug를 ticket에 복사하지 않는다.
9.2 Protobuf REST Gateway
- selected gateway kind/version과 descriptor, canonical HttpRule manifest, ProtoJSON profile, OpenAPI와 runtime config digest를 coherent set으로 비교한다.
- method/path/query/body/additional binding, path escaping과 response-body projection drift를 확인한다.
- ProtoJSON field name/default/enum/int64/bytes/null/presence/unknown behavior를 N/N-1 fixture와 비교한다.
- current REST envelope/status/error를 direct ProtoJSON body나 raw
google.rpc.Status로 잘못 decode했는지 확인한다. 201/204/304/412, ETag, idempotency, pagination과 safe error rewrite가 실제 BFF/gateway owner의 contract인지 확인한다. transcoder가 자동 제공한다고 가정하지 않는다.- browser abort→gateway context→upstream gRPC→application work의 cancellation/ deadline 전파를 확인한다. 이미 commit된 command는 receipt로 reconcile한다.
- runtime response rewrite와 generated OpenAPI가 다르면 affected route admission을 닫고 coherent gateway/contract set으로 rollback한다.
Connect/gRPC-Web/REST 사이 command replay는 금지한다. read-only registered fallback도 old generation을 cancel한 뒤 새 logical query로만 시작한다.
10. Schema/Mapper incident
10.1 Current v1 available checks
- operation의 string schema ID가 installed Zod resolver에 있는지 확인한다.
- envelope/payload parse와 mapper/domain factory 중 어느 current boundary에서 실패했는지 safe failure/diagnostics로 좁힌다.
- raw DTO/value를 출력하지 않고 affected query cache write를 확인한다.
- current registry에는 semantic fingerprint/provenance/typed mapper Result가 없으므로 이 값을 비교했다고 기록하지 않는다.
- frontend release/runtime config/manifest의 current string contract coherence를 확인하고 known-good coherent release로 rollback한다.
10.2 Target v2 composed 이후
- operation → schema ID/fingerprint → mapper ID/version binding을 확인한다.
- source artifact/generated output/runtime codec digest를 비교한다.
- missing/null/enum/numeric/time/unknown-field change를 classification한다.
- request strict와 response strip/reject 방향 정책을 확인한다.
- provider encoded-transfer와 browser decoded-byte owner를 분리하고, item/depth/node/string admission ceiling을 확인한다.
- mapper expected semantic failure가 throw/
UNKNOWN_FAILURE로 소실되지 않았는지 확인한다. - cache write와 partial collection이 0인지 확인한다.
- raw validation value/path/DTO를 log에 남기지 않는다.
- incompatible schema/mapper/query cache epoch를 coherent set으로 rollback/clear한다.
11. Server State Cache incident
11.0 Current v1 available checks
- Query retry off, global stale/gc, AbortSignal과 affected query의 cancel/invalidate/local clear를 확인한다.
- current arbitrary key/canonicalize와 hook-local pending Promise를 관측하고 collision/incorrect join cohort cache를 clear한다.
- current whole-snapshot optimistic rollback이 다른 commit을 덮었는지 backend authoritative state로 reconcile한다.
- strict key/identity token, cursor page와 optimistic layer CAS는 아직 없으므로 해당 fixture/control이 실행됐다고 기록하지 않는다.
- 필요하면 known-good/no-optimistic release로 rollback한다. operation별 runtime optimistic switch가 있다고 가정하지 않는다.
아래 10.1~10.4는 target v2 cache/mutation coordinator가 composed된 뒤 활성화한다.
11.1 Wrong/stale scope — target v2
- VD-13 frozen scope projection과 runtime generation을 확인한다.
- account/logout/release switch 전 query를 cancel했는지 확인한다.
- late response/mapper/cache write fence를 확인한다.
- raw account/resource ID를 key에서 찾거나 출력하지 않는다.
- current runtime cache를 clear/remount하고 backend authoritative data를 refetch한다.
11.2 Query key collision — target v2
- arbitrary key API가 남아 있는지 확인한다.
- undefined/NaN/Date/class/accessor/cycle/sparse/oversize fixture를 실행한다.
- collision 가능 cohort의 cache를 clear한다.
- strict key codec/profile 없는 신규 query traffic을 닫는다.
- URL/document/protobuf serialization을 key로 급히 넣지 않는다.
11.3 Mutation ordering/rollback — target v2
- 전체 validated semantic input의 runtime-private exact equality + identity token이 아닌 hook instance로 join/reject를 판정했는지 확인한다.
JOIN_IDENTICAL | REJECT_DUPLICATE | ALLOW_INDEPENDENT결과와 fetch/Promise 횟수가 profile대로인지 확인한다.- runtime/scope coordinator에서 same logical key의 two-hook/out-of-order execution을 확인한다.
- whole snapshot rollback이 다른 committed mutation을 덮었는지 확인한다.
- 자기 optimistic layer만 base cache revision CAS로 제거/역적용했는지 확인한다.
- CAS miss/unknown effect에서는 다른 commit을 보존하고 invalidate/refetch한다.
- optimistic update를 끄고 authoritative pending/refetch UX로 downgrade한다.
- server commit 뒤 invalidation failure는 command failure로 바꾸지 않는다.
11.4 Cache size/pagination — target v2
- result/page/item/estimated-byte cap을 확인한다.
- identity intern entry/total canonical bytes/active lease와 GC/terminal release leak를 확인한다. token/canonical bytes 자체는 출력하지 않는다.
- unbounded collection/stream history를 cancel/evict한다.
- binary/generated DTO를 cache value로 넣지 않았는지 확인한다.
- max pages와 page eviction/refetch policy를 적용한다.
12. Rollback
target v2 coordinator가 composed된 operation:
TrafficAdmission=DISABLED
-> cancel reads/streams
-> reconcile command effects
-> fence runtime generation
-> clear suspect current-scope memory cache
-> detach provider/listener/auth collaboration
-> restore coherent frontend + contract artifacts + provider/backend
-> run compatibility/provider probes
-> canary
current v1은 위 control이 있다고 가정하지 않는다. 신규 promotion을 중지하고 known-good release를 rollback하며, 실제 backend/BFF owner가 제공하는 route/kill switch가 있을 때만 provider traffic을 차단한다. v1 fallback은 unexpired provider/security evidence, incident가 v1/shared boundary 밖이라는 증거와 auth fail-close/final invariant 유지가 모두 있을 때만 선택하고, 아니면 safe unavailable로 닫는다.
금지:
- GraphQL/Connect/gRPC command를 REST 또는 gateway route로 자동 replay
- schema number/digest만 낮추기
- incompatible cache value를 cast/loose parse
- validation/mapper를 끄고 traffic 유지
- unknown command effect를 optimistic rollback만으로 해결
- auth unavailable을 anonymous request로 downgrade
13. Security containment
다음은 security owner에게 즉시 escalate한다.
- credential/CSRF/idempotency/presigned material이 cache/log에 노출
- auth owner가 endpoint/method/body를 변경
- unauthorized request가 실제 전송
- GraphQL arbitrary document/field authorization bypass
- gRPC metadata/status details payload 노출
- cross-account cache observation
신규 traffic을 닫고 credential/session/provider key/manifest를 필요한 scope에서 revoke/rotate한다. 삭제/보존은 incident response 정책을 따른다.
14. Drill과 evidence
분기 또는 major contract 변경 전:
- REST auth unavailable/final-request mutation
- total deadline/retry/401 single-flight
- oversized/truncated/schema/mapper
- idempotency concurrent replay/unknown effect
- cursor loop/ETag 304/412
- GraphQL persisted miss/partial/cost
- gRPC missing/conflicting terminal status source, corrupt frame와 stream gap
- query key collision/account late result
- optimistic concurrent rollback
- kill switch/coherent rollback
- GraphQL/Connect/gRPC/Gateway generated dependency/provider removal
evidence record:
protocol/operation/provider/profile
frontend/backend/router/proxy/browser version
contract artifact compatibility outcome
fault/drill ID
safe result
started/completed timestamp
owner/reviewer
artifact retention/expiry
raw payload, URL, document, protobuf와 identifier를 evidence record에 넣지 않는다.
15. 관련 문서
- VD-23 API transport selection과 REST execution
- VD-24 Runtime Schema와 boundary Mapper
- VD-25 Server State Cache lifecycle
- VD-26 Persisted GraphQL operation
- VD-27 gRPC-Web unary와 server stream
- VD-29 Connect-Web와 browser Protobuf runtime
- VD-30 Protobuf contract와 REST Gateway
- VD-13 Client cache scope와 persistence