diff --git a/README.md b/README.md index cd6ddeb..e6bce65 100644 --- a/README.md +++ b/README.md @@ -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; diff --git a/build.gradle b/build.gradle index c73bdc2..9a2eb59 100644 --- a/build.gradle +++ b/build.gradle @@ -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 ` from `src`. A command counts when it starts in this +// `./gradlew -p platforms/optional-build ` 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') } diff --git a/docs/adr/ADR-GRPC-001-platform-family-and-registry-shape.md b/docs/adr/ADR-GRPC-001-platform-family-and-registry-shape.md index f2eabfd..c45ff9c 100644 --- a/docs/adr/ADR-GRPC-001-platform-family-and-registry-shape.md +++ b/docs/adr/ADR-GRPC-001-platform-family-and-registry-shape.md @@ -1,3 +1,12 @@ + +> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. + +- 상태: 채택 +- 작성일: 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 diff --git a/docs/adr/ADR-GRPC-002-schema-governance-without-protoc.md b/docs/adr/ADR-GRPC-002-schema-governance-without-protoc.md index 5e3b523..8264186 100644 --- a/docs/adr/ADR-GRPC-002-schema-governance-without-protoc.md +++ b/docs/adr/ADR-GRPC-002-schema-governance-without-protoc.md @@ -1,3 +1,13 @@ + +> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. + +- 상태: 대체됨 +- 작성일: 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 diff --git a/docs/adr/ADR-GRPC-003-three-axis-execution-evidence.md b/docs/adr/ADR-GRPC-003-three-axis-execution-evidence.md index e4f6d50..9a944e9 100644 --- a/docs/adr/ADR-GRPC-003-three-axis-execution-evidence.md +++ b/docs/adr/ADR-GRPC-003-three-axis-execution-evidence.md @@ -1,3 +1,12 @@ + +> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. + +- 상태: 채택 +- 작성일: 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 diff --git a/docs/adr/ADR-GRPC-004-retry-ownership-and-durable-idempotency.md b/docs/adr/ADR-GRPC-004-retry-ownership-and-durable-idempotency.md index 7898463..00a03ed 100644 --- a/docs/adr/ADR-GRPC-004-retry-ownership-and-durable-idempotency.md +++ b/docs/adr/ADR-GRPC-004-retry-ownership-and-durable-idempotency.md @@ -1,3 +1,12 @@ + +> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. + +- 상태: 채택 +- 작성일: 2026-08-30 +- 요약: 재시도 주인은 하나이고 키가 있는 변경은 영속 원장이 필요하다는 결정이다. +- 현재 정본: `docs/compatibility/grpc-support-matrix.md` + + # ADR-GRPC-004: One retry owner, and keyed mutations need a durable ledger - Status: accepted diff --git a/docs/adr/ADR-GRPC-005-server-streaming-single-writer-and-resume.md b/docs/adr/ADR-GRPC-005-server-streaming-single-writer-and-resume.md index b648be9..712eddf 100644 --- a/docs/adr/ADR-GRPC-005-server-streaming-single-writer-and-resume.md +++ b/docs/adr/ADR-GRPC-005-server-streaming-single-writer-and-resume.md @@ -1,3 +1,12 @@ + +> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. + +- 상태: 채택 +- 작성일: 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 diff --git a/docs/adr/ADR-GRPC-006-stable-discovery-and-kubernetes-routing.md b/docs/adr/ADR-GRPC-006-stable-discovery-and-kubernetes-routing.md index 3be4e14..17e677a 100644 --- a/docs/adr/ADR-GRPC-006-stable-discovery-and-kubernetes-routing.md +++ b/docs/adr/ADR-GRPC-006-stable-discovery-and-kubernetes-routing.md @@ -1,3 +1,12 @@ + +> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. + +- 상태: 채택 +- 작성일: 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 diff --git a/docs/adr/ADR-GRPC-ADV-001-capability-promotion-is-per-capability.md b/docs/adr/ADR-GRPC-ADV-001-capability-promotion-is-per-capability.md index 041a85a..63e6bfd 100644 --- a/docs/adr/ADR-GRPC-ADV-001-capability-promotion-is-per-capability.md +++ b/docs/adr/ADR-GRPC-ADV-001-capability-promotion-is-per-capability.md @@ -1,3 +1,12 @@ + +> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. + +- 상태: 채택 +- 작성일: 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 diff --git a/docs/design/2026-08-30-grpc-platform-adaptation-design.md b/docs/design/2026-08-30-grpc-platform-adaptation-design.md index c7f2c24..55b23bb 100644 --- a/docs/design/2026-08-30-grpc-platform-adaptation-design.md +++ b/docs/design/2026-08-30-grpc-platform-adaptation-design.md @@ -1,3 +1,12 @@ + +> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다. + +- 상태: 확인 안 함 +- 작성일: 2026-08-30 +- 요약: 타입 안전 gRPC 실행 플랫폼 계획을 이 저장소의 구조와 게이트에 맞춘 설계다. +- 현재 정본: `docs/compatibility/grpc-support-matrix.md` + + # 타입 안전 gRPC 실행 플랫폼 — 이 저장소 규약으로의 어댑팅 설계 두 계획 문서를 이 저장소(`ca-skeleton`)의 실제 구조·정책·빌드 게이트에 맞춰 실행 가능한 형태로 diff --git a/gradle.properties b/gradle.properties index 0d1f586..cabb814 100644 --- a/gradle.properties +++ b/gradle.properties @@ -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 diff --git a/grpc-advanced/CLAUDE.md b/grpc-advanced/CLAUDE.md index 12b53b2..158830a 100644 --- a/grpc-advanced/CLAUDE.md +++ b/grpc-advanced/CLAUDE.md @@ -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..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. 두 번째가 diff --git a/grpc/CLAUDE.md b/grpc/CLAUDE.md index 5705281..190f58d 100644 --- a/grpc/CLAUDE.md +++ b/grpc/CLAUDE.md @@ -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::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::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 diff --git a/grpc/grpc-contract/buf.yaml b/grpc/grpc-contract/buf.yaml index 5565f6e..d81d5f1 100644 --- a/grpc/grpc-contract/buf.yaml +++ b/grpc/grpc-contract/buf.yaml @@ -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 '#subdir=src/grpc/grpc-contract' +# buf breaking --against '#subdir=src/platforms/grpc/grpc-contract' # # No dependencies: the only imports are protoc's own well-known types (google/protobuf/*.proto). version: v2 diff --git a/grpc/grpc-operation-ledger-jpa/build.gradle b/grpc/grpc-operation-ledger-jpa/build.gradle index 05d90ae..6a83f77 100644 --- a/grpc/grpc-operation-ledger-jpa/build.gradle +++ b/grpc/grpc-operation-ledger-jpa/build.gradle @@ -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')) } diff --git a/grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/GrpcOperationLedgerMigrationLockWaitIT.java b/grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/GrpcOperationLedgerMigrationLockWaitIT.java index 723fe1d..9ff4829 100644 --- a/grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/GrpcOperationLedgerMigrationLockWaitIT.java +++ b/grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/GrpcOperationLedgerMigrationLockWaitIT.java @@ -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; *

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. * *

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 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 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 tree = new LinkedHashMap<>(); + for (String migration : GrpcOperationLedgerMigrations.inOrder()) { + tree.put( + migration, + new LedgerMigration( + GrpcOperationLedgerMigrations.named(migration), + GrpcOperationLedgerMigrations.executeInTransaction(migration))); + } + + // when + List refused = refusalsOf(RUN_OUTSIDE_A_TRANSACTION.keySet(), tree); + + // then + assertThat(refused).isEmpty(); + } + + @ParameterizedTest + @MethodSource("listedFilesTheGuideDoesNotAllow") + @DisplayName( + "예외 목록 검사는 트리에 없는 파일, 동시 인덱스 문장이 없는 파일, executeInTransaction=false가 없는 파일, 다른 문장과 섞인 파일을 이유와 함께 거부한다") + void theListCheckRefusesAFileTheGuideDoesNotAllow( + String listed, Map tree, String reason) { + // when + List refused = refusalsOf(List.of(listed), tree); + + // then + assertThat(refused).singleElement().asString().contains(listed).contains(reason); + } + + @Test + @DisplayName("예외 목록 검사는 executeInTransaction=false를 곁에 둔, 동시 인덱스 문장 하나뿐인 파일을 받는다") + void theListCheckAcceptsAConcurrentIndexBuildAloneThatSaysSo() { + // given + Map tree = + Map.of(LISTED, new LedgerMigration(CONCURRENT_BUILD, false)); + + // when + List 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 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 refusalsOf(Collection listed, Map tree) { + ConcurrentIndexMigrationInspector inspector = new ConcurrentIndexMigrationInspector(); + List 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) { diff --git a/grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/GrpcOperationLedgerMigrations.java b/grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/GrpcOperationLedgerMigrations.java index f8832fc..c237e17 100644 --- a/grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/GrpcOperationLedgerMigrations.java +++ b/grpc/grpc-operation-ledger-jpa/src/integrationTest/java/dev/caskeleton/grpc/ledger/GrpcOperationLedgerMigrations.java @@ -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. * *

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 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 before(String fileName) throws IOException { + List 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 + *