review-followup Wave 2.5·Wave 3 라운드 1(P14·P17): 정합성 잔여 12행, gRPC 플랫폼 9 leaf·protobuf 플러그인+Buf

- P14(W2): inbox archive 종단 상태 보존, GraphQL platform context 누락 경고, fileserver 전이·quota·진행 중 upload 삭제,
  알림 profile 소실 재시도·lease fencing·body 읽기 기한, Mongo bulk write concern, Dynamic Target cross-origin 헤더(결정 23),
  S3 profile CONDITIONAL_RETIREMENT 주장 거부, sample 포스터 abort·reconcile 경합(결정 22)
- P17(W3): gRPC 18→9 leaf(registry), .proto는 protobuf Gradle 플러그인 + Buf CI(결정 18), hyeonworks→caskeleton,
  인증 식별자 Context 전달, 한계값 정합 검사, P5-new-2·3 결함 수정
- 오케스트레이터: 현황표 적용(완료 395·남음 359), 새 결함 행 9개, capability-status 「제거된 코드」 17행,
  계획서 Wave 3 상세 Task, by_area.py NEW-15+ KeyError 수정

검증: ./gradlew check architectureCheck verifyDependencyLocks --continue 통과(597 task),
./gradlew -p optional-platforms ci 통과, CapabilityStatusDocumentTest 통과

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
donghyeon-ka
2026-09-28 15:45:58 +09:00
co-authored by Claude Opus 5.5
parent 2c612cb95b
commit 3e2cbd54f1
299 changed files with 563 additions and 3368 deletions
+2 -2
View File
@@ -1,7 +1,7 @@
# Optional gRPC platforms
The default application does not depend on `grpc/*` or `grpc-advanced/*`, so those 18 projects are
kept out of the main multi-project build. This build preserves their existing project paths and
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.
```bash
@@ -1,8 +1,17 @@
# ADR-GRPC-002: Schema governance runs without protoc and without the Buf CLI
- Status: accepted
- 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`
- Scope: `:grpc:grpc-proto-contract`, `:grpc:grpc-codegen` (both removed)
> **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.
## Context
@@ -2,7 +2,7 @@
- Status: accepted
- Date: 2026-08-30
- Scope: `:grpc:grpc-core-api`, `:grpc:grpc-policy`, `:grpc:grpc-testkit`
- Scope: `:grpc:grpc-core-api`, `:grpc:grpc-runtime` (was `grpc-policy`), `:grpc:grpc-testkit`
## Context
@@ -2,7 +2,7 @@
- Status: accepted
- Date: 2026-08-30
- Scope: `:grpc:grpc-policy`, `:grpc:grpc-operation-ledger-jpa`, `:grpc:grpc-core-api`
- Scope: `:grpc:grpc-runtime` (was `grpc-policy`), `:grpc:grpc-operation-ledger-jpa`, `:grpc:grpc-core-api`
## Context
@@ -2,7 +2,7 @@
- Status: accepted
- Date: 2026-08-30
- Scope: `:grpc:grpc-policy`
- Scope: `:grpc:grpc-runtime` (was `grpc-policy`)
## Context
@@ -2,7 +2,7 @@
- Status: accepted
- Date: 2026-08-31
- Scope: `:grpc:grpc-discovery`, `:grpc:grpc-client`
- Scope: `:grpc:grpc-runtime` (was `grpc-discovery`, `grpc-client`)
## Context
@@ -63,6 +63,6 @@ declaration is a wrong statement somebody wrote down, and a missing one is a que
`GrpcChannelProfileValidator` takes resolved counts where they are known at startup and skips the
check where they are not, rather than guessing and failing on a name that cannot be resolved yet.
**xDS is reachable, and not by this route.** It lives in `grpc-advanced-resilience` behind its
**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.
+6 -6
View File
@@ -53,13 +53,13 @@ tested the adapter and not the transport.
| | Where it lives |
| --- | --- |
| Client streaming, bidirectional streaming | `grpc-advanced-streaming` |
| Manual flow control | `grpc-advanced-streaming` |
| Hedging | `grpc-advanced-resilience` |
| Custom name resolver, custom load balancer | `grpc-advanced-resilience` |
| xDS | `grpc-advanced-resilience` |
| Client streaming, bidirectional streaming | `grpc-advanced` (`streaming`) |
| Manual flow control | `grpc-advanced` (`streaming`) |
| Hedging | `grpc-advanced` (`resilience`) |
| Custom name resolver, custom 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 diagnostics | `grpc-advanced` (`diagnostics`) |
## Current release status
@@ -39,6 +39,13 @@ src/adapter/inbound/grpc 기존 인바운드 전송 어댑터 (
원본 모듈 경계 중 **이 저장소가 이미 다른 메커니즘으로 표현하는 것**만 합친다. 능력(capability)은
하나도 버리지 않는다.
> **2026-09-28 변경(리뷰 후속 S7-#3·S7-#13, 소유자 결정 18).** 아래 두 표는 채택 당시의 leaf 구성이다.
> 현재는 `grpc-policy`·`grpc-server`·`grpc-client`·`grpc-discovery`·`grpc-admin` → `grpc-runtime`,
> `grpc-proto-contract`·`grpc-codegen` → `grpc-contract`(protobuf Gradle 플러그인 + CI의 Buf, D5/D6 폐기 —
> ADR-GRPC-002 superseded), `grpc-advanced-bootstrap`·`-edition`·`-streaming`·`-resilience`·`-diagnostics`
> → `grpc-advanced`로 합쳐졌다. `grpc-advanced-compat`은 그대로다. 패키지 이름은 바뀌지 않았다. 현재
> leaf 목록은 registry(`src/config/architecture/modules.json`)가 SSOT다.
### Stable — `src/grpc/`
| leaf | 원본 모듈 | 담는 Task | 의존 |
+13 -8
View File
@@ -37,14 +37,19 @@ property key는 `ca-skeleton.grpc.advanced.<capability>.enabled`이고 전부
## Leaf별 담당 capability
| leaf | capability |
| --- | --- |
| `grpc-advanced-bootstrap` | capability grade, feature flag, module guard, capability별 promotion gate |
| `grpc-advanced-edition` | Protobuf Edition 2024 opt-in lane, Edition 2026 watch lane |
| `grpc-advanced-streaming` | client streaming(session/dedup/checkpoint), bidi(dual sequence), manual flow control |
| `grpc-advanced-resilience` | read-only hedging, custom name resolver SPI, custom load balancer SPI, proxyless xDS |
| `grpc-advanced-compat` | gRPC-Web, Spring Integration bridge, Reactor adapter, Kotlin coroutine 취소 bridge |
| `grpc-advanced-diagnostics` | Channelz/CSDS 진단 |
| leaf | 패키지(`dev.caskeleton.grpc.advanced.*`) | capability |
| --- | --- | --- |
| `grpc-advanced` | `bootstrap` | capability grade, feature flag, module guard, capability별 promotion gate |
| `grpc-advanced` | `edition` | Protobuf Edition 2024 opt-in lane, Edition 2026 watch lane |
| `grpc-advanced` | `streaming` | client streaming(session/dedup/checkpoint), bidi(dual sequence), manual flow control |
| `grpc-advanced` | `resilience`·`discovery`·`xds` | read-only hedging, custom name resolver SPI, custom load balancer SPI, proxyless xDS |
| `grpc-advanced` | `diagnostics` | Channelz/CSDS 진단 |
| `grpc-advanced-compat` | `web`·`integration`·`reactor`·`kotlin` | gRPC-Web, Spring Integration bridge, Reactor adapter, Kotlin coroutine 취소 bridge |
`grpc-advanced-compat`만 따로 있는 이유는 Reactor·Spring Integration이라는 실제 의존성 경계다. 나머지
다섯 capability는 framework 의존이 없어 한 leaf에 있다(2026-09-28까지는 leaf 다섯 개). capability별
독립은 leaf 경계가 아니라 capability flag와 promotion 레코드가 보장한다. 참조 Envoy 설정은 jar에 싣지
않는 테스트 fixture(`grpc-advanced-compat/src/test/resources/envoy/envoy.yaml`)다.
## Promotion은 capability별로 독립이다
@@ -1,14 +0,0 @@
plugins {
id 'ca.platform-module'
}
// The Advanced boundary itself: capability grades, the `ca-skeleton.grpc.advanced.*` feature-flag
// contract, the module guard that refuses an unflagged capability, and the per-capability
// promotion gate.
//
// This leaf depends on Stable public types and never the other way round. The Stable starter's
// registry entry names no advanced id, so `verifyCleanArchitectureDependencies` is what makes
// "Advanced never leaks into Stable" a build failure rather than a review note.
dependencies {
api project(':grpc:grpc-core-api')
}
@@ -1,84 +0,0 @@
# This is a Gradle generated file for dependency locking.
# Manual edits can break the build and are not advised.
# This file is expected to be part of source control.
com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor
com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor
com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs
com.github.spotbugs:spotbugs:4.10.2=spotbugs
com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs
com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor
com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor
com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor
com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs
com.google.code.gson:gson:2.13.2=spotbugs
com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_annotations:2.41.0=spotbugs
com.google.errorprone:error_prone_annotations:2.47.0=checkstyle
com.google.errorprone:error_prone_annotations:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor
com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.guava:guava:33.5.0-jre=annotationProcessor,testAnnotationProcessor
com.google.guava:guava:33.6.0-jre=checkstyle
com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor
com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins
com.puppycrawl.tools:checkstyle:13.5.0=checkstyle
commons-beanutils:commons-beanutils:1.11.0=checkstyle
commons-collections:commons-collections:3.2.2=checkstyle
commons-io:commons-io:2.21.0=spotbugs
info.picocli:picocli:4.7.7=checkstyle
io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor
io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor
javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor
jaxen:jaxen:2.0.6=spotbugs
net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath
net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs
org.antlr:antlr4-runtime:4.13.2=checkstyle
org.apache.bcel:bcel:6.12.0=spotbugs
org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs
org.apache.commons:commons-text:1.15.0=spotbugs
org.apache.commons:commons-text:1.3=checkstyle
org.apache.httpcomponents:httpclient:4.5.13=checkstyle
org.apache.httpcomponents:httpcore:4.4.16=checkstyle
org.apache.logging.log4j:log4j-api:2.25.5=spotbugs
org.apache.logging.log4j:log4j-core:2.25.5=spotbugs
org.apache.maven.doxia:doxia-core:1.12.0=checkstyle
org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle
org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle
org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle
org.apache.xbean:xbean-reflect:3.7=checkstyle
org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath
org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath
org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle
org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle
org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle
org.codehaus.plexus:plexus-utils:3.3.0=checkstyle
org.dom4j:dom4j:2.2.0=spotbugs
org.javassist:javassist:3.28.0-GA=checkstyle
org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath
org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath
org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath
org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath
org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit:junit-bom:6.1.0=spotbugs
org.mockito:mockito-core:5.20.0=mockitoAgent
org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath
org.ow2.asm:asm-analysis:9.10.1=spotbugs
org.ow2.asm:asm-commons:9.10.1=spotbugs
org.ow2.asm:asm-tree:9.10.1=spotbugs
org.ow2.asm:asm-util:9.10.1=spotbugs
org.ow2.asm:asm:9.10.1=spotbugs
org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor
org.reflections:reflections:0.10.2=checkstyle
org.slf4j:slf4j-api:2.0.18=spotbugs,spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.18=checkstyle
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
empty=compileClasspath,runtimeClasspath
@@ -1,5 +1,7 @@
plugins {
id 'ca.platform-module'
// grpc-platform, not platform: grpc-runtime's io.grpc api dependencies are versionless and
// need the gRPC BOM on every classpath they reach.
id 'ca.grpc-platform-module'
}
// Compatibility bridges: gRPC-Web, the Spring Integration bridge, the Reactor adapter, and the
@@ -7,12 +9,12 @@ plugins {
//
// No Kotlin source set (adaptation D7): this repository has no Kotlin toolchain, so the Kotlin side
// is only the Java-side cancellation bridge; nothing here claims Kotlin support.
//
// The reference Envoy configuration is a test fixture (src/test/resources/envoy), not something
// this jar ships: a proxy configuration belongs to the deployment that runs the proxy.
dependencies {
api project(':grpc:grpc-core-api')
api project(':grpc:grpc-policy')
api project(':grpc:grpc-server')
api project(':grpc:grpc-client')
api project(':grpc-advanced:grpc-advanced-bootstrap')
api project(':grpc:grpc-runtime')
// api: the Reactor adapter's public signatures are Mono/Flux, and the Integration gateways name
// Spring Integration's Message. Hiding either would only stop an adopter compiling against the
@@ -27,7 +27,7 @@ class GrpcIntegrationBridgePolicyTest {
private static final GrpcMetadataKey CORRELATION = GrpcMetadataKey.ascii("x-correlation-id");
private static final GrpcMethodName GET =
GrpcMethodName.parse("hyeonworks.document.v1.DocumentService/GetDocument");
GrpcMethodName.parse("caskeleton.document.v1.DocumentService/GetDocument");
private static GrpcRequestContext requestContext() {
return GrpcRequestContext.create(
@@ -28,7 +28,7 @@ import reactor.util.context.Context;
class GrpcReactorContextBridgeTest {
private static final GrpcMethodName GET =
GrpcMethodName.parse("hyeonworks.document.v1.DocumentService/GetDocument");
GrpcMethodName.parse("caskeleton.document.v1.DocumentService/GetDocument");
private static final Instant NOW = Instant.parse("2026-08-30T10:00:00Z");
private static GrpcContextSnapshot snapshot() {
@@ -1,11 +0,0 @@
plugins {
id 'ca.platform-module'
}
// Channelz/CSDS diagnostics for administrators, with the redactor that keeps socket authority,
// credentials, certificate material, metadata and payload out of a snapshot.
dependencies {
api project(':grpc:grpc-core-api')
api project(':grpc:grpc-client')
api project(':grpc-advanced:grpc-advanced-bootstrap')
}
@@ -1,12 +0,0 @@
plugins {
id 'ca.platform-module'
}
// Protobuf Edition lanes. Edition 2024 is an opt-in Advanced lane that must produce cross-consumer
// compile evidence before anything public moves onto it; Edition 2026 is a watch lane that records
// release/toolchain status.
dependencies {
api project(':grpc:grpc-core-api')
api project(':grpc:grpc-proto-contract')
api project(':grpc-advanced:grpc-advanced-bootstrap')
}
@@ -1,13 +0,0 @@
plugins {
id 'ca.platform-module'
}
// Resilience and discovery capabilities that Stable refuses: read-only unary hedging, the custom
// name resolver SPI, the custom load balancer SPI, and the proxyless xDS experimental profile.
dependencies {
api project(':grpc:grpc-core-api')
api project(':grpc:grpc-policy')
api project(':grpc:grpc-client')
api project(':grpc:grpc-discovery')
api project(':grpc-advanced:grpc-advanced-bootstrap')
}
@@ -1,12 +0,0 @@
plugins {
id 'ca.platform-module'
}
// The streaming shapes the Stable plan deliberately excludes: client streaming sessions with
// dedup/checkpoint/resume, bidirectional sessions with independent per-direction sequences, and the
// manual flow-control approval API.
dependencies {
api project(':grpc:grpc-core-api')
api project(':grpc:grpc-policy')
api project(':grpc-advanced:grpc-advanced-bootstrap')
}
@@ -1,91 +0,0 @@
# This is a Gradle generated file for dependency locking.
# Manual edits can break the build and are not advised.
# This file is expected to be part of source control.
com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor
com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor
com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs
com.github.spotbugs:spotbugs:4.10.2=spotbugs
com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs
com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor
com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor
com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor
com.google.code.findbugs:jsr305:3.0.2=checkstyle,compileClasspath,runtimeClasspath,spotbugs,testCompileClasspath,testRuntimeClasspath
com.google.code.gson:gson:2.13.2=spotbugs
com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_annotations:2.28.0=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
com.google.errorprone:error_prone_annotations:2.41.0=spotbugs
com.google.errorprone:error_prone_annotations:2.47.0=checkstyle
com.google.errorprone:error_prone_annotations:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor
com.google.guava:failureaccess:1.0.2=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.guava:guava:33.2.1-android=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
com.google.guava:guava:33.5.0-jre=annotationProcessor,testAnnotationProcessor
com.google.guava:guava:33.6.0-jre=checkstyle
com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,compileClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath
com.google.j2objc:j2objc-annotations:3.0.0=compileClasspath,testCompileClasspath
com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor
com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins
com.puppycrawl.tools:checkstyle:13.5.0=checkstyle
commons-beanutils:commons-beanutils:1.11.0=checkstyle
commons-collections:commons-collections:3.2.2=checkstyle
commons-io:commons-io:2.21.0=spotbugs
info.picocli:picocli:4.7.7=checkstyle
io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor
io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor
io.grpc:grpc-api:1.68.1=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.grpc:grpc-stub:1.68.1=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor
jaxen:jaxen:2.0.6=spotbugs
net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath
net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs
org.antlr:antlr4-runtime:4.13.2=checkstyle
org.apache.bcel:bcel:6.12.0=spotbugs
org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs
org.apache.commons:commons-text:1.15.0=spotbugs
org.apache.commons:commons-text:1.3=checkstyle
org.apache.httpcomponents:httpclient:4.5.13=checkstyle
org.apache.httpcomponents:httpcore:4.4.16=checkstyle
org.apache.logging.log4j:log4j-api:2.25.5=spotbugs
org.apache.logging.log4j:log4j-core:2.25.5=spotbugs
org.apache.maven.doxia:doxia-core:1.12.0=checkstyle
org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle
org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle
org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle
org.apache.xbean:xbean-reflect:3.7=checkstyle
org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath
org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath
org.checkerframework:checker-qual:3.42.0=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle
org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle
org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle
org.codehaus.plexus:plexus-utils:3.3.0=checkstyle
org.dom4j:dom4j:2.2.0=spotbugs
org.javassist:javassist:3.28.0-GA=checkstyle
org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath
org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath
org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath
org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath
org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit:junit-bom:6.1.0=spotbugs
org.mockito:mockito-core:5.20.0=mockitoAgent
org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath
org.ow2.asm:asm-analysis:9.10.1=spotbugs
org.ow2.asm:asm-commons:9.10.1=spotbugs
org.ow2.asm:asm-tree:9.10.1=spotbugs
org.ow2.asm:asm-util:9.10.1=spotbugs
org.ow2.asm:asm:9.10.1=spotbugs
org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor
org.reflections:reflections:0.10.2=checkstyle
org.slf4j:slf4j-api:2.0.18=spotbugs,spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.18=checkstyle
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
empty=
+28
View File
@@ -0,0 +1,28 @@
plugins {
// grpc-platform, not platform: grpc-runtime's io.grpc api dependencies are versionless and
// need the gRPC BOM on every classpath they reach.
id 'ca.grpc-platform-module'
}
// The capabilities the Stable platform deliberately excludes, each behind its own capability flag:
//
// bootstrap capability grades, the `ca-skeleton.grpc.advanced.*` feature-flag contract, the
// module guard that refuses an unflagged capability, the per-capability promotion
// gate
// edition Protobuf Edition 2024 opt-in lane and Edition 2026 watch lane
// streaming client streaming sessions (dedup/checkpoint/resume), bidirectional sessions with
// independent per-direction sequences, the manual flow-control approval API
// resilience read-only unary hedging, custom name resolver / load balancer SPIs, proxyless xDS
// diagnostics Channelz/CSDS snapshots and the redactor that keeps secrets out of them
//
// These were five leaves until 2026-09-28. None of them carried a framework dependency of its own,
// and the only rule the split enforced — Stable never reaches Advanced — is expressed by the
// registry through the two prefixes (`grpc:*` may not depend on `grpc-advanced:*`), not by how many
// advanced leaves exist. `grpc-advanced-compat` stays separate because Reactor and Spring
// Integration are a real dependency boundary.
//
// This leaf depends on Stable public types and never the other way round.
dependencies {
api project(':grpc:grpc-core-api')
api project(':grpc:grpc-runtime')
}
@@ -24,10 +24,10 @@ class GrpcEdition2024PolicyTest {
void editionIsOptInPerModule() {
GrpcEdition2024Policy policy = GrpcEdition2024Policy.notAdopted();
assertThat(policy.allowedIn("grpc-proto-contract")).isFalse();
assertThat(policy.allowedIn("grpc-contract")).isFalse();
assertThat(
new GrpcEdition2024Policy(Set.of("grpc-advanced-edition"), Set.of(), false)
.allowedIn("grpc-advanced-edition"))
new GrpcEdition2024Policy(Set.of("grpc-advanced"), Set.of(), false)
.allowedIn("grpc-advanced"))
.isTrue();
}
@@ -36,18 +36,14 @@ class GrpcEdition2024PolicyTest {
void publicServicesNeedAPromotion() {
GrpcEdition2024Policy withoutPromotion =
new GrpcEdition2024Policy(
Set.of("grpc-advanced-edition"),
Set.of("hyeonworks.document.v1.DocumentService"),
false);
Set.of("grpc-advanced"), Set.of("caskeleton.document.v1.DocumentService"), false);
GrpcEdition2024Policy withPromotion =
new GrpcEdition2024Policy(
Set.of("grpc-advanced-edition"),
Set.of("hyeonworks.document.v1.DocumentService"),
true);
Set.of("grpc-advanced"), Set.of("caskeleton.document.v1.DocumentService"), true);
assertThat(withoutPromotion.serviceMayMove("hyeonworks.document.v1.DocumentService")).isFalse();
assertThat(withPromotion.serviceMayMove("hyeonworks.document.v1.DocumentService")).isTrue();
assertThat(withoutPromotion.serviceMayMove("hyeonworks.internal.v1.ScratchService")).isTrue();
assertThat(withoutPromotion.serviceMayMove("caskeleton.document.v1.DocumentService")).isFalse();
assertThat(withPromotion.serviceMayMove("caskeleton.document.v1.DocumentService")).isTrue();
assertThat(withoutPromotion.serviceMayMove("caskeleton.internal.v1.ScratchService")).isTrue();
}
@Test
@@ -17,11 +17,11 @@ import org.junit.jupiter.api.Test;
class GrpcHedgingEligibilityTest {
private static final GrpcMethodName GET =
GrpcMethodName.parse("hyeonworks.document.v1.DocumentService/GetDocument");
GrpcMethodName.parse("caskeleton.document.v1.DocumentService/GetDocument");
private static final GrpcMethodName CREATE =
GrpcMethodName.parse("hyeonworks.document.v1.DocumentService/CreateDocument");
GrpcMethodName.parse("caskeleton.document.v1.DocumentService/CreateDocument");
private static final GrpcMethodName WATCH =
GrpcMethodName.parse("hyeonworks.document.v1.DocumentService/WatchDocuments");
GrpcMethodName.parse("caskeleton.document.v1.DocumentService/WatchDocuments");
private static final GrpcDeadlineProfile TWO_SECONDS =
GrpcDeadlineProfile.of(Duration.ofSeconds(2));
@@ -30,7 +30,7 @@ class GrpcXdsProfileTest {
@Test
@DisplayName("an xDS profile requires an xds target, a namespace, mesh retries and mTLS")
void anXdsProfileRequiresItsFourConditions() {
assertThat(profile("hyeonworks/documents").target().getScheme()).isEqualTo("xds");
assertThat(profile("caskeleton/documents").target().getScheme()).isEqualTo("xds");
assertThatThrownBy(
() ->
new GrpcXdsProfile(
@@ -1,9 +1,9 @@
edition = "2024";
package hyeonworks.grpc.edition.v1;
package caskeleton.grpc.edition.v1;
option java_multiple_files = true;
option java_package = "hyeonworks.grpc.edition.v1.generated";
option java_package = "caskeleton.grpc.edition.v1.generated";
// The Edition 2024 comparison fixture.
//
+14 -10
View File
@@ -20,13 +20,8 @@ leaf의 정확한 id는 registry에서 읽는다.
| Family | 역할 | 허용 framework |
| --- | --- | --- |
| `grpc-core-api` | 식별자, method policy, 실행 증거, 실패 모델, deadline, request context, operation ledger port | **Java stdlib만.** io.grpc / Spring / protobuf / DB 타입 금지 |
| `grpc-proto-contract` | `.proto` 스키마 소스와 style/schema 규칙 검증기 | Java stdlib만 |
| `grpc-codegen` | Buf governance, codegen manifest, descriptor 릴리스 아티팩트 | Java stdlib만 |
| `grpc-policy` | validation, context, status/rich error, TLS/credential, deadline/cancellation, retry, idempotency, streaming, size/compression | `io.grpc:grpc-api`, `grpc-stub`. Spring 금지 |
| `grpc-server` | application boundary rule, typed service adapter SPI, interceptor 순서, Netty profile | `io.grpc:grpc-api`, `grpc-stub`. Netty 자체 금지 — profile은 설정 모델이다 |
| `grpc-client` | named channel, runtime generation, typed stub factory, client metadata/credentials | `io.grpc:grpc-api`, `grpc-stub` |
| `grpc-discovery` | Static/DNS resolver, pick_first/round_robin, Kubernetes routing profile | Java stdlib만 |
| `grpc-admin` | health, reflection, drain, secret-free policy snapshot | Java stdlib만 |
| `grpc-contract` | `.proto` 스키마 소스(`src/main/proto`)와 protoc 생성 message. lint/breaking은 Buf(`buf.yaml`, CI job `grpc-proto-buf`) | `protobuf-java`(생성 코드 runtime)만. 규칙을 Java로 재구현하지 않는다 |
| `grpc-runtime` | policy(validation, context, status/rich error, TLS/credential, deadline/cancellation, retry, idempotency, streaming, size/compression) · server(typed service adapter SPI, interceptor 순서, Netty profile) · client(named channel, runtime generation, typed stub factory) · discovery(Static/DNS, pick_first/round_robin, Kubernetes routing) · admin(health, reflection, drain, policy snapshot) | `io.grpc:grpc-api`, `grpc-stub`. Spring·Netty 자체 금지 — Netty profile은 설정 모델이다 |
| `grpc-observability` | bounded metric/trace convention | `io.micrometer:micrometer-core`만 |
| `grpc-operation-ledger-jpa` | mutation idempotency의 durable 저장 | `jakarta.persistence`, `spring-data-jpa`. **port는 core-api에 있다** |
| `grpc-spring-boot-starter` | 조립 경계, typed properties, startup validator | Spring Boot autoconfigure. 여기서만 |
@@ -35,7 +30,16 @@ leaf의 정확한 id는 registry에서 읽는다.
`grpc-core-api`가 io.grpc를 이름조차 부르지 않는다는 것이 이 family의 핵심 제약이다. 실행 증거와
실패 모델은 "전송이 무엇을 했는가"를 기술하는 계약이고, 그 계약 안에 전송 타입이 들어가면 계약이
전송의 일부가 된다. `GrpcStatusCode`가 io.grpc의 코드를 미러링하는 이유가 이것이고, 양방향 번역은
`grpc-policy`의 `GrpcStatusMapping`이 단독으로 소유한다.
`grpc-runtime`의 `GrpcStatusMapping`이 단독으로 소유한다.
기본 전송 한도(메시지 1 MiB, metadata 8 KiB)는 `grpc-core-api`의 `GrpcTransportLimits` 한 곳에 있고,
server profile·named channel profile·method size profile·method policy 기본값·metadata budget이 모두
그 상수를 쓴다. `GrpcPlatformStartupValidator`는 method의 inbound 한도가 server profile 한도보다 크면
기동을 거부한다.
`.proto`의 proto 조직 이름은 `caskeleton`이다(`package caskeleton.grpc.common.v1`, 생성 Java 패키지
`caskeleton.grpc.common.v1.generated` — 손으로 쓴 `dev.caskeleton`과 겹치지 않는다). 템플릿을 재사용할
때 바꾸는 방법은 `AGENTS.md` 「템플릿 재사용 체크리스트」에 있다.
## 증거 등급 — testkit이 하나의 leaf인 이유
@@ -72,7 +76,7 @@ capability flag 뒤에 있다. `GrpcPlatformStartupValidator`가 Stable catalog
## Optional build에 있다는 것의 의미
`grpc:*`와 `grpc-advanced:*`는 기본 `ca-skeleton` settings에 include되지 않는다. 따라서 일반
`:app-bootstrap:build`는 이 18개 project를 configure하지 않는다. 플랫폼 자체는
`:app-bootstrap:build`는 이 project들을 configure하지 않는다(목록은 registry의 `"build": "optional-grpc"`). 플랫폼 자체는
`./gradlew -p optional-platforms ci`로 검증하고, application runtime에 실제 채택하려면 composition root가
명시적으로 dependency를 가져오는 별도 변경이 필요하다.
@@ -85,7 +89,7 @@ soak/performance baseline을 자동으로 의미하지 않는다. 지원 범위
`messaging:*`의 MSG-015(bridge 부재)를 반복하지 않는 것이 이 family의 목표다. 계약상의 경로는
```text
application-owned port → adapter:inbound:grpc (typed service adapter) → :grpc:grpc-server SPI
application-owned port → adapter:inbound:grpc (typed service adapter) → :grpc:grpc-runtime SPI
```
이고 `GrpcServiceAdapter`가 그 SPI를 소유한다. inbound adapter가 outbound adapter·persistence에
-10
View File
@@ -1,10 +0,0 @@
plugins {
id 'ca.platform-module'
}
// Operational surface: the standard health registry, the reflection exposure policy, the drain
// coordinator, and the secret-free runtime policy snapshot an administrator reads.
dependencies {
api project(':grpc:grpc-core-api')
api project(':grpc:grpc-server')
}
-91
View File
@@ -1,91 +0,0 @@
# This is a Gradle generated file for dependency locking.
# Manual edits can break the build and are not advised.
# This file is expected to be part of source control.
com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor
com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor
com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs
com.github.spotbugs:spotbugs:4.10.2=spotbugs
com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs
com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor
com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor
com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor
com.google.code.findbugs:jsr305:3.0.2=checkstyle,compileClasspath,runtimeClasspath,spotbugs,testCompileClasspath,testRuntimeClasspath
com.google.code.gson:gson:2.13.2=spotbugs
com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_annotations:2.28.0=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
com.google.errorprone:error_prone_annotations:2.41.0=spotbugs
com.google.errorprone:error_prone_annotations:2.47.0=checkstyle
com.google.errorprone:error_prone_annotations:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor
com.google.guava:failureaccess:1.0.2=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.guava:guava:33.2.1-android=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
com.google.guava:guava:33.5.0-jre=annotationProcessor,testAnnotationProcessor
com.google.guava:guava:33.6.0-jre=checkstyle
com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,compileClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath
com.google.j2objc:j2objc-annotations:3.0.0=compileClasspath,testCompileClasspath
com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor
com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins
com.puppycrawl.tools:checkstyle:13.5.0=checkstyle
commons-beanutils:commons-beanutils:1.11.0=checkstyle
commons-collections:commons-collections:3.2.2=checkstyle
commons-io:commons-io:2.21.0=spotbugs
info.picocli:picocli:4.7.7=checkstyle
io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor
io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor
io.grpc:grpc-api:1.68.1=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.grpc:grpc-stub:1.68.1=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor
jaxen:jaxen:2.0.6=spotbugs
net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath
net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs
org.antlr:antlr4-runtime:4.13.2=checkstyle
org.apache.bcel:bcel:6.12.0=spotbugs
org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs
org.apache.commons:commons-text:1.15.0=spotbugs
org.apache.commons:commons-text:1.3=checkstyle
org.apache.httpcomponents:httpclient:4.5.13=checkstyle
org.apache.httpcomponents:httpcore:4.4.16=checkstyle
org.apache.logging.log4j:log4j-api:2.25.5=spotbugs
org.apache.logging.log4j:log4j-core:2.25.5=spotbugs
org.apache.maven.doxia:doxia-core:1.12.0=checkstyle
org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle
org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle
org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle
org.apache.xbean:xbean-reflect:3.7=checkstyle
org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath
org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath
org.checkerframework:checker-qual:3.42.0=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle
org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle
org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle
org.codehaus.plexus:plexus-utils:3.3.0=checkstyle
org.dom4j:dom4j:2.2.0=spotbugs
org.javassist:javassist:3.28.0-GA=checkstyle
org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath
org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath
org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath
org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath
org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit:junit-bom:6.1.0=spotbugs
org.mockito:mockito-core:5.20.0=mockitoAgent
org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath
org.ow2.asm:asm-analysis:9.10.1=spotbugs
org.ow2.asm:asm-commons:9.10.1=spotbugs
org.ow2.asm:asm-tree:9.10.1=spotbugs
org.ow2.asm:asm-util:9.10.1=spotbugs
org.ow2.asm:asm:9.10.1=spotbugs
org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor
org.reflections:reflections:0.10.2=checkstyle
org.slf4j:slf4j-api:2.0.18=spotbugs,spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.18=checkstyle
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
empty=
-14
View File
@@ -1,14 +0,0 @@
plugins {
id 'ca.grpc-platform-module'
}
// Client runtime: named channel profiles, channel runtime generations with drain, the typed stub
// factory that refuses to hand a raw Channel to application code, and client metadata/credentials.
dependencies {
api project(':grpc:grpc-core-api')
api project(':grpc:grpc-policy')
api "io.grpc:grpc-api"
api "io.grpc:grpc-stub"
}
-91
View File
@@ -1,91 +0,0 @@
# This is a Gradle generated file for dependency locking.
# Manual edits can break the build and are not advised.
# This file is expected to be part of source control.
com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor
com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor
com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs
com.github.spotbugs:spotbugs:4.10.2=spotbugs
com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs
com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor
com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor
com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor
com.google.code.findbugs:jsr305:3.0.2=checkstyle,compileClasspath,runtimeClasspath,spotbugs,testCompileClasspath,testRuntimeClasspath
com.google.code.gson:gson:2.13.2=spotbugs
com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_annotations:2.28.0=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
com.google.errorprone:error_prone_annotations:2.41.0=spotbugs
com.google.errorprone:error_prone_annotations:2.47.0=checkstyle
com.google.errorprone:error_prone_annotations:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor
com.google.guava:failureaccess:1.0.2=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.guava:guava:33.2.1-android=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
com.google.guava:guava:33.5.0-jre=annotationProcessor,testAnnotationProcessor
com.google.guava:guava:33.6.0-jre=checkstyle
com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,compileClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath
com.google.j2objc:j2objc-annotations:3.0.0=compileClasspath,testCompileClasspath
com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor
com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins
com.puppycrawl.tools:checkstyle:13.5.0=checkstyle
commons-beanutils:commons-beanutils:1.11.0=checkstyle
commons-collections:commons-collections:3.2.2=checkstyle
commons-io:commons-io:2.21.0=spotbugs
info.picocli:picocli:4.7.7=checkstyle
io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor
io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor
io.grpc:grpc-api:1.68.1=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.grpc:grpc-stub:1.68.1=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor
jaxen:jaxen:2.0.6=spotbugs
net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath
net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs
org.antlr:antlr4-runtime:4.13.2=checkstyle
org.apache.bcel:bcel:6.12.0=spotbugs
org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs
org.apache.commons:commons-text:1.15.0=spotbugs
org.apache.commons:commons-text:1.3=checkstyle
org.apache.httpcomponents:httpclient:4.5.13=checkstyle
org.apache.httpcomponents:httpcore:4.4.16=checkstyle
org.apache.logging.log4j:log4j-api:2.25.5=spotbugs
org.apache.logging.log4j:log4j-core:2.25.5=spotbugs
org.apache.maven.doxia:doxia-core:1.12.0=checkstyle
org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle
org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle
org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle
org.apache.xbean:xbean-reflect:3.7=checkstyle
org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath
org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath
org.checkerframework:checker-qual:3.42.0=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle
org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle
org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle
org.codehaus.plexus:plexus-utils:3.3.0=checkstyle
org.dom4j:dom4j:2.2.0=spotbugs
org.javassist:javassist:3.28.0-GA=checkstyle
org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath
org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath
org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath
org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath
org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit:junit-bom:6.1.0=spotbugs
org.mockito:mockito-core:5.20.0=mockitoAgent
org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath
org.ow2.asm:asm-analysis:9.10.1=spotbugs
org.ow2.asm:asm-commons:9.10.1=spotbugs
org.ow2.asm:asm-tree:9.10.1=spotbugs
org.ow2.asm:asm-util:9.10.1=spotbugs
org.ow2.asm:asm:9.10.1=spotbugs
org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor
org.reflections:reflections:0.10.2=checkstyle
org.slf4j:slf4j-api:2.0.18=spotbugs,spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.18=checkstyle
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
empty=
-14
View File
@@ -1,14 +0,0 @@
plugins {
id 'ca.platform-module'
}
// Contract governance: Buf format/lint/breaking policy, the single codegen owner declaration, and
// the descriptor/schema-hash release artifact with its consumer-compile gate.
//
// The Buf rules are implemented here rather than shelled out to the Buf CLI (adaptation D5): the
// CLI is not present in this toolchain, and a gate that silently no-ops when a binary is missing is
// worse than one that computes the same judgement from the committed schema.
dependencies {
api project(':grpc:grpc-core-api')
api project(':grpc:grpc-proto-contract')
}
-84
View File
@@ -1,84 +0,0 @@
# This is a Gradle generated file for dependency locking.
# Manual edits can break the build and are not advised.
# This file is expected to be part of source control.
com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor
com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor
com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs
com.github.spotbugs:spotbugs:4.10.2=spotbugs
com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs
com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor
com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor
com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor
com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs
com.google.code.gson:gson:2.13.2=spotbugs
com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_annotations:2.41.0=spotbugs
com.google.errorprone:error_prone_annotations:2.47.0=checkstyle
com.google.errorprone:error_prone_annotations:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor
com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.guava:guava:33.5.0-jre=annotationProcessor,testAnnotationProcessor
com.google.guava:guava:33.6.0-jre=checkstyle
com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor
com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins
com.puppycrawl.tools:checkstyle:13.5.0=checkstyle
commons-beanutils:commons-beanutils:1.11.0=checkstyle
commons-collections:commons-collections:3.2.2=checkstyle
commons-io:commons-io:2.21.0=spotbugs
info.picocli:picocli:4.7.7=checkstyle
io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor
io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor
javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor
jaxen:jaxen:2.0.6=spotbugs
net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath
net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs
org.antlr:antlr4-runtime:4.13.2=checkstyle
org.apache.bcel:bcel:6.12.0=spotbugs
org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs
org.apache.commons:commons-text:1.15.0=spotbugs
org.apache.commons:commons-text:1.3=checkstyle
org.apache.httpcomponents:httpclient:4.5.13=checkstyle
org.apache.httpcomponents:httpcore:4.4.16=checkstyle
org.apache.logging.log4j:log4j-api:2.25.5=spotbugs
org.apache.logging.log4j:log4j-core:2.25.5=spotbugs
org.apache.maven.doxia:doxia-core:1.12.0=checkstyle
org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle
org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle
org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle
org.apache.xbean:xbean-reflect:3.7=checkstyle
org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath
org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath
org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle
org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle
org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle
org.codehaus.plexus:plexus-utils:3.3.0=checkstyle
org.dom4j:dom4j:2.2.0=spotbugs
org.javassist:javassist:3.28.0-GA=checkstyle
org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath
org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath
org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath
org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath
org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit:junit-bom:6.1.0=spotbugs
org.mockito:mockito-core:5.20.0=mockitoAgent
org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath
org.ow2.asm:asm-analysis:9.10.1=spotbugs
org.ow2.asm:asm-commons:9.10.1=spotbugs
org.ow2.asm:asm-tree:9.10.1=spotbugs
org.ow2.asm:asm-util:9.10.1=spotbugs
org.ow2.asm:asm:9.10.1=spotbugs
org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor
org.reflections:reflections:0.10.2=checkstyle
org.slf4j:slf4j-api:2.0.18=spotbugs,spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.18=checkstyle
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
empty=compileClasspath,runtimeClasspath
@@ -1,43 +0,0 @@
package dev.caskeleton.grpc.codegen;
/**
* The Buf breaking-change categories, ordered from strictest to loosest.
*
* <p>The Stable gate is {@link #FILE}, and the reason is the pair of properties below: only FILE
* and PACKAGE detect a change that keeps the wire format identical while breaking every generated
* consumer's compile. A team that gates on WIRE ships a field rename, watches its own integration
* tests pass, and finds out at the consumer's next build.
*/
public enum GrpcBreakingCategory {
/** Strictest: also catches file moves, package moves and Java option changes. */
FILE(true, true),
/** Catches type and field source breaks within a package, but not a file move. */
PACKAGE(true, false),
/** Wire plus JSON name compatibility. Source breaks pass. */
WIRE_JSON(false, false),
/** Binary wire compatibility only. Source breaks pass. */
WIRE(false, false);
private final boolean detectsSourceBreak;
private final boolean detectsFileMove;
GrpcBreakingCategory(boolean detectsSourceBreak, boolean detectsFileMove) {
this.detectsSourceBreak = detectsSourceBreak;
this.detectsFileMove = detectsFileMove;
}
/** Whether this category fails a change that stops a generated consumer compiling. */
public boolean detectsSourceBreak() {
return detectsSourceBreak;
}
/** Whether this category fails a file or package relocation. */
public boolean detectsFileMove() {
return detectsFileMove;
}
/** The category the Stable public API is gated on. */
public static GrpcBreakingCategory stableGate() {
return FILE;
}
}
@@ -1,75 +0,0 @@
package dev.caskeleton.grpc.codegen;
import java.util.List;
import java.util.Set;
/**
* The schema governance this repository runs, as a value the build and the tests both read.
*
* <p>Buf's CLI is not part of this toolchain (adaptation D5), so the four lifecycle task names
* below are the contract a CI environment fulfils and {@code GrpcProtoContractValidator} is what
* actually fails a build here. Keeping the task names in the policy rather than only in a workflow
* file means a missing stage is a test failure rather than a stage nobody noticed was gone.
*/
public record GrpcBufPolicy(
GrpcBreakingCategory breakingCategory,
boolean formatEnforced,
boolean lintEnforced,
GrpcSchemaBaseline baseline) {
/** The lifecycle stages a compliant schema pipeline runs, in order. */
private static final List<String> REQUIRED_TASKS =
List.of("bufFormatCheck", "bufLint", "bufBuild", "bufBreaking");
/** Refuses a policy that would let a source break through. */
public GrpcBufPolicy {
if (breakingCategory == null) {
throw new IllegalArgumentException("a Buf policy needs a breaking category");
}
if (baseline == null) {
throw new IllegalArgumentException(
"a Buf policy needs a released baseline to compare against");
}
if (!breakingCategory.detectsSourceBreak()) {
throw new IllegalArgumentException(
"the Stable public API may not be gated on "
+ breakingCategory
+ ": wire compatibility alone lets a rename through as compatible while every "
+ "generated consumer stops compiling");
}
if (!formatEnforced || !lintEnforced) {
throw new IllegalArgumentException(
"format and lint are not optional; a schema that is not linted is a schema whose style "
+ "rules are whatever the last author preferred");
}
}
/** The Stable policy: FILE breaking, format and lint enforced. */
public static GrpcBufPolicy stable(GrpcSchemaBaseline baseline) {
return new GrpcBufPolicy(GrpcBreakingCategory.stableGate(), true, true, baseline);
}
/** The lifecycle task names a compliant pipeline registers. */
public static List<String> requiredTasks() {
return REQUIRED_TASKS;
}
/**
* The task names missing from {@code registeredTasks}.
*
* @return an empty set when the pipeline is complete
*/
public static Set<String> missingTasks(Set<String> registeredTasks) {
if (registeredTasks == null) {
throw new IllegalArgumentException("the registered task set must not be null");
}
return REQUIRED_TASKS.stream()
.filter(task -> !registeredTasks.contains(task))
.collect(java.util.stream.Collectors.toUnmodifiableSet());
}
/** Whether a candidate schema hash may be released without a breaking review. */
public boolean unchangedFromBaseline(String candidateSchemaHash) {
return baseline.matches(candidateSchemaHash);
}
}
@@ -1,81 +0,0 @@
package dev.caskeleton.grpc.codegen;
/**
* Who generates Java from the schema, with what versions, into where.
*
* <p>One owner, named. Two generators for one schema is the state in which a type exists twice with
* different options and the classpath decides which one a consumer gets; refusing a second owner is
* cheaper than diagnosing that.
*
* <p>Both version sources are required to be the managed BOM rather than a literal. A pinned
* protobuf version beside a BOM-managed gRPC version is how the runtime and the generator drift
* into a combination nobody tested, and the symptom is a {@code NoSuchMethodError} in generated
* code.
*/
public record GrpcCodegenManifest(
String codegenOwner,
String protobufVersionSource,
String grpcJavaVersionSource,
GrpcCodegenOutput output,
GrpcGeneratedPackagePolicy packagePolicy) {
/** The only accepted version source: whatever the build's managed platform resolves. */
public static final String MANAGED_VERSION_SOURCE = "managed-platform";
/** Refuses a second owner, a literal version, or overlapping package namespaces. */
public GrpcCodegenManifest {
if (codegenOwner == null || codegenOwner.isBlank()) {
throw new IllegalArgumentException("code generation needs exactly one named owner");
}
if (output == null || packagePolicy == null) {
throw new IllegalArgumentException("a codegen manifest needs an output and a package policy");
}
requireManagedVersion(protobufVersionSource, "protobuf");
requireManagedVersion(grpcJavaVersionSource, "grpc-java");
packagePolicy.requireDisjoint();
}
private static void requireManagedVersion(String source, String what) {
if (!MANAGED_VERSION_SOURCE.equals(source)) {
throw new IllegalArgumentException(
what
+ " version must come from the managed platform, not from a literal declaration; got '"
+ source
+ "'. A pinned generator beside a managed runtime is a combination nobody tested.");
}
}
/**
* This repository's manifest.
*
* <p>The owner is the Gradle protobuf plugin. It does not run in this build yet — adaptation D6
* records why, and this manifest is what a future decision to turn it on has to satisfy rather
* than replace.
*/
public static GrpcCodegenManifest caSkeleton() {
return new GrpcCodegenManifest(
"gradle-protobuf-plugin",
MANAGED_VERSION_SOURCE,
MANAGED_VERSION_SOURCE,
GrpcCodegenOutput.standard(),
new GrpcGeneratedPackagePolicy(
java.util.Set.of("dev.caskeleton"),
java.util.Set.of("hyeonworks.grpc.common.v1.generated")));
}
/**
* Fails when a second generator claims the same schema.
*
* @throws IllegalStateException when {@code otherOwner} is not this manifest's owner
*/
public void requireSoleOwner(String otherOwner) {
if (!codegenOwner.equals(otherOwner)) {
throw new IllegalStateException(
"Java code generation for this schema is owned by '"
+ codegenOwner
+ "'; '"
+ otherOwner
+ "' may not also generate it");
}
}
}
@@ -1,58 +0,0 @@
package dev.caskeleton.grpc.codegen;
/**
* Where generated artifacts land.
*
* <p>Everything here is required to be inside a build directory. A generator that writes into a
* source tree produces files that get committed, then edited, then silently reverted by the next
* regeneration — and the diff that reverts them looks like the generator working correctly.
*/
public record GrpcCodegenOutput(
String javaOutputDirectory,
String grpcJavaOutputDirectory,
String descriptorSetPath,
boolean includeSourceInfo) {
private static final String BUILD_ROOT = "build/";
/** Requires every path to be build-directory relative. */
public GrpcCodegenOutput {
requireBuildRelative(javaOutputDirectory, "java output directory");
requireBuildRelative(grpcJavaOutputDirectory, "grpc-java output directory");
requireBuildRelative(descriptorSetPath, "descriptor set path");
if (!descriptorSetPath.endsWith(".desc") && !descriptorSetPath.endsWith(".binpb")) {
throw new IllegalArgumentException(
"a descriptor set is a serialized FileDescriptorSet; expected a .desc or .binpb path, got '"
+ descriptorSetPath
+ "'");
}
}
private static void requireBuildRelative(String path, String what) {
if (path == null || path.isBlank()) {
throw new IllegalArgumentException(what + " must not be blank");
}
if (path.startsWith("/") || path.contains("..")) {
throw new IllegalArgumentException(
what + " must be a project-relative path without '..'; got '" + path + "'");
}
if (!path.startsWith(BUILD_ROOT)) {
throw new IllegalArgumentException(
what
+ " must be under '"
+ BUILD_ROOT
+ "'; generated sources in a source tree get committed and then edited. Got '"
+ path
+ "'");
}
}
/** This repository's layout. */
public static GrpcCodegenOutput standard() {
return new GrpcCodegenOutput(
"build/generated/source/proto/main/java",
"build/generated/source/proto/main/grpc",
"build/generated/descriptor/stable-schema.desc",
true);
}
}
@@ -1,158 +0,0 @@
package dev.caskeleton.grpc.codegen;
import java.util.ArrayList;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Set;
/**
* A previously released consumer, described by exactly what it compiles against.
*
* <p>This is the check a wire-compatibility gate cannot make. A field rename, a service move to a
* new package, or a change to {@code java_package} keeps every serialized message valid and stops
* every generated client compiling — and the only way to notice before the consumer does is to keep
* a record of what the consumer names and compare a candidate schema against it.
*/
public record GrpcConsumerFixture(
String name,
String schemaVersion,
Set<String> requiredServicePaths,
Set<String> requiredMethodPaths,
Set<String> requiredJavaPackages) {
/** What kind of source break a consumer hit. Reported separately, never merged into one count. */
public enum BreakKind {
/** A service the consumer names is gone or moved. */
SERVICE_PATH,
/** A method the consumer calls is gone or renamed. */
METHOD_PATH,
/** The Java package the consumer imports from moved. */
JAVA_PACKAGE
}
/** One thing a consumer needs that a candidate schema no longer provides. */
public record SourceBreak(BreakKind kind, String missing) {
/** Requires both halves. */
public SourceBreak {
if (kind == null || missing == null || missing.isBlank()) {
throw new IllegalArgumentException("a source break names its kind and what went missing");
}
}
}
/** Copies every requirement set. */
public GrpcConsumerFixture {
if (name == null || name.isBlank()) {
throw new IllegalArgumentException("a consumer fixture needs a name");
}
if (schemaVersion == null || schemaVersion.isBlank()) {
throw new IllegalArgumentException(
"a consumer fixture names the schema version it was built against");
}
if (requiredServicePaths == null
|| requiredMethodPaths == null
|| requiredJavaPackages == null) {
throw new IllegalArgumentException("a consumer fixture states all three requirement sets");
}
requiredServicePaths = Set.copyOf(requiredServicePaths);
requiredMethodPaths = Set.copyOf(requiredMethodPaths);
requiredJavaPackages = Set.copyOf(requiredJavaPackages);
}
/**
* Derives a fixture from a released consumer's own source.
*
* <p>Read from the consumer rather than declared beside it, because a hand-written requirement
* list is a second copy of what the client already says and the copy is the one that stops being
* updated. Three rules, all mechanical:
*
* <ul>
* <li>a generated Java package is any package a {@code fixture} class imports from;
* <li>a service is a {@code <Name>Grpc} import, mapped back to {@code <package>.<Name>} with
* the generated-package suffix removed;
* <li>a method is a {@code stub.<name>(} call, mapped to {@code <service>/<UpperCamelName>}.
* </ul>
*
* <p>It is an approximation of compiling the fixture, which is what the plan asks for and what
* ADR-GRPC-002 records this repository cannot do yet. It is a useful approximation because it
* fails on exactly the changes a compile would fail on: a renamed method, a moved service, a
* relocated Java package.
*
* @param generatedPackageSuffix the segment appended to a proto package for generated code, e.g.
* {@code generated}; removed to recover the schema's own service path
*/
public static GrpcConsumerFixture fromJavaSource(
String name, String schemaVersion, String javaSource, String generatedPackageSuffix) {
if (javaSource == null || javaSource.isBlank()) {
throw new IllegalArgumentException("a consumer fixture needs its source text");
}
if (generatedPackageSuffix == null || generatedPackageSuffix.isBlank()) {
throw new IllegalArgumentException("the generated package suffix is required");
}
java.util.Set<String> javaPackages = new LinkedHashSet<>();
java.util.Set<String> servicePaths = new LinkedHashSet<>();
java.util.regex.Matcher imports =
java.util.regex.Pattern.compile(
"^\\s*import\\s+([\\w.]+)\\.(\\w+);", java.util.regex.Pattern.MULTILINE)
.matcher(javaSource);
while (imports.find()) {
String importedPackage = imports.group(1);
String importedType = imports.group(2);
if (!importedPackage.endsWith("." + generatedPackageSuffix)) {
continue;
}
javaPackages.add(importedPackage);
if (importedType.endsWith("Grpc")) {
String protoPackage =
importedPackage.substring(
0, importedPackage.length() - generatedPackageSuffix.length() - 1);
servicePaths.add(
protoPackage
+ "."
+ importedType.substring(0, importedType.length() - "Grpc".length()));
}
}
java.util.Set<String> methodPaths = new LinkedHashSet<>();
java.util.regex.Matcher calls =
java.util.regex.Pattern.compile("\\bstub\\.(\\w+)\\s*\\(").matcher(javaSource);
while (calls.find()) {
String method = calls.group(1);
String upperCamel = Character.toUpperCase(method.charAt(0)) + method.substring(1);
servicePaths.forEach(service -> methodPaths.add(service + "/" + upperCamel));
}
if (servicePaths.isEmpty() || methodPaths.isEmpty()) {
throw new IllegalArgumentException(
"no service or method could be derived from '"
+ name
+ "'; a fixture that requires nothing cannot detect a break");
}
return new GrpcConsumerFixture(name, schemaVersion, servicePaths, methodPaths, javaPackages);
}
/**
* What this consumer would fail to compile against {@code candidate}.
*
* @return an empty list when the consumer still compiles
*/
public List<SourceBreak> breaksAgainst(GrpcDescriptorArtifact candidate) {
if (candidate == null) {
throw new IllegalArgumentException("a compatibility check needs a candidate artifact");
}
List<SourceBreak> breaks = new ArrayList<>();
collect(breaks, BreakKind.SERVICE_PATH, requiredServicePaths, candidate.servicePaths());
collect(breaks, BreakKind.METHOD_PATH, requiredMethodPaths, candidate.methodPaths());
collect(
breaks, BreakKind.JAVA_PACKAGE, requiredJavaPackages, candidate.generatedJavaPackages());
return List.copyOf(breaks);
}
private static void collect(
List<SourceBreak> breaks, BreakKind kind, Set<String> required, Set<String> available) {
Set<String> missing = new LinkedHashSet<>(required);
missing.removeAll(available);
missing.stream().sorted().forEach(entry -> breaks.add(new SourceBreak(kind, entry)));
}
}
@@ -1,59 +0,0 @@
package dev.caskeleton.grpc.codegen;
import java.util.Set;
/**
* One immutable release of the schema: what it contains, and the hashes that prove which bytes it
* was built from.
*
* <p>Service and method paths are carried explicitly, not derived on demand, because they are what
* a consumer compatibility check compares. A descriptor that only carries a digest can say
* "something changed" and nothing else, which is the answer least useful to the person who has to
* decide whether to release.
*/
public record GrpcDescriptorArtifact(
String schemaVersion,
String schemaHash,
String descriptorSetDigest,
String bufImageDigest,
String policyVersion,
Set<String> servicePaths,
Set<String> methodPaths,
Set<String> generatedJavaPackages) {
/** Requires an immutable version, three digests and a non-empty surface. */
public GrpcDescriptorArtifact {
if (schemaVersion == null || schemaVersion.isBlank() || schemaVersion.endsWith("-SNAPSHOT")) {
throw new IllegalArgumentException(
"a schema artifact publishes an immutable version; got '" + schemaVersion + "'");
}
requireDigest(schemaHash, "schema hash");
requireDigest(descriptorSetDigest, "descriptor set digest");
requireDigest(bufImageDigest, "buf image digest");
if (policyVersion == null || policyVersion.isBlank()) {
throw new IllegalArgumentException(
"a schema artifact records the policy version it was judged under");
}
if (servicePaths == null || methodPaths == null || generatedJavaPackages == null) {
throw new IllegalArgumentException(
"a schema artifact carries its service, method and package surface");
}
if (methodPaths.isEmpty()) {
throw new IllegalArgumentException("a schema artifact with no methods describes nothing");
}
servicePaths = Set.copyOf(servicePaths);
methodPaths = Set.copyOf(methodPaths);
generatedJavaPackages = Set.copyOf(generatedJavaPackages);
}
private static void requireDigest(String digest, String what) {
if (digest == null || !digest.startsWith("sha256:") || digest.length() < 15) {
throw new IllegalArgumentException(what + " must be 'sha256:<digest>'; got '" + digest + "'");
}
}
/** Whether this artifact is byte-identical to {@code baseline}. */
public boolean unchangedFrom(GrpcSchemaBaseline baseline) {
return baseline.matches(schemaHash);
}
}
@@ -1,68 +0,0 @@
package dev.caskeleton.grpc.codegen;
import java.util.ArrayList;
import java.util.List;
import java.util.Set;
/**
* Keeps generated Java packages and hand-written ones apart.
*
* <p>An overlap is not a style problem. Generated code is deleted and rewritten on every build, so
* a hand-written class that shares its package is one clean build away from being either
* overwritten or, more often, from making the generator's output unbuildable in a way that reads as
* a compiler bug. Splitting the namespaces makes the ownership of every file legible from its
* package alone.
*/
public record GrpcGeneratedPackagePolicy(
Set<String> handWrittenPackages, Set<String> generatedPackages) {
/** Copies both sets. */
public GrpcGeneratedPackagePolicy {
if (handWrittenPackages == null || generatedPackages == null) {
throw new IllegalArgumentException("both package sets must be present");
}
if (generatedPackages.isEmpty()) {
throw new IllegalArgumentException("a codegen policy names at least one generated package");
}
handWrittenPackages = Set.copyOf(handWrittenPackages);
generatedPackages = Set.copyOf(generatedPackages);
}
/**
* Every overlap between the two namespaces, described.
*
* @return an empty list when the namespaces are disjoint
*/
public List<String> overlaps() {
List<String> overlaps = new ArrayList<>();
for (String generated : generatedPackages) {
for (String handWritten : handWrittenPackages) {
if (generated.equals(handWritten)
|| generated.startsWith(handWritten + ".")
|| handWritten.startsWith(generated + ".")) {
overlaps.add(
"generated package '"
+ generated
+ "' overlaps hand-written package '"
+ handWritten
+ "'");
}
}
}
overlaps.sort(java.util.Comparator.naturalOrder());
return List.copyOf(overlaps);
}
/**
* Fails when the namespaces overlap.
*
* @throws IllegalStateException naming every overlap
*/
public void requireDisjoint() {
List<String> overlaps = overlaps();
if (!overlaps.isEmpty()) {
throw new IllegalStateException(
"generated and hand-written Java packages must be disjoint: " + overlaps);
}
}
}
@@ -1,113 +0,0 @@
package dev.caskeleton.grpc.codegen;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
/**
* Decides whether a candidate schema may be published, and refuses to let a released version change
* underneath its consumers.
*
* <p>Two rules, and the second is the one that gets skipped in a hurry: a consumer fixture that no
* longer compiles blocks the release. Publishing anyway and telling the consumers is not the same
* thing — by then the artifact exists, somebody has resolved it, and the fix is a new version
* rather than a decision not to make the change.
*/
public final class GrpcSchemaArtifactPublisher {
private final GrpcBufPolicy policy;
private final Map<String, String> publishedHashesByVersion = new LinkedHashMap<>();
/** Binds a publisher to the governance policy it enforces. */
public GrpcSchemaArtifactPublisher(GrpcBufPolicy policy) {
if (policy == null) {
throw new IllegalArgumentException("a publisher needs a Buf policy");
}
this.policy = policy;
}
/** Whether a candidate may be published, and if not, why not. */
public record PublishDecision(boolean allowed, List<String> blockers) {
/** Copies the blocker list. */
public PublishDecision {
if (blockers == null) {
throw new IllegalArgumentException(
"a publish decision lists its blockers, even when empty");
}
blockers = List.copyOf(blockers);
if (allowed && !blockers.isEmpty()) {
throw new IllegalArgumentException("an allowed publish has no blockers");
}
if (!allowed && blockers.isEmpty()) {
throw new IllegalArgumentException("a refused publish says why");
}
}
}
/**
* Evaluates a candidate against the policy and every consumer fixture.
*
* @param fixtures the previously released consumers this schema must keep compiling
*/
public PublishDecision evaluate(
GrpcDescriptorArtifact candidate, List<GrpcConsumerFixture> fixtures) {
if (candidate == null || fixtures == null) {
throw new IllegalArgumentException("evaluation needs a candidate and a fixture list");
}
List<String> blockers = new ArrayList<>();
String alreadyPublished = publishedHashesByVersion.get(candidate.schemaVersion());
if (alreadyPublished != null && !alreadyPublished.equals(candidate.schemaHash())) {
blockers.add(
"version '"
+ candidate.schemaVersion()
+ "' is already published with a different schema hash; a released schema version is "
+ "immutable");
}
if (!policy.breakingCategory().detectsSourceBreak()) {
blockers.add("the active breaking category does not detect source breaks");
}
for (GrpcConsumerFixture fixture : fixtures) {
for (GrpcConsumerFixture.SourceBreak sourceBreak : fixture.breaksAgainst(candidate)) {
blockers.add(
"consumer '"
+ fixture.name()
+ "' ("
+ fixture.schemaVersion()
+ ") loses "
+ sourceBreak.kind()
+ " '"
+ sourceBreak.missing()
+ "'");
}
}
return new PublishDecision(blockers.isEmpty(), blockers);
}
/**
* Records a successful publish.
*
* @throws IllegalStateException when the decision refused it
*/
public void publish(GrpcDescriptorArtifact candidate, PublishDecision decision) {
if (decision == null || !decision.allowed()) {
throw new IllegalStateException(
"refusing to publish '"
+ (candidate == null ? "null" : candidate.schemaVersion())
+ "': "
+ (decision == null ? "no decision" : decision.blockers()));
}
publishedHashesByVersion.put(candidate.schemaVersion(), candidate.schemaHash());
}
/** The hash published for {@code version}, or null when nothing was. */
public String publishedHash(String version) {
return publishedHashesByVersion.get(version);
}
/** The governance policy in force. */
public GrpcBufPolicy policy() {
return policy;
}
}
@@ -1,37 +0,0 @@
package dev.caskeleton.grpc.codegen;
import java.time.Instant;
/**
* The released schema a breaking check compares against.
*
* <p>Pinned to a released artifact rather than to a branch, and that is the whole point. Comparing
* against the previous commit answers "did this commit break anything", which is not the question:
* a breaking change introduced two commits ago and refined since then passes every commit-to-commit
* check while being broken against everything that has actually been deployed.
*/
public record GrpcSchemaBaseline(String version, String schemaHash, Instant releasedAt) {
/** Requires an immutable version, a hash and a release moment. */
public GrpcSchemaBaseline {
if (version == null || version.isBlank()) {
throw new IllegalArgumentException("a schema baseline needs a released version");
}
if (version.endsWith("-SNAPSHOT")) {
throw new IllegalArgumentException(
"a breaking baseline must be an immutable release, not '" + version + "'");
}
if (schemaHash == null || !schemaHash.startsWith("sha256:") || schemaHash.length() < 15) {
throw new IllegalArgumentException(
"a schema baseline needs a 'sha256:<digest>' hash; got '" + schemaHash + "'");
}
if (releasedAt == null) {
throw new IllegalArgumentException("a schema baseline needs a release timestamp");
}
}
/** Whether {@code candidateHash} is byte-identical to this baseline. */
public boolean matches(String candidateHash) {
return schemaHash.equals(candidateHash);
}
}
@@ -1,88 +0,0 @@
package dev.caskeleton.grpc.codegen;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import java.time.Instant;
import java.util.Set;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
class GrpcBufPolicyTest {
private static final GrpcSchemaBaseline BASELINE =
new GrpcSchemaBaseline(
"1.4.0",
"sha256:0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0",
Instant.parse("2026-08-01T00:00:00Z"));
@Test
@DisplayName("the Stable public API is gated on the FILE breaking category")
void stablePublicApiUsesTheFileCategory() {
GrpcBufPolicy policy = GrpcBufPolicy.stable(BASELINE);
assertThat(policy.breakingCategory()).isEqualTo(GrpcBreakingCategory.FILE);
assertThat(GrpcBreakingCategory.stableGate()).isEqualTo(GrpcBreakingCategory.FILE);
assertThat(policy.breakingCategory().detectsSourceBreak()).isTrue();
assertThat(policy.breakingCategory().detectsFileMove()).isTrue();
}
@Test
@DisplayName("wire-only compatibility may not gate the Stable public API")
void wireOnlyCompatibilityIsRefused() {
assertThatThrownBy(() -> new GrpcBufPolicy(GrpcBreakingCategory.WIRE, true, true, BASELINE))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("stops compiling");
assertThatThrownBy(
() -> new GrpcBufPolicy(GrpcBreakingCategory.WIRE_JSON, true, true, BASELINE))
.isInstanceOf(IllegalArgumentException.class);
assertThat(GrpcBreakingCategory.WIRE.detectsSourceBreak()).isFalse();
assertThat(GrpcBreakingCategory.PACKAGE.detectsFileMove()).isFalse();
}
@Test
@DisplayName("format and lint are not optional")
void formatAndLintAreNotOptional() {
assertThatThrownBy(() -> new GrpcBufPolicy(GrpcBreakingCategory.FILE, false, true, BASELINE))
.isInstanceOf(IllegalArgumentException.class);
assertThatThrownBy(() -> new GrpcBufPolicy(GrpcBreakingCategory.FILE, true, false, BASELINE))
.isInstanceOf(IllegalArgumentException.class);
}
@Test
@DisplayName("the four lifecycle stages are named, and a missing one is reported")
void lifecycleStagesAreNamedAndChecked() {
assertThat(GrpcBufPolicy.requiredTasks())
.containsExactly("bufFormatCheck", "bufLint", "bufBuild", "bufBreaking");
assertThat(GrpcBufPolicy.missingTasks(Set.of("bufFormatCheck", "bufLint", "bufBuild")))
.containsExactly("bufBreaking");
assertThat(GrpcBufPolicy.missingTasks(Set.copyOf(GrpcBufPolicy.requiredTasks()))).isEmpty();
}
@Test
@DisplayName("the breaking baseline is a released version, never a snapshot")
void baselineIsAnImmutableRelease() {
assertThatThrownBy(
() ->
new GrpcSchemaBaseline(
"1.5.0-SNAPSHOT",
"sha256:0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0",
Instant.parse("2026-08-01T00:00:00Z")))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("immutable release");
assertThatThrownBy(
() ->
new GrpcSchemaBaseline(
"1.5.0", "not-a-digest", Instant.parse("2026-08-01T00:00:00Z")))
.isInstanceOf(IllegalArgumentException.class);
}
@Test
@DisplayName("an unchanged schema hash needs no breaking review")
void unchangedSchemaNeedsNoBreakingReview() {
GrpcBufPolicy policy = GrpcBufPolicy.stable(BASELINE);
assertThat(policy.unchangedFromBaseline(BASELINE.schemaHash())).isTrue();
assertThat(policy.unchangedFromBaseline("sha256:ffffffffffffffffffffffffffffffff")).isFalse();
}
}

Some files were not shown because too many files have changed in this diff Show More