- 결정 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>
95 lines
4.3 KiB
Markdown
95 lines
4.3 KiB
Markdown
# 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.
|