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에 있다.