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