diff --git a/docs/jpa/migration-guide.md b/docs/jpa/migration-guide.md index 9223d687..5f2e2158 100644 --- a/docs/jpa/migration-guide.md +++ b/docs/jpa/migration-guide.md @@ -20,7 +20,10 @@ older than itself, Flyway's own included — the deploy stops with no error and defaults (`config/module-defaults/persistence-jpa.yml`, `spring.flyway.postgresql.transactional-lock: false`) for the one Spring Boot builds at startup, and `FlywaySchemaPolicy.configure()` for every stream it builds itself — a service's own stream starts from it too, and `JpaProductionArchitectureTest` -refuses production code that calls `Flyway.configure()` directly. The deployment-owned migration of +refuses production code that builds a Flyway any other way: calling `Flyway.configure()`, or +constructing a configuration itself (`new FluentConfiguration()`, `new ClassicConfiguration()`, a +subclass of either, or `FluentConfiguration::new`). `new Flyway(...)` over the policy's configuration +is allowed. The deployment-owned migration of staging and prod is outside this repository: give its tool the same value (`FLYWAY_POSTGRESQL_TRANSACTIONAL_LOCK=false`, or the key above in its configuration file). diff --git a/docs/manual/04-persistence.md b/docs/manual/04-persistence.md index f009b847..e26a24e6 100644 --- a/docs/manual/04-persistence.md +++ b/docs/manual/04-persistence.md @@ -120,8 +120,10 @@ capability 스트림 db/migration/jpa/ 각자 histor (`src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/bootstrap/persistence/SamplePostgreSqlPersistenceConfig.java`)와 `NotificationSchemaStream`(persistence-notification). 그러면 번호가 템플릿 스트림과 독립이라 V1부터 쓴다. 자기 스트림의 Flyway는 `Flyway.configure()`가 아니라 `FlywaySchemaPolicy.configure()`(persistence-jpa)로 - 만든다. Flyway의 PostgreSQL 잠금을 세션에 두어야 `CREATE INDEX CONCURRENTLY` 마이그레이션이 끝나고, - 직접 부르면 `:app-bootstrap:architectureTest`가 실패한다(`docs/jpa/migration-guide.md` "Who may change the schema"). + 만든다. Flyway의 PostgreSQL 잠금을 세션에 두어야 `CREATE INDEX CONCURRENTLY` 마이그레이션이 끝난다. + `Flyway.configure()`를 직접 부르거나 설정 객체를 직접 만들면(`new FluentConfiguration()`, + `new ClassicConfiguration()`, 그 하위 클래스) `:app-bootstrap:architectureTest`가 실패한다 + (`docs/jpa/migration-guide.md` "Who may change the schema"). - **예외**: 템플릿 운영 스트림(`db/migration/postgresql`)에 직접 넣으면 upstream이 다음에 쓸 번호와 겹친다. 어쩔 수 없으면 upstream이 쓰지 않을 큰 번호대를 정해 문서에 적는다. - 이미 적용된 파일은 고치지 않는다. 고치면 체크섬 불일치로 기동이 멈추고, `repair`는 쓰지 않는다 diff --git a/docs/upgrade/2026-11-maturity-review.md b/docs/upgrade/2026-11-maturity-review.md index 73a3f76d..8b01b9b4 100644 --- a/docs/upgrade/2026-11-maturity-review.md +++ b/docs/upgrade/2026-11-maturity-review.md @@ -35,7 +35,7 @@ | 12 | 자기 Flyway 마이그레이션 번호가 템플릿의 새 번호와 겹치지 않는지 본다(4절) | 같은 버전 두 개로 Flyway 실패 | 같은 stream에 자기 마이그레이션을 둔 서비스 | | 13 | `.env`에 옛 `.env.example` 값을 복사해 두었다면 5.6절 키를 다시 맞춘다 | 새 기본값이 안 먹거나(JDBC batch), 기동 실패(알림 콜백 상한) | `.env`를 복사해 쓰는 서비스 | | 14 | 자기 테스트 코드에 `./gradlew testQualityCheck`를 돌려 보고, 발견을 고치거나 이유를 단 Match로 뺀다(B-40) | `mainCheck`가 실패 | 테스트 코드가 있는 모든 서비스 | -| 15 | staging·prod 배포 마이그레이션 도구에 `flyway.postgresql.transactional.lock=false`(환경 변수 `FLYWAY_POSTGRESQL_TRANSACTIONAL_LOCK=false`)를 넣는다. 자기 Flyway stream은 `Flyway.configure()` 대신 `FlywaySchemaPolicy.configure()`로 만든다(5절 「Flyway 잠금」) | `CREATE INDEX CONCURRENTLY`·`REINDEX … CONCURRENTLY` 마이그레이션에서 배포가 오류 없이 멈춘다. 자기 stream이 `Flyway.configure()`를 부르면 `:app-bootstrap:architectureTest` 실패 | persistence-jpa 선택 + 배포 도구로 마이그레이션하거나 자기 stream을 둔 서비스 | +| 15 | staging·prod 배포 마이그레이션 도구에 `flyway.postgresql.transactional.lock=false`(환경 변수 `FLYWAY_POSTGRESQL_TRANSACTIONAL_LOCK=false`)를 넣는다. 자기 Flyway stream은 `Flyway.configure()` 대신 `FlywaySchemaPolicy.configure()`로 만든다(5절 「Flyway 잠금」) | `CREATE INDEX CONCURRENTLY`·`REINDEX … CONCURRENTLY` 마이그레이션에서 배포가 오류 없이 멈춘다. 자기 stream이 `Flyway.configure()`를 부르거나 설정 객체를 직접 만들면(`new FluentConfiguration()`·`new ClassicConfiguration()`, 재리뷰 round7 RR7-03-06부터) `:app-bootstrap:architectureTest` 실패 | persistence-jpa 선택 + 배포 도구로 마이그레이션하거나 자기 stream을 둔 서비스 | | 16 | 자기 성능 lane(`performance()`)에서 `performance.assertions.enabled`를 `false`로 두는 `systemProperty` 줄을 지우고, 그 속성을 읽어 상한 단언을 건너뛰던 테스트는 항상 단언하게 고친다. 성능 lane의 `@Disabled`·assumption skip을 없앤다(B-43) | `performanceCheck`가 테스트 전에 실패(`its test JVM would get performance.assertions.enabled=false`)하거나 skip 때문에 실패(`forbids skipped tests`) | 자기 성능 lane이 있는 서비스 | | 17 | 자기 `docs/registries/error-codes.yaml` 행에서 `log_level:` 줄을 지운다(B-44) | `mainCheck`의 `:app-bootstrap:documentContractTest`가 실패(`docs/registries/error-codes.yaml rows with a log_level; the code decides the level, not the registry`) | `error-codes.yaml`에 자기 행을 더한 서비스 | @@ -247,7 +247,7 @@ V21 실패의 분류는 `docs/runbooks/migration-failed.md` "Classify the failur | 빌드 단계(HTTP client) | `httpClientFailureInjectionTest`(Toxiproxy 장애 주입)가 `mainCheck`에서 빠졌다. `integrationCheck`에만 있고, main push·nightly의 `integration-main.yml` `integration-check` job이 돌린다 | main push마다 같은 lane이 `main-check`·`integration-check` 두 job에서 두 번 돌던 것이 한 번이 된다. 로컬에서 `mainCheck`만 돌리면 이 lane은 돌지 않는다(`integrationCheck`로 돌린다) | r9 · `src/adapter/outbound/httpclient/build.gradle` | | 서버 로그(GraphQL·gRPC·STOMP) | carrier로 답한 실패를 web과 같은 줄(shared-contract `ServerFailureLog`)로 ERROR에 남긴다: persistence 실패는 분류만, 5xx carrier는 예외와 함께, 4xx carrier는 남기지 않는다. gRPC는 ` (method=…)`, GraphQL은 ` (executionId=…)`를 붙인다. gRPC는 인식 못 한 실패(`INTERNAL_ERROR`)도 `unhandled failure on …`로 남긴다. 클라이언트가 취소한 호출은 남기지 않고, 서비스가 `CANCELLED` status로 끝낸 살아 있는 호출은 남긴다. raw status는 넘겼든 던졌든 설명을 남기지 않는다(원인 예외가 있으면 그것만 붙인다). `IllegalArgumentException`(`BAD_PARAMETER`)은 web과 같은 WARN 한 줄 `request refused as BAD_PARAMETER by <예외 타입>`(메시지 없음)으로 남긴다. STOMP `@MessageMapping` 실패는 Spring의 `Unhandled exception from message handler method`(예외 전체) 대신 같은 줄로 남는다 | ERROR 로그가 늘어난다(전에는 gRPC가 아무것도 남기지 않았다). GraphQL·gRPC·STOMP는 잘못된 입력마다 WARN 한 줄이 생긴다. STOMP에서 Spring 문구로 경보를 걸었다면 고친다. `IDEMPOTENCY_RECOVERY_REQUIRED`의 scope digest를 모든 전송에서 찾을 수 있다(`docs/runbooks/idempotency-unavailable.md`) | r9 · `src/shared-contract/.../error/ServerFailureLog.java`, `GrpcExceptionHandlingInterceptor.java`, `GraphQlWireErrorMapper.java`, `StompHandlerFailureLog.java` | | sample-portfolio | 익명 쓰기 401, 포스터 제목 대소문자 무시 유일(409 `POSTER_ALREADY_EXISTS`), 관리자도 남의 work log 수정 불가, 샘플 이벤트 tenant `global` | sample을 남긴 서비스만 | `34565130`, `1400dc15` | -| Flyway 잠금 | Flyway의 PostgreSQL 마이그레이션 잠금을 트랜잭션 대신 세션에 둔다. Spring Boot의 Flyway는 module-defaults `spring.flyway.postgresql.transactional-lock: false`, 템플릿이 직접 만드는 Flyway(멱등성·알림·sample stream, schema-per-tenant, testkit `MigrationContractRunner`)는 `FlywaySchemaPolicy.configure()`, messaging inbox stream은 같은 값을 직접 넣는다. 운영 코드의 `Flyway.configure()` 직접 호출은 `JpaProductionArchitectureTest`가 거부한다 | Flyway 기본값에서는 동시 인덱스 마이그레이션이 Flyway 자신의 열린 트랜잭션을 기다려 끝나지 않았다. 이제 끝난다. 마이그레이션은 잠금을 잡은 연결 하나로 돈다. transaction 모드 PgBouncer 뒤에서는 잠금 해제가 다른 서버 연결로 가 다음 배포가 기다릴 수 있으니 마이그레이션은 직접 연결이나 session 모드 pool로 돌린다. 배포 도구는 이 repo 밖이라 2절 15번으로 맞춘다 | 재리뷰 round6 RR6-03-01 · `persistence-jpa.yml`, `.../migration/FlywaySchemaPolicy.java`, `docs/jpa/migration-guide.md` "Who may change the schema"·"Concurrent index builds" | +| Flyway 잠금 | Flyway의 PostgreSQL 마이그레이션 잠금을 트랜잭션 대신 세션에 둔다. Spring Boot의 Flyway는 module-defaults `spring.flyway.postgresql.transactional-lock: false`, 템플릿이 직접 만드는 Flyway(멱등성·알림·sample stream, schema-per-tenant, testkit `MigrationContractRunner`)는 `FlywaySchemaPolicy.configure()`, messaging inbox stream은 같은 값을 직접 넣는다. 운영 코드의 `Flyway.configure()` 직접 호출과 설정 객체 직접 생성(`new FluentConfiguration()`·`new ClassicConfiguration()`·그 하위 클래스, round7 RR7-03-06)은 `JpaProductionArchitectureTest`가 거부한다 | Flyway 기본값에서는 동시 인덱스 마이그레이션이 Flyway 자신의 열린 트랜잭션을 기다려 끝나지 않았다. 이제 끝난다. 마이그레이션은 잠금을 잡은 연결 하나로 돈다. transaction 모드 PgBouncer 뒤에서는 잠금 해제가 다른 서버 연결로 가 다음 배포가 기다릴 수 있으니 마이그레이션은 직접 연결이나 session 모드 pool로 돌린다. 배포 도구는 이 repo 밖이라 2절 15번으로 맞춘다 | 재리뷰 round6 RR6-03-01 · `persistence-jpa.yml`, `.../migration/FlywaySchemaPolicy.java`, `docs/jpa/migration-guide.md` "Who may change the schema"·"Concurrent index builds" | | 실패한 동시 인덱스 마이그레이션 복구 | `docs/runbooks/migration-failed.md`에 「Recover a failed concurrent index migration」을 더했다: 진행 중인 빌드가 없는지 보고, 무효 인덱스를 `DROP INDEX CONCURRENTLY`로 지우고, 원인을 정리하고, 그 버전의 실패 이력 행(`success = false`)만 지운 뒤 다시 배포한다. 「Do not」의 이력 수정 금지에 이 한 가지 예외를 적었다. `flyway repair`는 계속 쓰지 않는다 | 전에는 안내가 "`DROP INDEX` 하나"였고, 그대로 하면 남은 실패 이력 때문에 다음 배포가 validate에서 다시 멈췄다. 동시 인덱스 마이그레이션을 쓰는 서비스의 운영자는 이 절차로 복구한다 | 재리뷰 round7 RR7-03-03, 소유자 결정 2026-11-06 · `docs/jpa/migration-guide.md` "Concurrent index builds", `PostgreSqlConcurrentIndexMigrationIntegrationTest` | | 성능 lane(HTTP client·Mongo) | httpclient `LargeBodyResourceTest`의 힙 상한(32 MiB 스트리밍 중 힙 증가 16 MiB 미만)을 매번 단언한다. 전에는 `-Pperformance.assertions.enabled=true`일 때만 단언하고 아니면 건너뛴다는 줄만 찍었다. Mongo `MongoResourceBudgetLaneTest`는 표준 gate 전체(p99 500ms, pool 대기 250ms, 힙 512 MiB, examined/returned 10, spill 금지)를 Gradle 밖 실행에서도 단언한다(B-43) | 손으로 돌린 `performanceCheck`가 상한을 실제로 재므로, 전에는 통과하던 느린 기계에서 실패할 수 있다 | B4(2026-11-06) · `LargeBodyResourceTest`, `MongoResourceBudgetLaneTest` | | 보안 필터 로그 레벨 | 보안 필터(`AuthErrorResponseWriter`)의 `security failure` 줄을 5xx(`AUTH_JWKS_UNAVAILABLE` 503, `INTERNAL_AUTH_MISCONFIGURATION` 500)면 ERROR, 4xx면 WARN으로 남긴다. 전에는 모두 WARN이었다. 다른 경로가 5xx를 ERROR로 남기는 규칙(`ServerFailureLog`)과 같아졌다 | ERROR로 거르는 로그 경보·대시보드에 JWKS 장애와 인증 설정 오류가 새로 잡힌다. 401·403은 그대로 WARN | 설계 메모 2026-11-06 7절 결정 2 · `src/adapter/inbound/web/.../auth/AuthErrorResponseWriter.java`, `docs/superpowers/specs/2026-11-06-error-code-log-level-design.md` | diff --git a/src/adapter/outbound/persistence-jpa/CLAUDE.md b/src/adapter/outbound/persistence-jpa/CLAUDE.md index e8caf319..56a4170a 100644 --- a/src/adapter/outbound/persistence-jpa/CLAUDE.md +++ b/src/adapter/outbound/persistence-jpa/CLAUDE.md @@ -100,8 +100,9 @@ not grow by wiring accident. - Flyway holds its PostgreSQL migration lock for the session, never in an open transaction, or a `CREATE INDEX CONCURRENTLY` migration waits for Flyway forever: `spring.flyway.postgresql.transactional-lock: false` in the module defaults, and every Flyway built in code starts from - `FlywaySchemaPolicy.configure()` (`JpaProductionArchitectureTest` refuses `Flyway.configure()`; - `docs/jpa/migration-guide.md` "Who may change the schema"). + `FlywaySchemaPolicy.configure()` (`JpaProductionArchitectureTest` refuses `Flyway.configure()` and + constructing a Flyway configuration directly — `new FluentConfiguration()`, `new + ClassicConfiguration()`, a subclass; `docs/jpa/migration-guide.md` "Who may change the schema"). - Metric tags, exception messages, and logs carry no SQL parameters, entity ids, tenant ids, or PII. - Contracts run against real PostgreSQL. H2 never satisfies one. diff --git a/src/adapter/outbound/persistence-jpa/README.md b/src/adapter/outbound/persistence-jpa/README.md index a13880a2..a586810a 100644 --- a/src/adapter/outbound/persistence-jpa/README.md +++ b/src/adapter/outbound/persistence-jpa/README.md @@ -405,8 +405,9 @@ Flyway의 PostgreSQL 마이그레이션 잠금은 트랜잭션이 아니라 세 열어 두고, `CREATE INDEX CONCURRENTLY`·`REINDEX … CONCURRENTLY`는 그 트랜잭션이 끝나기를 기다려 배포가 끝나지 않는다(재리뷰 round6 RR6-03-01). Spring Boot의 Flyway는 `config/module-defaults/persistence-jpa.yml`의 `spring.flyway.postgresql.transactional-lock: false`로, 템플릿이 직접 만드는 Flyway는 -`FlywaySchemaPolicy.configure()`로 받는다. 운영 코드가 `Flyway.configure()`를 직접 부르면 -`JpaProductionArchitectureTest`가 거부한다. 배포 마이그레이션 도구에도 같은 값을 넣는다 +`FlywaySchemaPolicy.configure()`로 받는다. 운영 코드가 `Flyway.configure()`를 직접 부르거나 Flyway 설정 객체를 +직접 만들면(`new FluentConfiguration()`, `new ClassicConfiguration()`, 그 하위 클래스) `JpaProductionArchitectureTest`가 +거부한다. 배포 마이그레이션 도구에도 같은 값을 넣는다 (`docs/jpa/migration-guide.md` "Who may change the schema", lane `postgresqlConcurrentIndexMigrationIntegrationTest`). 적용된 versioned migration은 수정하지 않는다. Flyway가 기동할 때마다 checksum을 검사하므로 diff --git a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/migration/FlywaySchemaPolicy.java b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/migration/FlywaySchemaPolicy.java index 1ac9fbaf..272cb06e 100644 --- a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/migration/FlywaySchemaPolicy.java +++ b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/migration/FlywaySchemaPolicy.java @@ -109,8 +109,11 @@ public final class FlywaySchemaPolicy { * spring.flyway.postgresql.transactional-lock}); a deployment's migration tool has to be given it * ({@code docs/jpa/migration-guide.md}, "Who may change the schema"). * - *

Callers chain their own settings onto the result. Calling {@link Flyway#configure()} - * directly in production code is refused by {@code JpaProductionArchitectureTest}. + *

Callers chain their own settings onto the result. Production code that builds a Flyway any + * other way — calling {@link Flyway#configure()}, or constructing a Flyway configuration itself + * ({@code new FluentConfiguration()}, {@code new ClassicConfiguration()}, a subclass of either) — + * is refused by {@code JpaProductionArchitectureTest}; {@code new Flyway(...)} over this method's + * result is allowed (re-review 2026-11-03 round 7, RR7-03-06). */ public static FluentConfiguration configure() { return sessionLevelLock(Flyway.configure()); diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ArchitectureViolationFixtureTest.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ArchitectureViolationFixtureTest.java index 0b82c1e1..7d688eb1 100644 --- a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ArchitectureViolationFixtureTest.java +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ArchitectureViolationFixtureTest.java @@ -16,6 +16,7 @@ import dev.caskeleton.bootstrap.architecture.allowed.application.CleanProjection import dev.caskeleton.bootstrap.architecture.allowed.configuration.SystemCallerBesideControllerRegistrationFixture; import dev.caskeleton.bootstrap.architecture.allowed.configuration.SystemCallerBesideFieldReadingWebMvcConfigurerFixture; import dev.caskeleton.bootstrap.architecture.allowed.configuration.SystemCallerBesideWebMvcRegistrationFixture; +import dev.caskeleton.bootstrap.architecture.allowed.persistence.flyway.SchemaPolicyFlywayFixture; import dev.caskeleton.bootstrap.architecture.fixtures.application.RootWriteTransactionBoundaryUseCase; import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.messaging.SystemCallerRestControllerFixture; import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.messaging.UnmarkedSystemInvokedHandlerFixture; @@ -50,9 +51,16 @@ import dev.caskeleton.bootstrap.architecture.violations.domain.AnnotatedPublicNo import dev.caskeleton.bootstrap.architecture.violations.domain.JakartaValidationDomainFixture; import dev.caskeleton.bootstrap.architecture.violations.domain.entity.FakeDomainEntity; import dev.caskeleton.bootstrap.architecture.violations.domain.vo.PackagePublicNoArgValueObjectFixture; +import dev.caskeleton.bootstrap.architecture.violations.persistence.flyway.ClassicConfigurationFlywayFixture; +import dev.caskeleton.bootstrap.architecture.violations.persistence.flyway.ConfigureCallingFlywayFixture; +import dev.caskeleton.bootstrap.architecture.violations.persistence.flyway.FluentConfigurationFlywayFixture; +import dev.caskeleton.bootstrap.architecture.violations.persistence.flyway.ReferencedConfigurationFlywayFixture; import dev.caskeleton.bootstrap.architecture.violations.streaming.JakartaWebSocketEndpointFixture; import dev.caskeleton.bootstrap.architecture.violations.streaming.SpringWebSocketHandlerFixture; +import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; /** * Negative ("violations-as-data") tests proving each architecture rule actually catches the @@ -1383,4 +1391,44 @@ class ArchitectureViolationFixtureTest { + "it references no broker/HTTP type") .isFalse(); } + + @ParameterizedTest + @ValueSource( + classes = { + ConfigureCallingFlywayFixture.class, + FluentConfigurationFlywayFixture.class, + ClassicConfigurationFlywayFixture.class, + ReferencedConfigurationFlywayFixture.class + }) + @DisplayName("FlywaySchemaPolicy를 거치지 않고 Flyway를 만드는 길은 어느 것이든 Flyway 규칙에 걸린다") + void everyWayToBuildAFlywayPastTheSchemaPolicyIsCaught(Class fixture) { + // given + JavaClasses fixtureOnly = new ClassFileImporter().importClasses(fixture); + + // when + EvaluationResult result = + JpaProductionArchitectureTest.EVERY_FLYWAY_STARTS_FROM_THE_SCHEMA_POLICY.evaluate( + fixtureOnly); + + // then + assertThat(result.hasViolation()) + .as("%s builds a Flyway past FlywaySchemaPolicy.configure()", fixture.getSimpleName()) + .isTrue(); + } + + @Test + @DisplayName("FlywaySchemaPolicy.configure()에서 시작한 Flyway는 빌더로도 생성자로도 Flyway 규칙에 걸리지 않는다") + void aFlywayBuiltFromTheSchemaPolicyIsNotFlagged() { + // given + JavaClasses fixtureOnly = + new ClassFileImporter().importClasses(SchemaPolicyFlywayFixture.class); + + // when + EvaluationResult result = + JpaProductionArchitectureTest.EVERY_FLYWAY_STARTS_FROM_THE_SCHEMA_POLICY.evaluate( + fixtureOnly); + + // then + assertThat(result.getFailureReport().getDetails()).isEmpty(); + } } diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/JpaProductionArchitectureTest.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/JpaProductionArchitectureTest.java index a17fdf6b..07ea43dc 100644 --- a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/JpaProductionArchitectureTest.java +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/JpaProductionArchitectureTest.java @@ -3,8 +3,12 @@ package dev.caskeleton.bootstrap.architecture; import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses; import static org.assertj.core.api.Assertions.assertThat; +import com.tngtech.archunit.base.DescribedPredicate; +import com.tngtech.archunit.core.domain.JavaAccess; import com.tngtech.archunit.core.domain.JavaClasses; +import com.tngtech.archunit.core.domain.JavaConstructor; import com.tngtech.archunit.core.importer.ClassFileImporter; +import com.tngtech.archunit.lang.ArchRule; import dev.caskeleton.adapter.outbound.persistence.migration.FlywaySchemaPolicy; import dev.caskeleton.adapter.outbound.persistence.testkit.arch.JpaArchitectureRules; import jakarta.persistence.Entity; @@ -164,29 +168,63 @@ class JpaProductionArchitectureTest { .check(productionClasses); } + /** + * A call to, or a reference to ({@code FluentConfiguration::new}), a constructor of a type that + * is a Flyway {@code Configuration}. + */ + private static final DescribedPredicate> CONSTRUCTS_A_FLYWAY_CONFIGURATION = + DescribedPredicate.describe( + "a constructor of a Flyway Configuration", + access -> + JavaConstructor.CONSTRUCTOR_NAME.equals(access.getTarget().getName()) + && access + .getTargetOwner() + .isAssignableTo("org.flywaydb.core.api.configuration.Configuration")); + + /** + * Every Flyway the template builds starts from {@code FlywaySchemaPolicy.configure()}. + * + *

Flyway's PostgreSQL default holds its lock in a transaction left open for the whole run, and + * a concurrent index build waits for it without end (re-review 2026-11-03 round 6, RR6-03-01). + * FlywaySchemaPolicy.configure() holds it for the session; a stream that builds its own Flyway + * gets the default back. The inbox stream of adapter:inbound:messaging may not depend on + * persistence-jpa and keeps its own copy, held to the same value by its own test. + * + *

A Flyway has two starts besides the policy: {@code Flyway.configure()}, and a configuration + * built directly — {@code new FluentConfiguration()}, {@code new ClassicConfiguration()}, or a + * class of its own that extends or implements one — which {@code load()} or {@code new + * Flyway(...)} turns into a Flyway. The rule refuses both: the method, and constructing anything + * that is a Flyway {@code Configuration}, by a call or a constructor reference. {@code new + * Flyway(...)} itself stays allowed; over the policy's configuration it is the policy's Flyway + * (round 7, RR7-03-06: the rule saw only the method). The fixtures in {@code + * ..violations.persistence.flyway} and {@code ..allowed.persistence.flyway} show it catches the + * method, both constructors and a constructor reference, and passes the policy. A subclass has no + * fixture: SpotBugs cannot analyse a class that extends Flyway's configuration (it misses {@code + * lombok.Generated}, which the build treats as a failed analysis). Its constructor calls the + * configuration's, the access this rule refuses. + */ + static final ArchRule EVERY_FLYWAY_STARTS_FROM_THE_SCHEMA_POLICY = + noClasses() + .that() + .doNotHaveFullyQualifiedName(FlywaySchemaPolicy.class.getName()) + .and() + .doNotHaveFullyQualifiedName( + "dev.caskeleton.adapter.inbound.messaging.MessagingInboxSchemaStream") + .should() + .callMethod("org.flywaydb.core.Flyway", "configure") + .orShould() + .callMethod("org.flywaydb.core.Flyway", "configure", "java.lang.ClassLoader") + .orShould() + .accessTargetWhere(CONSTRUCTS_A_FLYWAY_CONFIGURATION) + .because( + "every Flyway the template builds starts from FlywaySchemaPolicy.configure(), which" + + " holds Flyway's PostgreSQL lock for the session (docs/jpa/migration-guide.md," + + " \"Concurrent index builds\")"); + @Test - @DisplayName("Flyway.configure()를 부르는 운영 코드는 FlywaySchemaPolicy뿐이다") + @DisplayName("Flyway.configure()를 부르거나 Flyway 설정 객체를 직접 만드는 운영 코드는 FlywaySchemaPolicy뿐이다") void everyProductionFlywayIsConfiguredThroughTheSchemaPolicy() { - // Flyway's PostgreSQL default holds its lock in a transaction left open for the whole run, and - // a concurrent index build waits for it without end (re-review 2026-11-03 round 6, RR6-03-01). - // FlywaySchemaPolicy.configure() holds it for the session; a stream that builds its own Flyway - // gets the default back. The inbox stream of adapter:inbound:messaging may not depend on - // persistence-jpa and keeps its own copy, held to the same value by its own test. - noClasses() - .that() - .doNotHaveFullyQualifiedName(FlywaySchemaPolicy.class.getName()) - .and() - .doNotHaveFullyQualifiedName( - "dev.caskeleton.adapter.inbound.messaging.MessagingInboxSchemaStream") - .should() - .callMethod("org.flywaydb.core.Flyway", "configure") - .orShould() - .callMethod("org.flywaydb.core.Flyway", "configure", "java.lang.ClassLoader") - .because( - "every Flyway the template builds starts from FlywaySchemaPolicy.configure(), which" - + " holds Flyway's PostgreSQL lock for the session (docs/jpa/migration-guide.md," - + " \"Concurrent index builds\")") - .check(productionClasses); + EVERY_FLYWAY_STARTS_FROM_THE_SCHEMA_POLICY.check(productionClasses); } @Test diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/allowed/persistence/flyway/SchemaPolicyFlywayFixture.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/allowed/persistence/flyway/SchemaPolicyFlywayFixture.java new file mode 100644 index 00000000..39f0c4a7 --- /dev/null +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/allowed/persistence/flyway/SchemaPolicyFlywayFixture.java @@ -0,0 +1,17 @@ +package dev.caskeleton.bootstrap.architecture.allowed.persistence.flyway; + +import dev.caskeleton.adapter.outbound.persistence.migration.FlywaySchemaPolicy; +import javax.sql.DataSource; +import org.flywaydb.core.Flyway; + +/** Builds a Flyway from the schema policy, the two ways a stream does. */ +public class SchemaPolicyFlywayFixture { + + public Flyway flyway(DataSource dataSource) { + return FlywaySchemaPolicy.configure().dataSource(dataSource).load(); + } + + public Flyway flywayFromTheConstructor(DataSource dataSource) { + return new Flyway(FlywaySchemaPolicy.configure().dataSource(dataSource)); + } +} diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/allowed/persistence/flyway/package-info.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/allowed/persistence/flyway/package-info.java new file mode 100644 index 00000000..c2487b8a --- /dev/null +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/allowed/persistence/flyway/package-info.java @@ -0,0 +1,6 @@ +/** + * "Allowed-as-data" for {@code EVERY_FLYWAY_STARTS_FROM_THE_SCHEMA_POLICY}: a Flyway built from + * {@code FlywaySchemaPolicy.configure()}, by its builder or by the {@code Flyway} constructor over + * the policy's configuration, is what the rule asks for and is not flagged. + */ +package dev.caskeleton.bootstrap.architecture.allowed.persistence.flyway; diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/ClassicConfigurationFlywayFixture.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/ClassicConfigurationFlywayFixture.java new file mode 100644 index 00000000..2725ccd4 --- /dev/null +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/ClassicConfigurationFlywayFixture.java @@ -0,0 +1,15 @@ +package dev.caskeleton.bootstrap.architecture.violations.persistence.flyway; + +import javax.sql.DataSource; +import org.flywaydb.core.Flyway; +import org.flywaydb.core.api.configuration.ClassicConfiguration; + +/** Builds a Flyway around {@code new ClassicConfiguration()}, the mutable configuration. */ +public class ClassicConfigurationFlywayFixture { + + public Flyway flyway(DataSource dataSource) { + ClassicConfiguration configuration = new ClassicConfiguration(); + configuration.setDataSource(dataSource); + return new Flyway(configuration); + } +} diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/ConfigureCallingFlywayFixture.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/ConfigureCallingFlywayFixture.java new file mode 100644 index 00000000..3754f095 --- /dev/null +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/ConfigureCallingFlywayFixture.java @@ -0,0 +1,12 @@ +package dev.caskeleton.bootstrap.architecture.violations.persistence.flyway; + +import javax.sql.DataSource; +import org.flywaydb.core.Flyway; + +/** Builds a Flyway from {@code Flyway.configure()} instead of the schema policy. */ +public class ConfigureCallingFlywayFixture { + + public Flyway flyway(DataSource dataSource) { + return Flyway.configure().dataSource(dataSource).load(); + } +} diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/FluentConfigurationFlywayFixture.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/FluentConfigurationFlywayFixture.java new file mode 100644 index 00000000..2f7fdea3 --- /dev/null +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/FluentConfigurationFlywayFixture.java @@ -0,0 +1,13 @@ +package dev.caskeleton.bootstrap.architecture.violations.persistence.flyway; + +import javax.sql.DataSource; +import org.flywaydb.core.Flyway; +import org.flywaydb.core.api.configuration.FluentConfiguration; + +/** Builds a Flyway from {@code new FluentConfiguration()}, the builder without the method call. */ +public class FluentConfigurationFlywayFixture { + + public Flyway flyway(DataSource dataSource) { + return new FluentConfiguration().dataSource(dataSource).load(); + } +} diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/ReferencedConfigurationFlywayFixture.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/ReferencedConfigurationFlywayFixture.java new file mode 100644 index 00000000..b8ecc0fd --- /dev/null +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/ReferencedConfigurationFlywayFixture.java @@ -0,0 +1,16 @@ +package dev.caskeleton.bootstrap.architecture.violations.persistence.flyway; + +import java.util.function.Supplier; +import javax.sql.DataSource; +import org.flywaydb.core.Flyway; +import org.flywaydb.core.api.configuration.FluentConfiguration; + +/** Builds a Flyway through a constructor reference, {@code FluentConfiguration::new}. */ +public class ReferencedConfigurationFlywayFixture { + + private final Supplier configurations = FluentConfiguration::new; + + public Flyway flyway(DataSource dataSource) { + return configurations.get().dataSource(dataSource).load(); + } +} diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/package-info.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/package-info.java new file mode 100644 index 00000000..62dfada3 --- /dev/null +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/package-info.java @@ -0,0 +1,8 @@ +/** + * "Violations-as-data" for {@code EVERY_FLYWAY_STARTS_FROM_THE_SCHEMA_POLICY}: each class builds a + * Flyway past {@code FlywaySchemaPolicy.configure()}, one way per class, and so gets Flyway's + * PostgreSQL lock default back — a lock held in a transaction that a concurrent index build waits + * for without end (re-review 2026-11-03 round 6, RR6-03-01; round 7, RR7-03-06: the rule saw only + * {@code Flyway.configure()}). + */ +package dev.caskeleton.bootstrap.architecture.violations.persistence.flyway;