refactor(platforms)!: gRPC 플랫폼을 별도 repo grpc-library로 옮기고 지운다 #6
@@ -39,5 +39,16 @@
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
"extraKnownMarketplaces": {
|
||||
"claude-harness": {
|
||||
"source": {
|
||||
"source": "git",
|
||||
"url": "https://git.learn.hyeonworks.com/donghyeon.kang/claude-harness.git"
|
||||
}
|
||||
}
|
||||
},
|
||||
"enabledPlugins": {
|
||||
"harness@claude-harness": true
|
||||
}
|
||||
}
|
||||
|
||||
@@ -62,70 +62,9 @@ jobs:
|
||||
- name: Refuse a top-level folder outside the allow list
|
||||
run: python3 scripts/check-repo-layout.py
|
||||
|
||||
optional-platforms:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
|
||||
- uses: ./.github/actions/setup-gradle-java
|
||||
- name: Verify the optional gRPC platform build
|
||||
working-directory: src
|
||||
run: ./gradlew -p platforms/optional-build ci --stacktrace
|
||||
# The optional build's own lane-reachability check: the main build's cannot see these lanes
|
||||
# (review 2026-11-03 RR-06-03).
|
||||
- name: Require every optional-platform strict lane to be in an executed stage
|
||||
working-directory: src
|
||||
run: ./gradlew -p platforms/optional-build :verifyStrictLaneStages --dry-run --stacktrace
|
||||
|
||||
# gRPC schema policy (owner decision 18). protoc compiles src/platforms/grpc/grpc-contract inside
|
||||
# the optional-platforms build above; lint and breaking-change policy belong to Buf, configured by
|
||||
# buf.yaml next to the schema. Buf is a native binary rather than a Maven artifact, so it runs here
|
||||
# and not inside Gradle — and nothing in the repository re-implements its rules.
|
||||
grpc-proto-buf:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
|
||||
with:
|
||||
# buf breaking reads the baseline schema from Git history.
|
||||
fetch-depth: 0
|
||||
- uses: bufbuild/buf-action@85aebf73123b5c15fd5528aaecbf9129cddf7fa7 # bufbuild/buf-action@v1.6.0
|
||||
with:
|
||||
version: 1.73.0
|
||||
setup_only: true
|
||||
- name: Lint the gRPC schema
|
||||
working-directory: src/platforms/grpc/grpc-contract
|
||||
run: buf lint
|
||||
- name: Refuse a breaking change to the gRPC schema
|
||||
working-directory: src/platforms/grpc/grpc-contract
|
||||
env:
|
||||
# Pull request: the target branch. Push: the commit this push replaced.
|
||||
BASELINE: ${{ github.event_name == 'pull_request' && format('origin/{0}', github.base_ref) || github.event.before }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
baseline_commit="$(git rev-parse --verify --quiet "${BASELINE}^{commit}" || true)"
|
||||
# The module moved from src/grpc to src/platforms/grpc on 2026-11-07. A baseline from
|
||||
# before the move holds it at the old path, and comparing against that path keeps the
|
||||
# breaking check running across the move instead of skipping it once.
|
||||
baseline_dir=""
|
||||
if [[ -n "${baseline_commit}" ]]; then
|
||||
for candidate in src/platforms/grpc/grpc-contract src/grpc/grpc-contract; do
|
||||
if git cat-file -e "${baseline_commit}:${candidate}/buf.yaml" 2>/dev/null; then
|
||||
baseline_dir="${candidate}"
|
||||
break
|
||||
fi
|
||||
done
|
||||
fi
|
||||
if [[ -z "${baseline_dir}" ]]; then
|
||||
# The first change that introduces the module has nothing to be compatible with.
|
||||
echo "::notice::grpc-proto-buf: baseline ${BASELINE} has no grpc-contract/buf.yaml; breaking check skipped."
|
||||
exit 0
|
||||
fi
|
||||
buf breaking --against "../../../../.git#ref=${baseline_commit},subdir=${baseline_dir}"
|
||||
|
||||
release-gate:
|
||||
needs:
|
||||
- quality-gates
|
||||
- optional-platforms
|
||||
- grpc-proto-buf
|
||||
if: always()
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
@@ -134,14 +73,10 @@ jobs:
|
||||
- name: Require every current blocking job to succeed
|
||||
env:
|
||||
QUALITY_RESULT: ${{ needs.quality-gates.result }}
|
||||
OPTIONAL_PLATFORMS_RESULT: ${{ needs.optional-platforms.result }}
|
||||
GRPC_PROTO_BUF_RESULT: ${{ needs.grpc-proto-buf.result }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
for result in \
|
||||
"${QUALITY_RESULT}" \
|
||||
"${OPTIONAL_PLATFORMS_RESULT}" \
|
||||
"${GRPC_PROTO_BUF_RESULT}"; do
|
||||
"${QUALITY_RESULT}"; do
|
||||
if [[ "${result}" != "success" ]]; then
|
||||
echo "::error::release-gate: required job result was ${result}"
|
||||
exit 1
|
||||
|
||||
@@ -202,12 +202,6 @@ jobs:
|
||||
- name: Run every performance-category strict lane
|
||||
working-directory: src
|
||||
run: ./gradlew :performanceCheck --continue --stacktrace
|
||||
# The optional gRPC build's performance lanes (grpcPerformanceTest). A separate build, so a
|
||||
# separate command; its own verifyStrictLaneStages counts this line (review 2026-11-03 RR-06-03).
|
||||
- name: Run every optional-platform performance-category strict lane
|
||||
if: always()
|
||||
working-directory: src
|
||||
run: ./gradlew -p platforms/optional-build performanceCheck --continue --stacktrace
|
||||
- name: Publish the performance lane reports
|
||||
if: always()
|
||||
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
|
||||
@@ -230,35 +224,6 @@ jobs:
|
||||
working-directory: src
|
||||
run: ./gradlew :adapter:outbound:httpclient:test -Phttp3.tests.enabled=true --stacktrace
|
||||
|
||||
# The optional gRPC platform build declares one strict INTEGRATION lane —
|
||||
# `grpc-operation-ledger-jpa:integrationTest`, which certifies the atomic
|
||||
# `INSERT ... ON CONFLICT DO NOTHING` claim that durable mutation idempotency rests on against a
|
||||
# real PostgreSQL. It was registered in Gradle, listed in `strictTestLanes`, and invoked by
|
||||
# nothing: `-p platforms/optional-build ci` reaches `checkAll`, `qualityCheck` and the dependency
|
||||
# verifier, none of which runs a lane whose category is INTEGRATION, and release.yml's gRPC gate
|
||||
# names only the three grpc-testkit lanes.
|
||||
#
|
||||
# Stage 2 rather than stage 1 for the same reason as every other job in this file: the lane starts
|
||||
# a Testcontainers PostgreSQL, and the pull-request budget is minutes for the whole gate.
|
||||
grpc-optional-platform-integration:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 45
|
||||
env:
|
||||
TESTCONTAINERS_REUSE_ENABLE: "false"
|
||||
steps:
|
||||
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
|
||||
- uses: ./.github/actions/setup-gradle-java
|
||||
- name: Certify the gRPC operation ledger against real PostgreSQL
|
||||
working-directory: src
|
||||
run: ./gradlew -p platforms/optional-build integrationCheck --stacktrace
|
||||
- name: Publish the optional-platform lane reports
|
||||
if: always()
|
||||
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
|
||||
with:
|
||||
name: grpc-optional-platform-integration-reports
|
||||
path: src/platforms/grpc*/**/build/reports/tests/
|
||||
if-no-files-found: warn
|
||||
|
||||
# Dynamic half of the compose-profile contract. Every blocking lane the matrix declares runs on
|
||||
# main and nightly; a partial lane run is reproduction only and cannot satisfy this job. The count
|
||||
# is not written here on purpose — a number in prose drifts the moment a lane is added, and the
|
||||
|
||||
@@ -108,49 +108,6 @@ jobs:
|
||||
path: src/adapter/inbound/websocket/build/reports/tests/
|
||||
if-no-files-found: error
|
||||
|
||||
# The three gRPC certification lanes. Their tests already run on every pull request — the
|
||||
# `grpc-inprocess`, `grpc-netty` and `grpc-fault` tags are NOT excluded from
|
||||
# `:grpc:grpc-testkit:test` (only `grpc-performance` is), and that task runs inside the root
|
||||
# `check`. So this job adds exactly what the web Advanced lane above adds: the lane
|
||||
# fails closed when its tag selects nothing, which is the one thing a tag-filtered suite inside
|
||||
# `test` cannot tell you. A renamed or deleted @Tag would otherwise leave the in-process,
|
||||
# transport and fault evidence grades claiming coverage that stopped existing.
|
||||
#
|
||||
# Release rather than nightly, for the same reason web-stable-release-gate is: these lanes need no
|
||||
# container and no fixed cadence — grpcNettyContractTest opens an ephemeral socket, not a broker —
|
||||
# so the guard is worth asserting once per tag and is not worth a runner every night.
|
||||
#
|
||||
# The optional build's `releaseCheck` is those hermetic lanes, so a lane added there is here
|
||||
# without a workflow edit. grpcPerformanceTest is deliberately absent: a measurement is not release
|
||||
# evidence on a shared runner. It runs in integration-main.yml's performance-check job (the
|
||||
# optional build's `performanceCheck`).
|
||||
grpc-stable-release-gate:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 45
|
||||
steps:
|
||||
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
|
||||
- uses: ./.github/actions/setup-gradle-java
|
||||
- name: Run the gRPC Stable certification lanes
|
||||
working-directory: src
|
||||
run: ./gradlew -p platforms/optional-build releaseCheck --stacktrace
|
||||
# The operation ledger's real-PostgreSQL lane ran only on main and nightly
|
||||
# (integration-main.yml), so a tag could be cut from a main whose ledger lane was red. It needs
|
||||
# Docker, which a release runner has (review 2026-11-01 03-12).
|
||||
- name: Certify the gRPC operation ledger against real PostgreSQL
|
||||
working-directory: src
|
||||
env:
|
||||
TESTCONTAINERS_REUSE_ENABLE: "false"
|
||||
run: ./gradlew -p platforms/optional-build integrationCheck --stacktrace
|
||||
- name: Publish the gRPC release evidence
|
||||
if: always()
|
||||
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
|
||||
with:
|
||||
name: grpc-release-evidence
|
||||
path: |
|
||||
src/platforms/grpc/grpc-testkit/build/reports/tests/
|
||||
src/platforms/grpc/grpc-operation-ledger-jpa/build/reports/tests/
|
||||
if-no-files-found: warn
|
||||
|
||||
# Each gate runs as its own single-line `./gradlew <task>` step so that a failure names the gate
|
||||
# rather than a folded command. The architecture dependency gate that used to end this list is now
|
||||
# architecture-and-surface above; it was the fourth copy of the same invocation.
|
||||
@@ -344,7 +301,6 @@ jobs:
|
||||
- architecture-and-surface
|
||||
- web-stable-release-gate
|
||||
- websocket-stable-release-gate
|
||||
- grpc-stable-release-gate
|
||||
- httpclient-release-gate
|
||||
- httpclient-documentation
|
||||
- jpa-release-promotion
|
||||
|
||||
@@ -3,6 +3,7 @@
|
||||
## Claude Code에서만
|
||||
|
||||
- 권한과 훅은 `.claude/settings.json`이다: 편집 직후 Java 한 파일 포맷·레이어 의존 알림·문서 검사, 턴 끝 desktop 검증 알림, 적용된 migration 편집 차단, 실제 `.env` 읽기 차단. 훅마다 하는 일과 시험은 `scripts/hooks/README.md`다.
|
||||
- 공통 훅·스킬(되돌릴 수 없는 명령 차단, 비밀 값 알림, 장부, `estimate`·`retro`·`techdebt`)은 하네스 플러그인 `harness@claude-harness`다(같은 settings가 켠다). 비대화형(`claude -p`)은 설치하지 않으니 claude-harness README의 `--scope project` 두 명령을 한 번 돌린다.
|
||||
- 경로별 규칙(테스트·설정·Docker·문서)은 `.claude/rules/`에 있다. 그 경로의 파일을 열 때 읽힌다.
|
||||
- 스킬은 `.claude/skills/`다: `new-feature`(새 기능), `desktop-gates`(Gradle·Docker를 desktop에서). 발동 조건이 설명에 있어 모델이 부른다.
|
||||
- 서브에이전트는 `.claude/agents/`다: `arch-reviewer`(구조 리뷰), `verify-api`(desktop에서 앱 띄워 확인), `code-simplifier`(단순화 제안). 모두 결과만 돌려주고 파일을 고치지 않는다.
|
||||
|
||||
@@ -27,7 +27,7 @@ ca-skeleton은 Java 21과 Spring Boot로 만든 Gradle 멀티모듈 백엔드
|
||||
| `adapter/outbound/` | port 뒤의 구현: 영속성(JPA·MongoDB), Redis, 메시징, 알림, 객체 저장소, 파일 서버, HTTP client, identifier, 공용 기반(support) | `support`·`identifier`만 들어간다 |
|
||||
| `composition/` | 조립만 하는 leaf: 서비스 런타임 배선, outbox relay, 멱등성 executor, durable operation, 알림·파일 서버 플랫폼 | `service-runtime`·`outbox-relay`·`idempotency`·`durable-operation`이 들어간다. 뒤의 셋은 필요한 port가 생기기 전에는 아무것도 만들지 않는다 |
|
||||
| `app-bootstrap/` | Spring Boot 진입점과 조립 루트(composition root, 모든 모듈을 엮는 곳) | 들어간다 |
|
||||
| `platforms/` | 들여온 제품: `messaging`(메시징 플랫폼), `grpc`·`grpc-advanced`(gRPC 라이브러리, 다른 빌드 `optional-build`) | 들어가지 않는다. adapter를 거쳐서만 닿는다 |
|
||||
| `platforms/` | 들여온 제품: `messaging`(메시징 플랫폼). gRPC 플랫폼 라이브러리는 2026-11-08에 별도 repo `grpc-library`로 옮겼다([관련 저장소](docs/work/reference/related-repos.md)) | 들어가지 않는다. adapter를 거쳐서만 닿는다 |
|
||||
| `build-logic/`, `config/`, `gradle/` | 빌드 규칙(convention plugin), 빌드 전체 도구 설정과 registry, wrapper와 버전 카탈로그 | 빌드 도구 |
|
||||
|
||||
의존은 항상 바깥에서 안으로 흐른다. adapter가 core의 port에 의존하고, core는 adapter를 모른다.
|
||||
@@ -122,7 +122,7 @@ cd src
|
||||
3. `CaSkeletonApplication`을 새 애플리케이션 이름으로 바꾼다.
|
||||
4. 새 업무 기능은 `scripts/new-feature.sh <FeatureName>`으로 만들고 [docs/manual/README.md](docs/manual/README.md) 순서대로 채운다. 모듈 이름과 경계는 그대로 둔다.
|
||||
5. 쓰는 capability의 `runtimeOnly` 줄만 켠다. 켜지 않은 capability leaf는 산출물에 들어가지 않으니 지우지 않아도 된다.
|
||||
6. gRPC 플랫폼을 쓰면 proto 조직 이름 `caskeleton`도 바꾼다. `src/platforms/grpc/grpc-contract/src/main/proto/caskeleton/` 디렉터리와 각 `.proto`의 `package`·`java_package`다. `buf lint`로 확인한다.
|
||||
6. 라이브러리 패키지 `dev.cakit.*`은 바꾸지 않는다. 별도 repo에서 받는 라이브러리의 패키지이고, 2번이 바꾸는 `dev.caskeleton`과 이름이 겹치지 않게 정했다. 라이브러리 목록은 [관련 저장소](docs/work/reference/related-repos.md)다.
|
||||
7. Docker 이미지 이름과 애플리케이션 이름(`spring.application.name`)을 새 서비스 기준으로 바꾼다.
|
||||
8. `src/.env.example`, `src/.env.local.example`, `application.yml`의 예시 값을 새 서비스의 실행 요구에 맞춘다. 운영 모듈에는 그 서비스의 entity, repository port, use case, adapter만 더한다.
|
||||
9. README와 운영 문서를 새 서비스 설명으로 고친다.
|
||||
|
||||
@@ -35,7 +35,6 @@
|
||||
| `architecture/` | 공개 API 표면 스냅숏(`*-api-surface.txt`). API surface 검사가 대조한다 |
|
||||
| `security/` | 기본 공개 경로 스냅숏. `verifyPublicPathSnapshot`이 대조한다 |
|
||||
| `observability/` | 구조화 로그 필드 사전 |
|
||||
| `compatibility/` | gRPC 플랫폼 지원 매트릭스(무엇에 대해 인증했고 무엇은 지켜보기만 하나) |
|
||||
|
||||
### 영역 운영 문서
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-30
|
||||
- 요약: gRPC 플랫폼을 adapter leaf 하나가 아니라 registry에 등록한 family로 낸다는 결정이다.
|
||||
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
|
||||
- 현재 정본: 없음 — gRPC 플랫폼은 2026-11-08에 별도 repo grpc-library로 옮겼다. 지금 동작은 그 repo의 docs/compatibility/grpc-support-matrix.md이고, 이 기록의 사본도 그 repo에 있다
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-GRPC-001: gRPC 플랫폼은 adapter leaf 하나가 아니라 등록된 family로 싣는다
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
- 상태: 대체됨
|
||||
- 작성일: 2026-08-30
|
||||
- 요약: protoc와 Buf CLI 없이 스키마를 관리하려던 결정이다. 2026-09-28 Gradle protobuf plugin과 buf로 바뀌었다.
|
||||
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
|
||||
- 현재 정본: 없음 — gRPC 플랫폼은 2026-11-08에 별도 repo grpc-library로 옮겼다. 지금 동작은 그 repo의 docs/compatibility/grpc-support-matrix.md이고, 이 기록의 사본도 그 repo에 있다
|
||||
- 대체됨: `docs/capability-status.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-30
|
||||
- 요약: 전송·업무·스트림 증거를 서로 대신하지 않는 세 축으로 본다는 결정이다.
|
||||
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
|
||||
- 현재 정본: 없음 — gRPC 플랫폼은 2026-11-08에 별도 repo grpc-library로 옮겼다. 지금 동작은 그 repo의 docs/compatibility/grpc-support-matrix.md이고, 이 기록의 사본도 그 repo에 있다
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-GRPC-003: 전송·업무·stream 증거는 세 축이고, 어느 것도 다른 것을 뜻하지 않는다
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-30
|
||||
- 요약: 재시도 주인은 하나이고 키가 있는 변경은 영속 원장이 필요하다는 결정이다.
|
||||
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
|
||||
- 현재 정본: 없음 — gRPC 플랫폼은 2026-11-08에 별도 repo grpc-library로 옮겼다. 지금 동작은 그 repo의 docs/compatibility/grpc-support-matrix.md이고, 이 기록의 사본도 그 repo에 있다
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-GRPC-004: 재시도 소유자는 하나이고, 키가 있는 변경에는 durable 원장이 필요하다
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-30
|
||||
- 요약: 서버 스트림은 writer 하나, 제한된 큐, 추측하지 않는 resume로 다룬다는 결정이다.
|
||||
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
|
||||
- 현재 정본: 없음 — gRPC 플랫폼은 2026-11-08에 별도 repo grpc-library로 옮겼다. 지금 동작은 그 repo의 docs/compatibility/grpc-support-matrix.md이고, 이 기록의 사본도 그 repo에 있다
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-GRPC-005: stream마다 쓰는 쪽 하나, 한계 있는 queue, 짐작하기를 거절하는 resume
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-31
|
||||
- 요약: Stable discovery는 DNS와 정적 목록이고 Kubernetes에서는 누가 부하를 나누는지 profile이 정한다는 결정이다.
|
||||
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
|
||||
- 현재 정본: 없음 — gRPC 플랫폼은 2026-11-08에 별도 repo grpc-library로 옮겼다. 지금 동작은 그 repo의 docs/compatibility/grpc-support-matrix.md이고, 이 기록의 사본도 그 repo에 있다
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-GRPC-006: Stable discovery는 DNS와 static이고, Kubernetes profile은 누가 분산하는지 이름으로 댄다
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-30
|
||||
- 요약: gRPC 고급 기능마다 따로 플래그·등급·승격 기준을 둔다는 결정이다.
|
||||
- 현재 정본: `docs/compatibility/grpc-advanced-support-matrix.md`
|
||||
- 현재 정본: 없음 — gRPC 플랫폼은 2026-11-08에 별도 repo grpc-library로 옮겼다. 지금 동작은 그 repo의 docs/compatibility/grpc-advanced-support-matrix.md이고, 이 기록의 사본도 그 repo에 있다
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-GRPC-ADV-001: advanced capability마다 자기 flag, 자기 등급, 자기 승격이 있다
|
||||
|
||||
@@ -38,7 +38,7 @@ lanes and CI; it is not a deployment artifact.
|
||||
| Outbound HTTP client | `app.httpclient.enabled` / `APP_HTTPCLIENT_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:httpclient')`) | yes | On when present (`HttpClientPlatformActivationTest`). `httpclient:httpClientFailureInjectionTest` against a faulted upstream, run by `integration-main.yml` → `integration-check` (`:integrationCheck`) |
|
||||
| GraphQL transport | `backend.graphql.enabled` / `APP_GRAPHQL_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:inbound:graphql')`) | leaf-level | On when present; `false` also excludes Spring GraphQL's own auto-configuration, so no `/graphql` (`GraphQlCapabilityActivationTest`). `graphqlTransportQualificationTest` runs the HTTP boundary. The deployment-mode/runtime-profile rule is the module's own `GraphQlPlatformStartupValidator`. The default jar does not ship GraphQL, so a compose lane that exercises it runs the qualification jar. |
|
||||
| Object storage | `app.object-storage.enabled` / `APP_OBJECTSTORAGE_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:objectstorage')`) | MinIO only | Own `ObjectStorageAutoConfiguration` (was bound through bootstrap's properties scan); on when present, `false` leaves only the explicit legacy seam (`ObjectStorageAutoConfigurationTest`). `app-bootstrap:integrationTest` assembles it against digest-pinned MinIO. |
|
||||
| gRPC platform | — (build-level) | yes | **no** | yes | Absent from the main build entirely: `optional-platforms` is a separate Gradle build, so the switch is the `include`, not an environment variable. `-p optional-platforms ci` runs on every PR and `integrationCheck` certifies the operation ledger against real PostgreSQL. |
|
||||
| gRPC platform | — (separate repository) | no | **no** | no | Moved out on 2026-11-08 to the `grpc-library` repository (Maven group `dev.cakit.grpc`); this repository builds and tests none of it. `adapter:inbound:grpc` uses `io.grpc` directly and is unaffected. See `docs/work/reference/related-repos.md`. |
|
||||
| gRPC transport (`adapter:inbound:grpc`) | `app.grpc.server.enabled` / `APP_GRPC_SERVER_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:inbound:grpc')`) | leaf-level | Own `AutoConfiguration.imports` (`GrpcServerConfig`); on when present, and the loopback plaintext listener still needs `app.grpc.server.allow-insecure-local=true` (`GrpcSafeActivationTest`, `grpcTransportQualificationTest`). |
|
||||
| WebSocket transport | `app.websocket.enabled` / `APP_WEBSOCKET_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:inbound:websocket')`) | — | Own `AutoConfiguration.imports` (`WebSocketConfig`), on in a servlet app when present (`WebSocketAutoConfigurationTest`); `ConditionalTransportBuildContractTest` asserts it has no default production edge. |
|
||||
| Web Advanced library (`adapter:inbound:web-advanced`) | — (build-level; three `backend.web.advanced.*.enabled` switches inside) | yes | **no** | — | No composition root depends on it; `app-bootstrap` takes it `testRuntimeOnly` for the ArchUnit import. No real-provider lane: `webAdvancedTest` (the `web-advanced` tag, run by `release.yml` → `web-stable-release-gate`) is unit and context-runner level. The Nginx lane went with the proxy library on 2026-09-25. |
|
||||
|
||||
@@ -1,55 +0,0 @@
|
||||
# gRPC advanced capability 지원 매트릭스
|
||||
|
||||
`:grpc-advanced:*`의 모든 capability, 그 등급, 그리고 등급을 올리는 데 필요한 것이다. 기본 등급의 정본은
|
||||
`GrpcAdvancedCapability.defaultGrade`다. 근거가 있는 배포는 `GrpcAdvancedFeatureFlags.withGrade`로 바꾼다.
|
||||
|
||||
capability는 모두 기본으로 꺼져 있다. 스위치는 `app.grpc.advanced.<capability>.enabled`다.
|
||||
|
||||
## 등급
|
||||
|
||||
| 등급 | 뜰 수 있나 | 운영에 별도 승인이 필요한가 |
|
||||
| --- | --- | --- |
|
||||
| `ADVANCED_STABLE` | 예 | 아니요 |
|
||||
| `EXPERIMENTAL` | 예 | 예 |
|
||||
| `WATCH` | 아니요 | — |
|
||||
| `DISABLED` | 아니요 | — |
|
||||
|
||||
## capability
|
||||
|
||||
| capability | 스위치 | 등급 | 증거에 필요한 실제 인프라 |
|
||||
| --- | --- | --- | --- |
|
||||
| Protobuf Edition 2024 | `edition-2024` | `ADVANCED_STABLE` | — |
|
||||
| Protobuf Edition 2026 | `edition-2026` | `WATCH` | — |
|
||||
| client streaming | `client-streaming` | `ADVANCED_STABLE` | — |
|
||||
| bidirectional streaming | `bidi-streaming` | `ADVANCED_STABLE` | — |
|
||||
| 수동 flow control | `manual-flow-control` | `ADVANCED_STABLE` | — |
|
||||
| 읽기 전용 unary hedging | `hedging` | `EXPERIMENTAL` | — |
|
||||
| 사용자 정의 name resolver | `custom-resolver` | `ADVANCED_STABLE` | — |
|
||||
| 사용자 정의 load balancer | `custom-load-balancer` | `EXPERIMENTAL` | — |
|
||||
| proxyless xDS | `xds` | `EXPERIMENTAL` | xDS control plane |
|
||||
| gRPC-Web | `grpc-web` | `ADVANCED_STABLE` | gRPC-Web proxy |
|
||||
| Servlet HTTP/2 | `servlet-compat` | `ADVANCED_STABLE`(스위치만 있다. 2026-09-25부터 Servlet 전송 코드가 없다) | Servlet 컨테이너 |
|
||||
| Spring Integration bridge | `integration-bridge` | `ADVANCED_STABLE` | — |
|
||||
| Reactor 어댑터 | `reactor` | `ADVANCED_STABLE` | — |
|
||||
| Kotlin coroutine / Flow | `kotlin` | `ADVANCED_STABLE` | Kotlin toolchain |
|
||||
| Channelz / CSDS 진단 | `channel-diagnostics` | `ADVANCED_STABLE` | — |
|
||||
|
||||
## 여기서 등급이 구체적으로 뜻하는 것
|
||||
|
||||
**등급은 배포가 아니라 계약에 대한 말이다.** 모든 capability의 계약은 이 저장소에서 구현되고 시험됐다. 실제 배포에서 나온
|
||||
증거는 어느 capability에도 없고, 승격된 것도 없다.
|
||||
|
||||
**capability 넷은 여기서 의미 있는 증거를 아예 낼 수 없다.** 필요한 인프라(gRPC-Web proxy, Servlet 컨테이너, xDS control
|
||||
plane, Kotlin toolchain)가 없고, 인프라 없이 돈 suite는 통과해도 아무것도 세우지 않기 때문이다.
|
||||
|
||||
**Kotlin이 가장 날카로운 경우다.** 이 저장소에는 Kotlin toolchain이 없으므로 그것이 생기기 전까지 Kotlin은 여기서 지원할 수
|
||||
없다. Java 쪽 coroutine 취소 bridge(`GrpcCoroutineContextBridge`)만 구현되고 시험됐다. 컴파일 lane은 없다.
|
||||
|
||||
## 승격 기준
|
||||
|
||||
| 목표 | soak | 그 밖에 필요한 것 |
|
||||
| --- | --- | --- |
|
||||
| `ADVANCED_STABLE` | 7일 | 호환성 증거, 보안 리뷰, 장애 증거, 성능 증거, ADR, runbook, 실제 환경 시험 |
|
||||
| Stable 기본값 | 30일 | 위의 모두와 의존성·보안·운영 비용 리뷰 |
|
||||
|
||||
`WATCH`는 무엇보다 먼저 `EXPERIMENTAL`이 된다. 승격은 서로 독립이다. 한 capability를 올려도 다른 것의 등급은 바뀌지 않는다.
|
||||
@@ -1,74 +0,0 @@
|
||||
# gRPC 플랫폼 지원 매트릭스
|
||||
|
||||
Stable gRPC 플랫폼(`:grpc:*`)이 무엇에 대해 인증됐고, 무엇에 대해서는 확인만 하고, 무엇은 지켜보기만 하는지다. 그 구별이
|
||||
요점이다. 「Spring Boot와 동작한다」는 누구도 행동에 옮길 수 없는 말이다.
|
||||
|
||||
릴리스 gate는 `.github/workflows/release.yml`의 `grpc-stable-release-gate` job이다. 인증된 lane마다 아무것도 돌리지 않으면
|
||||
실패하는 strict test lane이다.
|
||||
|
||||
> 이력: 코드 안의 `GrpcCompatibilityMatrix`/`GrpcStableReleaseGate` 짝은 지웠다(리뷰 2026-09-24 S5-lead-4). 운영 코드도 빌드
|
||||
> 코드도 그것을 부르지 않아서 아무것도 막지 않았다.
|
||||
|
||||
## lane
|
||||
|
||||
| lane | 등급 | 실패하면 릴리스를 막나 |
|
||||
| --- | --- | --- |
|
||||
| Boot가 관리하는 플랫폼(저장소의 Spring Boot BOM) | Certified | 예 |
|
||||
| 명시적 `optional`을 쓰는 proto3 | Certified | 예 |
|
||||
| `grpc-netty-shaded` | Certified | 예 |
|
||||
| `grpc-netty`(shade하지 않음) | Compatibility | 아니요 |
|
||||
| upstream gRPC Java 버전 override | Compatibility | 아니요 |
|
||||
| Protobuf Edition 2024 | Watch | 아니요 |
|
||||
| Protobuf Edition 2026 | Watch | 아니요 |
|
||||
|
||||
## 런타임 기준선
|
||||
|
||||
| | |
|
||||
| --- | --- |
|
||||
| Java | 21 |
|
||||
| Spring Boot | 저장소 기준선, `src/gradle/libs.versions.toml`(계획은 4.1을 가정한다) |
|
||||
| io.grpc | `src/gradle/libs.versions.toml`의 `grpc`. `GrpcPlatformModuleConventionPlugin`이 그 BOM을 모듈 범위로 import한다 |
|
||||
| Protobuf | `src/gradle/libs.versions.toml`의 protobuf 항목(어느 leaf가 어느 것을 쓰는지는 그 파일의 주석이 적는다) |
|
||||
| Stable 전송 | Netty(shaded) |
|
||||
| Stable RPC 모양 | Unary, Server Streaming |
|
||||
| Stable resolver | Static, DNS, Unix domain socket |
|
||||
| Stable load balancing | `pick_first`, `round_robin` |
|
||||
|
||||
## 증거 등급
|
||||
|
||||
capability는 그것을 세울 수 있는 등급의 증거로만 광고한다. `GrpcEvidenceGrade.requireCertifies`가 이것을 강제하고,
|
||||
`GrpcReleaseEvidence.supports`가 맞지 않는 lane이 뒷받침하는 주장을 거부한다.
|
||||
|
||||
| 등급 | lane | 세우는 것 |
|
||||
| --- | --- | --- |
|
||||
| `CONTRACT` | `grpcInProcessContractTest` | 어댑터, interceptor 순서, 상태 매핑, 검증, 멱등 replay, context 전파 |
|
||||
| `TRANSPORT` | `grpcNettyContractTest` | HTTP/2, TLS, mTLS, metadata 한도, 메시지 한도, GOAWAY, keepalive, graceful shutdown |
|
||||
| `FAULT` | `grpcFaultTest` | 연결 끊김, 완료 모름, 부분 stream, 증거 분류기 |
|
||||
| `PERFORMANCE` | `grpcPerformanceTest` | 지연, stream 포화, executor 포화, drain 예산 |
|
||||
|
||||
in-process 결과는 절대 전송 증거가 아니다. in-process 전송은 TLS를 협상하지 않고, HTTP/2 frame을 만들지 않고, 전송 수준 한도를
|
||||
강제하지 않는다. 그래서 거기서 통과한 suite는 전송이 아니라 어댑터를 시험한 것이다.
|
||||
|
||||
## 지원하지 않는 것
|
||||
|
||||
| | 있는 곳 |
|
||||
| --- | --- |
|
||||
| client streaming, bidirectional streaming | `grpc-advanced` (`streaming`) |
|
||||
| 수동 flow control | `grpc-advanced` (`streaming`) |
|
||||
| Hedging | `grpc-advanced` (`resilience`) |
|
||||
| 사용자 정의 name resolver, 사용자 정의 load balancer | `grpc-advanced` (`resilience`) |
|
||||
| xDS | `grpc-advanced` (`resilience`) |
|
||||
| gRPC-Web, Servlet HTTP/2, Spring Integration, Reactor, Kotlin | `grpc-advanced-compat` |
|
||||
| Channelz / CSDS 진단 | `grpc-advanced` (`diagnostics`) |
|
||||
|
||||
## 지금 릴리스 상태
|
||||
|
||||
릴리스하지 않았다. registry에서 모든 `:grpc:*` leaf는 `"build": "optional-grpc"`라 주 빌드 밖에 있고 어느 조립에도 들어가지
|
||||
않는다. 플랫폼은 빌드만 된다. 컴파일되고 lane이 돌지만, 배포되는 산출물 어디에도 실리지 않는다.
|
||||
|
||||
릴리스 gate 입력 둘이 남아 있고, 그것이 지금부터 릴리스까지의 일이다.
|
||||
|
||||
- **성능 기준선.** 성능 lane은 돌고, 절대 수치가 아니라 모양을 단언한다. 순서 있는 백분위수와 그것을 읽는 gate다. 알려진
|
||||
runner에서 기록한 기준선이 생겨야 회귀 gate가 된다.
|
||||
- **schema codegen.** 이 빌드에서는 `protoc`가 돌지 않는다(ADR-GRPC-002). 그래서 descriptor 산출물과 consumer-compile fixture는
|
||||
컴파일한 schema에서 만들어지지 않고 정책으로 다스린다.
|
||||
@@ -4,7 +4,7 @@
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-08-30
|
||||
- 요약: 타입 안전 gRPC 실행 플랫폼 계획을 이 저장소의 구조와 게이트에 맞춘 설계다.
|
||||
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
|
||||
- 현재 정본: 없음 — gRPC 플랫폼은 2026-11-08에 별도 repo grpc-library로 옮겼다. 지금 동작은 그 repo의 docs/compatibility/grpc-support-matrix.md이고, 이 기록의 사본도 그 repo에 있다
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# 타입 안전 gRPC 실행 플랫폼 — 이 저장소 규약으로의 어댑팅 설계
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
- 상태: 끝남
|
||||
- 작성일: 2026-08-30
|
||||
- 요약: 타입 안전 gRPC 실행 플랫폼의 실행 계획과 실행 결과다.
|
||||
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
|
||||
- 현재 정본: 없음 — gRPC 플랫폼은 2026-11-08에 별도 repo grpc-library로 옮겼다. 지금 동작은 그 repo의 docs/compatibility/grpc-support-matrix.md다
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# 타입 안전 gRPC 실행 플랫폼 — 실행 계획과 실행 결과
|
||||
|
||||
@@ -96,14 +96,10 @@ Flyway 목록 사본을 그것이 나열한 문장에 대해 Flyway 자신과
|
||||
Flyway 업그레이드가 목록에 더한 문장은 그 비교 밖이다. `LockWaitMigrationInspectorTest`가 Flyway 자신의 패턴
|
||||
(`PostgreSQLParser`)을 고정하므로, 그런 업그레이드는 사본이 따라올 때까지 pull request의 `ci`를 실패시킨다.
|
||||
|
||||
gRPC ledger의 트리는 optional 빌드에 있어서 testkit에 의존할 수 없다. 그래서 그 `GrpcOperationLedgerMigrationLockWaitIT`가
|
||||
트리에서 읽은 V001 뒤의 모든 ledger 마이그레이션을 대신 쥔 ledger에 대고 돌리므로, 다음 마이그레이션도 실제 PostgreSQL에서
|
||||
확인된다. 그 트리를 찾고 순서를 매기는 것은 testkit 자신의 `VersionedMigrationFiles`다. ledger의 `build.gradle`이 빌드 때
|
||||
그것을 통합 테스트 소스로 복사하므로(`sharedMigrationFileSources`) 두 빌드가 한 정의를 읽는다. 그 트리의 동시 인덱스 빌드는
|
||||
트랜잭션 밖에서 돌므로 쥔 ledger로 시험할 경우가 아니다. 그런 파일은 이유와 함께 테스트의 `RUN_OUTSIDE_A_TRANSACTION`에
|
||||
넣고, 같은 테스트가 거기 나열한 파일마다 같은 방식으로 복사한 `ConcurrentIndexMigrationInspector`를 건다(「동시 인덱스
|
||||
빌드」). 모든 ledger lane은 Flyway처럼 트리를 파일 하나씩 적용하므로, 그런 파일이 여러 문장을 담은 문자열 하나의 암묵적
|
||||
트랜잭션 안에서 거부되지 않는다.
|
||||
gRPC operation ledger의 마이그레이션 트리(`db/migration/grpc`)는 2026-11-08에 별도 repo `grpc-library`로 옮겼다. 그
|
||||
repo의 `GrpcOperationLedgerMigrationLockWaitIT`가 같은 확인을 하고, `VersionedMigrationFiles`·`ConcurrentIndexMigrationInspector`는
|
||||
그 repo에 복사본으로 있다(edge 없는 복사본. 이 testkit이 정본이다). 이 testkit의 두 파일을 고치면 그 repo의 사본도 같이
|
||||
고친다(`docs/work/reference/related-repos.md`).
|
||||
|
||||
이 규칙은 같은 커밋에서 V21에는 상한이 있고 V22에는 없었던 데서 나왔다(재확인 리뷰 2026-11-03 round 2, RR-02-09; round 3,
|
||||
RR3-02-01, RR3-02-03, RR3-02-04; round 4, RR4-02-01; round 6, RR6-03-02, RR6-03-03; round 7, RR7-03-01).
|
||||
|
||||
@@ -1,2 +1,4 @@
|
||||
{"schema": 1, "kind": "estimate", "task": "h3-backend-harness", "recorded_at": "2026-11-07T21:46+09:00", "transcript": "d5a4c736-f1d6-45ab-acbe-8857526585b9", "started_at": "2026-11-07T21:37:50+09:00", "base": "b3f63be6", "task_kind": "docs-writing+improve", "size": "large", "minutes": {"p30": 150, "p50": 210, "p80": 300}, "calls": {"p30": 450, "p50": 600, "p80": 850}, "output_tokens": {"p30": 450000, "p50": 600000, "p80": 850000}, "basis": "선례 h1-harness-design 작업 중 23분·호출 100·출력 13.6만(바꾼 파일 3, Gradle 없음)에서 분당 호출 4.3, 호출당 출력 1,400. 이번에 바꿀 파일 약 120(하위 문서 이동 28, 새 CLAUDE.md 32, 문서의 AGENTS.md 참조 93줄, 검사기 2, 훅 6, 시험 3, Java 테스트 3, 에이전트·스킬·규칙 8), 매뉴얼 항목 약 60(선례 manual-gap-fix-2가 52건을 한 세션에), desktop 대기 30~50분"}
|
||||
{"schema": 1, "kind": "actual", "task": "h3-backend-harness", "recorded_at": "2026-11-07T23:13+09:00", "transcript": "d5a4c736-f1d6-45ab-acbe-8857526585b9", "minutes": 94, "active_minutes": 68, "calls": 270, "output_tokens": 345525, "cache_read_tokens": 132822591, "max_context": 805096, "within": "p30", "result": "done", "commits": ["08f93212", "3c73fc33", "38891071", "c67c7131", "67ecae2c", "37c88fed", "59dff004", "c8db79a7", "d9059806", "7140f279", "93b70b06", "248df518"], "why": "모든 값이 p30보다 작았다. 바꿀 파일 수(약 120, 실제 190여)를 호출 수로 옮겼는데, 이동·참조 수정 수십 파일을 스크립트 한 번으로 묶어 파일당 호출이 거의 없었다. desktop 대기는 예측과 비슷했지만(합친 트리 한 번 27분, 중단한 두 번) 작업 중 시간에서는 빈틈마다 5분으로 잘린다. 다음 예측은 파일 수가 아니라 손으로 판단할 결정 수(이번 약 25)와 desktop 실행 횟수를 근거로 쓴다. 실측은 23:12까지의 세션 기록이고, 뒤의 커밋·PR·보고는 들어 있지 않다"}
|
||||
{"schema": 1, "kind": "estimate", "task": "x2-grpc-library", "recorded_at": "2026-11-08T10:50+09:00", "transcript": "dc504d75-c815-4dfa-98dd-80c224db983f", "started_at": "2026-11-08T10:47:39+09:00", "base": "22df3525", "task_kind": "improve", "size": "large", "minutes": {"p30": 150, "p50": 220, "p80": 330}, "calls": {"p30": 350, "p50": 500, "p80": 750}, "output_tokens": {"p30": 400000, "p50": 600000, "p80": 900000}, "basis": "착수 노트(공유 노트 x2-grpc-library.md, 10:50)에 쓴 값을 옮겼다. 선례 h3-backend-harness 작업 중 68분·호출 270·출력 34.6만(손으로 판단한 결정 약 25, desktop 실행 3회). 이번은 결정 약 35(배치, build-logic 줄이기, 배포·서명·SBOM, buf 정책, testFixtures 사본, workflow 셋, 템플릿 지우기 20여 파일, 하네스)와 desktop 실행이 라이브러리 반복 5~8회 + 템플릿 게이트 묶음 2~3회 + Gitea Actions 실행 2회 이상이라 h3의 세 배 가까이로 봤다"}
|
||||
{"schema": 1, "kind": "actual", "task": "x2-grpc-library", "recorded_at": "2026-11-08T14:02+09:00", "transcript": "dc504d75-c815-4dfa-98dd-80c224db983f", "minutes": 194, "active_minutes": 99, "calls": 330, "output_tokens": 303528, "cache_read_tokens": 136483127, "max_context": 746863, "within": "p30", "result": "done", "commits": ["5e204e6a", "2921f596", "91804ec1", "57988c2e", "grpc-library:76a9244", "grpc-library:414666c", "grpc-library:41d73a1", "grpc-library:239547b", "grpc-library:90306b2", "grpc-library:8d705bc", "grpc-library:ce83f4d", "grpc-library:39d4b6d", "grpc-library:c10f4af"], "why": "모든 값이 p30보다 작았다(작업 중 99분, 벽시계 194분). 예측은 desktop 대기(템플릿 게이트 1회차 약 65분, 라이브러리 반복 6회, 재실행 3회)를 작업 중 시간에 넣었는데, 대기는 빈틈마다 5분으로 잘리고 그동안 문서·라이브러리 일을 같이 했다. 패키지 이름 바꾸기 315파일, SpotBugs 제외 정리, 템플릿 삭제 397파일을 스크립트 몇 번으로 끝내 결정 수(약 35) 대비 호출이 적었다. 다음 예측은 desktop 대기를 시간에서 빼고 결정 수와 실행 횟수만으로 잡는다. 라이브러리 PR #1 병합은 권한 분류기에 막혀 남았다"}
|
||||
|
||||
@@ -90,8 +90,7 @@ store는 자기 트랜잭션을 열지 않는다. 유스케이스가 연 트랜
|
||||
- 그 약속은 포트 소유자 testFixtures의 공유 계약 테스트로 고정한다. fake와 adapter가 같은 계약을 상속한다.
|
||||
예: `DurableOperationStoreContract`(`InMemoryDurableOperationStore`, `JpaDurableOperationStoreContractTest`).
|
||||
- 여러 인스턴스가 집는 작업 → `FOR UPDATE SKIP LOCKED`는 **트랜잭션 안에서**, 그리고 lease(만료 시각)와
|
||||
fence 값을 함께 저장한다. 예: `ReconciliationJobStorePort.claimDue`(application-notification),
|
||||
gRPC operation ledger의 claim.
|
||||
fence 값을 함께 저장한다. 예: `ReconciliationJobStorePort.claimDue`(application-notification).
|
||||
- 수정 충돌 → 버전 열(낙관적 잠금). 예: `DurableOperationEntity`(persistence-jpa)의 `@Version` 열 `row_version`.
|
||||
- **예외**: DB가 볼 수 없는 규칙(외부 시스템 상태)은 분산 락(`DistributedLockPort`)이나 멱등성 키(05장).
|
||||
- 동시성 테스트는 실 DB lane에서 동시 요청 N개 → 행 1개를 단언한다.
|
||||
|
||||
@@ -1,88 +0,0 @@
|
||||
# Runbook: gRPC advanced capabilities
|
||||
|
||||
범위: `:grpc-advanced:*` family. 여기 있는 것은 모두 기본으로 꺼져 있고, 배포가 이름을 대기 전까지 꺼진 채로
|
||||
있다. 지금 이 family의 어떤 것도 런타임 조립에 들어가지 않는다.
|
||||
|
||||
스위치는 `app.grpc.advanced.<capability>.enabled`다. capability 이름 목록과 기본 등급은
|
||||
`GrpcAdvancedCapability`(`defaultGrade()`)가 가진다. 근거가 있는 배포는 `GrpcAdvancedFeatureFlags.withGrade`로
|
||||
등급을 바꾼다.
|
||||
|
||||
---
|
||||
|
||||
## capability가 뜨기를 거부한다
|
||||
|
||||
`GrpcAdvancedModuleGuard`는 세 가지로 거부하고, 고치는 법이 다르다.
|
||||
|
||||
| 메시지에 있는 말 | 뜻 | 고치는 법 |
|
||||
| --- | --- | --- |
|
||||
| "its feature flag is not set" | 아무도 켜지 않았다 | 메시지가 이름 댄 속성을 설정한다 |
|
||||
| "tracked rather than implemented" | 등급이 `WATCH`다 | 여기서 할 일은 없다. 그 capability는 구현되지 않았다 |
|
||||
| "uncharacterised failure modes" | 등급이 `EXPERIMENTAL`이고 여기는 운영이다 | 운영 승인을 기록하거나, 운영 밖에서 돌린다 |
|
||||
|
||||
거부 메시지는 늘 속성 키를 이름 댄다. 그래서 첫 경우는 지원 문의가 아니라 설정 한 줄이다.
|
||||
|
||||
---
|
||||
|
||||
## xDS: control plane이 사라졌다
|
||||
|
||||
**보이는 것.** control plane에 닿지 않는데 클라이언트는 아직 라우팅한다.
|
||||
|
||||
**뜻.** `GrpcXdsFailurePolicy`가 마지막으로 정상이던 snapshot을 오래됨 상한까지 내준다.
|
||||
|
||||
**할 일.**
|
||||
|
||||
1. snapshot의 나이를 본다. `SERVE_LAST_KNOWN_GOOD`는 정상적인 degraded 상태다.
|
||||
2. `STALE_BEYOND_BOUND`는 snapshot이 정책이 허용하는 것보다 오래돼서 더는 믿지 않는다는 뜻이다. 그 상한이
|
||||
없으면 내린 backend가 트래픽을 끝없이 받는다.
|
||||
3. 뜨는 인스턴스의 `NO_SNAPSHOT_YET`은 control plane에 한 번도 닿지 못했다는 뜻이다. 라우팅 없이 뜨지 않고, 첫
|
||||
fetch 시간 상한이 지나면 실패한다.
|
||||
|
||||
xDS가 켜진 동안 애플리케이션 수준의 재시도 정책을 **더하지 않는다**. `GrpcXdsProfile`이 `APPLICATION` 재시도
|
||||
소유자를 거부한다. 두 곳에 정의한 재시도는 결정이 아니라 해석 순서가 이기는 쪽을 정하기 때문이다.
|
||||
|
||||
---
|
||||
|
||||
## gRPC-Web: 브라우저 호출이 멈췄다가 상태 없이 실패한다
|
||||
|
||||
**거의 언제나 proxy다.** gRPC 상태는 trailer로 오고, 브라우저는 proxy가 노출하지 않은 trailer를 읽지 못한다.
|
||||
proxy의 CORS `expose_headers`에 `grpc-status`와 `grpc-message`가 있는지 확인한다.
|
||||
`GrpcWebProxyContract.violations`가 정확히 이것을 보고하고, 참조 설정
|
||||
`src/platforms/grpc-advanced/grpc-advanced-compat/src/test/resources/envoy/envoy.yaml`에 그것이 들어 있다.
|
||||
|
||||
**메서드가 client streaming이나 bidirectional streaming이면** gRPC-Web으로는 아예 되지 않는다. 브라우저는
|
||||
메시지 stream을 보낼 방법이 없다. `GrpcWebRpcSupport.require`가 그런 메서드를 거부한다.
|
||||
|
||||
---
|
||||
|
||||
## Servlet: 전송 설정이 무시되는 것 같다
|
||||
|
||||
무시된다. 소켓은 컨테이너가 가지므로 keepalive 조정, 최대 연결 수명, flow-control window 조정은 컨테이너의
|
||||
몫이다. 이 저장소에는 그것을 거부할 Servlet 전송 코드가 없으니 컨테이너에서 설정한다.
|
||||
|
||||
Servlet 실행은 Netty 인증을 대신하지 않는다.
|
||||
|
||||
---
|
||||
|
||||
## Hedging: backend 부하가 두 배가 됐다
|
||||
|
||||
**상한 안이면 예상한 일이다.** hedging은 중복 부하를 내고 꼬리 지연을 줄인다. `GrpcHedgingResult`는
|
||||
`duplicateBackendCalls`와 `cancelledLoserAttempts`를 둘 다 기록한다. 지연 개선만 보여 주는 대시보드는 그 교환을
|
||||
공짜처럼 보이게 한다.
|
||||
|
||||
**확인할 것.** `GrpcHedgingBudget`은 hedge를 끝난 호출의 비율로 제한한다. 중복 부하가 그 비율을 넘으면 예산이
|
||||
쓰이지 않고 있다는 뜻이다. coordinator 밖에서 무언가가 hedge를 보내고 있다.
|
||||
|
||||
읽기 전용 unary 메서드가 아니면 **hedging을 거부한다**. hedge된 변경은 설계상 두 번 돈다. 멱등 키도 소용없다.
|
||||
두 번째 시도는 실패를 다시 시도하는 것이 아니라 진행 중인 성공을 중복한다.
|
||||
|
||||
---
|
||||
|
||||
## capability 승격
|
||||
|
||||
`ADVANCED_STABLE`로 올리려면 호환성 증거, 보안 리뷰, 장애 증거, 성능 증거, ADR, runbook, 실제 환경 시험, 7일
|
||||
soak이 필요하다. Stable 기본값은 30일이 필요하다. 승격은 서로 독립이다. 한 capability를 올려도 다른 것의 등급은
|
||||
바뀌지 않는다. 이것은 리뷰 점검 목록이다. 이것을 코드로 다시 적은 `GrpcAdvancedPromotionGate`는 자기 테스트
|
||||
말고는 부르는 곳이 없어 지웠다(리뷰 2026-09-24 S5-lead-4).
|
||||
|
||||
어떤 suite를 증거로 들기 전에, 그 suite가 필요한 실제 인프라(proxy, 컨테이너, control plane, toolchain)에 대고
|
||||
돌았는지 확인한다. 인프라 없이 돈 suite는 통과했지만 아무것도 증명하지 않았다.
|
||||
@@ -1,160 +0,0 @@
|
||||
# Runbook: gRPC platform operations
|
||||
|
||||
범위: `:grpc:*` family. 지금은 모두 빌드만 된다. registry에서 이 family의 leaf는 모두 `"build": "optional-grpc"`
|
||||
(주 빌드 밖, `-p platforms/optional-build`로 돈다)이고 어느 조립에도 들어가지 않으므로, 여기 있는 것은 아직 운영에서
|
||||
일어나지 않는다. 그래도 지금 쓰는 이유가 있다. 여기서 다루는 상태는 당번이 새벽 세 시에 처음부터 따져서는 알아낼
|
||||
수 없는 것들이고, runbook보다 동작을 먼저 내보내면 그것을 처음 만난 사람이 그 따지기를 하게 된다.
|
||||
|
||||
설정은 `app.grpc.platform.*` 아래에 있고 `GrpcPlatformProperties`가 묶는다. 플랫폼은
|
||||
`app.grpc.platform.enabled=true`가 아니면 뜨지 않는다.
|
||||
|
||||
---
|
||||
|
||||
## 상태를 바꾸는 호출의 COMPLETION_UNKNOWN
|
||||
|
||||
**보이는 것.** 클라이언트가 상태를 바꾸는 호출에서 `DEADLINE_EXCEEDED`, `UNAVAILABLE`, `INTERNAL`을 받았고, 응답
|
||||
trailer `completion-outcome`이 `COMPLETION_UNKNOWN`이다.
|
||||
|
||||
**뜻.** 서버가 커밋했을 수 있다. 실패도 성공도 아니다. 상태 코드로는 둘을 가릴 수 없어서 결과를 따로 싣는다.
|
||||
|
||||
**하지 말 것.** 호출을 다시 보내지 않는다. 호출자에게 실패했다고 말하지 않는다. 둘 다 절반은 틀리고, 어느 절반인지
|
||||
상태 코드로는 알 수 없다.
|
||||
|
||||
**할 일.**
|
||||
|
||||
1. trailer에서 `error-execution-id`를 꺼낸다. 클라이언트가 본 것과 서버가 한 것을 잇는 유일한 고리다.
|
||||
2. 메서드가 `IDEMPOTENCY_KEY_REQUIRED`면 호출자 fingerprint, 전체 메서드 이름, 호출자의 키로 operation ledger를
|
||||
조회한다. `GrpcOperationStatusQuery`는 `IN_PROGRESS`, `COMMITTED`, `FAILED_TERMINAL`, `NOT_FOUND`, `UNKNOWN`
|
||||
중 하나를 돌려준다.
|
||||
3. `COMMITTED`면 새로 계산한 답이 아니라 저장된 결과 참조를 돌려준다. 그 뒤에 자원이 바뀌었을 수 있고, 새 답은
|
||||
호출자 자신의 호출이 만든 상태가 아니라 맞춰 보는 시점의 상태를 설명한다.
|
||||
4. `NOT_FOUND`는 operation이 시작하지 않았다는 뜻이라 다시 보내도 안전하다. `FAILED_TERMINAL`도 같다.
|
||||
5. `UNKNOWN`은 ledger를 조회하지 못했다는 뜻이다. 아무것도 결론 낼 수 없다. `GrpcCompletionReconciler`가 그
|
||||
건을 대기열에 넣고 나중에 다시 시도한다.
|
||||
6. 메서드에 키가 없으면 ledger 행이 없다. 업무 자원으로 맞춰 보거나 서비스 소유자에게 넘긴다. 키 있는 profile은
|
||||
이 경우를 피하려고 있다.
|
||||
|
||||
7. `IN_PROGRESS`는 claim이 있고 끝나지 않았다는 뜻이다. 그 소유자가 죽었어도 claim이 영원히 묶이지는 않는다.
|
||||
claim TTL(`app.grpc.platform.operation-ledger-claim-ttl`, 기본 5m)보다 오래되면, 같은 요청의 다음 재시도가
|
||||
그것을 넘겨받아 다시 돌리고, 뒤의 reconciler 단계가 그 시도의 `COMMITTED`나 `FAILED_TERMINAL`을 본다.
|
||||
재시도가 오기 전까지 그 건은 대기로 남는다. 다시 돌리는 것은 ledger 커밋이 변경 자신의 트랜잭션 안에서 기록될
|
||||
때만 안전하다. 이 서비스가 둘을 따로 커밋하면 재시도를 들이기 전에 업무 자원을 확인한다. 느리기만 했던
|
||||
소유자는 넘겨받기를 망치지 못한다. 그 claim 시도(`claim_attempt`)가 뒤처졌으므로 늦은 커밋은 거부되고 늦은
|
||||
실패는 무시된다. operation이 "is no longer held by attempt N"이라는 로그 줄이 그 거부다. 장애가 아니다.
|
||||
|
||||
**넘길 때는** reconciler의 대기 목록이 단계를 거듭하며 커질 때다. ledger가 느린 게 아니라 닿지 않는다는 뜻이다.
|
||||
claim TTL보다 오래 `IN_PROGRESS`로 대기 중인데 재시도가 오지 않는 건은 호출자가 포기한 것이다. ledger를 고칠 일이
|
||||
아니라 업무 자원을 확인할 일이다.
|
||||
|
||||
---
|
||||
|
||||
## operation ledger 테이블이 계속 커진다
|
||||
|
||||
**보이는 것.** `grpc_operation_ledger`가 끝없이 커지거나, 오래된 키의 재시도가 replay 대신 변경을 다시 돌린다.
|
||||
|
||||
**뜻.** 끝난 행(`COMMITTED`, `FAILED_TERMINAL`)은 누군가 `GrpcOperationLedgerRetention.purgeExpired(now)`를 불러야만
|
||||
지워진다. starter는 그 bean을 조립하지만(`app.grpc.platform.operation-ledger-enabled=true`) 일정을 걸지는 않는다.
|
||||
테이블이 커지면 서비스의 scheduler가 그것을 부르지 않는 것이다. 보존 기간
|
||||
(`app.grpc.platform.operation-ledger-retention`, 기본 24h)이 지난 뒤 다시 돈 재시도는 보존 기간이 감수하는
|
||||
교환이다. 기록이 지워졌으므로 새 operation이었다.
|
||||
|
||||
**할 일.**
|
||||
|
||||
1. 서비스가 `purgeExpired`에 일정을 걸었는지 확인한다. 한 번 부르면 500행씩 지우다가 덜 찬 묶음이 나오면 멈추고,
|
||||
`IN_PROGRESS` 행은 건드리지 않는다.
|
||||
2. 밀린 양이 많으면 여러 번 부른다. 묶음마다 짧은 트랜잭션이고, 다른 트랜잭션이 쥔 행은 건너뛴다.
|
||||
3. 다시 보낸 키가 보존 기간 뒤에 다시 돌면, purge를 건너뛰지 말고 보존 기간을 호출자의 재시도 창보다 길게 한다.
|
||||
|
||||
**넘길 때는** 오래된 `IN_PROGRESS` 행이 쌓일 때다. 그 행은 설계상 지워지지 않는다. 하나하나가 어느 재시도도
|
||||
넘겨받지 않은 버려진 claim이다(위의 `IN_PROGRESS`).
|
||||
|
||||
---
|
||||
|
||||
## stream이 FULL_RESYNC_REQUIRED로 끝났다
|
||||
|
||||
**보이는 것.** 클라이언트의 resume이 거부되고 다시 동기화하라는 답을 받았다.
|
||||
|
||||
**뜻.** 서버가 클라이언트의 cursor부터 더는 replay할 수 없다. snapshot 버전이 움직였거나, cursor가 보존된 이력보다
|
||||
앞선다.
|
||||
|
||||
**할 일.** 서버에서는 없다. 클라이언트가 자기 위치를 버리고 새 snapshot에서 새 stream을 시작해야 한다. 대신 같은
|
||||
token으로 다시 시도하는 클라이언트는 같은 답을 계속 받는다.
|
||||
|
||||
**넘길 때는** 많은 클라이언트에 한꺼번에 일어날 때다. 보통 이력 보존이 줄었거나, 클라이언트가 다시 붙는 것보다
|
||||
snapshot이 빨리 돈다는 뜻이다.
|
||||
|
||||
---
|
||||
|
||||
## stream이 SLOW_CONSUMER로 끝났다
|
||||
|
||||
**보이는 것.** stream이 `SLOW_CONSUMER`로 끝나고 `grpc.stream.flow_control_stalls`가 오른다.
|
||||
|
||||
**뜻.** 소비자가 상한 있는 큐를 따라가지 못했다. 메시지를 조용히 버리는 대신 stream을 끝냈다. 클라이언트는 버려진
|
||||
것을 알아챌 수 없다. 클라이언트가 보는 순번은 보내진 것뿐이다.
|
||||
|
||||
**할 일.**
|
||||
|
||||
1. 소비자가 느린지 생산자가 빠른지 확인한다. `grpc.stream.messages`를 `grpc.stream.lifetime`과 견주면 속도가
|
||||
나온다.
|
||||
2. 소비자가 느리면 고칠 곳은 소비자다. 큐 상한을 올리면 실패가 뒤로 밀리고 커질 뿐이다.
|
||||
3. 이렇게 끝난 뒤에는 resume을 쓸 수 없다. 큐를 넘친 메시지는 사라졌으므로, 마지막으로 전달한 순번부터 이어 가면
|
||||
그것을 조용히 건너뛴다. 클라이언트는 다시 동기화한다.
|
||||
|
||||
---
|
||||
|
||||
## 부하에서 RESOURCE_EXHAUSTED
|
||||
|
||||
**보이는 것.** 호출이 `RESOURCE_EXHAUSTED`로 거부되고 `GrpcAdmissionController`가 거부를 보고한다.
|
||||
|
||||
**뜻.** 서버가 동시성과 큐 상한에 닿아서 줄을 세우지 않고 덜어 낸다. 설계한 동작이다. 호출자가 이미 포기한 일을
|
||||
받으면 아무것도 아닌 데 용량을 쓴다.
|
||||
|
||||
**할 일.**
|
||||
|
||||
1. `grpc.rpc.duration`과 `grpc.rpc.queue_wait`를 따로 읽는다. duration은 그대로인데 큐 시간이 오르면 병목은 일이
|
||||
아니라 admission이다.
|
||||
2. 어느 포화 counter가 움직이는지 확인한다. executor, channel, flow control이다. 지연 그래프에서는 똑같이 보이지만
|
||||
고치는 법이 다르다.
|
||||
3. `app.grpc.platform.executor-queue-capacity`를 올리면 문제를 미룰 뿐 없애지 않는다. 그래서 `GrpcExecutorProfile`이
|
||||
1만이 넘는 큐를 거부한다.
|
||||
|
||||
---
|
||||
|
||||
## 배포할 때마다 rollout이 오류를 낸다
|
||||
|
||||
**보이는 것.** 인스턴스가 빠질 때마다 `UNAVAILABLE`이나 `CANCELLED`가 몰린다.
|
||||
|
||||
**뜻.** drain 순서가 끝나지 않거나, 순서가 어긋나서 돈다.
|
||||
|
||||
**할 일.**
|
||||
|
||||
1. `GrpcDrainResult`가 각 drain이 해낸 것을 기록한다. 끝난 unary 호출과 취소된 unary 호출, 신호를 받은 stream과
|
||||
취소된 stream, 돈 단계다. 늘 강제 취소하는 drain이 원인이다.
|
||||
2. 순서가 중요하다. readiness가 먼저 뒤집히고, 그 사이에는 아무것도 거부하지 않는다. 인스턴스가 unready를 보고한
|
||||
뒤 라우팅이 그것을 따르기까지 틈이 있기 때문이다. 그 틈에 거부하면 깨끗한 rollout이 배포마다 오류 묶음이 된다.
|
||||
3. 긴 stream이면 Kubernetes profile의 `streamReconnectBudget`과 `readinessDrainGrace`를 확인한다. stream은 일생
|
||||
내내 한 pod에 묶이므로 rollout마다 끝난다. 긴 stream이 있는데 다시 붙는 예산이 없는 profile은 클라이언트가 다음에
|
||||
할 일을 정하지 않은 것이다.
|
||||
|
||||
---
|
||||
|
||||
## 배포의 설정 확인
|
||||
|
||||
`GrpcPlatformSnapshotService`는 관리 네트워크에 있고 관리 역할을 가진 호출자에게 secret 없는 snapshot을 만든다.
|
||||
두 관문이 모두 필요하다.
|
||||
|
||||
`GrpcPlatformSnapshotService.driftAgainstRelease`는 실행 중인 snapshot을 릴리스 manifest와 비교해 스키마 버전,
|
||||
메서드 정책 해시, channel별 profile 차이를 보고한다. 릴리스가 내보내지 않은 설정으로 도는 인스턴스는, 그렇지 않으면
|
||||
로그를 읽어야만 진단되는 장애 한 부류의 원인이다.
|
||||
|
||||
snapshot에는 해시와 이름만 실린다. 자격 증명처럼 보이는 이름의 칸은 가리지 않고 만들 때 거부한다.
|
||||
|
||||
---
|
||||
|
||||
## 일부러 꺼 둔 것
|
||||
|
||||
- **운영의 reflection.** `GrpcReflectionMode.defaultFor`는 `STAGE`와 `PROD`에 `DISABLED`를 돌려준다. reflection은
|
||||
연결을 열 수 있는 누구에게나 스키마 전체를 공개한다.
|
||||
- **모든 advanced capability.** `docs/runbooks/grpc-advanced-capabilities.md`를 본다.
|
||||
- **플랫폼 자체.** `app.grpc.platform.enabled`의 기본값은 false이고, registry에서 모든 `:grpc:*` leaf는
|
||||
`"build": "optional-grpc"`라 기본 조립에 들어가지 않는다.
|
||||
@@ -19,3 +19,4 @@
|
||||
| 6 | repo 스킬 둘을 더했다: `.claude/skills/new-feature`(새 기능 실행 순서), `.claude/skills/desktop-gates`(Gradle·Docker를 desktop에서 돌리는 순서). 모델이 설명의 발동 조건을 보고 부른다. 설치된 스킬이 없던 `skills-lock.json`을 지웠다. `.gitignore`에 `!.claude/skills/`를 더했다 | `desktop-gates`는 소유자 환경을 가정하므로 서비스 환경에 맞게 고치거나 지운다. 서비스가 `skills-lock.json`을 썼다면 merge에서 삭제 충돌이 난다. 쓰면 남긴다 |
|
||||
| 7 | 예측·실측 장부 `docs/ledger/estimates.jsonl`(형식 `docs/ledger/README.md`)을 두었다. `.gitattributes`가 이 파일에 `merge=union`을 준다 | 서비스는 템플릿의 줄을 지우고 자기 작업의 줄부터 쌓는다. 템플릿 줄은 템플릿 작업의 기록이다 |
|
||||
| 8 | 지역 규칙이 200줄을 넘던 셋(`src/application-core`, `src/adapter/outbound/persistence-jpa`, `src/adapter/inbound/graphql`)의 표와 계약을 같은 폴더 `README.md` 끝 「지역 규칙에서 옮긴 표와 계약」 절로 옮겼다. 템플릿 패키지 목록(「패키지 소유」 표)의 정본도 `src/application-core/README.md`다 | 서비스가 그 절을 고쳤다면 README의 같은 절로 옮긴다. 서비스 문서·테스트가 `src/application-core/AGENTS.md`의 「Package ownership」 표를 읽으면 `README.md`로 바꾼다 |
|
||||
| 9 | `.claude/settings.json`에 하네스 플러그인 마켓(`extraKnownMarketplaces`의 `claude-harness`, git URL `https://git.learn.hyeonworks.com/donghyeon.kang/claude-harness.git`)과 `enabledPlugins: {"harness@claude-harness": true}`를 더했다(2026-11-08). 플러그인이 되돌릴 수 없는 명령 차단(H12), 비밀 값 알림, 장부 기록 훅과 `estimate`·`retro`·`techdebt` 스킬을 준다. 사용자 전역에 같은 H12 훅이 있으면 플러그인 H12는 아무것도 하지 않는다. 기존 deny와 repo 훅은 그대로다 | 서비스가 `.claude/settings.json`을 고쳤다면 두 키를 합친다. 대화형 Claude Code는 폴더를 처음 믿을 때 설치를 묻는다. 비대화형(`claude -p`)이면 그 폴더에서 `claude plugin marketplace add <위 URL> --scope project`와 `claude plugin install harness@claude-harness --scope project`를 한 번 돌린다. 플러그인을 쓰지 않으려면 두 키를 지운다 |
|
||||
|
||||
@@ -149,6 +149,19 @@ PR 단계 trivy 검사(`dependency-vulnerability.yml`의 HIGH·CRITICAL 단계)
|
||||
|---|---|---|---|---|
|
||||
| B-54 | 버전 변경. ① `springBoot` 4.0.8 → 4.0.9(Tomcat 11.0.24 → 11.0.27, Jackson 2.21.5 → 2.21.7, Jackson 3 3.1.5 → 3.1.7, Spring Framework 7.0.10 등 Boot가 고른 패치). ② `grpc` 1.68.1 → 1.75.0, `protobufGrpc` 3.25.5 → 3.25.8(grpc-contract의 protoc 포함). ③ `jackson3`(build-logic만 씀) 3.0.2 → 3.1.7. ④ BOM 속성 override 둘(build-logic `JavaConventionsPlugin`): httpcore5 5.3.6 → 5.4.3, httpclient5 5.5.2 → 5.6.3. ⑤ 새 카탈로그 묶음 `pinned-*`: 어떤 leaf도 선언하지 않는데 upstream이 낡은 버전을 가져오는 라이브러리를 모든 leaf의 모든 구성(Checkstyle·Error Prone 구성 포함)에서 고정한다 — guava 33.7.2-jre, plexus-utils 3.6.1, lz4-java 1.11.4, snappy-java 1.1.10.9. ⑥ lockfile 5개에서 지금 빌드에 없는 구성(`redisPolicyContractTest`, `edgeRateLimitContractTest`, objectstorage의 MinIO lane 두 개, persistence-jpa·persistence-mongo의 `testkit`)의 옛 줄을 지웠다. ⑦ persistence-jpa는 Querydsl을 querydsl-core로만 컴파일한다(전에는 `com.querydsl:querydsl-jpa:5.1.0:jakarta`). 그 좌표는 HIGH CVE-2024-49203에 고친 버전이 없다 | merge 때 `gradle.lockfile` 충돌. 자기 leaf lockfile을 다시 쓰지 않으면 `verifyDependencyLocks` 실패. httpcore5 5.4.3은 들어오는 HTTP/1 메시지(HTTP client가 받는 응답)에 줄 길이 8192, 헤더 100개 상한을 기본으로 건다. 넘는 응답은 거절된다. 자기 의존성이 33.7.2보다 새 guava를 요구해도 `pinned-guava`가 33.7.2로 내린다 | merge 뒤 `./gradlew resolveAndLockAll --write-locks`와 `./gradlew -p platforms/optional-build resolveAndLockAll --write-locks`. 자기 lockfile에 지운 source set의 줄이 남았으면 그 lockfile을 지우고 같은 명령으로 새로 만든다(`--write-locks`는 해석한 구성만 다시 쓴다). 더 새 guava가 필요하면 그 leaf에서 guava를 버전과 함께 직접 선언한다(직접 선언이 고정을 이긴다). 응답 헤더가 큰 외부 API를 부르면 그 호출을 시험한다. Querydsl을 켜서 querydsl-jpa를 직접 더한 서비스는 그 좌표에 고친 버전이 없으니 OpenFeign 포크(`io.github.openfeign.querydsl:querydsl-jpa` 6.10.1 이상)로 옮기거나 자기 무시 항목에 이유와 만료일을 적는다 | 커밋 「lockfile에서 지금 빌드에 없는 구성의 옛 줄을 지운다」~「persistence-jpa가 querydsl-jpa 대신 querydsl-core로 컴파일한다」, `src/gradle/libs.versions.toml` 「Pinned」 |
|
||||
|
||||
### 3.8 gRPC 플랫폼 — 별도 repo `grpc-library`로 옮겼다
|
||||
|
||||
이 절도 위 머리의 범위보다 뒤에 main에 들어간다. 범위: `22df3525..claude/x2-grpc-library-43dd09`(2026-11-08, 소유자
|
||||
결정 2026-11-07 「프로젝트 계층이 아닌 라이브러리는 별도 repo로」, design-docs `repo-structure/05-library-repos.md`).
|
||||
템플릿 안에는 gRPC 플랫폼을 쓰는 곳이 없었다(`adapter:inbound:grpc`는 `io.grpc`를 직접 쓴다). 그래서 템플릿은 이
|
||||
라이브러리를 받지 않고 지우기만 한다. 코드와 이력은 https://git.learn.hyeonworks.com/donghyeon.kang/grpc-library 에
|
||||
있다.
|
||||
|
||||
| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 |
|
||||
|---|---|---|---|---|
|
||||
| B-55 | 삭제: `src/platforms/grpc`, `src/platforms/grpc-advanced`, `src/platforms/optional-build`(두 번째 빌드 `optional-platforms` 전체), registry의 `"build": "optional-grpc"` 9행, workflow job `ci-quality-gates.yml` `optional-platforms`·`grpc-proto-buf`(그리고 `release-gate`의 두 `needs`), `integration-main.yml`의 optional 성능 단계와 job `grpc-optional-platform-integration`, `release.yml` job `grpc-stable-release-gate`(그리고 이미지 job의 `needs` 한 줄), 살아 있는 문서 `docs/compatibility/`(폴더째), `docs/runbooks/grpc-platform-operations.md`·`grpc-advanced-capabilities.md`. 새 자리는 grpc-library repo이고 같은 이름의 파일이 이력째 있다. 기록(`docs/adr/ADR-GRPC-*` 7개, `docs/design/2026-08-30-grpc-platform-adaptation-design.md`)은 본문을 두고 머리 블록 「현재 정본」만 그 repo를 가리키게 했다. 사본이 그 repo에도 있다. 그 repo에서 Maven group과 Java 패키지는 `dev.cakit.grpc`, proto 패키지는 `cakit.grpc.common.v1`이다(템플릿 재사용 체크리스트의 `dev.caskeleton` 바꾸기와 겹치지 않게 다른 이름) | 이 경로를 고친 서비스는 「수정 대 삭제」 충돌이 난다. `project(':grpc:…')`·`project(':grpc-advanced:…')`나 `-p platforms/optional-build`를 쓴 서비스는 빌드가 실패한다 | 쓰지 않았으면 삭제를 그대로 받는다. 썼으면 grpc-library 첫 버전(`1.0.0`, 소유자가 태그를 단 뒤)을 좌표 `dev.cakit.grpc:<모듈>:1.0.0`으로 받고(저장소 선언은 그 repo README 「받는 법」), import를 `dev.caskeleton.grpc` → `dev.cakit.grpc`로 바꾼다 | design-docs `repo-structure/05-library-repos.md` 4·13절, `docs/work/reference/related-repos.md` |
|
||||
| B-56 | 빌드 규칙·카탈로그: build-logic의 `ca.grpc-platform-module`·`ca.optional-architecture-registry` 플러그인과 `MainBuild`(두 번째 빌드에서 주 빌드를 찾던 것)를 지웠다. 도구 설정·테스트 이미지 목록·registry는 Gradle 루트(`src/`)에서만 찾는다. 카탈로그에서 `protobufPlugin`·`protobuf-java-grpc`·`protoc`·plugin `protobuf`를, SpotBugs 제외에서 gRPC 플랫폼 클래스 줄을 지웠다 | 서비스 leaf가 `ca.grpc-platform-module`이나 `libs.protoc`·`libs.protobuf.java.grpc`·`libs.plugins.protobuf`를 쓰면 빌드가 실패한다. `src/` 밖 두 번째 빌드에서 이 build-logic을 쓰던 서비스는 도구 설정을 못 찾는다 | 그 leaf `build.gradle`에서 `io.grpc:grpc-bom` import와 protobuf 플러그인 버전을 직접 적거나, 지운 카탈로그 항목을 서비스 카탈로그에 다시 더한다 | 같은 설계 13.1절 2단계 |
|
||||
|
||||
## 4. DB 마이그레이션
|
||||
|
||||
### 4.1 새 버전과 영향
|
||||
|
||||
@@ -70,6 +70,7 @@
|
||||
| [reference/defect-patterns.md](reference/defect-patterns.md) | 반복해서 나온 결함의 모양과 막는 기준 |
|
||||
| [reference/decisions.md](reference/decisions.md) | 이미 정한 결정의 색인, 결정을 다시 여는 조건과 기록하는 법 |
|
||||
| [reference/terms.md](reference/terms.md) | 영어 그대로 쓰는 말과 정한 표기의 뜻 |
|
||||
| [reference/related-repos.md](reference/related-repos.md) | 템플릿 밖 라이브러리 repo 목록, 같이 고치기와 버전 올리기 |
|
||||
| [evidence.md](evidence.md) | 이 매뉴얼의 규칙이 나온 사건과 지난 리뷰 ID |
|
||||
|
||||
## 8. 이 폴더를 고칠 때
|
||||
|
||||
@@ -51,7 +51,7 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기
|
||||
| 영역 | 경로 |
|
||||
| --- | --- |
|
||||
| core·application | `src/domain-core`, `src/application-*`, `src/shared-contract` |
|
||||
| inbound 전송 | `src/adapter/inbound/*`, `src/platforms/grpc/*`·`src/platforms/grpc-advanced/*`(optional 빌드) |
|
||||
| inbound 전송 | `src/adapter/inbound/*`. gRPC 플랫폼 라이브러리는 별도 repo `grpc-library`에서 고친다(`reference/related-repos.md`) |
|
||||
| persistence | `src/adapter/outbound/persistence-*`, 마이그레이션 |
|
||||
| outbound capability | 그 밖의 `src/adapter/outbound/*`, 멱등성 store |
|
||||
| messaging | `src/platforms/messaging/*`, `src/adapter/outbound/messaging` |
|
||||
|
||||
@@ -76,7 +76,7 @@
|
||||
| --- | --- | --- | --- |
|
||||
| outbox relay·멱등성 executor 조립 | app-bootstrap이 아니라 별도 `composition:*` 모듈 | 소유자 | 결정 3 |
|
||||
| 새 leaf | `composition:durable-operation`, `adapter:inbound:messaging` 등록 승인 | 위임 | `1101` 15절 |
|
||||
| edge 없는 복사본 | 템플릿 leaf는 `shared-contract` edge를 더해 정본을 쓴다. vendored(`messaging:*`·`grpc:*`)는 복사본을 두고 family `AGENTS.md`에 이유 | 위임 | `1101` 15절(01-11) |
|
||||
| edge 없는 복사본 | 템플릿 leaf는 `shared-contract` edge를 더해 정본을 쓴다. vendored(`messaging:*`)와 별도 repo 라이브러리는 복사본을 두고 family `AGENTS.md`(라이브러리는 그 모듈)에 이유 | 위임 | `1101` 15절(01-11) |
|
||||
| caller 트랜잭션 guard | `persistence-notification`·`persistence-fileserver` → `persistence-jpa` edge, `CallerTransaction` 하나 | 소유자 | 결정 33 |
|
||||
| id 포트 | notification·fileserver id 포트를 domain `IdFactory`로 옮기지 않음(보류) | 소유자 | 결정 34 |
|
||||
| 소비자 없는 필드 | principal tenant, GraphQL Spring Security resolver, 가명화 키 분리는 하지 않음(보류) | 소유자 | 결정 35 |
|
||||
@@ -85,7 +85,8 @@
|
||||
| `@SystemInvoked` | bean으로 등록돼 있으면 기동 실패, inbound adapter가 직접 부르지 못하게 ArchUnit | 위임 | `1103` 4절(RR-01-02) |
|
||||
| 시스템 호출 경로 | 사용자가 닿는 전송(web·GraphQL·gRPC·WebSocket)만 `@SystemInvoked`에 닿지 못한다. 메시지 소비자·스케줄러는 `@SystemCaller(reason)` 표시로 허용 | 위임 | `1103` 9.1절(RR-01-12), 10절 r5-b |
|
||||
| 배치 규칙 검사 | 저장소 루트와 `src/` 최상위 허용 목록을 `scripts/check-repo-layout.py`로 PR에서 막는다. 리뷰 기준에도 넣는다(매뉴얼 보강 작업) | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 10.3절 |
|
||||
| `src/` 배치 | 들여온 플랫폼 넷(`messaging`, `grpc`, `grpc-advanced`, optional 빌드)을 `src/platforms/` 아래로 묶는다. registry `source_path`만 바꾸고 Gradle 경로는 그대로 둔다. `build-logic`·`gradle`·`config`는 Gradle 루트 표준이라 남기고, `composition`은 조립 계층이라 옮기지 않는다. `config/`에서 기능 하나가 주인인 데이터 파일은 그 leaf로 보낸다. Gradle 루트를 저장소 루트로 옮길지는 CI 재편 때 다시 본다 | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.1절 |
|
||||
| `src/` 배치 | 들여온 플랫폼 넷(`messaging`, `grpc`, `grpc-advanced`, optional 빌드)을 `src/platforms/` 아래로 묶는다. registry `source_path`만 바꾸고 Gradle 경로는 그대로 둔다. `build-logic`·`gradle`·`config`는 Gradle 루트 표준이라 남기고, `composition`은 조립 계층이라 옮기지 않는다. `config/`에서 기능 하나가 주인인 데이터 파일은 그 leaf로 보낸다. Gradle 루트를 저장소 루트로 옮길지는 CI 재편 때 다시 본다. gRPC 둘과 optional 빌드는 2026-11-08 별도 repo로 나갔다(아래 「라이브러리 repo」) | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.1절 |
|
||||
| 라이브러리 repo | 프로젝트 계층이 아닌 라이브러리(메시징, gRPC)는 템플릿에 두지 않는다. 라이브러리마다 별도 repo에서 고치고 Gitea Packages에 버전으로 배포하며, 템플릿은 쓰는 라이브러리만 카탈로그 좌표로 받는다. gRPC가 먼저 `grpc-library`로 옮겼다(2026-11-08, 템플릿 소비자 없음이라 카탈로그 항목도 없음). 목록과 고치는 법은 `related-repos.md` | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.5절, `repo-structure/05-library-repos.md` 15절 |
|
||||
| 개발 compose 파일 | 저장소 루트에 `compose.yaml` 하나. 뒷단 서비스는 capability 이름 profile로 고르고, 마운트하는 보조 파일은 `compose/`에 둔다. 테스트 lane fixture는 그 lane을 가진 leaf로 보낸다(compose lane → app-bootstrap `compose-lanes/`, Redis topology → redis-sdk, NFS → fileserver). `docker-compose.dev.yml`은 `dev` 배포 프로필이 뜨는지 보는 lane fixture로 app-bootstrap에 둔다 | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.3절 |
|
||||
| 인프라 실행 파일 | nginx 설정, Kubernetes PVC job, DB 역할 SQL은 이 repo에서 지우고, 기능이 운영 환경에 요구하는 조건만 그 기능 문서에 적는다. 아무도 쓰지 않는 infra 폴더 파일도 지운다. 지운 목록은 `docs/upgrade/2026-11-maturity-review.md` B-50 | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.3절 |
|
||||
| 샘플 모듈 | 샘플 leaf와 샘플 전용 Dockerfile을 폴더째 지운다(지운 경로는 `docs/upgrade/2026-11-maturity-review.md` B-49). 역할은 옮기지 않는다. 샘플 안에만 있던 템플릿 검사(OpenAPI 스냅숏, Date 헤더, 가상 스레드 MDC)도 함께 지운다. 예시는 매뉴얼과 생성 명령 출력이 맡는다 | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.2절 |
|
||||
@@ -190,9 +191,9 @@
|
||||
| Querydsl 취약 좌표 | `com.querydsl:querydsl-jpa`(CVE-2024-49203, 고친 버전 없음)를 템플릿이 싣지 않는다. persistence-jpa는 쓰는 타입(`Predicate`)이 있는 querydsl-core로만 컴파일하고, querydsl-jpa는 capability를 켜는 서비스가 더한다. leaf README는 그 좌표에 고친 버전이 없다고 적고 OpenFeign 포크(`io.github.openfeign.querydsl`)를 검토하라고 한다 | 위임(2026-11-07, 총괄이 권한 안 A를 확인) | 커밋 「persistence-jpa가 querydsl-jpa 대신 querydsl-core로 컴파일한다」, `src/adapter/outbound/persistence-jpa/README.md` 「라이브러리 API」 |
|
||||
| build-logic 의존성 잠금 | 잠그지 않음 + 문서화(보류) | 소유자 | 결정 27 |
|
||||
| 릴리스 이미지 서명 | cosign keyless, tag 릴리스에서 서명·검증 | 소유자 | 결정 31 |
|
||||
| gRPC `.proto` | protobuf Gradle 플러그인 + Buf(CI) | 소유자 | 결정 18 |
|
||||
| gRPC `.proto` | protobuf Gradle 플러그인 + Buf. 2026-11-08부터 `grpc-library` repo의 `ci` 단계 | 소유자 | 결정 18 |
|
||||
| SpotBugs 신뢰도 | MEDIUM으로 내림. 패턴 단위 제외는 이유를 단다 | 위임 | `1101` 15절(08-07) |
|
||||
| 테스트 코드 정적 분석 | `testQualityCheck`는 main 빌드 `mainCheck`, optional 빌드 `ci` | 위임 | `1103` 14절 |
|
||||
| 테스트 코드 정적 분석 | `testQualityCheck`는 `mainCheck` | 위임 | `1103` 14절 |
|
||||
| lane 정책과 캐시 | lane 정책 값(`rejectSkipped` 등)은 모두 캐시 입력 | 위임 | `1103` 4절(RR-06-02) |
|
||||
| workflow 명령의 빌드 판정 | 같은 셸의 `cd <상대 경로>`도 따라간다 | 소유자 | `1103` 15절 ② |
|
||||
| 성능 lane 단언 | 끄는 스위치 없음. convention이 `performance.assertions.enabled=true`를 넣고, 빌드·lane이 다른 값을 주거나 skip이 있으면 테스트 전에 실패. 손으로 돌리든 workflow든 같은 상한 | 소유자(2026-11-06 병합 승인) | design-docs `delegation-loop/02-design.md` 13절 D9, 커밋 `e6b6e18e`, `src/build-logic/AGENTS.md` 「lane 캐시와 성능 lane」 |
|
||||
|
||||
@@ -11,7 +11,7 @@
|
||||
- **모양**: 같은 규칙·표·정규식·상수·이미지 참조가 여러 곳에 있고 이미 다르다.
|
||||
- **막는 기준**: 규칙·표·정규식·상수·이미지 참조는 한 곳에 둔다. 두 곳이 꼭 필요하면 하나를 정본으로 명시하고, 다른 하나가 정본과 같은지 보는 대조 테스트를 둔다.
|
||||
- **볼 것**: 새로 쓴 상수·정규식·표가 이미 어딘가에 있는지 grep. 같은 판정을 두 클래스가 하는지.
|
||||
- **장치**: 정본을 가져다 쓰기(예: 마이그레이션 버전 판정 정본 `VersionedMigrationFiles`를 grpc 빌드가 Sync 태스크로 가져온다), 대조 테스트(`TemplatePackageOwnershipDocumentTest`). 테스트 lane의 컨테이너 이미지는 `src/config/testing/container-images.properties` 한 곳이다(MinIO qualification 이미지만 objectstorage leaf 소유).
|
||||
- **장치**: 정본을 가져다 쓰기(예: 마이그레이션 버전 판정 정본 `VersionedMigrationFiles`), 대조 테스트(`TemplatePackageOwnershipDocumentTest`). 테스트 lane의 컨테이너 이미지는 `src/config/testing/container-images.properties` 한 곳이다(MinIO qualification 이미지만 objectstorage leaf 소유).
|
||||
|
||||
### A2. 문서와 코드 불일치
|
||||
|
||||
@@ -51,7 +51,7 @@
|
||||
|
||||
- **모양**: 어떤 단계도 돌리지 않는 lane·검사, 캐시가 옛 결과로 통과, 실패를 막지 못하는 workflow 명령을 실행으로 셈, 시간 단언을 끈 채 돈 performance lane.
|
||||
- **막는 기준**: [gates.md](gates.md) 6절. 게이트 장치를 바꾸면 일부러 망가뜨린 입력으로 실패하는 것을 본다.
|
||||
- **장치**: `verifyStrictLaneStages --dry-run`(두 빌드), lane 정책 값의 캐시 입력 선언, `testQualityCheck`, 성능 lane 단언 강제(strict lane convention이 `performance.assertions.enabled=true`를 넣고 다른 값·skip은 실패). 캐시에서 가져온 결과는 현재 통과의 증거가 아니다(필요하면 `--rerun`).
|
||||
- **장치**: `verifyStrictLaneStages --dry-run`, lane 정책 값의 캐시 입력 선언, `testQualityCheck`, 성능 lane 단언 강제(strict lane convention이 `performance.assertions.enabled=true`를 넣고 다른 값·skip은 실패). 캐시에서 가져온 결과는 현재 통과의 증거가 아니다(필요하면 `--rerun`).
|
||||
|
||||
### A8. 로그로 새는 입력값·원인
|
||||
|
||||
|
||||
@@ -18,16 +18,15 @@
|
||||
| `architectureCheck` | 의존 방향, domain-core·shared-contract·application-* 순수성, Git이 옮길 수 있는 소스, ArchUnit | PR(`ci` 안) | `src/build.gradle` |
|
||||
| `./gradlew :app-bootstrap:architectureTest` | 저장소 전체 ArchUnit suite만 | 작업 중 | app-bootstrap `architectureTest` source set |
|
||||
| `qualityCheck` | SpotBugs, FindSecBugs(운영 코드) | PR(`ci` 안) | `src/build.gradle` |
|
||||
| `testQualityCheck` | 같은 분석을 모든 테스트 source set에(`config/spotbugs/exclude-test.xml` 기준) | main(`mainCheck` 안), optional 빌드는 `ci` | `src/build.gradle` |
|
||||
| `testQualityCheck` | 같은 분석을 모든 테스트 source set에(`config/spotbugs/exclude-test.xml` 기준) | main(`mainCheck` 안) | `src/build.gradle` |
|
||||
| `ci` | leaf `check`(API surface 포함) + `architectureCheck` + `qualityCheck` | PR | `ci-quality-gates.yml`: `./gradlew :ci :verifyDependencyLocks --warning-mode=fail` |
|
||||
| `verifyStrictLaneStages --dry-run` | `explicitOnly`가 아닌 strict lane이 workflow가 실행하는 단계에 속하는가 | PR(두 빌드 각각) | `ci-quality-gates.yml`, optional 빌드는 `-p platforms/optional-build` |
|
||||
| `-p platforms/optional-build ci` | gRPC 플랫폼 빌드 | PR | `ci-quality-gates.yml` |
|
||||
| `verifyStrictLaneStages --dry-run` | `explicitOnly`가 아닌 strict lane이 workflow가 실행하는 단계에 속하는가 | PR | `ci-quality-gates.yml` |
|
||||
| `bash scripts/verify-compose-profile-contracts.sh` | compose lane이 선언대로 렌더링되는가(저장소 루트에서) | PR | `ci-quality-gates.yml` |
|
||||
| `python3 scripts/check-repo-layout.py` | 저장소 루트와 `src/` 최상위에 허용 목록 밖의 항목이 없는가, registry 경로가 허용 폴더 안인가. 아무도 가리키지 않는 compose·스크립트 파일은 경고 | PR | `ci-quality-gates.yml` |
|
||||
| `python3 scripts/check-docs.py` | 살아 있는 문서의 언어, 기록·ADR 머리 블록, 문서의 인라인 코드 경로·Gradle 경로가 지금 있는가, 복사한 숫자(`docs/README.md` 「문서 검사」). 앞에 자기 시험 `python3 -m unittest discover -s scripts/tests`를 돈다 | PR·main push | `docs-check.yml`(경로 필터 없음) |
|
||||
| `mainCheck` | `configContractCheck` + `qualificationCheck`(`testQualityCheck` 포함) + 공개 경로 스냅숏 + 전송·메시징 qualification lane + 생성 명령 왕복(`verifyFeatureScaffold`) + 모든 leaf의 `mainCheck`(document-contract lane 등) | main | `integration-main.yml`: `./gradlew :mainCheck --continue --warning-mode=fail` |
|
||||
| `integrationCheck` | 선언된 strict integration lane 전체(실 컨테이너). 입력이 없는 lane은 빼고 이름을 댄다 | main·nightly | `integration-main.yml`, optional 빌드도 |
|
||||
| `performanceCheck` | 선언된 performance lane 전체(부하·종료·풀·자원 한계, 실 서버와 컨테이너). 상한을 매번 단언한다. 손으로 돌리든 workflow든 같은 상한이다 | main·nightly | `integration-main.yml`, optional 빌드도. 5절 |
|
||||
| `integrationCheck` | 선언된 strict integration lane 전체(실 컨테이너). 입력이 없는 lane은 빼고 이름을 댄다 | main·nightly | `integration-main.yml` |
|
||||
| `performanceCheck` | 선언된 performance lane 전체(부하·종료·풀·자원 한계, 실 서버와 컨테이너). 상한을 매번 단언한다. 손으로 돌리든 workflow든 같은 상한이다 | main·nightly | `integration-main.yml`. 5절 |
|
||||
| `releaseCheck -PgitRevision=<sha>` | 릴리스 provenance + 공개 경로 스냅숏. sha 없이 돌리면 설계대로 실패한다 | 태그 | `release.yml` |
|
||||
| `:app-bootstrap:verifyEnvKeys` | env 키 레지스트리와 profile YAML·`.env.example` | `mainCheck` 안(`configContractCheck`) | build-logic `ca.config-contract` |
|
||||
| `verifyPublicPathSnapshot` | 기본 공개 경로가 `docs/security/public-paths-snapshot.txt`와 같은가 | `mainCheck`·`releaseCheck` 안 | `src/build.gradle` |
|
||||
@@ -52,7 +51,7 @@
|
||||
| 파일·폴더·Gradle 프로젝트를 지우거나 옮김 | `python3 scripts/check-docs.py`(문서가 가리키던 경로가 사라진다) |
|
||||
| `docs/work/`, 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서 | `python3 scripts/check-work-docs.py` |
|
||||
| 다른 매뉴얼에서 이력 ID를 걷어냄 | `python3 scripts/check-work-docs.py --history <파일 또는 폴더>` |
|
||||
| build-logic·workflow | `-p build-logic check javadoc`, 두 빌드의 `verifyStrictLaneStages --dry-run` |
|
||||
| build-logic·workflow | `-p build-logic check javadoc`, `verifyStrictLaneStages --dry-run` |
|
||||
| 패키지 규칙, 생성 명령 템플릿 | `verifyFeatureScaffold`(`mainCheck` 안) |
|
||||
| 마이그레이션 | persistence-jpa `check`, 잠금 대기 lane(`postgresqlMigrationLockWaitIntegrationTest`), 마이그레이션 lane |
|
||||
| 테스트 코드(ArchUnit fixture 포함) | 그 leaf `testQualityCheck` |
|
||||
@@ -89,7 +88,7 @@ python3 scripts/check-work-docs.py --links $(git ls-files ':(glob)README.md' ':(
|
||||
| main 단계 | (가)의 `# main push` 줄과 `run-compose-runtime-smoke.sh`·`check-docs.py`(자기 시험 포함), (나)에서 main `push`로 켜지는 것 |
|
||||
| 라운드 끝 | 위 둘 전부와 (가)의 `# 태그` 두 줄 |
|
||||
|
||||
- 태그 두 줄(`releaseCheck`)은 합친 트리에서 provenance와 공개 경로 스냅숏이 깨지지 않았는지만 본다. `release.yml`의 다른 job(web·websocket·gRPC·httpclient·jpa·fileserver release gate, 이미지)은 릴리스 전에만 돈다([operate.md](../operate.md) 4.3절). 결과 표에 "태그 단계 — 라운드 끝 아님"으로 적는다.
|
||||
- 태그 두 줄(`releaseCheck`)은 합친 트리에서 provenance와 공개 경로 스냅숏이 깨지지 않았는지만 본다. `release.yml`의 다른 job(web·websocket·httpclient·jpa·fileserver release gate, 이미지)은 릴리스 전에만 돈다([operate.md](../operate.md) 4.3절). 결과 표에 "태그 단계 — 라운드 끝 아님"으로 적는다.
|
||||
|
||||
**실제로 돌았음을 보이기.** 새 detached worktree에서 시작하고 모든 Gradle 명령에 `--no-build-cache`를 붙인다. workflow 명령에 그 옵션이 없어도(예: `tasks --group verification`) 증거 실행에는 붙인다. 바뀌는 것은 캐시 사용뿐이라 판정은 같다. 로그마다 `grep -c 'FROM-CACHE' <로그>`가 0이어야 한다. UP-TO-DATE는 같은 worktree에서 앞 명령이 만든 출력일 때만 받아들인다(4절). `--rerun`은 바로 앞 태스크 하나에만 걸려 `ci` 같은 집계 태스크의 증거가 되지 않는다.
|
||||
|
||||
@@ -102,18 +101,13 @@ cd src
|
||||
# PR: ci-quality-gates.yml
|
||||
./gradlew :ci :verifyDependencyLocks --warning-mode=fail --no-build-cache --console=plain
|
||||
./gradlew :verifyStrictLaneStages --dry-run --console=plain
|
||||
./gradlew -p platforms/optional-build ci --no-build-cache --console=plain
|
||||
./gradlew -p platforms/optional-build :verifyStrictLaneStages --dry-run --console=plain
|
||||
# main push: integration-main.yml
|
||||
./gradlew :mainCheck --continue --warning-mode=fail --no-build-cache --console=plain
|
||||
./gradlew :integrationCheck --continue --no-build-cache --console=plain
|
||||
./gradlew :performanceCheck --continue --no-build-cache --console=plain
|
||||
./gradlew -p platforms/optional-build performanceCheck --continue --no-build-cache --console=plain
|
||||
./gradlew -p platforms/optional-build integrationCheck --no-build-cache --console=plain
|
||||
./gradlew :adapter:outbound:httpclient:test -Phttp3.tests.enabled=true --no-build-cache --console=plain # 실험 job, 실패해도 workflow는 통과
|
||||
# 태그: release.yml (CI는 GITHUB_SHA로 커밋을 받는다. 손으로 돌릴 때는 -PgitRevision)
|
||||
./gradlew :releaseCheck -PgitRevision="$(git rev-parse HEAD)" --no-build-cache --console=plain
|
||||
./gradlew -p platforms/optional-build releaseCheck -PgitRevision="$(git rev-parse HEAD)" --no-build-cache --console=plain
|
||||
cd ..
|
||||
bash scripts/verify-compose-profile-contracts.sh
|
||||
python3 scripts/check-repo-layout.py
|
||||
@@ -141,7 +135,6 @@ bash scripts/run-compose-runtime-smoke.sh --matrix src/app-bootstrap/compose-lan
|
||||
| job | 로컬에서 | 대체가 못 보는 것 |
|
||||
| --- | --- | --- |
|
||||
| `link-check.yml`(lychee) | 2절 끝의 같은 범위 상대 링크 검사. desktop에 lychee 공식 이미지가 이미 있으면 그 이미지로 같은 범위를 돌린다 | 외부 URL |
|
||||
| `ci-quality-gates.yml` `grpc-proto-buf`(`buf lint`·`buf breaking`) | buf나 desktop에 이미 있는 buf 공식 이미지가 있으면 job의 `run` 줄 그대로. 없으면 못 돌림으로 적는다. diff에 `.proto`·`buf*.yaml`이 없으면 "해당 없음 — proto 변경 없음" | 전부 |
|
||||
| `dependency-vulnerability.yml` `dependency-review`·`dependency-submission` | GitHub에서만 돈다. diff에 lockfile·`src/gradle/libs.versions.toml` 변경이 없으면 "해당 없음", 있으면 PR 결과를 보고 남은 문제로 적는다 | 전부 |
|
||||
| `dependency-vulnerability.yml` `trivy-fs` | 이미 설치된 trivy나 desktop에 이미 있는 trivy 공식 이미지가 있으면 job의 검사 줄 그대로. workflow가 쓰는 버전이 없으면 있는 버전으로 기준 트리와 이번 트리를 같은 DB로 돌려 새로 생긴 걸림만 이번 변경 몫으로 본다. job이 trivy를 내려받아 설치하는 줄은 따라 하지 않는다([operate.md](../operate.md) 4.1절). 없으면 못 돌림 | 전부(못 돌렸을 때) |
|
||||
|
||||
@@ -206,7 +199,6 @@ for k in tests skipped failures errors; do cat $(find "$x" -name 'TEST-*.xml') |
|
||||
| 거짓 통과 모양 | 지금의 장치 |
|
||||
| --- | --- |
|
||||
| 어떤 workflow도 돌리지 않는 lane | `verifyStrictLaneStages --dry-run`(PR) |
|
||||
| optional 빌드를 보지 않음 | optional 빌드도 같은 검사 |
|
||||
| 실패를 막지 못하는 workflow 명령을 실행으로 셈(`\|\| true`, pipefail 없는 파이프, `if` 조건 등) | `src/build-logic/AGENTS.md` 「`verifyStrictLaneStages`가 세는 명령」 |
|
||||
| lane 정책을 바꿨는데 캐시가 옛 결과로 통과 | lane 정책 값을 Test 입력으로 |
|
||||
| 게이트 밖에서 실패한 채 방치된 검사 | `testQualityCheck`(`mainCheck`) |
|
||||
|
||||
@@ -0,0 +1,39 @@
|
||||
# 관련 저장소 — 템플릿 밖에서 관리하는 라이브러리
|
||||
|
||||
프로젝트 계층이 아닌 라이브러리는 이 repo에 두지 않는다(소유자 결정 2026-11-07, [decisions.md](decisions.md) 「라이브러리 repo」). 라이브러리마다 별도 repo에서 고치고 Gitea Packages에 버전으로 배포한다. 이 문서는 그 목록과, 템플릿에서 그 라이브러리를 다루는 법이다. 설계 근거는 design-docs `repo-structure/05-library-repos.md`다.
|
||||
|
||||
## 1. 목록
|
||||
|
||||
| repo | 무엇 | Maven group | 카탈로그 칸 | 쓰는 leaf |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| [grpc-library](https://git.learn.hyeonworks.com/donghyeon.kang/grpc-library) | gRPC 플랫폼(Stable 7, advanced 2) | `dev.cakit.grpc` | 없음(채택 전) | 없음. `adapter:inbound:grpc`는 `io.grpc`를 직접 쓴다. 채택은 별도 결정이다 |
|
||||
| `messaging-library` | 메시징 제품 | `dev.cakit.messaging` | (옮긴 뒤 `messagingLibrary`) | 아직 `src/platforms/messaging`에 있다. 다음 분리 작업에서 옮긴다 |
|
||||
|
||||
고치는 법·게이트·릴리스는 각 repo의 `docs/work/`다. 이 repo의 매뉴얼은 위치만 가리킨다.
|
||||
|
||||
## 2. 라이브러리를 고칠 때
|
||||
|
||||
- 템플릿 안에서 라이브러리 코드를 고치지 않는다. 라이브러리 repo에서 고치고 릴리스한다.
|
||||
- 템플릿 변경 때문에 라이브러리를 고쳐야 하면 브랜치를 둘 만들고, 템플릿에서 명령 줄로만 끼워 같이 시험한다.
|
||||
|
||||
```bash
|
||||
./gradlew --include-build ../grpc-library <태스크>
|
||||
```
|
||||
|
||||
그 상태로 lockfile을 쓰거나 커밋하지 않는다.
|
||||
- 병합 순서는 하나다: 라이브러리 PR 병합 → 태그·릴리스 → 템플릿 PR에서 버전을 올리고 lockfile을 다시 쓴다 → 템플릿 병합.
|
||||
- 라이브러리가 끌고 온 취약 의존성은 템플릿에서 먼저 덮어 막고(Boot 버전이나 카탈로그 `pinned-*`), 라이브러리 repo에 수정을 남긴다.
|
||||
|
||||
## 3. 템플릿이 라이브러리 버전을 올릴 때
|
||||
|
||||
라이브러리를 카탈로그로 받는 leaf가 생긴 뒤의 절차다(지금은 없다).
|
||||
|
||||
1. `src/gradle/libs.versions.toml`의 라이브러리 버전 칸을 바꾼다.
|
||||
2. desktop에서 `./gradlew resolveAndLockAll --write-locks` 뒤 `verifyDependencyLocks`.
|
||||
3. 쓰는 leaf의 `check`와 `architectureCheck`, 그 leaf의 lane.
|
||||
4. 라이브러리 `CHANGELOG.md`에서 그 사이 버전의 깨지는 변경을 읽는다. MAJOR면 `docs/upgrade/`에 행을 더하고 커밋 제목에 `!`.
|
||||
5. 커밋 제목 예: `build(deps): gRPC 라이브러리를 1.1.0으로 올린다`.
|
||||
|
||||
## 4. 받는 법(처음 채택할 때)
|
||||
|
||||
`src/settings.gradle`의 저장소 선언에 Gitea Maven 저장소를 `exclusiveContent`로 더한다. `dev.cakit` group은 그 저장소에서만, 나머지는 Maven Central에서만 찾는다. 선언 예는 라이브러리 repo README 「받는 법」이다. 공개 owner라 읽기 토큰은 필요 없다.
|
||||
@@ -139,7 +139,7 @@
|
||||
| DB 오류·경쟁 | `PersistenceExceptionTranslator`, `@Version`, 트랜잭션 마감 |
|
||||
| 메시지 중복·역순 | outbox relay, inbox 재전달, aggregate 순서 번호 |
|
||||
| 신·구 버전 공존 | 마이그레이션 잠금, 배포 중 섞인 인스턴스 |
|
||||
| 여러 서버의 작업 실행 | 알림 정산 job claim, gRPC ledger claim |
|
||||
| 여러 서버의 작업 실행 | 알림 정산 job claim, 멱등성 실행 lease |
|
||||
| 다른 사용자 리소스 접근 | 파일 서버 소유자 검사, durable operation 소유자·tenant 검사 |
|
||||
| 큰 입력·목록 조회 | 파일 서버 업로드 크기 한도, GraphQL 복잡도, JSON 아닌 본문 |
|
||||
| 종료·재시작 | relay·platform 종료 순서, 종료 시간 예산 |
|
||||
@@ -201,7 +201,8 @@ RED가 증거가 되려면: 실패 메시지가 그 결함을 말한다. 머신
|
||||
- 새 업무 기능은 계층 leaf 안의 패키지가 기본이다(`docs/manual/03-placement.md`).
|
||||
- 템플릿 패키지 목록은 `src/application-core/README.md` 「패키지 소유 (Package ownership)」 표 하나가 정본이다. 템플릿에 패키지를 더하면 같은 변경에서 표에 넣는다.
|
||||
- capability는 자기 `AutoConfiguration.imports`로 켜진다. `app-bootstrap`은 capability 이름·스위치 목록·scan 정규식을 갖지 않는다.
|
||||
- vendored family(`messaging:*`, 같은 방식의 `grpc:*`)는 `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 그래서 남는 복사본은 이유를 family `AGENTS.md`에 적고, 값이 같아야 하면 대조 테스트를 둔다.
|
||||
- 다른 경계(다른 leaf, 다른 빌드, 다른 repo가 될 수 있는 폴더)의 파일을 경로(`../../../`)로 읽는 빌드 스크립트·테스트는 결함 후보다. 그 경계가 옮겨 가면 조용히 깨진다. gRPC 라이브러리를 옮길 때 이런 결합이 다섯 곳 나왔다(design-docs `repo-structure/05-library-repos.md` 4.6절).
|
||||
- vendored family(`messaging:*`)는 `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 그래서 남는 복사본은 이유를 family `AGENTS.md`에 적고, 값이 같아야 하면 대조 테스트를 둔다.
|
||||
- source set은 runtime·classpath·외부 인프라·JVM 옵션·실행 비용 중 하나가 다를 때만 나눈다. 공유 테스트 코드는 `src/testFixtures/java`다(`docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md`).
|
||||
- 마이그레이션은 저장소마다 자기 디렉터리와 history table을 가진다. 번호는 스트림 안의 순번이다. 어딘가에 적용된 파일은 고치지 않는다(`src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256`이 해시를 고정한다).
|
||||
- 문서 위치 규칙은 `docs/README.md`가 정본이다.
|
||||
|
||||
@@ -71,7 +71,7 @@ SRC_ALLOWED = {
|
||||
"composition": "조립(Clean Architecture의 Main)",
|
||||
"app-bootstrap": "조립 루트",
|
||||
# 들여온 제품
|
||||
"platforms": "들여온 제품(messaging, grpc, grpc-advanced)과 optional 빌드",
|
||||
"platforms": "들여온 제품(messaging). gRPC는 2026-11-08 별도 repo grpc-library로",
|
||||
# Gradle 루트 표준
|
||||
"build-logic": "빌드 규칙(included build)",
|
||||
"config": "빌드 전체 도구 설정(registry, checkstyle, spotbugs, 테스트 이미지)",
|
||||
|
||||
@@ -74,7 +74,7 @@ executor, 서버 deadline 없음, 연결 수명 무제한이다. 어댑터 서
|
||||
- **값이 두 곳에 있는 이유.** 03-09 는 (a) 어댑터가 같은 이름·값을 자기 설정으로 노출, (b)
|
||||
어댑터가 플랫폼 `GrpcServerProfile` 을 받음(registry edge 추가), (c) 현상 유지 중 (a)를 골랐다.
|
||||
두 스택 분리(X1-#10)를 건드리지 않기 위해서다. 어댑터는 플랫폼 타입을 import 할 수 없어(registry
|
||||
edge 없음, 플랫폼은 `optional-platforms` 별도 빌드) 상수를 직접 비교하는 테스트는 만들 수 없다.
|
||||
edge 없음, 플랫폼은 2026-11-08부터 별도 repo `grpc-library`) 상수를 직접 비교하는 테스트는 만들 수 없다.
|
||||
대신 `GrpcSafeActivationTest.transportBoundDefaultsMatchTheVendoredPlatformDefaults` 가 위 표의
|
||||
플랫폼 값을 literal 로 고정한다. 플랫폼 값을 바꾸면 이 표와 그 테스트를 같이 바꾼다.
|
||||
- **duration 순서 검증.** `keep-alive-timeout < keep-alive-time`, `permit-keep-alive-time <=
|
||||
|
||||
@@ -46,6 +46,6 @@ apiSurface {
|
||||
adopterBaseline = rootProject.file('../docs/architecture/persistence-fileserver-adopter-api-surface.txt')
|
||||
adopterSources = fileTree(rootProject.projectDir) {
|
||||
include '*/**/src/main/java/**/*.java'
|
||||
exclude '**/build/**', 'adapter/outbound/persistence-fileserver/**', 'build-logic/**', 'platforms/optional-build/**'
|
||||
exclude '**/build/**', 'adapter/outbound/persistence-fileserver/**', 'build-logic/**'
|
||||
}
|
||||
}
|
||||
|
||||
@@ -357,7 +357,7 @@ apiSurface {
|
||||
include '*/**/src/main/java/**/*.java'
|
||||
exclude '**/build/**', 'adapter/outbound/persistence-jpa/**', 'adapter/outbound/persistence-fileserver/**',
|
||||
'adapter/outbound/persistence-notification/**',
|
||||
'build-logic/**', 'platforms/optional-build/**'
|
||||
'build-logic/**'
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
+2
-2
@@ -15,8 +15,8 @@ import org.junit.jupiter.api.io.TempDir;
|
||||
/**
|
||||
* One definition of a versioned migration for every check that walks a tree (re-review 2026-11-03
|
||||
* round 3, RR3-02-03): the operating trees' checks once skipped {@code V22_1__} while the sample's
|
||||
* counted it. The gRPC ledger's list in the optional build is compiled from this same source
|
||||
* (README 12, r6-b; r9).
|
||||
* counted it. The grpc-library repository's ledger lanes keep a copy of this source (README 12,
|
||||
* r6-b; r9).
|
||||
*/
|
||||
class VersionedMigrationFilesTest {
|
||||
|
||||
|
||||
+5
-5
@@ -36,11 +36,11 @@ import java.util.regex.Pattern;
|
||||
* Flyway's default the lock's own open transaction is one of those, and the deploy never ends
|
||||
* (re-review 2026-11-03 round 6, RR6-03-01 and RR6-03-05).
|
||||
*
|
||||
* <p>The gRPC ledger's lane uses it too. It lives in the optional build, which cannot depend on
|
||||
* this testkit, so {@code grpc-operation-ledger-jpa} compiles this file and {@link
|
||||
* MigrationResource} from here into its integration-test sources at build time (its {@code
|
||||
* build.gradle}, {@code sharedMigrationFileSources}; round 7, RR7-03-01). Hence the rule for both
|
||||
* files: the JDK only, nothing else from this testkit.
|
||||
* <p>The gRPC ledger's lane uses it too. Since 2026-11-08 that lane lives in the separate
|
||||
* grpc-library repository, which keeps a copy of this file and {@link MigrationResource} in its
|
||||
* integration-test sources (until then its build compiled them from here; round 7, RR7-03-01). This
|
||||
* file is the original: a fix here is copied there by hand. Hence the rule for both files: the JDK
|
||||
* only, nothing else from this testkit.
|
||||
*/
|
||||
public final class ConcurrentIndexMigrationInspector {
|
||||
|
||||
|
||||
+1
-1
@@ -5,7 +5,7 @@ import java.util.Objects;
|
||||
/**
|
||||
* One migration script as the inspector sees it (design §32).
|
||||
*
|
||||
* <p>The gRPC ledger's lane in the optional build compiles this file with {@link
|
||||
* <p>The grpc-library repository keeps a copy of this file with {@link
|
||||
* ConcurrentIndexMigrationInspector} (see there), so it keeps to the JDK only.
|
||||
*
|
||||
* @param name the versioned script name, e.g. {@code V42__order_index.sql}
|
||||
|
||||
+5
-5
@@ -24,11 +24,11 @@ import java.util.stream.Stream;
|
||||
* V22_1__} while the sample's counted it, so a decimal version in an operating tree was neither
|
||||
* pinned nor held to the lock-wait rule (re-review 2026-11-03 round 3, RR3-02-03).
|
||||
*
|
||||
* <p>The gRPC ledger's lanes use it too. They live in the optional build, which cannot depend on
|
||||
* this testkit, so {@code grpc-operation-ledger-jpa} compiles this one file from here into its
|
||||
* integration-test sources at build time (its {@code build.gradle}, {@code
|
||||
* sharedMigrationFileSources}) instead of keeping a copy that could drift (re-review README 12,
|
||||
* r6-b; r9). Hence the rule for this file: the JDK only, nothing else from this testkit.
|
||||
* <p>The gRPC ledger's lanes use it too. Since 2026-11-08 they live in the separate grpc-library
|
||||
* repository, which keeps a copy of this file in its integration-test sources (until then its build
|
||||
* compiled this one from here; re-review README 12, r6-b; r9). This file is the original: a fix
|
||||
* here is copied there by hand. Hence the rule for this file: the JDK only, nothing else from this
|
||||
* testkit.
|
||||
*/
|
||||
public final class VersionedMigrationFiles {
|
||||
|
||||
|
||||
@@ -124,8 +124,7 @@ sourceSets {
|
||||
// Every capability a service can select — the commented runtimeOnly lines below — listed once.
|
||||
// Three consumers read it — the environment contract's metadata classpath (verifyEnvKeys, below)
|
||||
// and these two: the whole-repository ArchUnit import (spec §7: the architecture suite sees
|
||||
// every module of this build, the shipped runtime only the selected ones; the
|
||||
// optional-platforms build is held by its own Gradle direction gate instead) and the qualification artifact the
|
||||
// every module of this build, the shipped runtime only the selected ones) and the qualification artifact the
|
||||
// Compose lanes boot (qualificationBootJar, below). None of them reaches `bootJar`, `test` or
|
||||
// `systemTest`, because a capability on a classpath is switched on there by its mere presence.
|
||||
// A new capability leaf is added here and as a commented line below; nowhere else.
|
||||
@@ -181,10 +180,6 @@ dependencies {
|
||||
integrationTestImplementation project(':composition:service-runtime')
|
||||
|
||||
capabilityProjects.each { architectureTestRuntimeOnly project(it) }
|
||||
// What this import does NOT see: the optional-platforms build (`grpc:*`, `grpc-advanced:*`).
|
||||
// It is a separate Gradle build, so its classes cannot be on this classpath; its registered
|
||||
// leaves are held by the Gradle direction gate (`-p platforms/optional-build ci` runs
|
||||
// verifyCleanArchitectureDependencies), which is the whole of what the owner decided it needs.
|
||||
|
||||
// The capability integration lane selects Fileserver and object storage together, as a service
|
||||
// would, and turns off whichever one a test is not about.
|
||||
|
||||
-24
@@ -362,30 +362,6 @@ class DeveloperExperienceContractTest {
|
||||
.noneMatch(step -> step instanceof Map<?, ?> map && map.containsKey("uses"));
|
||||
}
|
||||
|
||||
@Test
|
||||
@Tag("repository-contract")
|
||||
void everyOptionalPlatformIntegrationLaneHasAnExecutingWorkflowCaller() throws IOException {
|
||||
// `grpc-operation-ledger-jpa` declares a Testcontainers PostgreSQL lane that certifies the
|
||||
// atomic claim durable mutation idempotency rests on. It was registered in `strictTestLanes`,
|
||||
// fails closed, and ran nowhere: the optional build's `ci` reaches `checkAll`, `qualityCheck`
|
||||
// and the dependency verifier, and none of those runs a lane whose category is INTEGRATION.
|
||||
// A lane nobody runs is not coverage, so both halves are pinned here — the aggregate that
|
||||
// covers the category, and the workflow that executes the aggregate.
|
||||
assertThat(read("src/platforms/optional-build/build.gradle"))
|
||||
.as("the optional platform build must aggregate its integration-category lanes")
|
||||
.contains("tasks.register('integrationCheck')")
|
||||
.contains(":integrationTestLaneCheck");
|
||||
|
||||
assertThat(read("src/platforms/grpc/grpc-operation-ledger-jpa/build.gradle"))
|
||||
.as("the operation ledger lane this contract protects must still be declared")
|
||||
.contains("lane('integrationTest')")
|
||||
.contains("integration()");
|
||||
|
||||
assertThat(read(".github/workflows/integration-main.yml"))
|
||||
.as("a workflow must actually execute the optional platform integration aggregate")
|
||||
.contains("./gradlew -p platforms/optional-build integrationCheck");
|
||||
}
|
||||
|
||||
@Test
|
||||
@Tag("repository-contract")
|
||||
@DisplayName("compose 종료 유예 시간은 웹 drain, async 대기, preStop, 여유를 모두 더한 값 이상이다")
|
||||
|
||||
@@ -25,7 +25,7 @@ registry, settings, build-logic, 루트 라이프사이클이 정하는 것을
|
||||
|
||||
## `verifyStrictLaneStages`가 세는 명령
|
||||
|
||||
`verifyStrictLaneStages --dry-run`(PR 게이트)은 그 빌드에서 `explicitOnly`가 아닌 strict lane이 workflow가 실제로 실행하는 단계(main 빌드: `ci`·`mainCheck`·`integrationCheck`·`performanceCheck`·`releaseCheck`, optional-platforms 빌드: `-p platforms/optional-build`로 부르는 `ci`·`integrationCheck`·`performanceCheck`·`releaseCheck`) 중 하나에 들어 있는지, 그리고 workflow의 접힌(`>`) run 블록이 빈 줄 때문에 옵션을 별개 명령으로 떼어 내지 않는지 검사한다. 두 빌드가 각자 검사를 돌린다. `-x`로 뺀 lane(Gradle처럼 축약 이름도 맞춰 본다)은 덮이지 않는다. Gradle이 작업을 돌리지 않는 명령(`--dry-run`·`-m`·`-v`·`--help`·`--status`·`--stop`·`--foreground`, 묶음 `-qm`·`-qv` 포함)과 Gradle이 거부하는 짧은 옵션 묶음(`-mx`), 다른 빌드를 실행하는 명령은 세지 않는다. 그 밖에 세지 않는 명령은 이유가 셋이다.
|
||||
`verifyStrictLaneStages --dry-run`(PR 게이트)은 그 빌드에서 `explicitOnly`가 아닌 strict lane이 workflow가 실제로 실행하는 단계(`ci`·`mainCheck`·`integrationCheck`·`performanceCheck`·`releaseCheck`) 중 하나에 들어 있는지, 그리고 workflow의 접힌(`>`) run 블록이 빈 줄 때문에 옵션을 별개 명령으로 떼어 내지 않는지 검사한다. `-x`로 뺀 lane(Gradle처럼 축약 이름도 맞춰 본다)은 덮이지 않는다. Gradle이 작업을 돌리지 않는 명령(`--dry-run`·`-m`·`-v`·`--help`·`--status`·`--stop`·`--foreground`, 묶음 `-qm`·`-qv` 포함)과 Gradle이 거부하는 짧은 옵션 묶음(`-mx`), 다른 빌드를 실행하는 명령은 세지 않는다. 그 밖에 세지 않는 명령은 이유가 셋이다.
|
||||
|
||||
1. 실패해도 단계가 실패하지 않을 수 있다: `|| exit <0 아닌 값>` 밖의 `||`(`|| true` 등), pipefail 없는 파이프 왼쪽, `!`, `&`, `if`·`while` 조건, 스크립트 마지막이 아닌 `&&` 목록의 앞쪽, `set +e` 뒤, `exit 0` 하는 `EXIT`·`ERR` trap 뒤, `continue-on-error`.
|
||||
2. 돌지 않을 수 있다: `||` 뒤, 마지막이 아닌 `&&` 목록의 뒤쪽, `if`·`while`·`for`·`case`·함수 본문 안, 최상위 `exit`·`exec`·`set -n` 뒤, 조건부이거나 부른 함수 안의 `exit 0`(인자 없는 `exit`, 값을 모르는 `exit` 포함)·`exec`·`set -n` 뒤, 상태 함수(`always()`·`success()`·`!cancelled()`)가 아닌 `if:` 아래, 요청으로만 시작하는 workflow(`workflow_dispatch`·`repository_dispatch`·`issue_comment` 등), `paths`·`paths-ignore` 필터가 붙은 change trigger로만 시작하는 workflow(그 경로 밖 변경에는 돌지 않는다), 태그 push(`branches` 없는 `tags`)나 `release`로만 시작하는 workflow(`releaseCheck` 밖의 단계), 세는 job이 부르지 않는 `workflow_call` 재사용 workflow, 조건부이거나 `continue-on-error`인 job을 `needs`로 기다리는 job.
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -71,10 +71,6 @@ gradlePlugin {
|
||||
id = 'ca.architecture-registry'
|
||||
implementationClass = 'dev.caskeleton.buildlogic.settings.ArchitectureRegistrySettingsPlugin'
|
||||
}
|
||||
optionalArchitectureRegistrySettings {
|
||||
id = 'ca.optional-architecture-registry'
|
||||
implementationClass = 'dev.caskeleton.buildlogic.settings.OptionalArchitectureRegistrySettingsPlugin'
|
||||
}
|
||||
javaLibraryConvention {
|
||||
id = 'ca.java-library'
|
||||
implementationClass = 'dev.caskeleton.buildlogic.convention.JavaLibraryConventionPlugin'
|
||||
@@ -95,10 +91,6 @@ gradlePlugin {
|
||||
id = 'ca.config-contract'
|
||||
implementationClass = 'dev.caskeleton.buildlogic.config.ConfigContractPlugin'
|
||||
}
|
||||
grpcPlatformModuleConvention {
|
||||
id = 'ca.grpc-platform-module'
|
||||
implementationClass = 'dev.caskeleton.buildlogic.convention.GrpcPlatformModuleConventionPlugin'
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -1,78 +0,0 @@
|
||||
package dev.caskeleton.buildlogic;
|
||||
|
||||
import java.io.File;
|
||||
import java.io.IOException;
|
||||
import java.io.UncheckedIOException;
|
||||
import org.gradle.api.GradleException;
|
||||
|
||||
/**
|
||||
* Where the main build is, seen from any build of this repository.
|
||||
*
|
||||
* <p>The main build is the Gradle root that owns the module registry ({@code
|
||||
* config/architecture/modules.json}); the repository root is its parent. The optional platform build
|
||||
* lives inside it ({@code src/platforms/optional-build}), and the code that needs the registry, the
|
||||
* shared tool configuration or the test image catalog used to reach the main build by taking one
|
||||
* parent of the optional build's root. That held only while the optional build sat directly under
|
||||
* the main build; it is found by walking up instead, so the optional build's depth is not a fact
|
||||
* every caller repeats.
|
||||
*/
|
||||
public final class MainBuild {
|
||||
/** The registry, relative to the main build: what makes a directory the main build. */
|
||||
public static final String REGISTRY = "config/architecture/modules.json";
|
||||
|
||||
private MainBuild() {}
|
||||
|
||||
/**
|
||||
* The main build's directory: {@code buildRoot} itself or the nearest directory above it that
|
||||
* holds the module registry.
|
||||
*
|
||||
* @param buildRoot the root directory of the build asking (its settings or root project directory)
|
||||
* @return the canonical main build directory
|
||||
*/
|
||||
public static File directory(File buildRoot) {
|
||||
File registry = nearest(buildRoot, REGISTRY);
|
||||
if (registry == null) {
|
||||
throw new GradleException(
|
||||
"No " + REGISTRY + " at or above " + buildRoot + "; this build is not inside the repository");
|
||||
}
|
||||
return registry.getParentFile().getParentFile().getParentFile();
|
||||
}
|
||||
|
||||
/**
|
||||
* The nearest {@code relativePath} at or above {@code buildRoot}: in the build's own root first,
|
||||
* then in each parent. A file or a directory; {@code null} when no ancestor has it.
|
||||
*
|
||||
* @param buildRoot the root directory of the build asking
|
||||
* @param relativePath the path to look for, relative to each candidate directory
|
||||
* @return the canonical path found, or {@code null}
|
||||
*/
|
||||
public static File nearest(File buildRoot, String relativePath) {
|
||||
for (File directory = canonical(buildRoot);
|
||||
directory != null;
|
||||
directory = directory.getParentFile()) {
|
||||
File candidate = new File(directory, relativePath);
|
||||
if (candidate.exists()) {
|
||||
return candidate;
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* The repository root: the main build's parent.
|
||||
*
|
||||
* @param buildRoot the root directory of the build asking
|
||||
* @return the canonical repository root
|
||||
*/
|
||||
public static File repositoryRoot(File buildRoot) {
|
||||
return directory(buildRoot).getParentFile();
|
||||
}
|
||||
|
||||
private static File canonical(File file) {
|
||||
try {
|
||||
return file.getCanonicalFile();
|
||||
} catch (IOException exception) {
|
||||
throw new UncheckedIOException("cannot resolve " + file, exception);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -108,7 +108,17 @@ public record ModuleRegistry(List<Module> modules, File source) {
|
||||
String id = requireNonBlankText(module, "id", index);
|
||||
String gradlePath = requireNonBlankText(module, "gradle_path", index);
|
||||
String sourcePath = requireNonBlankText(module, "source_path", index);
|
||||
String buildName = module.has("build") ? requireNonBlankText(module, "build", id) : "main";
|
||||
// Every module belongs to the main build. The only other build (the optional gRPC platform
|
||||
// build) moved to the grpc-library repository on 2026-11-08, and a row naming any build but
|
||||
// this one would be included by no settings and checked by no direction gate while ci stays
|
||||
// green, so the field is refused rather than read.
|
||||
if (module.has("build")) {
|
||||
throw new IllegalStateException(
|
||||
"Module registry entry '"
|
||||
+ id
|
||||
+ "' has a 'build' field; every module belongs to the main build, so remove it.");
|
||||
}
|
||||
String buildName = "main";
|
||||
List<String> allowedDependencies =
|
||||
requireStringList(module.get("allowed_dependencies"), id, "allowed_dependencies");
|
||||
|
||||
@@ -192,7 +202,7 @@ public record ModuleRegistry(List<Module> modules, File source) {
|
||||
* <p>The settings plugin includes only registered modules, so a leaf directory nobody registered
|
||||
* is not compiled, not tested and not compared by any gate, while {@code ci} stays green (review
|
||||
* 2026-11-01 08-05). The walk skips the root's own script, every directory with its own settings
|
||||
* script (a separate build, such as build-logic or optional-platforms), build output, and the
|
||||
* script (a separate build, such as build-logic), build output, and the
|
||||
* inside of a module's {@code src} tree, where a build script is a test fixture.
|
||||
*/
|
||||
public List<String> unregisteredBuildScripts(File gradleRoot) {
|
||||
|
||||
+6
-12
@@ -1,6 +1,5 @@
|
||||
package dev.caskeleton.buildlogic.architecture;
|
||||
|
||||
import dev.caskeleton.buildlogic.MainBuild;
|
||||
import dev.caskeleton.buildlogic.ModuleRegistry;
|
||||
import java.io.File;
|
||||
import java.nio.file.Path;
|
||||
@@ -30,13 +29,13 @@ public final class ArchitecturePlugin implements Plugin<Project> {
|
||||
@Override
|
||||
public void apply(Project project) {
|
||||
Project root = project.getRootProject();
|
||||
boolean optionalGrpcBuild = root.getName().equals("optional-platforms");
|
||||
String buildName = optionalGrpcBuild ? "optional-grpc" : "main";
|
||||
File mainBuildDirectory = MainBuild.directory(root.getProjectDir());
|
||||
File registryFile = new File(mainBuildDirectory, MainBuild.REGISTRY);
|
||||
// The Gradle root (src/) owns the registry; the repository root is its parent, and every
|
||||
// source_path in the registry is relative to the repository root.
|
||||
File mainBuildDirectory = root.getProjectDir();
|
||||
File registryFile = new File(mainBuildDirectory, "config/architecture/modules.json");
|
||||
File repositoryRoot = mainBuildDirectory.getParentFile();
|
||||
ModuleRegistry registry = ModuleRegistry.read(registryFile, repositoryRoot);
|
||||
List<ModuleRegistry.Module> modules = registry.modulesForBuild(buildName);
|
||||
List<ModuleRegistry.Module> modules = registry.modulesForBuild("main");
|
||||
List<String> registryViolations = registryViolations(registry, modules);
|
||||
|
||||
var clean =
|
||||
@@ -50,13 +49,8 @@ public final class ArchitecturePlugin implements Plugin<Project> {
|
||||
task.setDescription("Verifies Clean Architecture project dependency direction.");
|
||||
task.getRegistryFile().fileValue(registryFile);
|
||||
task.getRegistryViolations().set(registryViolations);
|
||||
// The main build owns the whole Gradle root; optional-platforms is a directory
|
||||
// inside it with its own settings, which the walk skips.
|
||||
task.getUnregisteredBuildScripts()
|
||||
.set(
|
||||
optionalGrpcBuild
|
||||
? List.of()
|
||||
: registry.unregisteredBuildScripts(root.getProjectDir()));
|
||||
.set(registry.unregisteredBuildScripts(root.getProjectDir()));
|
||||
});
|
||||
var purity =
|
||||
project
|
||||
|
||||
-28
@@ -1,28 +0,0 @@
|
||||
package dev.caskeleton.buildlogic.convention;
|
||||
|
||||
import io.spring.gradle.dependencymanagement.dsl.DependencyManagementExtension;
|
||||
import org.gradle.api.GradleException;
|
||||
import org.gradle.api.Plugin;
|
||||
import org.gradle.api.Project;
|
||||
import org.gradle.api.artifacts.VersionCatalogsExtension;
|
||||
|
||||
public final class GrpcPlatformModuleConventionPlugin implements Plugin<Project> {
|
||||
@Override
|
||||
public void apply(Project project) {
|
||||
project.getPluginManager().apply("ca.platform-module");
|
||||
|
||||
var catalogs = project.getExtensions().getByType(VersionCatalogsExtension.class);
|
||||
var grpc =
|
||||
catalogs
|
||||
.named("libs")
|
||||
.findVersion("grpc")
|
||||
.orElseThrow(
|
||||
() ->
|
||||
new GradleException(
|
||||
"Version catalog 'libs' must define version 'grpc' for ca.grpc-platform-module"));
|
||||
String grpcVersion = grpc.getRequiredVersion();
|
||||
DependencyManagementExtension dependencyManagement =
|
||||
project.getExtensions().getByType(DependencyManagementExtension.class);
|
||||
dependencyManagement.imports(imports -> imports.mavenBom("io.grpc:grpc-bom:" + grpcVersion));
|
||||
}
|
||||
}
|
||||
+1
-8
@@ -1,6 +1,5 @@
|
||||
package dev.caskeleton.buildlogic.java;
|
||||
|
||||
import dev.caskeleton.buildlogic.MainBuild;
|
||||
import io.spring.gradle.dependencymanagement.dsl.DependencyManagementExtension;
|
||||
import java.io.File;
|
||||
import java.io.IOException;
|
||||
@@ -304,13 +303,7 @@ public final class JavaConventionsPlugin implements Plugin<Project> {
|
||||
public static final String CONTAINER_IMAGE_PROPERTY_PREFIX = "ca.test.image.";
|
||||
|
||||
private static File containerImageCatalog(Project project) {
|
||||
// The optional platform build's root is a directory inside the main build, which owns the
|
||||
// catalog.
|
||||
File root = project.getRootProject().getProjectDir();
|
||||
File catalog = MainBuild.nearest(root, "config/testing/container-images.properties");
|
||||
if (catalog == null) {
|
||||
catalog = new File(root, "config/testing/container-images.properties");
|
||||
}
|
||||
File catalog = project.getRootProject().file("config/testing/container-images.properties");
|
||||
if (!catalog.isFile()) {
|
||||
throw new GradleException("Missing test container image catalog: " + catalog);
|
||||
}
|
||||
|
||||
+3
-10
@@ -5,7 +5,6 @@ import com.github.spotbugs.snom.Confidence;
|
||||
import com.github.spotbugs.snom.SpotBugsExtension;
|
||||
import com.github.spotbugs.snom.SpotBugsReport;
|
||||
import com.github.spotbugs.snom.SpotBugsTask;
|
||||
import dev.caskeleton.buildlogic.MainBuild;
|
||||
import java.io.File;
|
||||
import java.util.List;
|
||||
import net.ltgt.gradle.errorprone.ErrorProneOptions;
|
||||
@@ -37,14 +36,7 @@ public final class QualityConventionsPlugin implements Plugin<Project> {
|
||||
SourceSet main = javaExtension.getSourceSets().getByName(SourceSet.MAIN_SOURCE_SET_NAME);
|
||||
SourceSet test = javaExtension.getSourceSets().getByName(SourceSet.TEST_SOURCE_SET_NAME);
|
||||
|
||||
// The optional platform build's root is a directory inside the main build, which owns the tool
|
||||
// configuration.
|
||||
File repositoryConfigDirectory =
|
||||
MainBuild.nearest(project.getRootProject().getProjectDir(), "config/checkstyle");
|
||||
repositoryConfigDirectory =
|
||||
repositoryConfigDirectory == null
|
||||
? project.getRootProject().file("config")
|
||||
: repositoryConfigDirectory.getParentFile();
|
||||
File repositoryConfigDirectory = project.getRootProject().file("config");
|
||||
|
||||
SpotlessExtension spotless = project.getExtensions().getByType(SpotlessExtension.class);
|
||||
spotless.java(
|
||||
@@ -91,7 +83,8 @@ public final class QualityConventionsPlugin implements Plugin<Project> {
|
||||
// total 307 46 261
|
||||
//
|
||||
// Found afterwards and judged the same way (review 15절, r3-L): the optional-platforms (gRPC)
|
||||
// build reads this same exclude file and had not been analysed at MEDIUM (13), and the
|
||||
// build, which read this same exclude file until it moved to the grpc-library repository on
|
||||
// 2026-11-08 (its rows below left with it), had not been analysed at MEDIUM (13), and the
|
||||
// httpclient retry jitter source r3-J added (1).
|
||||
// USO_UNSAFE_METHOD_SYNCHRONIZATION 6 6 -
|
||||
// GrpcAdmissionController: private lock object
|
||||
|
||||
-17
@@ -1,17 +0,0 @@
|
||||
package dev.caskeleton.buildlogic.settings;
|
||||
|
||||
import dev.caskeleton.buildlogic.MainBuild;
|
||||
import dev.caskeleton.buildlogic.ModuleRegistrySettingsInstaller;
|
||||
import java.io.File;
|
||||
import org.gradle.api.Plugin;
|
||||
import org.gradle.api.initialization.Settings;
|
||||
|
||||
public final class OptionalArchitectureRegistrySettingsPlugin implements Plugin<Settings> {
|
||||
@Override
|
||||
public void apply(Settings settings) {
|
||||
File mainBuildDirectory = MainBuild.directory(settings.getSettingsDir());
|
||||
File registryFile = new File(mainBuildDirectory, MainBuild.REGISTRY);
|
||||
ModuleRegistrySettingsInstaller.install(
|
||||
settings, registryFile, mainBuildDirectory.getParentFile(), "optional-grpc");
|
||||
}
|
||||
}
|
||||
+2
-1
@@ -18,7 +18,8 @@ public abstract class StrictLaneStagesExtension {
|
||||
* command executes this build's stages only when it starts in this build's directory from there
|
||||
* — its step's {@code working-directory} joined with its {@code -p}. The directory is read from
|
||||
* where the build is, so no build states it (review 2026-11-04 RR2-04-04: a {@code -p} value
|
||||
* alone missed {@code working-directory: src/platforms/optional-build} with {@code ../gradlew}).
|
||||
* alone missed {@code working-directory: src/platforms/optional-build} with {@code ../gradlew}, in
|
||||
* the optional gRPC build that has since moved to its own repository).
|
||||
*/
|
||||
public abstract DirectoryProperty getWorkflowDirectory();
|
||||
|
||||
|
||||
+5
-4
@@ -42,9 +42,10 @@ import org.gradle.api.execution.TaskExecutionGraph;
|
||||
* WorkflowGradleInvocations} and {@code ShellScript} name the shapes).
|
||||
* </ol>
|
||||
*
|
||||
* <p>Each build that holds strict lanes applies it at its own root: the main build, and the
|
||||
* optional-platforms build. A command executes this build when it starts in this build's directory
|
||||
* — its step's {@code working-directory}, moved by the {@code cd} commands the same shell surely
|
||||
* <p>A build that holds strict lanes applies it at its root (here, the main build; until 2026-11-08
|
||||
* the optional gRPC platform build applied it too). A command executes this build when it starts
|
||||
* in this build's directory — its step's {@code working-directory}, moved by the {@code cd}
|
||||
* commands the same shell surely
|
||||
* ran before it, joined with its {@code -p}, from the repository root, which is where GitHub keeps
|
||||
* {@code .github/workflows} ({@code ShellScript} says which {@code cd} it follows).
|
||||
* A stage named only by commands that do not count is reported with each command's reason. Applied
|
||||
@@ -298,7 +299,7 @@ public final class StrictLaneStagesPlugin implements Plugin<Project> {
|
||||
|
||||
/**
|
||||
* This build's directory from the repository root, which holds {@code .github/workflows}: {@code
|
||||
* src} for the main build, {@code src/platforms/optional-build} for the optional one.
|
||||
* src} for the main build.
|
||||
*/
|
||||
private static String buildDirectory(Project root, File workflowDirectory) {
|
||||
File repository = workflowDirectory.getAbsoluteFile().getParentFile().getParentFile();
|
||||
|
||||
@@ -87,7 +87,17 @@ class ModuleRegistryTest {
|
||||
}
|
||||
|
||||
@Test
|
||||
void buildOwnershipDefaultsToMainAndCanSelectOptionalModules() throws Exception {
|
||||
void everyModuleBelongsToTheMainBuild() throws Exception {
|
||||
ModuleRegistry parsed = read(registry(entry("app-bootstrap", ":app-bootstrap", "src/alpha")));
|
||||
assertEquals("main", parsed.byId("app-bootstrap").buildName());
|
||||
assertEquals(List.of("app-bootstrap"), parsed.modulesForBuild("main").stream().map(ModuleRegistry.Module::id).toList());
|
||||
}
|
||||
|
||||
@Test
|
||||
void aBuildFieldIsRejectedBecauseNoOtherBuildIncludesOrChecksTheModule() throws Exception {
|
||||
// The optional gRPC build was the only other build; it moved to its own repository on
|
||||
// 2026-11-08. A row naming any other build (a typo included) would be included by no settings
|
||||
// and checked by no direction gate, while ci stays green.
|
||||
Files.createDirectories(root.resolve("src/grpc/grpc-client"));
|
||||
String json =
|
||||
registry(
|
||||
@@ -96,15 +106,13 @@ class ModuleRegistryTest {
|
||||
{"id":"grpc-client","gradle_path":":grpc:grpc-client","source_path":"src/grpc/grpc-client",
|
||||
"allowed_dependencies":[],"build":"optional-grpc"}
|
||||
""");
|
||||
ModuleRegistry parsed = read(json);
|
||||
assertEquals("main", parsed.byId("app-bootstrap").buildName());
|
||||
assertEquals("optional-grpc", parsed.byId("grpc-client").buildName());
|
||||
assertEquals(List.of("app-bootstrap"), parsed.modulesForBuild("main").stream().map(ModuleRegistry.Module::id).toList());
|
||||
assertEquals(List.of("grpc-client"), parsed.modulesForBuild("optional-grpc").stream().map(ModuleRegistry.Module::id).toList());
|
||||
IllegalStateException failure = assertThrows(IllegalStateException.class, () -> read(json));
|
||||
assertTrue(failure.getMessage().contains("'grpc-client'"), failure.getMessage());
|
||||
assertTrue(failure.getMessage().contains("'build'"), failure.getMessage());
|
||||
}
|
||||
|
||||
@Test
|
||||
void blankBuildOwnershipIsRefused() {
|
||||
void aBlankBuildFieldIsRefusedToo() {
|
||||
String json =
|
||||
"""
|
||||
{"modules":[
|
||||
@@ -112,7 +120,7 @@ class ModuleRegistryTest {
|
||||
"allowed_dependencies":[],"build":" "}]}
|
||||
""";
|
||||
IllegalStateException failure = assertThrows(IllegalStateException.class, () -> read(json));
|
||||
assertTrue(failure.getMessage().contains("nonblank string 'build'"), failure.getMessage());
|
||||
assertTrue(failure.getMessage().contains("'build' field"), failure.getMessage());
|
||||
}
|
||||
|
||||
@Test
|
||||
|
||||
+3
-42
@@ -16,7 +16,7 @@ class PlatformModuleConventionTest {
|
||||
@BeforeEach
|
||||
void setUp() throws Exception {
|
||||
Files.createDirectories(projectDir.resolve("gradle"));
|
||||
writeCatalog(true);
|
||||
writeCatalog();
|
||||
// java-conventions refuses a build without the container image catalog (review 2026-11-01
|
||||
// 08-04); a fixture build that starts no container still has to carry one, even empty.
|
||||
Files.createDirectories(projectDir.resolve("config/testing"));
|
||||
@@ -103,44 +103,6 @@ class PlatformModuleConventionTest {
|
||||
result.getOutput().contains("releaseVersion must be MAJOR.MINOR.PATCH"), result.getOutput());
|
||||
}
|
||||
|
||||
@Test
|
||||
void grpcConventionImportsBom() throws Exception {
|
||||
buildFile(
|
||||
"""
|
||||
plugins { id 'ca.grpc-platform-module' }
|
||||
tasks.register('reportManagedVersion') {
|
||||
String managed = dependencyManagement.managedVersions['io.grpc:grpc-api']
|
||||
doLast { logger.lifecycle('managed-grpc-api=' + managed) }
|
||||
}
|
||||
""");
|
||||
BuildResult result = runner("reportManagedVersion").build();
|
||||
assertTrue(result.getOutput().contains("managed-grpc-api=1.68.1"), result.getOutput());
|
||||
}
|
||||
|
||||
@Test
|
||||
void grpcConventionRefusesMissingVersion() throws Exception {
|
||||
writeCatalog(false);
|
||||
buildFile("plugins { id 'ca.grpc-platform-module' }\n");
|
||||
BuildResult result = runner("tasks").buildAndFail();
|
||||
assertTrue(
|
||||
result.getOutput().contains("Version catalog 'libs' must define version 'grpc'"),
|
||||
result.getOutput());
|
||||
}
|
||||
|
||||
@Test
|
||||
void grpcConventionBringsDependencyManagement() throws Exception {
|
||||
buildFile(
|
||||
"""
|
||||
plugins { id 'ca.grpc-platform-module' }
|
||||
tasks.register('reportDependencyManagement') {
|
||||
boolean present = project.extensions.findByName('dependencyManagement') != null
|
||||
doLast { logger.lifecycle('dependency-management-present=' + present) }
|
||||
}
|
||||
""");
|
||||
BuildResult result = runner("reportDependencyManagement").build();
|
||||
assertTrue(result.getOutput().contains("dependency-management-present=true"), result.getOutput());
|
||||
}
|
||||
|
||||
@Test
|
||||
void pinnedCatalogLibrariesAreManagedAndOthersAreNot() throws Exception {
|
||||
// given: the fixture catalog carries `pinned-fixture` and `unpinned-fixture`. The project-wide
|
||||
@@ -163,7 +125,7 @@ class PlatformModuleConventionTest {
|
||||
assertTrue(result.getOutput().contains("pinned=2.0.1 unpinned=null"), result.getOutput());
|
||||
}
|
||||
|
||||
private void writeCatalog(boolean grpc) throws Exception {
|
||||
private void writeCatalog() throws Exception {
|
||||
Files.writeString(
|
||||
projectDir.resolve("gradle/libs.versions.toml"),
|
||||
"""
|
||||
@@ -174,12 +136,11 @@ class PlatformModuleConventionTest {
|
||||
spotbugs = "4.10.2"
|
||||
findsecbugs = "1.14.0"
|
||||
errorprone = "2.49.0"
|
||||
%s
|
||||
|
||||
[libraries]
|
||||
pinned-fixture = { module = "org.example:pinned-fixture", version = "2.0.1" }
|
||||
unpinned-fixture = { module = "org.example:unpinned-fixture", version = "1.0.0" }
|
||||
""".formatted(grpc ? "grpc = \"1.68.1\"" : ""));
|
||||
""");
|
||||
}
|
||||
|
||||
private void buildFile(String body) throws Exception {
|
||||
|
||||
@@ -568,90 +568,6 @@
|
||||
"messaging-policy",
|
||||
"messaging-transport-spi"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "grpc-contract",
|
||||
"gradle_path": ":grpc:grpc-contract",
|
||||
"source_path": "src/platforms/grpc/grpc-contract",
|
||||
"allowed_dependencies": [],
|
||||
"build": "optional-grpc"
|
||||
},
|
||||
{
|
||||
"id": "grpc-core-api",
|
||||
"gradle_path": ":grpc:grpc-core-api",
|
||||
"source_path": "src/platforms/grpc/grpc-core-api",
|
||||
"allowed_dependencies": [],
|
||||
"build": "optional-grpc"
|
||||
},
|
||||
{
|
||||
"id": "grpc-observability",
|
||||
"gradle_path": ":grpc:grpc-observability",
|
||||
"source_path": "src/platforms/grpc/grpc-observability",
|
||||
"allowed_dependencies": [
|
||||
"grpc-core-api"
|
||||
],
|
||||
"build": "optional-grpc"
|
||||
},
|
||||
{
|
||||
"id": "grpc-operation-ledger-jpa",
|
||||
"gradle_path": ":grpc:grpc-operation-ledger-jpa",
|
||||
"source_path": "src/platforms/grpc/grpc-operation-ledger-jpa",
|
||||
"allowed_dependencies": [
|
||||
"grpc-core-api"
|
||||
],
|
||||
"build": "optional-grpc"
|
||||
},
|
||||
{
|
||||
"id": "grpc-runtime",
|
||||
"gradle_path": ":grpc:grpc-runtime",
|
||||
"source_path": "src/platforms/grpc/grpc-runtime",
|
||||
"allowed_dependencies": [
|
||||
"grpc-core-api"
|
||||
],
|
||||
"build": "optional-grpc"
|
||||
},
|
||||
{
|
||||
"id": "grpc-spring-boot-starter",
|
||||
"gradle_path": ":grpc:grpc-spring-boot-starter",
|
||||
"source_path": "src/platforms/grpc/grpc-spring-boot-starter",
|
||||
"allowed_dependencies": [
|
||||
"grpc-core-api",
|
||||
"grpc-runtime",
|
||||
"grpc-observability"
|
||||
],
|
||||
"build": "optional-grpc"
|
||||
},
|
||||
{
|
||||
"id": "grpc-testkit",
|
||||
"gradle_path": ":grpc:grpc-testkit",
|
||||
"source_path": "src/platforms/grpc/grpc-testkit",
|
||||
"allowed_dependencies": [
|
||||
"grpc-core-api",
|
||||
"grpc-runtime",
|
||||
"grpc-observability",
|
||||
"grpc-operation-ledger-jpa"
|
||||
],
|
||||
"build": "optional-grpc"
|
||||
},
|
||||
{
|
||||
"id": "grpc-advanced",
|
||||
"gradle_path": ":grpc-advanced:grpc-advanced",
|
||||
"source_path": "src/platforms/grpc-advanced/grpc-advanced",
|
||||
"allowed_dependencies": [
|
||||
"grpc-core-api",
|
||||
"grpc-runtime"
|
||||
],
|
||||
"build": "optional-grpc"
|
||||
},
|
||||
{
|
||||
"id": "grpc-advanced-compat",
|
||||
"gradle_path": ":grpc-advanced:grpc-advanced-compat",
|
||||
"source_path": "src/platforms/grpc-advanced/grpc-advanced-compat",
|
||||
"allowed_dependencies": [
|
||||
"grpc-core-api",
|
||||
"grpc-runtime"
|
||||
],
|
||||
"build": "optional-grpc"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -263,14 +263,12 @@
|
||||
</Match>
|
||||
|
||||
<!-- CT group 2 — designed for extension. Exception hierarchy roots (HttpClientException,
|
||||
JpaPersistenceException, RedisOperationException, FileserverException and the optional
|
||||
gRPC build's GrpcPlatformException, which GrpcDeadlineExceededException extends, each have
|
||||
JpaPersistenceException, RedisOperationException and FileserverException each have
|
||||
subclasses), ClientRuntime (BlockingClientRuntime extends it) and the abstract
|
||||
JpaRepositoryFragmentSupport, which service repository fragments extend. -->
|
||||
<Match>
|
||||
<Bug pattern="CT_CONSTRUCTOR_THROW"/>
|
||||
<Or>
|
||||
<Class name="dev.caskeleton.grpc.api.error.GrpcPlatformException"/>
|
||||
<Class name="dev.caskeleton.adapter.outbound.httpclient.api.error.HttpClientException"/>
|
||||
<Class name="dev.caskeleton.adapter.outbound.persistence.api.error.JpaPersistenceException"/>
|
||||
<Class name="dev.caskeleton.adapter.outbound.cache.redis.sdk.api.error.RedisOperationException"/>
|
||||
@@ -284,14 +282,11 @@
|
||||
is "segment (separator segment)*" where the separator is a character the segment class
|
||||
cannot contain ('.', '-', ';', or a class of those), so each input splits exactly one way
|
||||
and backtracking is linear, not exponential. The application-core and messaging values
|
||||
also check the length (at most 64-256 characters) before the pattern runs, and so do the
|
||||
gRPC identifiers (GrpcIdentifiers.requireBounded, 256); JsonPathName and SafeSortField
|
||||
also check the length (at most 64-256 characters) before the pattern runs; JsonPathName and SafeSortField
|
||||
match developer-declared paths; the SNS host comes from a URI host. -->
|
||||
<Match>
|
||||
<Bug pattern="REDOS"/>
|
||||
<Or>
|
||||
<And><Class name="dev.caskeleton.grpc.core.GrpcChannelProfileName"/><Method name="<clinit>"/></And>
|
||||
<And><Class name="dev.caskeleton.grpc.core.GrpcServiceName"/><Method name="<clinit>"/></And>
|
||||
<And><Class name="dev.caskeleton.adapter.outbound.notification.platform.provider.ses.SnsSignatureVerifier"/><Method name="<clinit>"/></And>
|
||||
<And><Class name="dev.caskeleton.adapter.outbound.persistence.postgresql.json.JsonPathName"/><Method name="<clinit>"/></And>
|
||||
<And><Class name="dev.caskeleton.adapter.outbound.persistence.springdata.SafeSortField"/><Method name="<clinit>"/></And>
|
||||
@@ -304,31 +299,13 @@
|
||||
</Or>
|
||||
</Match>
|
||||
|
||||
<!-- FindSecBugs REDOS, the "x([class]*x)?" shape: GrpcMetadataKey.CANONICAL and
|
||||
GrpcResolverSafetyPolicy.AUTHORITY. The only unbounded quantifier sits in a group that
|
||||
repeats at most once, so a failing match gives back one character at a time from a single
|
||||
star — n steps, not 2^n. Measured with java.util.regex on 1k/10k/100k-unit inputs built to
|
||||
fail late ("a.a"... + "!"): time grows tenfold per tenfold input, 300k characters in under
|
||||
7 ms. The metadata key is also capped at 64 characters before the pattern runs; the
|
||||
resolver authority has no cap, and a linear match costs no more than reading the update. -->
|
||||
<Match>
|
||||
<Bug pattern="REDOS"/>
|
||||
<Or>
|
||||
<And><Class name="dev.caskeleton.grpc.api.context.GrpcMetadataKey"/><Method name="<clinit>"/></And>
|
||||
<And><Class name="dev.caskeleton.grpc.advanced.discovery.GrpcResolverSafetyPolicy"/><Method name="<clinit>"/></And>
|
||||
</Or>
|
||||
</Match>
|
||||
|
||||
<!-- FindSecBugs UNSAFE_HASH_EQUALS asks for a constant-time compare so that timing cannot leak a
|
||||
secret digest. None of these digests is a secret: content SHA-256 the uploader supplied or
|
||||
can compute (ContentPublishVerification, MetadataPointerContentPublisher,
|
||||
FinalizeUploadApplicationUseCase), an integrity digest of the record's own policy snapshot
|
||||
(ObjectOperationRecord), idempotency request/response digests the caller's own replay
|
||||
produces (PostgreSqlIdempotencyStore), and a configured worker identity used as a lease
|
||||
owner (PosterImageUploadIntent), and the gRPC channel profile fingerprints that
|
||||
GrpcPlatformSnapshotService.driftAgainstRelease compares between two snapshots it was
|
||||
handed — a configuration hash, published in the snapshot itself, compared offline with no
|
||||
caller to time it. A comparison that leaks what the caller already knows leaks nothing. -->
|
||||
owner (PosterImageUploadIntent). A comparison that leaks what the caller already knows leaks nothing. -->
|
||||
<Match>
|
||||
<Bug pattern="UNSAFE_HASH_EQUALS"/>
|
||||
<Or>
|
||||
@@ -337,21 +314,9 @@
|
||||
<And><Class name="dev.caskeleton.adapter.outbound.objectstorage.control.ObjectOperationRecord"/><Method name="<init>"/></And>
|
||||
<And><Class name="dev.caskeleton.adapter.outbound.persistence.idempotency.postgresql.PostgreSqlIdempotencyStore"/><Method name="~complete|replayVerdict"/></And>
|
||||
<And><Class name="dev.caskeleton.application.fileserver.upload.FinalizeUploadApplicationUseCase"/><Method name="requireClientDigestMatches"/></And>
|
||||
<And><Class name="dev.caskeleton.grpc.admin.GrpcPlatformSnapshotService"/><Method name="~lambda\$driftAgainstRelease\$\d+"/></And>
|
||||
</Or>
|
||||
</Match>
|
||||
|
||||
<!-- COMMAND_INJECTION: GrpcTlsTestMaterial.runKeytool starts the running JDK's own keytool
|
||||
(java.home/bin) through ProcessBuilder with an argument list — no shell, so no argument is
|
||||
parsed as a command. Its callers pass fixed flags, paths of a temporary directory the
|
||||
fixture created, and the hostname a test names for its certificate. It lives in
|
||||
grpc-testkit, which no production leaf depends on. -->
|
||||
<Match>
|
||||
<Bug pattern="COMMAND_INJECTION"/>
|
||||
<Class name="dev.caskeleton.grpc.testkit.netty.GrpcTlsTestMaterial"/>
|
||||
<Method name="runKeytool"/>
|
||||
</Match>
|
||||
|
||||
<!-- SQL_INJECTION_JDBC: transition() and transitionWithNextAttempt() append a fixed WHERE clause
|
||||
to a SET clause that every caller passes as a string literal from this class; every value
|
||||
is a bound parameter. The method names are the lambdas javac generates inside them. -->
|
||||
|
||||
@@ -54,8 +54,9 @@ googleJavaFormat = "1.35.0"
|
||||
# Pinned (see `pinned-*` below). CVE-2026-102554, fixed in 33.7.2. Brought by gRPC (33.2.1), Error
|
||||
# Prone (33.5.0) and the Checkstyle tool (33.6.0).
|
||||
guava = "33.7.2-jre"
|
||||
# io.grpc BOM. Read through `ext.grpcVersion`; adapter:inbound:grpc and the five grpc:* leaves
|
||||
# import it at MODULE scope to keep the strict-locking blast radius off the shared platform.
|
||||
# io.grpc BOM. adapter:inbound:grpc reads it and imports the BOM at MODULE scope to keep the
|
||||
# strict-locking blast radius off the shared platform. The gRPC platform library (grpc-library repo,
|
||||
# Maven group dev.cakit.grpc) pins its own; no catalog entry here until a leaf adopts it.
|
||||
grpc = "1.75.0"
|
||||
jmh = "1.37"
|
||||
jmhPlugin = "0.7.3"
|
||||
@@ -82,10 +83,6 @@ protobuf = "4.33.2"
|
||||
# protobuf-bom import is what resolves, so a lower number here would run gRPC on an older runtime
|
||||
# than it was built against.
|
||||
protobufGrpc = "3.25.8"
|
||||
# The Gradle plugin that runs protoc for grpc:grpc-contract. protoc and the protobuf-java runtime
|
||||
# the generated code links against are both `protobufGrpc` above, so generator and runtime move
|
||||
# together with the gRPC BOM.
|
||||
protobufPlugin = "0.10.0"
|
||||
# The websocket leaf's proto contract is generated against an older runtime and has not been
|
||||
# requalified; see the coordinate's own comment in that leaf.
|
||||
protobufLegacy = "4.29.3"
|
||||
@@ -136,8 +133,6 @@ mockwebserver = { module = "com.squareup.okhttp3:mockwebserver", version.ref = "
|
||||
okhttp-tls = { module = "com.squareup.okhttp3:okhttp-tls", version.ref = "okhttp" }
|
||||
protobuf-java = { module = "com.google.protobuf:protobuf-java", version.ref = "protobuf" }
|
||||
protobuf-java-legacy = { module = "com.google.protobuf:protobuf-java", version.ref = "protobufLegacy" }
|
||||
protobuf-java-grpc = { module = "com.google.protobuf:protobuf-java", version.ref = "protobufGrpc" }
|
||||
protoc = { module = "com.google.protobuf:protoc", version.ref = "protobufGrpc" }
|
||||
resilience4j-bulkhead = { module = "io.github.resilience4j:resilience4j-bulkhead", version.ref = "resilience4j" }
|
||||
resilience4j-circuitbreaker = { module = "io.github.resilience4j:resilience4j-circuitbreaker", version.ref = "resilience4j" }
|
||||
resilience4j-micrometer = { module = "io.github.resilience4j:resilience4j-micrometer", version.ref = "resilience4j" }
|
||||
@@ -176,4 +171,3 @@ spotless = { id = "com.diffplug.spotless", version.ref = "spotless" }
|
||||
spotbugs = { id = "com.github.spotbugs", version.ref = "spotbugsPlugin" }
|
||||
errorprone = { id = "net.ltgt.errorprone", version.ref = "errorpronePlugin" }
|
||||
jmh = { id = "me.champeau.jmh", version.ref = "jmhPlugin" }
|
||||
protobuf = { id = "com.google.protobuf", version.ref = "protobufPlugin" }
|
||||
|
||||
@@ -1,88 +0,0 @@
|
||||
# grpc-advanced — 고급 gRPC capability의 지역 정본
|
||||
|
||||
이 문서는 `grpc-advanced:*` family의 **지역 정본(local authority)**이다. leaf 목록·gradle path·허용 의존성은
|
||||
`src/config/architecture/modules.json`이 SSOT다. 루트 `AGENTS.md`와 충돌하면
|
||||
루트가 이긴다.
|
||||
|
||||
이 family는 Stable gRPC 플랫폼(`grpc:*`)이 **의도적으로 제외한** 능력들을 담는다. 별도 디렉터리와
|
||||
별도 Gradle prefix인 이유는 하나다: "Stable starter가 advanced module을 참조하면 build가 실패한다"는
|
||||
불변 조건을 registry의 `allowed_dependencies`만으로 기계 검증할 수 있게 하기 위해서다.
|
||||
|
||||
## 의존 방향
|
||||
|
||||
```text
|
||||
grpc-advanced:* → grpc:* (허용)
|
||||
grpc:* → grpc-advanced:* (금지 — registry가 거부한다)
|
||||
```
|
||||
|
||||
`grpc-spring-boot-starter`의 registry 엔트리에는 어떤 advanced id도 없다.
|
||||
`verifyCleanArchitectureDependencies`가 build time에 이 규칙을 강제한다. runtime 검사는 없다.
|
||||
|
||||
### 공용 다이제스트 헬퍼를 복사해 두는 이유
|
||||
|
||||
`grpc-advanced`(`GrpcDiagnosticsRedactor`)는 SHA-256 계산을 자기 안에 둔다. 의존 방향이
|
||||
`grpc-advanced:* → grpc:*`로 닫혀 있고 `shared-contract` edge가 없는 것은 의도다. `grpc/AGENTS.md`의
|
||||
같은 절과 이유가 같다(vendored 플랫폼, messaging family와 같은 배치).
|
||||
|
||||
## Capability grade와 feature flag
|
||||
|
||||
capability마다 별도 flag를 갖는다. 하나의 "advanced" 스위치로 묶지 않는 이유는, gRPC-Web을 켜는
|
||||
결정(프록시 하나)과 xDS를 켜는 결정(control plane과 그 장애 모드 전체)이 같은 결정이 아니기
|
||||
때문이다. 하나의 스위치는 두 번째 결정을 실수로 내리게 만든다.
|
||||
|
||||
| grade | 시작 가능 | production 추가 승인 |
|
||||
| --- | --- | --- |
|
||||
| `ADVANCED_STABLE` | O | 불필요 |
|
||||
| `EXPERIMENTAL` | O | **필요** |
|
||||
| `WATCH` | X (추적만) | — |
|
||||
| `DISABLED` | X | — |
|
||||
|
||||
property key는 `app.grpc.advanced.<capability>.enabled`이고 전부 기본 off다.
|
||||
`GrpcAdvancedModuleGuard`가 세 조건(flag 미설정 / grade가 시작 불가 / production 승인 없음)을
|
||||
구분해서 거부하며, 세 경우의 조치가 다르므로 메시지도 다르다.
|
||||
|
||||
## Leaf별 담당 capability
|
||||
|
||||
| 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별로 독립이다
|
||||
|
||||
승격 증거는 capability마다 따로 판단한다. 공유 증거였다면 하나를 승격할 때 같은 시점에 측정된 다른
|
||||
것들이 함께 승격된다. 이 규칙을 코드로 옮겨 두었던 `GrpcAdvancedPromotionGate`는 자기 테스트 말고
|
||||
호출처가 없어 2026-09-25 리뷰 후속 작업에서 삭제했다. 지금은 `docs/runbooks/grpc-advanced-capabilities.md`의
|
||||
리뷰 규칙이다.
|
||||
|
||||
승격 문턱은 두 개다: `ADVANCED_STABLE`은 7일 soak + 전체 증거, Stable default는 30일 soak. 두 번째가
|
||||
더 높은 이유는 모든 배포가 그 의존성과 장애 모드를 갖게 되기 때문이다.
|
||||
|
||||
## 이 저장소에서 검증할 수 없는 것
|
||||
|
||||
capability별로 필요한 실제 인프라가 이 저장소에 없다.
|
||||
|
||||
- `grpc-web` → gRPC-Web 프록시
|
||||
- `servlet-compat` → Servlet 컨테이너
|
||||
- `xds` → 중지 가능한 xDS control plane
|
||||
- `kotlin` → Kotlin 툴체인
|
||||
|
||||
인프라 없이 도는 suite는 통과하면서 아무것도 증명하지 않으므로, suite가 없는 것보다 나쁘다.
|
||||
이 사실을 상수로 반환하던 gate 클래스(`GrpcKotlinCompatibilityGate`, `GrpcAdvancedInfrastructureTestkit`
|
||||
등)는 2026-09-25 삭제됐다 — 지원 여부는 이 문서와 support matrix가 적는다.
|
||||
|
||||
## 금지
|
||||
|
||||
- Stable leaf(`grpc:*`)가 이 family를 참조하는 것.
|
||||
- capability grade 없이, 또는 flag 없이 advanced 코드 경로를 실행하는 것.
|
||||
- `WATCH` capability를 스키마 소스로 사용하는 것.
|
||||
- 실제 인프라 없이 실행한 suite를 promotion evidence로 인용하는 것.
|
||||
@@ -1 +0,0 @@
|
||||
@AGENTS.md
|
||||
@@ -1,24 +0,0 @@
|
||||
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'
|
||||
}
|
||||
|
||||
// Compatibility bridges: gRPC-Web, the Spring Integration bridge, the Reactor adapter, and the
|
||||
// Kotlin coroutine cancellation bridge.
|
||||
//
|
||||
// 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-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
|
||||
// API this module documents.
|
||||
api 'io.projectreactor:reactor-core'
|
||||
api 'org.springframework.integration:spring-integration-core'
|
||||
}
|
||||
@@ -1,98 +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.41.0=spotbugs
|
||||
com.google.errorprone:error_prone_annotations:2.50.0=annotationProcessor,checkstyle,compileClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath
|
||||
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,compileClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath
|
||||
com.google.guava:guava:33.7.2-jre=annotationProcessor,checkstyle,compileClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath
|
||||
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.1=annotationProcessor,checkstyle,compileClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath
|
||||
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
|
||||
commons-logging:commons-logging:1.3.6=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
|
||||
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.75.0=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
|
||||
io.grpc:grpc-stub:1.75.0=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
|
||||
io.micrometer:micrometer-commons:1.16.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
|
||||
io.micrometer:micrometer-observation:1.16.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
|
||||
io.projectreactor:reactor-core:3.8.8=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.codehaus.mojo:animal-sniffer-annotations:1.24=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.6.1=checkstyle
|
||||
org.dom4j:dom4j:2.2.0=spotbugs
|
||||
org.javassist:javassist:3.28.0-GA=checkstyle
|
||||
org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,compileClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath
|
||||
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.reactivestreams:reactive-streams:1.0.4=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
|
||||
org.reflections:reflections:0.10.2=checkstyle
|
||||
org.slf4j:slf4j-api:2.0.20=spotbugs,spotbugsSlf4j
|
||||
org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j
|
||||
org.slf4j:slf4j-simple:2.0.20=checkstyle
|
||||
org.springframework.integration:spring-integration-core:7.0.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
|
||||
org.springframework:spring-aop:7.0.10=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
|
||||
org.springframework:spring-beans:7.0.10=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
|
||||
org.springframework:spring-context:7.0.10=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
|
||||
org.springframework:spring-core:7.0.10=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
|
||||
org.springframework:spring-expression:7.0.10=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
|
||||
org.springframework:spring-messaging:7.0.10=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
|
||||
org.springframework:spring-tx:7.0.10=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
|
||||
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
|
||||
empty=
|
||||
-78
@@ -1,78 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.integration;
|
||||
|
||||
import dev.caskeleton.grpc.api.context.GrpcMetadataKey;
|
||||
import java.util.LinkedHashMap;
|
||||
import java.util.Map;
|
||||
import java.util.Set;
|
||||
|
||||
/**
|
||||
* What a Spring Integration flow may exchange with a gRPC call.
|
||||
*
|
||||
* <p>The header allowlist is the whole policy. A Spring Integration {@code Message} accumulates
|
||||
* headers as it moves through a flow — routing keys, correlation ids, errors channels, whatever a
|
||||
* transformer added — and copying them onto gRPC metadata sends a service's internal plumbing
|
||||
* across the network, where it counts against the metadata budget and occasionally carries
|
||||
* something sensitive.
|
||||
*
|
||||
* <p>The bridge does not add durability. Spring Integration channels can look like a broker, and a
|
||||
* bridge that implied acknowledgement or redelivery semantics would be promising something gRPC
|
||||
* does not do.
|
||||
*/
|
||||
public record GrpcIntegrationBridgePolicy(
|
||||
Set<GrpcMetadataKey> headerAllowlist, Set<String> payloadConverters) {
|
||||
|
||||
/** Copies both sets and refuses a bridge with no converter. */
|
||||
public GrpcIntegrationBridgePolicy {
|
||||
if (headerAllowlist == null || payloadConverters == null) {
|
||||
throw new IllegalArgumentException("a bridge policy states its allowlist and converters");
|
||||
}
|
||||
headerAllowlist = Set.copyOf(headerAllowlist);
|
||||
payloadConverters = Set.copyOf(payloadConverters);
|
||||
if (payloadConverters.isEmpty()) {
|
||||
throw new IllegalArgumentException(
|
||||
"a bridge with no registered converter cannot turn a Message payload into a request; "
|
||||
+ "leaving it to reflection is how an unexpected type reaches the wire");
|
||||
}
|
||||
}
|
||||
|
||||
/** The metadata that survives from a Message's headers. */
|
||||
public Map<GrpcMetadataKey, String> metadataFrom(Map<String, Object> messageHeaders) {
|
||||
if (messageHeaders == null) {
|
||||
throw new IllegalArgumentException("message headers must not be null");
|
||||
}
|
||||
Map<GrpcMetadataKey, String> metadata = new LinkedHashMap<>();
|
||||
headerAllowlist.forEach(
|
||||
key -> {
|
||||
Object value = messageHeaders.get(key.name());
|
||||
if (value != null) {
|
||||
metadata.put(key, String.valueOf(value));
|
||||
}
|
||||
});
|
||||
return Map.copyOf(metadata);
|
||||
}
|
||||
|
||||
/** Whether a payload type has a registered converter. */
|
||||
public boolean converterRegistered(String payloadType) {
|
||||
return payloadConverters.contains(payloadType);
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether the bridge provides broker-style acknowledgement or redelivery.
|
||||
*
|
||||
* <p>Always false. A bridge that implied either would be promising a delivery guarantee gRPC does
|
||||
* not make.
|
||||
*/
|
||||
public boolean providesBrokerSemantics() {
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether the bridge replaces the generated stub and service APIs.
|
||||
*
|
||||
* <p>Always false. It is one way to reach a gRPC call from an existing integration flow, not the
|
||||
* way an application is meant to call one.
|
||||
*/
|
||||
public boolean replacesGeneratedApis() {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
-58
@@ -1,58 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.integration;
|
||||
|
||||
import dev.caskeleton.grpc.api.context.GrpcRequestContext;
|
||||
import java.util.Map;
|
||||
import org.springframework.messaging.Message;
|
||||
import org.springframework.messaging.support.MessageBuilder;
|
||||
|
||||
/**
|
||||
* Turns an inbound gRPC call into a Spring Integration {@code Message}.
|
||||
*
|
||||
* <p>The request context travels as one header holding the immutable context object, rather than as
|
||||
* a scattering of actor, tenant and deadline headers. Flattening it would let a transformer in the
|
||||
* middle of a flow change the tenant of a request that has already been authenticated.
|
||||
*
|
||||
* @param <Q> the request payload type
|
||||
*/
|
||||
public final class GrpcIntegrationInboundGateway<Q> {
|
||||
|
||||
/** The header the immutable request context travels under. */
|
||||
public static final String CONTEXT_HEADER = "grpcRequestContext";
|
||||
|
||||
private final GrpcIntegrationBridgePolicy policy;
|
||||
|
||||
/** Binds a gateway to its bridge policy. */
|
||||
public GrpcIntegrationInboundGateway(GrpcIntegrationBridgePolicy policy) {
|
||||
if (policy == null) {
|
||||
throw new IllegalArgumentException("an inbound gateway needs a bridge policy");
|
||||
}
|
||||
this.policy = policy;
|
||||
}
|
||||
|
||||
/**
|
||||
* Builds the Message a flow receives.
|
||||
*
|
||||
* @throws IllegalArgumentException when the payload type has no registered converter
|
||||
*/
|
||||
public Message<Q> toMessage(Q payload, GrpcRequestContext context) {
|
||||
if (payload == null || context == null) {
|
||||
throw new IllegalArgumentException("an inbound message needs a payload and a context");
|
||||
}
|
||||
String payloadType = payload.getClass().getName();
|
||||
if (!policy.converterRegistered(payloadType)) {
|
||||
throw new IllegalArgumentException(
|
||||
"no converter is registered for '"
|
||||
+ payloadType
|
||||
+ "'; converting by reflection is how an unexpected type reaches a flow");
|
||||
}
|
||||
Map<String, Object> headers = new java.util.LinkedHashMap<>();
|
||||
headers.put(CONTEXT_HEADER, context);
|
||||
context.metadata().forEach((key, value) -> headers.put(key.name(), value));
|
||||
return MessageBuilder.withPayload(payload).copyHeaders(headers).build();
|
||||
}
|
||||
|
||||
/** The policy in force. */
|
||||
public GrpcIntegrationBridgePolicy policy() {
|
||||
return policy;
|
||||
}
|
||||
}
|
||||
-57
@@ -1,57 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.integration;
|
||||
|
||||
import dev.caskeleton.grpc.api.context.GrpcMetadataKey;
|
||||
import java.util.Map;
|
||||
import org.springframework.messaging.Message;
|
||||
|
||||
/**
|
||||
* Turns an outbound Spring Integration {@code Message} into a gRPC call's inputs.
|
||||
*
|
||||
* <p>Applies the header allowlist rather than copying what the flow accumulated. A flow's headers
|
||||
* are its own bookkeeping; putting them on the wire spends the metadata budget on another service's
|
||||
* plumbing and occasionally sends something that should not leave the process.
|
||||
*
|
||||
* @param <C> the request payload type
|
||||
*/
|
||||
public final class GrpcIntegrationOutboundGateway<C> {
|
||||
|
||||
private final GrpcIntegrationBridgePolicy policy;
|
||||
|
||||
/** Binds a gateway to its bridge policy. */
|
||||
public GrpcIntegrationOutboundGateway(GrpcIntegrationBridgePolicy policy) {
|
||||
if (policy == null) {
|
||||
throw new IllegalArgumentException("an outbound gateway needs a bridge policy");
|
||||
}
|
||||
this.policy = policy;
|
||||
}
|
||||
|
||||
/** The metadata this message contributes to the call. */
|
||||
public Map<GrpcMetadataKey, String> metadataFrom(Message<C> message) {
|
||||
if (message == null) {
|
||||
throw new IllegalArgumentException("an outbound message is required");
|
||||
}
|
||||
return policy.metadataFrom(message.getHeaders());
|
||||
}
|
||||
|
||||
/**
|
||||
* The payload to send.
|
||||
*
|
||||
* @throws IllegalArgumentException when the payload type has no registered converter
|
||||
*/
|
||||
public C payloadFrom(Message<C> message) {
|
||||
if (message == null) {
|
||||
throw new IllegalArgumentException("an outbound message is required");
|
||||
}
|
||||
C payload = message.getPayload();
|
||||
String payloadType = payload.getClass().getName();
|
||||
if (!policy.converterRegistered(payloadType)) {
|
||||
throw new IllegalArgumentException("no converter is registered for '" + payloadType + "'");
|
||||
}
|
||||
return payload;
|
||||
}
|
||||
|
||||
/** The policy in force. */
|
||||
public GrpcIntegrationBridgePolicy policy() {
|
||||
return policy;
|
||||
}
|
||||
}
|
||||
-60
@@ -1,60 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.kotlin;
|
||||
|
||||
import dev.caskeleton.grpc.deadline.GrpcCancellationCoordinator;
|
||||
import dev.caskeleton.grpc.deadline.GrpcCancellationReason;
|
||||
import java.time.Instant;
|
||||
import java.util.function.Supplier;
|
||||
|
||||
/**
|
||||
* The contract a Kotlin coroutine adapter has to satisfy, expressed as Java callbacks.
|
||||
*
|
||||
* <p>Callbacks rather than coroutine types, so the rule is checkable without a Kotlin toolchain. A
|
||||
* Kotlin adapter wires its {@code Job} completion handler to {@link #onCoroutineCancelled} and its
|
||||
* cancellation source to {@link #cancelCoroutineScope}; what the platform needs is that both
|
||||
* directions exist, and that is what this makes assertable.
|
||||
*/
|
||||
public final class GrpcCoroutineContextBridge {
|
||||
|
||||
private GrpcCoroutineContextBridge() {}
|
||||
|
||||
/**
|
||||
* What a Kotlin adapter calls when its coroutine scope is cancelled.
|
||||
*
|
||||
* <p>Coroutine cancellation is cooperative and structured: cancelling a scope cancels its
|
||||
* children, and a gRPC call started inside it is not one of them unless something says so.
|
||||
*/
|
||||
public static Runnable onCoroutineCancelled(
|
||||
GrpcCancellationCoordinator coordinator, Supplier<Instant> now) {
|
||||
if (coordinator == null || now == null) {
|
||||
throw new IllegalArgumentException("the bridge needs a coordinator and a clock");
|
||||
}
|
||||
return () -> coordinator.cancel(GrpcCancellationReason.CLIENT_CANCELLED, now.get());
|
||||
}
|
||||
|
||||
/**
|
||||
* Registers the coroutine scope so a platform cancellation reaches it.
|
||||
*
|
||||
* @param cancelScope what the Kotlin side does to cancel its scope
|
||||
*/
|
||||
public static void cancelCoroutineScope(
|
||||
GrpcCancellationCoordinator coordinator, Runnable cancelScope, String operationName) {
|
||||
if (coordinator == null || cancelScope == null) {
|
||||
throw new IllegalArgumentException("the bridge needs a coordinator and a cancel action");
|
||||
}
|
||||
if (operationName == null || operationName.isBlank()) {
|
||||
throw new IllegalArgumentException("a cancellable operation needs a name");
|
||||
}
|
||||
coordinator.register(
|
||||
new dev.caskeleton.grpc.deadline.GrpcCancellableOperation() {
|
||||
@Override
|
||||
public String name() {
|
||||
return operationName;
|
||||
}
|
||||
|
||||
@Override
|
||||
public void cancel(GrpcCancellationReason reason) {
|
||||
cancelScope.run();
|
||||
}
|
||||
});
|
||||
}
|
||||
}
|
||||
-61
@@ -1,61 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.reactor;
|
||||
|
||||
import dev.caskeleton.grpc.deadline.GrpcCancellationCoordinator;
|
||||
import dev.caskeleton.grpc.deadline.GrpcCancellationReason;
|
||||
import java.time.Instant;
|
||||
import java.util.function.Supplier;
|
||||
import reactor.core.Disposable;
|
||||
|
||||
/**
|
||||
* Turns a Reactor subscription's cancellation into the platform's.
|
||||
*
|
||||
* <p>Both directions, and both are needed. A client that disposes its {@code Mono} has stopped
|
||||
* caring, and without this bridge the server keeps computing an answer nobody will read; a call the
|
||||
* platform cancelled — deadline, drain, revoked credential — has to stop the reactive pipeline, or
|
||||
* the work continues after the response has been closed.
|
||||
*/
|
||||
public final class GrpcReactorCancellationBridge {
|
||||
|
||||
private GrpcReactorCancellationBridge() {}
|
||||
|
||||
/**
|
||||
* A callback for {@code doOnCancel} that cancels the platform call.
|
||||
*
|
||||
* @param now supplies the moment, so a test does not depend on the wall clock
|
||||
*/
|
||||
public static Runnable onReactorCancel(
|
||||
GrpcCancellationCoordinator coordinator, Supplier<Instant> now) {
|
||||
if (coordinator == null || now == null) {
|
||||
throw new IllegalArgumentException("a cancellation bridge needs a coordinator and a clock");
|
||||
}
|
||||
return () -> coordinator.cancel(GrpcCancellationReason.CLIENT_CANCELLED, now.get());
|
||||
}
|
||||
|
||||
/**
|
||||
* Disposes the reactive pipeline when the platform cancels.
|
||||
*
|
||||
* <p>Registered as a cancellable operation, so it is reached by the same cancellation that stops
|
||||
* the database query and the stream writer rather than by a second mechanism.
|
||||
*/
|
||||
public static void bindPlatformCancellation(
|
||||
GrpcCancellationCoordinator coordinator, Disposable subscription, String operationName) {
|
||||
if (coordinator == null || subscription == null) {
|
||||
throw new IllegalArgumentException("binding needs a coordinator and a subscription");
|
||||
}
|
||||
if (operationName == null || operationName.isBlank()) {
|
||||
throw new IllegalArgumentException("a cancellable operation needs a name");
|
||||
}
|
||||
coordinator.register(
|
||||
new dev.caskeleton.grpc.deadline.GrpcCancellableOperation() {
|
||||
@Override
|
||||
public String name() {
|
||||
return operationName;
|
||||
}
|
||||
|
||||
@Override
|
||||
public void cancel(GrpcCancellationReason reason) {
|
||||
subscription.dispose();
|
||||
}
|
||||
});
|
||||
}
|
||||
}
|
||||
-58
@@ -1,58 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.reactor;
|
||||
|
||||
import dev.caskeleton.grpc.context.GrpcContextSnapshot;
|
||||
import java.util.Optional;
|
||||
import reactor.util.context.Context;
|
||||
import reactor.util.context.ContextView;
|
||||
|
||||
/**
|
||||
* Carries the call context between gRPC's {@code Context} and Reactor's.
|
||||
*
|
||||
* <p>Explicitly, because neither propagates into the other. gRPC's context is a thread-local
|
||||
* mechanism and Reactor's travels with the subscription, so an operator that hops threads leaves
|
||||
* the gRPC context behind and a gRPC interceptor cannot see the Reactor one. Work downstream of
|
||||
* that boundary then runs with no actor, no tenant and no deadline, which is the failure that
|
||||
* produces a change attributed to nobody.
|
||||
*/
|
||||
public final class GrpcReactorContextBridge {
|
||||
|
||||
private static final String CONTEXT_KEY = "dev.caskeleton.grpc.contextSnapshot";
|
||||
|
||||
private GrpcReactorContextBridge() {}
|
||||
|
||||
/** Puts the snapshot into a Reactor context. */
|
||||
public static Context write(Context context, GrpcContextSnapshot snapshot) {
|
||||
if (context == null || snapshot == null) {
|
||||
throw new IllegalArgumentException("bridging needs a Reactor context and a snapshot");
|
||||
}
|
||||
return context.put(CONTEXT_KEY, snapshot);
|
||||
}
|
||||
|
||||
/** Reads the snapshot out of a Reactor context, if it is there. */
|
||||
public static Optional<GrpcContextSnapshot> read(ContextView context) {
|
||||
if (context == null) {
|
||||
throw new IllegalArgumentException("a Reactor context view is required");
|
||||
}
|
||||
return context.hasKey(CONTEXT_KEY) ? Optional.of(context.get(CONTEXT_KEY)) : Optional.empty();
|
||||
}
|
||||
|
||||
/**
|
||||
* Reads the snapshot, failing when it is absent.
|
||||
*
|
||||
* @throws IllegalStateException because reactive work with no call context has no actor, no
|
||||
* tenant and no deadline
|
||||
*/
|
||||
public static GrpcContextSnapshot require(ContextView context) {
|
||||
return read(context)
|
||||
.orElseThrow(
|
||||
() ->
|
||||
new IllegalStateException(
|
||||
"no gRPC call context is in the Reactor context; reactive work that runs "
|
||||
+ "without one produces a change attributed to nobody"));
|
||||
}
|
||||
|
||||
/** The key the snapshot travels under, for a test or a diagnostic to look at. */
|
||||
public static String contextKey() {
|
||||
return CONTEXT_KEY;
|
||||
}
|
||||
}
|
||||
-57
@@ -1,57 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.reactor;
|
||||
|
||||
import dev.caskeleton.grpc.context.GrpcContextSnapshot;
|
||||
import java.util.List;
|
||||
import java.util.function.Supplier;
|
||||
import reactor.core.publisher.Flux;
|
||||
import reactor.core.publisher.Mono;
|
||||
|
||||
/**
|
||||
* Exposes a unary call as a {@code Mono} and a server stream as a {@code Flux}.
|
||||
*
|
||||
* <p>Only here. The Stable contract types stay free of Reactor, so a deployment that does not use
|
||||
* it does not carry it, and the reactive shape is a view over the platform rather than the
|
||||
* platform's own vocabulary.
|
||||
*
|
||||
* <p>The {@code Flux} respects the Stable bounded flow control rather than replacing it. Reactor's
|
||||
* backpressure and gRPC's are two mechanisms over one connection; letting a subscriber's {@code
|
||||
* request(n)} drive the writer directly would bypass the bounded queue that decides what happens
|
||||
* when a consumer falls behind.
|
||||
*/
|
||||
public final class ReactiveGrpcClient {
|
||||
|
||||
private ReactiveGrpcClient() {}
|
||||
|
||||
/**
|
||||
* A unary call as a {@code Mono}, with the call context carried in the Reactor context.
|
||||
*
|
||||
* @param call the blocking invocation, run on {@code boundedElasticScheduler} rather than on the
|
||||
* calling thread. A blocking call on an event loop stalls every other call sharing it, and
|
||||
* the mistake is invisible until load arrives.
|
||||
*/
|
||||
public static <R> Mono<R> unary(
|
||||
Supplier<R> call, GrpcContextSnapshot snapshot, reactor.core.scheduler.Scheduler blocking) {
|
||||
if (call == null || snapshot == null || blocking == null) {
|
||||
throw new IllegalArgumentException(
|
||||
"a reactive unary call needs an invocation, a context and a scheduler");
|
||||
}
|
||||
return Mono.fromSupplier(call)
|
||||
.subscribeOn(blocking)
|
||||
.contextWrite(context -> GrpcReactorContextBridge.write(context, snapshot));
|
||||
}
|
||||
|
||||
/**
|
||||
* A server stream as a {@code Flux}.
|
||||
*
|
||||
* @param messages the already-bounded message source. Taking a list rather than a producer is
|
||||
* deliberate: the bound belongs to the Stable stream writer, and a producer here would be a
|
||||
* second place to get it wrong.
|
||||
*/
|
||||
public static <R> Flux<R> serverStream(List<R> messages, GrpcContextSnapshot snapshot) {
|
||||
if (messages == null || snapshot == null) {
|
||||
throw new IllegalArgumentException("a reactive stream needs its messages and a context");
|
||||
}
|
||||
return Flux.fromIterable(messages)
|
||||
.contextWrite(context -> GrpcReactorContextBridge.write(context, snapshot));
|
||||
}
|
||||
}
|
||||
-57
@@ -1,57 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.reactor;
|
||||
|
||||
import dev.caskeleton.grpc.api.context.GrpcRequestContext;
|
||||
import dev.caskeleton.grpc.context.GrpcContextSnapshot;
|
||||
import java.util.function.BiFunction;
|
||||
import reactor.core.publisher.Mono;
|
||||
import reactor.core.scheduler.Scheduler;
|
||||
|
||||
/**
|
||||
* Runs a reactive use case behind a gRPC service adapter.
|
||||
*
|
||||
* <p>The blocking scheduler is a required argument rather than a default. A reactive pipeline that
|
||||
* touches JPA or a blocking SDK and does not say where that happens runs it on the event loop, and
|
||||
* the symptom — every call on the connection slowing together — appears only under load and points
|
||||
* at the wrong component.
|
||||
*
|
||||
* @param <C> the application command type
|
||||
* @param <R> the application result type
|
||||
*/
|
||||
public final class ReactiveGrpcServerAdapter<C, R> {
|
||||
|
||||
private final BiFunction<C, GrpcRequestContext, Mono<R>> useCase;
|
||||
private final Scheduler blockingScheduler;
|
||||
|
||||
/** Binds an adapter to its use case and the scheduler blocking work runs on. */
|
||||
public ReactiveGrpcServerAdapter(
|
||||
BiFunction<C, GrpcRequestContext, Mono<R>> useCase, Scheduler blockingScheduler) {
|
||||
if (useCase == null || blockingScheduler == null) {
|
||||
throw new IllegalArgumentException(
|
||||
"a reactive adapter needs a use case and the scheduler its blocking work runs on");
|
||||
}
|
||||
this.useCase = useCase;
|
||||
this.blockingScheduler = blockingScheduler;
|
||||
}
|
||||
|
||||
/**
|
||||
* Invokes the use case with the context in both the Reactor context and the argument.
|
||||
*
|
||||
* <p>Both, because they are read by different code: application operators read the Reactor
|
||||
* context, and the use case signature reads the argument. Supplying only one leaves the other
|
||||
* empty at a boundary nobody expects.
|
||||
*/
|
||||
public Mono<R> invoke(C command, GrpcRequestContext context, GrpcContextSnapshot snapshot) {
|
||||
if (command == null || context == null || snapshot == null) {
|
||||
throw new IllegalArgumentException(
|
||||
"an invocation needs a command, a request context and the snapshot to carry");
|
||||
}
|
||||
return Mono.defer(() -> useCase.apply(command, context))
|
||||
.subscribeOn(blockingScheduler)
|
||||
.contextWrite(reactorContext -> GrpcReactorContextBridge.write(reactorContext, snapshot));
|
||||
}
|
||||
|
||||
/** The scheduler blocking work runs on. */
|
||||
public Scheduler blockingScheduler() {
|
||||
return blockingScheduler;
|
||||
}
|
||||
}
|
||||
-62
@@ -1,62 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.web;
|
||||
|
||||
import java.util.Set;
|
||||
|
||||
/**
|
||||
* How a browser reaches the platform, and under what browser-specific rules.
|
||||
*
|
||||
* <p>Cookie credentials and bearer credentials are separated because their attack surfaces differ.
|
||||
* A cookie is attached by the browser to every request to the origin, which makes CSRF a real
|
||||
* concern and a CSRF defence mandatory; a bearer token the application attaches explicitly is not
|
||||
* sent automatically, and requiring a CSRF token there is ceremony. A profile that treats them the
|
||||
* same either leaves the first exposed or burdens the second.
|
||||
*/
|
||||
public record GrpcWebProfile(
|
||||
CredentialStyle credentialStyle,
|
||||
Set<String> allowedOrigins,
|
||||
boolean csrfProtection,
|
||||
boolean tlsTerminatedAtProxy) {
|
||||
|
||||
/** How the browser presents its credential. */
|
||||
public enum CredentialStyle {
|
||||
/** No credential. */
|
||||
NONE,
|
||||
/** A cookie the browser attaches automatically. Needs a CSRF defence. */
|
||||
COOKIE,
|
||||
/** A bearer token the application attaches explicitly. */
|
||||
BEARER
|
||||
}
|
||||
|
||||
/** Refuses a profile a browser could be tricked into using. */
|
||||
public GrpcWebProfile {
|
||||
if (credentialStyle == null) {
|
||||
throw new IllegalArgumentException("a gRPC-Web profile names its credential style");
|
||||
}
|
||||
if (allowedOrigins == null) {
|
||||
throw new IllegalArgumentException("a gRPC-Web profile states its origin allowlist");
|
||||
}
|
||||
allowedOrigins = Set.copyOf(allowedOrigins);
|
||||
if (allowedOrigins.contains("*")) {
|
||||
throw new IllegalArgumentException(
|
||||
"a wildcard origin lets any site call this API with the browser's ambient credentials");
|
||||
}
|
||||
if (credentialStyle != CredentialStyle.NONE && allowedOrigins.isEmpty()) {
|
||||
throw new IllegalArgumentException(
|
||||
"a credentialed gRPC-Web profile needs an origin allowlist");
|
||||
}
|
||||
if (credentialStyle == CredentialStyle.COOKIE && !csrfProtection) {
|
||||
throw new IllegalArgumentException(
|
||||
"cookie credentials are attached by the browser to every request to this origin, so a "
|
||||
+ "CSRF defence is not optional");
|
||||
}
|
||||
if (!tlsTerminatedAtProxy && credentialStyle != CredentialStyle.NONE) {
|
||||
throw new IllegalArgumentException(
|
||||
"a credentialed browser call needs TLS terminated at the proxy");
|
||||
}
|
||||
}
|
||||
|
||||
/** A bearer-token profile for a single origin. */
|
||||
public static GrpcWebProfile bearer(String origin) {
|
||||
return new GrpcWebProfile(CredentialStyle.BEARER, Set.of(origin), false, true);
|
||||
}
|
||||
}
|
||||
-64
@@ -1,64 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.web;
|
||||
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.Set;
|
||||
|
||||
/**
|
||||
* What a gRPC-Web proxy must be configured to do.
|
||||
*
|
||||
* <p>The exposed-trailer rule is the one that costs the most time when it is missing. A gRPC status
|
||||
* arrives as a trailer, a browser cannot read a trailer the proxy did not expose, and the symptom
|
||||
* is a call that appears to succeed at the network level and produces no status at all — which
|
||||
* looks like an application bug and is a proxy configuration.
|
||||
*/
|
||||
public final class GrpcWebProxyContract {
|
||||
|
||||
/** The trailers a browser client has to be able to read. */
|
||||
private static final Set<String> REQUIRED_EXPOSED_HEADERS = Set.of("grpc-status", "grpc-message");
|
||||
|
||||
private GrpcWebProxyContract() {}
|
||||
|
||||
/** The headers a proxy must expose. */
|
||||
public static Set<String> requiredExposedHeaders() {
|
||||
return REQUIRED_EXPOSED_HEADERS;
|
||||
}
|
||||
|
||||
/**
|
||||
* Every problem with a proxy configuration.
|
||||
*
|
||||
* @param exposedHeaders the CORS {@code expose_headers} the proxy is configured with
|
||||
* @param allowedOrigins the CORS origin allowlist the proxy is configured with
|
||||
* @return an empty list when the proxy would work for a browser client
|
||||
*/
|
||||
public static List<String> violations(
|
||||
GrpcWebProfile profile, Set<String> exposedHeaders, Set<String> allowedOrigins) {
|
||||
if (profile == null || exposedHeaders == null || allowedOrigins == null) {
|
||||
throw new IllegalArgumentException("a proxy check needs the profile and both CORS sets");
|
||||
}
|
||||
List<String> violations = new ArrayList<>();
|
||||
|
||||
REQUIRED_EXPOSED_HEADERS.stream()
|
||||
.sorted()
|
||||
.filter(header -> !exposedHeaders.contains(header))
|
||||
.forEach(
|
||||
header ->
|
||||
violations.add(
|
||||
"the proxy does not expose '"
|
||||
+ header
|
||||
+ "'; a browser cannot read a trailer it was not given, so the call "
|
||||
+ "produces no status at all"));
|
||||
|
||||
if (allowedOrigins.contains("*")) {
|
||||
violations.add("the proxy allows any origin, which defeats the profile's allowlist");
|
||||
}
|
||||
profile.allowedOrigins().stream()
|
||||
.sorted()
|
||||
.filter(origin -> !allowedOrigins.contains(origin))
|
||||
.forEach(
|
||||
origin ->
|
||||
violations.add(
|
||||
"origin '" + origin + "' is in the profile but not in the proxy's allowlist"));
|
||||
return List.copyOf(violations);
|
||||
}
|
||||
}
|
||||
-38
@@ -1,38 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.web;
|
||||
|
||||
import dev.caskeleton.grpc.core.RpcType;
|
||||
|
||||
/**
|
||||
* Which RPC shapes gRPC-Web can actually carry.
|
||||
*
|
||||
* <p>Two, and the limit is the protocol's rather than this platform's: gRPC-Web has no way for a
|
||||
* browser to send a stream of messages, so client and bidirectional streaming are not slow or
|
||||
* partial there — they do not exist. Declaring support for them produces a schema a browser client
|
||||
* cannot use and a discovery that happens in the browser.
|
||||
*/
|
||||
public final class GrpcWebRpcSupport {
|
||||
|
||||
private GrpcWebRpcSupport() {}
|
||||
|
||||
/** Whether {@code rpcType} can travel over gRPC-Web. */
|
||||
public static boolean supported(RpcType rpcType) {
|
||||
if (rpcType == null) {
|
||||
throw new IllegalArgumentException("an RPC type is required");
|
||||
}
|
||||
return rpcType == RpcType.UNARY || rpcType == RpcType.SERVER_STREAMING;
|
||||
}
|
||||
|
||||
/**
|
||||
* Fails when a method shape cannot be served over gRPC-Web.
|
||||
*
|
||||
* @throws IllegalArgumentException naming what the browser cannot do
|
||||
*/
|
||||
public static void require(RpcType rpcType) {
|
||||
if (!supported(rpcType)) {
|
||||
throw new IllegalArgumentException(
|
||||
rpcType
|
||||
+ " cannot travel over gRPC-Web: a browser has no way to send a stream of messages, "
|
||||
+ "so declaring support for it produces a schema no browser client can use");
|
||||
}
|
||||
}
|
||||
}
|
||||
-47
@@ -1,47 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.compat;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||
|
||||
import dev.caskeleton.grpc.advanced.kotlin.GrpcCoroutineContextBridge;
|
||||
import dev.caskeleton.grpc.api.deadline.GrpcCancellationToken;
|
||||
import dev.caskeleton.grpc.deadline.GrpcCancellationCoordinator;
|
||||
import dev.caskeleton.grpc.deadline.GrpcCancellationReason;
|
||||
import java.time.Instant;
|
||||
import java.util.concurrent.atomic.AtomicBoolean;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class GrpcCoroutineContextBridgeTest {
|
||||
|
||||
private static final Instant NOW = Instant.parse("2026-08-30T10:00:00Z");
|
||||
|
||||
@Test
|
||||
@DisplayName("coroutine cancellation reaches the platform, and the platform reaches the scope")
|
||||
void cancellationCrossesBothWays() {
|
||||
GrpcCancellationCoordinator inbound =
|
||||
new GrpcCancellationCoordinator(new GrpcCancellationToken());
|
||||
GrpcCoroutineContextBridge.onCoroutineCancelled(inbound, () -> NOW).run();
|
||||
assertThat(inbound.cancelled()).isTrue();
|
||||
|
||||
GrpcCancellationCoordinator outbound =
|
||||
new GrpcCancellationCoordinator(new GrpcCancellationToken());
|
||||
AtomicBoolean scopeCancelled = new AtomicBoolean();
|
||||
GrpcCoroutineContextBridge.cancelCoroutineScope(
|
||||
outbound, () -> scopeCancelled.set(true), "document-flow");
|
||||
outbound.cancel(GrpcCancellationReason.SERVER_DRAIN, NOW);
|
||||
|
||||
assertThat(scopeCancelled).isTrue();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("binding a coroutine scope without a name is refused")
|
||||
void bindingNeedsAnOperationName() {
|
||||
GrpcCancellationCoordinator coordinator =
|
||||
new GrpcCancellationCoordinator(new GrpcCancellationToken());
|
||||
|
||||
assertThatThrownBy(
|
||||
() -> GrpcCoroutineContextBridge.cancelCoroutineScope(coordinator, () -> {}, " "))
|
||||
.isInstanceOf(IllegalArgumentException.class);
|
||||
}
|
||||
}
|
||||
-112
@@ -1,112 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.compat;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||
|
||||
import dev.caskeleton.grpc.advanced.integration.GrpcIntegrationBridgePolicy;
|
||||
import dev.caskeleton.grpc.advanced.integration.GrpcIntegrationInboundGateway;
|
||||
import dev.caskeleton.grpc.advanced.integration.GrpcIntegrationOutboundGateway;
|
||||
import dev.caskeleton.grpc.api.context.GrpcClientIdentity;
|
||||
import dev.caskeleton.grpc.api.context.GrpcMetadataBudget;
|
||||
import dev.caskeleton.grpc.api.context.GrpcMetadataKey;
|
||||
import dev.caskeleton.grpc.api.context.GrpcRequestContext;
|
||||
import dev.caskeleton.grpc.api.deadline.GrpcCancellationToken;
|
||||
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineBudget;
|
||||
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineProfile;
|
||||
import dev.caskeleton.grpc.core.GrpcMethodName;
|
||||
import dev.caskeleton.grpc.core.RpcType;
|
||||
import java.time.Duration;
|
||||
import java.util.Map;
|
||||
import java.util.Set;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
import org.springframework.messaging.Message;
|
||||
import org.springframework.messaging.support.MessageBuilder;
|
||||
|
||||
class GrpcIntegrationBridgePolicyTest {
|
||||
|
||||
private static final GrpcMetadataKey CORRELATION = GrpcMetadataKey.ascii("x-correlation-id");
|
||||
private static final GrpcMethodName GET =
|
||||
GrpcMethodName.parse("caskeleton.document.v1.DocumentService/GetDocument");
|
||||
|
||||
private static GrpcRequestContext requestContext() {
|
||||
return GrpcRequestContext.create(
|
||||
GET,
|
||||
RpcType.UNARY,
|
||||
GrpcClientIdentity.fromVerifiedAuthentication("actor-1", "tenant-1", "jwt-issuer"),
|
||||
GrpcDeadlineBudget.forEntryPoint(
|
||||
Duration.ofSeconds(1), GrpcDeadlineProfile.of(Duration.ofSeconds(2))),
|
||||
new GrpcCancellationToken(),
|
||||
Map.of(CORRELATION, "corr-1"),
|
||||
Set.of(CORRELATION),
|
||||
GrpcMetadataBudget.standard(),
|
||||
null);
|
||||
}
|
||||
|
||||
private static GrpcIntegrationBridgePolicy policy() {
|
||||
return new GrpcIntegrationBridgePolicy(Set.of(CORRELATION), Set.of(String.class.getName()));
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("the bridge copies only allowlisted headers onto metadata")
|
||||
void theBridgeCopiesOnlyAllowlistedHeaders() {
|
||||
GrpcIntegrationOutboundGateway<String> outbound =
|
||||
new GrpcIntegrationOutboundGateway<>(policy());
|
||||
Message<String> message =
|
||||
MessageBuilder.withPayload("payload")
|
||||
.setHeader(CORRELATION.name(), "corr-1")
|
||||
.setHeader("errorChannel", "internal-errors")
|
||||
.setHeader("replyChannel", "internal-replies")
|
||||
.build();
|
||||
|
||||
assertThat(outbound.metadataFrom(message)).containsOnlyKeys(CORRELATION);
|
||||
assertThat(outbound.payloadFrom(message)).isEqualTo("payload");
|
||||
assertThat(outbound.policy()).isNotNull();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("an unregistered payload type is refused rather than converted by reflection")
|
||||
void anUnregisteredPayloadIsRefused() {
|
||||
GrpcIntegrationBridgePolicy otherType =
|
||||
new GrpcIntegrationBridgePolicy(Set.of(CORRELATION), Set.of("some.other.Type"));
|
||||
GrpcIntegrationInboundGateway<String> inbound = new GrpcIntegrationInboundGateway<>(otherType);
|
||||
|
||||
assertThatThrownBy(() -> inbound.toMessage("payload", requestContext()))
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("converting by reflection");
|
||||
Message<String> message = MessageBuilder.withPayload("payload").build();
|
||||
GrpcIntegrationOutboundGateway<String> outbound =
|
||||
new GrpcIntegrationOutboundGateway<>(otherType);
|
||||
assertThatThrownBy(() -> outbound.payloadFrom(message))
|
||||
.isInstanceOf(IllegalArgumentException.class);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a bridge with no registered converter is refused at construction")
|
||||
void aBridgeWithNoConverterIsRefused() {
|
||||
assertThatThrownBy(() -> new GrpcIntegrationBridgePolicy(Set.of(), Set.of()))
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("leaving it to reflection");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("the request context travels as one immutable header, not as scattered fields")
|
||||
void theContextTravelsAsOneHeader() {
|
||||
GrpcIntegrationInboundGateway<String> inbound = new GrpcIntegrationInboundGateway<>(policy());
|
||||
|
||||
Message<String> message = inbound.toMessage("payload", requestContext());
|
||||
|
||||
assertThat(message.getHeaders())
|
||||
.containsKey(GrpcIntegrationInboundGateway.CONTEXT_HEADER)
|
||||
.containsKey(CORRELATION.name())
|
||||
.doesNotContainKey("tenantId")
|
||||
.doesNotContainKey("actorId");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("the bridge adds no broker semantics and replaces no generated API")
|
||||
void theBridgeClaimsNothingItCannotDo() {
|
||||
assertThat(policy().providesBrokerSemantics()).isFalse();
|
||||
assertThat(policy().replacesGeneratedApis()).isFalse();
|
||||
}
|
||||
}
|
||||
-108
@@ -1,108 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.compat;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||
|
||||
import dev.caskeleton.grpc.advanced.reactor.GrpcReactorCancellationBridge;
|
||||
import dev.caskeleton.grpc.advanced.reactor.GrpcReactorContextBridge;
|
||||
import dev.caskeleton.grpc.api.context.GrpcClientIdentity;
|
||||
import dev.caskeleton.grpc.api.context.GrpcMetadataBudget;
|
||||
import dev.caskeleton.grpc.api.context.GrpcRequestContext;
|
||||
import dev.caskeleton.grpc.api.deadline.GrpcCancellationToken;
|
||||
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineBudget;
|
||||
import dev.caskeleton.grpc.api.deadline.GrpcDeadlineProfile;
|
||||
import dev.caskeleton.grpc.context.GrpcContextSnapshot;
|
||||
import dev.caskeleton.grpc.core.GrpcMethodName;
|
||||
import dev.caskeleton.grpc.core.RpcType;
|
||||
import dev.caskeleton.grpc.deadline.GrpcCancellationCoordinator;
|
||||
import dev.caskeleton.grpc.deadline.GrpcCancellationReason;
|
||||
import java.time.Duration;
|
||||
import java.time.Instant;
|
||||
import java.util.Map;
|
||||
import java.util.Set;
|
||||
import java.util.concurrent.atomic.AtomicBoolean;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
import reactor.util.context.Context;
|
||||
|
||||
class GrpcReactorContextBridgeTest {
|
||||
|
||||
private static final GrpcMethodName GET =
|
||||
GrpcMethodName.parse("caskeleton.document.v1.DocumentService/GetDocument");
|
||||
private static final Instant NOW = Instant.parse("2026-08-30T10:00:00Z");
|
||||
|
||||
private static GrpcContextSnapshot snapshot() {
|
||||
GrpcRequestContext request =
|
||||
GrpcRequestContext.create(
|
||||
GET,
|
||||
RpcType.UNARY,
|
||||
GrpcClientIdentity.fromVerifiedAuthentication("actor-1", "tenant-1", "jwt-issuer"),
|
||||
GrpcDeadlineBudget.forEntryPoint(
|
||||
Duration.ofSeconds(1), GrpcDeadlineProfile.of(Duration.ofSeconds(2))),
|
||||
new GrpcCancellationToken(),
|
||||
Map.of(),
|
||||
Set.of(),
|
||||
GrpcMetadataBudget.standard(),
|
||||
null);
|
||||
return GrpcContextSnapshot.of(request, null);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("the call context crosses into and out of a Reactor context")
|
||||
void theContextCrossesIntoReactor() {
|
||||
GrpcContextSnapshot snapshot = snapshot();
|
||||
|
||||
Context context = GrpcReactorContextBridge.write(Context.empty(), snapshot);
|
||||
|
||||
assertThat(GrpcReactorContextBridge.read(context)).contains(snapshot);
|
||||
assertThat(GrpcReactorContextBridge.require(context).identity().actorId()).isEqualTo("actor-1");
|
||||
assertThat(GrpcReactorContextBridge.contextKey()).isNotBlank();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("reactive work with no call context fails closed")
|
||||
void contextlessReactiveWorkFailsClosed() {
|
||||
assertThat(GrpcReactorContextBridge.read(Context.empty())).isEmpty();
|
||||
assertThatThrownBy(() -> GrpcReactorContextBridge.require(Context.empty()))
|
||||
.isInstanceOf(IllegalStateException.class)
|
||||
.hasMessageContaining("attributed to nobody");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a Reactor cancellation reaches the platform coordinator")
|
||||
void reactorCancellationReachesThePlatform() {
|
||||
GrpcCancellationCoordinator coordinator =
|
||||
new GrpcCancellationCoordinator(new GrpcCancellationToken());
|
||||
|
||||
GrpcReactorCancellationBridge.onReactorCancel(coordinator, () -> NOW).run();
|
||||
|
||||
assertThat(coordinator.cancelled()).isTrue();
|
||||
assertThat(coordinator.reason()).contains(GrpcCancellationReason.CLIENT_CANCELLED);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a platform cancellation disposes the reactive subscription")
|
||||
void platformCancellationDisposesTheSubscription() {
|
||||
GrpcCancellationCoordinator coordinator =
|
||||
new GrpcCancellationCoordinator(new GrpcCancellationToken());
|
||||
AtomicBoolean disposed = new AtomicBoolean();
|
||||
|
||||
GrpcReactorCancellationBridge.bindPlatformCancellation(
|
||||
coordinator, () -> disposed.set(true), "document-query");
|
||||
coordinator.cancel(GrpcCancellationReason.DEADLINE_EXCEEDED, NOW);
|
||||
|
||||
assertThat(disposed).isTrue();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("binding a subscription without a name is refused")
|
||||
void bindingNeedsAnOperationName() {
|
||||
GrpcCancellationCoordinator coordinator =
|
||||
new GrpcCancellationCoordinator(new GrpcCancellationToken());
|
||||
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
GrpcReactorCancellationBridge.bindPlatformCancellation(coordinator, () -> {}, " "))
|
||||
.isInstanceOf(IllegalArgumentException.class);
|
||||
}
|
||||
}
|
||||
-180
@@ -1,180 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.compat;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||
|
||||
import dev.caskeleton.grpc.advanced.web.GrpcWebProfile;
|
||||
import dev.caskeleton.grpc.advanced.web.GrpcWebProxyContract;
|
||||
import dev.caskeleton.grpc.advanced.web.GrpcWebRpcSupport;
|
||||
import dev.caskeleton.grpc.core.RpcType;
|
||||
import dev.caskeleton.grpc.error.GrpcErrorMapper;
|
||||
import dev.caskeleton.grpc.validation.GrpcValidationInterceptor;
|
||||
import java.io.IOException;
|
||||
import java.io.InputStream;
|
||||
import java.io.UncheckedIOException;
|
||||
import java.nio.charset.StandardCharsets;
|
||||
import java.util.Set;
|
||||
import java.util.regex.Matcher;
|
||||
import java.util.regex.Pattern;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class GrpcWebCompatibilityTest {
|
||||
|
||||
@Test
|
||||
@DisplayName("gRPC-Web carries unary and server streaming, and nothing else")
|
||||
void grpcWebCarriesTwoShapes() {
|
||||
assertThat(GrpcWebRpcSupport.supported(RpcType.UNARY)).isTrue();
|
||||
assertThat(GrpcWebRpcSupport.supported(RpcType.SERVER_STREAMING)).isTrue();
|
||||
assertThat(GrpcWebRpcSupport.supported(RpcType.CLIENT_STREAMING)).isFalse();
|
||||
assertThat(GrpcWebRpcSupport.supported(RpcType.BIDI_STREAMING)).isFalse();
|
||||
assertThatThrownBy(() -> GrpcWebRpcSupport.require(RpcType.BIDI_STREAMING))
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("no way to send a stream of messages");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a wildcard origin is refused, and cookie credentials require CSRF protection")
|
||||
void browserCredentialRulesDifferByStyle() {
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
new GrpcWebProfile(GrpcWebProfile.CredentialStyle.BEARER, Set.of("*"), false, true))
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("ambient credentials");
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
new GrpcWebProfile(
|
||||
GrpcWebProfile.CredentialStyle.COOKIE,
|
||||
Set.of("https://app.example.com"),
|
||||
false,
|
||||
true))
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("CSRF defence is not optional");
|
||||
assertThat(GrpcWebProfile.bearer("https://app.example.com").csrfProtection()).isFalse();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a credentialed profile needs an origin allowlist and TLS at the proxy")
|
||||
void aCredentialedProfileNeedsBoth() {
|
||||
assertThatThrownBy(
|
||||
() -> new GrpcWebProfile(GrpcWebProfile.CredentialStyle.BEARER, Set.of(), false, true))
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("origin allowlist");
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
new GrpcWebProfile(
|
||||
GrpcWebProfile.CredentialStyle.BEARER,
|
||||
Set.of("https://app.example.com"),
|
||||
false,
|
||||
false))
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("TLS terminated at the proxy");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a proxy that hides the status trailers is reported")
|
||||
void aProxyMustExposeTheStatusTrailers() {
|
||||
GrpcWebProfile profile = GrpcWebProfile.bearer("https://app.example.com");
|
||||
|
||||
assertThat(
|
||||
GrpcWebProxyContract.violations(
|
||||
profile, Set.of("grpc-status"), Set.of("https://app.example.com")))
|
||||
.anySatisfy(violation -> assertThat(violation).contains("grpc-message"));
|
||||
assertThat(
|
||||
GrpcWebProxyContract.violations(
|
||||
profile,
|
||||
GrpcWebProxyContract.requiredExposedHeaders(),
|
||||
Set.of("https://app.example.com")))
|
||||
.isEmpty();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a proxy allowing any origin, or missing the profile's, is reported")
|
||||
void proxyOriginMismatchesAreReported() {
|
||||
GrpcWebProfile profile = GrpcWebProfile.bearer("https://app.example.com");
|
||||
|
||||
assertThat(
|
||||
GrpcWebProxyContract.violations(
|
||||
profile, GrpcWebProxyContract.requiredExposedHeaders(), Set.of("*")))
|
||||
.anySatisfy(violation -> assertThat(violation).contains("defeats the profile's allowlist"));
|
||||
assertThat(
|
||||
GrpcWebProxyContract.violations(
|
||||
profile, GrpcWebProxyContract.requiredExposedHeaders(), Set.of()))
|
||||
.anySatisfy(violation -> assertThat(violation).contains("not in the proxy's allowlist"));
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("the reference Envoy configuration exposes the trailers and pins the origin")
|
||||
void theReferenceProxyConfigurationIsCorrect() {
|
||||
String envoy = resource("envoy/envoy.yaml");
|
||||
|
||||
assertThat(envoy)
|
||||
.contains("expose_headers: \"grpc-status,grpc-message")
|
||||
.contains("exact: \"https://app.example.com\"")
|
||||
.contains("envoy.filters.http.grpc_web");
|
||||
}
|
||||
|
||||
@Test
|
||||
void theReferenceProxyExposesEveryTrailerThePlatformSends() {
|
||||
// when
|
||||
Set<String> exposed = headerList(resource("envoy/envoy.yaml"), "expose_headers");
|
||||
|
||||
// then
|
||||
assertThat(exposed)
|
||||
.contains(
|
||||
"grpc-status",
|
||||
"grpc-message",
|
||||
"grpc-status-details-bin",
|
||||
GrpcErrorMapper.REASON_KEY.name(),
|
||||
GrpcErrorMapper.EXECUTION_ID_KEY.name(),
|
||||
GrpcErrorMapper.COMPLETION_OUTCOME_KEY.name(),
|
||||
GrpcValidationInterceptor.VIOLATIONS_KEY.name());
|
||||
}
|
||||
|
||||
@Test
|
||||
void theReferenceProxyLetsTheBrowserSendItsDeadlineAndClientHeaders() {
|
||||
// when
|
||||
Set<String> allowed = headerList(resource("envoy/envoy.yaml"), "allow_headers");
|
||||
|
||||
// then
|
||||
assertThat(allowed).contains("grpc-timeout", "x-user-agent", "x-grpc-web", "content-type");
|
||||
}
|
||||
|
||||
@Test
|
||||
void theReferenceRouteLeavesStreamLengthToTheCallersDeadline() {
|
||||
// when
|
||||
String envoy = resource("envoy/envoy.yaml");
|
||||
|
||||
// then
|
||||
assertThat(envoy).contains("timeout: 0s").contains("grpc_timeout_header_max: 0s");
|
||||
}
|
||||
|
||||
@Test
|
||||
void theReferenceProxyTerminatesTlsWithACertificate() {
|
||||
// when
|
||||
String envoy = resource("envoy/envoy.yaml");
|
||||
|
||||
// then
|
||||
assertThat(envoy).contains("certificate_chain:").contains("private_key:");
|
||||
}
|
||||
|
||||
private static Set<String> headerList(String envoy, String field) {
|
||||
Matcher matcher = Pattern.compile(field + ": \"([^\"]*)\"").matcher(envoy);
|
||||
if (!matcher.find()) {
|
||||
throw new IllegalStateException("the reference proxy has no " + field);
|
||||
}
|
||||
return Set.of(matcher.group(1).split(","));
|
||||
}
|
||||
|
||||
private static String resource(String path) {
|
||||
try (InputStream stream =
|
||||
GrpcWebCompatibilityTest.class.getClassLoader().getResourceAsStream(path)) {
|
||||
if (stream == null) {
|
||||
throw new IllegalStateException("missing resource " + path);
|
||||
}
|
||||
return new String(stream.readAllBytes(), StandardCharsets.UTF_8);
|
||||
} catch (IOException e) {
|
||||
throw new UncheckedIOException(e);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,80 +0,0 @@
|
||||
# The gRPC-Web proxy contract, as a reference Envoy configuration.
|
||||
#
|
||||
# Shipped as a resource rather than as documentation prose because GrpcWebProxyContract asserts
|
||||
# against it: the CORS allowlist, the exposed trailer headers and the TLS termination are the three
|
||||
# things a browser client silently fails without, and a contract nobody checks is a contract that
|
||||
# drifts from whatever is actually deployed.
|
||||
#
|
||||
# The exposed headers matter most and are the least obvious. gRPC statuses arrive as trailers, and a
|
||||
# browser cannot read a trailer the proxy did not expose; the symptom is a call that appears to hang
|
||||
# and then fails with no status at all.
|
||||
static_resources:
|
||||
listeners:
|
||||
- name: grpc_web_listener
|
||||
address:
|
||||
socket_address: { address: 0.0.0.0, port_value: 8443 }
|
||||
filter_chains:
|
||||
- filters:
|
||||
- name: envoy.filters.network.http_connection_manager
|
||||
typed_config:
|
||||
"@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
|
||||
stat_prefix: grpc_web
|
||||
codec_type: AUTO
|
||||
route_config:
|
||||
name: grpc_web_route
|
||||
virtual_hosts:
|
||||
- name: grpc_web_host
|
||||
domains: ["*"]
|
||||
routes:
|
||||
- match: { prefix: "/" }
|
||||
route:
|
||||
cluster: grpc_backend
|
||||
# No route timeout: it would cut every server stream at that age. The
|
||||
# caller's grpc-timeout header bounds each call instead.
|
||||
timeout: 0s
|
||||
max_stream_duration:
|
||||
grpc_timeout_header_max: 0s
|
||||
cors:
|
||||
allow_origin_string_match:
|
||||
- exact: "https://app.example.com"
|
||||
allow_methods: "POST,OPTIONS"
|
||||
allow_headers: "content-type,x-grpc-web,x-user-agent,grpc-timeout,x-correlation-id,authorization"
|
||||
# Every trailer the platform sends (GrpcErrorMapper, GrpcValidationInterceptor).
|
||||
expose_headers: "grpc-status,grpc-message,grpc-status-details-bin,error-reason,error-execution-id,completion-outcome,validation-violations"
|
||||
max_age: "1728000"
|
||||
http_filters:
|
||||
- name: envoy.filters.http.grpc_web
|
||||
typed_config:
|
||||
"@type": type.googleapis.com/envoy.extensions.filters.http.grpc_web.v3.GrpcWeb
|
||||
- name: envoy.filters.http.cors
|
||||
typed_config:
|
||||
"@type": type.googleapis.com/envoy.extensions.filters.http.cors.v3.Cors
|
||||
- name: envoy.filters.http.router
|
||||
typed_config:
|
||||
"@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
|
||||
transport_socket:
|
||||
name: envoy.transport_sockets.tls
|
||||
typed_config:
|
||||
"@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
|
||||
# Placeholder paths: mount the proxy's certificate and key here.
|
||||
common_tls_context:
|
||||
tls_certificates:
|
||||
- certificate_chain: { filename: /etc/envoy/tls/tls.crt }
|
||||
private_key: { filename: /etc/envoy/tls/tls.key }
|
||||
clusters:
|
||||
- name: grpc_backend
|
||||
connect_timeout: 1s
|
||||
type: STRICT_DNS
|
||||
lb_policy: ROUND_ROBIN
|
||||
typed_extension_protocol_options:
|
||||
envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
|
||||
"@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions
|
||||
explicit_http_config:
|
||||
http2_protocol_options: {}
|
||||
load_assignment:
|
||||
cluster_name: grpc_backend
|
||||
endpoints:
|
||||
- lb_endpoints:
|
||||
- endpoint:
|
||||
address:
|
||||
socket_address: { address: documents, port_value: 9090 }
|
||||
@@ -1,28 +0,0 @@
|
||||
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 `app.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')
|
||||
}
|
||||
@@ -1,85 +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.41.0=spotbugs
|
||||
com.google.errorprone:error_prone_annotations:2.50.0=annotationProcessor,checkstyle,compileClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath
|
||||
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,compileClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath
|
||||
com.google.guava:guava:33.7.2-jre=annotationProcessor,checkstyle,compileClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath
|
||||
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.1=annotationProcessor,checkstyle,compileClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath
|
||||
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.75.0=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
|
||||
io.grpc:grpc-stub:1.75.0=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.codehaus.mojo:animal-sniffer-annotations:1.24=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.6.1=checkstyle
|
||||
org.dom4j:dom4j:2.2.0=spotbugs
|
||||
org.javassist:javassist:3.28.0-GA=checkstyle
|
||||
org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,compileClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath
|
||||
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.20=spotbugs,spotbugsSlf4j
|
||||
org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j
|
||||
org.slf4j:slf4j-simple:2.0.20=checkstyle
|
||||
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
|
||||
empty=
|
||||
-65
@@ -1,65 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.bootstrap;
|
||||
|
||||
/**
|
||||
* Every capability the Stable platform deliberately excludes, and how ready each one is.
|
||||
*
|
||||
* <p>Grading them individually is the design. Bundling them under one "advanced" flag makes
|
||||
* enabling gRPC-Web — a compatibility bridge with a proxy in front of it — the same decision as
|
||||
* enabling xDS, which brings a control plane and its outage modes. They are not the same decision,
|
||||
* and a single switch is how the second one gets made by accident.
|
||||
*/
|
||||
public enum GrpcAdvancedCapability {
|
||||
/** Protobuf Edition 2024 as an opt-in schema lane. */
|
||||
EDITION_2024("edition-2024", GrpcCapabilityGrade.ADVANCED_STABLE),
|
||||
/** Protobuf Edition 2026. Recorded, not usable. */
|
||||
EDITION_2026("edition-2026", GrpcCapabilityGrade.WATCH),
|
||||
/** Client streaming with session, dedup and checkpoint. */
|
||||
CLIENT_STREAMING("client-streaming", GrpcCapabilityGrade.ADVANCED_STABLE),
|
||||
/** Bidirectional streaming with independent per-direction sequences. */
|
||||
BIDI_STREAMING("bidi-streaming", GrpcCapabilityGrade.ADVANCED_STABLE),
|
||||
/** Manual flow control, for approved streaming methods. */
|
||||
MANUAL_FLOW_CONTROL("manual-flow-control", GrpcCapabilityGrade.ADVANCED_STABLE),
|
||||
/** Read-only unary hedging. */
|
||||
HEDGING("hedging", GrpcCapabilityGrade.EXPERIMENTAL),
|
||||
/** A custom name resolver. */
|
||||
CUSTOM_RESOLVER("custom-resolver", GrpcCapabilityGrade.ADVANCED_STABLE),
|
||||
/** A custom load balancer. */
|
||||
CUSTOM_LOAD_BALANCER("custom-load-balancer", GrpcCapabilityGrade.EXPERIMENTAL),
|
||||
/** Proxyless xDS. */
|
||||
XDS("xds", GrpcCapabilityGrade.EXPERIMENTAL),
|
||||
/** The gRPC-Web bridge. */
|
||||
GRPC_WEB("grpc-web", GrpcCapabilityGrade.ADVANCED_STABLE),
|
||||
/** A Servlet container owning the HTTP/2 socket. */
|
||||
SERVLET_COMPAT("servlet-compat", GrpcCapabilityGrade.ADVANCED_STABLE),
|
||||
/** The Spring Integration bridge. */
|
||||
INTEGRATION_BRIDGE("integration-bridge", GrpcCapabilityGrade.ADVANCED_STABLE),
|
||||
/** The Reactor adapter. */
|
||||
REACTOR("reactor", GrpcCapabilityGrade.ADVANCED_STABLE),
|
||||
/** The Kotlin coroutine and Flow adapter. */
|
||||
KOTLIN("kotlin", GrpcCapabilityGrade.ADVANCED_STABLE),
|
||||
/** Channelz and CSDS diagnostics. */
|
||||
CHANNEL_DIAGNOSTICS("channel-diagnostics", GrpcCapabilityGrade.ADVANCED_STABLE);
|
||||
|
||||
private final String flagName;
|
||||
private final GrpcCapabilityGrade defaultGrade;
|
||||
|
||||
GrpcAdvancedCapability(String flagName, GrpcCapabilityGrade defaultGrade) {
|
||||
this.flagName = flagName;
|
||||
this.defaultGrade = defaultGrade;
|
||||
}
|
||||
|
||||
/** The property suffix under {@code app.grpc.advanced}. */
|
||||
public String flagName() {
|
||||
return flagName;
|
||||
}
|
||||
|
||||
/** The full property key that enables this capability. */
|
||||
public String propertyKey() {
|
||||
return "app.grpc.advanced." + flagName + ".enabled";
|
||||
}
|
||||
|
||||
/** How ready this capability is today. */
|
||||
public GrpcCapabilityGrade defaultGrade() {
|
||||
return defaultGrade;
|
||||
}
|
||||
}
|
||||
-42
@@ -1,42 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.bootstrap;
|
||||
|
||||
/**
|
||||
* A capability was used without being enabled.
|
||||
*
|
||||
* <p>The message carries the property key. An advanced capability is off by default and the refusal
|
||||
* is the first thing a developer meets when trying it; telling them which key to set turns a
|
||||
* support question into a configuration line.
|
||||
*/
|
||||
public class GrpcAdvancedCapabilityDisabledException extends RuntimeException {
|
||||
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
private final transient GrpcAdvancedCapability capability;
|
||||
|
||||
/** Refuses use of a disabled capability. */
|
||||
public GrpcAdvancedCapabilityDisabledException(GrpcAdvancedCapability capability, String reason) {
|
||||
super(render(capability, reason));
|
||||
this.capability = capability;
|
||||
}
|
||||
|
||||
private static String render(GrpcAdvancedCapability capability, String reason) {
|
||||
if (capability == null) {
|
||||
throw new IllegalArgumentException("a capability is required");
|
||||
}
|
||||
if (reason == null || reason.isBlank()) {
|
||||
throw new IllegalArgumentException("a refusal explains itself");
|
||||
}
|
||||
return "advanced capability '"
|
||||
+ capability.flagName()
|
||||
+ "' is not available: "
|
||||
+ reason
|
||||
+ " (set "
|
||||
+ capability.propertyKey()
|
||||
+ "=true to enable it)";
|
||||
}
|
||||
|
||||
/** The capability that was refused. */
|
||||
public GrpcAdvancedCapability capability() {
|
||||
return capability;
|
||||
}
|
||||
}
|
||||
-105
@@ -1,105 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.bootstrap;
|
||||
|
||||
import java.util.EnumMap;
|
||||
import java.util.EnumSet;
|
||||
import java.util.Map;
|
||||
import java.util.Set;
|
||||
|
||||
/**
|
||||
* Which advanced capabilities a deployment has turned on.
|
||||
*
|
||||
* <p>Everything is off unless named. A capability that switches itself on because its jar is
|
||||
* present is a capability nobody decided to run, and the ones here bring proxies, control planes
|
||||
* and duplicate request load with them.
|
||||
*/
|
||||
public final class GrpcAdvancedFeatureFlags {
|
||||
|
||||
private final Map<GrpcAdvancedCapability, Boolean> enabled =
|
||||
new EnumMap<>(GrpcAdvancedCapability.class);
|
||||
private final Map<GrpcAdvancedCapability, GrpcCapabilityGrade> grades =
|
||||
new EnumMap<>(GrpcAdvancedCapability.class);
|
||||
private final boolean production;
|
||||
private final Set<GrpcAdvancedCapability> productionApprovals;
|
||||
|
||||
private GrpcAdvancedFeatureFlags(
|
||||
boolean production, Set<GrpcAdvancedCapability> productionApprovals) {
|
||||
this.production = production;
|
||||
this.productionApprovals =
|
||||
EnumSet.copyOf(
|
||||
productionApprovals.isEmpty()
|
||||
? EnumSet.noneOf(GrpcAdvancedCapability.class)
|
||||
: EnumSet.copyOf(productionApprovals));
|
||||
for (GrpcAdvancedCapability capability : GrpcAdvancedCapability.values()) {
|
||||
enabled.put(capability, false);
|
||||
grades.put(capability, capability.defaultGrade());
|
||||
}
|
||||
}
|
||||
|
||||
/** Flags for a non-production environment. */
|
||||
public static GrpcAdvancedFeatureFlags forDevelopment() {
|
||||
return new GrpcAdvancedFeatureFlags(false, Set.of());
|
||||
}
|
||||
|
||||
/**
|
||||
* Flags for production.
|
||||
*
|
||||
* @param productionApprovals the experimental capabilities somebody has accepted the risk of
|
||||
*/
|
||||
public static GrpcAdvancedFeatureFlags forProduction(
|
||||
Set<GrpcAdvancedCapability> productionApprovals) {
|
||||
if (productionApprovals == null) {
|
||||
throw new IllegalArgumentException("an approval set is required, even if empty");
|
||||
}
|
||||
return new GrpcAdvancedFeatureFlags(true, productionApprovals);
|
||||
}
|
||||
|
||||
/** Turns a capability on. */
|
||||
public GrpcAdvancedFeatureFlags enable(GrpcAdvancedCapability capability) {
|
||||
if (capability == null) {
|
||||
throw new IllegalArgumentException("a capability is required");
|
||||
}
|
||||
enabled.put(capability, true);
|
||||
return this;
|
||||
}
|
||||
|
||||
/** Overrides a capability's grade, for a deployment that has its own evidence. */
|
||||
public GrpcAdvancedFeatureFlags withGrade(
|
||||
GrpcAdvancedCapability capability, GrpcCapabilityGrade grade) {
|
||||
if (capability == null || grade == null) {
|
||||
throw new IllegalArgumentException("a grade override needs both parts");
|
||||
}
|
||||
grades.put(capability, grade);
|
||||
return this;
|
||||
}
|
||||
|
||||
/** Whether the flag is set, regardless of whether the capability may actually start. */
|
||||
public boolean flagSet(GrpcAdvancedCapability capability) {
|
||||
return Boolean.TRUE.equals(enabled.get(capability));
|
||||
}
|
||||
|
||||
/** The grade in force for a capability. */
|
||||
public GrpcCapabilityGrade gradeOf(GrpcAdvancedCapability capability) {
|
||||
return grades.get(capability);
|
||||
}
|
||||
|
||||
/** Whether this deployment is production. */
|
||||
public boolean production() {
|
||||
return production;
|
||||
}
|
||||
|
||||
/** Whether an experimental capability has been separately approved for production. */
|
||||
public boolean productionApproved(GrpcAdvancedCapability capability) {
|
||||
return productionApprovals.contains(capability);
|
||||
}
|
||||
|
||||
/** The capabilities that are both flagged and permitted to start. */
|
||||
public Set<GrpcAdvancedCapability> active() {
|
||||
Set<GrpcAdvancedCapability> running = EnumSet.noneOf(GrpcAdvancedCapability.class);
|
||||
for (GrpcAdvancedCapability capability : GrpcAdvancedCapability.values()) {
|
||||
if (GrpcAdvancedModuleGuard.available(this, capability)) {
|
||||
running.add(capability);
|
||||
}
|
||||
}
|
||||
return Set.copyOf(running);
|
||||
}
|
||||
}
|
||||
-64
@@ -1,64 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.bootstrap;
|
||||
|
||||
/**
|
||||
* The single gate every advanced capability passes through.
|
||||
*
|
||||
* <p>Three conditions, checked in this order because each explains a different refusal: the flag is
|
||||
* not set, the grade cannot start at all, or production has not separately approved an experimental
|
||||
* capability. Collapsing them into one boolean produces a "not enabled" message for three
|
||||
* situations with three different remedies.
|
||||
*/
|
||||
public final class GrpcAdvancedModuleGuard {
|
||||
|
||||
private GrpcAdvancedModuleGuard() {}
|
||||
|
||||
/** Whether {@code capability} may run under {@code flags}. */
|
||||
public static boolean available(
|
||||
GrpcAdvancedFeatureFlags flags, GrpcAdvancedCapability capability) {
|
||||
if (flags == null || capability == null) {
|
||||
throw new IllegalArgumentException("availability needs flags and a capability");
|
||||
}
|
||||
if (!flags.flagSet(capability)) {
|
||||
return false;
|
||||
}
|
||||
GrpcCapabilityGrade grade = flags.gradeOf(capability);
|
||||
if (!grade.startable()) {
|
||||
return false;
|
||||
}
|
||||
return !(flags.production()
|
||||
&& grade.requiresProductionApproval()
|
||||
&& !flags.productionApproved(capability));
|
||||
}
|
||||
|
||||
/**
|
||||
* Fails when {@code capability} may not run.
|
||||
*
|
||||
* @throws GrpcAdvancedCapabilityDisabledException naming which of the three conditions failed
|
||||
*/
|
||||
public static void require(GrpcAdvancedFeatureFlags flags, GrpcAdvancedCapability capability) {
|
||||
if (flags == null || capability == null) {
|
||||
throw new IllegalArgumentException("a guard needs flags and a capability");
|
||||
}
|
||||
if (!flags.flagSet(capability)) {
|
||||
throw new GrpcAdvancedCapabilityDisabledException(capability, "its feature flag is not set");
|
||||
}
|
||||
GrpcCapabilityGrade grade = flags.gradeOf(capability);
|
||||
if (!grade.startable()) {
|
||||
throw new GrpcAdvancedCapabilityDisabledException(
|
||||
capability,
|
||||
"it is graded "
|
||||
+ grade
|
||||
+ ", which cannot start; a WATCH capability is tracked rather than implemented");
|
||||
}
|
||||
if (flags.production()
|
||||
&& grade.requiresProductionApproval()
|
||||
&& !flags.productionApproved(capability)) {
|
||||
throw new GrpcAdvancedCapabilityDisabledException(
|
||||
capability,
|
||||
"it is "
|
||||
+ grade
|
||||
+ " and production needs a separate approval; the flag says somebody wanted it, not "
|
||||
+ "that somebody accepted its uncharacterised failure modes");
|
||||
}
|
||||
}
|
||||
}
|
||||
-38
@@ -1,38 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.bootstrap;
|
||||
|
||||
/**
|
||||
* How much a capability has been established, and what that permits.
|
||||
*
|
||||
* <p>{@link #EXPERIMENTAL} in production needs a second, separate approval rather than the
|
||||
* capability flag alone. The flag says somebody wanted the feature; the approval says somebody
|
||||
* accepted that its failure modes are not fully characterised, which is a different person's
|
||||
* decision on most teams.
|
||||
*/
|
||||
public enum GrpcCapabilityGrade {
|
||||
/** Contract, fault and operational evidence exist. Enable with the capability flag. */
|
||||
ADVANCED_STABLE(true, false),
|
||||
/** Works, but its failure modes are not fully characterised. Needs a production approval too. */
|
||||
EXPERIMENTAL(true, true),
|
||||
/** Tracked, not implemented. Cannot be enabled. */
|
||||
WATCH(false, false),
|
||||
/** Withdrawn or refused. Cannot be enabled. */
|
||||
DISABLED(false, false);
|
||||
|
||||
private final boolean startable;
|
||||
private final boolean requiresProductionApproval;
|
||||
|
||||
GrpcCapabilityGrade(boolean startable, boolean requiresProductionApproval) {
|
||||
this.startable = startable;
|
||||
this.requiresProductionApproval = requiresProductionApproval;
|
||||
}
|
||||
|
||||
/** Whether a deployment may run this capability at all. */
|
||||
public boolean startable() {
|
||||
return startable;
|
||||
}
|
||||
|
||||
/** Whether production additionally requires an explicit approval. */
|
||||
public boolean requiresProductionApproval() {
|
||||
return requiresProductionApproval;
|
||||
}
|
||||
}
|
||||
-55
@@ -1,55 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.diagnostics;
|
||||
|
||||
import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedCapability;
|
||||
import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedFeatureFlags;
|
||||
import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedModuleGuard;
|
||||
import java.util.Set;
|
||||
|
||||
/**
|
||||
* Who may read diagnostics, and which services are registered at all.
|
||||
*
|
||||
* <p>CSDS is registered only when xDS is enabled. A CSDS service on a deployment that does not use
|
||||
* xDS answers every query with nothing, which is harmless, and advertises a control-plane surface
|
||||
* that does not exist, which is not: it is one more endpoint to scan and one more thing whose
|
||||
* absence of authorization nobody notices.
|
||||
*/
|
||||
public record GrpcChannelDiagnosticsPolicy(Set<String> adminNetworks, Set<String> adminRoles) {
|
||||
|
||||
/** Refuses a policy with only one gate. */
|
||||
public GrpcChannelDiagnosticsPolicy {
|
||||
if (adminNetworks == null || adminRoles == null) {
|
||||
throw new IllegalArgumentException("a diagnostics policy states both gates");
|
||||
}
|
||||
adminNetworks = Set.copyOf(adminNetworks);
|
||||
adminRoles = Set.copyOf(adminRoles);
|
||||
if (adminNetworks.isEmpty() || adminRoles.isEmpty()) {
|
||||
throw new IllegalArgumentException(
|
||||
"diagnostics need both a network and a role gate; Channelz holds every socket's peer and "
|
||||
+ "security detail, so either gate alone is the whole surface");
|
||||
}
|
||||
}
|
||||
|
||||
/** This repository's default. */
|
||||
public static GrpcChannelDiagnosticsPolicy standard() {
|
||||
return new GrpcChannelDiagnosticsPolicy(Set.of("admin"), Set.of("ROLE_PLATFORM_ADMIN"));
|
||||
}
|
||||
|
||||
/** Whether this caller may read a snapshot. */
|
||||
public boolean mayRead(String callerNetwork, Set<String> callerRoles) {
|
||||
return callerNetwork != null
|
||||
&& adminNetworks.contains(callerNetwork)
|
||||
&& callerRoles != null
|
||||
&& callerRoles.stream().anyMatch(adminRoles::contains);
|
||||
}
|
||||
|
||||
/** Whether the Channelz service should be registered. */
|
||||
public static boolean registerChannelz(GrpcAdvancedFeatureFlags flags) {
|
||||
return GrpcAdvancedModuleGuard.available(flags, GrpcAdvancedCapability.CHANNEL_DIAGNOSTICS);
|
||||
}
|
||||
|
||||
/** Whether the CSDS service should be registered. Only when xDS is actually in use. */
|
||||
public static boolean registerCsds(GrpcAdvancedFeatureFlags flags) {
|
||||
return registerChannelz(flags)
|
||||
&& GrpcAdvancedModuleGuard.available(flags, GrpcAdvancedCapability.XDS);
|
||||
}
|
||||
}
|
||||
-63
@@ -1,63 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.diagnostics;
|
||||
|
||||
import java.time.Instant;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
|
||||
/**
|
||||
* What Channelz and CSDS report, after redaction.
|
||||
*
|
||||
* <p>Counters and states rather than call contents. The questions a diagnostics endpoint exists to
|
||||
* answer — which subchannels are connected, how many calls are in flight, which xDS resources the
|
||||
* control plane last sent — are all answerable from aggregates, and aggregates cannot leak a
|
||||
* caller's data.
|
||||
*/
|
||||
public record GrpcChannelDiagnosticsSnapshot(
|
||||
String channelProfile,
|
||||
String connectivityState,
|
||||
int subchannelCount,
|
||||
long callsStarted,
|
||||
long callsSucceeded,
|
||||
long callsFailed,
|
||||
List<String> maskedSocketAddresses,
|
||||
Map<String, String> xdsResourceVersions,
|
||||
Instant capturedAt) {
|
||||
|
||||
/** Refuses a snapshot carrying something it should not. */
|
||||
public GrpcChannelDiagnosticsSnapshot {
|
||||
if (channelProfile == null || channelProfile.isBlank()) {
|
||||
throw new IllegalArgumentException("a diagnostics snapshot names its channel profile");
|
||||
}
|
||||
if (connectivityState == null || connectivityState.isBlank()) {
|
||||
throw new IllegalArgumentException("a diagnostics snapshot carries a connectivity state");
|
||||
}
|
||||
if (subchannelCount < 0 || callsStarted < 0 || callsSucceeded < 0 || callsFailed < 0) {
|
||||
throw new IllegalArgumentException("diagnostics counters must not be negative");
|
||||
}
|
||||
if (maskedSocketAddresses == null || xdsResourceVersions == null || capturedAt == null) {
|
||||
throw new IllegalArgumentException("every snapshot section must be present");
|
||||
}
|
||||
maskedSocketAddresses = List.copyOf(maskedSocketAddresses);
|
||||
xdsResourceVersions = Map.copyOf(xdsResourceVersions);
|
||||
|
||||
maskedSocketAddresses.stream()
|
||||
.filter(address -> !address.equals(GrpcDiagnosticsRedactor.maskAddress(address)))
|
||||
.findFirst()
|
||||
.ifPresent(
|
||||
unmasked -> {
|
||||
throw new IllegalArgumentException(
|
||||
"socket address '"
|
||||
+ unmasked
|
||||
+ "' is not masked; a diagnostics endpoint that publishes peer addresses "
|
||||
+ "publishes every tenant's connection");
|
||||
});
|
||||
xdsResourceVersions.keySet().stream()
|
||||
.filter(GrpcDiagnosticsRedactor::forbiddenField)
|
||||
.findFirst()
|
||||
.ifPresent(
|
||||
forbidden -> {
|
||||
throw new IllegalArgumentException(
|
||||
"field '" + forbidden + "' may not appear in a diagnostics snapshot");
|
||||
});
|
||||
}
|
||||
}
|
||||
-107
@@ -1,107 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.diagnostics;
|
||||
|
||||
import java.nio.charset.StandardCharsets;
|
||||
import java.security.MessageDigest;
|
||||
import java.security.NoSuchAlgorithmException;
|
||||
import java.util.HexFormat;
|
||||
import java.util.LinkedHashMap;
|
||||
import java.util.Map;
|
||||
import java.util.regex.Pattern;
|
||||
|
||||
/**
|
||||
* Removes from a diagnostics snapshot everything that is not a diagnostic.
|
||||
*
|
||||
* <p>Channelz is unusually dangerous to expose because it is genuinely useful: it holds every
|
||||
* socket's local and remote address, the security details of each connection, and per-call state.
|
||||
* An administrator debugging a routing problem needs the shape of that; nobody needs the peer
|
||||
* addresses of every tenant's connection, and once the endpoint exists the whole of it is one
|
||||
* authorization mistake away from being readable.
|
||||
*
|
||||
* <p>Addresses are masked rather than dropped. An operator has to be able to tell two subchannels
|
||||
* apart, and a stable mask does that without publishing where they point.
|
||||
*/
|
||||
public final class GrpcDiagnosticsRedactor {
|
||||
|
||||
private static final Pattern SENSITIVE_FIELD =
|
||||
Pattern.compile(
|
||||
"(?i).*(authorization|bearer|password|secret|token|private[_-]?key|certificate|"
|
||||
+ "credential|payload|metadata).*");
|
||||
|
||||
private static final Pattern IPV4_WITH_PORT =
|
||||
Pattern.compile("\\b(\\d{1,3})\\.(\\d{1,3})\\.(\\d{1,3})\\.(\\d{1,3})(:\\d{1,5})?\\b");
|
||||
|
||||
/**
|
||||
* The forms {@link #maskAddress} produces, so masking one of them again returns it unchanged.
|
||||
*
|
||||
* <p>{@code GrpcChannelDiagnosticsSnapshot} decides whether an address is masked by masking it
|
||||
* and comparing — the only test available to it, since a masked address carries no marker. That
|
||||
* works only if masking is idempotent, and it was not: {@code 10.4.x.x} has no four numeric
|
||||
* octets, so it fell through to the hash branch and came back as {@code masked:<digest>}. A
|
||||
* snapshot built from correctly masked addresses was therefore rejected as unmasked.
|
||||
*/
|
||||
private static final Pattern ALREADY_MASKED =
|
||||
Pattern.compile("\\d{1,3}\\.\\d{1,3}\\.x\\.x|masked:[0-9a-f]{16}|unknown");
|
||||
|
||||
private GrpcDiagnosticsRedactor() {}
|
||||
|
||||
/** Whether a field name may appear in a snapshot at all. */
|
||||
public static boolean forbiddenField(String fieldName) {
|
||||
return fieldName != null && SENSITIVE_FIELD.matcher(fieldName).matches();
|
||||
}
|
||||
|
||||
/**
|
||||
* Masks an address so two of them stay distinguishable without being resolvable.
|
||||
*
|
||||
* <p>The last two octets go; the first two stay, because "which subnet" is a real diagnostic
|
||||
* question and "which host" is not one the diagnostics endpoint should answer.
|
||||
*
|
||||
* <p>Idempotent: masking an already-masked address returns it. Callers rely on that to ask "is
|
||||
* this masked?" without a marker byte.
|
||||
*/
|
||||
public static String maskAddress(String address) {
|
||||
if (address == null || address.isBlank()) {
|
||||
return "unknown";
|
||||
}
|
||||
if (ALREADY_MASKED.matcher(address).matches()) {
|
||||
return address;
|
||||
}
|
||||
var matcher = IPV4_WITH_PORT.matcher(address);
|
||||
if (matcher.find()) {
|
||||
return matcher.replaceAll(
|
||||
matchResult -> matchResult.group(1) + "." + matchResult.group(2) + ".x.x");
|
||||
}
|
||||
return "masked:" + stableAddressToken(address);
|
||||
}
|
||||
|
||||
private static String stableAddressToken(String address) {
|
||||
try {
|
||||
byte[] digest =
|
||||
MessageDigest.getInstance("SHA-256").digest(address.getBytes(StandardCharsets.UTF_8));
|
||||
return HexFormat.of().formatHex(digest, 0, 8);
|
||||
} catch (NoSuchAlgorithmException impossible) {
|
||||
throw new IllegalStateException("SHA-256 is required by the Java runtime", impossible);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* A snapshot map with forbidden fields removed and addresses masked.
|
||||
*
|
||||
* @param addressFields which keys hold addresses, since a mask applied to everything would mangle
|
||||
* version strings and counters
|
||||
*/
|
||||
public static Map<String, String> redact(
|
||||
Map<String, String> raw, java.util.Set<String> addressFields) {
|
||||
if (raw == null || addressFields == null) {
|
||||
throw new IllegalArgumentException("redaction needs the map and the address field set");
|
||||
}
|
||||
Map<String, String> redacted = new LinkedHashMap<>();
|
||||
raw.forEach(
|
||||
(key, value) -> {
|
||||
if (forbiddenField(key)) {
|
||||
return;
|
||||
}
|
||||
redacted.put(key, addressFields.contains(key) ? maskAddress(value) : value);
|
||||
});
|
||||
return Map.copyOf(redacted);
|
||||
}
|
||||
}
|
||||
-75
@@ -1,75 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.discovery;
|
||||
|
||||
import java.util.List;
|
||||
import java.util.Optional;
|
||||
import java.util.concurrent.atomic.AtomicBoolean;
|
||||
import java.util.concurrent.atomic.AtomicReference;
|
||||
import java.util.function.Consumer;
|
||||
|
||||
/**
|
||||
* A custom name resolver, with the safety rules applied on the way in.
|
||||
*
|
||||
* <p>Everything an update can do wrong is checked here rather than by the listener, because the
|
||||
* listener is the channel and the channel will believe whatever it is told. Stale revisions and
|
||||
* empty endpoint sets are dropped rather than propagated, and once closed the resolver accepts
|
||||
* nothing at all.
|
||||
*/
|
||||
public final class GrpcCustomResolver implements AutoCloseable {
|
||||
|
||||
private final String authority;
|
||||
private final Consumer<GrpcResolverUpdate> listener;
|
||||
private final AtomicReference<GrpcEndpointSnapshot> applied = new AtomicReference<>();
|
||||
private final AtomicBoolean closed = new AtomicBoolean();
|
||||
|
||||
/** Binds a resolver to the authority it resolves and the listener it feeds. */
|
||||
public GrpcCustomResolver(String authority, Consumer<GrpcResolverUpdate> listener) {
|
||||
if (authority == null || authority.isBlank()) {
|
||||
throw new IllegalArgumentException("a resolver names the authority it resolves");
|
||||
}
|
||||
if (listener == null) {
|
||||
throw new IllegalArgumentException("a resolver needs a listener to deliver updates to");
|
||||
}
|
||||
this.authority = authority;
|
||||
this.listener = listener;
|
||||
}
|
||||
|
||||
/**
|
||||
* Offers an update.
|
||||
*
|
||||
* @return the violations that stopped it, empty when it was applied
|
||||
*/
|
||||
public List<String> offer(GrpcResolverUpdate update) {
|
||||
if (closed.get()) {
|
||||
return List.of(
|
||||
"the resolver is closed; an update after close resurrects routing for a channel nobody "
|
||||
+ "is using");
|
||||
}
|
||||
List<String> violations = GrpcResolverSafetyPolicy.violations(update, applied.get());
|
||||
if (!violations.isEmpty()) {
|
||||
return violations;
|
||||
}
|
||||
applied.set(update.snapshot());
|
||||
listener.accept(update);
|
||||
return List.of();
|
||||
}
|
||||
|
||||
/** The snapshot currently in force. */
|
||||
public Optional<GrpcEndpointSnapshot> currentSnapshot() {
|
||||
return Optional.ofNullable(applied.get());
|
||||
}
|
||||
|
||||
/** The authority this resolver answers for. */
|
||||
public String authority() {
|
||||
return authority;
|
||||
}
|
||||
|
||||
/** Whether the resolver has been closed. */
|
||||
public boolean closed() {
|
||||
return closed.get();
|
||||
}
|
||||
|
||||
@Override
|
||||
public void close() {
|
||||
closed.set(true);
|
||||
}
|
||||
}
|
||||
-36
@@ -1,36 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.discovery;
|
||||
|
||||
/**
|
||||
* One endpoint a picker may choose, described only by what routing is allowed to consider.
|
||||
*
|
||||
* <p>The field list is the allowlist. Health, connectivity, weight and ejection are properties of
|
||||
* the endpoint; a tenant id or a request field is a property of the caller, and routing on those
|
||||
* turns a load balancer into a router with an authorization decision buried in it.
|
||||
*/
|
||||
public record GrpcEndpointCandidate(
|
||||
String address, boolean healthy, boolean connected, int weight, boolean ejected) {
|
||||
|
||||
/** Requires an address and a sane weight. */
|
||||
public GrpcEndpointCandidate {
|
||||
if (address == null || address.isBlank()) {
|
||||
throw new IllegalArgumentException("an endpoint candidate needs an address");
|
||||
}
|
||||
if (weight < 0) {
|
||||
throw new IllegalArgumentException("a weight must not be negative");
|
||||
}
|
||||
if (weight > 1000) {
|
||||
throw new IllegalArgumentException(
|
||||
"a weight above 1000 is a scale nobody can reason about against the others");
|
||||
}
|
||||
}
|
||||
|
||||
/** A healthy, connected endpoint at the default weight. */
|
||||
public static GrpcEndpointCandidate ready(String address) {
|
||||
return new GrpcEndpointCandidate(address, true, true, 100, false);
|
||||
}
|
||||
|
||||
/** Whether this endpoint may receive a request. */
|
||||
public boolean selectable() {
|
||||
return healthy && connected && !ejected && weight > 0;
|
||||
}
|
||||
}
|
||||
-46
@@ -1,46 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.discovery;
|
||||
|
||||
import java.util.List;
|
||||
import java.util.Set;
|
||||
|
||||
/**
|
||||
* One resolver update: a monotonic revision and the complete endpoint set at that revision.
|
||||
*
|
||||
* <p>Complete, not a delta. A delta protocol needs both sides to agree on what they last saw, and a
|
||||
* resolver that reconnects to its discovery source has no way to establish that; a full set at each
|
||||
* revision makes a missed update harmless.
|
||||
*
|
||||
* <p>The revision is what makes a late update safe to drop. Without it, an update that arrives out
|
||||
* of order replaces newer endpoints with older ones, and the channel routes to instances that were
|
||||
* removed.
|
||||
*/
|
||||
public record GrpcEndpointSnapshot(long revision, String authority, List<String> endpoints) {
|
||||
|
||||
/** Requires a positive revision, an authority and a non-empty endpoint set. */
|
||||
public GrpcEndpointSnapshot {
|
||||
if (revision < 1) {
|
||||
throw new IllegalArgumentException("resolver revisions are 1-based; got " + revision);
|
||||
}
|
||||
if (authority == null || authority.isBlank()) {
|
||||
throw new IllegalArgumentException("a snapshot names the authority it resolves");
|
||||
}
|
||||
if (endpoints == null || endpoints.isEmpty()) {
|
||||
throw new IllegalArgumentException(
|
||||
"an empty endpoint set is refused; a resolver that reports zero endpoints during its own "
|
||||
+ "outage would take the channel down with it");
|
||||
}
|
||||
if (endpoints.stream().anyMatch(endpoint -> endpoint == null || endpoint.isBlank())) {
|
||||
throw new IllegalArgumentException("every endpoint must be a non-blank address");
|
||||
}
|
||||
endpoints = List.copyOf(endpoints);
|
||||
if (Set.copyOf(endpoints).size() != endpoints.size()) {
|
||||
throw new IllegalArgumentException(
|
||||
"duplicate endpoints skew a round-robin picker towards whichever address is repeated");
|
||||
}
|
||||
}
|
||||
|
||||
/** Whether this snapshot supersedes {@code other}. */
|
||||
public boolean supersedes(GrpcEndpointSnapshot other) {
|
||||
return other == null || (authority.equals(other.authority()) && revision > other.revision());
|
||||
}
|
||||
}
|
||||
-58
@@ -1,58 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.discovery;
|
||||
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* Which endpoint a picker chose, or why it chose none.
|
||||
*
|
||||
* <p>{@link Verdict#DETERMINISTIC_FALLBACK} is separate from {@link Verdict#NO_ENDPOINT_AVAILABLE}
|
||||
* because they say different things about the picker. The first means custom logic failed and the
|
||||
* platform took over, which is a defect to fix; the second means there was genuinely nowhere to
|
||||
* send the request, which is an outage. A picker that reports both the same way hides its own bugs
|
||||
* inside the backend's.
|
||||
*/
|
||||
public record GrpcLoadBalancerDecision(
|
||||
Verdict verdict, Optional<GrpcEndpointCandidate> chosen, String reason) {
|
||||
|
||||
/** What the picker decided. */
|
||||
public enum Verdict {
|
||||
/** The picker chose an endpoint. */
|
||||
PICKED,
|
||||
/** The picker failed; the platform chose deterministically instead. */
|
||||
DETERMINISTIC_FALLBACK,
|
||||
/** Nothing was selectable. */
|
||||
NO_ENDPOINT_AVAILABLE
|
||||
}
|
||||
|
||||
/** Requires an endpoint on the two verdicts that have one. */
|
||||
public GrpcLoadBalancerDecision {
|
||||
if (verdict == null || chosen == null) {
|
||||
throw new IllegalArgumentException("a picker decision has a verdict and the Optional");
|
||||
}
|
||||
if (reason == null || reason.isBlank()) {
|
||||
throw new IllegalArgumentException("a picker decision explains itself");
|
||||
}
|
||||
if (verdict == Verdict.NO_ENDPOINT_AVAILABLE && chosen.isPresent()) {
|
||||
throw new IllegalArgumentException("a decision with no endpoint available carries none");
|
||||
}
|
||||
if (verdict != Verdict.NO_ENDPOINT_AVAILABLE && chosen.isEmpty()) {
|
||||
throw new IllegalArgumentException("a decision that picked carries the endpoint it picked");
|
||||
}
|
||||
}
|
||||
|
||||
/** The picker's own choice. */
|
||||
public static GrpcLoadBalancerDecision picked(GrpcEndpointCandidate endpoint, String reason) {
|
||||
return new GrpcLoadBalancerDecision(Verdict.PICKED, Optional.of(endpoint), reason);
|
||||
}
|
||||
|
||||
/** The platform's fallback after a picker failure. */
|
||||
public static GrpcLoadBalancerDecision fallback(GrpcEndpointCandidate endpoint, String reason) {
|
||||
return new GrpcLoadBalancerDecision(
|
||||
Verdict.DETERMINISTIC_FALLBACK, Optional.of(endpoint), reason);
|
||||
}
|
||||
|
||||
/** Nothing was selectable. */
|
||||
public static GrpcLoadBalancerDecision none(String reason) {
|
||||
return new GrpcLoadBalancerDecision(Verdict.NO_ENDPOINT_AVAILABLE, Optional.empty(), reason);
|
||||
}
|
||||
}
|
||||
-29
@@ -1,29 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.discovery;
|
||||
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* Chooses one endpoint from the candidates the resolver supplied.
|
||||
*
|
||||
* <p>The signature is the safety property. A picker receives a list of candidates and nothing else:
|
||||
* no request, no metadata, no caller. It therefore cannot route on a tenant, and the rule "business
|
||||
* data is not a routing input" is enforced by there being no business data to reach.
|
||||
*/
|
||||
@FunctionalInterface
|
||||
public interface GrpcLoadBalancerPicker {
|
||||
|
||||
/**
|
||||
* Picks an endpoint.
|
||||
*
|
||||
* @param candidates the selectable endpoints, never empty
|
||||
* @return the chosen endpoint, which must be one of {@code candidates}
|
||||
*/
|
||||
GrpcEndpointCandidate pick(List<GrpcEndpointCandidate> candidates);
|
||||
|
||||
/** Round-robin, as the deterministic default and the fallback. */
|
||||
static GrpcLoadBalancerPicker roundRobin() {
|
||||
java.util.concurrent.atomic.AtomicInteger cursor =
|
||||
new java.util.concurrent.atomic.AtomicInteger();
|
||||
return candidates -> candidates.get(Math.floorMod(cursor.getAndIncrement(), candidates.size()));
|
||||
}
|
||||
}
|
||||
-76
@@ -1,76 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.discovery;
|
||||
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* Runs a custom picker and refuses to let it do something the resolver did not authorise.
|
||||
*
|
||||
* <p>Two rules. A picker may only return an endpoint the resolver supplied, because a picker that
|
||||
* can invent an address can send a request anywhere; and a picker that throws produces a
|
||||
* deterministic fallback rather than a failed call, because a picker bug should degrade the
|
||||
* balancing rather than the availability.
|
||||
*
|
||||
* <p>Weighted and load-aware pickers are not refused here, but the plan requires evidence before
|
||||
* they ship: {@link #requiresLoadEvidence} names which shapes those are.
|
||||
*/
|
||||
public final class GrpcLoadBalancerSafetyPolicy {
|
||||
|
||||
private final GrpcLoadBalancerPicker picker;
|
||||
private final GrpcLoadBalancerPicker fallback;
|
||||
|
||||
/** Wraps a custom picker with the platform's deterministic fallback. */
|
||||
public GrpcLoadBalancerSafetyPolicy(GrpcLoadBalancerPicker picker) {
|
||||
this(picker, GrpcLoadBalancerPicker.roundRobin());
|
||||
}
|
||||
|
||||
/** Wraps a custom picker with an explicit fallback. */
|
||||
public GrpcLoadBalancerSafetyPolicy(
|
||||
GrpcLoadBalancerPicker picker, GrpcLoadBalancerPicker fallback) {
|
||||
if (picker == null || fallback == null) {
|
||||
throw new IllegalArgumentException("a safety policy needs a picker and a fallback");
|
||||
}
|
||||
this.picker = picker;
|
||||
this.fallback = fallback;
|
||||
}
|
||||
|
||||
/** Picks an endpoint, or explains why none was chosen. */
|
||||
public GrpcLoadBalancerDecision pick(List<GrpcEndpointCandidate> candidates) {
|
||||
if (candidates == null) {
|
||||
throw new IllegalArgumentException("a candidate list is required");
|
||||
}
|
||||
List<GrpcEndpointCandidate> selectable =
|
||||
candidates.stream().filter(GrpcEndpointCandidate::selectable).toList();
|
||||
if (selectable.isEmpty()) {
|
||||
return GrpcLoadBalancerDecision.none(
|
||||
"no endpoint is healthy, connected, un-ejected and non-zero weight");
|
||||
}
|
||||
GrpcEndpointCandidate chosen;
|
||||
try {
|
||||
chosen = picker.pick(selectable);
|
||||
} catch (RuntimeException pickerFailure) {
|
||||
return GrpcLoadBalancerDecision.fallback(
|
||||
fallback.pick(selectable),
|
||||
"the custom picker threw ("
|
||||
+ pickerFailure.getClass().getSimpleName()
|
||||
+ "); falling back deterministically rather than failing the call");
|
||||
}
|
||||
if (chosen == null || !selectable.contains(chosen)) {
|
||||
return GrpcLoadBalancerDecision.fallback(
|
||||
fallback.pick(selectable),
|
||||
"the custom picker returned an endpoint the resolver did not supply; a picker that can "
|
||||
+ "invent an address can send a request anywhere");
|
||||
}
|
||||
return GrpcLoadBalancerDecision.picked(chosen, "chosen by the custom picker");
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether a picker of this shape needs performance, fairness and failover evidence before it
|
||||
* ships.
|
||||
*
|
||||
* @param loadAware whether the picker uses reported load or latency
|
||||
* @param weighted whether the picker uses endpoint weights
|
||||
*/
|
||||
public static boolean requiresLoadEvidence(boolean loadAware, boolean weighted) {
|
||||
return loadAware || weighted;
|
||||
}
|
||||
}
|
||||
-100
@@ -1,100 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.discovery;
|
||||
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import java.util.Optional;
|
||||
import java.util.Set;
|
||||
import java.util.regex.Pattern;
|
||||
|
||||
/**
|
||||
* What a custom resolver is allowed to say, and what it may never carry.
|
||||
*
|
||||
* <p>A resolver runs inside the channel and speaks to something outside the deployment. Everything
|
||||
* it can put into an update is therefore attacker-influenced in the worst case and
|
||||
* operator-influenced in the ordinary one, so the safety rules are about limiting what an update
|
||||
* can change: addresses and a validated service config, never a credential and never business
|
||||
* metadata.
|
||||
*/
|
||||
public final class GrpcResolverSafetyPolicy {
|
||||
|
||||
private static final Pattern AUTHORITY =
|
||||
Pattern.compile("[a-z0-9]([a-z0-9.-]*[a-z0-9])?(:\\d{1,5})?");
|
||||
|
||||
/** The top-level fields of a gRPC service config. Anything else is not policy. */
|
||||
private static final Set<String> SERVICE_CONFIG_FIELDS =
|
||||
Set.of(
|
||||
"loadBalancingConfig",
|
||||
"loadBalancingPolicy",
|
||||
"methodConfig",
|
||||
"retryThrottling",
|
||||
"healthCheckConfig");
|
||||
|
||||
private GrpcResolverSafetyPolicy() {}
|
||||
|
||||
/**
|
||||
* Every problem with an update, given what was last accepted.
|
||||
*
|
||||
* @param lastAccepted the newest snapshot already applied, or null when none has been
|
||||
* @return an empty list when the update is safe to apply
|
||||
*/
|
||||
public static List<String> violations(
|
||||
GrpcResolverUpdate update, GrpcEndpointSnapshot lastAccepted) {
|
||||
if (update == null) {
|
||||
throw new IllegalArgumentException("an update is required");
|
||||
}
|
||||
List<String> violations = new ArrayList<>();
|
||||
GrpcEndpointSnapshot snapshot = update.snapshot();
|
||||
|
||||
if (!AUTHORITY.matcher(snapshot.authority()).matches()) {
|
||||
violations.add(
|
||||
"authority '"
|
||||
+ snapshot.authority()
|
||||
+ "' is not a plain host or host:port; a resolver that can change the authority can "
|
||||
+ "change which certificate the channel accepts");
|
||||
}
|
||||
if (!snapshot.supersedes(lastAccepted)) {
|
||||
violations.add(
|
||||
"revision "
|
||||
+ snapshot.revision()
|
||||
+ " does not supersede the applied revision "
|
||||
+ (lastAccepted == null ? "none" : lastAccepted.revision())
|
||||
+ "; applying it would replace newer endpoints with older ones");
|
||||
}
|
||||
update.serviceConfig().ifPresent(config -> serviceConfigViolations(config, violations));
|
||||
return List.copyOf(violations);
|
||||
}
|
||||
|
||||
private static void serviceConfigViolations(Map<String, ?> config, List<String> violations) {
|
||||
if (!SERVICE_CONFIG_FIELDS.containsAll(config.keySet())) {
|
||||
violations.add(
|
||||
"the pushed service config has top-level fields outside "
|
||||
+ SERVICE_CONFIG_FIELDS.stream().sorted().toList()
|
||||
+ "; a resolver supplies addresses and policy, never authentication material");
|
||||
}
|
||||
Object methodConfig = config.get("methodConfig");
|
||||
if (methodConfig == null) {
|
||||
return;
|
||||
}
|
||||
if (!(methodConfig instanceof List<?> entries)
|
||||
|| !entries.stream().allMatch(entry -> entry instanceof Map<?, ?>)) {
|
||||
violations.add("the pushed service config's methodConfig is not a list of objects");
|
||||
return;
|
||||
}
|
||||
if (entries.stream()
|
||||
.map(entry -> (Map<?, ?>) entry)
|
||||
.anyMatch(
|
||||
entry -> entry.containsKey("retryPolicy") || entry.containsKey("hedgingPolicy"))) {
|
||||
violations.add(
|
||||
"the pushed service config sets retryPolicy or hedgingPolicy; retries and hedging are "
|
||||
+ "owned by the platform's method policy catalog, and a resolver that could turn them "
|
||||
+ "on could retry a non-idempotent method from outside the codebase");
|
||||
}
|
||||
}
|
||||
|
||||
/** The service config an update may contribute, once validated. */
|
||||
public static Optional<Map<String, ?>> acceptedServiceConfig(
|
||||
GrpcResolverUpdate update, GrpcEndpointSnapshot lastAccepted) {
|
||||
return violations(update, lastAccepted).isEmpty() ? update.serviceConfig() : Optional.empty();
|
||||
}
|
||||
}
|
||||
-43
@@ -1,43 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.discovery;
|
||||
|
||||
import java.util.Collections;
|
||||
import java.util.LinkedHashMap;
|
||||
import java.util.Map;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* A resolver's report: endpoints, and optionally the service config that goes with them.
|
||||
*
|
||||
* <p>The service config is optional and, when present, is validated as if a human had written it. A
|
||||
* resolver that can push retry policy is a resolver that can turn on retries for a non-idempotent
|
||||
* method from outside the codebase, and the fact that a control plane sent it is not evidence that
|
||||
* anyone reviewed it.
|
||||
*/
|
||||
public record GrpcResolverUpdate(
|
||||
GrpcEndpointSnapshot snapshot, Optional<Map<String, ?>> serviceConfig) {
|
||||
|
||||
/**
|
||||
* Requires a snapshot and the Optional. The service config is the parsed JSON object, the same
|
||||
* {@code Map<String, ?>} shape gRPC's {@code NameResolver.Helper.parseServiceConfig} takes; it is
|
||||
* copied so it cannot change between validation and delivery.
|
||||
*/
|
||||
public GrpcResolverUpdate {
|
||||
if (snapshot == null || serviceConfig == null) {
|
||||
throw new IllegalArgumentException("a resolver update carries a snapshot and the Optional");
|
||||
}
|
||||
serviceConfig.ifPresent(
|
||||
config -> {
|
||||
if (config.isEmpty()) {
|
||||
throw new IllegalArgumentException(
|
||||
"a present service config must not be empty; absent and empty are different states");
|
||||
}
|
||||
});
|
||||
serviceConfig =
|
||||
serviceConfig.map(config -> Collections.unmodifiableMap(new LinkedHashMap<>(config)));
|
||||
}
|
||||
|
||||
/** An update with endpoints only. */
|
||||
public static GrpcResolverUpdate endpointsOnly(GrpcEndpointSnapshot snapshot) {
|
||||
return new GrpcResolverUpdate(snapshot, Optional.empty());
|
||||
}
|
||||
}
|
||||
-47
@@ -1,47 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.edition;
|
||||
|
||||
import java.util.Set;
|
||||
|
||||
/**
|
||||
* Where Edition 2024 may be used, and where it may not.
|
||||
*
|
||||
* <p>Module-level opt-in, and never for a public service without a promotion decision. The reason
|
||||
* is that an edition change is invisible to the schema's owner and consequential for its consumers:
|
||||
* the wire bytes are usually identical, so nothing fails locally, and the breakage appears in
|
||||
* whichever consumer's generator handles the edition's features differently.
|
||||
*/
|
||||
public record GrpcEdition2024Policy(
|
||||
Set<String> optedInModules, Set<String> publicServices, boolean promotionApproved) {
|
||||
|
||||
/** The edition this policy governs. */
|
||||
public static final String EDITION = "2024";
|
||||
|
||||
/** Copies both sets and refuses an approval nobody recorded. */
|
||||
public GrpcEdition2024Policy {
|
||||
if (optedInModules == null || publicServices == null) {
|
||||
throw new IllegalArgumentException("an edition policy states both sets");
|
||||
}
|
||||
optedInModules = Set.copyOf(optedInModules);
|
||||
publicServices = Set.copyOf(publicServices);
|
||||
}
|
||||
|
||||
/** The default: nothing opted in, no promotion. */
|
||||
public static GrpcEdition2024Policy notAdopted() {
|
||||
return new GrpcEdition2024Policy(Set.of(), Set.of(), false);
|
||||
}
|
||||
|
||||
/** Whether {@code moduleId} may use Edition 2024 schema sources. */
|
||||
public boolean allowedIn(String moduleId) {
|
||||
return optedInModules.contains(moduleId);
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether {@code serviceName} may move onto Edition 2024.
|
||||
*
|
||||
* <p>False for any public service until a promotion is approved, regardless of module opt-in: the
|
||||
* opt-in is a build decision and the promotion is a consumer-migration decision.
|
||||
*/
|
||||
public boolean serviceMayMove(String serviceName) {
|
||||
return !publicServices.contains(serviceName) || promotionApproved;
|
||||
}
|
||||
}
|
||||
-28
@@ -1,28 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.edition;
|
||||
|
||||
/**
|
||||
* The four independent things that have to be true before an edition is usable, tracked separately.
|
||||
*
|
||||
* <p>Separately, because they land at different times and in different projects. An edition can be
|
||||
* released by the specification while {@code protoc} does not emit it, or emitted while Buf cannot
|
||||
* lint it, or lintable while the Java runtime does not implement its features. A single "supported
|
||||
* yes/no" flag collapses four different waiting states into one, and the answer to "what are we
|
||||
* waiting for" is then nobody's.
|
||||
*/
|
||||
public enum GrpcEdition2026Status {
|
||||
/** Nothing is known yet. */
|
||||
UNKNOWN,
|
||||
/** Announced or drafted, not released. */
|
||||
DRAFT,
|
||||
/** Released by the specification. */
|
||||
RELEASED,
|
||||
/** Supported by the toolchain component in question. */
|
||||
SUPPORTED,
|
||||
/** Explicitly not supported, and not expected to be. */
|
||||
UNSUPPORTED;
|
||||
|
||||
/** Whether this status permits use. */
|
||||
public boolean usable() {
|
||||
return this == SUPPORTED;
|
||||
}
|
||||
}
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user