Files
grpc-library/docs/runbooks/grpc-advanced-capabilities.md
T
donghyeon-kaandClaude Opus 5.5 ee4b243fe0 review-followup Wave 3 라운드 1(P16): 빌드 게이트 정리 — JPA evidence manifest 폐기, build-tools 제거, API surface를 leaf check로
- 결정 4: JPA evidence·qualification manifest 폐기 → persistence-jpa 테스트, build-tools included build 비움(verifyEnvKeys는
  app-bootstrap 태스크, 구현은 build-logic `ca.config-contract`), gRPC release gate 삭제
- 결정 20: API surface 검사를 leaf `check`로, JPA adopter 검사를 `ca.api-surface`로 합침(구현 하나)
- 레인 단계 정리(문서 대조 레인은 `mainStage()`), integrationCheck가 입력 없는 레인을 이름과 함께 제외 → 로컬 통과(NEW-16)
- release workflow 통합, releaseCheck는 tag 전용, build-logic 비핵심 플러그인 정리, sample을 ArchUnit 대상에
- 보류 4행(B3 변경 모듈만 실행, C 이미지 서명, messaging 카드 검증 이동 2행 — 결정 필요), 남음 2행(O3-5 나머지)
- 통합: P17이 옮긴 gRPC release gate 사본 삭제, `grpc-proto-buf`를 release-gate needs에(P17-new-3)

검증: ./gradlew ci verifyDependencyLocks --warning-mode=fail 통과(685 task), mainCheck 통과(268 task),
-p optional-platforms ci 통과, -p build-logic test 78건 통과(손상된 TestKit 캐시 삭제 후)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-28 16:44:17 +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 ca-skeleton.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.