Files
clean-architecture-frontend…/docs/operations/api-contract-and-server-state-recovery.md
DongHyeonka 45e8cb774c docs(operations): 운영 문서와 adapter 재검토 처리 원장을 한국어로 옮긴다
문제: docs/operations의 release-cache-rollback.md와
adapter-remediation-ledger.md는 본문이 영어이고, 나머지 복구 문서와
ci-quality-gates.md에도 영어 문단이 남아 있다.

고른 방법: 뜻을 바꾸지 않고 옮긴다. 원장은 check:remediation-ledger가
읽으므로 같은 변경에서 스크립트를 맞춘다.
- `SECTION_HEADING`을 옮긴 절 제목(`## 세 번째 재검토 (2026-08-14)`)으로
- 「모두 닫혔다」를 잡는 `BLANKET_CLOSURE`에 한국어 대안을 더한다. 영어
  대안은 원장이 인용한 옛 문장을 잡도록 그대로 둔다
- 표 구조, id 칸, disposition 칸의 백틱 값, file-transfer 예산 숫자는
  그대로다
- ci-quality-gates.md의 advisory 표가 복사한 zod·react-router 버전을
  `package.json`·`pnpm-lock.yaml`을 가리키게 바꾼다(number 검사)

위험: check:remediation-ledger는 게이트 밖이라 CI가 돌리지 않는다.
desktop에서 손으로 돌려 확인했다.

검증: dispositions.json의 id 25개가 그 절의 행과 맞는지, 예산 숫자가
있는지를 스크립트로 확인했다. 문서 검사의 language·number 줄이 0이 되어
예외 목록에서 지웠다.
2026-11-08 21:57:47 +09:00

34 KiB

API contract와 Server State recovery

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 조합을 바꾸려면 재배포가 필요 admission을 원자적으로 끄기
provider containment actual BFF/API owner의 route/kill switch가 있을 때만 사용 registered provider kill switch와 probe
query cleanup 조립된 QueryClient/coordinator의 취소·무효화·로컬 삭제 generation fence와 profile 범위 정리
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 그룹, GraphQL의 안전한 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

  1. 영향 operation family/protocol/provider/browser/release cohort를 safe aggregate로 좁힌다.
  2. target v2 control이 실제 composed됐으면 해당 operation의 TrafficAdmission을 DISABLED 또는 안전한 canary cohort로 낮춘다. current v1이면 promotion을 중지하고 known-good release rollback 또는 실제 backend/BFF route control을 사용한다.
  3. query/read는 cancel하고 stream reader를 닫는다.
  4. command는 무조건 retry/rollback하지 않고 effect certainty를 NOT_APPLIED | COMMITTED | UNKNOWN으로 분류한다.
  5. UNKNOWN command는 backend idempotency/status/reconcile owner에게 전달한다.
  6. current scope의 suspect query를 invalidate한다. wrong-scope/contract-poison 가능성이 있으면 cancel 후 current runtime cache를 clear한다.
  7. GraphQL/Connect/gRPC-Web failure를 REST command로 자동 failover하지 않는다.
  8. 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 묶음
schema/mapper 불일치 급증 backend 산출물 배포(rollout), unknown/null/enum/scalar 변화, 잘못된 codec
retry/traffic 폭증 retry owner 중복, 401 loop, Retry-After, total deadline
낡거나 잘못된 account 데이터 scope generation, 늦게 온 결과, query key 충돌, 무효화(invalidation)
command 중복/rollback 이상 idempotency tuple, 입력을 고려한(input-aware) 동시성 제어, 낙관적(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 직접 호출)를 먼저 의심한다.

점검:

  1. session state가 authenticated인지 확인한다.
  2. auth owner가 CredentialPatch만 반환하는지 또는 final request invariant를 재검증하는지 확인한다.
  3. URL/origin/method/body digest/idempotency/conditional/CSRF가 attach 전후 같은지 확인한다.
  4. unavailable/integration-failed/attach rejected에서 fetch가 0회인지 증명한다.
  5. 401 recovery가 logical execution당 1회인지 확인한다.
  6. concurrent 401이 single-flight recovery를 공유하는지 확인한다.
  7. non-replayable command가 recovery 뒤 재실행되지 않았는지 확인한다.

의심 시 operation auth traffic을 즉시 닫는다. anonymous fallback을 만들지 않는다.

5.2 CSRF/CORS

  1. unsafe cookie request의 exact Origin/Fetch Metadata/CSRF proof를 server에서 확인한다.
  2. SameSite/custom header/preflight 하나만으로 방어했다고 기록하지 않는다.
  3. cross-origin allow-origin/credentials/method/header/expose가 exact한지 확인한다.
  4. wildcard credential, redirect와 unexpected origin을 복구한다.
  5. CSRF token/header 값을 ticket에 기록하지 않는다.
  6. V3 요청은 논리 실행마다 x-correlation-id 하나를 보낸다(재시도도 같은 값, src/adapters/http/http-execution-v3.ts createRequestId). cross-origin API면 preflight Access-Control-Allow-Headers에 x-correlation-id가 있어야 요청이 나간다. 응답의 x-correlation-id를 AppFailure.requestId와 diagnostics correlation_id로 쓰려면 Access-Control-Expose-Headers에도 넣는다 (src/adapters/http/feature-http-binding.ts projectExecutionOutcome, src/bootstrap/runtime-adapters.ts createHttpObservationProjector). telemetry에는 넣지 않는다. 반사값이 없으면(마감 초과, 연결 끊김, 헤더를 노출하지 않는 서버나 게이트웨이) requestId는 요청에 보낸 값이다(V3 결과의 sentRequestId). 결과 불명 쓰기 화면은 이 값을 "지원 참조"로 보인다(0929/03-04).

6. REST incident

6.0 V3에서 바로 쓸 수 있는 점검

  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절 표를 본다.
  2. 본문은 bounded-body-reader.ts가 상한을 적용한 뒤 계약 validator와 feature mapper를 거친다. 실패 kind로 어느 단계인지 좁힌다.
  3. QueryClient/coordinator로 affected read를 cancel/invalidate/clear한다.
  4. cursor runtime과 conditional request는 설치된 operation에 조합되지 않았으므로 해당 control을 실행했다고 기록하지 않는다(1절 표).
  5. 문의 식별자는 AppFailure.requestId와 diagnostics correlation_id로 서버 로그와 잇는다(5.2절 6항).

6.1·6.2는 V3 operation에 적용한다. 항목 중 V3에 없는 control은 실행했다고 기록하지 않는다. 6.4·6.5는 해당 runtime이 operation에 조합된 뒤에만 운영 절차로 활성화한다.

6.1 Timeout/retry storm

  1. Query retry가 꺼지고 REST transport 하나만 network retry하는지 확인한다.
  2. total logical deadline 안에 auth, fetch, body, mapper, recovery와 sleep이 모두 포함되는지 확인한다.
  3. attempt timeout과 logical deadline exhaustion을 별도 kind로 확인한다.
  4. 초회/retry/401 replay 모든 provider fetch가 하나의 monotonic physical-attempt cap을 소비하는지 확인한다.
  5. exact retry status가 network/408/429/502/503/504 중 operation subset인지 확인한다.
  6. 429/503 Retry-After가 injected clock, max sleep/elapsed ceiling을 지키는지 확인한다.
  7. timer/listener/reader leak가 있는 cohort는 traffic을 닫는다.
  8. keyed command는 backend dedupe evidence 없이는 retry를 끈다.

6.2 Body/media/schema failure

  1. final URL/status/content type을 확인한다.
  2. present/valid Content-Length advisory preflight와 actual browser-visible decoded byte cap을 확인한다.
  3. actual encoded transfer/decompression ratio cap은 BFF/proxy/CDN evidence에서 확인한다. browser reader가 encoded bytes를 셌다고 가정하지 않는다.
  4. 표준 JSON parse profile이면 decoded byte는 parse 전(pre-parse) guard, depth/node/key는 parse 뒤(post-parse) admission guard인지 확인한다.
  5. truncated, content encoding/decompression overflow와 invalid UTF-8을 구분한다.
  6. success status/media/envelope profile이 operation registry와 일치하는지 확인한다.
  7. schema unknown-field policy와 actual codec fingerprint를 확인한다.
  8. failure body/value를 출력하지 않는다.
  9. schema/mapper failure result를 cache하지 않았는지 확인한다.
  10. backend/frontend artifact가 coherent하지 않으면 operation traffic을 닫고 N/N-1 compatible set으로 rollback한다.

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하지 않는다. 클라이언트는 결과 불명 admission의 intent를 보관하고, 같은 canonical input의 재저장과 "같은 요청으로 다시 보내기"는 그 intent와 같은 Idempotency-Key로 보낸다. 입력이 바뀌면 새 key다. 자동 재전송은 없다(src/presentation/adapters/query/application-query.ts submit·resendUnknownEffect, 화면 src/presentation/components/async-surface.tsx). 다시 보낸 요청이 쓰기 전에 거절되거나(429, 401, 403, 503 RATE_LIMIT_*, 422 IDEMPOTENT_REQUEST_MISMATCH, 기능이 선언한 code) 보내지 못하면(NOT_STARTED) 그 시도만 적용되지 않은 것이다. 결과 불명과 key는 그대로다. 폼은 "잠시 뒤 같은 요청으로 다시 보내 주세요"와 결과 불명 화면(확인, 다시 보내기)을 보이고 저장을 받지 않는다. 401은 다시 로그인 안내가 먼저다. 예외는 같은 요청이 매번 받는 거절이다. 짝 백엔드 표의 400 VALIDATION_FAILED(필드 목록이 있든 없든)와 400 IDEMPOTENCY_KEY_INVALID만 첫 요청도 거절됐다는 뜻으로 읽어 결과 불명을 풀고, 폼은 필드 오류를 보이고 저장을 다시 받는다. 기능의 mapProblem이 정한 kind(VALIDATION_REJECTED)는 보지 않는다. 기능 code는 상태 규칙일 수 있다(1106/03-01, src/contracts/errors.ts isRefusedOnEveryAttempt). 키가 없는 command(NEVER)는 서버가 두 번째 요청을 가려내지 못하므로 재전송 버튼을 그리지 않는다(canResendUnknownEffect, 0929/03-03). 같은 canonical input의 재저장도 보내지 않는다. 훅의 submit이 NOT_STARTED DUPLICATE_IN_FLIGHT(code UNKNOWN_EFFECT_PENDING)를 돌려주고, 결과 불명 요청이 확인될 때까지 그대로다. 폼 밖에서 submit을 부르는 화면도 같다. 화면은 상태에 unknownEffectResendable: true가 있을 때만 재전송 버튼을 그린다. IDEMPOTENT command는 키가 없어도 두 번 적용한 결과가 같아서 재전송과 같은 입력 재저장을 보낸다(정책 resendSafe, 1106/03-03).
  5. backend status/receipt로 COMMITTED면 cache reconcile/invalidate한다. 화면의 "변경됨으로 확인"이 이 경로다.
  6. NOT_APPLIED가 증명된 경우만 정책에 따라 retry한다. 화면은 근거 없는 "변경되지 않음" 확정을 주지 않고 목록 새로고침 링크를 준다.
  7. 한계: 결과 불명 admission은 메모리에만 있다. 새로고침·로그아웃·계정 전환 뒤 같은 입력의 저장은 새 key다. 서버 key 보관 기간이 지난 뒤의 재전송도 중복될 수 있다. 두 경우는 backend 도메인 유일성 제약이나 status 조회로 막는다.

6.4 Cursor loop — target v2

  1. query root filters/sort/scope/snapshot을 확인한다.
  2. same cursor 반복, hasMore/cursor 모순과 non-progress page를 확인한다.
  3. max pages/items/bytes를 초과했으면 추가 fetch를 중지한다.
  4. snapshot이 바뀌었으면 old/new pages를 합치지 않고 root부터 재시작한다.
  5. raw cursor/next URL을 로그에 남기거나 임의 follow하지 않는다.

6.5 Conditional request — target v2

  1. operation cache owner가 APP_ETAG인지 browser HTTP cache인지 확인한다.
  2. 304에서 exact query/scope/generation/validator binding과 mapped cached value가 모두 있는지 확인한다.
  3. 304가 same query-entry cache revision CAS를 통과했는지 확인한다.
  4. cached value가 없으면 304를 success로 만들지 않는다.
  5. full 200 value와 validator가 atomic하게 교체됐는지 확인한다.
  6. Query removal/GC, scope/logout와 release/contract/schema/mapper epoch에서 sidecar가 함께 폐기됐는지 확인한다.
  7. 412 precondition과 409 business conflict를 구분한다.
  8. ETag/revision 값을 incident ticket에 기록하지 않는다.

7. GraphQL incident

이 절은 VD-26 runtime 조합 후 적용한다.

7.1 Persisted operation mismatch

  1. frontend schema/operation manifest와 router manifest 호환성을 확인한다.
  2. operation ID, hash, schema digest와 retirement window를 artifact에서 비교한다.
  3. full document fallback/APQ miss fallback을 활성화하지 않는다.
  4. affected GraphQL operation traffic을 닫는다.
  5. frontend + manifest + router를 coherent N/N-1 set으로 rollback한다.

7.2 HTTP/media + data/errors

  1. selected GraphQL-over-HTTP revision, persisted-envelope extension, Accept/response media와 status/body matrix를 확인한다.
  2. application/graphql-response+json이면 허용 status에서도 body를 bounded GraphQL envelope로 처리했는지 확인한다. legacy application/json non-2xx intermediary body를 GraphQL error로 해석하지 않는다.
  3. errors=[], null/absent data + no errors를 envelope mismatch로 닫았는지 확인한다.
  4. data/errors state branch와 operation partial policy를 확인한다.
  5. raw message/path/extensions를 보지 않고 allowlisted safe code만 확인한다.
  6. query partial이 ALLOW_TYPED_PARTIAL 조건을 모두 만족하는지 확인한다.
  7. unauthorized/contract error field를 previous cache로 자동 채우지 않는다.
  8. mutation이면 effect certainty/receipt를 확인한다.
  9. partial/mutation error를 ordinary success로 cache하지 않는다.

7.3 Cost/depth/rate failure

  1. persisted operation manifest의 max cost/depth/aliases/list와 router 실제 budget을 비교한다.
  2. variables/response size가 frontend/server 양쪽 ceiling 안인지 확인한다.
  3. client retry storm을 끈다.
  4. arbitrary operation 또는 introspection을 허용해 우회하지 않는다.
  5. 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 실패/멈춤

  1. exact client runtime/wire-spec revision/content type/transport/rpc-kind capability matrix를 확인한다. official XHR runtime과 Connect-Web/custom Fetch runtime을 같은 cancel/deadline/frame 관측 경로로 취급하지 않는다.
  2. responseHttpStatusProfileId와 HTTP status/gRPC media/terminal-source 교차 matrix를 확인한다.
  3. custom Fetch framed runtime이면 frame prefix/length/flag/compression을 확인한다. official runtime이면 runtime-owned callback/status API와 ClientReadableStream.cancel() 경로를 확인하며 raw ReadableStream parser가 있다고 가정하지 않는다.
  4. 최종 status를 알려 주는 곳(terminal status source)이 정확히 하나인지 확인한다. 후보는 body trailer frame과, body가 없는 trailers-only 응답의 header다.
  5. grpc-status가 있으면 canonical decimal 0..16으로 exactly once인지, body trailer name lowercase와 rich-details outer code가 맞는지 확인하며 그 status를 authority로 사용한다.
  6. grpc-status가 없으면 공식 fallback만 적용한다: 400→INTERNAL, 401→UNAUTHENTICATED, 403→PERMISSION_DENIED, 404→UNIMPLEMENTED, 429|502|503|504→UNAVAILABLE, 그 외 UNKNOWN. 이것을 wire header로 위조하지 않고 internal normalized failure로만 사용한다.
  7. HTTP success만으로 RPC success를 기록하지 않는다. duplicate/conflicting/ malformed terminal source는 provider incompatibility로 traffic을 닫는다.
  8. Envoy의 upstream HTTP/2, filter 순서, route/idle/max-stream timeout과 buffering profile을 확인한다. default route timeout으로 long stream이 잘렸는지 확인한다.
  9. raw grpc-message/status-details를 ticket에 복사하지 않는다.

8.2 Unary response

  1. OK status에서 response message가 exact 1개인지 확인한다.
  2. google.protobuf.Empty도 zero-length payload data frame 하나여야 한다. trailers-only OK + zero-message unary는 contract mismatch다.
  3. two-or-more message/data-after-trailer/extra bytes를 contract mismatch로 닫는다.
  4. generated decode 뒤 semantic schema/mapper가 통과했는지 확인한다.
  5. failure/late generation에서 cache write가 0인지 확인한다.

8.3 Server stream

  1. message/frame/total bytes/count/idle/total deadline을 확인한다.
  2. bounded queue와 consumer backpressure를 확인한다.
  3. duplicate/order/gap/resume token protocol을 확인한다.
  4. event 전달 뒤 transport-only auto replay가 없었는지 확인한다.
  5. overflow/gap/truncation에서 current aggregate를 complete success로 쓰지 않는다.
  6. 끝이 있는(finite) aggregate는 올바른 OK 최종 status와 완결성(completeness)을 확인한 뒤 cache에 원자적으로 commit하는지 확인한다.
  7. 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

  1. exact Connect-Web package/runtime, CONNECT | GRPC_WEB, JSON/binary, POST/GET와 rpc kind row를 확인한다. content type으로 다른 protocol을 자동 선택하지 않는다.
  2. Connect unary는 HTTP status와 크기 상한이 있는 Connect error를, stream은 HTTP admission과 정확히 하나인 마지막 EndStream을 각각 authority로 사용한다.
  3. missing/early/duplicate EndStream, terminal 뒤 data, malformed/oversize envelope와 compression mismatch에서 call을 cancel하고 cache write를 막는다.
  4. stock runtime이 whole unary body를 읽는 profile이면 edge encoded/decompressed cap과 selected version의 actual overflow evidence를 확인한다. interceptor가 raw-byte cap을 제공했다고 기록하지 않는다.
  5. remaining total deadline이 0 이하면 runtime timeoutMs=0을 호출하지 않고 local deadline failure로 닫는다. abort 뒤 command는 backend receipt로 reconcile한다.
  6. GET은 descriptor NO_SIDE_EFFECTS, 입력 분류, URL 상한(cap), cache key, Vary와 credential/preflight profile이 모두 일치하는지 확인한다.
  7. raw Connect message/metadata/detail/debug를 ticket에 복사하지 않는다.

9.2 Protobuf REST Gateway

  1. selected gateway kind/version과 descriptor, canonical HttpRule manifest, ProtoJSON profile, OpenAPI와 runtime config digest를 coherent set으로 비교한다.
  2. method/path/query/body/additional binding, path escaping과 response-body projection drift를 확인한다.
  3. ProtoJSON field name/default/enum/int64/bytes/null/presence/unknown behavior를 N/N-1 fixture와 비교한다.
  4. current REST envelope/status/error를 direct ProtoJSON body나 raw google.rpc.Status로 잘못 decode했는지 확인한다.
  5. 201/204/304/412, ETag, idempotency, pagination과 safe error rewrite가 실제 BFF/gateway owner의 contract인지 확인한다. transcoder가 자동 제공한다고 가정하지 않는다.
  6. browser abort→gateway context→upstream gRPC→application work의 cancellation/ deadline 전파를 확인한다. 이미 commit된 command는 receipt로 reconcile한다.
  7. 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

  1. operation의 string schema ID가 installed Zod resolver에 있는지 확인한다.
  2. envelope/payload parse와 mapper/domain factory 중 어느 current boundary에서 실패했는지 safe failure/diagnostics로 좁힌다.
  3. raw DTO/value를 출력하지 않고 affected query cache write를 확인한다.
  4. current registry에는 semantic fingerprint/provenance/typed mapper Result가 없으므로 이 값을 비교했다고 기록하지 않는다.
  5. frontend release/runtime config/manifest의 current string contract coherence를 확인하고 known-good coherent release로 rollback한다.

10.2 Target v2 composed 이후

  1. operation → schema ID/fingerprint → mapper ID/version binding을 확인한다.
  2. source artifact/generated output/runtime codec digest를 비교한다.
  3. missing/null/enum/numeric/time/unknown-field change를 classification한다.
  4. request strict와 response strip/reject 방향 정책을 확인한다.
  5. provider encoded-transfer와 browser decoded-byte owner를 분리하고, item/depth/node/string admission ceiling을 확인한다.
  6. mapper expected semantic failure가 throw/UNKNOWN_FAILURE로 소실되지 않았는지 확인한다.
  7. cache write와 partial collection이 0인지 확인한다.
  8. raw validation value/path/DTO를 log에 남기지 않는다.
  9. incompatible schema/mapper/query cache epoch를 coherent set으로 rollback/clear한다.

11. Server State Cache incident

11.0 Current v1 available checks

  1. Query retry가 꺼져 있는지, 전역 stale/gc, AbortSignal과 영향받은 query의 cancel/invalidate/local clear를 확인한다.
  2. current arbitrary key/canonicalize와 hook-local pending Promise를 관측하고 collision/incorrect join cohort cache를 clear한다.
  3. current whole-snapshot optimistic rollback이 다른 commit을 덮었는지 backend authoritative state로 reconcile한다.
  4. strict key/identity token, cursor page와 optimistic layer CAS는 아직 없으므로 해당 fixture/control이 실행됐다고 기록하지 않는다.
  5. 필요하면 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

  1. VD-13 frozen scope projection과 runtime generation을 확인한다.
  2. account/logout/release switch 전 query를 cancel했는지 확인한다.
  3. late response/mapper/cache write fence를 확인한다.
  4. raw account/resource ID를 key에서 찾거나 출력하지 않는다.
  5. current runtime cache를 clear/remount하고 backend authoritative data를 refetch한다.

11.2 Query key collision — target v2

  1. arbitrary key API가 남아 있는지 확인한다.
  2. undefined/NaN/Date/class/accessor/cycle/sparse/oversize fixture를 실행한다.
  3. collision 가능 cohort의 cache를 clear한다.
  4. strict key codec/profile 없는 신규 query traffic을 닫는다.
  5. URL/document/protobuf serialization을 key로 급히 넣지 않는다.

11.3 Mutation ordering/rollback — target v2

  1. join/reject를 검증된 semantic input 전체의 runtime-private 정확한 동일성(exact equality)과 identity token이 아니라 hook instance로 판정했는지 확인한다.
  2. JOIN_IDENTICAL | REJECT_DUPLICATE | ALLOW_INDEPENDENT 결과와 fetch/Promise 횟수가 profile대로인지 확인한다.
  3. runtime/scope coordinator에서 same logical key의 two-hook/out-of-order execution을 확인한다.
  4. whole snapshot rollback이 다른 committed mutation을 덮었는지 확인한다.
  5. 자기 optimistic layer만 base cache revision CAS로 제거/역적용했는지 확인한다.
  6. CAS miss/unknown effect에서는 다른 commit을 보존하고 invalidate/refetch한다.
  7. optimistic update를 끄고 authoritative pending/refetch UX로 downgrade한다.
  8. server commit 뒤 invalidation failure는 command failure로 바꾸지 않는다.

11.4 Cache size/pagination — target v2

  1. result/page/item/estimated-byte cap을 확인한다.
  2. identity intern entry/total canonical bytes/active lease와 GC/terminal release leak를 확인한다. token/canonical bytes 자체는 출력하지 않는다.
  3. unbounded collection/stream history를 cancel/evict한다.
  4. binary/generated DTO를 cache value로 넣지 않았는지 확인한다.
  5. 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 최종 status source 누락·충돌, 깨진 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. 관련 문서