Merge pull request 'refactor!: 확인 리뷰 수정과 저장소 구조·문서 체계 정리를 합친다' (#2) from refactor/maturity-review-2026-11 into main
This commit is contained in:
@@ -5,8 +5,8 @@ registry entries with `"build": "optional-grpc"`) are kept out of the main multi
|
||||
internal project dependencies while making their configuration opt-in.
|
||||
|
||||
```bash
|
||||
./gradlew -p optional-platforms ci
|
||||
./gradlew -p optional-platforms :grpc:grpc-testkit:grpcInProcessContractTest
|
||||
./gradlew -p platforms/optional-build ci
|
||||
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcInProcessContractTest
|
||||
```
|
||||
|
||||
`adapter:inbound:grpc` remains in the main application build because it is an application adapter;
|
||||
|
||||
+2
-2
@@ -84,9 +84,9 @@ tasks.register('releaseCheck') {
|
||||
}
|
||||
|
||||
// The stages this build's strict lanes may belong to, executed by workflows as
|
||||
// `./gradlew -p optional-platforms <stage>` from `src`. A command counts when it starts in this
|
||||
// `./gradlew -p platforms/optional-build <stage>` from `src`. A command counts when it starts in this
|
||||
// directory (working-directory joined with -p), which the plugin reads from where this build is.
|
||||
strictLaneStages {
|
||||
stage ':ci', ':integrationCheck', ':performanceCheck', ':releaseCheck'
|
||||
workflowDirectory = layout.projectDirectory.dir('../../.github/workflows')
|
||||
workflowDirectory = layout.projectDirectory.dir('../../../.github/workflows')
|
||||
}
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-30
|
||||
- 요약: gRPC 플랫폼을 adapter leaf 하나가 아니라 registry에 등록한 family로 낸다는 결정이다.
|
||||
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-GRPC-001: The gRPC platform ships as a registered family, not as one adapter leaf
|
||||
|
||||
- Status: accepted
|
||||
|
||||
@@ -1,3 +1,13 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 대체됨
|
||||
- 작성일: 2026-08-30
|
||||
- 요약: protoc와 Buf CLI 없이 스키마를 관리하려던 결정이다. 2026-09-28 Gradle protobuf plugin과 buf로 바뀌었다.
|
||||
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
|
||||
- 대체됨: `docs/capability-status.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-GRPC-002: Schema governance runs without protoc and without the Buf CLI
|
||||
|
||||
- Status: **superseded (2026-09-28)** by owner decision 18 of the 2026-09-25 review follow-up
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-30
|
||||
- 요약: 전송·업무·스트림 증거를 서로 대신하지 않는 세 축으로 본다는 결정이다.
|
||||
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-GRPC-003: Transport, business and stream evidence are three axes, and none implies another
|
||||
|
||||
- Status: accepted
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-30
|
||||
- 요약: 재시도 주인은 하나이고 키가 있는 변경은 영속 원장이 필요하다는 결정이다.
|
||||
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-GRPC-004: One retry owner, and keyed mutations need a durable ledger
|
||||
|
||||
- Status: accepted
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-30
|
||||
- 요약: 서버 스트림은 writer 하나, 제한된 큐, 추측하지 않는 resume로 다룬다는 결정이다.
|
||||
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-GRPC-005: One writer per stream, a bounded queue, and resume that refuses to guess
|
||||
|
||||
- Status: accepted
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-31
|
||||
- 요약: Stable discovery는 DNS와 정적 목록이고 Kubernetes에서는 누가 부하를 나누는지 profile이 정한다는 결정이다.
|
||||
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-GRPC-006: Stable discovery is DNS and static, and a Kubernetes profile names who balances
|
||||
|
||||
- Status: accepted
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 채택
|
||||
- 작성일: 2026-08-30
|
||||
- 요약: gRPC 고급 기능마다 따로 플래그·등급·승격 기준을 둔다는 결정이다.
|
||||
- 현재 정본: `docs/compatibility/grpc-advanced-support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# ADR-GRPC-ADV-001: Each advanced capability has its own flag, its own grade and its own promotion
|
||||
|
||||
- Status: accepted
|
||||
|
||||
@@ -1,3 +1,12 @@
|
||||
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
||||
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
|
||||
|
||||
- 상태: 확인 안 함
|
||||
- 작성일: 2026-08-30
|
||||
- 요약: 타입 안전 gRPC 실행 플랫폼 계획을 이 저장소의 구조와 게이트에 맞춘 설계다.
|
||||
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
|
||||
<!-- 머리 블록 끝 -->
|
||||
|
||||
# 타입 안전 gRPC 실행 플랫폼 — 이 저장소 규약으로의 어댑팅 설계
|
||||
|
||||
두 계획 문서를 이 저장소(`ca-skeleton`)의 실제 구조·정책·빌드 게이트에 맞춰 실행 가능한 형태로
|
||||
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
# optional-platforms is a build of its own (`./gradlew -p optional-platforms ...`), and Gradle reads
|
||||
# optional-platforms is a build of its own (`./gradlew -p platforms/optional-build ...`), and Gradle reads
|
||||
# gradle.properties from the build's root directory only, so src/gradle.properties never reached it:
|
||||
# the optional build ran serially and without the build cache (review 2026-11-01 08-06).
|
||||
# The values and their reasons are src/gradle.properties'. settings.gradle fails the build when the
|
||||
|
||||
@@ -18,11 +18,11 @@ grpc:* → grpc-advanced:* (금지 — registry가 거부한다)
|
||||
`grpc-spring-boot-starter`의 registry 엔트리에는 어떤 advanced id도 없다.
|
||||
`verifyCleanArchitectureDependencies`가 build time에 이 규칙을 강제한다. runtime 검사는 없다.
|
||||
|
||||
### 공용 다이제스트 헬퍼를 복사해 두는 이유 (review 2026-11-01 01-11)
|
||||
### 공용 다이제스트 헬퍼를 복사해 두는 이유
|
||||
|
||||
`grpc-advanced`(`GrpcDiagnosticsRedactor`)는 SHA-256 계산을 자기 안에 둔다. 의존 방향이
|
||||
`grpc-advanced:* → grpc:*`로 닫혀 있고 `shared-contract` edge가 없는 것은 의도다. `grpc/CLAUDE.md`의
|
||||
같은 절과 이유가 같다(vendored 플랫폼, MSG-023 §6.2와 같은 배치).
|
||||
같은 절과 이유가 같다(vendored 플랫폼, messaging family와 같은 배치).
|
||||
|
||||
## Capability grade와 feature flag
|
||||
|
||||
@@ -61,7 +61,7 @@ property key는 `app.grpc.advanced.<capability>.enabled`이고 전부 기본 off
|
||||
|
||||
승격 증거는 capability마다 따로 판단한다. 공유 증거였다면 하나를 승격할 때 같은 시점에 측정된 다른
|
||||
것들이 함께 승격된다. 이 규칙을 코드로 옮겨 두었던 `GrpcAdvancedPromotionGate`는 자기 테스트 말고
|
||||
호출처가 없어 삭제했다(리뷰 2026-09-24 S5-lead-4). 지금은 `docs/runbooks/grpc-advanced-capabilities.md`의
|
||||
호출처가 없어 2026-09-25 리뷰 후속 작업에서 삭제했다. 지금은 `docs/runbooks/grpc-advanced-capabilities.md`의
|
||||
리뷰 규칙이다.
|
||||
|
||||
승격 문턱은 두 개다: `ADVANCED_STABLE`은 7일 soak + 전체 증거, Stable default는 30일 soak. 두 번째가
|
||||
|
||||
+15
-15
@@ -1,7 +1,7 @@
|
||||
# grpc — local authority for the gRPC platform family
|
||||
|
||||
이 문서는 `grpc:*` family의 **local authority**다. gRPC platform은 기본 application build와 분리된
|
||||
`src/optional-platforms` build가 소유한다. 여기서 정하는 것은 family별 framework 규칙, 증거 등급,
|
||||
`src/platforms/optional-build` build가 소유한다. 여기서 정하는 것은 family별 framework 규칙, 증거 등급,
|
||||
Stable 범위의 경계와 application에 채택될 때 필요한 계약이다.
|
||||
|
||||
Root 정책(`CLAUDE.md` / `AGENTS.md`)과 충돌하면 root가 이긴다.
|
||||
@@ -11,7 +11,7 @@ Root 정책(`CLAUDE.md` / `AGENTS.md`)과 충돌하면 root가 이긴다.
|
||||
`adapter:inbound:grpc`를 통해 라이브러리로서 도달한다.
|
||||
|
||||
설계 근거와 원본 계획 대비 deviation은
|
||||
[docs/superpowers/specs/2026-08-30-grpc-platform-adaptation-design.md](../../docs/superpowers/specs/2026-08-30-grpc-platform-adaptation-design.md)가 SSOT다.
|
||||
[docs/design/2026-08-30-grpc-platform-adaptation-design.md](../../../docs/design/2026-08-30-grpc-platform-adaptation-design.md)가 SSOT다.
|
||||
|
||||
## Family와 framework 규칙
|
||||
|
||||
@@ -41,13 +41,13 @@ server profile·named channel profile·method size profile·method policy 기본
|
||||
`caskeleton.grpc.common.v1.generated` — 손으로 쓴 `dev.caskeleton`과 겹치지 않는다). 템플릿을 재사용할
|
||||
때 바꾸는 방법은 `AGENTS.md` 「템플릿 재사용 체크리스트」에 있다.
|
||||
|
||||
### 공용 다이제스트 헬퍼를 복사해 두는 이유 (review 2026-11-01 01-11)
|
||||
### 공용 다이제스트 헬퍼를 복사해 두는 이유
|
||||
|
||||
`grpc-runtime`(`GrpcRequestFingerprint`, `GrpcResumeTokenCodec`)은 SHA-256·HMAC-SHA256 계산을 자기
|
||||
안에 둔다. 템플릿의 `shared-contract` `digest/Sha256`·`HmacSha256`을 쓰지 않는 것은 의도다. 이
|
||||
family는 optional build에 있는 vendored 플랫폼이고 registry edge는 `grpc:*` 안에서만 닫힌다(위 표).
|
||||
`shared-contract` edge를 주면 플랫폼이 템플릿 계약 leaf에 묶여 따로 떼어 쓸 수 없게 된다 — messaging
|
||||
family가 같은 이유로 고른 배치(MSG-023 §6.2)와 같다. 복사본을 고칠 때는 `shared-contract`의 정본과
|
||||
family가 같은 이유로 고른 배치(2026-08-14 messaging 모듈 리뷰 뒤 소유자가 정함)와 같다. 복사본을 고칠 때는 `shared-contract`의 정본과
|
||||
같은 규칙인지 함께 본다.
|
||||
|
||||
## 증거 등급 — testkit이 하나의 leaf인 이유
|
||||
@@ -86,7 +86,7 @@ capability flag 뒤에 있다. `GrpcPlatformStartupValidator`가 Stable catalog
|
||||
|
||||
`grpc:*`와 `grpc-advanced:*`는 기본 `ca-skeleton` settings에 include되지 않는다. 따라서 일반
|
||||
`:app-bootstrap:build`는 이 project들을 configure하지 않는다(목록은 registry의 `"build": "optional-grpc"`). 플랫폼 자체는
|
||||
`./gradlew -p optional-platforms ci`로 검증하고, application runtime에 실제 채택하려면 composition root가
|
||||
`./gradlew -p platforms/optional-build ci`로 검증하고, application runtime에 실제 채택하려면 composition root가
|
||||
명시적으로 dependency를 가져오는 별도 변경이 필요하다.
|
||||
|
||||
런타임 포함 여부와 qualification은 별개다. in-process·Netty·fault lane이 통과해도 실제 배포 환경의
|
||||
@@ -95,7 +95,7 @@ soak/performance baseline을 자동으로 의미하지 않는다. 지원 범위
|
||||
|
||||
## application이 이 family에 도달하는 경로
|
||||
|
||||
`messaging:*`의 MSG-015(bridge 부재)를 반복하지 않는 것이 이 family의 목표다. 계약상의 경로는
|
||||
`messaging:*`가 겪은 bridge 부재(2026-08-14 messaging 모듈 리뷰)를 반복하지 않는 것이 이 family의 목표다. 계약상의 경로는
|
||||
|
||||
```text
|
||||
application-owned port → adapter:inbound:grpc (typed service adapter) → :grpc:grpc-runtime SPI
|
||||
@@ -115,11 +115,11 @@ focused test는 registry의 `gradle_path`에서 파생한다.
|
||||
|
||||
```bash
|
||||
cd src
|
||||
./gradlew -p optional-platforms :grpc:<leaf>:test --console=plain
|
||||
./gradlew -p optional-platforms :grpc:grpc-testkit:grpcInProcessContractTest --console=plain
|
||||
./gradlew -p optional-platforms :grpc:grpc-testkit:grpcNettyContractTest --console=plain
|
||||
./gradlew -p optional-platforms :grpc:grpc-testkit:grpcFaultTest --console=plain
|
||||
./gradlew -p optional-platforms :grpc:grpc-testkit:grpcPerformanceTest --console=plain
|
||||
./gradlew -p platforms/optional-build :grpc:<leaf>:test --console=plain
|
||||
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcInProcessContractTest --console=plain
|
||||
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcNettyContractTest --console=plain
|
||||
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcFaultTest --console=plain
|
||||
./gradlew -p platforms/optional-build :grpc:grpc-testkit:grpcPerformanceTest --console=plain
|
||||
```
|
||||
|
||||
## 금지
|
||||
@@ -164,9 +164,9 @@ These keys are not in `docs/registries/env-keys.yaml`: no `app.grpc.platform.*`
|
||||
optional build is not part of the shipped runtime. They join the registry when a composition root
|
||||
adopts the platform.
|
||||
|
||||
**Why the starter assembles the interceptor (03-11 (b)), and not (a).** The review proposed (a):
|
||||
delete the flag and judge by whether a ledger bean exists. (b) was chosen and is recorded in
|
||||
ADR-GRPC-004 (re-review 2026-11-03, RR-02-07): the flag stays and means what it says — when true, the
|
||||
**Why the starter assembles the interceptor (option (b)), and not (a).** The 2026-11-01 maturity review proposed (a):
|
||||
delete the flag and judge by whether a ledger bean exists. (b) was chosen on 2026-11-03 and is recorded in
|
||||
ADR-GRPC-004: the flag stays and means what it says — when true, the
|
||||
decision function is assembled and its TTL comes from configuration. (a) would have removed the false promise but left every adopter to rebuild the same
|
||||
assembly and TTL validation by hand; (b) keeps that in one place. The interceptor bean has no
|
||||
`@ConditionalOnMissingBean` on purpose: a replacement would silently ignore `operation-ledger-claim-ttl`.
|
||||
@@ -182,7 +182,7 @@ its typed service adapter: `decide(...)` before the mutation, `recordCommit(...)
|
||||
transaction, `recordFailure(...)` on a terminal failure. Both record calls take the `GrpcClaimToken`
|
||||
the `PROCEED` decision carried: a commit by an attempt whose claim was taken over is refused (its
|
||||
transaction rolls back) and its failure is ignored, so a slow owner cannot write over the attempt that
|
||||
took its claim (re-review RR-02-04, ADR-GRPC-004).
|
||||
took its claim (ADR-GRPC-004).
|
||||
|
||||
**Purge scheduling is the adopter's.** `GrpcOperationLedgerRetention.purgeExpired(now)` deletes
|
||||
expired finished rows in bounded batches (500 per statement) until a batch comes back short. The
|
||||
|
||||
@@ -4,9 +4,9 @@
|
||||
# build.gradle) owns compilation. CI runs both `buf lint` and `buf breaking` from this directory —
|
||||
# see the `grpc-proto-buf` job in .github/workflows/ci-quality-gates.yml.
|
||||
#
|
||||
# cd src/grpc/grpc-contract
|
||||
# cd src/platforms/grpc/grpc-contract
|
||||
# buf lint
|
||||
# buf breaking --against '<baseline>#subdir=src/grpc/grpc-contract'
|
||||
# buf breaking --against '<baseline>#subdir=src/platforms/grpc/grpc-contract'
|
||||
#
|
||||
# No dependencies: the only imports are protoc's own well-known types (google/protobuf/*.proto).
|
||||
version: v2
|
||||
|
||||
@@ -17,16 +17,20 @@ configurations {
|
||||
}
|
||||
|
||||
// One definition of a versioned migration file and of Flyway's order for both builds (re-review
|
||||
// README 12, r6-b; r9). This build cannot depend on persistence-jpa's testkit, so the one file the
|
||||
// ledger lanes need from it — VersionedMigrationFiles, JDK only — is copied from there into this
|
||||
// lane's sources at build time instead of being kept here as a second copy that could drift.
|
||||
// README 12, r6-b; r9), and one concurrent index check (round 7, RR7-03-01). This build cannot
|
||||
// depend on persistence-jpa's testkit, so the files the ledger lanes need from it, all JDK only —
|
||||
// VersionedMigrationFiles, and ConcurrentIndexMigrationInspector with the MigrationResource it
|
||||
// takes — are copied from there into this lane's sources at build time instead of being kept here
|
||||
// as second copies that could drift.
|
||||
// Rejected: that testkit directory as a source root of this lane (Spotless refuses a target outside
|
||||
// this project's directory, and the include filter would cover this lane's own sources too), a
|
||||
// dependency on the main build (it would pull the whole main build into this one), and a test that
|
||||
// compares two copies (two definitions stay, and the test would have to parse Java source text).
|
||||
def sharedMigrationFileSources = tasks.register('sharedMigrationFileSources', Sync) {
|
||||
from(file('../../adapter/outbound/persistence-jpa/src/testFixtures/java')) {
|
||||
from(file('../../../adapter/outbound/persistence-jpa/src/testFixtures/java')) {
|
||||
include 'dev/caskeleton/adapter/outbound/persistence/testkit/migration/VersionedMigrationFiles.java'
|
||||
include 'dev/caskeleton/adapter/outbound/persistence/testkit/migration/ConcurrentIndexMigrationInspector.java'
|
||||
include 'dev/caskeleton/adapter/outbound/persistence/testkit/migration/MigrationResource.java'
|
||||
}
|
||||
into(layout.buildDirectory.dir('generated/sources/sharedMigrationFiles/java'))
|
||||
}
|
||||
|
||||
+170
-8
@@ -2,21 +2,30 @@ package dev.caskeleton.grpc.ledger;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.catchThrowable;
|
||||
import static org.junit.jupiter.params.provider.Arguments.arguments;
|
||||
|
||||
import dev.caskeleton.adapter.outbound.persistence.testkit.migration.ConcurrentIndexMigrationInspector;
|
||||
import dev.caskeleton.adapter.outbound.persistence.testkit.migration.MigrationResource;
|
||||
import java.io.IOException;
|
||||
import java.sql.Connection;
|
||||
import java.sql.ResultSet;
|
||||
import java.sql.SQLException;
|
||||
import java.sql.Statement;
|
||||
import java.time.Duration;
|
||||
import java.util.ArrayList;
|
||||
import java.util.Collection;
|
||||
import java.util.LinkedHashMap;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import java.util.concurrent.Executors;
|
||||
import java.util.concurrent.ScheduledExecutorService;
|
||||
import java.util.concurrent.ScheduledFuture;
|
||||
import java.util.concurrent.TimeUnit;
|
||||
import java.util.stream.Stream;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
import org.junit.jupiter.params.ParameterizedTest;
|
||||
import org.junit.jupiter.params.provider.Arguments;
|
||||
import org.junit.jupiter.params.provider.MethodSource;
|
||||
import org.postgresql.ds.PGSimpleDataSource;
|
||||
import org.testcontainers.junit.jupiter.Container;
|
||||
@@ -38,9 +47,18 @@ import org.testcontainers.postgresql.PostgreSQLContainer;
|
||||
* <p>A file Flyway runs outside a transaction — one holding {@code CREATE INDEX CONCURRENTLY} or
|
||||
* another statement on Flyway's list, or with {@code executeInTransaction=false} beside it — is not
|
||||
* one this test can judge: run here in a transaction, PostgreSQL refuses it ({@code 25001}), and no
|
||||
* {@code SET LOCAL} would bound it in a deploy anyway. Name such a file as an exception in this
|
||||
* test, and keep it alone in its migration ({@code docs/jpa/migration-guide.md}, "Concurrent index
|
||||
* builds"; re-review 2026-11-03 round 6, RR6-03-05).
|
||||
* {@code SET LOCAL} would bound it in a deploy anyway. The one such file the ledger may have is a
|
||||
* concurrent index build, and it goes in {@link #RUN_OUTSIDE_A_TRANSACTION} with the reason it
|
||||
* needs to: the lock-wait case leaves it out, and {@code
|
||||
* everyMigrationListedAsRunningOutsideATransactionIsOneConcurrentIndexBuildThatSaysSo} holds it to
|
||||
* the guide instead — a concurrent index statement, alone in its file, with {@code
|
||||
* executeInTransaction=false} beside it ({@code docs/jpa/migration-guide.md}, "Concurrent index
|
||||
* builds"). The list takes nothing else: a {@code VACUUM FULL} or another locking statement that
|
||||
* cannot run in a transaction does not belong in a migration at all ("Bound the lock wait"). The
|
||||
* migrations before the one under test are applied one file at a time ({@link
|
||||
* GrpcOperationLedgerMigrations#before(String)}), so a listed file is no obstacle to a later one.
|
||||
* Re-review 2026-11-03 round 6, RR6-03-05; round 7, RR7-03-01: the message pointed at a list this
|
||||
* test did not have.
|
||||
*
|
||||
* <p>Every migration after V001 is held to this, read from the tree itself ({@link
|
||||
* GrpcOperationLedgerMigrations#inOrder()}), so a V004 is checked without anyone naming it here.
|
||||
@@ -66,9 +84,25 @@ class GrpcOperationLedgerMigrationLockWaitIT {
|
||||
.withUsername("grpc")
|
||||
.withPassword("grpc");
|
||||
|
||||
/** Every ledger migration after V001, the one that creates the ledger. */
|
||||
/**
|
||||
* The ledger migrations Flyway runs outside a transaction, by file name, each with why it has to:
|
||||
* a concurrent index build that would stop the ledger's writes if it were built in a transaction.
|
||||
* Empty while the tree has none.
|
||||
*/
|
||||
static final Map<String, String> RUN_OUTSIDE_A_TRANSACTION = Map.of();
|
||||
|
||||
/** The file name the list check's fixture cases list. */
|
||||
private static final String LISTED = "V004__ledger_index.sql";
|
||||
|
||||
/** A concurrent index build alone, as the guide asks such a file to be. */
|
||||
private static final String CONCURRENT_BUILD =
|
||||
"CREATE INDEX CONCURRENTLY ix_ledger_note ON grpc_operation_ledger (note);\n";
|
||||
|
||||
/** Every ledger migration after V001, the one that creates the ledger, that runs in one. */
|
||||
static Stream<String> migrationsAfterTheFirst() throws IOException {
|
||||
return GrpcOperationLedgerMigrations.inOrder().stream().skip(1);
|
||||
return GrpcOperationLedgerMigrations.inOrder().stream()
|
||||
.skip(1)
|
||||
.filter(migration -> !RUN_OUTSIDE_A_TRANSACTION.containsKey(migration));
|
||||
}
|
||||
|
||||
@ParameterizedTest
|
||||
@@ -80,7 +114,9 @@ class GrpcOperationLedgerMigrationLockWaitIT {
|
||||
Statement statement = setup.createStatement()) {
|
||||
// given
|
||||
statement.execute("DROP TABLE IF EXISTS grpc_operation_ledger");
|
||||
statement.execute(GrpcOperationLedgerMigrations.before(migration));
|
||||
for (String script : GrpcOperationLedgerMigrations.before(migration)) {
|
||||
statement.execute(script);
|
||||
}
|
||||
String schemaBefore = schema(statement);
|
||||
|
||||
// when
|
||||
@@ -100,13 +136,130 @@ class GrpcOperationLedgerMigrationLockWaitIT {
|
||||
ACTIVE_SQL_TRANSACTION.equals(attempt.sqlState())
|
||||
? ". PostgreSQL refused it inside a transaction (25001): Flyway runs such a file"
|
||||
+ " outside one, where SET LOCAL bounds nothing, so it is no case for this"
|
||||
+ " test. Keep it alone in its migration and name it as an exception here"
|
||||
+ " (\"Concurrent index builds\")"
|
||||
+ " test. If it is a concurrent index build, keep it alone in its migration"
|
||||
+ " with executeInTransaction=false beside it and add it, with the reason, to"
|
||||
+ " RUN_OUTSIDE_A_TRANSACTION in this test (\"Concurrent index builds\");"
|
||||
+ " anything else that cannot run in a transaction does not belong in a"
|
||||
+ " migration (\"Bound the lock wait\")"
|
||||
: "")
|
||||
.containsExactly(LOCK_NOT_AVAILABLE, true, schemaBefore);
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName(
|
||||
"트랜잭션 밖에서 도는 예외 목록의 ledger 마이그레이션은 트리에 있고, 동시 인덱스 문장 하나뿐이며, executeInTransaction=false를 적었다")
|
||||
void everyMigrationListedAsRunningOutsideATransactionIsOneConcurrentIndexBuildThatSaysSo()
|
||||
throws IOException {
|
||||
// given
|
||||
Map<String, LedgerMigration> tree = new LinkedHashMap<>();
|
||||
for (String migration : GrpcOperationLedgerMigrations.inOrder()) {
|
||||
tree.put(
|
||||
migration,
|
||||
new LedgerMigration(
|
||||
GrpcOperationLedgerMigrations.named(migration),
|
||||
GrpcOperationLedgerMigrations.executeInTransaction(migration)));
|
||||
}
|
||||
|
||||
// when
|
||||
List<String> refused = refusalsOf(RUN_OUTSIDE_A_TRANSACTION.keySet(), tree);
|
||||
|
||||
// then
|
||||
assertThat(refused).isEmpty();
|
||||
}
|
||||
|
||||
@ParameterizedTest
|
||||
@MethodSource("listedFilesTheGuideDoesNotAllow")
|
||||
@DisplayName(
|
||||
"예외 목록 검사는 트리에 없는 파일, 동시 인덱스 문장이 없는 파일, executeInTransaction=false가 없는 파일, 다른 문장과 섞인 파일을 이유와 함께 거부한다")
|
||||
void theListCheckRefusesAFileTheGuideDoesNotAllow(
|
||||
String listed, Map<String, LedgerMigration> tree, String reason) {
|
||||
// when
|
||||
List<String> refused = refusalsOf(List.of(listed), tree);
|
||||
|
||||
// then
|
||||
assertThat(refused).singleElement().asString().contains(listed).contains(reason);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("예외 목록 검사는 executeInTransaction=false를 곁에 둔, 동시 인덱스 문장 하나뿐인 파일을 받는다")
|
||||
void theListCheckAcceptsAConcurrentIndexBuildAloneThatSaysSo() {
|
||||
// given
|
||||
Map<String, LedgerMigration> tree =
|
||||
Map.of(LISTED, new LedgerMigration(CONCURRENT_BUILD, false));
|
||||
|
||||
// when
|
||||
List<String> refused = refusalsOf(List.of(LISTED), tree);
|
||||
|
||||
// then
|
||||
assertThat(refused).isEmpty();
|
||||
}
|
||||
|
||||
/** One listed file for each way the guide's rule can be broken, and the reason it is refused. */
|
||||
static Stream<Arguments> listedFilesTheGuideDoesNotAllow() {
|
||||
return Stream.of(
|
||||
arguments(LISTED, Map.of(), "is not a migration in the ledger tree"),
|
||||
arguments(
|
||||
LISTED,
|
||||
Map.of(
|
||||
LISTED,
|
||||
new LedgerMigration(
|
||||
"ALTER TABLE grpc_operation_ledger ADD COLUMN note TEXT;\n", false)),
|
||||
"holds no concurrent index statement"),
|
||||
arguments(
|
||||
LISTED,
|
||||
Map.of(LISTED, new LedgerMigration(CONCURRENT_BUILD, true)),
|
||||
"must set executeInTransaction=false"),
|
||||
arguments(
|
||||
LISTED,
|
||||
Map.of(
|
||||
LISTED,
|
||||
new LedgerMigration("SET LOCAL lock_timeout = '5s';\n" + CONCURRENT_BUILD, false)),
|
||||
"mixes a concurrent index statement with other statements"));
|
||||
}
|
||||
|
||||
/**
|
||||
* Why each migration listed as running outside a transaction may not: one reason per file
|
||||
* refused, none when every listed file is in the tree and is a concurrent index statement alone
|
||||
* in its file with {@code executeInTransaction=false} beside it ("Concurrent index builds"). The
|
||||
* list test runs it over {@link #RUN_OUTSIDE_A_TRANSACTION} and the tree, and the fixture cases
|
||||
* hold it to every refusal while that list is empty (re-review 2026-11-03 round 8, RR8-03-04: its
|
||||
* loop never ran, so a broken check passed).
|
||||
*
|
||||
* @param listed the file names listed
|
||||
* @param tree every migration in the tree, by file name
|
||||
* @return the reasons, in the order the files are listed
|
||||
*/
|
||||
static List<String> refusalsOf(Collection<String> listed, Map<String, LedgerMigration> tree) {
|
||||
ConcurrentIndexMigrationInspector inspector = new ConcurrentIndexMigrationInspector();
|
||||
List<String> refused = new ArrayList<>();
|
||||
for (String migration : listed) {
|
||||
LedgerMigration file = tree.get(migration);
|
||||
if (file == null) {
|
||||
refused.add(migration + " is not a migration in the ledger tree");
|
||||
continue;
|
||||
}
|
||||
MigrationResource resource = new MigrationResource(migration, file.sql());
|
||||
if (!inspector.containsConcurrentIndexStatement(resource.sql())) {
|
||||
refused.add(
|
||||
migration
|
||||
+ " holds no concurrent index statement; only a concurrent index build may run"
|
||||
+ " outside a transaction");
|
||||
continue;
|
||||
}
|
||||
Throwable thrown =
|
||||
catchThrowable(
|
||||
() -> {
|
||||
inspector.validate(resource, file.executeInTransaction());
|
||||
inspector.requireIsolatedStatement(resource);
|
||||
});
|
||||
if (thrown != null) {
|
||||
refused.add(thrown.getMessage());
|
||||
}
|
||||
}
|
||||
return refused;
|
||||
}
|
||||
|
||||
/** Runs the migration in one transaction while another one holds a write to the ledger. */
|
||||
private static Attempt whileAWriterHolds(PGSimpleDataSource dataSource, String migration)
|
||||
throws SQLException {
|
||||
@@ -170,6 +323,15 @@ class GrpcOperationLedgerMigrationLockWaitIT {
|
||||
return dataSource;
|
||||
}
|
||||
|
||||
/**
|
||||
* A ledger migration as the list check reads it.
|
||||
*
|
||||
* @param sql the script
|
||||
* @param executeInTransaction whether Flyway runs it in a transaction, as {@link
|
||||
* GrpcOperationLedgerMigrations#executeInTransaction} reads it from the file beside it
|
||||
*/
|
||||
record LedgerMigration(String sql, boolean executeInTransaction) {}
|
||||
|
||||
/** What the migration did while the writer held the ledger. */
|
||||
private record Attempt(Throwable thrown, Duration took) {
|
||||
|
||||
|
||||
+34
-8
@@ -3,12 +3,16 @@ package dev.caskeleton.grpc.ledger;
|
||||
import dev.caskeleton.adapter.outbound.persistence.testkit.migration.VersionedMigrationFiles;
|
||||
import java.io.IOException;
|
||||
import java.io.InputStream;
|
||||
import java.io.Reader;
|
||||
import java.nio.charset.StandardCharsets;
|
||||
import java.nio.file.Files;
|
||||
import java.nio.file.Path;
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.Properties;
|
||||
|
||||
/**
|
||||
* The ledger's Flyway scripts in version order, as one SQL text for a test database.
|
||||
* The ledger's Flyway scripts in version order, one SQL text per file for a test database.
|
||||
*
|
||||
* <p>One list for every PostgreSQL lane, so a new migration is applied by all of them or by none.
|
||||
* The list is the tree on disk, not a copy of it: a hand-kept list let a V004 that nobody added to
|
||||
@@ -38,21 +42,26 @@ final class GrpcOperationLedgerMigrations {
|
||||
.toList();
|
||||
}
|
||||
|
||||
/** Every migration's SQL, concatenated in version order. */
|
||||
static String all() throws IOException {
|
||||
/** Every migration's SQL in version order, one script per file. */
|
||||
static List<String> all() throws IOException {
|
||||
return before(null);
|
||||
}
|
||||
|
||||
/** The SQL of every migration before the one named, concatenated in version order. */
|
||||
static String before(String fileName) throws IOException {
|
||||
StringBuilder sql = new StringBuilder();
|
||||
/**
|
||||
* The SQL of every migration before the one named, in version order, one script per file. Run
|
||||
* each as a statement of its own, the way Flyway runs a file: one string holding many files runs
|
||||
* in one implicit transaction, where PostgreSQL refuses a file Flyway runs outside one — a
|
||||
* concurrent index build (re-review 2026-11-03 round 7, RR7-03-01).
|
||||
*/
|
||||
static List<String> before(String fileName) throws IOException {
|
||||
List<String> scripts = new ArrayList<>();
|
||||
for (String name : inOrder()) {
|
||||
if (name.equals(fileName)) {
|
||||
break;
|
||||
}
|
||||
sql.append(read(name)).append('\n');
|
||||
scripts.add(read(name));
|
||||
}
|
||||
return sql.toString();
|
||||
return scripts;
|
||||
}
|
||||
|
||||
/** One migration's SQL, by its file name. */
|
||||
@@ -63,6 +72,23 @@ final class GrpcOperationLedgerMigrations {
|
||||
return read(fileName);
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether Flyway is told to run the migration in a transaction: false only when the {@code
|
||||
* <script>.conf} beside it sets {@code executeInTransaction} to {@code false}, read as Flyway
|
||||
* reads it (a properties file, any case).
|
||||
*/
|
||||
static boolean executeInTransaction(String fileName) throws IOException {
|
||||
Path configuration = TREE.resolve(fileName + ".conf");
|
||||
if (!Files.exists(configuration)) {
|
||||
return true;
|
||||
}
|
||||
Properties properties = new Properties();
|
||||
try (Reader reader = Files.newBufferedReader(configuration)) {
|
||||
properties.load(reader);
|
||||
}
|
||||
return !"false".equalsIgnoreCase(properties.getProperty("executeInTransaction", "").trim());
|
||||
}
|
||||
|
||||
private static String read(String fileName) throws IOException {
|
||||
String path = LOCATION + fileName;
|
||||
try (InputStream stream =
|
||||
|
||||
+3
-5
@@ -56,7 +56,9 @@ class GrpcOperationLedgerPostgresIT {
|
||||
try (Connection connection = dataSource.getConnection();
|
||||
Statement statement = connection.createStatement()) {
|
||||
statement.execute("DROP TABLE IF EXISTS grpc_operation_ledger");
|
||||
statement.execute(migration());
|
||||
for (String script : GrpcOperationLedgerMigrations.all()) {
|
||||
statement.execute(script);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -142,8 +144,4 @@ class GrpcOperationLedgerPostgresIT {
|
||||
.replace(":requestFingerprint", "?")
|
||||
.replace(":claimedAt", "?");
|
||||
}
|
||||
|
||||
private static String migration() throws IOException {
|
||||
return GrpcOperationLedgerMigrations.all();
|
||||
}
|
||||
}
|
||||
|
||||
+3
-5
@@ -55,7 +55,9 @@ class JpaGrpcOperationLedgerContractIT extends GrpcOperationLedgerContract {
|
||||
|
||||
@BeforeAll
|
||||
static void startJpa() throws SQLException, IOException {
|
||||
execute(migration());
|
||||
for (String script : GrpcOperationLedgerMigrations.all()) {
|
||||
execute(script);
|
||||
}
|
||||
entityManagerFactory =
|
||||
new PersistenceConfiguration("grpc-operation-ledger")
|
||||
.managedClass(GrpcOperationLedgerEntity.class)
|
||||
@@ -171,10 +173,6 @@ class JpaGrpcOperationLedgerContractIT extends GrpcOperationLedgerContract {
|
||||
}
|
||||
}
|
||||
|
||||
private static String migration() throws IOException {
|
||||
return GrpcOperationLedgerMigrations.all();
|
||||
}
|
||||
|
||||
/** Runs each call in its own transaction, as a caller's business transaction would. */
|
||||
private record PerCallTransactionLedger(
|
||||
JpaGrpcOperationLedger delegate, TransactionTemplate transactions)
|
||||
|
||||
+1
-1
@@ -20,7 +20,7 @@ class GrpcPackageOwnershipTest {
|
||||
List<String> leaves = List.of("grpc-core-api", "grpc-runtime", "grpc-operation-ledger-jpa");
|
||||
Map<String, List<String>> owners = new LinkedHashMap<>();
|
||||
for (String leaf : leaves) {
|
||||
Path source = repo.resolve("src/grpc").resolve(leaf).resolve("src/main/java");
|
||||
Path source = repo.resolve("src/platforms/grpc").resolve(leaf).resolve("src/main/java");
|
||||
try (var files = Files.walk(source)) {
|
||||
for (Path file : files.filter(path -> path.toString().endsWith(".java")).toList()) {
|
||||
var matcher = PACKAGE.matcher(Files.readString(file));
|
||||
|
||||
+4
-4
@@ -1,5 +1,5 @@
|
||||
pluginManagement {
|
||||
includeBuild('../build-logic')
|
||||
includeBuild('../../build-logic')
|
||||
}
|
||||
|
||||
plugins {
|
||||
@@ -13,7 +13,7 @@ dependencyResolutionManagement {
|
||||
}
|
||||
versionCatalogs {
|
||||
libs {
|
||||
from(files('../gradle/libs.versions.toml'))
|
||||
from(files('../../gradle/libs.versions.toml'))
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -28,9 +28,9 @@ def readBuildProperties = { File file ->
|
||||
file.withInputStream { properties.load(it) }
|
||||
properties
|
||||
}
|
||||
def mainBuildProperties = readBuildProperties(new File(settingsDir, '../gradle.properties'))
|
||||
def mainBuildProperties = readBuildProperties(new File(settingsDir, '../../gradle.properties'))
|
||||
def ownBuildProperties = readBuildProperties(new File(settingsDir, 'gradle.properties'))
|
||||
if (mainBuildProperties != ownBuildProperties) {
|
||||
throw new GradleException("optional-platforms/gradle.properties differs from src/gradle.properties: " +
|
||||
throw new GradleException("platforms/optional-build/gradle.properties differs from src/gradle.properties: " +
|
||||
"${ownBuildProperties} vs ${mainBuildProperties}. Copy the main build's values.")
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user