From 7e08fb46a2a1bc3ae9b331752b6ecbcfd3021c51 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 17:33:54 +0900 Subject: [PATCH] =?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가 조용히 넓어질 수 없다.