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