Files
clean-architecture-backend-…/docs/runbooks/grpc-advanced-capabilities.md
T
donghyeon-kaandClaude Opus 5.5 27f23add08 review-followup Wave 3: 설정 prefix app.* 통일(P20), Wave 3 종료
- 결정 16: `ca-skeleton.*`·`backend.graphql` 등 → `app.*`(APP_* env 키 이름 유지), selector 키 상수 하나(`CapabilitySelectors`),
  바인딩만 되던 `streaming-idle` 삭제
- `StrictSettingsBinder`가 env 오타까지 거부 — 모든 capability(graphql·websocket·mongo는 edge 제약으로 파일만 strict),
  httpclient 리플렉션 `HttpClientEnvironmentKeys` 삭제
- persistence-jpa가 `APP_DATASOURCE_PASSWORD` secret 요구를 기여(bootstrap이 JPA 스위치를 읽지 않음), Redis ACL fixture에서 pub/sub 권한 제거
- 결함 수정: SMTP 설정 env 이름 충돌(P20-new-1), `bindExcept`가 system env까지 filter(P20-new-2), graphql 빈 deployment-mode 메시지(P20-new-6)
- 통합: P30과 충돌 11건(P30의 명시적 bean 구조 유지), P30 코드의 옛 키를 app.*로, persistence-jpa 포맷
- 현황표: 소유자 결정 36(persistence-jpa 설정은 플랫폼 키만 app.persistence-jpa.*로, 공유 기능 트리 예외), 재개 문서에 일시 정지 상태

Wave 3 종료 검증: check · ci verifyDependencyLocks --warning-mode=fail(714 task) · mainCheck · architectureCheck
verifyPublicPathSnapshot :app-bootstrap:verifyEnvKeys configContractCheck · :app-bootstrap:integrationTest
:sample-portfolio:integrationTest :sample-portfolio:systemTest · integrationCheck · -p build-logic test ·
-p optional-platforms ci · :app-bootstrap:qualificationBootJar releaseCheck 통과

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-29 17:01:54 +09:00

4.3 KiB

Runbook: gRPC advanced capabilities

Scope: the :grpc-advanced:* family. Everything here is off by default and stays off until a deployment names it. Nothing in this family ships in a runtime composition today.

Flags are app.grpc.advanced.<capability>.enabled. GrpcAdvancedCapability owns the list of capability names; GrpcAdvancedSupportMatrix owns their current grades.


A capability refuses to start

GrpcAdvancedModuleGuard gives three different refusals, and the remedy differs:

Message contains Meaning Remedy
"its feature flag is not set" Nobody enabled it Set the property named in the message
"tracked rather than implemented" Grade is WATCH Nothing to do here; the capability is not implemented
"uncharacterised failure modes" Grade is EXPERIMENTAL and this is production Record a production approval, or run it outside production

The refusal message always names the property key, so the first case is a configuration line rather than a support question.


xDS: the control plane went away

What you are seeing. The control plane is unreachable and clients are still routing.

What it means. GrpcXdsFailurePolicy serves the last-known-good snapshot, up to its staleness bound.

What to do.

  1. Check the snapshot's age. SERVE_LAST_KNOWN_GOOD is the healthy degraded state.
  2. STALE_BEYOND_BOUND means the snapshot is older than the policy allows and is no longer trusted. Beyond that bound, a decommissioned backend would otherwise keep receiving traffic indefinitely.
  3. NO_SNAPSHOT_YET on a starting instance means it never reached the control plane. It fails after the initial fetch timeout rather than starting with no routing.

Do not add application-level retry policy while xDS is enabled. GrpcXdsProfile refuses an APPLICATION retry owner, because retry defined in two places has a winner that depends on resolution order rather than on a decision.


gRPC-Web: a browser call hangs and then fails with no status

Almost always the proxy. A gRPC status arrives as a trailer, and a browser cannot read a trailer the proxy did not expose. Check that the proxy's CORS expose_headers includes grpc-status and grpc-message; GrpcWebProxyContract.violations reports exactly this, and the reference configuration in envoy/envoy.yaml shows it in place.

If the method is client- or bidirectional-streaming, it cannot work over gRPC-Web at all — a browser has no way to send a stream of messages. GrpcWebRpcSupport.require refuses such a method.


Servlet: a transport setting appears to be ignored

It is ignored. The container owns the socket, so keepalive tuning, maximum connection age and flow-control window tuning belong to it. This repository has no Servlet transport code that would refuse them, so configure them on the container.

A Servlet run never substitutes for Netty certification.


Hedging: backend load doubled

Expected, within a bound. Hedging trades duplicate load for tail latency. GrpcHedgingResult records both duplicateBackendCalls and cancelledLoserAttempts; a dashboard showing only the latency improvement makes the trade look free.

What to check. GrpcHedgingBudget caps hedges as a fraction of completed calls. If duplicate load is above that fraction, the budget is not being consumed — which means something is issuing hedges outside the coordinator.

Hedging is refused for anything but a read-only unary method. A hedged mutation runs twice by design, and an idempotency key does not help: the second attempt duplicates a success in progress rather than retrying a failure.


Promoting a capability

Promotion to ADVANCED_STABLE needs compatibility evidence, a security review, fault evidence, performance evidence, an ADR, a runbook, a real-environment test and seven days of soak. A Stable default needs thirty. Promotions are independent: promoting one capability changes no other's grade. This is a review checklist; the in-code GrpcAdvancedPromotionGate that restated it was removed (review 2026-09-24 S5-lead-4) because nothing but its own test called it.

Before citing a suite as evidence, check that it ran against the real infrastructure it needs (proxy, container, control plane or toolchain). A suite that ran without it passed and established nothing.