Merge pull request 'docs!: 번역 네 묶음을 합치고 문서 검사 장치를 마무리한다' (#3) from claude/i2-docs-merge-02df15 into main

This commit is contained in:
2026-11-07 11:45:21 +00:00
14 changed files with 587 additions and 693 deletions
+6 -6
View File
@@ -1,13 +1,13 @@
# Optional gRPC platforms # optional gRPC 플랫폼
The default application does not depend on `grpc/*` or `grpc-advanced/*`, so those projects (the 기본 애플리케이션은 `grpc/*`나 `grpc-advanced/*`에 의존하지 않는다. 그래서 이 프로젝트들(registry에서
registry entries with `"build": "optional-grpc"`) are kept out of the main multi-project build. This build preserves their existing project paths and `"build": "optional-grpc"`인 항목)은 주 멀티 프로젝트 빌드에서 뺀다. 이 빌드는 그 프로젝트들의 원래
internal project dependencies while making their configuration opt-in. 프로젝트 경로와 내부 프로젝트 의존을 그대로 두면서, 그 설정을 고를 때만 켜지게 한다.
```bash ```bash
./gradlew -p platforms/optional-build ci ./gradlew -p platforms/optional-build ci
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcInProcessContractTest ./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcInProcessContractTest
``` ```
`adapter:inbound:grpc` remains in the main application build because it is an application adapter; `adapter:inbound:grpc`는 애플리케이션 어댑터라서 주 애플리케이션 빌드에 남는다. 다시 쓰는 gRPC
the reusable gRPC platform libraries are optional capability code and live here. 플랫폼 라이브러리는 optional capability 코드이고 여기 있다.
@@ -7,58 +7,51 @@
- 현재 정본: `docs/compatibility/grpc-support-matrix.md` - 현재 정본: `docs/compatibility/grpc-support-matrix.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-GRPC-001: The gRPC platform ships as a registered family, not as one adapter leaf # ADR-GRPC-001: gRPC 플랫폼은 adapter leaf 하나가 아니라 등록된 family로 싣는다
- Status: accepted - 상태: 채택
- Date: 2026-08-30 - 날짜: 2026-08-30
- Scope: `:grpc:*`, `:grpc-advanced:*`, `src/config/architecture/modules.json` - 범위: `:grpc:*`, `:grpc-advanced:*`, `src/config/architecture/modules.json`
## Context ## 배경
The two source plans describe a type-safe gRPC execution platform with its own API, SPI, adapters and 두 원본 계획은 자기 API, SPI, 어댑터, 조립 루트를 가진 타입 안전 gRPC 실행 플랫폼을 설명한다: `modules/grpc` 아래
composition root: fifteen Stable modules under `modules/grpc` and sixteen Advanced ones under Stable 모듈 열다섯과 `modules/grpc-advanced` 아래 Advanced 모듈 열여섯, Gradle Kotlin DSL, 패키지
`modules/grpc-advanced`, on Gradle Kotlin DSL, in package `io.backend.skeleton.grpc`, against `io.backend.skeleton.grpc`, Spring Boot 4.1 기준.
Spring Boot 4.1.
None of that layout exists here. This repository uses Groovy DSL, a fail-closed module registry that 그 배치는 여기 하나도 없다. 이 저장소는 Groovy DSL, leaf 목록을 가진 실패하면 닫히는 모듈 registry, 패키지 루트
owns the leaf list, package root `dev.caskeleton`, and Spring Boot 4.0.8. The plans anticipate this: `dev.caskeleton`, Spring Boot 4.0.8을 쓴다. 계획은 이것을 예상한다: 마지막 Global Constraint가, 저장소 구조가 다르면
their last Global Constraint says that when the repository structure differs, file paths are remapped 파일 경로를 다시 대응시키고 공개 계약·불변식·시험의 뜻은 바꾸지 않는다고 말한다.
and the public contracts, invariants and test meanings are not changed.
Two shapes were available. Fold the platform into the existing `:adapter:inbound:grpc` leaf as 고를 수 있는 모양은 둘이었다. 플랫폼을 기존 `:adapter:inbound:grpc` leaf에 패키지로 접어 넣기 — JPA, GraphQL,
packages — which is what the JPA, GraphQL, WebSocket and HTTP platforms did here — or register it as WebSocket, HTTP 플랫폼이 여기서 그렇게 했다 — 또는 `messaging:*`를 등록한 방식대로 family로 등록하기.
a family the way `messaging:*` is registered.
## Decision ## 결정
Register it as a family: twelve Stable leaves under `src/grpc/` and six Advanced ones under family로 등록한다: `src/grpc/` 아래 Stable leaf 열둘과 `src/grpc-advanced/` 아래 Advanced leaf 여섯.
`src/grpc-advanced/`.
The deciding property is that this is not a layer of this application. Root `CLAUDE.md` already 결정을 가른 성질은 이것이 이 애플리케이션의 계층이 아니라는 점이다. 루트 `CLAUDE.md`는 이미 `messaging:*`를 "a
describes `messaging:*` as "a vendored messaging platform: a product with its own API, SPI, adapters vendored messaging platform: a product with its own API, SPI, adapters and composition boundary, not a layer of this
and composition boundary, not a layer of this application", and the gRPC platform is the same shape application"(들여온 메시징 플랫폼: 자기 API, SPI, 어댑터, 조립 경계를 가진 제품이고 이 애플리케이션의 계층이
for the same reason — the application is meant to reach it the way it reaches a library, through an 아니다)이라고 설명하고, gRPC 플랫폼은 같은 이유로 같은 모양이다 — 애플리케이션은 라이브러리에 닿듯, 애플리케이션이
application-owned port. The four platforms that became packages are all layers of this application; 가진 포트를 거쳐 그것에 닿아야 한다. 패키지가 된 네 플랫폼은 모두 이 애플리케이션의 계층이다. 이것은 아니다.
this one is not.
The split between `src/grpc/` and `src/grpc-advanced/` is not organisational. The Stable plan `src/grpc/`와 `src/grpc-advanced/`의 분리는 정리용이 아니다. Stable 계획은 Stable starter의 빌드가 Advanced 모듈에
requires that the Stable starter's build fail if it reaches an Advanced module, and separate Gradle 닿으면 실패해야 한다고 요구하고, Gradle 경로 접두어를 따로 두면 그것이 리뷰 메모가 아니라
path prefixes make that a `verifyCleanArchitectureDependencies` failure rather than a review note: `verifyCleanArchitectureDependencies` 실패가 된다: `grpc-spring-boot-starter`의 registry 항목은 advanced id를 하나도
`grpc-spring-boot-starter`'s registry entry names no advanced id, and it cannot acquire one silently. 대지 않고, 소리 없이 얻을 수도 없다.
## Consequences ## 결과
**The registry grew from 44 leaves to 62.** That is a large registry change, made deliberately and in **registry가 leaf 44개에서 62개로 늘었다.** 큰 registry 변경이고, 일부러 한곳에서 했다. 새 leaf는 모두
one place. Every new leaf is `runtime_memberships: []`, so nothing ships until a second, explicit `runtime_memberships: []`라서, 두 번째로 명시한 결정이 옮기기 전까지 아무것도 실리지 않는다.
decision moves it.
**The advanced boundary is checked twice.** Once by the registry at build time, and once by **advanced 경계는 두 번 검사한다.** 빌드 때 registry가 한 번, 런타임에 `GrpcStableBuildInvariant`가 한 번. fat jar나
`GrpcStableBuildInvariant` at runtime, because a fat jar or a shaded artifact is assembled by shaded artifact는 registry가 보지 못하는 무언가가 조립하기 때문이다.
something the registry never sees.
**Four testkit modules became four test lanes.** The plan's split exists so in-process results cannot **testkit 모듈 넷은 시험 lane 넷이 됐다.** 계획이 나눈 이유는 프로세스 안 결과를 네트워크 결과로 착각하지 못하게
be mistaken for network results; this repository expresses that with `ca.strict-test-lane`, whose 하려는 것이다. 이 저장소는 그것을 `ca.strict-test-lane`으로 나타낸다. 그 lane은 아무것도 찾지 못하면 실패하고,
lanes fail when they discover nothing and never serve an up-to-date result. `GrpcEvidenceGrade` keeps up-to-date 결과를 내주지 않는다. `GrpcEvidenceGrade`가 코드 안에서 같은 규칙을 지키므로, 보고서가 계약 실행을 전송
the same rule inside the code, so a report cannot cite a contract run as transport evidence. 증거로 인용할 수 없다.
**Codegen is not wired.** See ADR-GRPC-002. **codegen은 배선하지 않았다.** ADR-GRPC-002를 본다.
@@ -8,74 +8,65 @@
- 대체됨: `docs/capability-status.md` - 대체됨: `docs/capability-status.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-GRPC-002: Schema governance runs without protoc and without the Buf CLI # ADR-GRPC-002: schema 관리는 protoc 없이, Buf CLI 없이 돈다
- Status: **superseded (2026-09-28)** by owner decision 18 of the 2026-09-25 review follow-up - 상태: **대체됨(2026-09-28)** — 2026-09-25 리뷰 후속의 소유자 결정 18
- Date: 2026-08-30 - 날짜: 2026-08-30
- Scope: `:grpc:grpc-proto-contract`, `:grpc:grpc-codegen` (both removed) - 범위: `:grpc:grpc-proto-contract`, `:grpc:grpc-codegen`(둘 다 지움)
> **Superseded.** The regex `.proto` validator and the Java re-implementation of Buf's rules were > **대체됨.** 정규식 `.proto` 검증기와 Buf 규칙의 Java 재구현은 지웠다. schema는 이제 `:grpc:grpc-contract`
> deleted. The schema now lives in `:grpc:grpc-contract` (`src/grpc/grpc-contract/src/main/proto`), > (`src/grpc/grpc-contract/src/main/proto`)에 있고 Gradle protobuf 플러그인(`com.google.protobuf`, 버전은
> compiled by the Gradle protobuf plugin (`com.google.protobuf`, version pinned in > `src/gradle/libs.versions.toml`에 고정. protoc와 protobuf-java runtime은 둘 다 `protobufGrpc`)이 컴파일한다. 생성된
> `src/gradle/libs.versions.toml`; protoc and the protobuf-java runtime are both `protobufGrpc`). > 소스는 그 leaf에서만 Spotless, Checkstyle, Error Prone에서 뺀다. `buf lint`와 `buf breaking`
> Generated sources are excluded from Spotless, Checkstyle and Error Prone in that leaf only. > (`src/grpc/grpc-contract/buf.yaml`, STANDARD lint, FILE breaking)은 CI의 `.github/workflows/ci-quality-gates.yml`
> `buf lint` and `buf breaking` (`src/grpc/grpc-contract/buf.yaml`, STANDARD lint, FILE breaking) > job `grpc-proto-buf`에서 돈다. proto organization은 `caskeleton`이다(예전에는 `hyeonworks`). 아래 글은 원래 결정의
> run in CI, job `grpc-proto-buf` in `.github/workflows/ci-quality-gates.yml`. The proto organization > 기록으로 남긴다.
> is `caskeleton` (was `hyeonworks`). The text below is kept as the record of the original decision.
## Context ## 배경
Stable Tasks 8 through 11 require proto style rules, Buf format/lint/breaking governance, a single Stable Task 8부터 11은 proto 문체 규칙, Buf format·lint·breaking 관리, Java codegen 소유자 하나, 그리고 쓰는 쪽
Java codegen owner, and a descriptor artifact whose consumer-compile result gates a release. 컴파일 결과가 릴리스를 막는 descriptor artifact를 요구한다.
Two of the tools those tasks name are absent from this toolchain. The Buf CLI is not installed. And 그 Task가 이름을 대는 도구 중 둘이 이 toolchain에 없다. Buf CLI는 설치돼 있지 않다. 그리고 `protoc`는 Gradle
`protoc` is available through the Gradle protobuf plugin, but every leaf in this repository passes protobuf 플러그인으로 쓸 수 있지만, 이 저장소의 모든 leaf는 google-java-format을 쓴 spotless, checkstyle, HIGH
spotless with google-java-format, checkstyle, SpotBugs at HIGH confidence, Error Prone and `-Werror` confidence의 SpotBugs, Error Prone, `-Werror`를 통과하는데 — 생성된 protobuf 소스는 그중 어느 것도 통과하지 못한다.
— and generated protobuf sources pass none of them. Turning codegen on means excluding a source set codegen을 켜면 source set 하나를 품질 게이트 다섯에서 빼야 한다.
from five quality gates.
There is precedent for such an exclusion: the `jmh` source set has `spotbugsJmh` and `checkstyleJmh` 그런 예외에는 선례가 있다: `jmh` source set은 `spotbugsJmh`와 `checkstyleJmh`를 끄고 Error Prone도 끈다. 그러니 빼는
disabled and Error Prone off. So the carve-out is available. It is also a decision about the quality 길은 있다. 하지만 그것은 Task 하나를 위해 leaf의 품질 기준선에 대해 내리는 결정이고, 이 일이 바꾸라고 받은 범위
baseline of a leaf, taken for one task, and outside what this work was asked to change. 밖이다.
`adapter:inbound:grpc` also carries a recorded decision in the opposite direction: its `CLAUDE.md` `adapter:inbound:grpc`에도 반대 방향으로 기록된 결정이 있다: 그 `CLAUDE.md`는 쓰는 기능 모듈이 자기 schema를 가져야
forbids the protobuf plugin and `.proto` in that leaf, on the grounds that a consuming feature module 한다는 이유로 그 leaf에서 protobuf 플러그인과 `.proto`를 금지한다.
should own its schema.
## Decision ## 결정
Commit the `.proto` sources and implement every rule the tasks require as executable Java, with no `.proto` 소스를 커밋하고, Task가 요구하는 모든 규칙을 protoc 실행도 Buf CLI 호출도 없이 실행되는 Java로 구현한다.
protoc run and no Buf CLI invocation.
`GrpcProtoContractValidator` reads `.proto` text and enforces proto3 syntax, the `GrpcProtoContractValidator`는 `.proto` 글을 읽고 다음을 강제한다: proto3 문법, `{organization}.{domain}.v{major}`
`{organization}.{domain}.v{major}` package rule, `java_multiple_files`, a generated Java package 패키지 규칙, `java_multiple_files`, 손으로 쓴 것과 겹치지 않는 생성 Java 패키지, `_UNSPECIFIED` enum 0값, 받은 삭제
disjoint from the hand-written one, `_UNSPECIFIED` enum zero values, `reserved` declarations checked 이력과 대조한 `reserved` 선언, well-known type 허용 목록, map 필드 허용 목록. 자기 시험에서 커밋한 schema에 대고
against a supplied removal history, a well-known-type allowlist and a map-field allowlist. It runs 돌므로, 출하하는 `.proto` 파일은 장식이 아니라 살아 있다.
against the committed schema in its own test, so the shipped `.proto` files are live rather than
decorative.
`GrpcBufPolicy` fixes the breaking gate at Buf's `FILE` category and names the four lifecycle stages `GrpcBufPolicy`는 breaking gate를 Buf의 `FILE` category로 고정하고, 규칙을 따르는 pipeline이 등록하는 lifecycle 단계
a compliant pipeline registers. `GrpcCodegenManifest` fixes one codegen owner and refuses a literal 넷을 이름으로 댄다. `GrpcCodegenManifest`는 codegen 소유자를 하나로 고정하고 리터럴 생성기 버전을 거절한다.
generator version. `GrpcDescriptorArtifact`, `GrpcConsumerFixture` and `GrpcSchemaArtifactPublisher` `GrpcDescriptorArtifact`, `GrpcConsumerFixture`, `GrpcSchemaArtifactPublisher`는 schema hash, descriptor digest, 쓰는
carry the schema hash, the descriptor digest and the per-consumer source-break report, and refuse a 쪽별 소스 깨짐 보고를 싣고, 쓰는 쪽을 깨뜨리는 게시나 이미 릴리스한 버전을 다른 바이트로 다시 게시하는 것을
publish that breaks a consumer or republishes a released version with different bytes. 거절한다.
The committed `buf.yaml` states the same rules, so running the CLI in an environment that has it 커밋한 `buf.yaml`도 같은 규칙을 적으므로, CLI가 있는 환경에서 돌리면 같은 판정에 닿는다.
reaches the same verdict.
## Consequences ## 결과
**The invariants are enforced; the process is not run.** Everything Tasks 8 to 11 are about — which **불변식은 강제하고, 과정은 돌리지 않는다.** Task 8부터 11이 다루는 모든 것 — 어떤 schema 변경을 거절하는지, 어떤
schema changes are refused, which consumer breaks block a release, who owns generation — is a 쓰는 쪽 깨짐이 릴리스를 막는지, 생성을 누가 가지는지 — 이 여기서는 빌드로 검사하는 규칙이다. 빠진 것은 protoc
build-checkable rule here. What is missing is the protoc invocation and the Buf binary. 호출과 Buf 바이너리다.
**Turning codegen on is a bounded change.** `GrpcCodegenManifest.caSkeleton()` already names the **codegen을 켜는 것은 한계 있는 변경이다.** `GrpcCodegenManifest.caSkeleton()`이 이미 실제 플러그인 설정이 만족해야
owner, the managed version source, the build-directory output paths and the disjoint package policy 할 소유자, 관리되는 버전 출처, 빌드 디렉터리 출력 경로, 겹치지 않는 패키지 정책을 이름으로 댄다. 할 일은 source set
that a real plugin configuration has to satisfy. The work is a source-set carve-out and a plugin 예외와 플러그인 블록이지 재설계가 아니다.
block, not a redesign.
**The fixtures use a text codec.** `GrpcTextCodec` gives the testkit a UTF-8 marshaller so the **fixture는 텍스트 codec을 쓴다.** `GrpcTextCodec`이 testkit에 UTF-8 marshaller를 줘서, 프로세스 안 lane과 Netty
in-process and Netty lanes can exercise interceptors, status mapping, metadata limits and stream lane이 생성된 stub 없이 interceptor, status 대응, metadata 한계, stream 순서를 시험할 수 있다. 그 계약은 메시지
sequencing without generated stubs. Those contracts are properties of the platform and the transport, 모양이 아니라 플랫폼과 전송의 성질이므로 바꿔 넣어도 잃는 것이 없다 — 그리고 lane이 codegen이 들어온 뒤가 아니라
not of any message shape, so the substitution costs nothing — and the lanes run today rather than 오늘 돈다.
after codegen lands.
@@ -7,53 +7,48 @@
- 현재 정본: `docs/compatibility/grpc-support-matrix.md` - 현재 정본: `docs/compatibility/grpc-support-matrix.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-GRPC-003: Transport, business and stream evidence are three axes, and none implies another # ADR-GRPC-003: 전송·업무·stream 증거는 세 축이고, 어느 것도 다른 것을 뜻하지 않는다
- Status: accepted - 상태: 채택
- Date: 2026-08-30 - 날짜: 2026-08-30
- Scope: `:grpc:grpc-core-api`, `:grpc:grpc-runtime` (was `grpc-policy`), `:grpc:grpc-testkit` - 범위: `:grpc:grpc-core-api`, `:grpc:grpc-runtime`(예전 `grpc-policy`), `:grpc:grpc-testkit`
## Context ## 배경
A failed RPC produces a status code, and a status code is not an answer to the question the caller 실패한 RPC는 status code를 낸다. 그리고 status code는 호출자가 실제로 가진 질문의 답이 아니다. 변경 요청의
actually has. `DEADLINE_EXCEEDED` on a mutation does not say whether the mutation happened; `DEADLINE_EXCEEDED`는 변경이 일어났는지 말하지 않는다. 요청을 보낸 뒤의 `UNAVAILABLE`은 서버가 그것을 한 번도 보지
`UNAVAILABLE` after the request was sent does not say the server never saw it; response headers 않았다고 말하지 않는다. 응답 header가 도착했다고 트랜잭션이 커밋된 것은 아니다.
arriving does not say a transaction committed.
Every one of those is a place where a plausible inference produces a duplicate write or a lost one, 그 하나하나가 그럴듯한 추론이 중복 쓰기나 잃은 쓰기를 낳는 자리이고, 성공 경로만 시험하는 시험에서는 하나도 보이지
and none of them is visible in a test that only exercises the happy path. 않는다.
## Decision ## 결정
Model what happened as three independent axes, and refuse the inferences between them. 일어난 일을 서로 독립인 세 축으로 모델링하고, 축 사이의 추론을 거절한다.
`GrpcTransportEvidence` records what the client observed on the wire, and distinguishes `NOT_SENT` — `GrpcTransportEvidence`는 client가 wire에서 본 것을 기록하고, `NOT_SENT` — client가 자기 보내기가 실패하는 것을 봤다
the client watched its own send fail — from `UNOBSERVED`, which is every other case where nothing is — 와, 아무것도 모르는 다른 모든 경우인 `UNOBSERVED`를 구별한다. `GrpcBusinessEvidence`는 애플리케이션이 확인한 것을
known. `GrpcBusinessEvidence` records what the application confirmed, with `COMMIT_UNKNOWN` as a real 기록하고, `COMMIT_UNKNOWN`은 자리표시가 아니라 실제 상태다. `GrpcStreamEvidence`는 sealed 계층이고, 비어 있지 않은
state rather than a placeholder. `GrpcStreamEvidence` is a sealed hierarchy whose non-empty cases all 경우는 모두 위치를 싣는다. 마지막 순번 없는 「부분」은 이어 가지도 맞춰 보지도 못하기 때문이다.
carry a position, because "partial" without a last sequence can be neither resumed nor reconciled.
`GrpcExecutionEvidence` holds all three and rejects combinations nobody could have observed: a unary `GrpcExecutionEvidence`는 셋을 모두 가지고, 아무도 볼 수 없었을 조합을 거절한다: stream 증거가 있는 unary 호출, 또는
call with stream evidence, or a request the client watched fail to send that nonetheless carries client가 보내기 실패를 봤는데도 업무 증거를 실은 요청. 응답 header를 확인된 커밋으로 올리는 것은
business evidence. Promoting response headers to a confirmed commit is possible only by editing `withResponseHeadersSeen`을 고쳐야만 할 수 있다. 그것은 interceptor 안의 그럴듯한 한 줄이 아니라 메서드 하나다.
`withResponseHeadersSeen`, which is one method rather than a plausible line in an interceptor.
`GrpcCompletionOutcome.forMutation` derives what a caller may conclude, and defaults `GrpcCompletionOutcome.forMutation`이 호출자가 결론 내릴 수 있는 것을 끌어내고, 변경 요청의 `DEADLINE_EXCEEDED`와
`DEADLINE_EXCEEDED` and post-send `UNAVAILABLE` on a mutation to `COMPLETION_UNKNOWN`. 보낸 뒤의 `UNAVAILABLE`을 기본으로 `COMPLETION_UNKNOWN`으로 둔다.
The same types are used by the failure model and by the observation convention, so an incident has 실패 모델과 관측 규약이 같은 타입을 쓰므로, 사고 때 호출 하나에 대한 설명이 둘이 아니라 하나다.
one account of a call rather than two.
## Consequences ## 결과
**A whole class of retry bug becomes unrepresentable.** `GrpcRetryEligibility` reads all three axes **재시도 결함의 한 종류를 아예 나타낼 수 없게 된다.** `GrpcRetryEligibility`는 세 축 모두와 멱등성 profile을 읽는다.
plus the idempotency profile; a caller cannot reach "retry" from a status alone because the status status만으로는 입력이 아니므로, 호출자는 status만 보고 「재시도」에 닿을 수 없다.
alone is not an input.
**The fault lane has something to check.** `GrpcTransportEvidenceClassifier` turns a client's **장애 lane에 검사할 것이 생긴다.** `GrpcTransportEvidenceClassifier`가 client의 관찰을 증거로 바꾸고, 관찰하지 않은
observations into evidence and refuses to infer `NOT_SENT` from an unobserved state — and the lane 상태에서 `NOT_SENT`를 추론하기를 거절한다 — 그리고 lane은 mock이 아니라 호출 중간에 끊은 실제 연결에 대고 그것을
exercises it against a real connection dropped mid-call, not against a mock. 시험한다.
**Callers must handle a third outcome.** `COMPLETION_UNKNOWN` is not a failure and not a success, and **호출자는 세 번째 결과를 다뤄야 한다.** `COMPLETION_UNKNOWN`은 실패도 성공도 아니고, 둘 중 하나로 다루는 호출자는
a caller that treats it as either is wrong. `GrpcOperationStatusQuery` and `GrpcCompletionReconciler` 틀렸다. `GrpcOperationStatusQuery`와 `GrpcCompletionReconciler`는 그것을 푸는 일이 호출자에게 맡긴 숙제가 아니라
exist so that resolving it is a supported path rather than an exercise for the caller. 지원하는 경로가 되게 하려고 있다.
@@ -7,129 +7,106 @@
- 현재 정본: `docs/compatibility/grpc-support-matrix.md` - 현재 정본: `docs/compatibility/grpc-support-matrix.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-GRPC-004: One retry owner, and keyed mutations need a durable ledger # ADR-GRPC-004: 재시도 소유자는 하나이고, 키가 있는 변경에는 durable 원장이 필요하다
- Status: accepted - 상태: 채택
- Date: 2026-08-30 - 날짜: 2026-08-30
- Scope: `:grpc:grpc-runtime` (was `grpc-policy`), `:grpc:grpc-operation-ledger-jpa`, `:grpc:grpc-core-api` - 범위: `:grpc:grpc-runtime`(예전 `grpc-policy`), `:grpc:grpc-operation-ledger-jpa`, `:grpc:grpc-core-api`
## Context ## 배경
Three layers can retry a gRPC call: the application, the channel's service config, and a service gRPC 호출을 재시도할 수 있는 계층이 셋 있다: 애플리케이션, channel의 service config, service mesh. 그 효과는 곱해진다.
mesh. Their effects multiply. Three attempts at each layer is twenty-seven requests for one call, and 계층마다 세 번 시도하면 호출 하나에 요청 스물일곱 개이고, 그 부하는 의존 대상이 이미 실패하고 있을 바로 그때 온다.
the load arrives exactly when the dependency is already failing.
Separately, a mutation that is safe to repeat needs somewhere to record that it ran. Without one, a 따로, 되풀이해도 안전한 변경에는 그것이 돌았다는 기록을 둘 곳이 필요하다. 없으면 응답을 잃은 뒤의 재시도는 효과를
retry after a lost response either duplicates the effect or drops it, and nothing distinguishes the 겹치게 하거나 버리게 되고, 나중에 둘을 구별할 것이 없다.
two afterwards.
## Decision ## 결정
**Exactly one retry owner per channel.** `GrpcRetryOwner` has four values including `NONE`, which is a **channel마다 재시도 소유자는 정확히 하나다.** `GrpcRetryOwner`에는 `NONE`을 포함해 값이 넷 있고, `NONE`은 빠뜨림이
decision rather than an omission. `GrpcServiceConfigPolicy` refuses an in-process retry entry when the 아니라 결정이다. `GrpcServiceConfigPolicy`는 소유자가 mesh이거나 아무도 아닐 때 프로세스 안 재시도 항목을 거절하고,
owner is the mesh or nobody, and `GrpcRetryOwnershipValidator` compares the service config's method `GrpcRetryOwnershipValidator`는 service config의 메서드 이름을 정책 catalog와 대조한다 — 이름이 바뀐 메서드는 그 재시도
names against the policy catalog — a renamed method leaves its retry entry matching nothing, silently, 항목이 소리 없이 아무것과도 맞지 않게 되고, 그 메서드는 channel 기본값으로 돈다.
and the method then runs with channel defaults.
**Retry eligibility reads the method, the evidence and the status together.** **재시도 자격은 메서드, 증거, status를 함께 읽는다.** `GrpcRetryEligibility`는 멱등이 아닌 메서드를 바로 거절하고,
`GrpcRetryEligibility` refuses a non-idempotent method outright, refuses any call whose stream stream이 앞부분을 전달한 호출을 모두 거절하며, 변경 요청의 `DEADLINE_EXCEEDED`나 보낸 뒤의 `UNAVAILABLE`을 재시도가
delivered a prefix, and turns a `DEADLINE_EXCEEDED` or post-send `UNAVAILABLE` mutation into 아니라 「먼저 완료를 풀어라」로 바꾼다.
"resolve the completion first" rather than a retry.
**A keyed mutation is retryable only with both a caller key and a durable ledger.** **키가 있는 변경은 호출자 키와 durable 원장이 둘 다 있을 때만 재시도할 수 있다.** `GrpcOperationLedger`는
`GrpcOperationLedger` is a port in `grpc-core-api`, so the policy layer can require durable `grpc-core-api`의 포트라서, 정책 계층이 데이터베이스에 의존하지 않고 durable 멱등성을 요구할 수 있다. 그 `claim` 계약은
idempotency without depending on a database. Its `claim` contract is a single atomic insert-or-read unique 제약에 대한 원자적 insert-or-read 하나다: `JpaGrpcOperationLedger`는 먼저 insert하고 제약 위반이면 읽는다.
against a unique constraint: `JpaGrpcOperationLedger` inserts first and reads on constraint violation, read-then-insert 구현에는 그것이 닫으려는 경쟁만큼 넓은 창이 있고, 두 시도를 동시에 돌리지 않는 모든 시험을
because a read-then-insert implementation has a window exactly as wide as the race it closes and 통과하기 때문이다.
passes every test that does not run two attempts concurrently.
The identity is caller fingerprint plus full method plus hashed key. All three are load-bearing: identity는 호출자 fingerprint + 전체 메서드 + hash한 키다. 셋 모두 꼭 필요하다: 호출자가 없으면 한 테넌트의 키가 다른
without the caller, one tenant's key suppresses another's write; without the method, a key reused 테넌트의 쓰기를 막는다. 메서드가 없으면 operation 사이에서 다시 쓴 키 때문에 둘째가 첫째의 재생이 된다.
across operations makes the second a replay of the first.
## Consequences ## 결과
**A budget bounds retries as a fraction of traffic.** `GrpcRetryBudget` degrades to roughly no **예산이 재시도를 traffic의 비율로 묶는다.** `GrpcRetryBudget`은 모든 것이 실패할 때 재시도가 거의 없는 쪽으로
retries when everything is failing, which is the behaviour that lets a dependency recover. 떨어진다. 그것이 의존 대상이 회복하게 하는 동작이다.
**The ledger and the mutation should commit together.** `JpaGrpcOperationLedger` carries no **원장과 변경은 함께 커밋해야 한다.** `JpaGrpcOperationLedger`는 일부러 트랜잭션 애너테이션을 달지 않는다:
transaction annotations, deliberately: a `REQUIRES_NEW` would put the claim in its own transaction and `REQUIRES_NEW`는 claim을 자기 트랜잭션에 넣어서, 쓰기는 durable한데 claim은 아닌 창을 다시 들인다.
reintroduce the window where the write is durable and the claim is not.
**A claim expires instead of blocking its key forever** (review 2026-11-01, 03-10). A claim still **claim은 키를 영원히 막지 않고 만료된다**(review 2026-11-01, 03-10). claim TTL이 지난 뒤에도 `IN_PROGRESS`인 claim은
`IN_PROGRESS` after the claim TTL is presumed abandoned by a dead owner, and the next retry of the same 죽은 주인이 버린 것으로 보고, 같은 요청의 다음 재시도가 `GrpcOperationLedger.reclaimStale`로 넘겨받는다 — 조건부
request takes it over with `GrpcOperationLedger.reclaimStale` — one conditional `UPDATE … WHERE state = 'IN_PROGRESS' AND claimed_at < :cutoff` 하나라서, 동시에 넘겨받기 둘이 오면 정확히 하나가 이긴다.
`UPDATE … WHERE state = 'IN_PROGRESS' AND claimed_at < :cutoff`, so of two concurrent takeovers exactly `reclaimFailed`와 같은 모양이다. TTL은 `GrpcIdempotencyInterceptor`의 `claimTtl` 인자이고, 키가 있는 모든 메서드의
one wins, the same shape as `reclaimFailed`. The TTL is the `claimTtl` argument of deadline보다 길지 않으면 만들 때 거절한다. 03-11 후속부터 starter는 `app.grpc.platform.operation-ledger-enabled=true`이면
`GrpcIdempotencyInterceptor`, refused at construction when it is not longer than every keyed method's interceptor를 조립하고 TTL을 `app.grpc.platform.operation-ledger-claim-ttl`(기본 5m)에서 가져온다. 생성자가 거절하는
deadline. Since the 03-11 follow-up the starter assembles the interceptor when TTL은 그 키 이름을 대며 기동을 실패시키고, `GrpcOperationLedger` bean 없이 flag를 켜도 기동이 실패한다.
`app.grpc.platform.operation-ledger-enabled=true` and takes the TTL from
`app.grpc.platform.operation-ledger-claim-ttl` (default 5m); a TTL the constructor refuses fails startup
naming that key, and an enabled flag without a `GrpcOperationLedger` bean fails startup too.
The takeover is safe only because the commit is recorded in the mutation's own transaction: then a 넘겨받기가 안전한 것은 커밋을 변경 자신의 트랜잭션 안에서 기록하기 때문뿐이다: 그러면 아직 `IN_PROGRESS`인 claim은
claim still `IN_PROGRESS` means the mutation never committed. An adopter that commits them separately 변경이 한 번도 커밋되지 않았다는 뜻이다. 둘을 따로 커밋하는 채택자는 버려진 claim을 모르는 결과로 만들고, 넘겨받기가
turns an abandoned claim into an unknown outcome, and a takeover can run the mutation twice. A takeover 변경을 두 번 돌릴 수 있다. 그저 느린 주인을 넘겨받아도 같은 일이 생긴다. 그래서 TTL은 deadline만이 아니라 키가 있는
of an owner that is merely slow does the same, which is why the TTL must exceed the slowest keyed 가장 느린 메서드보다 길어야 한다.
method and not just its deadline.
Rejected: an owner token with a heartbeat lease (the outbox lease model) — needed only when a keyed 버린 것: heartbeat lease를 단 owner token(outbox lease 모델) — 키가 있는 메서드가 어떤 고정 TTL보다 오래 돌 수 있을 때만
method can run longer than any fixed TTL; revisit when one exists. A sweeper job that deletes stale 필요하다. 그런 메서드가 생기면 다시 본다. 낡은 행을 지우는 sweeper job — 이 family에 없는 scheduler가 필요하고,
rows — it needs a scheduler this family does not have, and deleting a claim makes the next retry a claim을 지우면 다음 재시도가 시도를 버렸다는 기록 없는 새 claim이 된다.
fresh claim with no record that an attempt was abandoned.
**A taken-over owner is fenced by a claim token** (re-review 2026-11-03, RR-02-04). The owner a **넘겨받긴 주인은 claim token으로 막는다**(re-review 2026-11-03, RR-02-04). 넘겨받기가 죽었다고 보는 주인은 그저 느릴
takeover presumes dead may only be slow. Without knowing which attempt held the claim, its late 수 있다. 어느 시도가 claim을 쥐었는지 모르면, 그 주인의 늦은 `markFailed`가 새 시도의 claim을 `FAILED_TERMINAL`로
`markFailed` turned the new attempt's claim `FAILED_TERMINAL`, the next retry re-claimed it, and two 만들었고, 다음 재시도가 그것을 다시 claim해서 두 시도가 동시에 변경을 돌렸다. 늦은 `markCommitted`는 새 시도 옆에서
attempts ran the mutation at once; its late `markCommitted` committed beside the new attempt. Every 커밋했다. 이제 모든 claim은 `GrpcClaimToken`(`claim_attempt`, migration V003)을 싣는다: 첫 claim은 1이고,
claim now carries a `GrpcClaimToken` (`claim_attempt`, migration V003): 1 for the first claim, one more `reclaimFailed`나 `reclaimStale`마다 하나씩 늘어난다. `decide`는 `PROCEED`에서 그것을 돌려주고, `recordCommit` /
for each `reclaimFailed` or `reclaimStale`. `decide` returns it on `PROCEED`, and `recordCommit` / `recordFailure`가 그것을 되돌려 준다. 커밋이나 실패는 조건부
`recordFailure` hand it back. A commit or a failure is one conditional `UPDATE … WHERE state = 'IN_PROGRESS' AND claim_attempt = :attempt` 하나다: claim을 잃은 시도의 커밋은 예외로 거절해서
`UPDATE … WHERE state = 'IN_PROGRESS' AND claim_attempt = :attempt`: a commit by an attempt that lost 그 업무 트랜잭션이 롤백되고, 그런 시도의 실패는 무시한다(`markFailed`가 false를 돌려준다). 같은 조건부 update가 JPA
the claim is refused with an exception, so its business transaction rolls back; a failure by one is 커밋 경쟁도 닫는다 — load-check-save에서는 둘 다 `IN_PROGRESS`를 읽은 커밋 둘이 둘 다 썼다. 이제 정확히 하나만 맞는다.
ignored (`markFailed` returns false). The same conditional update closes the JPA commit race — insert와 read 사이에 충돌 행이 지워진 claim은 호출을 실패시키지 않고 insert를 한 번 다시 시도한다.
load-check-save let two commits that both read `IN_PROGRESS` both write; now exactly one matches.
A claim whose conflicting row is purged between insert and read retries the insert once instead of
failing the call.
`release(identity, claimToken)` is fenced the same way (re-review 2026-11-03 round 2, RR-01-15): it is a `release(identity, claimToken)`도 같은 방식으로 막는다(re-review 2026-11-03 round 2, RR-01-15): 조건부
conditional `DELETE … WHERE state = 'IN_PROGRESS' AND claim_attempt = :attempt` and returns whether it `DELETE … WHERE state = 'IN_PROGRESS' AND claim_attempt = :attempt`이고 지웠는지를 돌려준다. 예전에는 키만으로 지웠기
deleted. It used to delete by key alone, so any caller could erase the claim of the attempt that held 때문에, 아무 호출자나 그것을 쥔 시도의 claim이나 재시도가 재생하는 끝난 레코드를 지울 수 있었다. counter는 행 안에
it, or a finished record a retry replays. The counter lives in the row, so a deleted row's key starts 있으므로 지운 행의 키는 다시 attempt 1에서 시작한다: token은 행 하나의 시도들을 가르지, 삭제를 넘는 시도들을 가르지
again at attempt 1: the token separates the attempts of one row, not attempts across a delete. Both 않는다. 그래서 두 삭제를 모두 제한한다 — release는 주인이 사라졌다고 아는 claim에만, purge는 어떤 재시도보다 오래 전에
deletions are limited accordingly — release only for a claim whose owner is known to be gone, purge 끝난 행에만. 버린 것: 포트에서 `release`를 빼기(`markFailed` 뒤 `reclaimFailed`는 counter를 지키지만, 다른 요청을 위해
only for rows finished longer ago than any retry. Rejected: dropping `release` from the port 키를 풀어야 하는 배포에는 다른 길이 없다), counter를 지키는 tombstone 행(지울 두 번째 상태가 생기는데, 그 창은 두 제한이
(`markFailed` then `reclaimFailed` keeps the counter, but a deployment that must free a key for a 이미 닫는다).
different request has no other path), and a tombstone row that keeps the counter (a second state to
purge, for a window the two limits already close).
Chosen over the claim moment as the token (`WHERE claimed_at = :claimedAt`), which needs no column: token으로 claim 시각(`WHERE claimed_at = :claimedAt`)을 쓰는 안보다 이것을 골랐다. 시각은 열이 따로 필요 없지만,
PostgreSQL stores microseconds while `Instant` carries nanoseconds, so the token a caller holds and PostgreSQL은 마이크로초를 저장하고 `Instant`는 나노초를 싣는다. 그래서 호출자가 쥔 token과 저장된 것이 반올림만큼
the one stored can differ by rounding, and two processes' clocks can give two attempts the same 다를 수 있고, 두 프로세스의 시계가 두 시도에 같은 시각을 줄 수 있다. counter에는 두 문제가 다 없다. 위 heartbeat lease는
moment. The counter has neither problem. The heartbeat lease above stays rejected for the same reason 앞과 같은 이유로 계속 버린다. token은 그것 없이 막는다.
as before; the token fences without one.
**What `operation-ledger-enabled=true` promises (03-11 (b), recorded 2026-11-03, RR-02-07).** The **`operation-ledger-enabled=true`가 약속하는 것(03-11 (b), 2026-11-03 기록, RR-02-07).** 2026-11-01 리뷰는 (a) flag를
2026-11-01 review offered (a) delete the flag and judge by whether a ledger bean exists, or (b) keep the 지우고 원장 bean이 있는지로 판단하기와 (b) flag를 두고 starter가 그것으로 판정 함수를 조립하기를 내놓았다. (b)를
flag and have the starter assemble the decision function from it. (b) is kept: the assembly and the 지킨다: 조립과 TTL 검증이 채택자마다가 아니라 한곳에 있다. (a)는 거짓 약속을 없애되 조립까지 함께 없애기 때문에
TTL validation live in one place instead of in every adopter. (a) was rejected because it removes the 버렸다. 한계는 남고, 운영자가 그것을 만나는 곳에 적는다: starter는 서버를 만들지 않으므로 flag는 판정 함수만
false promise only by removing the assembly with it. The limit stays and is stated where an operator 조립하고, 채택자의 `IDEMPOTENCY` 단계 interceptor나 service adapter가 `decide`와 `recordCommit`을 부를 때 비로소 키가
meets it: the starter builds no server, so the flag assembles the decision function only, and keys are 지켜진다. 키가 있는 메서드에 대한 `GrpcPlatformStartupValidator`의 거절이 바로 그것을 말한다. 돌고 있는 프로세스는 그
honoured once the adopter's `IDEMPOTENCY` stage interceptor or service adapter calls `decide` and 단계가 있는지 볼 수 없으니, validator는 그것을 검사한다고 주장하지 않는다.
`recordCommit`. `GrpcPlatformStartupValidator`'s refusal for a keyed method says exactly that; a running
process cannot see whether the stage exists, so the validator does not claim to check it.
**Finished rows are purged after a retention; in-progress rows never are** (03-10 follow-up). **끝난 행은 보존 기간 뒤에 지우고, 진행 중인 행은 절대 지우지 않는다**(03-10 후속).
`GrpcOperationLedger.purgeCompletedBefore(cutoff, limit)` deletes at most `limit` `COMMITTED` or `GrpcOperationLedger.purgeCompletedBefore(cutoff, limit)`는 cutoff 전에 끝난 `COMMITTED`나 `FAILED_TERMINAL` 행을 오래된
`FAILED_TERMINAL` rows that completed before the cutoff, oldest first — on PostgreSQL one bounded 것부터 많아야 `limit`개 지운다 — PostgreSQL에서는 migration V002의 부분 index가 받쳐 주는 한계 있는
`DELETE … WHERE storage_key IN (SELECT … LIMIT … FOR UPDATE SKIP LOCKED)` served by the partial index `DELETE … WHERE storage_key IN (SELECT … LIMIT … FOR UPDATE SKIP LOCKED)` 하나다.
of migration V002. `GrpcOperationLedgerRetention.purgeExpired(now)` applies `GrpcOperationLedgerRetention.purgeExpired(now)`가 `app.grpc.platform.operation-ledger-retention`(기본 24h, HTTP 멱등성
`app.grpc.platform.operation-ledger-retention` (default 24h, the HTTP idempotency replay TTL) in 재생 TTL)을 batch로 적용한다. 레코드가 지워진 뒤의 재시도는 새 claim이고 다시 돈다. 그래서 보존 시간은 호출자의 재시도
batches. A retry after its record was purged is a fresh claim and runs again, so the retention must 창보다 길어야 한다. 지우기 일정은 채택자가 잡는다. starter는 정책만 조립한다. 예약된 bean은 모든 배포에 scheduler를
exceed the callers' retry window. The adopter schedules the purge; the starter assembles the policy 강요하고, starter는 어느 replica가 돌려야 하는지 알 수 없기 때문이다.
only, because a scheduled bean would force a scheduler onto every deployment and the starter cannot
know which replica should run it.
**A key reused for a different request is a caller error, not a duplicate.** The stored request **다른 요청에 다시 쓴 키는 중복이 아니라 호출자 오류다.** 저장된 요청 fingerprint가 그것을 소리 없이 첫 요청의 답을
fingerprint turns that into `FAILED_PRECONDITION` rather than silently returning the first request's 돌려주는 대신 `FAILED_PRECONDITION`으로 바꾼다.
answer.
@@ -7,53 +7,46 @@
- 현재 정본: `docs/compatibility/grpc-support-matrix.md` - 현재 정본: `docs/compatibility/grpc-support-matrix.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-GRPC-005: One writer per stream, a bounded queue, and resume that refuses to guess # ADR-GRPC-005: stream마다 쓰는 쪽 하나, 한계 있는 queue, 짐작하기를 거절하는 resume
- Status: accepted - 상태: 채택
- Date: 2026-08-30 - 날짜: 2026-08-30
- Scope: `:grpc:grpc-runtime` (was `grpc-policy`) - 범위: `:grpc:grpc-runtime`(예전 `grpc-policy`)
## Context ## 배경
`StreamObserver` is not thread-safe, and the failure when two producers call `onNext` concurrently is `StreamObserver`는 thread-safe가 아니다. 두 producer가 동시에 `onNext`를 부를 때의 실패는 예외가 아니다 — 섞인 바이트이고,
not an exception — it is interleaved bytes, which a client decodes as a corrupt message or, worse, as client는 그것을 깨진 메시지로, 더 나쁘게는 받지 말았어야 할 유효한 메시지로 decode한다.
a valid one it should never have received.
Two further properties of server streams are easy to get wrong in ways that look healthy. A consumer server stream에는 건강해 보이는 방식으로 틀리기 쉬운 성질이 둘 더 있다. 뒤처진 소비자는 stream을 끝내거나 메시지를 소리
that falls behind either terminates the stream or silently loses messages, and the second leaves a 없이 잃는데, 둘째는 client에게 멀쩡해 보이지만 변경이 빠진 stream을 남긴다. 그리고 재연결은 서버가 아직 재생할 수 있는
client with a stream that appears fine and is missing changes. And a reconnect either continues from 위치에서 이어 가거나, 더는 없는 것을 건너뛴다.
a position the server can still replay, or skips whatever is no longer there.
## Decision ## 결정
**A bounded queue drained by one writer.** `GrpcSerializedStreamWriter` accepts messages from any **쓰는 쪽 하나가 비우는 한계 있는 queue.** `GrpcSerializedStreamWriter`는 어느 스레드에서든 메시지를 받고, synchronized인
thread and hands them to the transport only from `flush`, which is synchronized. `write` returning `flush`에서만 전송에 넘긴다. `write`가 `ACCEPTED`를 돌려주는 것은 줄 세웠다는 뜻이고, 이름을 일부러 `sent`로 하지
`ACCEPTED` means queued, and the name is deliberately not `sent`: the transport call returns as soon 않았다: 전송 호출은 바이트를 넘기자마자 돌아오므로, 여기 어떤 메서드도 전달을 정직하게 알릴 수 없다.
as bytes are handed over, so no method here can honestly report delivery.
**Both a message bound and a byte bound.** Either alone is unbounded in the other dimension. **메시지 한계와 바이트 한계를 둘 다.** 하나만 두면 다른 차원으로는 한계가 없다. `GrpcFlowControlPolicy`는 전송 자신의
`GrpcFlowControlPolicy` also takes the transport's own readiness signal, because a writer that relies readiness 신호도 받는다. queue 한계에만 기대는 쓰는 쪽은 메모리를 할당할 수 있는 만큼 빨리 만들어 내기 때문이다.
only on its queue bound produces as fast as it can allocate.
**Termination is the default for a slow consumer.** `GrpcSlowConsumerPolicy.DROP_OLDEST` exists for **느린 소비자에게는 끝내기가 기본이다.** `GrpcSlowConsumerPolicy.DROP_OLDEST`는 업무 뜻이 손실을 견디는 feed를 위해
feeds whose business meaning tolerates loss, and is not the default, because a client cannot detect 있고 기본값이 아니다. client는 버려진 메시지를 알아챌 수 없기 때문이다: client가 보는 순번은 보내진 것의 순번이다.
dropped messages: the sequence numbers it sees are the ones it was sent.
**Resume is refused rather than faked.** `GrpcStreamGapDetector` requires a signed, unexpired token **resume은 꾸며 내지 않고 거절한다.** `GrpcStreamGapDetector`는 서명됐고 만료되지 않았으며 호출자·필터 fingerprint가
whose caller and filter fingerprints match the current request, refuses one whose snapshot version 지금 요청과 맞는 token을 요구하고, snapshot version이 움직인 token을 거절하며, cursor가 보존한 이력보다 앞서면
moved, and returns `FULL_RESYNC_REQUIRED` when the cursor predates retained history. `GrpcResumeToken` `FULL_RESYNC_REQUIRED`를 돌려준다. `GrpcResumeToken`은 key id를 싣는다. 그래서 서명 키를 바꿔도 아직 쓰이는 모든 token이
carries a key id so the signing key can rotate without invalidating every outstanding token. 무효가 되지 않는다.
## Consequences ## 결과
**A stream carries an envelope, not a bare payload.** `GrpcStreamEnvelope` holds the stream id, **stream은 맨 payload가 아니라 envelope을 싣는다.** `GrpcStreamEnvelope`은 stream id, generation, 순번, snapshot version,
generation, sequence, snapshot version and resume token, because resume, gap detection and drain all resume token을 가진다. resume, 빈틈 찾기, 비우기가 모두 위치와 generation을 필요로 하기 때문이다.
need a position and a generation.
**Four clocks, not one.** `GrpcStreamLifetimePolicy` separates setup deadline, idle timeout, max **시계는 하나가 아니라 넷이다.** `GrpcStreamLifetimePolicy`는 준비 deadline, idle timeout, 최대 지속 시간, heartbeat
duration and heartbeat interval, and refuses combinations where one can never fire. Merging any pair 간격을 나누고, 하나가 절대 울릴 수 없는 조합을 거절한다. 어느 둘을 합치든 익숙한 결함이 나온다: 최대 지속 시간으로 쓴
produces a familiar bug: an idle timeout used as a max duration kills healthy busy streams. idle timeout은 건강하게 바쁜 stream을 죽인다.
**A heartbeat is a liveness signal and nothing else.** It is not an application acknowledgement and **heartbeat는 살아 있다는 신호이고 그 밖의 무엇도 아니다.** 애플리케이션 확인 응답도 순서 보장도 아니다.
not an ordering guarantee; `GrpcStreamHeartbeat` says so in the place somebody would otherwise reuse `GrpcStreamHeartbeat`가 누가 그것을 다르게 다시 쓸 법한 자리에서 그렇게 말한다.
it.
@@ -7,71 +7,61 @@
- 현재 정본: `docs/compatibility/grpc-support-matrix.md` - 현재 정본: `docs/compatibility/grpc-support-matrix.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-GRPC-006: Stable discovery is DNS and static, and a Kubernetes profile names who balances # ADR-GRPC-006: Stable discovery는 DNS와 static이고, Kubernetes profile은 누가 분산하는지 이름으로 댄다
- Status: accepted - 상태: 채택
- Date: 2026-08-31 - 날짜: 2026-08-31
- Scope: `:grpc:grpc-runtime` (was `grpc-discovery`, `grpc-client`) - 범위: `:grpc:grpc-runtime`(예전 `grpc-discovery`, `grpc-client`)
## Context ## 배경
A gRPC channel's discovery configuration has a failure mode with no runtime symptom: it works, and gRPC channel의 discovery 설정에는 런타임 증상이 없는 실패 방식이 있다: 동작은 하는데, 대시보드가 말하는 일을 하지 않는다.
it does not do what the dashboard says it does.
The specific case is `round_robin` over a Kubernetes Service ClusterIP. The Service is one virtual 구체적인 경우는 Kubernetes Service ClusterIP 위의 `round_robin`이다. Service는 가상 주소 하나라서 resolver가 endpoint 하나를
address, so the resolver returns one endpoint and the client-side balancer has nothing to rotate 돌려주고 client 쪽 분산기는 돌려 가며 보낼 대상이 없다. kube-proxy는 연결할 때 pod를 고르고, HTTP/2 연결은 오래 살기
across; kube-proxy picks a pod at connect time, and an HTTP/2 connection is long-lived, so every 때문에, 그 client의 모든 요청이 연결이 사는 동안 같은 pod로 간다. 실패하는 것은 없다. 설정은 `round_robin`이라고 말하고,
request from that client goes to the same pod for the life of the connection. Nothing fails. The metric은 요청이 pod가 아니라 client 사이에 퍼진 것을 보여 주며, 「client 쪽 부하 분산을 한다」는 결론은 아무도 확인할
configuration says `round_robin`, the metrics show requests spread across clients rather than pods, 계기가 없는 방식으로 틀렸다.
and the conclusion "we have client-side load balancing" is wrong in a way nobody is prompted to
check.
The mirror-image mistake is `pick_first` over a headless record, which pins a client to one pod out 거울상 실수는 headless record 위의 `pick_first`다. 많은 pod 중 하나에 client를 묶는다.
of many.
Separately, a service mesh changes who owns retries, and a deployment that adds mesh routing without 따로, service mesh는 재시도를 누가 가지는지 바꾸고, mesh 라우팅을 더하면서 자기 재시도 정책을 빼지 않은 배포는 효과가
removing its own retry policy has two retriers whose effects multiply. 곱해지는 재시도자 둘을 가진다.
## Decision ## 결정
**Stable resolvers are Static, DNS and Unix domain socket; Stable load balancing is `pick_first` and **Stable resolver는 Static, DNS, Unix domain socket이고, Stable 부하 분산은 `pick_first`와 `round_robin`이다.**
`round_robin`.** `GrpcDiscoveryPolicyValidator.requireStableScheme` refuses `xds`, `consul`, `etcd` `GrpcDiscoveryPolicyValidator.requireStableScheme`은 `xds`, `consul`, `etcd`, `eureka`를 이름으로 거절하고, 그것이 모르는
and `eureka` by name, with a message saying they are Advanced capabilities with their own control scheme이 아니라 자기 control plane과 승격 gate를 가진 Advanced capability라고 메시지로 말한다.
plane and promotion gate rather than unknown schemes.
**The pairing is checked against the resolved address count, not against intent.** **짝 맞춤은 의도가 아니라 해석된 주소 수와 대조한다.** `GrpcResolverProfile`은 `expectedAddressCount`를 싣고,
`GrpcResolverProfile` carries `expectedAddressCount`, and `GrpcStableLoadBalancer.effective` answers `GrpcStableLoadBalancer.effective`가 그 수의 endpoint 위에서 정책이 무언가를 분산하는지 답한다. 주소 하나 위의
whether the policy distributes anything over that many endpoints. A `round_robin` profile over one `round_robin` profile은 보고되는 위반이고, 그 메시지는 그것이 일어나지 않는 퍼뜨리기를 설명한다고 말한다.
address is a reported violation whose message says it describes spreading that is not happening.
**A Kubernetes deployment names its routing mode**, and the mode implies both the balancer and the **Kubernetes 배포는 자기 라우팅 모드를 이름으로 대고**, 그 모드가 분산기와 재시도 소유자를 둘 다 정한다.
retry owner. `GrpcKubernetesRoutingMode` has three values — `K8S_VIP`, `K8S_HEADLESS`, `MESH` — and `GrpcKubernetesRoutingMode`에는 값이 셋 있다 — `K8S_VIP`, `K8S_HEADLESS`, `MESH` — 그리고 `GrpcKubernetesProfile`은 재시도
`GrpcKubernetesProfile` refuses a mesh profile whose retry owner retries in-process. 소유자가 프로세스 안에서 재시도하는 mesh profile을 거절한다.
**A profile that carries long-lived streams must state a reconnect budget and a readiness drain **오래 사는 stream을 싣는 profile은 재연결 예산과 readiness 비우기 유예를 밝혀야 한다.** stream은 사는 내내 client를 pod
grace.** A stream pins a client to one pod for its whole life, so every rollout, eviction and 하나에 묶으므로, 모든 rollout, eviction, scale-down이 그것을 끝낸다. `GrpcKubernetesProfileValidator`는 긴 stream을 싣는
scale-down ends it. `GrpcKubernetesProfileValidator` additionally reports a VIP profile carrying VIP profile과, 재연결 예산보다 짧은 비우기 유예도 알린다 — 후자는 client가 다른 곳으로 재연결을 마치기 전에 pod가 응답을
long streams, and a drain grace shorter than the reconnect budget — the second means the pod stops 멈춘다는 뜻이다.
serving before its clients have finished reconnecting elsewhere.
**A DNS profile must refresh.** `GrpcResolverProfile` refuses a zero refresh interval on DNS, **DNS profile은 새로 고쳐야 한다.** `GrpcResolverProfile`은 DNS에서 새로 고침 간격 0을 거절한다. 기동 때 한 번 해석한
because a channel that resolved once at startup keeps sending to addresses that stopped existing an channel은 한 시간 전에 없어진 주소로 계속 보내고, 그 결과인 `UNAVAILABLE`은 rollout이 끝난 지 한참 뒤에도 건강하지 않은
hour ago, and the resulting `UNAVAILABLE` looks like an unhealthy deployment long after the rollout 배포처럼 보인다.
finished.
## Consequences ## 결과
**Two validators, not one.** `GrpcDiscoveryPolicyValidator` asks whether a balancer does anything **validator는 하나가 아니라 둘이다.** `GrpcDiscoveryPolicyValidator`는 분산기가 자기가 볼 주소 위에서 무언가를 하는지
over the addresses it will see; `GrpcKubernetesProfileValidator` asks whether the deployment shape, 묻는다. `GrpcKubernetesProfileValidator`는 배포 모양, 재시도 소유자, stream 의무가 맞는지 묻는다. 배포는 resolver profile이
the retry owner and the stream obligations agree. A deployment can have a coherent resolver profile 앞뒤가 맞으면서도 재시도를 두 곳에 둘 수 있다. 그래서 둘을 합치면 한 답이 다른 답을 가린다.
and still have put retries in two places, so merging them would let one answer hide the other.
**`expectedAddressCount` has to come from somewhere.** It is a declared number, and a declaration can **`expectedAddressCount`는 어딘가에서 와야 한다.** 선언한 숫자이고, 선언은 틀릴 수 있다. 그래도 아무것도 비교하지 않는
be wrong. It is still better than the alternative, which is not comparing anything: a wrong 대안보다 낫다: 틀린 선언은 누가 적어 둔 틀린 말이고, 빠진 선언은 아무도 묻지 않은 질문이다.
declaration is a wrong statement somebody wrote down, and a missing one is a question nobody asked. `GrpcChannelProfileValidator`는 기동 때 알 수 있는 곳에서는 해석된 수를 받고, 알 수 없는 곳에서는 짐작해서 아직 해석할 수
`GrpcChannelProfileValidator` takes resolved counts where they are known at startup and skips the 없는 이름에서 실패하는 대신 검사를 건너뛴다.
check where they are not, rather than guessing and failing on a name that cannot be resolved yet.
**xDS is reachable, and not by this route.** It lives in `grpc-advanced` (package `resilience`/`xds`) behind its **xDS에는 닿을 수 있지만, 이 길로는 아니다.** xDS는 `grpc-advanced`(패키지 `resilience`/`xds`)에서 자기 capability flag와
capability flag and its production approval, and `GrpcXdsStartupGuard.advertisableAsStableSupport()` 운영 승인 뒤에 있고, `GrpcXdsStartupGuard.advertisableAsStableSupport()`가 false를 돌려주므로 Stable 지원 설명이 조용히
returns false so the Stable support statement cannot widen quietly. See ADR-GRPC-ADV-001. 넓어질 수 없다. ADR-GRPC-ADV-001을 본다.
@@ -7,60 +7,51 @@
- 현재 정본: `docs/compatibility/grpc-advanced-support-matrix.md` - 현재 정본: `docs/compatibility/grpc-advanced-support-matrix.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-GRPC-ADV-001: Each advanced capability has its own flag, its own grade and its own promotion # ADR-GRPC-ADV-001: advanced capability마다 자기 flag, 자기 등급, 자기 승격이 있다
- Status: accepted - 상태: 채택
- Date: 2026-08-30 - 날짜: 2026-08-30
- Scope: `:grpc-advanced:*` - 범위: `:grpc-advanced:*`
## Context ## 배경
The advanced plan covers sixteen capabilities that differ by orders of magnitude in what they bring advanced 계획은 capability 열여섯을 다룬다. 그것들이 함께 가져오는 것은 몇 자릿수씩 다르다. gRPC-Web은 proxy를 더한다.
with them. gRPC-Web adds a proxy. Reactor adds a dependency. xDS adds a control plane, its outage Reactor는 의존 하나를 더한다. xDS는 control plane, 그 장애 방식, 자기 보안 경계, 자기 버전 어긋남을 더한다. hedging은 운영
modes, its own security boundary and its own version skew. Hedging duplicates production traffic. traffic을 겹친다.
Bundling them under one flag makes enabling the cheapest of those the same decision as enabling the 그것들을 flag 하나로 묶으면 가장 싼 것을 켜는 일이 가장 무거운 것을 켜는 일과 같은 결정이 된다.
most consequential.
## Decision ## 결정
**One flag per capability**, under `ca-skeleton.grpc.advanced.<capability>.enabled`, all off by **capability마다 flag 하나.** `ca-skeleton.grpc.advanced.<capability>.enabled` 아래에 있고, 기본은 모두 꺼짐이다.
default.
**Four grades.** `ADVANCED_STABLE` starts on its flag; `EXPERIMENTAL` additionally needs a separate **등급 넷.** `ADVANCED_STABLE`은 flag로 시작한다. `EXPERIMENTAL`은 따로 운영 승인도 필요하다. flag는 누가 그 기능을 원했다는
production approval, because the flag says somebody wanted the feature and the approval says somebody 뜻이고, 승인은 누가 그 장애 방식이 다 밝혀지지 않았음을 받아들였다는 뜻이기 때문이다. `WATCH`는 아예 시작할 수 없다.
accepted that its failure modes are not fully characterised; `WATCH` cannot start at all; `DISABLED` `DISABLED`는 거둬들인 것이다.
is withdrawn.
`GrpcAdvancedModuleGuard` distinguishes the three refusals — flag unset, grade unstartable, `GrpcAdvancedModuleGuard`는 세 거절 — flag 없음, 시작할 수 없는 등급, 운영 승인 없음 — 을 구별한다. 경우마다 고치는 법이
production unapproved — because the remedy differs in each case. 다르기 때문이다.
**Promotion evidence is per capability.** `GrpcAdvancedPromotionEvidence` is one record per **승격 증거는 capability마다다.** `GrpcAdvancedPromotionEvidence`는 capability마다 record 하나라서, 어떤 승격도 다른 것을
capability, so no promotion can drag another along; 끌고 가지 못한다. `GrpcAdvancedPromotionGate.capabilitiesDraggedAlong`은 빈 목록을 돌려주고, 그것은 주장이 아니라 시험한
`GrpcAdvancedPromotionGate.capabilitiesDraggedAlong` returns an empty list, and that is a tested 성질이다. (2026-09-28: gate 클래스는 자기 시험 밖에서 부르는 것이 없어서 지웠다 — review 2026-09-24 S5-lead-4.
property rather than a claim. (2026-09-28: the gate classes were removed because nothing outside capability별 규칙은 `docs/runbooks/grpc-advanced-capabilities.md`의 리뷰 규칙으로 남는다.) 문턱은 둘이다:
their own tests called them — review 2026-09-24 S5-lead-4. The per-capability rule stands as a `ADVANCED_STABLE`에는 7일 soak와 완전한 증거, Stable 기본값에는 30일. 후자는 모든 배포가 그 capability의 의존과 장애 방식을
review rule in `docs/runbooks/grpc-advanced-capabilities.md`.) Two thresholds: seven days of soak plus complete evidence for 받는다는 뜻이기 때문이다.
`ADVANCED_STABLE`, thirty for a Stable default, because the second means every deployment gets the
capability's dependencies and its failure modes.
**Infrastructure is named per capability.** `GrpcAdvancedInfrastructureTestkit` records that **기반 시설은 capability마다 이름으로 댄다.** `GrpcAdvancedInfrastructureTestkit`은 gRPC-Web에는 proxy가, Servlet에는
gRPC-Web needs a proxy, Servlet needs a container, xDS needs a stoppable control plane and Kotlin container가, xDS에는 멈출 수 있는 control plane이, Kotlin에는 toolchain이 필요하다고 적는다. 기반 시설 없이 도는 suite는
needs a toolchain. A suite that runs without its infrastructure passes and establishes nothing, which 통과하고 아무것도 세우지 않는다. 없는 것보다 나쁘다.
is worse than not having one.
## Consequences ## 결과
**The Kotlin adapter fails closed here, and says why.** This repository has no Kotlin toolchain, so **Kotlin 어댑터는 여기서 실패하면 닫히고, 이유를 말한다.** 이 저장소에는 Kotlin toolchain이 없어서
`GrpcKotlinCompatibilityGate.supportableHere()` returns false. The four contract requirements — one `GrpcKotlinCompatibilityGate.supportableHere()`가 false를 돌려준다. 계약 요구 넷 — schema 출처 하나, coroutine 취소 전파,
schema source, coroutine cancellation propagation, Flow backpressure inside the Stable bounds, Stable 한계 안의 Flow backpressure, 플랫폼 증거 타입 보존 — 은 검사할 수 있고 검사한다. 빠진 것은 compile lane뿐이다.
platform evidence types preserved — are checkable and are checked; only the compile lane is missing.
**Edition 2026 cannot be used however its watch report reads.** `GrpcEdition2026Guard` is not **Edition 2026은 그 watch 보고가 무어라 하든 쓸 수 없다.** `GrpcEdition2026Guard`는 보고에 따라 달라지지 않는다. 상태 기록이
conditional on the report, because letting a status record also authorise use means a schema moves 사용까지 허락하게 두면, 누가 필드 넷을 SUPPORTED로 표시하는 순간 schema가 승격 결정도, 쓰는 쪽 옮기기도, ADR도 없이 그
onto an edition the moment somebody marks four fields SUPPORTED, with no promotion decision, no edition으로 옮겨 가기 때문이다.
consumer migration and no ADR.
**xDS is not part of the Stable support statement.** It works, behind its flag and its approval; **xDS는 Stable 지원 설명의 일부가 아니다.** flag와 승인 뒤에서 동작한다. `GrpcXdsStartupGuard.advertisableAsStableSupport()`가
`GrpcXdsStartupGuard.advertisableAsStableSupport()` returns false so a support matrix cannot widen false를 돌려주므로 support matrix가 조용히 넓어질 수 없다.
quietly.
@@ -1,60 +1,55 @@
# gRPC advanced capability support matrix # gRPC advanced capability 지원 매트릭스
Every capability in `:grpc-advanced:*`, its grade, and what it would take to raise it. `:grpc-advanced:*`의 모든 capability, 그 등급, 그리고 등급을 올리는 데 필요한 것이다. 기본 등급의 정본은
`GrpcAdvancedSupportMatrix` is the machine-readable form; `GrpcAdvancedCapability.defaultGrade` `GrpcAdvancedCapability.defaultGrade`다. 근거가 있는 배포는 `GrpcAdvancedFeatureFlags.withGrade`로 바꾼다.
carries the same values.
All capabilities are off by default. Flags are `app.grpc.advanced.<capability>.enabled`. capability는 모두 기본으로 꺼져 있다. 스위치는 `app.grpc.advanced.<capability>.enabled`다.
## Grades ## 등급
| Grade | May start | Production needs a separate approval | | 등급 | 뜰 수 있나 | 운영에 별도 승인이 필요한가 |
| --- | --- | --- | | --- | --- | --- |
| `ADVANCED_STABLE` | Yes | No | | `ADVANCED_STABLE` | 예 | 아니요 |
| `EXPERIMENTAL` | Yes | Yes | | `EXPERIMENTAL` | 예 | 예 |
| `WATCH` | No | — | | `WATCH` | 아니요 | — |
| `DISABLED` | No | — | | `DISABLED` | 아니요 | — |
## Capabilities ## capability
| Capability | Flag | Grade | Real infrastructure its evidence needs | | capability | 스위치 | 등급 | 증거에 필요한 실제 인프라 |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| Protobuf Edition 2024 | `edition-2024` | `ADVANCED_STABLE` | — | | Protobuf Edition 2024 | `edition-2024` | `ADVANCED_STABLE` | — |
| Protobuf Edition 2026 | `edition-2026` | `WATCH` | — | | Protobuf Edition 2026 | `edition-2026` | `WATCH` | — |
| Client streaming | `client-streaming` | `ADVANCED_STABLE` | — | | client streaming | `client-streaming` | `ADVANCED_STABLE` | — |
| Bidirectional streaming | `bidi-streaming` | `ADVANCED_STABLE` | — | | bidirectional streaming | `bidi-streaming` | `ADVANCED_STABLE` | — |
| Manual flow control | `manual-flow-control` | `ADVANCED_STABLE` | — | | 수동 flow control | `manual-flow-control` | `ADVANCED_STABLE` | — |
| Read-only unary hedging | `hedging` | `EXPERIMENTAL` | — | | 읽기 전용 unary hedging | `hedging` | `EXPERIMENTAL` | — |
| Custom name resolver | `custom-resolver` | `ADVANCED_STABLE` | — | | 사용자 정의 name resolver | `custom-resolver` | `ADVANCED_STABLE` | — |
| Custom load balancer | `custom-load-balancer` | `EXPERIMENTAL` | — | | 사용자 정의 load balancer | `custom-load-balancer` | `EXPERIMENTAL` | — |
| Proxyless xDS | `xds` | `EXPERIMENTAL` | xDS control plane | | proxyless xDS | `xds` | `EXPERIMENTAL` | xDS control plane |
| gRPC-Web | `grpc-web` | `ADVANCED_STABLE` | gRPC-Web proxy | | gRPC-Web | `grpc-web` | `ADVANCED_STABLE` | gRPC-Web proxy |
| Servlet HTTP/2 | `servlet-compat` | `ADVANCED_STABLE` (flag only; no Servlet transport code since 2026-09-25) | Servlet container | | Servlet HTTP/2 | `servlet-compat` | `ADVANCED_STABLE`(스위치만 있다. 2026-09-25부터 Servlet 전송 코드가 없다) | Servlet 컨테이너 |
| Spring Integration bridge | `integration-bridge` | `ADVANCED_STABLE` | — | | Spring Integration bridge | `integration-bridge` | `ADVANCED_STABLE` | — |
| Reactor adapter | `reactor` | `ADVANCED_STABLE` | — | | Reactor 어댑터 | `reactor` | `ADVANCED_STABLE` | — |
| Kotlin coroutine / Flow | `kotlin` | `ADVANCED_STABLE` | Kotlin toolchain | | Kotlin coroutine / Flow | `kotlin` | `ADVANCED_STABLE` | Kotlin toolchain |
| Channelz / CSDS diagnostics | `channel-diagnostics` | `ADVANCED_STABLE` | — | | Channelz / CSDS 진단 | `channel-diagnostics` | `ADVANCED_STABLE` | — |
## What the grades mean here, concretely ## 여기서 등급이 구체적으로 뜻하는 것
**Grade is a statement about the contract, not about a deployment.** Every capability's contract is **등급은 배포가 아니라 계약에 대한 말이다.** 모든 capability의 계약은 이 저장소에서 구현되고 시험됐다. 실제 배포에서 나온
implemented and tested in this repository. What no capability has is evidence from a real deployment: 증거는 어느 capability에도 없고, 승격된 것도 없다.
`GrpcAdvancedPromotionEvidence` for each one is empty, and no promotion has been granted.
**Four capabilities cannot produce meaningful evidence here at all**, because the infrastructure they **capability 넷은 여기서 의미 있는 증거를 아예 낼 수 없다.** 필요한 인프라(gRPC-Web proxy, Servlet 컨테이너, xDS control
need is absent (gRPC-Web proxy, Servlet container, xDS control plane, Kotlin toolchain), and a suite plane, Kotlin toolchain)가 없고, 인프라 없이 돈 suite는 통과해도 아무것도 세우지 않기 때문이다.
that runs without its infrastructure passes and establishes nothing.
**Kotlin is the sharpest case.** This repository has no Kotlin toolchain, so Kotlin is not **Kotlin이 가장 날카로운 경우다.** 이 저장소에는 Kotlin toolchain이 없으므로 그것이 생기기 전까지 Kotlin은 여기서 지원할 수
supportable here until one exists. Only the Java-side coroutine cancellation bridge 없다. Java 쪽 coroutine 취소 bridge(`GrpcCoroutineContextBridge`)만 구현되고 시험됐다. 컴파일 lane은 없다.
(`GrpcCoroutineContextBridge`) is implemented and tested; there is no compile lane.
## Promotion thresholds ## 승격 기준
| To | Soak | Also required | | 목표 | soak | 그 밖에 필요한 것 |
| --- | --- | --- | | --- | --- | --- |
| `ADVANCED_STABLE` | 7 days | compatibility evidence, security review, fault evidence, performance evidence, ADR, runbook, real-environment test | | `ADVANCED_STABLE` | 7일 | 호환성 증거, 보안 리뷰, 장애 증거, 성능 증거, ADR, runbook, 실제 환경 시험 |
| Stable default | 30 days | all of the above, plus a dependency, security and operational-cost review | | Stable 기본값 | 30일 | 위의 모두와 의존성·보안·운영 비용 리뷰 |
`WATCH` becomes `EXPERIMENTAL` before anything else. Promotions are independent: promoting one `WATCH`는 무엇보다 먼저 `EXPERIMENTAL`이 된다. 승격은 서로 독립이다. 한 capability를 올려도 다른 것의 등급은 바뀌지 않는다.
capability changes no other's grade.
+48 -51
View File
@@ -1,77 +1,74 @@
# gRPC platform support matrix # gRPC 플랫폼 지원 매트릭스
What the Stable gRPC platform (`:grpc:*`) is certified against, what it is only checked against, and Stable gRPC 플랫폼(`:grpc:*`)이 무엇에 대해 인증됐고, 무엇에 대해서는 확인만 하고, 무엇은 지켜보기만 하는지다. 그 구별이
what is merely watched. The distinction is the point: "works with Spring Boot" is not a statement 요점이다. 「Spring Boot와 동작한다」는 누구도 행동에 옮길 수 없는 말이다.
anyone can act on.
The release gate is the `grpc-stable-release-gate` job in `.github/workflows/release.yml`: each 릴리스 gate는 `.github/workflows/release.yml`의 `grpc-stable-release-gate` job이다. 인증된 lane마다 아무것도 돌리지 않으면
certified lane is a strict test lane that fails when it runs nothing. The in-code 실패하는 strict test lane이다.
`GrpcCompatibilityMatrix`/`GrpcStableReleaseGate` pair was removed (review 2026-09-24 S5-lead-4):
no production or build code called it, so it gated nothing.
## Lanes > 이력: 코드 안의 `GrpcCompatibilityMatrix`/`GrpcStableReleaseGate` 짝은 지웠다(리뷰 2026-09-24 S5-lead-4). 운영 코드도 빌드
> 코드도 그것을 부르지 않아서 아무것도 막지 않았다.
| Lane | Grade | Failure blocks a release | ## lane
| lane | 등급 | 실패하면 릴리스를 막나 |
| --- | --- | --- | | --- | --- | --- |
| Boot-managed platform (Spring Boot 4.0.8 BOM) | Certified | Yes | | Boot가 관리하는 플랫폼(저장소의 Spring Boot BOM) | Certified | 예 |
| proto3 with explicit `optional` | Certified | Yes | | 명시적 `optional`을 쓰는 proto3 | Certified | 예 |
| `grpc-netty-shaded` | Certified | Yes | | `grpc-netty-shaded` | Certified | 예 |
| `grpc-netty` (unshaded) | Compatibility | No | | `grpc-netty`(shade하지 않음) | Compatibility | 아니요 |
| Upstream gRPC Java version override | Compatibility | No | | upstream gRPC Java 버전 override | Compatibility | 아니요 |
| Protobuf Edition 2024 | Watch | No | | Protobuf Edition 2024 | Watch | 아니요 |
| Protobuf Edition 2026 | Watch | No | | Protobuf Edition 2026 | Watch | 아니요 |
## Runtime baseline ## 런타임 기준선
| | | | | |
| --- | --- | | --- | --- |
| Java | 21 | | Java | 21 |
| Spring Boot | 4.0.8 (the repository baseline; the plans assume 4.1) | | Spring Boot | 저장소 기준선, `src/gradle/libs.versions.toml`(계획은 4.1을 가정한다) |
| io.grpc | `ext.grpcVersion` in `src/build.gradle` | | io.grpc | `src/gradle/libs.versions.toml`의 `grpc`. `GrpcPlatformModuleConventionPlugin`이 그 BOM을 모듈 범위로 import한다 |
| Protobuf | `ext.protobufVersion` in `src/build.gradle` | | Protobuf | `src/gradle/libs.versions.toml`의 protobuf 항목(어느 leaf가 어느 것을 쓰는지는 그 파일의 주석이 적는다) |
| Stable transport | Netty (shaded) | | Stable 전송 | Netty(shaded) |
| Stable RPC shapes | Unary, Server Streaming | | Stable RPC 모양 | Unary, Server Streaming |
| Stable resolvers | Static, DNS, Unix domain socket | | Stable resolver | Static, DNS, Unix domain socket |
| Stable load balancing | `pick_first`, `round_robin` | | Stable load balancing | `pick_first`, `round_robin` |
## Evidence grades ## 증거 등급
A capability may only be advertised on evidence of a grade that can establish it. capability는 그것을 세울 수 있는 등급의 증거로만 광고한다. `GrpcEvidenceGrade.requireCertifies`가 이것을 강제하고,
`GrpcEvidenceGrade.requireCertifies` enforces this, and `GrpcReleaseEvidence.supports` refuses a `GrpcReleaseEvidence.supports`가 맞지 않는 lane이 뒷받침하는 주장을 거부한다.
claim backed by the wrong lane.
| Grade | Lane | Establishes | | 등급 | lane | 세우는 것 |
| --- | --- | --- | | --- | --- | --- |
| `CONTRACT` | `grpcInProcessContractTest` | adapter, interceptor order, status mapping, validation, idempotency replay, context propagation | | `CONTRACT` | `grpcInProcessContractTest` | 어댑터, interceptor 순서, 상태 매핑, 검증, 멱등 replay, context 전파 |
| `TRANSPORT` | `grpcNettyContractTest` | HTTP/2, TLS, mTLS, metadata limit, message limit, GOAWAY, keepalive, graceful shutdown | | `TRANSPORT` | `grpcNettyContractTest` | HTTP/2, TLS, mTLS, metadata 한도, 메시지 한도, GOAWAY, keepalive, graceful shutdown |
| `FAULT` | `grpcFaultTest` | connection loss, completion unknown, partial stream, evidence classifier | | `FAULT` | `grpcFaultTest` | 연결 끊김, 완료 모름, 부분 stream, 증거 분류기 |
| `PERFORMANCE` | `grpcPerformanceTest` | latency, stream saturation, executor saturation, drain budget | | `PERFORMANCE` | `grpcPerformanceTest` | 지연, stream 포화, executor 포화, drain 예산 |
In-process results are never transport evidence. The in-process transport does not negotiate TLS, in-process 결과는 절대 전송 증거가 아니다. in-process 전송은 TLS를 협상하지 않고, HTTP/2 frame을 만들지 않고, 전송 수준 한도를
does not frame HTTP/2 and does not enforce transport-level limits, so a suite that passes there has 강제하지 않는다. 그래서 거기서 통과한 suite는 전송이 아니라 어댑터를 시험한 것이다.
tested the adapter and not the transport.
## What is not supported ## 지원하지 않는 것
| | Where it lives | | | 있는 곳 |
| --- | --- | | --- | --- |
| Client streaming, bidirectional streaming | `grpc-advanced` (`streaming`) | | client streaming, bidirectional streaming | `grpc-advanced` (`streaming`) |
| Manual flow control | `grpc-advanced` (`streaming`) | | 수동 flow control | `grpc-advanced` (`streaming`) |
| Hedging | `grpc-advanced` (`resilience`) | | Hedging | `grpc-advanced` (`resilience`) |
| Custom name resolver, custom load balancer | `grpc-advanced` (`resilience`) | | 사용자 정의 name resolver, 사용자 정의 load balancer | `grpc-advanced` (`resilience`) |
| xDS | `grpc-advanced` (`resilience`) | | xDS | `grpc-advanced` (`resilience`) |
| gRPC-Web, Servlet HTTP/2, Spring Integration, Reactor, Kotlin | `grpc-advanced-compat` | | gRPC-Web, Servlet HTTP/2, Spring Integration, Reactor, Kotlin | `grpc-advanced-compat` |
| Channelz / CSDS diagnostics | `grpc-advanced` (`diagnostics`) | | Channelz / CSDS 진단 | `grpc-advanced` (`diagnostics`) |
## Current release status ## 지금 릴리스 상태
Not released. Every `:grpc:*` leaf is `runtime_memberships: []` in the module registry, so the 릴리스하지 않았다. registry에서 모든 `:grpc:*` leaf는 `"build": "optional-grpc"`라 주 빌드 밖에 있고 어느 조립에도 들어가지
platform is build-only: it compiles, its lanes run, and no deployed artifact carries it. 않는다. 플랫폼은 빌드만 된다. 컴파일되고 lane이 돌지만, 배포되는 산출물 어디에도 실리지 않는다.
Two release gate inputs are outstanding and are the work between here and a release: 릴리스 gate 입력 둘이 남아 있고, 그것이 지금부터 릴리스까지의 일이다.
- **Performance baseline.** The performance lane runs and asserts shape — ordered percentiles, a gate - **성능 기준선.** 성능 lane은 돌고, 절대 수치가 아니라 모양을 단언한다. 순서 있는 백분위수와 그것을 읽는 gate다. 알려진
that reads them — rather than absolute numbers. A recorded baseline on a known runner is what turns runner에서 기록한 기준선이 생겨야 회귀 gate가 된다.
it into a regression gate. - **schema codegen.** 이 빌드에서는 `protoc`가 돌지 않는다(ADR-GRPC-002). 그래서 descriptor 산출물과 consumer-compile fixture는
- **Schema codegen.** No `protoc` runs in this build (ADR-GRPC-002), so the descriptor artifact and 컴파일한 schema에서 만들어지지 않고 정책으로 다스린다.
the consumer-compile fixture are governed as policy rather than produced from a compiled schema.
+49 -55
View File
@@ -1,94 +1,88 @@
# Runbook: gRPC advanced capabilities # Runbook: gRPC advanced capabilities
Scope: the `:grpc-advanced:*` family. Everything here is off by default and stays off until a 범위: `:grpc-advanced:*` family. 여기 있는 것은 모두 기본으로 꺼져 있고, 배포가 이름을 대기 전까지 꺼진 채로
deployment names it. Nothing in this family ships in a runtime composition today. 있다. 지금 이 family의 어떤 것도 런타임 조립에 들어가지 않는다.
Flags are `app.grpc.advanced.<capability>.enabled`. `GrpcAdvancedCapability` owns the list of 스위치는 `app.grpc.advanced.<capability>.enabled`다. capability 이름 목록과 기본 등급은
capability names; `GrpcAdvancedSupportMatrix` owns their current grades. `GrpcAdvancedCapability`(`defaultGrade()`)가 가진다. 근거가 있는 배포는 `GrpcAdvancedFeatureFlags.withGrade`로
등급을 바꾼다.
--- ---
## A capability refuses to start ## capability가 뜨기를 거부한다
`GrpcAdvancedModuleGuard` gives three different refusals, and the remedy differs: `GrpcAdvancedModuleGuard`는 세 가지로 거부하고, 고치는 법이 다르다.
| Message contains | Meaning | Remedy | | 메시지에 있는 말 | 뜻 | 고치는 법 |
| --- | --- | --- | | --- | --- | --- |
| "its feature flag is not set" | Nobody enabled it | Set the property named in the message | | "its feature flag is not set" | 아무도 켜지 않았다 | 메시지가 이름 댄 속성을 설정한다 |
| "tracked rather than implemented" | Grade is `WATCH` | Nothing to do here; the capability is not implemented | | "tracked rather than implemented" | 등급이 `WATCH`다 | 여기서 할 일은 없다. 그 capability는 구현되지 않았다 |
| "uncharacterised failure modes" | Grade is `EXPERIMENTAL` and this is production | Record a production approval, or run it outside production | | "uncharacterised failure modes" | 등급이 `EXPERIMENTAL`이고 여기는 운영이다 | 운영 승인을 기록하거나, 운영 밖에서 돌린다 |
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 ## xDS: control plane이 사라졌다
**What you are seeing.** The control plane is unreachable and clients are still routing. **보이는 것.** control plane에 닿지 않는데 클라이언트는 아직 라우팅한다.
**What it means.** `GrpcXdsFailurePolicy` serves the last-known-good snapshot, up to its staleness **뜻.** `GrpcXdsFailurePolicy`가 마지막으로 정상이던 snapshot을 오래됨 상한까지 내준다.
bound.
**What to do.** **할 일.**
1. Check the snapshot's age. `SERVE_LAST_KNOWN_GOOD` is the healthy degraded state. 1. snapshot의 나이를 본다. `SERVE_LAST_KNOWN_GOOD`는 정상적인 degraded 상태다.
2. `STALE_BEYOND_BOUND` means the snapshot is older than the policy allows and is no longer trusted. 2. `STALE_BEYOND_BOUND`는 snapshot이 정책이 허용하는 것보다 오래돼서 더는 믿지 않는다는 뜻이다. 그 상한이
Beyond that bound, a decommissioned backend would otherwise keep receiving traffic indefinitely. 없으면 내린 backend가 트래픽을 끝없이 받는다.
3. `NO_SNAPSHOT_YET` on a starting instance means it never reached the control plane. It fails after 3. 뜨는 인스턴스의 `NO_SNAPSHOT_YET`은 control plane에 한 번도 닿지 못했다는 뜻이다. 라우팅 없이 뜨지 않고, 첫
the initial fetch timeout rather than starting with no routing. fetch 시간 상한이 지나면 실패한다.
**Do not** add application-level retry policy while xDS is enabled. `GrpcXdsProfile` refuses an xDS가 켜진 동안 애플리케이션 수준의 재시도 정책을 **더하지 않는다**. `GrpcXdsProfile`이 `APPLICATION` 재시도
`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 ## gRPC-Web: 브라우저 호출이 멈췄다가 상태 없이 실패한다
**Almost always the proxy.** A gRPC status arrives as a trailer, and a browser cannot read a trailer **거의 언제나 proxy다.** gRPC 상태는 trailer로 오고, 브라우저는 proxy가 노출하지 않은 trailer를 읽지 못한다.
the proxy did not expose. Check that the proxy's CORS `expose_headers` includes `grpc-status` and proxy의 CORS `expose_headers`에 `grpc-status`와 `grpc-message`가 있는지 확인한다.
`grpc-message`; `GrpcWebProxyContract.violations` reports exactly this, and the reference `GrpcWebProxyContract.violations`가 정확히 이것을 보고하고, 참조 설정
configuration in `envoy/envoy.yaml` shows it in place. `src/platforms/grpc-advanced/grpc-advanced-compat/src/test/resources/envoy/envoy.yaml`에 그것이 들어 있다.
**If the method is client- or bidirectional-streaming**, it cannot work over gRPC-Web at all — a **메서드가 client streaming이나 bidirectional streaming이면** gRPC-Web으로는 아예 되지 않는다. 브라우저는
browser has no way to send a stream of messages. `GrpcWebRpcSupport.require` refuses such a method. 메시지 stream을 보낼 방법이 없다. `GrpcWebRpcSupport.require`가 그런 메서드를 거부한다.
--- ---
## Servlet: a transport setting appears to be ignored ## Servlet: 전송 설정이 무시되는 것 같다
It is ignored. The container owns the socket, so keepalive tuning, maximum connection age and 무시된다. 소켓은 컨테이너가 가지므로 keepalive 조정, 최대 연결 수명, flow-control window 조정은 컨테이너의
flow-control window tuning belong to it. This repository has no Servlet transport code that would 몫이다. 이 저장소에는 그것을 거부할 Servlet 전송 코드가 없으니 컨테이너에서 설정한다.
refuse them, so configure them on the container.
A Servlet run never substitutes for Netty certification. Servlet 실행은 Netty 인증을 대신하지 않는다.
--- ---
## Hedging: backend load doubled ## Hedging: backend 부하가 두 배가 됐다
**Expected, within a bound.** Hedging trades duplicate load for tail latency. **상한 안이면 예상한 일이다.** hedging은 중복 부하를 내고 꼬리 지연을 줄인다. `GrpcHedgingResult`는
`GrpcHedgingResult` records both `duplicateBackendCalls` and `cancelledLoserAttempts`; a dashboard `duplicateBackendCalls`와 `cancelledLoserAttempts`를 둘 다 기록한다. 지연 개선만 보여 주는 대시보드는 그 교환을
showing only the latency improvement makes the trade look free. 공짜처럼 보이게 한다.
**What to check.** `GrpcHedgingBudget` caps hedges as a fraction of completed calls. If duplicate **확인할 것.** `GrpcHedgingBudget`은 hedge를 끝난 호출의 비율로 제한한다. 중복 부하가 그 비율을 넘으면 예산이
load is above that fraction, the budget is not being consumed — which means something is issuing 쓰이지 않고 있다는 뜻이다. coordinator 밖에서 무언가가 hedge를 보내고 있다.
hedges outside the coordinator.
**Hedging is refused** for anything but a read-only unary method. A hedged mutation runs twice by 읽기 전용 unary 메서드가 아니면 **hedging을 거부한다**. hedge된 변경은 설계상 두 번 돈다. 멱등 키도 소용없다.
design, and an idempotency key does not help: the second attempt duplicates a success in progress 두 번째 시도는 실패를 다시 시도하는 것이 아니라 진행 중인 성공을 중복한다.
rather than retrying a failure.
--- ---
## Promoting a capability ## capability 승격
Promotion to `ADVANCED_STABLE` needs compatibility evidence, a security review, fault evidence, `ADVANCED_STABLE`로 올리려면 호환성 증거, 보안 리뷰, 장애 증거, 성능 증거, ADR, runbook, 실제 환경 시험, 7일
performance evidence, an ADR, a runbook, a real-environment test and seven days of soak. A Stable soak이 필요하다. Stable 기본값은 30일이 필요하다. 승격은 서로 독립이다. 한 capability를 올려도 다른 것의 등급은
default needs thirty. Promotions are independent: promoting one capability changes no other's 바뀌지 않는다. 이것은 리뷰 점검 목록이다. 이것을 코드로 다시 적은 `GrpcAdvancedPromotionGate`는 자기 테스트
grade. This is a review checklist; the in-code `GrpcAdvancedPromotionGate` that restated it was 말고는 부르는 곳이 없어 지웠다(리뷰 2026-09-24 S5-lead-4).
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, 어떤 suite를 증거로 들기 전에, 그 suite가 필요한 실제 인프라(proxy, 컨테이너, control plane, toolchain)에 대고
container, control plane or toolchain). A suite that ran without it passed and established nothing. 돌았는지 확인한다. 인프라 없이 돈 suite는 통과했지만 아무것도 증명하지 않았다.
+101 -120
View File
@@ -1,179 +1,160 @@
# Runbook: gRPC platform operations # Runbook: gRPC platform operations
Scope: the `:grpc:*` family. All of it is build-only today — every leaf's `runtime_memberships` is 범위: `:grpc:*` family. 지금은 모두 빌드만 된다. registry에서 이 family의 leaf는 모두 `"build": "optional-grpc"`
empty — so nothing here fires in production yet. It is written now because the states it covers are (주 빌드 밖, `-p platforms/optional-build`로 돈다)이고 어느 조립에도 들어가지 않으므로, 여기 있는 것은 아직 운영에서
the ones an on-call cannot work out from first principles at three in the morning, and shipping the 일어나지 않는다. 그래도 지금 쓰는 이유가 있다. 여기서 다루는 상태는 당번이 새벽 세 시에 처음부터 따져서는 알아낼
behaviour before the runbook means the first person to meet one is doing that. 수 없는 것들이고, runbook보다 동작을 먼저 내보내면 그것을 처음 만난 사람이 그 따지기를 하게 된다.
Configuration lives under `app.grpc.platform.*` and is bound by `GrpcPlatformProperties`. 설정은 `app.grpc.platform.*` 아래에 있고 `GrpcPlatformProperties`가 묶는다. 플랫폼은
The platform does not start unless `app.grpc.platform.enabled=true`. `app.grpc.platform.enabled=true`가 아니면 뜨지 않는다.
--- ---
## COMPLETION_UNKNOWN on a mutation ## 상태를 바꾸는 호출의 COMPLETION_UNKNOWN
**What you are seeing.** A client received `DEADLINE_EXCEEDED`, `UNAVAILABLE` or `INTERNAL` on a **보이는 것.** 클라이언트가 상태를 바꾸는 호출에서 `DEADLINE_EXCEEDED`, `UNAVAILABLE`, `INTERNAL`을 받았고, 응답
state-changing call, and the response trailer `completion-outcome` reads `COMPLETION_UNKNOWN`. trailer `completion-outcome`이 `COMPLETION_UNKNOWN`이다.
**What it means.** The server may have committed. This is not a failure and not a success; the status **뜻.** 서버가 커밋했을 수 있다. 실패도 성공도 아니다. 상태 코드로는 둘을 가릴 수 없어서 결과를 따로 싣는다.
code cannot distinguish them, which is why the outcome is carried separately.
**What not to do.** Do not re-issue the call. Do not tell the caller it failed. Both are wrong half **하지 말 것.** 호출을 다시 보내지 않는다. 호출자에게 실패했다고 말하지 않는다. 둘 다 절반은 틀리고, 어느 절반인지
the time, and which half is not knowable from the status. 상태 코드로는 알 수 없다.
**What to do.** **할 일.**
1. Take the `error-execution-id` from the trailers. It is the only link between what the client saw 1. trailer에서 `error-execution-id`를 꺼낸다. 클라이언트가 본 것과 서버가 한 것을 잇는 유일한 고리다.
and what the server did. 2. 메서드가 `IDEMPOTENCY_KEY_REQUIRED`면 호출자 fingerprint, 전체 메서드 이름, 호출자의 키로 operation ledger를
2. If the method is `IDEMPOTENCY_KEY_REQUIRED`, query the operation ledger with the caller 조회한다. `GrpcOperationStatusQuery`는 `IN_PROGRESS`, `COMMITTED`, `FAILED_TERMINAL`, `NOT_FOUND`, `UNKNOWN`
fingerprint, the full method name and the caller's key. `GrpcOperationStatusQuery` returns one of 중 하나를 돌려준다.
`IN_PROGRESS`, `COMMITTED`, `FAILED_TERMINAL`, `NOT_FOUND` or `UNKNOWN`. 3. `COMMITTED`면 새로 계산한 답이 아니라 저장된 결과 참조를 돌려준다. 그 뒤에 자원이 바뀌었을 수 있고, 새 답은
3. `COMMITTED` means return the stored outcome reference, not a freshly computed answer — the resource 호출자 자신의 호출이 만든 상태가 아니라 맞춰 보는 시점의 상태를 설명한다.
may have changed since, and a new answer would describe the state at reconciliation time rather 4. `NOT_FOUND`는 operation이 시작하지 않았다는 뜻이라 다시 보내도 안전하다. `FAILED_TERMINAL`도 같다.
than the state the caller's own call produced. 5. `UNKNOWN`은 ledger를 조회하지 못했다는 뜻이다. 아무것도 결론 낼 수 없다. `GrpcCompletionReconciler`가 그
4. `NOT_FOUND` means the operation never started and is safe to re-issue. `FAILED_TERMINAL` means the 건을 대기열에 넣고 나중에 다시 시도한다.
same. 6. 메서드에 키가 없으면 ledger 행이 없다. 업무 자원으로 맞춰 보거나 서비스 소유자에게 넘긴다. 키 있는 profile은
5. `UNKNOWN` means the ledger could not be consulted. Nothing may be concluded. The case is queued by 이 경우를 피하려고 있다.
`GrpcCompletionReconciler` and retried later.
6. If the method is not keyed, there is no ledger row. Resolve it against the business resource, or
escalate to the service owner. This is the case the keyed profile exists to avoid.
7. `IN_PROGRESS` means a claim exists and has not finished. If its owner died, the claim is not 7. `IN_PROGRESS`는 claim이 있고 끝나지 않았다는 뜻이다. 그 소유자가 죽었어도 claim이 영원히 묶이지는 않는다.
stuck forever: once it is older than the claim TTL (`app.grpc.platform.operation-ledger-claim-ttl`, claim TTL(`app.grpc.platform.operation-ledger-claim-ttl`, 기본 5m)보다 오래되면, 같은 요청의 다음 재시도가
default 5m), the next retry of the same request takes it over and runs again, 그것을 넘겨받아 다시 돌리고, 뒤의 reconciler 단계가 그 시도의 `COMMITTED`나 `FAILED_TERMINAL`을 본다.
and a later reconciler pass sees that attempt's `COMMITTED` or `FAILED_TERMINAL`. Until a retry 재시도가 오기 전까지 그 건은 대기로 남는다. 다시 돌리는 것은 ledger 커밋이 변경 자신의 트랜잭션 안에서 기록될
arrives, the case stays pending. The re-run is safe only when the ledger commit is recorded in the 때만 안전하다. 이 서비스가 둘을 따로 커밋하면 재시도를 들이기 전에 업무 자원을 확인한다. 느리기만 했던
mutation's own transaction; if this service commits them separately, check the business resource 소유자는 넘겨받기를 망치지 못한다. 그 claim 시도(`claim_attempt`)가 뒤처졌으므로 늦은 커밋은 거부되고 늦은
before letting the retry through. An owner that was only slow cannot spoil the takeover: its claim 실패는 무시된다. operation이 "is no longer held by attempt N"이라는 로그 줄이 그 거부다. 장애가 아니다.
attempt (`claim_attempt`) is behind, so its late commit is refused and its late failure ignored.
A log line saying an operation "is no longer held by attempt N" is that refusal, not an outage.
**Escalate when** the reconciler's pending list grows across passes. That means the ledger is **넘길 때는** reconciler의 대기 목록이 단계를 거듭하며 커질 때다. ledger가 느린 게 아니라 닿지 않는다는 뜻이다.
unreachable rather than slow. A case pending as `IN_PROGRESS` for longer than the claim TTL with no claim TTL보다 오래 `IN_PROGRESS`로 대기 중인데 재시도가 오지 않는 건은 호출자가 포기한 것이다. ledger를 고칠 일이
retry arriving is a caller that gave up; it needs the business resource checked, not a ledger fix. 아니라 업무 자원을 확인할 일이다.
--- ---
## The operation ledger table keeps growing ## operation ledger 테이블이 계속 커진다
**What you are seeing.** `grpc_operation_ledger` grows without bound, or a retry of an old key runs **보이는 것.** `grpc_operation_ledger`가 끝없이 커지거나, 오래된 키의 재시도가 replay 대신 변경을 다시 돌린다.
the mutation again instead of replaying.
**What it means.** Finished rows (`COMMITTED`, `FAILED_TERMINAL`) are deleted only when something **뜻.** 끝난 행(`COMMITTED`, `FAILED_TERMINAL`)은 누군가 `GrpcOperationLedgerRetention.purgeExpired(now)`를 불러야만
calls `GrpcOperationLedgerRetention.purgeExpired(now)`; the starter assembles that bean 지워진다. starter는 그 bean을 조립하지만(`app.grpc.platform.operation-ledger-enabled=true`) 일정을 걸지는 않는다.
(`app.grpc.platform.operation-ledger-enabled=true`) but does not schedule it. A growing table means 테이블이 커지면 서비스의 scheduler가 그것을 부르지 않는 것이다. 보존 기간
the service's scheduler is not calling it. A retry that re-ran after the retention (`app.grpc.platform.operation-ledger-retention`, 기본 24h)이 지난 뒤 다시 돈 재시도는 보존 기간이 감수하는
(`app.grpc.platform.operation-ledger-retention`, default 24h) is the trade the retention makes: its 교환이다. 기록이 지워졌으므로 새 operation이었다.
record was purged, so it was a new operation.
**What to do.** **할 일.**
1. Check that the service schedules `purgeExpired`. Each call deletes in batches of 500 until a batch 1. 서비스가 `purgeExpired`에 일정을 걸었는지 확인한다. 한 번 부르면 500행씩 지우다가 덜 찬 묶음이 나오면 멈추고,
comes back short, never touching `IN_PROGRESS` rows. `IN_PROGRESS` 행은 건드리지 않는다.
2. For a large backlog, call it repeatedly; each batch is a short transaction that skips rows another 2. 밀린 양이 많으면 여러 번 부른다. 묶음마다 짧은 트랜잭션이고, 다른 트랜잭션이 쥔 행은 건너뛴다.
transaction holds. 3. 다시 보낸 키가 보존 기간 뒤에 다시 돌면, purge를 건너뛰지 말고 보존 기간을 호출자의 재시도 창보다 길게 한다.
3. If retried keys re-run after the retention, raise the retention above the callers' retry window
rather than skipping the purge.
**Escalate when** old `IN_PROGRESS` rows accumulate. Those are not purged by design; each is an **넘길 때는** 오래된 `IN_PROGRESS` 행이 쌓일 때다. 그 행은 설계상 지워지지 않는다. 하나하나가 어느 재시도도
abandoned claim no retry has taken over (see `IN_PROGRESS` above). 넘겨받지 않은 버려진 claim이다(위의 `IN_PROGRESS`).
--- ---
## A stream ended with FULL_RESYNC_REQUIRED ## stream이 FULL_RESYNC_REQUIRED로 끝났다
**What you are seeing.** A client's resume was refused and it was told to resynchronise. **보이는 것.** 클라이언트의 resume이 거부되고 다시 동기화하라는 답을 받았다.
**What it means.** The server can no longer replay from the client's cursor. Either the snapshot **뜻.** 서버가 클라이언트의 cursor부터 더는 replay할 수 없다. snapshot 버전이 움직였거나, cursor가 보존된 이력보다
version moved, or the cursor predates retained history. 앞선다.
**What to do.** Nothing on the server. The client is expected to discard its position and start a new **할 일.** 서버에서는 없다. 클라이언트가 자기 위치를 버리고 새 snapshot에서 새 stream을 시작해야 한다. 대신 같은
stream from a fresh snapshot. A client that instead retries the same token will keep receiving the token으로 다시 시도하는 클라이언트는 같은 답을 계속 받는다.
same answer.
**Escalate when** it is happening to many clients at once. That usually means history retention was **넘길 때는** 많은 클라이언트에 한꺼번에 일어날 때다. 보통 이력 보존이 줄었거나, 클라이언트가 다시 붙는 것보다
reduced, or snapshots are rotating faster than clients reconnect. snapshot이 빨리 돈다는 뜻이다.
--- ---
## A stream ended with SLOW_CONSUMER ## stream이 SLOW_CONSUMER로 끝났다
**What you are seeing.** Streams terminating with `SLOW_CONSUMER`, and **보이는 것.** stream이 `SLOW_CONSUMER`로 끝나고 `grpc.stream.flow_control_stalls`가 오른다.
`grpc.stream.flow_control_stalls` rising.
**What it means.** The consumer could not keep up with the bounded queue. The stream was terminated **뜻.** 소비자가 상한 있는 큐를 따라가지 못했다. 메시지를 조용히 버리는 대신 stream을 끝냈다. 클라이언트는 버려진
rather than silently dropping messages, because a client cannot detect drops — the sequence numbers 것을 알아챌 수 없다. 클라이언트가 보는 순번은 보내진 것뿐이다.
it sees are the ones it was sent.
**What to do.** **할 일.**
1. Check whether the consumer is slow or the producer is fast. `grpc.stream.messages` against 1. 소비자가 느린지 생산자가 빠른지 확인한다. `grpc.stream.messages`를 `grpc.stream.lifetime`과 견주면 속도가
`grpc.stream.lifetime` tells you the rate. 나온다.
2. If the consumer is slow, the fix is on the consumer. Raising the queue bound moves the failure 2. 소비자가 느리면 고칠 곳은 소비자다. 큐 상한을 올리면 실패가 뒤로 밀리고 커질 뿐이다.
later and makes it larger. 3. 이렇게 끝난 뒤에는 resume을 쓸 수 없다. 큐를 넘친 메시지는 사라졌으므로, 마지막으로 전달한 순번부터 이어 가면
3. A resume is not available after this ending: the messages that overflowed the queue are gone, so 그것을 조용히 건너뛴다. 클라이언트는 다시 동기화한다.
continuing from the last delivered sequence would silently skip them. The client resynchronises.
--- ---
## RESOURCE_EXHAUSTED under load ## 부하에서 RESOURCE_EXHAUSTED
**What you are seeing.** Calls refused with `RESOURCE_EXHAUSTED` and `GrpcAdmissionController` **보이는 것.** 호출이 `RESOURCE_EXHAUSTED`로 거부되고 `GrpcAdmissionController`가 거부를 보고한다.
reporting rejections.
**What it means.** The server is at its concurrency and queue bounds and is shedding rather than **뜻.** 서버가 동시성과 큐 상한에 닿아서 줄을 세우지 않고 덜어 낸다. 설계한 동작이다. 호출자가 이미 포기한 일을
queueing. This is the designed behaviour: accepting work whose callers have already given up spends 받으면 아무것도 아닌 데 용량을 쓴다.
capacity on nothing.
**What to do.** **할 일.**
1. Read `grpc.rpc.duration` and `grpc.rpc.queue_wait` separately. Queue time rising with duration flat 1. `grpc.rpc.duration`과 `grpc.rpc.queue_wait`를 따로 읽는다. duration은 그대로인데 큐 시간이 오르면 병목은 일이
means the bottleneck is admission, not the work. 아니라 admission이다.
2. Check which saturation counter is moving — executor, channel or flow control. They look identical 2. 어느 포화 counter가 움직이는지 확인한다. executor, channel, flow control이다. 지연 그래프에서는 똑같이 보이지만
in a latency graph and have different fixes. 고치는 법이 다르다.
3. Raising `app.grpc.platform.executor-queue-capacity` defers the problem; it does not remove 3. `app.grpc.platform.executor-queue-capacity`를 올리면 문제를 미룰 뿐 없애지 않는다. 그래서 `GrpcExecutorProfile`이
it. `GrpcExecutorProfile` refuses a queue above ten thousand for that reason. 1만이 넘는 큐를 거부한다.
--- ---
## A rollout is producing errors at every deploy ## 배포할 때마다 rollout이 오류를 낸다
**What you are seeing.** A burst of `UNAVAILABLE` or `CANCELLED` each time an instance goes away. **보이는 것.** 인스턴스가 빠질 때마다 `UNAVAILABLE`이나 `CANCELLED`가 몰린다.
**What it means.** The drain sequence is not completing, or is running out of order. **뜻.** drain 순서가 끝나지 않거나, 순서가 어긋나서 돈다.
**What to do.** **할 일.**
1. `GrpcDrainResult` records what each drain achieved: completed and cancelled unary calls, signalled 1. `GrpcDrainResult`가 각 drain이 해낸 것을 기록한다. 끝난 unary 호출과 취소된 unary 호출, 신호를 받은 stream과
and cancelled streams, and which phases ran. A drain that routinely force-cancels is the cause. 취소된 stream, 돈 단계다. 늘 강제 취소하는 drain이 원인이다.
2. The order matters. Readiness flips first and nothing is refused during that window, because there 2. 순서가 중요하다. readiness가 먼저 뒤집히고, 그 사이에는 아무것도 거부하지 않는다. 인스턴스가 unready를 보고한
is a gap between an instance reporting unready and routing acting on it. Refusing during that gap 뒤 라우팅이 그것을 따르기까지 틈이 있기 때문이다. 그 틈에 거부하면 깨끗한 rollout이 배포마다 오류 묶음이 된다.
turns a clean rollout into a burst of errors at every deploy. 3. 긴 stream이면 Kubernetes profile의 `streamReconnectBudget`과 `readinessDrainGrace`를 확인한다. stream은 일생
3. For long streams, check the Kubernetes profile's `streamReconnectBudget` and 내내 한 pod에 묶이므로 rollout마다 끝난다. 긴 stream이 있는데 다시 붙는 예산이 없는 profile은 클라이언트가 다음에
`readinessDrainGrace`. A stream is pinned to one pod for its whole life, so every rollout ends it; 할 일을 정하지 않은 것이다.
a profile with long streams and no reconnect budget has not decided what clients do next.
--- ---
## Verifying a deployment's configuration ## 배포의 설정 확인
`GrpcPlatformSnapshotService` produces a secret-free snapshot for a caller on the admin network `GrpcPlatformSnapshotService`는 관리 네트워크에 있고 관리 역할을 가진 호출자에게 secret 없는 snapshot을 만든다.
holding an admin role. Both gates are required. 두 관문이 모두 필요하다.
`GrpcPlatformSnapshotService.driftAgainstRelease` compares a running snapshot with the release `GrpcPlatformSnapshotService.driftAgainstRelease`는 실행 중인 snapshot을 릴리스 manifest와 비교해 스키마 버전,
manifest and reports schema version, method policy hash and per-channel profile differences. An 메서드 정책 해시, channel별 profile 차이를 보고한다. 릴리스가 내보내지 않은 설정으로 도는 인스턴스는, 그렇지 않으면
instance running a configuration the release did not ship is behind a whole class of incidents that 로그를 읽어야만 진단되는 장애 한 부류의 원인이다.
are otherwise diagnosed by reading logs.
The snapshot carries hashes and names only. A field whose name looks like a credential is refused at snapshot에는 해시와 이름만 실린다. 자격 증명처럼 보이는 이름의 칸은 가리지 않고 만들 때 거부한다.
construction rather than redacted.
--- ---
## Things that are deliberately off ## 일부러 꺼 둔 것
- **Reflection in production.** `GrpcReflectionMode.defaultFor` returns `DISABLED` for `STAGE` and - **운영의 reflection.** `GrpcReflectionMode.defaultFor`는 `STAGE`와 `PROD`에 `DISABLED`를 돌려준다. reflection은
`PROD`. Reflection publishes the whole schema to anyone who can open a connection. 연결을 열 수 있는 누구에게나 스키마 전체를 공개한다.
- **Every advanced capability.** See `docs/runbooks/grpc-advanced-capabilities.md`. - **모든 advanced capability.** `docs/runbooks/grpc-advanced-capabilities.md`를 본다.
- **The platform itself.** `app.grpc.platform.enabled` defaults to false, and every `:grpc:*` - **플랫폼 자체.** `app.grpc.platform.enabled`의 기본값은 false이고, registry에서 모든 `:grpc:*` leaf는
leaf is build-only in the registry. `"build": "optional-grpc"`라 기본 조립에 들어가지 않는다.
+2 -2
View File
@@ -1,6 +1,6 @@
# grpc-advanced — local authority for the advanced gRPC capabilities # grpc-advanced — 고급 gRPC capability의 지역 정본
이 문서는 `grpc-advanced:*` family의 **local authority**다. leaf 목록·gradle path·허용 의존성은 이 문서는 `grpc-advanced:*` family의 **지역 정본(local authority)**이다. leaf 목록·gradle path·허용 의존성은
`src/config/architecture/modules.json`이 SSOT다. Root 정책(`CLAUDE.md` / `AGENTS.md`)과 충돌하면 `src/config/architecture/modules.json`이 SSOT다. Root 정책(`CLAUDE.md` / `AGENTS.md`)과 충돌하면
root가 이긴다. root가 이긴다.
+48 -51
View File
@@ -1,6 +1,6 @@
# grpc — local authority for the gRPC platform family # grpc — gRPC 플랫폼 family의 지역 정본
이 문서는 `grpc:*` family의 **local authority**다. gRPC platform은 기본 application build와 분리된 이 문서는 `grpc:*` family의 **지역 정본(local authority)**이다. gRPC platform은 기본 application build와 분리된
`src/platforms/optional-build` build가 소유한다. 여기서 정하는 것은 family별 framework 규칙, 증거 등급, `src/platforms/optional-build` build가 소유한다. 여기서 정하는 것은 family별 framework 규칙, 증거 등급,
Stable 범위의 경계와 application에 채택될 때 필요한 계약이다. Stable 범위의 경계와 application에 채택될 때 필요한 계약이다.
@@ -132,64 +132,61 @@ cd src
(`GrpcMetricCardinalityPolicy`가 거부한다). (`GrpcMetricCardinalityPolicy`가 거부한다).
### Adoption-time observability gate ### 채택할 때의 관측 게이트
The metric names implemented by `grpc-observability` are **not registered in `grpc-observability`가 구현한 metric 이름은 **아직 `docs/registries/metrics.yaml`에 등록하지
`docs/registries/metrics.yaml` yet** because this optional family is not a shipped runtime capability. 않았다**. 이 optional family는 출하하는 런타임 capability가 아니기 때문이다. 채택하면서 저장소의
Do not present those names as repository-certified metrics until adoption adds registry entries with `.seconds` / `.total` 단위 이름 규칙에 맞는 registry 항목과 그에 맞는 검증 게이트를 더하기 전에는 그
the repository's `.seconds` / `.total` unit naming and the corresponding validation gate. 이름을 저장소가 인증한 metric처럼 내세우지 않는다.
### Durable operation ledger adoption ### durable operation 원장 채택
`grpc-spring-boot-starter` does not pull the JPA ledger adapter transitively (11-M9). A deployment that `grpc-spring-boot-starter`는 JPA 원장 어댑터를 전이 의존으로 끌어오지 않는다(2026-09-18 리뷰가 찾은 문제). durable
needs durable operation idempotency adds `:grpc:grpc-operation-ledger-jpa` explicitly, defines a operation 멱등성이 필요한 배포는 `:grpc:grpc-operation-ledger-jpa`를 직접 더하고,
`GrpcOperationLedger` bean (`new JpaGrpcOperationLedger(repository)`), includes that adapter's Flyway `GrpcOperationLedger` bean(`new JpaGrpcOperationLedger(repository)`)을 정의하고, 그 어댑터의 Flyway
location `db/migration/grpc` (V001 table, V002 retention index, V003 claim attempt), and sets the flag below. A deployment 위치 `db/migration/grpc`(V001 테이블, V002 보존 index, V003 claim attempt)를 넣고, 아래 flag를 켠다.
that does not adopt the ledger pays no Spring Data JPA classpath cost. 원장을 채택하지 않는 배포는 Spring Data JPA classpath 비용을 내지 않는다.
| Key (`app.grpc.platform.*`) | Default | What it does | | 키 (`app.grpc.platform.*`) | 기본값 | 하는 일 |
| --- | --- | --- | | --- | --- | --- |
| `operation-ledger-enabled` | `false` | `true`: the starter assembles `GrpcIdempotencyInterceptor` (bean `grpcIdempotencyInterceptor`) and `GrpcOperationLedgerRetention` (bean `grpcOperationLedgerRetention`) over the deployment's `GrpcOperationLedger` bean, and refuses startup when there is none. `false`: neither bean exists, and a method that is `IDEMPOTENCY_KEY_REQUIRED` refuses startup | | `operation-ledger-enabled` | `false` | `true`: starter가 배포의 `GrpcOperationLedger` bean 위에 `GrpcIdempotencyInterceptor`(bean `grpcIdempotencyInterceptor`)와 `GrpcOperationLedgerRetention`(bean `grpcOperationLedgerRetention`)을 조립하고, 원장 bean이 없으면 기동을 거절한다. `false`: 두 bean 모두 없고, `IDEMPOTENCY_KEY_REQUIRED`인 메서드가 있으면 기동을 거절한다 |
| `operation-ledger-claim-ttl` | `5m` | How long an `IN_PROGRESS` claim is trusted to have a live owner. After it, a retry of the same request takes the claim over (`GrpcOperationLedger.reclaimStale`). Refused at startup unless longer than every keyed method's deadline | | `operation-ledger-claim-ttl` | `5m` | `IN_PROGRESS` claim의 주인이 살아 있다고 믿는 시간. 지나면 같은 요청의 재시도가 claim을 넘겨받는다(`GrpcOperationLedger.reclaimStale`). 키가 필요한 모든 메서드의 deadline보다 길지 않으면 기동에서 거절한다 |
| `operation-ledger-retention` | `24h` | How long a finished (`COMMITTED`/`FAILED_TERMINAL`) record is kept before `GrpcOperationLedgerRetention.purgeExpired` may delete it. `IN_PROGRESS` rows are never purged | | `operation-ledger-retention` | `24h` | 끝난(`COMMITTED`/`FAILED_TERMINAL`) 레코드를 `GrpcOperationLedgerRetention.purgeExpired`가 지울 수 있게 되기 전까지 두는 시간. `IN_PROGRESS` 행은 지우지 않는다 |
Defaults: the 5-minute TTL is the value the ledger contract and interceptor tests certify, far beyond 기본값: 5분 TTL은 원장 계약 시험과 interceptor 시험이 인증한 값이다. unary deadline보다 훨씬 길고,
a unary deadline, and short enough that a key whose owner died unblocks within a client's retry 주인이 죽은 키가 클라이언트의 재시도 인내 안에 풀릴 만큼 짧다. 24시간 보존은 HTTP 멱등성 재생 TTL
patience. The 24-hour retention matches the HTTP idempotency replay TTL (`app.capabilities.idempotency.replay-ttl`)과 같다. 레코드를 지운 뒤 같은 키로 하는 재시도는 새
(`app.capabilities.idempotency.replay-ttl`). A retry of a key after its record was purged is a new operation이므로, 보존 시간은 호출자의 재시도 창보다 길어야 한다.
operation, so the retention must exceed the callers' retry window.
These keys are not in `docs/registries/env-keys.yaml`: no `app.grpc.platform.*` key is, because the 이 키들은 `docs/registries/env-keys.yaml`에 없다. optional 빌드는 출하하는 런타임이 아니라서
optional build is not part of the shipped runtime. They join the registry when a composition root `app.grpc.platform.*` 키는 하나도 없다. 조립 루트가 플랫폼을 채택할 때 registry에 들어간다.
adopts the platform.
**Why the starter assembles the interceptor (option (b)), and not (a).** The 2026-11-01 maturity review proposed (a): **starter가 interceptor를 조립하는 이유(선택지 (b)), (a)가 아닌 이유.** 2026-11-01 성숙도 리뷰는
delete the flag and judge by whether a ledger bean exists. (b) was chosen on 2026-11-03 and is recorded in (a)를 제안했다: flag를 지우고 원장 bean이 있는지로 판단한다. 2026-11-03에 (b)를 골랐고 ADR-GRPC-004에
ADR-GRPC-004: the flag stays and means what it says — when true, the 적었다: flag를 남기고 flag는 말 그대로의 뜻이다 — true이면 판정 함수를 조립하고 그 TTL은 설정에서
decision function is assembled and its TTL comes from configuration. (a) would have removed the false promise but left every adopter to rebuild the same 온다. (a)는 거짓 약속을 없앴겠지만 채택하는 쪽마다 같은 조립과 TTL 검증을 손으로 다시 만들게
assembly and TTL validation by hand; (b) keeps that in one place. The interceptor bean has no 했다. (b)는 그것을 한곳에 둔다. interceptor bean에는 일부러 `@ConditionalOnMissingBean`이 없다:
`@ConditionalOnMissingBean` on purpose: a replacement would silently ignore `operation-ledger-claim-ttl`. 바꿔 넣은 bean은 `operation-ledger-claim-ttl`을 소리 없이 무시하게 된다. 돌고 있는 operation의
Duplicates of a running operation are refused (`REJECT_IN_PROGRESS`), not told to wait; a 중복은 기다리라고 하지 않고 거절한다(`REJECT_IN_PROGRESS`). 기다렸다가 다시 묻는 선택지는 키가
wait-and-poll option becomes a key when a keyed method needs it. 필요한 메서드가 그것을 필요로 할 때 키가 된다.
**Server wiring is still the adopter's, and stays a separate decision.** The starter builds no **서버 배선은 여전히 채택하는 쪽의 몫이고, 따로 정할 일로 남는다.** starter는 서버를 만들지
server, so assembling the decision does not wire the platform into `adapter:inbound:grpc` (see "배선은 않으므로, 판정을 조립한다고 플랫폼이 `adapter:inbound:grpc`에 배선되지는 않는다(위 "배선은
별도 결정" above). `GrpcIdempotencyInterceptor` is a decision function, not an `io.grpc.ServerInterceptor`. 별도 결정"을 본다). `GrpcIdempotencyInterceptor`는 판정 함수이고 `io.grpc.ServerInterceptor`가
The adopter injects the bean by type and calls it from its own `IDEMPOTENCY` stage interceptor 아니다. 채택하는 쪽은 bean을 타입으로 주입받아 자기 `IDEMPOTENCY` 단계 interceptor
(`GrpcServerInterceptorChain.builder().stage(GrpcServerInterceptorStage.IDEMPOTENCY, ...)`) or from (`GrpcServerInterceptorChain.builder().stage(GrpcServerInterceptorStage.IDEMPOTENCY, ...)`)나 자기
its typed service adapter: `decide(...)` before the mutation, `recordCommit(...)` inside the mutation's typed service adapter에서 부른다: 변경 전에 `decide(...)`, 변경의 트랜잭션 안에서
transaction, `recordFailure(...)` on a terminal failure. Both record calls take the `GrpcClaimToken` `recordCommit(...)`, 끝난 실패에 `recordFailure(...)`. 두 기록 호출은 모두 `PROCEED` 판정이 실어 온
the `PROCEED` decision carried: a commit by an attempt whose claim was taken over is refused (its `GrpcClaimToken`을 받는다: claim을 넘겨준 시도의 커밋은 거절되고(그 트랜잭션은 롤백된다) 그 실패는
transaction rolls back) and its failure is ignored, so a slow owner cannot write over the attempt that 무시된다. 그래서 느린 주인이 claim을 가져간 시도를 덮어쓰지 못한다(ADR-GRPC-004).
took its claim (ADR-GRPC-004).
**Purge scheduling is the adopter's.** `GrpcOperationLedgerRetention.purgeExpired(now)` deletes **지우기 일정은 채택하는 쪽의 몫이다.** `GrpcOperationLedgerRetention.purgeExpired(now)`는 기한이 지난
expired finished rows in bounded batches (500 per statement) until a batch comes back short. The 끝난 행을 한계 있는 batch(문장 하나에 500)로 지우고, batch가 덜 차서 돌아오면 멈춘다. starter는 이것을
starter does not schedule it: it owns no scheduler and cannot know which replica should run it, and a 예약하지 않는다: scheduler를 가지지 않고 어느 replica가 돌려야 하는지 알 수 없으며, 예약된 bean은 모든
scheduled bean would force a task scheduler onto every deployment. The adopter calls it from its own 배포에 task scheduler를 강요하게 된다. 채택하는 쪽이 자기 scheduler에서 부른다(예: 한 시간마다).
scheduler (for example hourly); concurrent runs on several replicas are safe because the delete skips 지우기가 잠긴 행을 건너뛰므로 여러 replica에서 동시에 돌려도 안전하다. 한 번도 돌리지 않아도 안전하지만
locked rows. Running it never is safe but lets the table grow without bound. 테이블이 끝없이 커진다.
The commit must be recorded in the mutation's transaction and the TTL must be longer than the slowest 커밋은 변경의 트랜잭션 안에서 기록해야 하고 TTL은 키가 필요한 가장 느린 메서드보다 길어야 한다. 두
keyed method; both reasons are in ADR-GRPC-004. 이유는 모두 ADR-GRPC-004에 있다.