fix!: 리뷰가 기록만 하고 남겨 둔 결함을 모두 고친다
문제: 확인 리뷰들이 찾은 Minor와 "남음" 항목을 고치지 않고 기록만 했다. 그중 동작에 닿는 것이 여럿이었다. verifyStrictLaneStages가 `./gradlew ci || true`, `| tee`, `if ./gradlew …` 같은 실패를 막지 못하는 명령을 실행으로 세는 거짓 통과, Redis 멱등 저장소가 lease가 지난 CLAIMED의 시작을 받아 주던 것(PostgreSQL은 거절), gRPC가 INTERNAL_ERROR 실패를 아무 데도 남기지 않고 STOMP가 SQL 원인까지 로그에 쓰던 것, 잠금 대기 검사기가 Flyway가 트랜잭션 밖에서 돌리는 VACUUM FULL을 몰라 통과시키던 것, 템플릿 패키지 목록과 버전 판정 정규식이 두 곳에 갈라져 있던 것. 방법: 영역별 4묶음이 실패 테스트를 먼저 확인하고 고쳤다(재리뷰 README 16절). - workflow run 스크립트를 bash 문법으로 읽고, 실패를 막지 못하는 명령과 셸이 실행하지 않는 줄의 cd는 이유를 대며 세지 않는다. - 두 멱등 저장소가 lease가 지난 시작을 LEASE_EXPIRED로 거절하고, executor는 아무것도 실행하지 않았으므로 503으로 답한다. - web·GraphQL·gRPC·STOMP가 shared-contract ServerFailureLog로 같은 실패 로그 줄을 쓴다(persistence 실패는 분류만). - @SystemCaller 규칙이 인터페이스로 주입한 경로도 보고, 조립 설정은 사용자 전송으로 세지 않는다. - 갈라진 복사본은 하나로: 템플릿 패키지 표가 정본이고 클래스를 대조하며, 버전 판정 코드는 grpc 빌드가 Sync로 가져와 컴파일한다. - httpclient 장애 주입 lane이 main 단계에서 두 번 돌던 것을 한 번으로. - 게이트에서 드러난 httpclient drain 스레드 경쟁: close()가 스레드를 join하고, 런타임이 닫기를 거부해도 drain 스레드를 먼저 멈춘다. 위험·한계: 목록에 넣지 않은 새 템플릿 패키지는 기능 패키지와 구별할 수 없다(문서화). 서브셸·eval·source 안의 cd 뒤 명령과 `|| exit 1`은 세지 않는다 (거짓 실패 쪽). Gradle 옵션 판독은 Gradle 9.0 동작을 TestKit으로 고정했다. 검증: 첫 ci가 httpclient ClientRuntimeRegistryTest 1건으로 실패(기존 코드의 drain 스레드 경쟁, README 16.1절) — 고친 뒤 ci 재실행 통과. 두 빌드 verifyStrictLaneStages, mainCheck, :integrationCheck, -p optional-platforms ci integrationCheck performanceCheck, :performanceCheck, :releaseCheck, compose 18 lane 통과. httpclient check·testQualityCheck·failure injection·performance lane을 수정 뒤 다시 돌려 통과. Refs: docs/reviews/2026-11-03-rereview/README.md 16절 BREAKING CHANGE: 멱등 저장소 시작·renew 결과에 LEASE_EXPIRED가 생겼고, lease가 지난 시작은 503 IDEMPOTENCY_UNAVAILABLE이다. verifyStrictLaneStages가 실패를 막지 못하는 workflow 명령을 세지 않는다.
This commit is contained in:
@@ -84,9 +84,11 @@ root `CLAUDE.md`는 이 목록의 동기화된 요약이다. 두 문서가 어
|
|||||||
줄 때문에 옵션을 별개 명령으로 떼어 내지 않는지 검사한다. 두 빌드가 각자 검사를 돌린다. `-x`로 뺀
|
줄 때문에 옵션을 별개 명령으로 떼어 내지 않는지 검사한다. 두 빌드가 각자 검사를 돌린다. `-x`로 뺀
|
||||||
lane(Gradle처럼 축약 이름도 맞춰 본다), `continue-on-error` 아래 명령, 상태 함수(`always()`·`success()`·
|
lane(Gradle처럼 축약 이름도 맞춰 본다), `continue-on-error` 아래 명령, 상태 함수(`always()`·`success()`·
|
||||||
`!cancelled()`)가 아닌 `if:` 아래 명령, `workflow_dispatch`로만 시작하는 workflow의 명령은 실행으로 세지
|
`!cancelled()`)가 아닌 `if:` 아래 명령, `workflow_dispatch`로만 시작하는 workflow의 명령은 실행으로 세지
|
||||||
않는다. 명령이 어느 빌드를 실행하는지는 `working-directory`에서 시작해 같은 셸이 그 앞에서 확실히
|
않는다. 실패해도 단계를 실패시키지 못하는 명령(`|| true`, pipefail 없는 파이프 왼쪽, `!`, `&`,
|
||||||
실행한 `cd <상대 경로>`를 따라간 뒤 `-p`를 합친 디렉터리로 정한다. 따라갈 수 없는 `cd`(`cd "$VAR"`·
|
`if`·`while` 조건과 복합 명령·함수·명령 치환 안, `set +e` 뒤, 스크립트 마지막이 아닌 `&&` 목록)과
|
||||||
`cd -`·`pushd`·조건부·서브셸 등) 뒤의 명령은 추측하지 않고 세지 않는다.
|
Gradle이 거부하는 명령줄(`-mx`)도 세지 않는다. 명령이 어느 빌드를 실행하는지는 `working-directory`에서
|
||||||
|
시작해 같은 셸이 그 앞에서 확실히 실행한 `cd <상대 경로>`를 따라간 뒤 `-p`를 합친 디렉터리로 정한다.
|
||||||
|
따라갈 수 없는 `cd`(`cd "$VAR"`·`cd -`·`pushd`·조건부·서브셸 등) 뒤의 명령은 추측하지 않고 세지 않는다.
|
||||||
|
|
||||||
작업 파일의 소유 leaf는 registry의 `source_path`로 판단하고 가장 가까운 `src/**/CLAUDE.md`를
|
작업 파일의 소유 leaf는 registry의 `source_path`로 판단하고 가장 가까운 `src/**/CLAUDE.md`를
|
||||||
함께 읽는다. focused test는 registry의 `gradle_path`에서
|
함께 읽는다. focused test는 registry의 `gradle_path`에서
|
||||||
|
|||||||
@@ -41,7 +41,9 @@ If this summary drifts from `AGENTS.md`, `AGENTS.md` wins and this summary must
|
|||||||
request; the main build and, as `-p optional-platforms`, the optional build each run their own)
|
request; the main build and, as `-p optional-platforms`, the optional build each run their own)
|
||||||
fails when a non-`explicitOnly` strict lane is in no stage a workflow executes — a lane the
|
fails when a non-`explicitOnly` strict lane is in no stage a workflow executes — a lane the
|
||||||
command removes with `-x` (abbreviations matched as Gradle does), a command under
|
command removes with `-x` (abbreviations matched as Gradle does), a command under
|
||||||
`continue-on-error` or a non-status `if:`, and a `workflow_dispatch`-only workflow do not count;
|
`continue-on-error` or a non-status `if:`, a command whose failure cannot fail its step
|
||||||
|
(`|| true`, a pipe without pipefail, an `if` condition, …), a command line Gradle rejects, and a
|
||||||
|
`workflow_dispatch`-only workflow do not count;
|
||||||
the build a command runs is its `working-directory`, then the `cd <relative path>` the same shell
|
the build a command runs is its `working-directory`, then the `cd <relative path>` the same shell
|
||||||
surely ran before it, joined with `-p` (a `cd` it cannot follow is not guessed: the command does
|
surely ran before it, joined with `-p` (a `cd` it cannot follow is not guessed: the command does
|
||||||
not count) — or a folded workflow `run:` block splits an option off its command.
|
not count) — or a folded workflow `run:` block splits an option off its command.
|
||||||
|
|||||||
@@ -107,7 +107,10 @@ transports. The JDK transport keeps its exchange-wide timeout off a streamed bod
|
|||||||
watchdog bounds each read's wait by `read-idle`, because the JDK client has no socket read timeout.
|
watchdog bounds each read's wait by `read-idle`, because the JDK client has no socket read timeout.
|
||||||
The watchdog wakes on one daemon thread of its own (`httpclient-jdk-read-idle`), not on the common
|
The watchdog wakes on one daemon thread of its own (`httpclient-jdk-read-idle`), not on the common
|
||||||
`ForkJoinPool`, so a service that fills that pool with blocking work does not delay it (re-review
|
`ForkJoinPool`, so a service that fills that pool with blocking work does not delay it (re-review
|
||||||
2026-11-04 RR3-03-01). Before review 2026-11-03 RR-04-03 every JDK download longer than
|
2026-11-04 RR3-03-01). That thread ends 60 s after the last wake it had queued and the next stream
|
||||||
|
starts it again; it inherits no thread-locals from the request thread that starts it and uses the
|
||||||
|
module's class loader as its context loader, so an idle service keeps no thread and a redeployed
|
||||||
|
application's loader is not pinned (RR4-03-04). Before review 2026-11-03 RR-04-03 every JDK download longer than
|
||||||
`response-header` was cut mid-body. A body failure after hand-over is thrown from `read` as `HttpBodyReadException` — an `IOException`, as
|
`response-header` was cut mid-body. A body failure after hand-over is thrown from `read` as `HttpBodyReadException` — an `IOException`, as
|
||||||
`InputStream` promises, so `catch (IOException)` still sees it — whose `failure()` is
|
`InputStream` promises, so `catch (IOException)` still sees it — whose `failure()` is
|
||||||
`HttpResponseTimeoutException` (a wait longer than `read-idle`) or `HttpResponseTruncatedException`
|
`HttpResponseTimeoutException` (a wait longer than `read-idle`) or `HttpResponseTruncatedException`
|
||||||
|
|||||||
@@ -52,9 +52,26 @@ goes into a migration that runs in one. A statement on a table the same migratio
|
|||||||
earlier waits for nothing and needs no bound; `CREATE TABLE IF NOT EXISTS` does not count, because
|
earlier waits for nothing and needs no bound; `CREATE TABLE IF NOT EXISTS` does not count, because
|
||||||
the table may already be there.
|
the table may already be there.
|
||||||
|
|
||||||
|
Flyway also takes a migration out of its transaction on its own, without a `.sql.conf`: on
|
||||||
|
PostgreSQL 12 and later, any statement that starts with `VACUUM`, `CREATE [UNIQUE] INDEX
|
||||||
|
CONCURRENTLY`, `DROP INDEX CONCURRENTLY`, `REINDEX [VERBOSE] SCHEMA|DATABASE|SYSTEM`, `CREATE` or
|
||||||
|
`DROP DATABASE|TABLESPACE|SUBSCRIPTION`, `ALTER SYSTEM` or `DISCARD ALL` (Flyway 11,
|
||||||
|
`PostgreSQLParser`; words inside parentheses are skipped, so `VACUUM (FULL)` and `REINDEX (VERBOSE)
|
||||||
|
SCHEMA` count). One such statement puts the whole script outside a transaction. Next to any other
|
||||||
|
statement — a `SET LOCAL lock_timeout` included — Flyway refuses the migration at deploy under its
|
||||||
|
default `mixed=false`; a service that sets `mixed=true` gets it run, with the bound silently gone.
|
||||||
|
Put such a statement in a migration of its own. `REINDEX TABLE|INDEX CONCURRENTLY` is not on
|
||||||
|
Flyway's list: Flyway runs it in the transaction, PostgreSQL refuses it there, and it needs
|
||||||
|
`executeInTransaction=false` (below). A locking statement that cannot run in a transaction at all —
|
||||||
|
`VACUUM FULL`, a non-concurrent `REINDEX SCHEMA|DATABASE|SYSTEM` — can never be bounded this way and
|
||||||
|
does not belong in a migration: run it by hand as an operations step, outside a deploy, in a psql
|
||||||
|
session that sets `SET lock_timeout = '5s';` first (the session ends with the step, so the plain
|
||||||
|
`SET` is the bound there).
|
||||||
|
|
||||||
Enforced, not remembered: `LockWaitMigrationInspector` (persistence-jpa testkit) reads a script —
|
Enforced, not remembered: `LockWaitMigrationInspector` (persistence-jpa testkit) reads a script —
|
||||||
and the `.sql.conf` beside it — and names the statements from its list that lock an existing table
|
and the `.sql.conf` beside it, as Flyway reads it (a properties file, `false` in any case), and
|
||||||
with no bound in force: `ALTER TABLE`, `LOCK TABLE`, `TRUNCATE`, `DROP TABLE`; `CREATE INDEX`,
|
otherwise the statements Flyway takes out of the transaction on its own — and names the statements
|
||||||
|
from its list that lock an existing table with no bound in force: `ALTER TABLE`, `LOCK TABLE`, `TRUNCATE`, `DROP TABLE`; `CREATE INDEX`,
|
||||||
`DROP INDEX`, `REINDEX` and `REFRESH MATERIALIZED VIEW` without `CONCURRENTLY`, `CLUSTER`, `VACUUM
|
`DROP INDEX`, `REINDEX` and `REFRESH MATERIALIZED VIEW` without `CONCURRENTLY`, `CLUSTER`, `VACUUM
|
||||||
FULL`; `REFERENCES` on the table it references, in a new table as much as in an `ALTER TABLE` (a
|
FULL`; `REFERENCES` on the table it references, in a new table as much as in an `ALTER TABLE` (a
|
||||||
foreign key locks its parent against writes while it is added); `CREATE TRIGGER` and `DROP TRIGGER`
|
foreign key locks its parent against writes while it is added); `CREATE TRIGGER` and `DROP TRIGGER`
|
||||||
@@ -67,16 +84,24 @@ stay that way (they are applied, and applied files are never edited); the test l
|
|||||||
refuses any new one. `PostgreSqlMigrationLockWaitIntegrationTest`
|
refuses any new one. `PostgreSqlMigrationLockWaitIntegrationTest`
|
||||||
(`postgresqlMigrationLockWaitIntegrationTest`) shows on real PostgreSQL that a bounded migration
|
(`postgresqlMigrationLockWaitIntegrationTest`) shows on real PostgreSQL that a bounded migration
|
||||||
gives up within the bound while another transaction holds the table, and leaves the version below
|
gives up within the bound while another transaction holds the table, and leaves the version below
|
||||||
it. The gRPC ledger's tree lives in the optional build, which cannot reach the testkit: its
|
it; it also holds the inspector's copy of Flyway's list to Flyway itself (the statements it names
|
||||||
`GrpcOperationLedgerMigrationLockWaitIT` runs every ledger migration after V001, read from the tree,
|
are exactly those Flyway refuses next to a `SET LOCAL`), and shows a `VACUUM FULL` run under
|
||||||
against a held ledger instead, so its next migration is checked on real PostgreSQL. The rule came
|
`mixed=true` waiting out a reader despite its `SET LOCAL`. The gRPC ledger's tree lives in the
|
||||||
from V21 having the bound and V22, in the same commit, not having it (re-review 2026-11-03 round 2,
|
optional build, which cannot depend on the testkit: its `GrpcOperationLedgerMigrationLockWaitIT`
|
||||||
RR-02-09; round 3, RR3-02-01, RR3-02-03, RR3-02-04).
|
runs every ledger migration after V001, read from the tree, against a held ledger instead, so its
|
||||||
|
next migration is checked on real PostgreSQL. It finds and orders that tree with the testkit's own
|
||||||
|
`VersionedMigrationFiles`, which the ledger's `build.gradle` copies into its integration-test sources
|
||||||
|
at build time (`sharedMigrationFileSources`), so both builds read one definition. The rule came from
|
||||||
|
V21 having the bound and V22, in the same commit, not having it (re-review 2026-11-03 round 2,
|
||||||
|
RR-02-09; round 3, RR3-02-01, RR3-02-03, RR3-02-04; round 4, RR4-02-01).
|
||||||
|
|
||||||
## Concurrent index builds
|
## Concurrent index builds
|
||||||
|
|
||||||
`CREATE INDEX CONCURRENTLY` cannot run inside a transaction block, and Flyway wraps migrations in
|
`CREATE INDEX CONCURRENTLY` cannot run inside a transaction block, and Flyway wraps migrations in
|
||||||
one by default. The migration therefore needs a companion configuration:
|
one by default. Flyway recognizes `CREATE`/`DROP INDEX CONCURRENTLY` and runs such a script outside
|
||||||
|
the transaction on its own (above), but not `REINDEX … CONCURRENTLY`; write the companion
|
||||||
|
configuration for every concurrent statement anyway, so the file says what it needs and no reader
|
||||||
|
has to know Flyway's list:
|
||||||
|
|
||||||
```conf
|
```conf
|
||||||
# V42__order_index.sql.conf
|
# V42__order_index.sql.conf
|
||||||
|
|||||||
@@ -131,7 +131,10 @@ capability 스트림 db/migration/jpa/<capability> 각자 histor
|
|||||||
- 운영 중인 테이블을 잠그는 문장(`ALTER TABLE`, `CONCURRENTLY` 없는 `CREATE INDEX`, `UPDATE`·`DELETE`, 기존
|
- 운영 중인 테이블을 잠그는 문장(`ALTER TABLE`, `CONCURRENTLY` 없는 `CREATE INDEX`, `UPDATE`·`DELETE`, 기존
|
||||||
테이블을 가리키는 `REFERENCES`, trigger 만들기·지우기 등 — 전체 목록은 `docs/jpa/migration-guide.md`)이 있으면
|
테이블을 가리키는 `REFERENCES`, trigger 만들기·지우기 등 — 전체 목록은 `docs/jpa/migration-guide.md`)이 있으면
|
||||||
그 앞에 `SET LOCAL lock_timeout = '5s';`를 둔다(`V8_1`, `V22`). 값은 0이 아니어야 하고,
|
그 앞에 `SET LOCAL lock_timeout = '5s';`를 둔다(`V8_1`, `V22`). 값은 0이 아니어야 하고,
|
||||||
`executeInTransaction=false` 마이그레이션에서는 `SET LOCAL`이 효과가 없으니 잠그는 문장을 거기 두지 않는다. 상한이 없으면 그 테이블을 건드린 열린
|
`executeInTransaction=false` 마이그레이션에서는 `SET LOCAL`이 효과가 없으니 잠그는 문장을 거기 두지 않는다. Flyway가
|
||||||
|
스스로 트랜잭션 밖에서 돌리는 문장(`VACUUM`, `CREATE INDEX CONCURRENTLY` 등 — 목록은 같은 가이드)이 하나라도 있는 파일도
|
||||||
|
트랜잭션 밖에서 돌므로, 그런 문장은 따로 한 파일에 둔다. `VACUUM FULL`처럼 트랜잭션 안에서 돌 수 없는 잠금 문장은
|
||||||
|
상한을 걸 수 없으니 마이그레이션에 두지 않고 운영 절차로 돌린다. 상한이 없으면 그 테이블을 건드린 열린
|
||||||
트랜잭션 하나(`ALTER TABLE`이면 읽기만 한 것도) 뒤에서 마이그레이션이 끝없이 기다리고, 그동안 뒤에 온 그
|
트랜잭션 하나(`ALTER TABLE`이면 읽기만 한 것도) 뒤에서 마이그레이션이 끝없이 기다리고, 그동안 뒤에 온 그
|
||||||
테이블의 쓰기(`ALTER TABLE`이면 읽기까지)가 모두 마이그레이션 뒤에 줄을 선다. 상한이 있으면 5초 뒤 실패·롤백되고 새 버전이 뜨지 않을 뿐이다. 자기 스트림에도
|
테이블의 쓰기(`ALTER TABLE`이면 읽기까지)가 모두 마이그레이션 뒤에 줄을 선다. 상한이 있으면 5초 뒤 실패·롤백되고 새 버전이 뜨지 않을 뿐이다. 자기 스트림에도
|
||||||
`SampleMigrationLockWaitTest`처럼 `LockWaitMigrationInspector`(persistence-jpa testkit) 검사를 둔다
|
`SampleMigrationLockWaitTest`처럼 `LockWaitMigrationInspector`(persistence-jpa testkit) 검사를 둔다
|
||||||
|
|||||||
@@ -49,21 +49,35 @@ DB 커밋 중 연결 끊김 ─────────────────
|
|||||||
| --- | --- | --- |
|
| --- | --- | --- |
|
||||||
| 409 `IDEMPOTENT_IN_FLIGHT`, `retryable=true`, `Retry-After: 2` | 같은 키가 아직 실행 중. 결과 불명 | **같은 키로** 기다렸다 재전송. 새 키 금지 |
|
| 409 `IDEMPOTENT_IN_FLIGHT`, `retryable=true`, `Retry-After: 2` | 같은 키가 아직 실행 중. 결과 불명 | **같은 키로** 기다렸다 재전송. 새 키 금지 |
|
||||||
| 422 `IDEMPOTENT_REQUEST_MISMATCH` | 같은 키에 다른 본문 | 클라이언트 버그. 재전송 안 함 |
|
| 422 `IDEMPOTENT_REQUEST_MISMATCH` | 같은 키에 다른 본문 | 클라이언트 버그. 재전송 안 함 |
|
||||||
| 503 `IDEMPOTENCY_UNAVAILABLE` | 실행 전 거부 | 같은 키로 나중에 |
|
| 503 `IDEMPOTENCY_UNAVAILABLE` | 실행 전 거부(저장소 응답 없음, 또는 claim의 lease가 시작 전에 끝남) | 같은 키로 나중에 |
|
||||||
| 503 `IDEMPOTENCY_COMPLETION_UNKNOWN`, `retryable=true` | 실행 뒤 결과 기록 실패. 적용됐을 수 있음 | "적용 안 됨"이라 하지 않는다. **같은 키로** 나중에 재전송, 새 키 금지 |
|
| 503 `IDEMPOTENCY_COMPLETION_UNKNOWN`, `retryable=true` | 실행 뒤 결과 기록 실패. 적용됐을 수 있음 | "적용 안 됨"이라 하지 않는다. **같은 키로** 나중에 재전송, 새 키 금지 |
|
||||||
| 500 `IDEMPOTENCY_RECOVERY_REQUIRED` | 이전 시도 효과를 증명 못함 | 자동 재시도 안 함. 같은 키 재전송은 안전(재생·실행·다시 500을 서버가 판정, 다시 돌리지 않음). 업무 데이터로 확인하고, 효과가 없다고 확인된 뒤에만 운영 절차에 따라 새 키 |
|
| 500 `IDEMPOTENCY_RECOVERY_REQUIRED` | 이전 시도 효과를 증명 못함 | 자동 재시도 안 함. 같은 키 재전송은 안전(재생·실행·다시 500을 서버가 판정, 다시 돌리지 않음). 업무 데이터로 확인하고, 효과가 없다고 확인된 뒤에만 운영 절차에 따라 새 키 |
|
||||||
| 500 `DB_COMPLETION_UNKNOWN`, `retryable=false` | DB 커밋 중 연결 끊김. 커밋됐을 수도 있음 | 키 없이 재시도 금지. KEYED면 같은 키로 재전송하면 서버가 판정 |
|
| 500 `DB_COMPLETION_UNKNOWN`, `retryable=false` | DB 커밋 중 연결 끊김. 커밋됐을 수도 있음 | 키 없이 재시도 금지. KEYED면 같은 키로 재전송하면 서버가 판정 |
|
||||||
|
|
||||||
같은 키 재전송은 작업을 다시 돌리지 않는다. 첫 시도가 실행을 시작한 뒤 processing lease(기본 30s)가
|
같은 키 재전송은 작업을 다시 돌리지 않는다. 다만 첫 시도가 processing lease(기본 30s)보다 오래 걸릴 때
|
||||||
지나면 두 저장소 모두 그 기록을 넘겨주지 않고 500 `IDEMPOTENCY_RECOVERY_REQUIRED`로 답한다. 넘겨받는 것은
|
보이는 모습은 저장소마다 다르다(재리뷰 2026-11-04 RR5-01-05, 정본 `docs/web/http-contract.md` 2절).
|
||||||
실행 전 claim과 재시도 가능한 실패뿐이다. 이 답은 기록을 바꾸지 않는다. executor는 lease를 늘리지 않아
|
|
||||||
30s를 넘는 정상 요청도 lease가 지나는데, 그 첫 시도가 나중에 끝나면 결과가 기록되고 첫 요청은 정상 응답을
|
- **Redis**: 첫 시도가 실행을 시작한 뒤 lease가 지나면 그 기록을 넘겨주지 않고 500
|
||||||
받으며 그 뒤 같은 키 요청은 그 결과를 재생한다(2026-11-04 소유자 결정). 기록은 lease + `replay-ttl` 동안
|
`IDEMPOTENCY_RECOVERY_REQUIRED`로 답한다. 넘겨받는 것은 실행 전 claim과 재시도 가능한 실패뿐이다. 이 답은
|
||||||
남고, `replay-ttl`이 lease보다 짧으면 기동이 실패한다(`IdempotencyStoreContract`, 재리뷰 2026-11-04
|
기록을 바꾸지 않는다. executor는 lease를 늘리지 않아 30s를 넘는 정상 요청도 lease가 지나는데, 그 첫
|
||||||
RR-01-11·RR-03-11). 작업이 실패로 끝나 executor가 포기나 재시도 가능으로 표시한 기록은 표시한 때부터
|
시도가 나중에 끝나면 결과가 기록되고 첫 요청은 정상 응답을 받으며 그 뒤 같은 키 요청은 그 결과를
|
||||||
`failure-retention`(기본 24h) 동안 남는다. `failure-retention`이 `replay-ttl`보다 짧으면 기동이 실패한다.
|
재생한다(2026-11-04 소유자 결정).
|
||||||
|
- **PostgreSQL**: executor를 유스케이스의 쓰기 트랜잭션 하나 안에서 부르면(템플릿의 모양) claim 기록은 그
|
||||||
|
트랜잭션과 함께 커밋되거나 롤백된다. 같은 키 요청은 409·500 대신 첫 요청이 끝날 때까지 기다렸다가
|
||||||
|
재생(커밋)이나 새 실행(롤백)을 받는다. 작업이 예외로 끝나면 실패 기록도 함께 롤백되어 다음 같은 키
|
||||||
|
요청이 다시 실행한다. 쓰기 트랜잭션 제한(기본 30s)을 넘긴 요청도 기록과 함께 롤백된다
|
||||||
|
(`DB_QUERY_CANCELED`). 그래서 이 저장소가 막는 중복은 같은 트랜잭션 안의 DB 효과다. 트랜잭션 밖 효과는
|
||||||
|
다음 요청에서 다시 일어날 수 있다.
|
||||||
|
|
||||||
|
claim의 lease가 작업 시작 전에 끝나면 두 저장소 모두 시작을 거절하고(`LEASE_EXPIRED`), executor는 작업을
|
||||||
|
돌리지 않은 채 503 `IDEMPOTENCY_UNAVAILABLE`로 답한다. 다음 같은 키 요청이 그 claim을 넘겨받아 실행한다.
|
||||||
|
기록은 lease + `replay-ttl` 동안 남고, `replay-ttl`이 lease보다 짧으면 기동이 실패한다
|
||||||
|
(`IdempotencyStoreContract`, 재리뷰 2026-11-04 RR-01-11·RR-03-11). 작업이 실패로 끝나 executor가 포기나
|
||||||
|
재시도 가능으로 표시한 기록은 표시한 때부터 `failure-retention`(기본 24h) 동안 남는다(PostgreSQL을 트랜잭션
|
||||||
|
하나로 쓰면 위처럼 롤백과 함께 사라진다). `failure-retention`이 `replay-ttl`보다 짧으면 기동이 실패한다.
|
||||||
짧으면 효과 불명으로 포기한 기록이 먼저 사라져 같은 키 재전송이 작업을 다시 돌리기 때문이다(RR3-03-02,
|
짧으면 효과 불명으로 포기한 기록이 먼저 사라져 같은 키 재전송이 작업을 다시 돌리기 때문이다(RR3-03-02,
|
||||||
2026-11-04 소유자 결정).
|
2026-11-04 소유자 결정). 거꾸로 말하면 `replay-ttl`(`APP_IDEMPOTENCY_TTL`)은 lease 이상, `failure-retention`
|
||||||
|
이하로 둔다.
|
||||||
|
|
||||||
409를 `retryable=true`로 바꾼 이유(리뷰 02-01 결정): 같은 키 재전송은 서버가 안전하게 판정하므로 다시
|
409를 `retryable=true`로 바꾼 이유(리뷰 02-01 결정): 같은 키 재전송은 서버가 안전하게 판정하므로 다시
|
||||||
보내는 것이 맞고, 새 키로 보내면 서버가 막지 못한다. 짝 프론트 분류기도 이 표를 따른다.
|
보내는 것이 맞고, 새 키로 보내면 서버가 막지 못한다. 짝 프론트 분류기도 이 표를 따른다.
|
||||||
|
|||||||
@@ -72,7 +72,8 @@ JWT의 `realm_access.roles`와 **자기 client**(`app.security.audience`)의 `re
|
|||||||
|
|
||||||
```text
|
```text
|
||||||
사용자 요청 ─▶ web·GraphQL·gRPC·WebSocket ──✗──▶ @SystemInvoked 유스케이스 (빌드 실패)
|
사용자 요청 ─▶ web·GraphQL·gRPC·WebSocket ──✗──▶ @SystemInvoked 유스케이스 (빌드 실패)
|
||||||
사용자 요청 ─▶ web·GraphQL·gRPC·WebSocket ──✗──▶ @SystemCaller (빌드 실패, 중간 클래스를 거쳐도)
|
사용자 요청 ─▶ web·GraphQL·gRPC·WebSocket ──✗──▶ @SystemCaller (빌드 실패, 중간 클래스·작업의 인터페이스를 거쳐도.
|
||||||
|
타입을 거치지 않는 길은 아래 「규칙이 못 보는 길」)
|
||||||
시스템 ─▶ 스케줄러(조립 모듈이 new로 넘김) ─────▶ @SystemInvoked 유스케이스
|
시스템 ─▶ 스케줄러(조립 모듈이 new로 넘김) ─────▶ @SystemInvoked 유스케이스
|
||||||
시스템 ─▶ 메시지 handler(@SystemCaller, 직접 new) ─▶ @SystemInvoked 유스케이스
|
시스템 ─▶ 메시지 handler(@SystemCaller, 직접 new) ─▶ @SystemInvoked 유스케이스
|
||||||
시스템 ─▶ 예약 작업(@SystemCaller, 직접 new) ──────▶ @SystemInvoked 유스케이스
|
시스템 ─▶ 예약 작업(@SystemCaller, 직접 new) ──────▶ @SystemInvoked 유스케이스
|
||||||
@@ -89,7 +90,7 @@ JWT의 `realm_access.roles`와 **자기 client**(`app.security.audience`)의 `re
|
|||||||
| --- | --- | --- |
|
| --- | --- | --- |
|
||||||
| 조립 모듈의 스케줄러 | `composition:*` leaf. 예: outbox relay(`src/composition/outbox-relay`) | 조립 모듈의 `@Bean` 메서드가 `new`로 만들어 스케줄러에 넘긴다 |
|
| 조립 모듈의 스케줄러 | `composition:*` leaf. 예: outbox relay(`src/composition/outbox-relay`) | 조립 모듈의 `@Bean` 메서드가 `new`로 만들어 스케줄러에 넘긴다 |
|
||||||
| 메시지 handler | `adapter:inbound:messaging` leaf, 또는 서비스 leaf의 `..adapter.inbound.messaging..` 패키지 | handler 생성자가 port를 받아 `new`로 만든다. handler에 `@SystemCaller`. 작업 순서는 09장 「소비」 4단계 |
|
| 메시지 handler | `adapter:inbound:messaging` leaf, 또는 서비스 leaf의 `..adapter.inbound.messaging..` 패키지 | handler 생성자가 port를 받아 `new`로 만든다. handler에 `@SystemCaller`. 작업 순서는 09장 「소비」 4단계 |
|
||||||
| 예약 작업 | 서비스 자기 leaf의 `..adapter.inbound.scheduler..` 패키지. 등록된 scheduler leaf는 없다 | 작업 클래스 생성자가 port를 받아 `new`로 만든다. 작업 클래스에 `@SystemCaller`. 모양은 메시지 handler와 같고, 깨우는 것이 `@Scheduled` 메서드다 |
|
| 예약 작업 | 서비스 자기 leaf의 `..adapter.inbound.scheduler..` 패키지. 등록된 scheduler leaf는 없다 | 작업 클래스 생성자가 port를 받아 `new`로 만든다. 작업 클래스에 `@SystemCaller`. 모양은 메시지 handler와 같고, 깨우는 것이 `@Scheduled` 메서드다. `Runnable`·`ApplicationRunner` 같은 프로젝트 밖 타입을 구현하지 않는다. task scheduler에 직접 등록하면 그 자리에서 `job::run`을 넘긴다 |
|
||||||
|
|
||||||
예약 작업은 controller와 같은 leaf에 놓이기 쉽다. 그때 "지금 실행" endpoint가 작업 bean을 주입받아 부르면
|
예약 작업은 controller와 같은 leaf에 놓이기 쉽다. 그때 "지금 실행" endpoint가 작업 bean을 주입받아 부르면
|
||||||
권한 검사 없는 쓰기를 사용자가 부르게 된다. 아래 `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`가 이것을
|
권한 검사 없는 쓰기를 사용자가 부르게 된다. 아래 `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`가 이것을
|
||||||
@@ -101,7 +102,8 @@ JWT의 `realm_access.roles`와 **자기 client**(`app.security.audience`)의 `re
|
|||||||
| bean 금지 | `@SystemInvoked` 유스케이스가 bean이면 기동 실패. 호출자가 `new`로 만들어 혼자 들고 있는 것만 허용한다 | `src/composition/service-runtime/src/main/java/dev/caskeleton/composition/runtime/authorization/PermissionEnforcementGuard.java` |
|
| bean 금지 | `@SystemInvoked` 유스케이스가 bean이면 기동 실패. 호출자가 `new`로 만들어 혼자 들고 있는 것만 허용한다 | `src/composition/service-runtime/src/main/java/dev/caskeleton/composition/runtime/authorization/PermissionEnforcementGuard.java` |
|
||||||
| 시스템 호출자만 | inbound adapter가 그 클래스에 의존하면 빌드 실패. `@SystemCaller(reason = "...")`를 단 클래스와 그 안에 중첩된 클래스만 예외 | `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`(`ApplicationBoundaryArchitectureTest`) |
|
| 시스템 호출자만 | inbound adapter가 그 클래스에 의존하면 빌드 실패. `@SystemCaller(reason = "...")`를 단 클래스와 그 안에 중첩된 클래스만 예외 | `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`(`ApplicationBoundaryArchitectureTest`) |
|
||||||
| 표시 검사 | `@SystemCaller` 클래스와 그 안에 중첩된 클래스는 `..adapter.inbound.messaging..`·`..adapter.inbound.scheduler..`에만 있고, 사용자 전송 타입(controller·JAX-RS·GraphQL·STOMP mapping·gRPC·servlet)에 의존하지 않는다 | `SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`(같은 파일) |
|
| 표시 검사 | `@SystemCaller` 클래스와 그 안에 중첩된 클래스는 `..adapter.inbound.messaging..`·`..adapter.inbound.scheduler..`에만 있고, 사용자 전송 타입(controller·JAX-RS·GraphQL·STOMP mapping·gRPC·servlet)에 의존하지 않는다 | `SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`(같은 파일) |
|
||||||
| 전송 → 시스템 호출자 금지 | 사용자 전송 클래스가 `@SystemCaller`에 의존하면 빌드 실패. 중간 클래스를 거쳐도 잡는다. 사용자 전송 클래스는 사용자 전송 패키지에 있거나 사용자 전송 타입에 의존하는 클래스다. 그래서 handler를 bean으로 등록하는 `@Configuration`은 걸리지 않는다 | `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`(같은 파일) |
|
| 전송 → 시스템 호출자 금지 | 사용자 전송 클래스가 `@SystemCaller`나, 그 클래스가 구현·상속하는 프로젝트 타입(작업의 인터페이스 등)에 의존하면 빌드 실패. 중간 클래스를 거쳐도 잡는다. 사용자 전송 클래스는 사용자 전송 패키지에 있는 클래스, 또는 사용자 전송 타입에 의존하는 클래스 가운데 설정(`@Configuration`·`@AutoConfiguration`)이 아닌 것이다. 그래서 handler를 bean으로 등록하는 설정은 같은 클래스에서 `WebMvcConfigurer`·interceptor·controller bean을 함께 만들어도 걸리지 않는다. 설정이 만드는 controller는 controller 자신이 검사받는다 | `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`(같은 파일) |
|
||||||
|
| 프로젝트 밖 상위 타입 금지 | `@SystemCaller` 클래스와 그 안에 중첩된 클래스(익명·지역 클래스 제외)는 프로젝트(`dev.caskeleton..`) 밖의 클래스·인터페이스를 상속·구현하지 않는다. `Runnable`은 누구나 의존하는 타입이라, endpoint가 작업을 `Runnable`로 주입받아도 위 규칙이 다른 사용과 구별하지 못하기 때문이다. 메시지 handler의 `MessageHandler<T>`는 프로젝트 타입이라 된다 | `SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`(같은 파일) |
|
||||||
|
|
||||||
규칙은 "누가 닿으면 안 되나"가 아니라 "누가 닿아도 되나"를 적는다. 이 성질은 **패키지** 쪽에서만 온다.
|
규칙은 "누가 닿으면 안 되나"가 아니라 "누가 닿아도 되나"를 적는다. 이 성질은 **패키지** 쪽에서만 온다.
|
||||||
패키지는 허용 목록이라, 나중에 새 전송 패키지가 생겨도 따로 고치지 않아도 막힌다. 사용자 전송 **타입**
|
패키지는 허용 목록이라, 나중에 새 전송 패키지가 생겨도 따로 고치지 않아도 막힌다. 사용자 전송 **타입**
|
||||||
@@ -109,13 +111,30 @@ JWT의 `realm_access.roles`와 **자기 client**(`app.security.audience`)의 `re
|
|||||||
목록이라, 목록에 없는 전송 라이브러리로 만든 endpoint는 전송으로 보이지 않는다. 새 전송 라이브러리를
|
목록이라, 목록에 없는 전송 라이브러리로 만든 endpoint는 전송으로 보이지 않는다. 새 전송 라이브러리를
|
||||||
들이면 그 패키지를 이 목록에 더한다.
|
들이면 그 패키지를 이 목록에 더한다.
|
||||||
|
|
||||||
이 규칙들은 클래스 의존만 본다. 실행 중에 bean을 찾는 코드(`getBean`, `ObjectProvider`)는 의존이 아니라서
|
|
||||||
잡지 못한다.
|
|
||||||
|
|
||||||
D4 실패(`MUTATING_USE_CASES_DECLARE_REQUIRED_PERMISSION`)를 끄려고 이 표시를 쓰지 않는다. 사용자가 부르는
|
D4 실패(`MUTATING_USE_CASES_DECLARE_REQUIRED_PERMISSION`)를 끄려고 이 표시를 쓰지 않는다. 사용자가 부르는
|
||||||
쓰기라면 권한을 선언하고 역할에 매핑한다. 같은 쓰기를 사용자도 시스템도 부르면 유스케이스를 둘로 나눈다
|
쓰기라면 권한을 선언하고 역할에 매핑한다. 같은 쓰기를 사용자도 시스템도 부르면 유스케이스를 둘로 나눈다
|
||||||
(사용자용 `@RequiresPermission`, 시스템용 `@SystemInvoked`). 업무 규칙은 domain에 두고 둘이 같이 쓴다.
|
(사용자용 `@RequiresPermission`, 시스템용 `@SystemInvoked`). 업무 규칙은 domain에 두고 둘이 같이 쓴다.
|
||||||
|
|
||||||
|
### 규칙이 못 보는 길
|
||||||
|
|
||||||
|
이 규칙들은 클래스 의존만 본다. 그래서 타입 이름이 코드에 남는 길은 모두 잡는다. `ObjectProvider<작업 클래스>`,
|
||||||
|
`getBean(작업 클래스.class)`, 작업의 인터페이스 주입이 여기에 든다. 타입 이름이 남지 않는 길은 못 본다.
|
||||||
|
|
||||||
|
- 이름이나 `Object`로 bean을 찾는 코드: `getBean("nightlyJob")`, `Map<String, Object>` 주입 뒤 reflection 호출.
|
||||||
|
- 설정이 사용자 전송에 작업을 감싼 함수를 넘기는 코드: `new RunNowController(job::run)`처럼 controller는
|
||||||
|
`Runnable`만 받는다. 의존은 설정 → 작업 쪽에만 있고, 설정은 사용자 전송이 아니다.
|
||||||
|
|
||||||
|
이 길을 막는 것은 ArchUnit 규칙이 아니라 다음 셋이다.
|
||||||
|
|
||||||
|
- `@SystemInvoked` 유스케이스는 bean이 아니고(`PermissionEnforcementGuard`), 시스템 호출자가 `new`로 만들어
|
||||||
|
혼자 든다. 그래서 사용자 전송은 시스템 호출자 객체를 거치지 않고는 그 유스케이스를 부를 수 없다.
|
||||||
|
- 의존 방향 게이트(`src/config/architecture/modules.json`): 등록된 leaf 가운데 `adapter:inbound:messaging`에
|
||||||
|
의존할 수 있는 것은 조립 루트(`app-bootstrap`)뿐이다. 다른 leaf의 사용자 전송은 handler 타입을 컴파일조차
|
||||||
|
못 한다. 예약 작업은 서비스 자기 leaf에 있어서 같은 leaf의 controller와 사이에는 이 게이트가 없다. 그래서
|
||||||
|
위 두 길은 사실상 controller와 작업이 같은 leaf에 있을 때, 또는 둘을 모두 보는 설정에서 생긴다.
|
||||||
|
- 리뷰: 설정에서 시스템 호출자를 함수로 감싸 다른 bean에 넘기거나, 사용자 전송이 bean을 이름으로 찾는 코드는
|
||||||
|
리뷰에서 거절한다. 사용자도 같은 일을 시켜야 하면 위 문단대로 사용자용 유스케이스를 따로 만든다.
|
||||||
|
|
||||||
## web 없는 조립
|
## web 없는 조립
|
||||||
|
|
||||||
web이 빠진 조립(gRPC 전용·배치 전용)에는 `@RequiresPermission`을 검사할 advisor가 없다. 그런 조립에
|
web이 빠진 조립(gRPC 전용·배치 전용)에는 `@RequiresPermission`을 검사할 advisor가 없다. 그런 조립에
|
||||||
@@ -127,6 +146,7 @@ web이 빠진 조립(gRPC 전용·배치 전용)에는 `@RequiresPermission`을
|
|||||||
- 쓰기 = `@RequiresPermission` + non-final + bean + 역할 매핑.
|
- 쓰기 = `@RequiresPermission` + non-final + bean + 역할 매핑.
|
||||||
- 시스템만 부르는 쓰기 = `@SystemInvoked` + bean 아님 + 사용자 전송에서 안 닿음. 부르는 쪽은 셋뿐이다:
|
- 시스템만 부르는 쓰기 = `@SystemInvoked` + bean 아님 + 사용자 전송에서 안 닿음. 부르는 쪽은 셋뿐이다:
|
||||||
조립 모듈의 스케줄러, `@SystemCaller` 메시지 handler, `@SystemCaller` 예약 작업. 사용자 전송은
|
조립 모듈의 스케줄러, `@SystemCaller` 메시지 handler, `@SystemCaller` 예약 작업. 사용자 전송은
|
||||||
`@SystemCaller`에도 닿지 못한다.
|
`@SystemCaller`에도, 그 작업의 인터페이스에도 닿지 못한다. 타입 이름이 남지 않는 길(이름으로 찾기,
|
||||||
|
설정이 넘기는 함수)은 빌드가 못 보니 리뷰가 막는다.
|
||||||
- 객체 판정은 유스케이스 안, 남의 것은 404.
|
- 객체 판정은 유스케이스 안, 남의 것은 404.
|
||||||
- 역할은 자기 client 것만 읽는다.
|
- 역할은 자기 client 것만 읽는다.
|
||||||
|
|||||||
@@ -1601,9 +1601,11 @@ env_keys:
|
|||||||
|
|
||||||
- name: APP_IDEMPOTENCY_TTL
|
- name: APP_IDEMPOTENCY_TTL
|
||||||
# app.capabilities.idempotency.replay-ttl: how long a completed response stays
|
# app.capabilities.idempotency.replay-ttl: how long a completed response stays
|
||||||
# replayable. One value for every provider; IdempotencySettings refuses more than 72h, and less
|
# replayable. One value for every provider; IdempotencySettings refuses more than 72h, less than
|
||||||
# than APP_IDEMPOTENCY_PROCESSING_LEASE, at startup (re-review 2026-11-04 RR-03-11). Each record
|
# APP_IDEMPOTENCY_PROCESSING_LEASE (re-review 2026-11-04 RR-03-11), and more than
|
||||||
# lives for the processing lease plus this value in both stores.
|
# APP_IDEMPOTENCY_FAILURE_RETENTION (RR3-03-02, owner decision 2026-11-04), at startup: raising
|
||||||
|
# this key alone past the failure retention (default 24h) fails startup, so raise both
|
||||||
|
# (RR5-03-01). Each record lives for the processing lease plus this value in both stores.
|
||||||
type: duration
|
type: duration
|
||||||
default: 24h
|
default: 24h
|
||||||
allowed_values: null
|
allowed_values: null
|
||||||
@@ -1611,7 +1613,7 @@ env_keys:
|
|||||||
required: false
|
required: false
|
||||||
reload_policy: restart-only
|
reload_policy: restart-only
|
||||||
owner_branch: feature-rate-limit-idempotency-contract
|
owner_branch: feature-rate-limit-idempotency-contract
|
||||||
validation: spring_duration_shorthand_le_72h_ge_processing_lease
|
validation: spring_duration_shorthand_le_72h_ge_processing_lease_le_failure_retention
|
||||||
compatibility_impact: behavior-change
|
compatibility_impact: behavior-change
|
||||||
required_test: idempotency-contract:ttl-applied
|
required_test: idempotency-contract:ttl-applied
|
||||||
|
|
||||||
|
|||||||
@@ -324,3 +324,40 @@ PR #1을 만든 뒤 사용자가 묶음이 기본값으로 정한 세 가지를
|
|||||||
리뷰어 1명([round5/review.md](round5/review.md)): Critical 0, **Important 0**, 회귀 0, Minor 9(7건은 이 커밋, 2건은 이전부터). 결정 ①②③이 코드·공유 계약·문서에 결정대로 들어갔고, lease가 지난 `EXECUTING`을 다시 실행하는 경로는 남지 않았으며, PostgreSQL과 Redis가 같은 판정을 한다.
|
리뷰어 1명([round5/review.md](round5/review.md)): Critical 0, **Important 0**, 회귀 0, Minor 9(7건은 이 커밋, 2건은 이전부터). 결정 ①②③이 코드·공유 계약·문서에 결정대로 들어갔고, lease가 지난 `EXECUTING`을 다시 실행하는 경로는 남지 않았으며, PostgreSQL과 Redis가 같은 판정을 한다.
|
||||||
|
|
||||||
Minor 중 RR5-01-01(`IDEMPOTENCY_RECOVERY_REQUIRED`의 클라이언트 안내가 `http-contract.md` 표·매뉴얼 05 표·runbook에서 서로 다름 — 표는 "새 키 금지", runbook은 "효과가 없으면 새 키")은 오케스트레이터가 이번 커밋에서 만든 모순이라 바로 고쳤다: 세 문서와 프론트 인계 문서를 "자동 재시도 안 함, 같은 키 재전송은 안전(서버가 판정하고 다시 돌리지 않음), 효과가 없다고 확인된 뒤에만 운영 절차에 따라 새 키"로 맞췄다. 나머지 Minor 8건은 11.1절 결정대로 기록만 한다(round5/review.md) — 그중 RR5-02-01은 heredoc·호출하지 않은 함수·여러 줄 문자열 안의 `cd`도 따라간다는 것으로, 이 repo에서는 그 step이 실패해 조용한 거짓 통과는 아니다.
|
Minor 중 RR5-01-01(`IDEMPOTENCY_RECOVERY_REQUIRED`의 클라이언트 안내가 `http-contract.md` 표·매뉴얼 05 표·runbook에서 서로 다름 — 표는 "새 키 금지", runbook은 "효과가 없으면 새 키")은 오케스트레이터가 이번 커밋에서 만든 모순이라 바로 고쳤다: 세 문서와 프론트 인계 문서를 "자동 재시도 안 함, 같은 키 재전송은 안전(서버가 판정하고 다시 돌리지 않음), 효과가 없다고 확인된 뒤에만 운영 절차에 따라 새 키"로 맞췄다. 나머지 Minor 8건은 11.1절 결정대로 기록만 한다(round5/review.md) — 그중 RR5-02-01은 heredoc·호출하지 않은 함수·여러 줄 문자열 안의 `cd`도 따라간다는 것으로, 이 repo에서는 그 step이 실패해 조용한 거짓 통과는 아니다.
|
||||||
|
|
||||||
|
## 16. 남은 결함 전부 수정 r9 (2026-11-05)
|
||||||
|
|
||||||
|
소유자 지시: "보고할 때 남은 문제가 없어야 한다." 11.1절의 "Minor는 기록만" 결정을 거두고, 리뷰가 찾고 기록만 했던 것(13절 Minor 7건, 15.2절 Minor 8건, 10·12·15절 "남음", 원래 리뷰 16.3절)을 영역 묶음 4개가 `c508b1ba`에서 고쳤다. 고치다 새로 찾은 영역 안의 결함도 고쳤다.
|
||||||
|
|
||||||
|
| 묶음 | 항목 | 처리 | 검증 (에이전트) | 결정 |
|
||||||
|
|---|---|---|---|---|
|
||||||
|
| r9-a core·inbound | RR4-01-01, RR4-01-02, `graphql..` fixture, 원래 리뷰 16.3, RR4-03-03 | 규칙 대상을 `@SystemCaller`와 그 프로젝트 상위 타입으로 넓히고 `SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`(프로젝트 밖 타입 구현 금지)를 더했다(RED). `@Configuration`·`@AutoConfiguration`은 사용자 전송이 아니다(RED 2). graphql-java를 architectureTest 컴파일 전용으로 넣어 `graphql..` 항목을 fixture로 증명. 템플릿 패키지 목록: `application-core/CLAUDE.md` 표를 정본으로, `TemplatePackageOwnership`과 소유 leaf를 대조하는 문서 대조 테스트(RED 3). shared-contract `ServerFailureLog`로 web·GraphQL·gRPC·STOMP가 같은 실패 로그 줄을 쓴다(RED gRPC 4·GraphQL 2). 새로 찾아 고친 것: gRPC가 `INTERNAL_ERROR` 실패를 아무 데도 남기지 않음, STOMP가 persistence 실패의 SQL 원인까지 로그에 씀 | 9 leaf `check`·`qualityCheck`·`testQualityCheck`, architectureTest 216, documentContractTest 65, architectureCheck, verifyDependencyLocks, `-p optional-platforms ci`, 전송 qualification lane, systemTest | 규칙으로 막을 수 없는 길(bean 이름 조회, 설정이 함수로 감싸 넘김)과 그 길을 막는 다른 방어를 매뉴얼 07에 적었다. 목록에 넣지 않은 새 템플릿 패키지는 기능 패키지와 구별할 수 없다(한계로 문서화) |
|
||||||
|
| r9-b 멱등성·outbound | README 15 남음(CLAIMED → 시작의 lease), RR5-01-02~05, RR5-03-01, RR4-03-01·02·04 | 두 저장소 모두 lease가 지난 CLAIMED의 시작을 `LEASE_EXPIRED`로 거절하고 executor는 503 `IDEMPOTENCY_UNAVAILABLE`(실행 안 됨)로 답한다(RED 실 Redis·실 PG). renew·start 결과 값마다 Javadoc. 포트 Javadoc "먼저 온 보고 하나". 늦은 실패 뒤 다음 claim까지 보는 계약 4건. PostgreSQL 기본 사용 모양(쓰기 트랜잭션 안의 executor)에서는 lease 지난 EXECUTING이 남에게 보이지 않는다는 사실을 문서에 저장소별로. TTL 관계(lease ≤ replay-ttl ≤ failure-retention) 안내. watchdog RED 테스트를 공용 풀 병렬도와 무관하게, runbook의 Redis 기록 삭제를 `EVALSHA` 한 번으로(실 Redis·실 ACL에서 runbook 블록 그대로 실행), watchdog 스레드는 60초 유휴 뒤 끝나고 요청 스레드의 thread-local·class loader를 물려받지 않는다(RED) | 6 leaf `check`·`testQualityCheck`, `redisContainerContractTest` 72, PG 계약 31, `postgresqlIdempotencyIntegrationTest` 10, `httpClientPerformanceTest` 5, architectureCheck, verifyEnvKeys, documentContractTest | 애플리케이션 Redis 계정은 ACL이 `EVAL`을 막아 runbook은 `SCRIPT LOAD`+`EVALSHA`. 시작 거절은 아무것도 실행되지 않았으므로 503 |
|
||||||
|
| r9-c persistence | RR4-02-01, gRPC 버전 정규식 복사본, V21 주석 | 잠금 대기 검사기가 Flyway 11.14.1이 스스로 트랜잭션 밖에서 돌리는 문장 목록을 쓰고(실 PG 21개 판정 일치), `VACUUM FULL`은 마이그레이션에서 거부(RED 25). 버전 판정 정본 `VersionedMigrationFiles` 하나를 grpc 빌드가 Sync 태스크로 가져와 컴파일하고 복사본을 지웠다(RED 2). V21 주석은 `bbe944bd`에서 이미 고쳐져 있었다. 새로 찾아 고친 것: 가이드의 "CONCURRENTLY는 Flyway가 트랜잭션으로 감싼다" 오류 | persistence-jpa `check` 647, sample `check` 339, `postgresqlMigrationLockWaitIntegrationTest` 28, optional grpc ledger `check`·`integrationTest` 46, architectureCheck 두 빌드, documentContractTest | 버린 대안: 원본 디렉터리를 소스 루트로 직접 추가(Spotless가 프로젝트 밖 파일 거부), 주 빌드 의존, 대조 테스트(정의가 둘로 남음) |
|
||||||
|
| r9-d build-logic | README 15 남음 + RR5-02-02, RR5-02-01, RR5-02-03, `-mx`, httpclient 장애 주입 lane 두 번 실행 | `ShellScript`가 run 스크립트를 bash 문법으로 읽는다. 실패를 막지 못하는 명령(`|| true`, pipefail 없는 `| tee`, `!`, `&`, `echo`, `if`·`while` 조건, 함수 본문, `set +e`, `shell: pwsh`)은 이유를 대며 세지 않는다(RED). heredoc·여러 줄 문자열 안의 `cd`는 데이터(RED). 실패 메시지가 다른 빌드로 읽힌 명령·dry-run·안 센 이유를 보여 준다(RED). 짧은 플래그 묶음은 Gradle 9.0 파서대로(TestKit으로 Gradle 동작 고정). 장애 주입 lane을 `mainCheck`에서 뺐다(`integrationCheck`가 main에서 돌아 두 번 돌릴 근거가 사라졌다). 새로 찾아 고친 것: `$(( ))` 파싱, `help --task ci`, `${{ }}` 안 공백, `-x=b` | `-p build-logic check javadoc` 146, 두 빌드 verifyStrictLaneStages, 실제 workflow 판독 전후 같음, 변형 실험 8, run 스크립트 253개 파싱 실패 0 | 서브셸·`eval`·`source` 안의 `cd` 뒤 명령과 `|| exit 1`은 세지 않는다(거짓 실패 쪽) |
|
||||||
|
|
||||||
|
합칠 때 오케스트레이터: 업그레이드 안내를 r9-a·r9-b와 손으로 합쳤다(5절에 세 묶음이 각자 더한 행을 모두 살림, B-41은 r9-b).
|
||||||
|
|
||||||
|
### 16.1 합친 뒤 게이트에서 드러난 것
|
||||||
|
|
||||||
|
첫 `ci`가 httpclient `ClientRuntimeRegistryTest.closingTheRegistryReleasesEveryGenerationAndLeavesNoThread` 하나로 실패했다(부하 16, r9 변경과 무관한 기존 코드). 원인 둘:
|
||||||
|
- `ClientRuntimeRegistry.close()`는 drain scheduler의 `awaitTermination`만 기다렸다. 실행기는 worker 스레드 안에서 종료를 알린 뒤 그 스레드가 끝나므로, 부하가 높으면 `close()`가 돌아왔을 때 스레드가 아직 살아 있다. "스레드를 남기지 않는다"는 약속이 타이밍에 기댔다.
|
||||||
|
- 런타임 하나가 닫기를 거부하면 `close()`가 scheduler를 멈추기 전에 예외를 던져 drain 스레드가 계속 살았다.
|
||||||
|
|
||||||
|
고친 것: scheduler가 만든 스레드를 기억해 `close()`가 종료를 기다린 뒤 그 스레드를 join한다(마감 안에 안 끝나면 실패). 런타임이 닫기를 거부해도 scheduler를 먼저 멈추고 예외는 그 뒤에 던진다. RED: 새 테스트 `aRuntimeThatRefusesToCloseStillLeavesNoDrainThread`가 옛 코드에서 실패(기존 테스트도 함께 실패). GREEN: httpclient `check`·`testQualityCheck`·`httpClientFailureInjectionTest`·`httpClientPerformanceTest`, 그 테스트 클래스 5회 반복 통과.
|
||||||
|
|
||||||
|
### 16.2 게이트 (2026-11-05, 공유 잠금)
|
||||||
|
|
||||||
|
| 게이트 | 결과 | 시간 | 실행 직전 부하(1분) |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `ci` 첫 실행 | 실패 — httpclient `ClientRuntimeRegistryTest` 1건(16.1절) | 8분 48초 | 16.28 |
|
||||||
|
| `ci` 재실행(16.1절 수정 뒤) | rc=0 | 1분 22초(나머지 캐시) | 17.54 |
|
||||||
|
| `verifyStrictLaneStages --dry-run` (주 빌드 / optional) | rc=0 / rc=0 | 19초 / 4초 | 20.30 / 18.13 |
|
||||||
|
| `mainCheck` | rc=0 | 10분 59초 | 17.48 |
|
||||||
|
| `:integrationCheck` | rc=0 | 20분 11초 | 14.92 |
|
||||||
|
| `-p optional-platforms ci integrationCheck performanceCheck` | rc=0 | 2분 16초 | 15.57 |
|
||||||
|
| `:performanceCheck` | rc=0 | 36초 | 24.43 |
|
||||||
|
| `:releaseCheck -PgitRevision=<HEAD>` | rc=0 | 5초 | 19.00 |
|
||||||
|
| `scripts/verify-compose-profile-contracts.sh` | rc=0, 18 lane | — | 18.44 |
|
||||||
|
|
||||||
|
`mainCheck`·`integrationCheck`는 16.1절 수정 전 트리에서 돌았다. 그 수정은 httpclient만 바꿔서 httpclient `check`·`testQualityCheck`·`httpClientFailureInjectionTest`·`httpClientPerformanceTest`를 따로 다시 돌렸다(통과).
|
||||||
|
|||||||
@@ -4,7 +4,7 @@ category: TRANSIENT_DEPENDENCY
|
|||||||
error_codes: [IDEMPOTENCY_UNAVAILABLE, IDEMPOTENCY_COMPLETION_UNKNOWN, IDEMPOTENCY_RECOVERY_REQUIRED]
|
error_codes: [IDEMPOTENCY_UNAVAILABLE, IDEMPOTENCY_COMPLETION_UNKNOWN, IDEMPOTENCY_RECOVERY_REQUIRED]
|
||||||
severity: P2
|
severity: P2
|
||||||
owner: oncall
|
owner: oncall
|
||||||
last_updated: 2026-11-04
|
last_updated: 2026-11-05
|
||||||
status: active
|
status: active
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -17,6 +17,11 @@ status: active
|
|||||||
- `IdempotencyExecutor` refused to run the action because the replay store (JPA or Redis, whichever
|
- `IdempotencyExecutor` refused to run the action because the replay store (JPA or Redis, whichever
|
||||||
`app.idempotency` selects) did not answer. Nothing was executed: the refusal happens before the
|
`app.idempotency` selects) did not answer. Nothing was executed: the refusal happens before the
|
||||||
action, so a client retry is safe.
|
action, so a client retry is safe.
|
||||||
|
- The same 503 when the store refused to start a claim whose processing lease had already run out
|
||||||
|
— the request spent longer than the lease between its claim and the start of its action (a
|
||||||
|
stalled process, a slow store call). The ERROR line's message then reads `the claim's processing
|
||||||
|
lease ran out before the action started; nothing ran: <scope>`, and the store may be healthy.
|
||||||
|
Nothing ran here either, and the next request with the key takes the claim over and runs it.
|
||||||
- HTTP 503 `IDEMPOTENCY_COMPLETION_UNKNOWN` (`retryable=true`) is the same outage hitting after the
|
- HTTP 503 `IDEMPOTENCY_COMPLETION_UNKNOWN` (`retryable=true`) is the same outage hitting after the
|
||||||
action ran: the store did not answer while the result was being recorded. When the use case called
|
action ran: the store did not answer while the result was being recorded. When the use case called
|
||||||
the executor inside its write transaction, that transaction's database writes rolled back with the
|
the executor inside its write transaction, that transaction's database writes rolled back with the
|
||||||
@@ -32,6 +37,10 @@ status: active
|
|||||||
record. If the attempt is still running and finishes, its result is recorded, the first request
|
record. If the attempt is still running and finishes, its result is recorded, the first request
|
||||||
gets its normal answer, and later requests with the key get that result replayed; a failure it
|
gets its normal answer, and later requests with the key get that result replayed; a failure it
|
||||||
reports is recorded the same way. So this 500 can stop on its own (owner decision 2026-11-04).
|
reports is recorded the same way. So this 500 can stop on its own (owner decision 2026-11-04).
|
||||||
|
This is the Redis store's case. The PostgreSQL store, called inside the use case's write
|
||||||
|
transaction as the template calls it, never shows another request an unfinished record: that
|
||||||
|
request waits for the first transaction to end, and gets the replay if it committed or a fresh
|
||||||
|
run if it rolled back (`docs/web/http-contract.md` §2).
|
||||||
|
|
||||||
## Diagnosis
|
## Diagnosis
|
||||||
|
|
||||||
@@ -39,16 +48,27 @@ status: active
|
|||||||
JPA datasource or Redis, depending on the selected provider).
|
JPA datasource or Redis, depending on the selected provider).
|
||||||
- Look for connection-pool saturation or timeouts on that store in the same time window; the
|
- Look for connection-pool saturation or timeouts on that store in the same time window; the
|
||||||
executor reports saturation as unavailable rather than guessing.
|
executor reports saturation as unavailable rather than guessing.
|
||||||
- For `IDEMPOTENCY_RECOVERY_REQUIRED`, find the scope in the server's ERROR log of the failed request
|
- For `IDEMPOTENCY_RECOVERY_REQUIRED`, find the scope in the server's ERROR log of the failed request.
|
||||||
(the web adapter logs `failure classified as IDEMPOTENCY_RECOVERY_REQUIRED` with the exception,
|
Every transport writes the same line, `failure classified as IDEMPOTENCY_RECOVERY_REQUIRED
|
||||||
under the request's `X-Request-Id`). The exception message ends with
|
(category=DATA_INTEGRITY, retryable=false)`, with the exception attached
|
||||||
|
(shared-contract `ServerFailureLog`), and adds its own correlation:
|
||||||
|
- web: no suffix; the line carries the request's `X-Request-Id` (MDC `request_id`).
|
||||||
|
- gRPC: ` (method=<service>/<method>)`; MDC `request_id` too when the service closed the call on
|
||||||
|
its callback thread.
|
||||||
|
- GraphQL: ` (executionId=<id>)`, the `executionId` the client got in the error's `extensions`.
|
||||||
|
- STOMP (`@MessageMapping`): no suffix; MDC `request_id` is the frame's.
|
||||||
|
|
||||||
|
The exception message ends with
|
||||||
`<operation code>::v<digest version>::<scope digest>`, for example
|
`<operation code>::v<digest version>::<scope digest>`, for example
|
||||||
`claim requires reconciliation: CHARGE_CARD::v1::3f9a…` (64 hex characters). Then look at the
|
`claim requires reconciliation: CHARGE_CARD::v1::3f9a…` (64 hex characters). Then look at the
|
||||||
record in the store the service uses (`APP_IDEMPOTENCY_PROVIDER`). There is no tool for this; these
|
record in the store the service uses (`APP_IDEMPOTENCY_PROVIDER`). There is no tool for this; these
|
||||||
are the commands.
|
are the commands.
|
||||||
- Redis. The key is
|
- Redis. The key, for example `prod:order:shared:idem:v1:d1:CHARGE_CARD:3f9a…`, is
|
||||||
`<APP_REDIS_NAMESPACE_ENVIRONMENT>:<APP_REDIS_NAMESPACE_SERVICE>:<APP_REDIS_NAMESPACE_DOMAIN>:idem:v1:d<digest version>:<operation code>:<scope digest>`,
|
|
||||||
for example `prod:order:shared:idem:v1:d1:CHARGE_CARD:3f9a…`.
|
<!-- runbook-redis: idempotency-record-key -->
|
||||||
|
```
|
||||||
|
<APP_REDIS_NAMESPACE_ENVIRONMENT>:<APP_REDIS_NAMESPACE_SERVICE>:<APP_REDIS_NAMESPACE_DOMAIN>:idem:v1:d<digest version>:<operation code>:<scope digest>
|
||||||
|
```
|
||||||
|
|
||||||
```
|
```
|
||||||
HMGET <key> state attempt leaseUntil
|
HMGET <key> state attempt leaseUntil
|
||||||
@@ -77,7 +97,10 @@ status: active
|
|||||||
|
|
||||||
## Action
|
## Action
|
||||||
|
|
||||||
- `IDEMPOTENCY_UNAVAILABLE`: restore the store; clients retry with the same key and backoff.
|
- `IDEMPOTENCY_UNAVAILABLE`: restore the store; clients retry with the same key and backoff. When
|
||||||
|
the message says the claim's processing lease ran out before the action started, the store is
|
||||||
|
not the cause: find what held those requests between claim and start (thread dumps, GC pauses,
|
||||||
|
the store's latency in that window). Nothing to repair; the next same-key request runs.
|
||||||
- `IDEMPOTENCY_COMPLETION_UNKNOWN`: restore the store, then check the effects outside the
|
- `IDEMPOTENCY_COMPLETION_UNKNOWN`: restore the store, then check the effects outside the
|
||||||
transaction for the failed requests (the ERROR log line names the code). A same-key resend replays
|
transaction for the failed requests (the ERROR log line names the code). A same-key resend replays
|
||||||
a result that was in fact recorded, gets `IDEMPOTENT_IN_FLIGHT` while the attempt's lease lasts,
|
a result that was in fact recorded, gets `IDEMPOTENT_IN_FLIGHT` while the attempt's lease lasts,
|
||||||
@@ -100,8 +123,26 @@ status: active
|
|||||||
`EXECUTING` record, even past its lease: if its attempt is still alive, its late result finds no
|
`EXECUTING` record, even past its lease: if its attempt is still alive, its late result finds no
|
||||||
record (`ABSENT`) — the result is lost, the first request gets this 500 after its work took
|
record (`ABSENT`) — the result is lost, the first request gets this 500 after its work took
|
||||||
effect, and the next request with the key runs the work a second time. Leave it to expire.
|
effect, and the next request with the key runs the work a second time. Leave it to expire.
|
||||||
- Redis: check `HMGET <key> state` is `ABANDONED` and `PTTL <key>` has minutes left, then
|
- Redis: check and delete in one step, as the account the service's registered scripts run as
|
||||||
`DEL <key>`. A record that is about to expire needs nothing; once it is gone the key is new.
|
(`APP_REDIS_AUTHENTICATION_ADVANCED_CREDENTIAL_REFERENCE`, or the application account when it
|
||||||
|
is unset). Checking with `HMGET` and then sending `DEL` is two commands: a record that expires
|
||||||
|
between them and is claimed again by a new request is deleted while that request runs, and
|
||||||
|
the next request with the key runs the work a second time (re-review 2026-11-04 RR4-03-02).
|
||||||
|
The program below deletes the key only while its `state` is `ABANDONED`. The application
|
||||||
|
accounts are denied `EVAL` (`infra/redis-sdk/acl/README.md`), so load it and run it by the
|
||||||
|
digest `SCRIPT LOAD` prints, as the service runs its own scripts:
|
||||||
|
|
||||||
|
<!-- runbook-redis: idempotency-delete-abandoned -->
|
||||||
|
```
|
||||||
|
SCRIPT LOAD "if redis.call('HGET', KEYS[1], 'state') == 'ABANDONED' then return redis.call('DEL', KEYS[1]) end return 0"
|
||||||
|
EVALSHA <digest SCRIPT LOAD printed> 1 <key>
|
||||||
|
```
|
||||||
|
|
||||||
|
`1` deleted the record; the key is new. `0` deleted nothing: the record is no longer
|
||||||
|
`ABANDONED` (or is gone) — look again before doing anything else. `NOSCRIPT` means the node
|
||||||
|
that holds the key (a cluster) has not loaded the program: run `SCRIPT LOAD` on that node and
|
||||||
|
`EVALSHA` again; nothing was deleted. A record that is about to expire needs nothing; once it
|
||||||
|
is gone the key is new.
|
||||||
- PostgreSQL:
|
- PostgreSQL:
|
||||||
|
|
||||||
```sql
|
```sql
|
||||||
|
|||||||
@@ -1748,6 +1748,9 @@ update idempotency_record
|
|||||||
> 무언가가 record를 움직였으니 caller는 자기 view를 현재로 취급하면 안 된다. row를 읽고 나서
|
> 무언가가 record를 움직였으니 caller는 자기 view를 현재로 취급하면 안 된다. row를 읽고 나서
|
||||||
> scope만으로 update하면 lease가 만료된 worker가 takeover한 worker의 상태를 덮어쓸 수 있다.
|
> scope만으로 update하면 lease가 만료된 worker가 takeover한 worker의 상태를 덮어쓸 수 있다.
|
||||||
|
|
||||||
|
START/RENEW만은 store가 잠근 row를 owner 튜플과 먼저 비교한 뒤에 돌리므로, 그 둘의 0은 lease가 끝난
|
||||||
|
것이다. 그래서 `NOT_OWNER`가 아니라 `LEASE_EXPIRED`로 답한다(재리뷰 2026-11-04 RR5-01-02).
|
||||||
|
|
||||||
`IdempotencyDigestPolicy`의 기록이 특히 좋다.
|
`IdempotencyDigestPolicy`의 기록이 특히 좋다.
|
||||||
|
|
||||||
> `transition|operationId|ownerToken|attempt|stateRevision`은 **누가, 언제**를 덮고 **무엇**은
|
> `transition|operationId|ownerToken|attempt|stateRevision`은 **누가, 언제**를 덮고 **무엇**은
|
||||||
@@ -2832,7 +2835,8 @@ Flyway는 세 옵션이 **pin**되어 있다(env-driven 아님): `baseline-on-mi
|
|||||||
`reaper-interval: PT10M`, `published-retention: P7D`.
|
`reaper-interval: PT10M`, `published-retention: P7D`.
|
||||||
|
|
||||||
`ca-skeleton.capabilities.idempotency.*`: `provider: disabled`, `processing-lease: 30s`,
|
`ca-skeleton.capabilities.idempotency.*`: `provider: disabled`, `processing-lease: 30s`,
|
||||||
`replay-ttl: 24h`(`APP_IDEMPOTENCY_TTL`, 최대 72h), `failure-retention: 24h`,
|
`replay-ttl: 24h`(`APP_IDEMPOTENCY_TTL`, 최대 72h, `processing-lease` 이상·`failure-retention` 이하),
|
||||||
|
`failure-retention: 24h`,
|
||||||
`reaper-interval: 10m`. 한 record(`IdempotencySettings`)가 전부 바인딩한다.
|
`reaper-interval: 10m`. 한 record(`IdempotencySettings`)가 전부 바인딩한다.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|||||||
@@ -25,7 +25,7 @@
|
|||||||
| 2 | dev·prod 환경 변수의 `APP_FLYWAY_ENABLED` 값을 확인한다 | `false`가 남아 있으면 이제 정말로 마이그레이션이 안 돈다 | persistence-jpa 선택 |
|
| 2 | dev·prod 환경 변수의 `APP_FLYWAY_ENABLED` 값을 확인한다 | `false`가 남아 있으면 이제 정말로 마이그레이션이 안 돈다 | persistence-jpa 선택 |
|
||||||
| 3 | prod 비밀값(레지스트리 `secret` 행, 모듈이 기여한 비밀, `secret://…/<VAR>`이 가리키는 변수)이 `fixture-`로 시작하지 않게 한다 | prod 기동 실패(exit 78) | prod 배포 전부 |
|
| 3 | prod 비밀값(레지스트리 `secret` 행, 모듈이 기여한 비밀, `secret://…/<VAR>`이 가리키는 변수)이 `fixture-`로 시작하지 않게 한다 | prod 기동 실패(exit 78) | prod 배포 전부 |
|
||||||
| 4 | 직접 만든 `StartupRule`·`RequiredProductionSecrets` bean을 `static @Bean`, 의존성 없이 바꾸고, 그 클래스에서 `@Value`·`@Autowired` 멤버와 `@ConfigurationProperties`를 뺀다 | 기동 실패 `startup rule or secret list '<이름>' created [...]` 또는 `'<이름>' (...) is a StartupRule or RequiredProductionSecrets ... but it needs one`(exit 78) | 자기 rule이 있는 서비스 |
|
| 4 | 직접 만든 `StartupRule`·`RequiredProductionSecrets` bean을 `static @Bean`, 의존성 없이 바꾸고, 그 클래스에서 `@Value`·`@Autowired` 멤버와 `@ConfigurationProperties`를 뺀다 | 기동 실패 `startup rule or secret list '<이름>' created [...]` 또는 `'<이름>' (...) is a StartupRule or RequiredProductionSecrets ... but it needs one`(exit 78) | 자기 rule이 있는 서비스 |
|
||||||
| 5 | 직접 구현한 outbox·발행·알림·파일 서버 포트를 새 시그니처로 고친다(3.1절) | 컴파일 오류 | 해당 포트를 구현·호출하는 서비스 |
|
| 5 | 직접 구현한 outbox·발행·알림·파일 서버 포트를 새 시그니처로, 직접 구현한 멱등성 store를 새 결과 값(B-41)으로 고친다(3.1절) | 컴파일 오류, 멱등성 공유 계약 실패 | 해당 포트를 구현·호출하는 서비스 |
|
||||||
| 6 | `dev.caskeleton.application.outbound.*` import를 `application.secret.*`·`application.objectstorage.content.CallBudget`으로 바꾼다 | 컴파일 오류 | 해당 타입을 쓰는 서비스 |
|
| 6 | `dev.caskeleton.application.outbound.*` import를 `application.secret.*`·`application.objectstorage.content.CallBudget`으로 바꾼다 | 컴파일 오류 | 해당 타입을 쓰는 서비스 |
|
||||||
| 7 | 이벤트 id를 소문자 UUIDv7로 만들고 `IntegrationEventDraft`는 `IntegrationEventDrafts.draft(...)`로만 만든다 | 쓰기 요청이 `IllegalArgumentException`으로 실패, architectureTest 실패 | 통합 이벤트를 내는 서비스 |
|
| 7 | 이벤트 id를 소문자 UUIDv7로 만들고 `IntegrationEventDraft`는 `IntegrationEventDrafts.draft(...)`로만 만든다 | 쓰기 요청이 `IllegalArgumentException`으로 실패, architectureTest 실패 | 통합 이벤트를 내는 서비스 |
|
||||||
| 8 | V21 배포 전에 `docs/runbooks/outbox-dead-letter.md` §8 Step 1 쿼리를 운영 DB에 돌린다 | 중복 순서 키가 있으면 기동 실패(exit 70, V20에 남음) | persistence-jpa + outbox |
|
| 8 | V21 배포 전에 `docs/runbooks/outbox-dead-letter.md` §8 Step 1 쿼리를 운영 DB에 돌린다 | 중복 순서 키가 있으면 기동 실패(exit 70, V20에 남음) | persistence-jpa + outbox |
|
||||||
@@ -62,6 +62,7 @@
|
|||||||
| B-10 | adapter 공개 타입 삭제·이동: graphql `execution.GraphQlTimeoutPolicy`·`dataloader.GraphQlDataLoaderRequestRegistry` 삭제(`runtime.GraphQlDeadlineInstrumentation`·`GraphQlPerParentFetchInstrumentation` 추가). jpa `experimental.tenant.TenantId` 삭제 → `dev.caskeleton.application.tenant.TenantId`. persistence-notification의 엔티티는 `...platform.entity`, 저장소는 `...platform.repository`로 이동, `inbox` 하위 클래스는 `platform`으로 올라옴, `PreferenceJpaRepository`·`SuppressionJpaRepository` 삭제, `JpaNotificationSideEffect` → application-notification `dispatch.SuppressionSideEffect`. graphql `GraphQlClientPolicy.effectivePageSize(Integer, Integer)` 삭제 → `pagination.GraphQlConnectionPolicy.effectivePageSize`(상한 검사 포함, 재리뷰 RR-01-14). grpc(optional-platforms) `GrpcOperationLedger.release(identity)` → `boolean release(identity, GrpcClaimToken)`: 진행 중이고 그 token이 가진 claim만 지운다(RR-01-15) | import 실패, 호출부·직접 구현한 ledger 컴파일 오류. leaf `check`의 API surface 비교가 스냅샷과 달라 실패(자기 공개 타입을 더했다면 merge 충돌) | import를 바꾼다. 스냅샷 파일은 upstream 것을 받고 자기 추가분을 다시 승인한다 | `1400dc15`·`5786126c` · `docs/architecture/graphql-api-surface.txt`, `docs/architecture/jpa-api-surface.txt`(166→165), `docs/notification/api-surface-snapshot.txt`(362→364) |
|
| B-10 | adapter 공개 타입 삭제·이동: graphql `execution.GraphQlTimeoutPolicy`·`dataloader.GraphQlDataLoaderRequestRegistry` 삭제(`runtime.GraphQlDeadlineInstrumentation`·`GraphQlPerParentFetchInstrumentation` 추가). jpa `experimental.tenant.TenantId` 삭제 → `dev.caskeleton.application.tenant.TenantId`. persistence-notification의 엔티티는 `...platform.entity`, 저장소는 `...platform.repository`로 이동, `inbox` 하위 클래스는 `platform`으로 올라옴, `PreferenceJpaRepository`·`SuppressionJpaRepository` 삭제, `JpaNotificationSideEffect` → application-notification `dispatch.SuppressionSideEffect`. graphql `GraphQlClientPolicy.effectivePageSize(Integer, Integer)` 삭제 → `pagination.GraphQlConnectionPolicy.effectivePageSize`(상한 검사 포함, 재리뷰 RR-01-14). grpc(optional-platforms) `GrpcOperationLedger.release(identity)` → `boolean release(identity, GrpcClaimToken)`: 진행 중이고 그 token이 가진 claim만 지운다(RR-01-15) | import 실패, 호출부·직접 구현한 ledger 컴파일 오류. leaf `check`의 API surface 비교가 스냅샷과 달라 실패(자기 공개 타입을 더했다면 merge 충돌) | import를 바꾼다. 스냅샷 파일은 upstream 것을 받고 자기 추가분을 다시 승인한다 | `1400dc15`·`5786126c` · `docs/architecture/graphql-api-surface.txt`, `docs/architecture/jpa-api-surface.txt`(166→165), `docs/notification/api-surface-snapshot.txt`(362→364) |
|
||||||
| B-11 | 조립·지원 타입: `bootstrap.autoconfigure.operation.DurableOperationConfig` → `composition:durable-operation`의 `composition.operation.DurableOperationAutoConfiguration`. `bootstrap.settings.LoggingSettings` 삭제. `composition.outbox.OutboxLeaderElectionToken` 삭제. `TracingSamplingEnvironmentPostProcessor` → `TracingEnvironmentPostProcessor`, `StartupOrder.TRACING_SAMPLING` → `TRACING_PROPERTIES`. `StartupRuleRunner(Environment, List<StartupRule>)` → `StartupRuleRunner(Environment)`. `SecretSourceValidator(ConfigurableEnvironment, SecretSourcePort, List)` → `SecretSourceValidator(Supplier<List<RequiredProductionSecrets>>)` | 이 타입을 참조하는 코드·테스트 컴파일 오류 | 새 이름으로 바꾼다 | `1400dc15`, `34565130`, `bbe944bd` · `src/composition/durable-operation/`, `src/adapter/outbound/support/.../startup/` |
|
| B-11 | 조립·지원 타입: `bootstrap.autoconfigure.operation.DurableOperationConfig` → `composition:durable-operation`의 `composition.operation.DurableOperationAutoConfiguration`. `bootstrap.settings.LoggingSettings` 삭제. `composition.outbox.OutboxLeaderElectionToken` 삭제. `TracingSamplingEnvironmentPostProcessor` → `TracingEnvironmentPostProcessor`, `StartupOrder.TRACING_SAMPLING` → `TRACING_PROPERTIES`. `StartupRuleRunner(Environment, List<StartupRule>)` → `StartupRuleRunner(Environment)`. `SecretSourceValidator(ConfigurableEnvironment, SecretSourcePort, List)` → `SecretSourceValidator(Supplier<List<RequiredProductionSecrets>>)` | 이 타입을 참조하는 코드·테스트 컴파일 오류 | 새 이름으로 바꾼다 | `1400dc15`, `34565130`, `bbe944bd` · `src/composition/durable-operation/`, `src/adapter/outbound/support/.../startup/` |
|
||||||
| B-39 | vendored messaging SPI `KafkaQuarantinePublisher`(`messaging-kafka`): `quarantine(ConsumerRecord, Throwable)` → `quarantine(ConsumerRecord, FailureCategory category, Throwable reason)`. 호출자가 격리 이유(읽을 수 없는 레코드 `DESERIALIZATION`, 시도 예산 소진은 실패의 category 또는 `POISON_MESSAGE`)를 넘기고, 구현은 그것을 `msg.failure-category` header로 쓴다 | 이 SPI를 직접 구현한 서비스는 `does not override abstract method` 컴파일 오류. 람다로 만든 것도 인자 수 오류 | 세 인자 메서드로 고친다. category를 header나 저장소에 그대로 남겨야 redrive가 두 경우를 가른다(템플릿 `KafkaDeadLetterQuarantine`, 테스트 `KafkaDeadLetterQuarantineTest`) | `bbe944bd`(리뷰 06-14), 3차 수정에서 목록에 추가(재리뷰 2차 RR-02-16) · `src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaQuarantinePublisher.java` |
|
| B-39 | vendored messaging SPI `KafkaQuarantinePublisher`(`messaging-kafka`): `quarantine(ConsumerRecord, Throwable)` → `quarantine(ConsumerRecord, FailureCategory category, Throwable reason)`. 호출자가 격리 이유(읽을 수 없는 레코드 `DESERIALIZATION`, 시도 예산 소진은 실패의 category 또는 `POISON_MESSAGE`)를 넘기고, 구현은 그것을 `msg.failure-category` header로 쓴다 | 이 SPI를 직접 구현한 서비스는 `does not override abstract method` 컴파일 오류. 람다로 만든 것도 인자 수 오류 | 세 인자 메서드로 고친다. category를 header나 저장소에 그대로 남겨야 redrive가 두 경우를 가른다(템플릿 `KafkaDeadLetterQuarantine`, 테스트 `KafkaDeadLetterQuarantineTest`) | `bbe944bd`(리뷰 06-14), 3차 수정에서 목록에 추가(재리뷰 2차 RR-02-16) · `src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaQuarantinePublisher.java` |
|
||||||
|
| B-41 | enum 값 추가: `IdempotencyStartOutcome.LEASE_EXPIRED`, `IdempotencyRenewOutcome.LEASE_EXPIRED`(둘 다 `carriesOwner()`=false). 주인이 아직 기록을 가졌지만 processing lease가 끝나 시작·renew를 거절한다는 뜻이다. 전에는 PostgreSQL이 둘 다 `NOT_OWNER`, Redis가 renew는 `NOT_OWNER`·시작은 `STARTED`였다 | `default` 없는 switch 식이 "does not cover all possible input values" 컴파일 오류. 직접 구현한 store는 `IdempotencyStoreContract`의 새 시간 케이스(lease 지난 시작·renew)에서 실패 | 새 값 분기를 더한다. `LEASE_EXPIRED`를 `NOT_OWNER`처럼 "기록을 잃었다"로 읽지 않는다 — 실행 중이면 주인은 여전히 `complete`·`markFailed` 한다. store는 lease가 끝난 시작·renew에 이 값을 돌려준다 | r9(재리뷰 README 15 남음, RR5-01-02) · `src/application-core/.../idempotency/IdempotencyStartOutcome.java`, `IdempotencyRenewOutcome.java`, `src/application-core/src/testFixtures/.../IdempotencyStoreContract.java` |
|
||||||
|
|
||||||
### 3.2 설정·기동 — 기동이 실패하거나 런타임 예외가 난다
|
### 3.2 설정·기동 — 기동이 실패하거나 런타임 예외가 난다
|
||||||
|
|
||||||
@@ -71,7 +72,7 @@
|
|||||||
| B-13 | `app.security.*` strict 바인딩: 접두어 아래 오타 키, 또는 설정·placeholder 어디에도 쓰이지 않는 `APP_SECURITY_*` 환경 변수가 기동을 막는다 | 기동 실패(메시지는 `StrictSettingsBinder`가 키 이름을 담아 냄, 정확한 문구 확인 못 함) | 쓰지 않는 `APP_SECURITY_*` 변수를 지운다 | `5786126c` · `SecuritySettings.bind`, `src/adapter/outbound/support/.../StrictSettingsBinder.java` |
|
| B-13 | `app.security.*` strict 바인딩: 접두어 아래 오타 키, 또는 설정·placeholder 어디에도 쓰이지 않는 `APP_SECURITY_*` 환경 변수가 기동을 막는다 | 기동 실패(메시지는 `StrictSettingsBinder`가 키 이름을 담아 냄, 정확한 문구 확인 못 함) | 쓰지 않는 `APP_SECURITY_*` 변수를 지운다 | `5786126c` · `SecuritySettings.bind`, `src/adapter/outbound/support/.../StrictSettingsBinder.java` |
|
||||||
| B-14 | prod 프로필에서 `fixture-`로 시작하는 비밀값을 거부(레지스트리 `secret` 행, 모듈이 기여한 비밀, `secret://…/<VAR>` 참조 대상. `HOSTNAME`·앱 이름 같은 비밀 아닌 값은 보지 않는다 — RR2-04-01). Redis ACL fixture 파일 이름 변경: `infra/redis-sdk/acl/all-accounts.acl` → `lane-fixture-accounts.acl` | prod 기동 실패, 요약 `prod secret/config-source contract is invalid`(exit 78). 옛 ACL 경로를 mount하던 compose는 파일 없음 | prod 값을 진짜 비밀로 바꾼다. compose의 ACL 경로를 새 이름으로. Redis SDK admin 계정(`RedisAccountContribution`)을 조립했다면 그 변수를 `static` `RequiredProductionSecrets` bean으로도 낸다(코드에 든 참조는 검사가 보지 않는다, RR3-04-03, `src/adapter/outbound/redis-sdk/README.md`) | `bbe944bd` · `src/app-bootstrap/.../runtime/SecretSourceValidator.java`, `docs/registries/secrets-classification.yaml` |
|
| B-14 | prod 프로필에서 `fixture-`로 시작하는 비밀값을 거부(레지스트리 `secret` 행, 모듈이 기여한 비밀, `secret://…/<VAR>` 참조 대상. `HOSTNAME`·앱 이름 같은 비밀 아닌 값은 보지 않는다 — RR2-04-01). Redis ACL fixture 파일 이름 변경: `infra/redis-sdk/acl/all-accounts.acl` → `lane-fixture-accounts.acl` | prod 기동 실패, 요약 `prod secret/config-source contract is invalid`(exit 78). 옛 ACL 경로를 mount하던 compose는 파일 없음 | prod 값을 진짜 비밀로 바꾼다. compose의 ACL 경로를 새 이름으로. Redis SDK admin 계정(`RedisAccountContribution`)을 조립했다면 그 변수를 `static` `RequiredProductionSecrets` bean으로도 낸다(코드에 든 참조는 검사가 보지 않는다, RR3-04-03, `src/adapter/outbound/redis-sdk/README.md`) | `bbe944bd` · `src/app-bootstrap/.../runtime/SecretSourceValidator.java`, `docs/registries/secrets-classification.yaml` |
|
||||||
| B-15 | 기동 rule이 모든 singleton보다 먼저 돈다(`StartupRuleRunner`가 `BeanFactoryPostProcessor`). `StartupRule`과 `RequiredProductionSecrets` bean은 `static @Bean`이고 `Environment`, bean factory, static 무인자 `RequiredProductionSecrets`의 `ObjectProvider`만 받아야 한다. 두 타입의 클래스는 `@Value`·`@Autowired`·`@Inject`·`@Resource` 멤버, `@PostConstruct`·`@PreDestroy`, `@ConfigurationProperties`를 가질 수 없다(post-processor보다 먼저 만들어져 비어 있게 된다, RR2-04-03) | non-static `@Bean`이거나 다른 bean을 받으면 기동 실패 `startup rule or secret list '<이름>' created [<bean>] while creating it ... Declare the rule with a static @Bean method ...`, 위 멤버가 있으면 `'<이름>' (...) is a StartupRule or RequiredProductionSecrets ... but it needs one: [...]`(둘 다 exit 78, 둘 다 모든 프로필. runner가 rule과 비밀 목록을 프로필과 무관하게 먼저 만들어, 인터페이스 타입 `@Bean`이 돌려준 실제 클래스까지 본다, RR3-04-01) | rule 선언을 `static`으로, 인자를 위 셋으로 줄인다. 값은 `violations(Environment)`가 받는 `Environment`에서 읽는다. 다른 bean이 필요한 검사는 rule이 아니라 일반 bean으로 둔다 | `34565130`, `bbe944bd` · `src/adapter/outbound/support/.../startup/StartupRule.java`, `StartupRuleRunner.java` |
|
| B-15 | 기동 rule이 모든 singleton보다 먼저 돈다(`StartupRuleRunner`가 `BeanFactoryPostProcessor`). `StartupRule`과 `RequiredProductionSecrets` bean은 `static @Bean`이고 `Environment`, bean factory, static 무인자 `RequiredProductionSecrets`의 `ObjectProvider`만 받아야 한다. 두 타입의 클래스는 `@Value`·`@Autowired`·`@Inject`·`@Resource` 멤버, `@PostConstruct`·`@PreDestroy`, `@ConfigurationProperties`를 가질 수 없다(post-processor보다 먼저 만들어져 비어 있게 된다, RR2-04-03) | non-static `@Bean`이거나 다른 bean을 받으면 기동 실패 `startup rule or secret list '<이름>' created [<bean>] while creating it ... Declare the rule with a static @Bean method ...`, 위 멤버가 있으면 `'<이름>' (...) is a StartupRule or RequiredProductionSecrets ... but it needs one: [...]`(둘 다 exit 78, 둘 다 모든 프로필. runner가 rule과 비밀 목록을 프로필과 무관하게 먼저 만들어, 인터페이스 타입 `@Bean`이 돌려준 실제 클래스까지 본다, RR3-04-01) | rule 선언을 `static`으로, 인자를 위 셋으로 줄인다. 값은 `violations(Environment)`가 받는 `Environment`에서 읽는다. 다른 bean이 필요한 검사는 rule이 아니라 일반 bean으로 둔다 | `34565130`, `bbe944bd` · `src/adapter/outbound/support/.../startup/StartupRule.java`, `StartupRuleRunner.java` |
|
||||||
| B-16 | 권한 가드(새 `PermissionEnforcementGuard`): `@SystemInvoked` 유스케이스가 bean이면 기동 실패. `@RequiresPermission`을 단 bean에 적용되는 advisor가 없어도 기동 실패. ArchUnit `SYSTEM_INVOKED_USE_CASES_DECLARE_NO_PERMISSION`, `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`, `SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`, `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS` 추가, 새 표시 `@SystemCaller` | 기동 실패 `@SystemInvoked use cases are registered as beans ...` 또는 `beans declare @RequiresPermission but no advisor enforces it ...`(exit 72). `@SystemCaller`가 아닌 inbound adapter가 그 유스케이스를 부르거나, 사용자 전송(controller 등)이 `@SystemCaller` bean을 직접·중간 클래스를 거쳐 부르면 architectureTest 실패 | 시스템만 부르는 쓰기 유스케이스는 composition에서 `new`로 만들어 스케줄러에 넘기거나, 메시지 handler·예약 작업이면 그 클래스에 `@SystemCaller`를 달고 생성자에서 `new`로 만든다. 예약 작업은 서비스 leaf의 `..adapter.inbound.scheduler..` 패키지에 둔다. 세 경로와 두는 곳은 매뉴얼 07장 「시스템이 부르는 쓰기」(handler 작업 순서는 09장 「소비」 4단계). "지금 실행" endpoint가 필요하면 `@RequiresPermission` 유스케이스를 따로 만든다. `@RequiresPermission`을 쓰면 web adapter(`MethodSecurityConfig`)가 조립돼 있어야 한다 | `1400dc15`, `bbe944bd` · `src/composition/service-runtime/.../authorization/PermissionEnforcementGuard.java`, `src/application-core/.../security/SystemInvoked.java`, `SystemCaller.java` |
|
| B-16 | 권한 가드(새 `PermissionEnforcementGuard`): `@SystemInvoked` 유스케이스가 bean이면 기동 실패. `@RequiresPermission`을 단 bean에 적용되는 advisor가 없어도 기동 실패. ArchUnit `SYSTEM_INVOKED_USE_CASES_DECLARE_NO_PERMISSION`, `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`, `SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`, `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`, `SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES` 추가, 새 표시 `@SystemCaller` | 기동 실패 `@SystemInvoked use cases are registered as beans ...` 또는 `beans declare @RequiresPermission but no advisor enforces it ...`(exit 72). `@SystemCaller`가 아닌 inbound adapter가 그 유스케이스를 부르거나, 사용자 전송(controller 등)이 `@SystemCaller` bean을 직접·중간 클래스를 거쳐·그 작업이 구현하는 프로젝트 인터페이스로 부르면 architectureTest 실패. `@SystemCaller` 클래스가 `Runnable`·`ApplicationRunner` 같은 프로젝트 밖 타입을 구현·상속해도 실패. 설정(`@Configuration`)은 웹 bean과 handler bean을 함께 등록해도 사용자 전송으로 세지 않는다 | 시스템만 부르는 쓰기 유스케이스는 composition에서 `new`로 만들어 스케줄러에 넘기거나, 메시지 handler·예약 작업이면 그 클래스에 `@SystemCaller`를 달고 생성자에서 `new`로 만든다. 예약 작업은 서비스 leaf의 `..adapter.inbound.scheduler..` 패키지에 둔다. 세 경로와 두는 곳은 매뉴얼 07장 「시스템이 부르는 쓰기」(handler 작업 순서는 09장 「소비」 4단계). "지금 실행" endpoint가 필요하면 `@RequiresPermission` 유스케이스를 따로 만든다. 작업을 task scheduler에 직접 등록하던 코드는 작업이 `Runnable`을 구현하는 대신 등록하는 곳에서 `job::run`을 넘긴다. `@RequiresPermission`을 쓰면 web adapter(`MethodSecurityConfig`)가 조립돼 있어야 한다 | `1400dc15`, `bbe944bd`, r9 · `src/composition/service-runtime/.../authorization/PermissionEnforcementGuard.java`, `src/application-core/.../security/SystemInvoked.java`, `SystemCaller.java` |
|
||||||
| B-17 | `IntegrationEventDraft`: `eventId`·`causationId`는 소문자 UUIDv7만. ArchUnit `INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`: `new IntegrationEventDraft<>(...)` 금지, `IntegrationEventDrafts.draft(...)`만 | 이벤트를 만드는 쓰기 요청이 `IllegalArgumentException: eventId must be a canonical lower-case UUIDv7...`로 실패. architectureTest 실패 | event id를 UUIDv7로 만든다(예: sample `UuidOutboxEventIdFactory`가 `UuidCreator.getTimeOrderedEpochPlus1()`). draft는 헬퍼로 만든다. tenant가 없는 이벤트는 `IntegrationEventDrafts.SINGLE_TENANT_SCOPE`(`global`) | `1400dc15`, `bbe944bd` · `src/application-core/.../messaging/event/IntegrationEventDraft.java`, `IntegrationEventDrafts.java` |
|
| B-17 | `IntegrationEventDraft`: `eventId`·`causationId`는 소문자 UUIDv7만. ArchUnit `INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`: `new IntegrationEventDraft<>(...)` 금지, `IntegrationEventDrafts.draft(...)`만 | 이벤트를 만드는 쓰기 요청이 `IllegalArgumentException: eventId must be a canonical lower-case UUIDv7...`로 실패. architectureTest 실패 | event id를 UUIDv7로 만든다(예: sample `UuidOutboxEventIdFactory`가 `UuidCreator.getTimeOrderedEpochPlus1()`). draft는 헬퍼로 만든다. tenant가 없는 이벤트는 `IntegrationEventDrafts.SINGLE_TENANT_SCOPE`(`global`) | `1400dc15`, `bbe944bd` · `src/application-core/.../messaging/event/IntegrationEventDraft.java`, `IntegrationEventDrafts.java` |
|
||||||
| B-18 | `MessageHandler.schemaVersions()`(vendored `messaging-core-api`, default `{v1}`): 소비자 decode 목록을 handler 선언으로 만든다. 같은 (메시지 타입, 버전)에 다른 payload class를 선언하면 실패 | 컴파일은 된다. v1이 아닌 메시지는 `SCHEMA_VERSION_NOT_REGISTERED`로 거부. 발행 등록(`MessageContracts`)과 class가 다르면 기동 실패 `MESSAGING_CONTRACT_CONFLICT` | v2 이상을 읽는 handler는 `schemaVersions()`를 override한다. 소비 타입을 `MessageContracts`에 따로 등록하던 코드는 지운다 | `5786126c` · `src/messaging/messaging-core-api/.../delivery/MessageHandler.java`, `messaging-spring-boot-starter/.../MessageContracts.java` |
|
| B-18 | `MessageHandler.schemaVersions()`(vendored `messaging-core-api`, default `{v1}`): 소비자 decode 목록을 handler 선언으로 만든다. 같은 (메시지 타입, 버전)에 다른 payload class를 선언하면 실패 | 컴파일은 된다. v1이 아닌 메시지는 `SCHEMA_VERSION_NOT_REGISTERED`로 거부. 발행 등록(`MessageContracts`)과 class가 다르면 기동 실패 `MESSAGING_CONTRACT_CONFLICT` | v2 이상을 읽는 handler는 `schemaVersions()`를 override한다. 소비 타입을 `MessageContracts`에 따로 등록하던 코드는 지운다 | `5786126c` · `src/messaging/messaging-core-api/.../delivery/MessageHandler.java`, `messaging-spring-boot-starter/.../MessageContracts.java` |
|
||||||
| B-19 | `APP_FLYWAY_ENABLED`가 모든 프로필에서 읽힌다. dev·prod 프로필 파일의 `spring.flyway.enabled: true`·`app.persistence.vendor` 고정값을 지우고 persistence-jpa `config/module-defaults`가 `${APP_FLYWAY_ENABLED:true}`를 싣는다 | dev·prod 환경에 `APP_FLYWAY_ENABLED=false`가 있으면 전에는 무시됐지만 이제 기동 때 마이그레이션이 안 돈다 | dev·prod 환경 값을 확인한다. 자기 `application-dev.yml`·`application-prod.yml`에 같은 고정값을 다시 넣지 않는다 | `5786126c` · `src/app-bootstrap/src/main/resources/application-{dev,prod}.yml`, `src/adapter/outbound/persistence-jpa/.../module-defaults/persistence-jpa.yml` |
|
| B-19 | `APP_FLYWAY_ENABLED`가 모든 프로필에서 읽힌다. dev·prod 프로필 파일의 `spring.flyway.enabled: true`·`app.persistence.vendor` 고정값을 지우고 persistence-jpa `config/module-defaults`가 `${APP_FLYWAY_ENABLED:true}`를 싣는다 | dev·prod 환경에 `APP_FLYWAY_ENABLED=false`가 있으면 전에는 무시됐지만 이제 기동 때 마이그레이션이 안 돈다 | dev·prod 환경 값을 확인한다. 자기 `application-dev.yml`·`application-prod.yml`에 같은 고정값을 다시 넣지 않는다 | `5786126c` · `src/app-bootstrap/src/main/resources/application-{dev,prod}.yml`, `src/adapter/outbound/persistence-jpa/.../module-defaults/persistence-jpa.yml` |
|
||||||
@@ -101,9 +102,9 @@
|
|||||||
|
|
||||||
| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 |
|
| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 |
|
||||||
|---|---|---|---|---|
|
|---|---|---|---|---|
|
||||||
| B-34 | 템플릿 패키지 규칙(ArchUnit): `FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES`, `TEMPLATE_PACKAGES_DO_NOT_DEPEND_ON_FEATURE_PACKAGES`. 템플릿 이름: application `usecase command query capability transaction security tenant observability secret messaging outbox idempotency operation lease lock cache realtime notification fileserver objectstorage`, domain `identifier stereotype` | 기능 패키지 이름이 이 목록과 겹치거나(예: `domain.lock`), 업무 코드를 템플릿 패키지(예: `application.usecase.*`)에 두고 기능 패키지를 import하면 `:app-bootstrap:architectureTest` 실패 | 기능 패키지 이름을 바꾸고, 업무 코드를 `dev.caskeleton.application.<feature>`로 옮긴다. 규칙 정본은 `src/application-core/CLAUDE.md` "Package ownership" | `5786126c` · `src/app-bootstrap/src/architectureTest/.../TemplatePackageOwnership.java` |
|
| B-34 | 템플릿 패키지 규칙(ArchUnit): `FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES`, `TEMPLATE_PACKAGES_DO_NOT_DEPEND_ON_FEATURE_PACKAGES`. 템플릿 이름: application `usecase command query capability transaction security tenant observability secret messaging outbox idempotency operation lease lock cache realtime notification fileserver objectstorage`, domain `identifier stereotype` | 기능 패키지 이름이 이 목록과 겹치거나(예: `domain.lock`), 업무 코드를 템플릿 패키지(예: `application.usecase.*`)에 두고 기능 패키지를 import하면 `:app-bootstrap:architectureTest` 실패 | 기능 패키지 이름을 바꾸고, 업무 코드를 `dev.caskeleton.application.<feature>`로 옮긴다. 규칙 정본은 `src/application-core/CLAUDE.md` "Package ownership" | `5786126c`, r9 · `src/app-bootstrap/src/test/.../TemplatePackageOwnership.java`(표와 대조: `TemplatePackageOwnershipDocumentTest`) |
|
||||||
| B-35 | JPA 규칙: 양방향 연관은 한쪽에서만 매핑(`mappedBy`), notification·fileserver 저장소 엔티티는 그 leaf 안에서만, `@Version` 엔티티의 bulk update는 version을 올려야 함 | 위반 엔티티·쿼리가 있으면 architectureTest 실패 | 매핑·쿼리를 고친다 | `34565130`, `1400dc15`, `bbe944bd` · `src/app-bootstrap/src/architectureTest/.../JpaProductionArchitectureTest.java` |
|
| B-35 | JPA 규칙: 양방향 연관은 한쪽에서만 매핑(`mappedBy`), notification·fileserver 저장소 엔티티는 그 leaf 안에서만, `@Version` 엔티티의 bulk update는 version을 올려야 함 | 위반 엔티티·쿼리가 있으면 architectureTest 실패 | 매핑·쿼리를 고친다 | `34565130`, `1400dc15`, `bbe944bd` · `src/app-bootstrap/src/architectureTest/.../JpaProductionArchitectureTest.java` |
|
||||||
| B-36 | 빌드 검사 강화: `modules.json`에 없는 `build.gradle`이 있으면 `verifyCleanArchitectureDependencies` 실패. `verifyStrictLaneStages --dry-run`은 모든 strict lane이 workflow가 실행하는 단계(`:ci` `:sample-portfolio:check` `:mainCheck` `:integrationCheck` `:performanceCheck` `:releaseCheck`)에 속해야 하고 `.github/workflows`를 읽는다. 명령의 빌드는 `working-directory`(단계·job·workflow `defaults`)에서 시작해 같은 `run:` 셸이 그 앞에서 실행한 `cd <상대 경로>`(`cd src && ./gradlew …`, `cd src; ./gradlew …`, 앞 줄의 `cd src`)를 따라간 뒤 `-p`를 붙인 디렉터리로 정하고(`70fb80bf`(2026-11-04 소유자 결정)), `workflow_dispatch`로만 시작하는 workflow의 명령은 세지 않으며, 축약한 `-x`도 Gradle처럼 맞춰 본다(RR2-04-04). 붙여 쓴 `-x<task>`·`-p<dir>`도 Gradle처럼 읽는다(RR3-04-02). `verifyEnvKeys`: lane 계약 json의 `APP_` 밖 키는 `SPRING_`·`MANAGEMENT_`·`SERVER_`이거나 `secret://…/<VAR>`가 가리키는 변수여야 하고, 레지스트리 `property:` 행은 그 property가 설정 metadata에 있어야 읽히는 것으로 친다(`@ConditionalOnProperty`로만 읽는 스위치는 `META-INF/additional-spring-configuration-metadata.json`에 선언, RR2-04-05). SpotBugs 신뢰도 HIGH → MEDIUM | 등록 안 한 leaf, 단계에 안 걸린 자기 lane, 자기 코드의 MEDIUM 발견이 `ci`·`qualityCheck`를 막는다. `working-directory: src`도 `cd src`도 없이 `./gradlew`를 부르는 자기 workflow 단계는 실행으로 세지 않는다. 확실히 따라갈 수 없는 디렉터리 이동(`cd "$VAR"`, `cd -`, `cd ~`, 절대 경로, `pushd`, `if`/`for`/`case`·`{ }`·서브셸 안의 `cd`, `||`·`|`로 이은 `cd`, 다른 명령과 `&&`로 묶인 `cd` 다음 줄) 뒤의 명령도 세지 않고, 실패 메시지에 그 명령과 이유를 적는다 | leaf를 등록하거나 지운다. 자기 lane은 단계에 건다. 단계를 부르는 workflow 명령에 `working-directory`를 두거나 같은 셸에서 `cd <상대 경로>`로 옮긴 뒤 부른다. SpotBugs 발견은 고치거나 이유를 단 제외로 | `1400dc15`, `34565130`, `bbe944bd`, `5786126c`, `70fb80bf`(2026-11-04 소유자 결정) · `src/build-logic/.../ModuleRegistry.java`, `.../strictlane/StrictLaneStagesPlugin.java`, `.../strictlane/WorkflowGradleInvocations.java`, `.../quality/QualityConventionsPlugin.java`, `src/build.gradle` |
|
| B-36 | 빌드 검사 강화: `modules.json`에 없는 `build.gradle`이 있으면 `verifyCleanArchitectureDependencies` 실패. `verifyStrictLaneStages --dry-run`은 모든 strict lane이 workflow가 실행하는 단계(`:ci` `:sample-portfolio:check` `:mainCheck` `:integrationCheck` `:performanceCheck` `:releaseCheck`)에 속해야 하고 `.github/workflows`를 읽는다. 명령의 빌드는 `working-directory`(단계·job·workflow `defaults`)에서 시작해 같은 `run:` 셸이 그 앞에서 실행한 `cd <상대 경로>`(`cd src && ./gradlew …`, `cd src; ./gradlew …`, 앞 줄의 `cd src`)를 따라간 뒤 `-p`를 붙인 디렉터리로 정하고(`70fb80bf`(2026-11-04 소유자 결정)), `workflow_dispatch`로만 시작하는 workflow의 명령은 세지 않으며, 축약한 `-x`도 Gradle처럼 맞춰 본다(RR2-04-04). 붙여 쓴 `-x<task>`·`-p<dir>`도 Gradle처럼 읽는다(RR3-04-02). `run:` 스크립트를 bash 문법으로 읽어(heredoc·여러 줄 문자열·함수 본문 안의 `cd`는 따라가지 않음), 실패해도 단계를 실패시키지 못하는 명령(`\|\| true`·`\|\| exit 1`, pipefail 없는 파이프 왼쪽, `!`, `&`, `if`·`while` 조건과 `if`·`for`·`case`·함수·`$( )`·`bash -c` 안, `set +e`·최상위 `exit` 뒤, 스크립트 마지막이 아닌 `&&` 목록), Gradle이 거부하는 명령줄(`-mx`)과 묶음 dry-run(`-qm`)은 세지 않고, `shell:`이 기본·`bash`·`sh`가 아닌 단계도 세지 않는다. 단계를 부르지만 세지 않은 명령은 다른 빌드로 읽힌 것까지 실패 메시지에 이유와 함께 적는다(r9). `verifyEnvKeys`: lane 계약 json의 `APP_` 밖 키는 `SPRING_`·`MANAGEMENT_`·`SERVER_`이거나 `secret://…/<VAR>`가 가리키는 변수여야 하고, 레지스트리 `property:` 행은 그 property가 설정 metadata에 있어야 읽히는 것으로 친다(`@ConditionalOnProperty`로만 읽는 스위치는 `META-INF/additional-spring-configuration-metadata.json`에 선언, RR2-04-05). SpotBugs 신뢰도 HIGH → MEDIUM | 등록 안 한 leaf, 단계에 안 걸린 자기 lane, 자기 코드의 MEDIUM 발견이 `ci`·`qualityCheck`를 막는다. `working-directory: src`도 `cd src`도 없이 `./gradlew`를 부르는 자기 workflow 단계는 실행으로 세지 않는다. 확실히 따라갈 수 없는 디렉터리 이동(`cd "$VAR"`, `cd -`, `cd ~`, 절대 경로, `pushd`, `if`/`for`/`case`·`{ }`·서브셸 안의 `cd`, `||`·`|`로 이은 `cd`, 다른 명령과 `&&`로 묶인 `cd` 다음 줄) 뒤의 명령도 세지 않고, 실패 메시지에 그 명령과 이유를 적는다. 단계를 `./gradlew ci \| tee log`(기본 셸), `./gradlew ci \|\| true`, `if ./gradlew ci; then` 같은 모양으로만 부르는 자기 workflow도 실패한다 | leaf를 등록하거나 지운다. 자기 lane은 단계에 건다. 단계를 부르는 workflow 명령에 `working-directory`를 두거나 같은 셸에서 `cd <상대 경로>`로 옮긴 뒤 부른다. 단계 명령은 혼자 한 줄로 두고, 로그를 파이프로 남기려면 `shell: bash`나 앞 줄 `set -o pipefail`을 둔다. SpotBugs 발견은 고치거나 이유를 단 제외로 | `1400dc15`, `34565130`, `bbe944bd`, `5786126c`, `70fb80bf`(2026-11-04 소유자 결정), r9 · `src/build-logic/.../ModuleRegistry.java`, `.../strictlane/StrictLaneStagesPlugin.java`, `.../strictlane/WorkflowGradleInvocations.java`, `.../strictlane/ShellScript.java`, `.../quality/QualityConventionsPlugin.java`, `src/build.gradle` |
|
||||||
| B-37 | app-bootstrap 테스트 lane 분리: 저장소 파일을 읽는 테스트는 태그 `document-contract`(main 단계) 또는 `repository-contract`(`check`)여야 하고, 일반 `test` lane에는 `ca.repository.root`가 없다 | app-bootstrap에 둔 자기 테스트가 저장소 파일을 읽으면 `test`에서 실패 | 태그를 단다 | `1400dc15` · `src/app-bootstrap/build.gradle` |
|
| B-37 | app-bootstrap 테스트 lane 분리: 저장소 파일을 읽는 테스트는 태그 `document-contract`(main 단계) 또는 `repository-contract`(`check`)여야 하고, 일반 `test` lane에는 `ca.repository.root`가 없다 | app-bootstrap에 둔 자기 테스트가 저장소 파일을 읽으면 `test`에서 실패 | 태그를 단다 | `1400dc15` · `src/app-bootstrap/build.gradle` |
|
||||||
| B-40 | 테스트 코드 정적 분석 `testQualityCheck`: SpotBugs·FindSecBugs를 main 밖 모든 source set(test, testFixtures, integrationTest, systemTest 등)에 돌린다. 테스트용 제외 목록은 `config/spotbugs/exclude-test.xml`(보안 범주·내부 상태 노출·생성자 예외·반환값 null 역참조·아키텍처 위반 fixture). 분석 classpath가 그 source set의 runtime classpath로 넓어졌고, 분석이 불완전하면(빠진 클래스) 실패한다. main 빌드는 `mainCheck`(`qualificationCheck`), optional 빌드는 `ci` | 자기 테스트 코드의 SpotBugs 발견(예: `CountDownLatch.await` 반환값 무시, 공유 변수 비원자 쓰기, 닫지 않은 `Statement`)이 main 단계를 막는다. 테스트 classpath에 없는 타입을 참조하면 `SpotBugs analysis incomplete` | 고치거나, 클래스·메서드로 좁힌 Match를 이유와 함께 `exclude-test.xml`에 더한다. 빠진 타입은 그 테스트 suite 의존성에 넣는다 | `2678955c` · `src/build-logic/.../quality/QualityConventionsPlugin.java`, `src/config/spotbugs/exclude-test.xml`, `src/build.gradle` |
|
| B-40 | 테스트 코드 정적 분석 `testQualityCheck`: SpotBugs·FindSecBugs를 main 밖 모든 source set(test, testFixtures, integrationTest, systemTest 등)에 돌린다. 테스트용 제외 목록은 `config/spotbugs/exclude-test.xml`(보안 범주·내부 상태 노출·생성자 예외·반환값 null 역참조·아키텍처 위반 fixture). 분석 classpath가 그 source set의 runtime classpath로 넓어졌고, 분석이 불완전하면(빠진 클래스) 실패한다. main 빌드는 `mainCheck`(`qualificationCheck`), optional 빌드는 `ci` | 자기 테스트 코드의 SpotBugs 발견(예: `CountDownLatch.await` 반환값 무시, 공유 변수 비원자 쓰기, 닫지 않은 `Statement`)이 main 단계를 막는다. 테스트 classpath에 없는 타입을 참조하면 `SpotBugs analysis incomplete` | 고치거나, 클래스·메서드로 좁힌 Match를 이유와 함께 `exclude-test.xml`에 더한다. 빠진 타입은 그 테스트 suite 의존성에 넣는다 | `2678955c` · `src/build-logic/.../quality/QualityConventionsPlugin.java`, `src/config/spotbugs/exclude-test.xml`, `src/build.gradle` |
|
||||||
|
|
||||||
@@ -141,6 +142,13 @@
|
|||||||
파일의 `SET LOCAL`을 상한으로 세지 않는다. 자기 스트림의 이미 배포된 파일이 새로 걸리면 그 파일은 고치지 않고 규칙 이전
|
파일의 `SET LOCAL`을 상한으로 세지 않는다. 자기 스트림의 이미 배포된 파일이 새로 걸리면 그 파일은 고치지 않고 규칙 이전
|
||||||
목록에 더한다(템플릿은 idempotency V1, notification V3, messaging V1003, postgresql V11·V12를 더했다). 파일 경로를 넘기는
|
목록에 더한다(템플릿은 idempotency V1, notification V3, messaging V1003, postgresql V11·V12를 더했다). 파일 경로를 넘기는
|
||||||
`unboundedLockingStatements(Path)`가 옆의 `.sql.conf`까지 읽으니, 복사한 검사는 문자열 대신 경로를 넘긴다.
|
`unboundedLockingStatements(Path)`가 옆의 `.sql.conf`까지 읽으니, 복사한 검사는 문자열 대신 경로를 넘긴다.
|
||||||
|
r9부터 검사기는 Flyway가 `.sql.conf` 없이 스스로 트랜잭션 밖에서 돌리는 문장(`VACUUM`, `CREATE`·`DROP INDEX CONCURRENTLY`,
|
||||||
|
`REINDEX SCHEMA` 등)이 있는 파일도 트랜잭션 밖으로 보고 그 파일의 `SET LOCAL`을 상한으로 세지 않으며(그런 파일은 다른 문장과
|
||||||
|
섞이면 Flyway가 기본 `mixed=false`로 거부한다), `VACUUM FULL`은 "마이그레이션에 두지 말고 운영 절차로" 거부한다.
|
||||||
|
`.sql.conf`는 Flyway처럼 properties로 읽어 `executeInTransaction=FALSE`·`executeInTransaction: false`도 트랜잭션 밖으로 본다.
|
||||||
|
`GRANT … REFERENCES ON`과 `REINDEX (CONCURRENTLY) …`는 더 이상 거부하지 않는다. 자기 스트림 검사가 새로 실패하면 그 파일은
|
||||||
|
Flyway가 거부하거나(`mixed=false`) 상한 없이 도는(`mixed=true`) 파일이다. 아직 배포 전이면 문장을 나누고, 이미 배포했으면
|
||||||
|
규칙 이전 목록에 더한다(r9, 재리뷰 RR4-02-01).
|
||||||
- **번호 충돌**: 템플릿이 이제 postgresql V20~V22, notification V11~V13, sample V8_1, grpc V002·V003을 쓴다. 파생 서비스가 같은
|
- **번호 충돌**: 템플릿이 이제 postgresql V20~V22, notification V11~V13, sample V8_1, grpc V002·V003을 쓴다. 파생 서비스가 같은
|
||||||
위치에 같은 번호를 두었다면 Flyway가 같은 버전 두 개로 실패한다. 자기 마이그레이션은 템플릿과 떨어진 번호대로 옮긴다
|
위치에 같은 번호를 두었다면 Flyway가 같은 버전 두 개로 실패한다. 자기 마이그레이션은 템플릿과 떨어진 번호대로 옮긴다
|
||||||
(이미 적용된 파일 이름을 바꾸면 checksum·history가 어긋나므로 운영 DB에 적용된 것이면 DB 담당과 정한다).
|
(이미 적용된 파일 이름을 바꾸면 checksum·history가 어긋나므로 운영 DB에 적용된 것이면 DB 담당과 정한다).
|
||||||
@@ -224,6 +232,9 @@ V21 실패의 분류는 `docs/runbooks/migration-failed.md` "Classify the failur
|
|||||||
| HTTP client(JDK transport) | 스트리밍 응답의 read-idle 감시가 전용 데몬 스레드 하나(`httpclient-jdk-read-idle`)에서 돈다. 스트림마다 감시 작업 하나, 스트림을 닫으면 작업을 바로 취소 | 스레드 덤프에 그 스레드가 하나 보인다. 공용 `ForkJoinPool`이 바빠도 timeout이 설정값에 난다(전에는 늦게 났다). Apache transport(기본)는 영향 없음 | 3차 확인 리뷰 RR3-03-01 · `src/adapter/outbound/httpclient/.../jdk/ReadIdleInputStream.java` |
|
| HTTP client(JDK transport) | 스트리밍 응답의 read-idle 감시가 전용 데몬 스레드 하나(`httpclient-jdk-read-idle`)에서 돈다. 스트림마다 감시 작업 하나, 스트림을 닫으면 작업을 바로 취소 | 스레드 덤프에 그 스레드가 하나 보인다. 공용 `ForkJoinPool`이 바빠도 timeout이 설정값에 난다(전에는 늦게 났다). Apache transport(기본)는 영향 없음 | 3차 확인 리뷰 RR3-03-01 · `src/adapter/outbound/httpclient/.../jdk/ReadIdleInputStream.java` |
|
||||||
| 멱등성 | `IDEMPOTENCY_RECOVERY_REQUIRED`를 내는 예외 메시지 끝에 scope digest가 붙는다. Redis 기록 조회(INSPECT 스크립트)가 `leaseUntil`을 돌려줘 `processingLeaseUntil`이 실제 lease 끝이다(전에는 key TTL 끝, 즉 lease + replay TTL) | 예외 메시지 전체에 맞추던 로그 매처는 고친다. 회복 절차는 `docs/runbooks/idempotency-unavailable.md`(digest로 기록을 찾는다) | 3차 확인 리뷰 RR3-03-03·05 · `src/application-core/.../idempotency/IdempotencyRecoveryRequiredException.java`, `src/adapter/outbound/cache-redis/.../idempotency/IdempotencyScripts.java` |
|
| 멱등성 | `IDEMPOTENCY_RECOVERY_REQUIRED`를 내는 예외 메시지 끝에 scope digest가 붙는다. Redis 기록 조회(INSPECT 스크립트)가 `leaseUntil`을 돌려줘 `processingLeaseUntil`이 실제 lease 끝이다(전에는 key TTL 끝, 즉 lease + replay TTL) | 예외 메시지 전체에 맞추던 로그 매처는 고친다. 회복 절차는 `docs/runbooks/idempotency-unavailable.md`(digest로 기록을 찾는다) | 3차 확인 리뷰 RR3-03-03·05 · `src/application-core/.../idempotency/IdempotencyRecoveryRequiredException.java`, `src/adapter/outbound/cache-redis/.../idempotency/IdempotencyScripts.java` |
|
||||||
| 멱등성(lease가 지난 실행) | lease가 지난 `EXECUTING` 기록을 claim이 만나면 기록을 바꾸지 않고 500 `IDEMPOTENCY_RECOVERY_REQUIRED`로 답한다. 그 실행의 주인이 늦게 부른 `complete`·`markFailed`는 기록된다. 전에는 두 저장소 모두 기록을 `ABANDONED`로 바꿔(PostgreSQL은 `last_transition_kind` `EXPIRED_EXECUTION`) 늦은 결과를 거절했고 첫 요청도 500이었다. 이미 끝난 lease의 `renew`는 두 저장소 모두 거절한다(Redis는 전에 받아들였다). 남의 lease 지난 실행을 `inspect`하면 `ABANDONED`(전에는 `IN_PROGRESS_OTHER`) | 30s를 넘는 정상 요청이 이제 결과를 남기고 정상 응답을 받는다. 같은 키 재전송은 500을 받은 뒤 재생을 받을 수 있다. 직접 구현한 store는 `IdempotencyStoreContract`의 바뀐 시간 케이스로 확인한다. 운영자는 `EXECUTING` 기록을 지우지 않는다 — 살아 있는 실행의 늦은 결과가 기록을 못 찾아(`ABSENT`) 사라진다(`docs/runbooks/idempotency-unavailable.md`) | `70fb80bf`(2026-11-04 소유자 결정) · `src/application-core/src/testFixtures/.../IdempotencyStoreContract.java`, `src/adapter/outbound/cache-redis/.../idempotency/IdempotencyScripts.java`, `src/adapter/outbound/persistence-jpa/.../postgresql/PostgreSqlIdempotencyStore.java` |
|
| 멱등성(lease가 지난 실행) | lease가 지난 `EXECUTING` 기록을 claim이 만나면 기록을 바꾸지 않고 500 `IDEMPOTENCY_RECOVERY_REQUIRED`로 답한다. 그 실행의 주인이 늦게 부른 `complete`·`markFailed`는 기록된다. 전에는 두 저장소 모두 기록을 `ABANDONED`로 바꿔(PostgreSQL은 `last_transition_kind` `EXPIRED_EXECUTION`) 늦은 결과를 거절했고 첫 요청도 500이었다. 이미 끝난 lease의 `renew`는 두 저장소 모두 거절한다(Redis는 전에 받아들였다). 남의 lease 지난 실행을 `inspect`하면 `ABANDONED`(전에는 `IN_PROGRESS_OTHER`) | 30s를 넘는 정상 요청이 이제 결과를 남기고 정상 응답을 받는다. 같은 키 재전송은 500을 받은 뒤 재생을 받을 수 있다. 직접 구현한 store는 `IdempotencyStoreContract`의 바뀐 시간 케이스로 확인한다. 운영자는 `EXECUTING` 기록을 지우지 않는다 — 살아 있는 실행의 늦은 결과가 기록을 못 찾아(`ABSENT`) 사라진다(`docs/runbooks/idempotency-unavailable.md`) | `70fb80bf`(2026-11-04 소유자 결정) · `src/application-core/src/testFixtures/.../IdempotencyStoreContract.java`, `src/adapter/outbound/cache-redis/.../idempotency/IdempotencyScripts.java`, `src/adapter/outbound/persistence-jpa/.../postgresql/PostgreSqlIdempotencyStore.java` |
|
||||||
|
| 멱등성(lease가 끝난 시작, r9) | lease가 지난 `CLAIMED`는 주인도 시작할 수 없다(`LEASE_EXPIRED`). executor는 작업을 돌리지 않고 503 `IDEMPOTENCY_UNAVAILABLE`(실행 전 거부, 메시지 `the claim's processing lease ran out before the action started`)로 답하고, 다음 같은 키 요청이 그 claim을 넘겨받아 실행한다. 전에는 Redis가 시작해 작업을 돌렸고 그동안 다른 요청은 lease가 지난 실행으로 500을 받았다. PostgreSQL은 `NOT_OWNER`로 거절해 500 `IDEMPOTENCY_RECOVERY_REQUIRED`였다. | claim과 시작 사이가 lease(기본 30s)보다 길었던 드문 요청이 500 대신 503(같은 키 재전송)을 받는다. 클라이언트는 `error.code`로 이미 가르므로 바꿀 것이 없다. 운영자는 이 503에서 저장소 장애를 찾지 않는다(runbook) | r9(재리뷰 README 15 남음, RR5-01-02·03) · `IdempotencyExecutor.java`, `src/adapter/outbound/cache-redis/.../idempotency/IdempotencyScripts.java`, `src/adapter/outbound/persistence-jpa/.../postgresql/PostgreSqlIdempotencyStore.java` |
|
||||||
|
| 빌드 단계(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 <method> …`로 남긴다(클라이언트 취소 제외). STOMP `@MessageMapping` 실패는 Spring의 `Unhandled exception from message handler method`(예외 전체) 대신 같은 줄로 남는다 | ERROR 로그가 늘어난다(전에는 gRPC가 아무것도 남기지 않았다). 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` |
|
| sample-portfolio | 익명 쓰기 401, 포스터 제목 대소문자 무시 유일(409 `POSTER_ALREADY_EXISTS`), 관리자도 남의 work log 수정 불가, 샘플 이벤트 tenant `global` | sample을 남긴 서비스만 | `34565130`, `1400dc15` |
|
||||||
|
|
||||||
## 6. 따라오는 순서
|
## 6. 따라오는 순서
|
||||||
|
|||||||
+25
-12
@@ -86,7 +86,7 @@ status는 코드 표(`HttpStatusErrorCodes`)에 있는 것만 그대로 나간
|
|||||||
| 경우 | status | `error.code` | `retryable` | `Retry-After` | 클라이언트 행동 |
|
| 경우 | status | `error.code` | `retryable` | `Retry-After` | 클라이언트 행동 |
|
||||||
| --- | --- | --- | --- | --- | --- |
|
| --- | --- | --- | --- | --- | --- |
|
||||||
| 재생(replay): 같은 키·같은 본문, 첫 요청 완료 | 첫 요청과 같은 성공 status | — (성공 Envelope) | — | 없음 | 첫 요청의 결과로 받아들인다. `meta`의 id는 이번 요청의 것이다 |
|
| 재생(replay): 같은 키·같은 본문, 첫 요청 완료 | 첫 요청과 같은 성공 status | — (성공 Envelope) | — | 없음 | 첫 요청의 결과로 받아들인다. `meta`의 id는 이번 요청의 것이다 |
|
||||||
| 처리 중(in-flight): 같은 키, 첫 요청이 아직 실행 중 | 409 | `IDEMPOTENT_IN_FLIGHT` | `true` | `2` | 결과 불명. **같은 `Idempotency-Key`로** `Retry-After` 뒤 재전송한다. **새 키 금지** |
|
| 처리 중(in-flight): 같은 키, 첫 요청이 아직 실행 중(Redis 저장소. PostgreSQL 저장소는 409 대신 첫 요청이 끝날 때까지 기다린다 — 아래 "첫 시도가 lease보다 오래 걸릴 때") | 409 | `IDEMPOTENT_IN_FLIGHT` | `true` | `2` | 결과 불명. **같은 `Idempotency-Key`로** `Retry-After` 뒤 재전송한다. **새 키 금지** |
|
||||||
| 본문 불일치(mismatch): 같은 키·다른 본문 | 422 | `IDEMPOTENT_REQUEST_MISMATCH` | `false` | 없음 | 클라이언트 버그. 다시 보내지 않는다. 새 작업이면 새 키를 만든다 |
|
| 본문 불일치(mismatch): 같은 키·다른 본문 | 422 | `IDEMPOTENT_REQUEST_MISMATCH` | `false` | 없음 | 클라이언트 버그. 다시 보내지 않는다. 새 작업이면 새 키를 만든다 |
|
||||||
| 키 누락·형식 오류 | 400 | `IDEMPOTENCY_KEY_INVALID` (`details.reason` = `MISSING`/`MALFORMED`) | `false` | 없음 | 문법에 맞는 키를 붙여 다시 보낸다 |
|
| 키 누락·형식 오류 | 400 | `IDEMPOTENCY_KEY_INVALID` (`details.reason` = `MISSING`/`MALFORMED`) | `false` | 없음 | 문법에 맞는 키를 붙여 다시 보낸다 |
|
||||||
|
|
||||||
@@ -108,7 +108,7 @@ status는 코드 표(`HttpStatusErrorCodes`)에 있는 것만 그대로 나간
|
|||||||
|
|
||||||
| 경우 | status | `error.code` | `retryable` | `Retry-After` | 클라이언트 행동 |
|
| 경우 | status | `error.code` | `retryable` | `Retry-After` | 클라이언트 행동 |
|
||||||
| --- | --- | --- | --- | --- | --- |
|
| --- | --- | --- | --- | --- | --- |
|
||||||
| 작업 실행 전(claim·시작 단계) 멱등성 저장소 응답 없음 | 503 | `IDEMPOTENCY_UNAVAILABLE` | `true` | 없음 | 작업은 실행되지 않았다. 같은 키로 나중에 다시 보낸다 |
|
| 작업 실행 전(claim·시작 단계) 멱등성 저장소 응답 없음. 또는 claim의 processing lease가 작업 시작 전에 끝나 저장소가 시작을 거절함 | 503 | `IDEMPOTENCY_UNAVAILABLE` | `true` | 없음 | 작업은 실행되지 않았다. 같은 키로 나중에 다시 보낸다(다음 요청이 그 claim을 넘겨받아 실행한다) |
|
||||||
| 작업 실행 뒤 결과 기록(complete 단계) 중 저장소 응답 없음 — **결과 불명** | 503 | `IDEMPOTENCY_COMPLETION_UNKNOWN` | `true` | 없음 | "적용되지 않았다"고 알리지 않는다. **같은 키로** 나중에 다시 보낸다. 새 키 금지 |
|
| 작업 실행 뒤 결과 기록(complete 단계) 중 저장소 응답 없음 — **결과 불명** | 503 | `IDEMPOTENCY_COMPLETION_UNKNOWN` | `true` | 없음 | "적용되지 않았다"고 알리지 않는다. **같은 키로** 나중에 다시 보낸다. 새 키 금지 |
|
||||||
| 이전 시도의 효과를 증명할 수 없음 | 500 | `IDEMPOTENCY_RECOVERY_REQUIRED` | `false` | 없음 | 자동 재시도하지 않는다. 같은 키 재전송은 안전하다 — 서버는 효과가 있었을 수 있는 작업을 다시 돌리지 않고, 첫 시도가 늦게 끝났으면 그 결과를 재생하며, 효과 없이 끝났으면 실행하고, 아니면 다시 500이다. 결과는 업무 데이터로 확인하고, 효과가 없다고 확인된 뒤에만 운영 절차(`docs/runbooks/idempotency-unavailable.md`)에 따라 새 키로 다시 보낸다 |
|
| 이전 시도의 효과를 증명할 수 없음 | 500 | `IDEMPOTENCY_RECOVERY_REQUIRED` | `false` | 없음 | 자동 재시도하지 않는다. 같은 키 재전송은 안전하다 — 서버는 효과가 있었을 수 있는 작업을 다시 돌리지 않고, 첫 시도가 늦게 끝났으면 그 결과를 재생하며, 효과 없이 끝났으면 실행하고, 아니면 다시 500이다. 결과는 업무 데이터로 확인하고, 효과가 없다고 확인된 뒤에만 운영 절차(`docs/runbooks/idempotency-unavailable.md`)에 따라 새 키로 다시 보낸다 |
|
||||||
|
|
||||||
@@ -118,15 +118,27 @@ status는 코드 표(`HttpStatusErrorCodes`)에 있는 것만 그대로 나간
|
|||||||
503이어도 code가 다르다. 클라이언트는 status가 아니라 `error.code`로 가른다.
|
503이어도 code가 다르다. 클라이언트는 status가 아니라 `error.code`로 가른다.
|
||||||
- **같은 키로 다시 보내면 서버가 판정하고, 작업을 다시 돌리지 않는다.** 결과가 실제로는 기록됐으면
|
- **같은 키로 다시 보내면 서버가 판정하고, 작업을 다시 돌리지 않는다.** 결과가 실제로는 기록됐으면
|
||||||
재생(첫 요청의 성공 응답), 첫 시도의 processing lease(`processing-lease`, 기본 30s)가 아직 남았으면 409
|
재생(첫 요청의 성공 응답), 첫 시도의 processing lease(`processing-lease`, 기본 30s)가 아직 남았으면 409
|
||||||
`IDEMPOTENT_IN_FLIGHT`, lease가 지났으면 500 `IDEMPOTENCY_RECOVERY_REQUIRED`다. 새 키로 보내면 서버는 다른
|
`IDEMPOTENT_IN_FLIGHT`, lease가 지났으면 500 `IDEMPOTENCY_RECOVERY_REQUIRED`다. 이것은 Redis 저장소의
|
||||||
요청으로 보고 막지 못한다(재리뷰 2026-11-03 README 4절 결정 RR-02-03, 2026-11-04 9.1절 결정 RR-01-11).
|
판정이다. PostgreSQL 저장소는 아래처럼 첫 요청이 끝날 때까지 기다린 뒤 판정한다. 새 키로 보내면 서버는
|
||||||
- **첫 시도가 lease보다 오래 걸려도 그 결과는 기록된다.** executor는 lease를 늘리지 않으므로 30s를 넘는
|
다른 요청으로 보고 막지 못한다(재리뷰 2026-11-03 README 4절 결정 RR-02-03, 2026-11-04 9.1절 결정
|
||||||
정상 요청도 lease가 지난다. lease가 지난 실행 기록을 다음 요청이 만나면 두 저장소(PostgreSQL·Redis) 모두
|
RR-01-11).
|
||||||
500으로 답하고 기록은 건드리지 않는다. 첫 시도가 그 뒤에 끝나면 결과가 그대로 기록되고, 첫 요청은 자기
|
- **첫 시도가 lease보다 오래 걸릴 때 — 저장소마다 다르다.** executor는 lease를 늘리지 않으므로 30s를 넘는
|
||||||
응답을 정상으로 받는다. 그 뒤 같은 키 요청은 그 결과를 재생한다. 첫 시도가 실패를 보고하면 그 실패가
|
정상 요청도 lease가 지난다(재리뷰 2026-11-04 RR5-01-05).
|
||||||
기록된다(효과 불명이면 계속 500, 효과 없는 재시도 가능 실패면 다음 같은 키 요청이 다시 실행한다). 기록이
|
- Redis: lease가 지난 실행 기록을 다음 요청이 만나면 500으로 답하고 기록은 건드리지 않는다. 첫 시도가
|
||||||
이미 사라진 뒤에 끝나면 결과를 기록하지 못해 첫 요청도 500 `IDEMPOTENCY_RECOVERY_REQUIRED`를 받는다
|
그 뒤에 끝나면 결과가 그대로 기록되고, 첫 요청은 자기 응답을 정상으로 받는다. 그 뒤 같은 키 요청은 그
|
||||||
(2026-11-04 소유자 결정).
|
결과를 재생한다. 첫 시도가 실패를 보고하면 먼저 온 보고 하나가 기록된다(효과 불명이면 계속 500, 효과
|
||||||
|
없는 재시도 가능 실패면 다음 같은 키 요청이 다시 실행한다). 기록이 이미 사라진 뒤에 끝나면 결과를
|
||||||
|
기록하지 못해 첫 요청도 500 `IDEMPOTENCY_RECOVERY_REQUIRED`를 받는다(2026-11-04 소유자 결정).
|
||||||
|
- PostgreSQL: 템플릿처럼 executor를 유스케이스의 쓰기 트랜잭션 하나 안에서 부르면 claim 기록은 그
|
||||||
|
트랜잭션이 끝날 때 함께 커밋되거나 롤백된다. 그래서 같은 키 요청은 409나 500을 받지 않고 그 기록에서
|
||||||
|
기다린다. 첫 트랜잭션이 커밋되면 재생을, 롤백되면 새 실행을 받는다. lease가 지나도 같다. 작업이 실패해
|
||||||
|
예외로 끝난 요청은 executor가 남긴 실패 기록도 함께 롤백되므로, 효과 불명 실패도 다음 같은 키 요청이
|
||||||
|
다시 실행한다. 또 쓰기 트랜잭션 제한(`app.persistence-jpa.transaction.write-timeout`, 기본 30s — 기본
|
||||||
|
lease와 같다, 업그레이드 안내 B-21)이 두 요청에 모두 걸린다. 첫 요청이 그보다 오래 걸리면 취소되고 claim
|
||||||
|
기록도 함께 롤백된다(503 `DB_QUERY_CANCELED`). 기다리던 요청도 자기 제한을 넘기면 같은 코드로 끝난다.
|
||||||
|
어느 경우든 롤백된 DB 변경은 남지 않지만, 트랜잭션 밖 효과(다른 시스템 호출, 메시지)는 다음 같은 키
|
||||||
|
요청에서 두 번 일어날 수 있다. 이 저장소가 막는 중복은 같은 트랜잭션 안의 DB 효과다
|
||||||
|
(`PostgreSqlIdempotencyIntegrationTest`).
|
||||||
- **서버가 기억하는 기간.** 위 판정은 기록이 남아 있는 동안만 선다. 기록이 사라지면 같은 키는 새
|
- **서버가 기억하는 기간.** 위 판정은 기록이 남아 있는 동안만 선다. 기록이 사라지면 같은 키는 새
|
||||||
요청으로 실행된다. 기록의 수명은 시도가 어떻게 끝났는지로 갈린다.
|
요청으로 실행된다. 기록의 수명은 시도가 어떻게 끝났는지로 갈린다.
|
||||||
- 완료된 응답: 완료부터 `replay-ttl`(`APP_IDEMPOTENCY_TTL`, 기본 24h).
|
- 완료된 응답: 완료부터 `replay-ttl`(`APP_IDEMPOTENCY_TTL`, 기본 24h).
|
||||||
@@ -134,7 +146,8 @@ status는 코드 표(`HttpStatusErrorCodes`)에 있는 것만 그대로 나간
|
|||||||
쓴다. 그 사이 첫 시도가 끝나면 그때부터 위(완료)나 아래(실패)의 수명으로 바뀐다.
|
쓴다. 그 사이 첫 시도가 끝나면 그때부터 위(완료)나 아래(실패)의 수명으로 바뀐다.
|
||||||
- 실패로 표시된 시도: 작업이 예외를 던졌거나 효과 불명으로 끝나 포기(abandoned)된 시도, 효과 없이
|
- 실패로 표시된 시도: 작업이 예외를 던졌거나 효과 불명으로 끝나 포기(abandoned)된 시도, 효과 없이
|
||||||
재시도 가능으로 끝난 시도. 표시한 때부터 `failure-retention`(`APP_IDEMPOTENCY_FAILURE_RETENTION`,
|
재시도 가능으로 끝난 시도. 표시한 때부터 `failure-retention`(`APP_IDEMPOTENCY_FAILURE_RETENTION`,
|
||||||
기본 24h).
|
기본 24h). PostgreSQL 저장소를 쓰기 트랜잭션 하나 안에서 쓰면 실패 기록은 요청의 롤백과 함께 사라져
|
||||||
|
남지 않는다(위 PostgreSQL 항목).
|
||||||
|
|
||||||
`replay-ttl`이 `processing-lease`보다 짧으면 기동이 실패한다(재리뷰 2026-11-04 RR-03-11).
|
`replay-ttl`이 `processing-lease`보다 짧으면 기동이 실패한다(재리뷰 2026-11-04 RR-03-11).
|
||||||
`failure-retention`이 `replay-ttl`보다 짧아도 기동이 실패한다. 더 짧으면 효과 불명으로 포기한 기록이 그만큼
|
`failure-retention`이 `replay-ttl`보다 짧아도 기동이 실패한다. 더 짧으면 효과 불명으로 포기한 기록이 그만큼
|
||||||
|
|||||||
+2
-1
@@ -121,7 +121,8 @@ APP_RATE_LIMIT_REFILL_TOKENS=100
|
|||||||
APP_RATE_LIMIT_REFILL_PERIOD=1s
|
APP_RATE_LIMIT_REFILL_PERIOD=1s
|
||||||
APP_RATE_LIMIT_MAXIMUM_COST=10
|
APP_RATE_LIMIT_MAXIMUM_COST=10
|
||||||
APP_RATE_LIMIT_CLEANUP_GRACE=5s
|
APP_RATE_LIMIT_CLEANUP_GRACE=5s
|
||||||
# Replay TTL: at most 72h and not shorter than APP_IDEMPOTENCY_PROCESSING_LEASE (startup fails).
|
# Replay TTL: at most 72h, not shorter than APP_IDEMPOTENCY_PROCESSING_LEASE and not longer than
|
||||||
|
# APP_IDEMPOTENCY_FAILURE_RETENTION (startup fails) — raising it past 24h means raising that too.
|
||||||
APP_IDEMPOTENCY_TTL=24h
|
APP_IDEMPOTENCY_TTL=24h
|
||||||
# disabled | redis | postgresql. postgresql refuses a non-PostgreSQL data source, so bootRunH2
|
# disabled | redis | postgresql. postgresql refuses a non-PostgreSQL data source, so bootRunH2
|
||||||
# runs with disabled or redis.
|
# runs with disabled or redis.
|
||||||
|
|||||||
+3
-2
@@ -28,7 +28,7 @@ Checkstyle은 **포매터가 표현할 수 없는 것만** — 네이밍과 몇
|
|||||||
| `qualificationCheck` | 전체 기동(system) 레인과 보조 source set Checkstyle을 실행 |
|
| `qualificationCheck` | 전체 기동(system) 레인과 보조 source set Checkstyle을 실행 |
|
||||||
| `integrationCheck` | 선언된 strict integration lane(sample 포함)을 실행. 대부분 container runtime이 필요. 입력이 필요한 lane(Redis topology: `-Predis.topology.mode`, AWS: 보호 자격 증명 env)은 입력이 없으면 빠지고 집계가 그 이유를 출력 |
|
| `integrationCheck` | 선언된 strict integration lane(sample 포함)을 실행. 대부분 container runtime이 필요. 입력이 필요한 lane(Redis topology: `-Predis.topology.mode`, AWS: 보호 자격 증명 env)은 입력이 없으면 빠지고 집계가 그 이유를 출력 |
|
||||||
| `performanceCheck` | 선언된 strict performance lane(부하·종료·pool·자원 상한)을 실행. 실서버·container가 필요. `integration-main.yml` `performance-check`가 main·nightly에 돌림 |
|
| `performanceCheck` | 선언된 strict performance lane(부하·종료·pool·자원 상한)을 실행. 실서버·container가 필요. `integration-main.yml` `performance-check`가 main·nightly에 돌림 |
|
||||||
| `verifyStrictLaneStages` | `--dry-run` 전용. `explicitOnly`가 아닌 strict lane이 workflow가 실제 실행하는 단계(`ci`·`:sample-portfolio:check`·`mainCheck`·`integrationCheck`·`performanceCheck`·`releaseCheck`) 중 하나의 계획에 있는지, 각 단계를 workflow가 `--dry-run` 없이 실행하는지 검사. PR 게이트가 돌림 |
|
| `verifyStrictLaneStages` | `--dry-run` 전용. `explicitOnly`가 아닌 strict lane이 workflow가 실제 실행하는 단계(`ci`·`:sample-portfolio:check`·`mainCheck`·`integrationCheck`·`performanceCheck`·`releaseCheck`) 중 하나의 계획에 있는지, 각 단계를 workflow가 `--dry-run` 없이 실행하는지 검사. 실패해도 단계를 실패시키지 못하는 명령(`\|\| true`, pipefail 없는 파이프, `if` 조건 등)은 실행으로 세지 않는다. PR 게이트가 돌림 |
|
||||||
| `ci` | PR 게이트: 모든 leaf `check`(API surface 검사 포함, 소유자 결정 20) + `architectureCheck` + `qualityCheck` |
|
| `ci` | PR 게이트: 모든 leaf `check`(API surface 검사 포함, 소유자 결정 20) + `architectureCheck` + `qualityCheck` |
|
||||||
| `mainCheck` | main 단계: `configContractCheck` + `qualificationCheck` + sample web 계약 + sample 전체 기동(`:sample-portfolio:systemTest`) + `verifyPublicPathSnapshot` + 전송·메시징 qualification 레인 + 각 leaf의 `mainCheck`(문서 대조 레인 `*DocumentContractTest`, objectstorage MinIO 레인) |
|
| `mainCheck` | main 단계: `configContractCheck` + `qualificationCheck` + sample web 계약 + sample 전체 기동(`:sample-portfolio:systemTest`) + `verifyPublicPathSnapshot` + 전송·메시징 qualification 레인 + 각 leaf의 `mainCheck`(문서 대조 레인 `*DocumentContractTest`, objectstorage MinIO 레인) |
|
||||||
| `releaseCheck` | tag 전용 검사: `verifyReleaseProvenance` + `verifyPublicPathSnapshot`(`ci`를 다시 돌리지 않음) |
|
| `releaseCheck` | tag 전용 검사: `verifyReleaseProvenance` + `verifyPublicPathSnapshot`(`ci`를 다시 돌리지 않음) |
|
||||||
@@ -237,7 +237,8 @@ drift하기 시작하면 그때 자동화합니다. 진짜 항목을 상대로,
|
|||||||
`disabled` 나 `redis` 를 씁니다.
|
`disabled` 나 `redis` 를 씁니다.
|
||||||
- **`APP_IDEMPOTENCY_TTL`** — 완료 응답을 재생할 수 있는 기간(`replay-ttl`). duration(예: `24h`).
|
- **`APP_IDEMPOTENCY_TTL`** — 완료 응답을 재생할 수 있는 기간(`replay-ttl`). duration(예: `24h`).
|
||||||
최대 72h 이고 넘으면 기동을 거부합니다. (D6) `APP_IDEMPOTENCY_PROCESSING_LEASE`(기본 30s)보다
|
최대 72h 이고 넘으면 기동을 거부합니다. (D6) `APP_IDEMPOTENCY_PROCESSING_LEASE`(기본 30s)보다
|
||||||
짧아도 기동을 거부합니다.
|
짧아도, `APP_IDEMPOTENCY_FAILURE_RETENTION`(기본 24h)보다 길어도 기동을 거부합니다. 24h보다
|
||||||
|
올리려면 `APP_IDEMPOTENCY_FAILURE_RETENTION`도 함께 올립니다.
|
||||||
|
|
||||||
### Async executor
|
### Async executor
|
||||||
|
|
||||||
|
|||||||
+15
@@ -5,11 +5,14 @@ import dev.caskeleton.shared.error.ApiErrorCode;
|
|||||||
import dev.caskeleton.shared.error.Category;
|
import dev.caskeleton.shared.error.Category;
|
||||||
import dev.caskeleton.shared.error.ClientErrorMessages;
|
import dev.caskeleton.shared.error.ClientErrorMessages;
|
||||||
import dev.caskeleton.shared.error.OperationalError;
|
import dev.caskeleton.shared.error.OperationalError;
|
||||||
|
import dev.caskeleton.shared.error.ServerFailureLog;
|
||||||
import graphql.ErrorClassification;
|
import graphql.ErrorClassification;
|
||||||
import graphql.GraphQLError;
|
import graphql.GraphQLError;
|
||||||
import java.util.EnumMap;
|
import java.util.EnumMap;
|
||||||
import java.util.Map;
|
import java.util.Map;
|
||||||
import java.util.Objects;
|
import java.util.Objects;
|
||||||
|
import org.slf4j.Logger;
|
||||||
|
import org.slf4j.LoggerFactory;
|
||||||
import org.springframework.graphql.execution.ErrorType;
|
import org.springframework.graphql.execution.ErrorType;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
@@ -33,9 +36,16 @@ import org.springframework.graphql.execution.ErrorType;
|
|||||||
* <p>An unrecognised failure never contributes its own message. That is the fail-closed direction:
|
* <p>An unrecognised failure never contributes its own message. That is the fail-closed direction:
|
||||||
* a new exception type nobody mapped becomes an opaque internal error with a correlation id, and
|
* a new exception type nobody mapped becomes an opaque internal error with a correlation id, and
|
||||||
* the detail goes to the log under that id ({@link GraphQlExceptionResolver}).
|
* the detail goes to the log under that id ({@link GraphQlExceptionResolver}).
|
||||||
|
*
|
||||||
|
* <p>A carrier is logged here, with {@link ServerFailureLog}'s line — the one the web and gRPC
|
||||||
|
* adapters write — plus the execution id the client received. A server-side code therefore leaves
|
||||||
|
* its detail in the log, such as the scope digest of an {@code IDEMPOTENCY_RECOVERY_REQUIRED}
|
||||||
|
* (review 2026-11-04 RR4-03-03); a persistence failure leaves its classification only.
|
||||||
*/
|
*/
|
||||||
public final class GraphQlWireErrorMapper {
|
public final class GraphQlWireErrorMapper {
|
||||||
|
|
||||||
|
private static final Logger LOG = LoggerFactory.getLogger(GraphQlWireErrorMapper.class);
|
||||||
|
|
||||||
/** How one shared category is rendered on the GraphQL wire. */
|
/** How one shared category is rendered on the GraphQL wire. */
|
||||||
private record Rendering(GraphQlErrorCategory wireCategory, ErrorClassification classification) {}
|
private record Rendering(GraphQlErrorCategory wireCategory, ErrorClassification classification) {}
|
||||||
|
|
||||||
@@ -104,6 +114,11 @@ public final class GraphQlWireErrorMapper {
|
|||||||
}
|
}
|
||||||
ApiErrorCode shared = sharedCodeOf(failure);
|
ApiErrorCode shared = sharedCodeOf(failure);
|
||||||
if (shared != null) {
|
if (shared != null) {
|
||||||
|
ServerFailureLog.of(failure, shared)
|
||||||
|
.ifPresent(
|
||||||
|
line ->
|
||||||
|
LOG.error(
|
||||||
|
line.format(" (executionId={})"), line.arguments(context.executionId())));
|
||||||
return fromApiError(shared, context);
|
return fromApiError(shared, context);
|
||||||
}
|
}
|
||||||
return applicationMappings.resolve(failure, context);
|
return applicationMappings.resolve(failure, context);
|
||||||
|
|||||||
+90
@@ -2,14 +2,24 @@ package dev.caskeleton.adapter.inbound.graphql.error;
|
|||||||
|
|
||||||
import static org.assertj.core.api.Assertions.assertThat;
|
import static org.assertj.core.api.Assertions.assertThat;
|
||||||
|
|
||||||
|
import ch.qos.logback.classic.Level;
|
||||||
|
import ch.qos.logback.classic.Logger;
|
||||||
|
import ch.qos.logback.classic.spi.ILoggingEvent;
|
||||||
|
import ch.qos.logback.core.read.ListAppender;
|
||||||
import dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlBatchTimeoutException;
|
import dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlBatchTimeoutException;
|
||||||
import dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlMissingKeyException;
|
import dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlMissingKeyException;
|
||||||
import dev.caskeleton.adapter.inbound.graphql.execution.GraphQlRequestCancelledException;
|
import dev.caskeleton.adapter.inbound.graphql.execution.GraphQlRequestCancelledException;
|
||||||
|
import dev.caskeleton.application.idempotency.IdempotencyRecoveryRequiredException;
|
||||||
|
import dev.caskeleton.shared.error.OperationalError;
|
||||||
|
import dev.caskeleton.shared.error.PersistenceFailureException;
|
||||||
|
import java.sql.SQLException;
|
||||||
|
import java.util.List;
|
||||||
import java.util.stream.Stream;
|
import java.util.stream.Stream;
|
||||||
import org.junit.jupiter.api.DisplayName;
|
import org.junit.jupiter.api.DisplayName;
|
||||||
import org.junit.jupiter.params.ParameterizedTest;
|
import org.junit.jupiter.params.ParameterizedTest;
|
||||||
import org.junit.jupiter.params.provider.Arguments;
|
import org.junit.jupiter.params.provider.Arguments;
|
||||||
import org.junit.jupiter.params.provider.MethodSource;
|
import org.junit.jupiter.params.provider.MethodSource;
|
||||||
|
import org.slf4j.LoggerFactory;
|
||||||
|
|
||||||
class GraphQlWireErrorMapperTest {
|
class GraphQlWireErrorMapperTest {
|
||||||
|
|
||||||
@@ -128,4 +138,84 @@ class GraphQlWireErrorMapperTest {
|
|||||||
extensions -> extensions.get("retryable"))
|
extensions -> extensions.get("retryable"))
|
||||||
.containsExactly("DEPENDENCY_TIMEOUT", "DEPENDENCY", true);
|
.containsExactly("DEPENDENCY_TIMEOUT", "DEPENDENCY", true);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@org.junit.jupiter.api.Test
|
||||||
|
void aServerSideCarrierIsLoggedAtErrorWithTheExecutionIdAndTheFailureThatNamesTheScopeDigest() {
|
||||||
|
// given
|
||||||
|
GraphQlWireErrorMapper mapper = GraphQlWireErrorMapper.masking();
|
||||||
|
RuntimeException failure =
|
||||||
|
new IdempotencyRecoveryRequiredException(
|
||||||
|
"claim requires reconciliation: CHARGE_CARD::v1::3f9a");
|
||||||
|
|
||||||
|
// when
|
||||||
|
List<ILoggingEvent> logged =
|
||||||
|
loggedWhile(() -> mapper.toGraphQlError(failure, GraphQlErrorContext.of("exec-9")));
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(logged)
|
||||||
|
.singleElement()
|
||||||
|
.extracting(
|
||||||
|
ILoggingEvent::getLevel,
|
||||||
|
ILoggingEvent::getFormattedMessage,
|
||||||
|
event -> event.getThrowableProxy().getMessage())
|
||||||
|
.containsExactly(
|
||||||
|
Level.ERROR,
|
||||||
|
"failure classified as IDEMPOTENCY_RECOVERY_REQUIRED (category=DATA_INTEGRITY,"
|
||||||
|
+ " retryable=false) (executionId=exec-9)",
|
||||||
|
"claim requires reconciliation: CHARGE_CARD::v1::3f9a");
|
||||||
|
}
|
||||||
|
|
||||||
|
@org.junit.jupiter.api.Test
|
||||||
|
void aPersistenceFailureIsLoggedByItsClassificationWithoutItsCause() {
|
||||||
|
// given
|
||||||
|
GraphQlWireErrorMapper mapper = GraphQlWireErrorMapper.masking();
|
||||||
|
RuntimeException failure =
|
||||||
|
new PersistenceFailureException(
|
||||||
|
OperationalError.DB_UNAVAILABLE,
|
||||||
|
"08006",
|
||||||
|
new SQLException("jdbc:postgresql://db.internal/customer?password=secret", "08006"));
|
||||||
|
|
||||||
|
// when
|
||||||
|
List<ILoggingEvent> logged =
|
||||||
|
loggedWhile(() -> mapper.map(failure, GraphQlErrorContext.of("exec-9")));
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(logged)
|
||||||
|
.singleElement()
|
||||||
|
.extracting(ILoggingEvent::getFormattedMessage, ILoggingEvent::getThrowableProxy)
|
||||||
|
.containsExactly(
|
||||||
|
"persistence failure classified as DB_UNAVAILABLE (category=TRANSIENT_DEPENDENCY,"
|
||||||
|
+ " retryable=true) (executionId=exec-9)",
|
||||||
|
null);
|
||||||
|
}
|
||||||
|
|
||||||
|
@org.junit.jupiter.api.Test
|
||||||
|
void aClientSideCarrierIsNotLogged() {
|
||||||
|
// given
|
||||||
|
GraphQlWireErrorMapper mapper = GraphQlWireErrorMapper.masking();
|
||||||
|
|
||||||
|
// when
|
||||||
|
List<ILoggingEvent> logged =
|
||||||
|
loggedWhile(
|
||||||
|
() ->
|
||||||
|
mapper.map(
|
||||||
|
new IllegalArgumentException("bad cursor"), GraphQlErrorContext.of("exec-9")));
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(logged).isEmpty();
|
||||||
|
}
|
||||||
|
|
||||||
|
private static List<ILoggingEvent> loggedWhile(Runnable action) {
|
||||||
|
Logger logger = (Logger) LoggerFactory.getLogger(GraphQlWireErrorMapper.class);
|
||||||
|
ListAppender<ILoggingEvent> appender = new ListAppender<>();
|
||||||
|
appender.start();
|
||||||
|
logger.addAppender(appender);
|
||||||
|
try {
|
||||||
|
action.run();
|
||||||
|
} finally {
|
||||||
|
logger.detachAppender(appender);
|
||||||
|
appender.stop();
|
||||||
|
}
|
||||||
|
return appender.list;
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -151,6 +151,12 @@ handler throw, listener callback throw, `responseObserver.onError(...)`, raw
|
|||||||
예외 메시지(SQLState/업스트림 세부를 담을 수 있음)는 절대 클라이언트에 내보내지 않는다. 인식되지
|
예외 메시지(SQLState/업스트림 세부를 담을 수 있음)는 절대 클라이언트에 내보내지 않는다. 인식되지
|
||||||
않은 예외와 raw gRPC status/description은 원래 status를 신뢰하지 않고 `Status.INTERNAL` +
|
않은 예외와 raw gRPC status/description은 원래 status를 신뢰하지 않고 `Status.INTERNAL` +
|
||||||
`INTERNAL_ERROR`로 폴백한다. 입력 trailers도 폐기한다.
|
`INTERNAL_ERROR`로 폴백한다. 입력 trailers도 폐기한다.
|
||||||
|
- **서버 로그**: carrier는 web과 같은 줄(shared-contract `ServerFailureLog`)에 ` (method=<서비스/메서드>)`를
|
||||||
|
붙여 ERROR로 남긴다. persistence 실패는 분류만, 5xx carrier는 예외와 함께, 4xx carrier는 남기지 않는다.
|
||||||
|
인식되지 않아 `INTERNAL_ERROR`로 답한 실패는 `unhandled failure on <method> answered as INTERNAL_ERROR
|
||||||
|
(status=<code>)`에 원인 예외를 붙인다. raw status만 있으면 description은 남기지 않는다(입력이 들 수
|
||||||
|
있다). 클라이언트가 취소한 호출(`CANCELLED`)은 남기지 않는다. 그래서 `IDEMPOTENCY_RECOVERY_REQUIRED`도
|
||||||
|
web처럼 scope digest를 로그에 남긴다(재리뷰 RR4-03-03, `docs/runbooks/idempotency-unavailable.md`).
|
||||||
|
|
||||||
`Category → Status` 표(설계 스펙 Error Mapping SSOT):
|
`Category → Status` 표(설계 스펙 Error Mapping SSOT):
|
||||||
|
|
||||||
|
|||||||
+44
-9
@@ -3,6 +3,7 @@ package dev.caskeleton.adapter.inbound.grpc;
|
|||||||
import dev.caskeleton.shared.error.ApiErrorCarrier;
|
import dev.caskeleton.shared.error.ApiErrorCarrier;
|
||||||
import dev.caskeleton.shared.error.ApiErrorCode;
|
import dev.caskeleton.shared.error.ApiErrorCode;
|
||||||
import dev.caskeleton.shared.error.OperationalError;
|
import dev.caskeleton.shared.error.OperationalError;
|
||||||
|
import dev.caskeleton.shared.error.ServerFailureLog;
|
||||||
import io.grpc.ForwardingServerCall.SimpleForwardingServerCall;
|
import io.grpc.ForwardingServerCall.SimpleForwardingServerCall;
|
||||||
import io.grpc.ForwardingServerCallListener.SimpleForwardingServerCallListener;
|
import io.grpc.ForwardingServerCallListener.SimpleForwardingServerCallListener;
|
||||||
import io.grpc.Metadata;
|
import io.grpc.Metadata;
|
||||||
@@ -11,6 +12,8 @@ import io.grpc.ServerCallHandler;
|
|||||||
import io.grpc.ServerInterceptor;
|
import io.grpc.ServerInterceptor;
|
||||||
import io.grpc.Status;
|
import io.grpc.Status;
|
||||||
import java.util.concurrent.atomic.AtomicBoolean;
|
import java.util.concurrent.atomic.AtomicBoolean;
|
||||||
|
import org.slf4j.Logger;
|
||||||
|
import org.slf4j.LoggerFactory;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Centralises the gRPC error contract: a feature service just throws or calls {@code onError}, and
|
* Centralises the gRPC error contract: a feature service just throws or calls {@code onError}, and
|
||||||
@@ -29,9 +32,20 @@ import java.util.concurrent.atomic.AtomicBoolean;
|
|||||||
* client sees the stable code, category and retryability in the trailers and the shared category
|
* client sees the stable code, category and retryability in the trailers and the shared category
|
||||||
* message as the status description — raw descriptions and input trailers, which may carry a
|
* message as the status description — raw descriptions and input trailers, which may carry a
|
||||||
* SQLState or upstream detail, are never surfaced.
|
* SQLState or upstream detail, are never surfaced.
|
||||||
|
*
|
||||||
|
* <p>What the client cannot see goes to the server log, as on the web: a carrier is logged with
|
||||||
|
* {@link ServerFailureLog}'s line, the one the web and GraphQL adapters write, plus the method — so
|
||||||
|
* an {@code IDEMPOTENCY_RECOVERY_REQUIRED} answer leaves the scope digest the runbook looks the
|
||||||
|
* record up by ({@code docs/runbooks/idempotency-unavailable.md}, review 2026-11-04 RR4-03-03). An
|
||||||
|
* unrecognised failure answered as {@code INTERNAL_ERROR} is logged with its exception, or by its
|
||||||
|
* status code alone when the service closed with a raw status — its description may echo input. A
|
||||||
|
* call the client cancelled is not logged: nobody is waiting for the answer, and nothing failed on
|
||||||
|
* the server.
|
||||||
*/
|
*/
|
||||||
public class GrpcExceptionHandlingInterceptor implements ServerInterceptor {
|
public class GrpcExceptionHandlingInterceptor implements ServerInterceptor {
|
||||||
|
|
||||||
|
private static final Logger log = LoggerFactory.getLogger(GrpcExceptionHandlingInterceptor.class);
|
||||||
|
|
||||||
private final GrpcStatusMapper statusMapper;
|
private final GrpcStatusMapper statusMapper;
|
||||||
|
|
||||||
public GrpcExceptionHandlingInterceptor(GrpcStatusMapper statusMapper) {
|
public GrpcExceptionHandlingInterceptor(GrpcStatusMapper statusMapper) {
|
||||||
@@ -107,12 +121,18 @@ public class GrpcExceptionHandlingInterceptor implements ServerInterceptor {
|
|||||||
return;
|
return;
|
||||||
}
|
}
|
||||||
|
|
||||||
ApiErrorCode code = errorCodeOf(status.getCause());
|
String method = delegate.getMethodDescriptor().getFullMethodName();
|
||||||
if (code == null) {
|
Throwable carrier = carrierOf(status.getCause());
|
||||||
code =
|
ApiErrorCode code;
|
||||||
status.getCause() instanceof IllegalArgumentException
|
if (carrier != null) {
|
||||||
? OperationalError.BAD_PARAMETER
|
code = ((ApiErrorCarrier) carrier).errorCode();
|
||||||
: OperationalError.INTERNAL_ERROR;
|
ServerFailureLog.of(carrier, code)
|
||||||
|
.ifPresent(line -> log.error(line.format(" (method={})"), line.arguments(method)));
|
||||||
|
} else if (status.getCause() instanceof IllegalArgumentException) {
|
||||||
|
code = OperationalError.BAD_PARAMETER;
|
||||||
|
} else {
|
||||||
|
code = OperationalError.INTERNAL_ERROR;
|
||||||
|
logUnrecognised(method, status);
|
||||||
}
|
}
|
||||||
super.close(statusMapper.statusFor(code), statusMapper.trailersFor(code));
|
super.close(statusMapper.statusFor(code), statusMapper.trailersFor(code));
|
||||||
}
|
}
|
||||||
@@ -123,11 +143,26 @@ public class GrpcExceptionHandlingInterceptor implements ServerInterceptor {
|
|||||||
call.close(Status.fromThrowable(exception).withCause(exception), new Metadata());
|
call.close(Status.fromThrowable(exception).withCause(exception), new Metadata());
|
||||||
}
|
}
|
||||||
|
|
||||||
private static ApiErrorCode errorCodeOf(Throwable throwable) {
|
private static void logUnrecognised(String method, Status status) {
|
||||||
|
if (status.getCode() == Status.Code.CANCELLED) {
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
// The cause, when there is one, is the last argument and so the logged exception; the raw
|
||||||
|
// description is never logged.
|
||||||
|
log.error(
|
||||||
|
"unhandled failure on {} answered as {} (status={})",
|
||||||
|
method,
|
||||||
|
OperationalError.INTERNAL_ERROR.code(),
|
||||||
|
status.getCode(),
|
||||||
|
status.getCause());
|
||||||
|
}
|
||||||
|
|
||||||
|
/** The first {@link ApiErrorCarrier} in the cause chain, or {@code null}. */
|
||||||
|
private static Throwable carrierOf(Throwable throwable) {
|
||||||
Throwable current = throwable;
|
Throwable current = throwable;
|
||||||
while (current != null) {
|
while (current != null) {
|
||||||
if (current instanceof ApiErrorCarrier carrier) {
|
if (current instanceof ApiErrorCarrier) {
|
||||||
return carrier.errorCode();
|
return current;
|
||||||
}
|
}
|
||||||
if (current.getCause() == current) {
|
if (current.getCause() == current) {
|
||||||
break;
|
break;
|
||||||
|
|||||||
+165
-2
@@ -2,6 +2,10 @@ package dev.caskeleton.adapter.inbound.grpc;
|
|||||||
|
|
||||||
import static org.assertj.core.api.Assertions.assertThat;
|
import static org.assertj.core.api.Assertions.assertThat;
|
||||||
|
|
||||||
|
import ch.qos.logback.classic.Level;
|
||||||
|
import ch.qos.logback.classic.Logger;
|
||||||
|
import ch.qos.logback.classic.spi.ILoggingEvent;
|
||||||
|
import ch.qos.logback.core.read.ListAppender;
|
||||||
import dev.caskeleton.shared.error.ApiErrorCarrier;
|
import dev.caskeleton.shared.error.ApiErrorCarrier;
|
||||||
import dev.caskeleton.shared.error.ApiErrorCode;
|
import dev.caskeleton.shared.error.ApiErrorCode;
|
||||||
import dev.caskeleton.shared.error.ClientErrorMessages;
|
import dev.caskeleton.shared.error.ClientErrorMessages;
|
||||||
@@ -12,8 +16,11 @@ import io.grpc.MethodDescriptor;
|
|||||||
import io.grpc.ServerCall;
|
import io.grpc.ServerCall;
|
||||||
import io.grpc.ServerCallHandler;
|
import io.grpc.ServerCallHandler;
|
||||||
import io.grpc.Status;
|
import io.grpc.Status;
|
||||||
|
import java.sql.SQLException;
|
||||||
|
import java.util.List;
|
||||||
import java.util.concurrent.atomic.AtomicBoolean;
|
import java.util.concurrent.atomic.AtomicBoolean;
|
||||||
import org.junit.jupiter.api.Test;
|
import org.junit.jupiter.api.Test;
|
||||||
|
import org.slf4j.LoggerFactory;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Verifies the interceptor translates a synchronous handler exception into a mapped {@code
|
* Verifies the interceptor translates a synchronous handler exception into a mapped {@code
|
||||||
@@ -116,6 +123,138 @@ class GrpcExceptionHandlingInterceptorTest {
|
|||||||
assertThat(cancelled).isTrue();
|
assertThat(cancelled).isTrue();
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aServerSideCarrierIsLoggedAtErrorWithTheMethodAndTheFailureThatNamesTheScopeDigest() {
|
||||||
|
// given
|
||||||
|
CarrierException recoveryRequired =
|
||||||
|
new CarrierException(
|
||||||
|
OperationalError.IDEMPOTENCY_RECOVERY_REQUIRED,
|
||||||
|
"claim requires reconciliation: CHARGE_CARD::v1::3f9a");
|
||||||
|
|
||||||
|
// when
|
||||||
|
List<ILoggingEvent> logged = loggedWhile(() -> closeAfterThrowing(recoveryRequired));
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(logged)
|
||||||
|
.singleElement()
|
||||||
|
.extracting(
|
||||||
|
ILoggingEvent::getLevel,
|
||||||
|
ILoggingEvent::getFormattedMessage,
|
||||||
|
event -> event.getThrowableProxy().getMessage())
|
||||||
|
.containsExactly(
|
||||||
|
Level.ERROR,
|
||||||
|
"failure classified as IDEMPOTENCY_RECOVERY_REQUIRED (category=DATA_INTEGRITY,"
|
||||||
|
+ " retryable=false) (method=test.Fixture/Call)",
|
||||||
|
"claim requires reconciliation: CHARGE_CARD::v1::3f9a");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aPersistenceFailureIsLoggedByItsClassificationWithoutItsCause() {
|
||||||
|
// given
|
||||||
|
PersistenceFailureException failure =
|
||||||
|
new PersistenceFailureException(
|
||||||
|
OperationalError.DB_UNAVAILABLE,
|
||||||
|
"08006",
|
||||||
|
new SQLException("jdbc:postgresql://db.internal/customer?password=secret", "08006"));
|
||||||
|
|
||||||
|
// when
|
||||||
|
List<ILoggingEvent> logged = loggedWhile(() -> closeAfterThrowing(failure));
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(logged)
|
||||||
|
.singleElement()
|
||||||
|
.extracting(ILoggingEvent::getFormattedMessage, ILoggingEvent::getThrowableProxy)
|
||||||
|
.containsExactly(
|
||||||
|
"persistence failure classified as DB_UNAVAILABLE (category=TRANSIENT_DEPENDENCY,"
|
||||||
|
+ " retryable=true) (method=test.Fixture/Call)",
|
||||||
|
null);
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aClientSideCarrierIsNotLogged() {
|
||||||
|
// when
|
||||||
|
List<ILoggingEvent> logged =
|
||||||
|
loggedWhile(() -> closeAfterThrowing(new CarrierException(OperationalError.BAD_PARAMETER)));
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(logged).isEmpty();
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void anUnrecognisedFailureIsLoggedAtErrorWithTheFailure() {
|
||||||
|
// when
|
||||||
|
List<ILoggingEvent> logged =
|
||||||
|
loggedWhile(() -> closeAfterThrowing(new IllegalStateException("boom")));
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(logged)
|
||||||
|
.singleElement()
|
||||||
|
.extracting(
|
||||||
|
ILoggingEvent::getLevel,
|
||||||
|
ILoggingEvent::getFormattedMessage,
|
||||||
|
event -> event.getThrowableProxy().getClassName())
|
||||||
|
.containsExactly(
|
||||||
|
Level.ERROR,
|
||||||
|
"unhandled failure on test.Fixture/Call answered as INTERNAL_ERROR (status=UNKNOWN)",
|
||||||
|
IllegalStateException.class.getName());
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aRawStatusWithoutACauseIsLoggedByItsCodeAlone() {
|
||||||
|
// given
|
||||||
|
CapturingServerCall call = new CapturingServerCall();
|
||||||
|
ServerCallHandler<String, String> handler =
|
||||||
|
(serverCall, headers) -> {
|
||||||
|
serverCall.close(
|
||||||
|
Status.NOT_FOUND.withDescription("row 42 of customer alice"), new Metadata());
|
||||||
|
return new ServerCall.Listener<>() {};
|
||||||
|
};
|
||||||
|
|
||||||
|
// when
|
||||||
|
List<ILoggingEvent> logged =
|
||||||
|
loggedWhile(() -> interceptor.interceptCall(call, new Metadata(), handler));
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(logged)
|
||||||
|
.singleElement()
|
||||||
|
.extracting(ILoggingEvent::getFormattedMessage, ILoggingEvent::getThrowableProxy)
|
||||||
|
.containsExactly(
|
||||||
|
"unhandled failure on test.Fixture/Call answered as INTERNAL_ERROR (status=NOT_FOUND)",
|
||||||
|
null);
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aCallTheClientCancelledIsNotLogged() {
|
||||||
|
// given
|
||||||
|
CapturingServerCall call = new CapturingServerCall();
|
||||||
|
ServerCallHandler<String, String> handler =
|
||||||
|
(serverCall, headers) -> {
|
||||||
|
serverCall.close(Status.CANCELLED.withDescription("client cancelled"), new Metadata());
|
||||||
|
return new ServerCall.Listener<>() {};
|
||||||
|
};
|
||||||
|
|
||||||
|
// when
|
||||||
|
List<ILoggingEvent> logged =
|
||||||
|
loggedWhile(() -> interceptor.interceptCall(call, new Metadata(), handler));
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(logged).isEmpty();
|
||||||
|
}
|
||||||
|
|
||||||
|
private static List<ILoggingEvent> loggedWhile(Runnable action) {
|
||||||
|
Logger logger = (Logger) LoggerFactory.getLogger(GrpcExceptionHandlingInterceptor.class);
|
||||||
|
ListAppender<ILoggingEvent> appender = new ListAppender<>();
|
||||||
|
appender.start();
|
||||||
|
logger.addAppender(appender);
|
||||||
|
try {
|
||||||
|
action.run();
|
||||||
|
} finally {
|
||||||
|
logger.detachAppender(appender);
|
||||||
|
appender.stop();
|
||||||
|
}
|
||||||
|
return appender.list;
|
||||||
|
}
|
||||||
|
|
||||||
private CapturingServerCall closeAfterThrowing(RuntimeException thrown) {
|
private CapturingServerCall closeAfterThrowing(RuntimeException thrown) {
|
||||||
CapturingServerCall call = new CapturingServerCall();
|
CapturingServerCall call = new CapturingServerCall();
|
||||||
ServerCallHandler<String, String> handler =
|
ServerCallHandler<String, String> handler =
|
||||||
@@ -139,7 +278,11 @@ class GrpcExceptionHandlingInterceptorTest {
|
|||||||
private final ApiErrorCode errorCode;
|
private final ApiErrorCode errorCode;
|
||||||
|
|
||||||
CarrierException(ApiErrorCode errorCode) {
|
CarrierException(ApiErrorCode errorCode) {
|
||||||
super(errorCode.code());
|
this(errorCode, errorCode.code());
|
||||||
|
}
|
||||||
|
|
||||||
|
CarrierException(ApiErrorCode errorCode, String message) {
|
||||||
|
super(message);
|
||||||
this.errorCode = errorCode;
|
this.errorCode = errorCode;
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -151,6 +294,26 @@ class GrpcExceptionHandlingInterceptorTest {
|
|||||||
|
|
||||||
/** Minimal {@link ServerCall} that records the {@code close(status, trailers)} arguments. */
|
/** Minimal {@link ServerCall} that records the {@code close(status, trailers)} arguments. */
|
||||||
private static final class CapturingServerCall extends ServerCall<String, String> {
|
private static final class CapturingServerCall extends ServerCall<String, String> {
|
||||||
|
private static final MethodDescriptor.Marshaller<String> NO_WIRE =
|
||||||
|
new MethodDescriptor.Marshaller<>() {
|
||||||
|
@Override
|
||||||
|
public java.io.InputStream stream(String value) {
|
||||||
|
throw new UnsupportedOperationException("no wire in this test");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public String parse(java.io.InputStream stream) {
|
||||||
|
throw new UnsupportedOperationException("no wire in this test");
|
||||||
|
}
|
||||||
|
};
|
||||||
|
private static final MethodDescriptor<String, String> METHOD =
|
||||||
|
MethodDescriptor.<String, String>newBuilder()
|
||||||
|
.setType(MethodDescriptor.MethodType.UNARY)
|
||||||
|
.setFullMethodName("test.Fixture/Call")
|
||||||
|
.setRequestMarshaller(NO_WIRE)
|
||||||
|
.setResponseMarshaller(NO_WIRE)
|
||||||
|
.build();
|
||||||
|
|
||||||
private Status status;
|
private Status status;
|
||||||
private Metadata trailers;
|
private Metadata trailers;
|
||||||
|
|
||||||
@@ -176,7 +339,7 @@ class GrpcExceptionHandlingInterceptorTest {
|
|||||||
|
|
||||||
@Override
|
@Override
|
||||||
public MethodDescriptor<String, String> getMethodDescriptor() {
|
public MethodDescriptor<String, String> getMethodDescriptor() {
|
||||||
return null;
|
return METHOD;
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -14,7 +14,9 @@
|
|||||||
`@SystemInvoked` use case itself; the use case is never a bean, and no user transport calls the
|
`@SystemInvoked` use case itself; the use case is never a bean, and no user transport calls the
|
||||||
handler (manual 09 「소비」 step 4, manual 07 「시스템이 부르는 쓰기」,
|
handler (manual 09 「소비」 step 4, manual 07 「시스템이 부르는 쓰기」,
|
||||||
`ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`, `SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`,
|
`ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`, `SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`,
|
||||||
`USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`).
|
`USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`). The handler implements only project types
|
||||||
|
(`MessageHandler<T>`), never `Runnable` or another type outside the project
|
||||||
|
(`SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`).
|
||||||
- Tests: focused auto-configuration and inbox behavior tests; `./gradlew :adapter:inbound:messaging:check`.
|
- Tests: focused auto-configuration and inbox behavior tests; `./gradlew :adapter:inbound:messaging:check`.
|
||||||
The real Kafka + PostgreSQL redelivery lane is `messagingInboxRedeliveryIntegrationTest`
|
The real Kafka + PostgreSQL redelivery lane is `messagingInboxRedeliveryIntegrationTest`
|
||||||
(`:integrationCheck`).
|
(`:integrationCheck`).
|
||||||
|
|||||||
@@ -105,7 +105,9 @@ PostgreSQL에서 같은 모양은 `InboxRedeliveryIntegrationTest`의 `Projectio
|
|||||||
요청이 들어오는 전송(web·GraphQL·gRPC·WebSocket)만 그 use case에 닿지 못하고, 표시는 ArchUnit이 검사한다
|
요청이 들어오는 전송(web·GraphQL·gRPC·WebSocket)만 그 use case에 닿지 못하고, 표시는 ArchUnit이 검사한다
|
||||||
(`SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`: 표시한 클래스와 그 안에 중첩된 클래스는 messaging·
|
(`SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`: 표시한 클래스와 그 안에 중첩된 클래스는 messaging·
|
||||||
scheduler inbound 패키지에만, 사용자 전송 타입에 의존하지 않음). 사용자 전송이 handler bean을 주입받아
|
scheduler inbound 패키지에만, 사용자 전송 타입에 의존하지 않음). 사용자 전송이 handler bean을 주입받아
|
||||||
부르는 길은 `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`가 막는다(RR3-01-01). 기동 가드는 바꾸지 않는다:
|
부르는 길은 `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`가 막는다(RR3-01-01). handler가 구현하는
|
||||||
|
`MessageHandler<T>` 같은 프로젝트 인터페이스로 주입받아도 같다. handler는 프로젝트 밖 타입(`Runnable` 등)을
|
||||||
|
구현하지 않는다(`SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES`, RR4-01-01). 기동 가드는 바꾸지 않는다:
|
||||||
`@SystemInvoked` bean은 예외 없이 실패다. 규칙 전체는 매뉴얼 07장 「시스템이 부르는 쓰기」.
|
`@SystemInvoked` bean은 예외 없이 실패다. 규칙 전체는 매뉴얼 07장 「시스템이 부르는 쓰기」.
|
||||||
- 버림: use case를 bean으로 두고 가드에 "handler만 주입받으면 허용" 예외 — 누가 주입받는지는 기동 때
|
- 버림: use case를 bean으로 두고 가드에 "handler만 주입받으면 허용" 예외 — 누가 주입받는지는 기동 때
|
||||||
확정되지 않는다(`ObjectProvider`, `getBean`, 나중에 추가된 bean). 예외 조건이 곧 우회 경로가 된다.
|
확정되지 않는다(`ObjectProvider`, `getBean`, 나중에 추가된 bean). 예외 조건이 곧 우회 경로가 된다.
|
||||||
|
|||||||
+17
-30
@@ -7,9 +7,9 @@ import dev.caskeleton.adapter.inbound.web.observability.RetryAfterAdvisor;
|
|||||||
import dev.caskeleton.adapter.inbound.web.pagination.PageValidationException;
|
import dev.caskeleton.adapter.inbound.web.pagination.PageValidationException;
|
||||||
import dev.caskeleton.shared.error.ApiErrorCarrier;
|
import dev.caskeleton.shared.error.ApiErrorCarrier;
|
||||||
import dev.caskeleton.shared.error.ApiErrorCode;
|
import dev.caskeleton.shared.error.ApiErrorCode;
|
||||||
import dev.caskeleton.shared.error.DependencyFailureException;
|
|
||||||
import dev.caskeleton.shared.error.OperationalError;
|
import dev.caskeleton.shared.error.OperationalError;
|
||||||
import dev.caskeleton.shared.error.PersistenceFailureException;
|
import dev.caskeleton.shared.error.PersistenceFailureException;
|
||||||
|
import dev.caskeleton.shared.error.ServerFailureLog;
|
||||||
import dev.caskeleton.shared.response.Envelope;
|
import dev.caskeleton.shared.response.Envelope;
|
||||||
import dev.caskeleton.shared.tracing.SpanErrorRecorder;
|
import dev.caskeleton.shared.tracing.SpanErrorRecorder;
|
||||||
import jakarta.servlet.http.HttpServletResponse;
|
import jakarta.servlet.http.HttpServletResponse;
|
||||||
@@ -159,40 +159,27 @@ public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {
|
|||||||
* through its own {@link ApiErrorCode}. One branch, so the web adapter answers a carrier exactly
|
* through its own {@link ApiErrorCode}. One branch, so the web adapter answers a carrier exactly
|
||||||
* as the GraphQL, gRPC and STOMP adapters do.
|
* as the GraphQL, gRPC and STOMP adapters do.
|
||||||
*
|
*
|
||||||
* <p>A persistence carrier's cause can hold SQL values, constraints, credentials and endpoints,
|
* <p>What reaches the log is {@link ServerFailureLog}'s line, the one the GraphQL and gRPC
|
||||||
* so its log line and span receive only the stable classification. A server-side (5xx) carrier is
|
* adapters write too: a persistence carrier by its classification only (its cause can hold SQL
|
||||||
* logged with its cause; a client-side one is not logged, because it is an answer, not an
|
* values, constraints, credentials and endpoints), a dependency carrier and any other server-side
|
||||||
* incident. A retryable code with a registered delay also carries {@code Retry-After}.
|
* (5xx) carrier with the exception, a client-side carrier not at all — it is an answer, not an
|
||||||
|
* incident. The span gets the same failure, a persistence one again reduced to its
|
||||||
|
* classification. A retryable code with a registered delay also carries {@code Retry-After}.
|
||||||
*
|
*
|
||||||
* @param failure a throwable that implements {@link ApiErrorCarrier}
|
* @param failure a throwable that implements {@link ApiErrorCarrier}
|
||||||
*/
|
*/
|
||||||
public ResponseEntity<Envelope<Void>> handleCarrier(Exception failure) {
|
public ResponseEntity<Envelope<Void>> handleCarrier(Exception failure) {
|
||||||
ApiErrorCode code = ((ApiErrorCarrier) failure).errorCode();
|
ApiErrorCode code = ((ApiErrorCarrier) failure).errorCode();
|
||||||
if (failure instanceof PersistenceFailureException) {
|
ServerFailureLog.of(failure, code)
|
||||||
log.error(
|
.ifPresent(
|
||||||
"persistence failure classified as {} (category={}, retryable={})",
|
line -> {
|
||||||
code.code(),
|
log.error(line.format(""), line.arguments());
|
||||||
code.category(),
|
spanErrorRecorder.recordException(
|
||||||
code.retryable());
|
failure instanceof PersistenceFailureException
|
||||||
spanErrorRecorder.recordException(sanitizedPersistenceFailure(code), code.code());
|
? sanitizedPersistenceFailure(code)
|
||||||
} else if (failure instanceof DependencyFailureException dependency) {
|
: failure,
|
||||||
log.error(
|
code.code());
|
||||||
"dependency failure classified as {} (category={}, retryable={}, dependency={})",
|
});
|
||||||
code.code(),
|
|
||||||
code.category(),
|
|
||||||
code.retryable(),
|
|
||||||
dependency.dependencyName(),
|
|
||||||
failure);
|
|
||||||
spanErrorRecorder.recordException(failure, code.code());
|
|
||||||
} else if (code.httpStatus() >= 500) {
|
|
||||||
log.error(
|
|
||||||
"failure classified as {} (category={}, retryable={})",
|
|
||||||
code.code(),
|
|
||||||
code.category(),
|
|
||||||
code.retryable(),
|
|
||||||
failure);
|
|
||||||
spanErrorRecorder.recordException(failure, code.code());
|
|
||||||
}
|
|
||||||
ResponseEntity.BodyBuilder builder = ResponseEntity.status(code.httpStatus());
|
ResponseEntity.BodyBuilder builder = ResponseEntity.status(code.httpStatus());
|
||||||
RetryAfterAdvisor.retryAfterSeconds(code)
|
RetryAfterAdvisor.retryAfterSeconds(code)
|
||||||
.ifPresent(seconds -> builder.header(ApiHeaders.RETRY_AFTER, String.valueOf(seconds)));
|
.ifPresent(seconds -> builder.header(ApiHeaders.RETRY_AFTER, String.valueOf(seconds)));
|
||||||
|
|||||||
@@ -30,9 +30,14 @@
|
|||||||
세션 종료 콜백뿐이고, 통과한 SockJS handshake가 세션이 되지 않을 수도 있어 두 곳에서 세면 자리가
|
세션 종료 콜백뿐이고, 통과한 SockJS handshake가 세션이 되지 않을 수도 있어 두 곳에서 세면 자리가
|
||||||
샌다. 1008이 아니라 1013인 이유: 거부 사유가 클라이언트가 아니라 지금 이 노드의 부하라서, 일반
|
샌다. 1008이 아니라 1013인 이유: 거부 사유가 클라이언트가 아니라 지금 이 노드의 부하라서, 일반
|
||||||
클라이언트가 물러났다가(가능하면 다른 노드로) 다시 붙게 한다.
|
클라이언트가 물러났다가(가능하면 다른 노드로) 다시 붙게 한다.
|
||||||
- 처리 실패는 모두 빈 본문의 ERROR 프레임이 되고 `message` 헤더는 고정값
|
- handler 메서드가 돌기 전의 처리 실패(inbound interceptor의 거부 등)는 빈 본문의 ERROR 프레임이 되고
|
||||||
`WEBSOCKET_REQUEST_REJECTED`다. `error-code` 헤더는 원인 사슬에 `ApiErrorCarrier`가 있으면 그
|
`message` 헤더는 고정값 `WEBSOCKET_REQUEST_REJECTED`다. `error-code` 헤더는 원인 사슬에
|
||||||
코드, `IllegalArgumentException`이면 `BAD_PARAMETER`, 나머지는 `WEBSOCKET_REQUEST_REJECTED`다.
|
`ApiErrorCarrier`가 있으면 그 코드, `IllegalArgumentException`이면 `BAD_PARAMETER`, 나머지는
|
||||||
|
`WEBSOCKET_REQUEST_REJECTED`다.
|
||||||
|
- `@MessageMapping` 메서드의 실패는 inbound 채널 executor에서 끝나서 프레임이 나가지 않는다. 서버 로그는
|
||||||
|
`StompHandlerFailureLog`가 web·GraphQL·gRPC와 같은 줄로 남긴다(`ServerFailureLog`): persistence 실패는
|
||||||
|
분류만, 5xx carrier는 예외와 함께, 4xx carrier는 남기지 않는다. 그 밖의 예외는 예외와 함께 ERROR.
|
||||||
|
전에는 Spring이 예외 전체(persistence 실패의 SQL 원인 포함)를 ERROR로 남겼다.
|
||||||
- `LiveEventProjector<T>` bean이 정확히 하나 있는 `@DomainEvent` 타입만 broadcast한다. 도메인
|
- `LiveEventProjector<T>` bean이 정확히 하나 있는 `@DomainEvent` 타입만 broadcast한다. 도메인
|
||||||
객체를 그대로 직렬화하지 않고, projector가 만든 bounded `Map<String, String>`만 보낸다.
|
객체를 그대로 직렬화하지 않고, projector가 만든 bounded `Map<String, String>`만 보낸다.
|
||||||
|
|
||||||
|
|||||||
+7
-2
@@ -13,10 +13,15 @@ import org.springframework.web.socket.messaging.StompSubProtocolErrorHandler;
|
|||||||
*
|
*
|
||||||
* <p>The frame's {@code message} header is fixed, so no exception text can reach the client. Its
|
* <p>The frame's {@code message} header is fixed, so no exception text can reach the client. Its
|
||||||
* {@code error-code} header is the stable code every other transport would send for the same
|
* {@code error-code} header is the stable code every other transport would send for the same
|
||||||
* failure: an {@link ApiErrorCarrier} anywhere in the cause chain (the broker wraps use-case
|
* failure: an {@link ApiErrorCarrier} anywhere in the cause chain (Spring wraps a failure raised
|
||||||
* failures in a {@code MessagingException}) reports its own code, an {@link
|
* while the frame is processed in a {@code MessagingException}) reports its own code, an {@link
|
||||||
* IllegalArgumentException} reports {@code BAD_PARAMETER}, and everything else stays {@link
|
* IllegalArgumentException} reports {@code BAD_PARAMETER}, and everything else stays {@link
|
||||||
* #SAFE_ERROR_CODE}.
|
* #SAFE_ERROR_CODE}.
|
||||||
|
*
|
||||||
|
* <p>What reaches it is what fails before a handler method runs — an inbound interceptor's refusal,
|
||||||
|
* on the thread that received the frame. A {@code @MessageMapping} method runs on the inbound
|
||||||
|
* channel's executor, and its failure stays there: {@link StompHandlerFailureLog} logs it and no
|
||||||
|
* frame is sent.
|
||||||
*/
|
*/
|
||||||
final class SafeStompSubProtocolErrorHandler extends StompSubProtocolErrorHandler {
|
final class SafeStompSubProtocolErrorHandler extends StompSubProtocolErrorHandler {
|
||||||
|
|
||||||
|
|||||||
+39
@@ -0,0 +1,39 @@
|
|||||||
|
package dev.caskeleton.adapter.inbound.websocket.stomp;
|
||||||
|
|
||||||
|
import dev.caskeleton.shared.error.ApiErrorCarrier;
|
||||||
|
import dev.caskeleton.shared.error.ServerFailureLog;
|
||||||
|
import org.slf4j.Logger;
|
||||||
|
import org.slf4j.LoggerFactory;
|
||||||
|
import org.springframework.messaging.handler.annotation.MessageExceptionHandler;
|
||||||
|
import org.springframework.web.bind.annotation.ControllerAdvice;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Writes the server-log line for a {@code @MessageMapping} method that throws, the way the web,
|
||||||
|
* GraphQL and gRPC adapters do.
|
||||||
|
*
|
||||||
|
* <p>Such a failure is handled on the inbound channel's executor, so it never reaches {@link
|
||||||
|
* SafeStompSubProtocolErrorHandler}, which only sees what fails before a handler runs (an
|
||||||
|
* interceptor's refusal). Without a handler for it, Spring's method handler logs the whole
|
||||||
|
* exception and stops: a persistence failure's SQL cause — values, constraint names, credentials —
|
||||||
|
* went to the log, and a client-side refusal was logged as an error. With this advice a carrier
|
||||||
|
* gets {@link ServerFailureLog}'s line (a persistence failure its classification only, a
|
||||||
|
* client-side code nothing), and anything else is logged with its exception, as before. The request
|
||||||
|
* id is on MDC ({@link WebSocketCorrelationInterceptor}). The client is answered as before: a
|
||||||
|
* handler method that throws sends no frame. A feature's own {@code @MessageExceptionHandler} still
|
||||||
|
* takes precedence over this one.
|
||||||
|
*/
|
||||||
|
@ControllerAdvice
|
||||||
|
class StompHandlerFailureLog {
|
||||||
|
|
||||||
|
private static final Logger log = LoggerFactory.getLogger(StompHandlerFailureLog.class);
|
||||||
|
|
||||||
|
@MessageExceptionHandler
|
||||||
|
void logFailure(Exception failure) {
|
||||||
|
if (failure instanceof ApiErrorCarrier carrier) {
|
||||||
|
ServerFailureLog.of(failure, carrier.errorCode())
|
||||||
|
.ifPresent(line -> log.error(line.format(""), line.arguments()));
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
log.error("unhandled failure in a STOMP message handler", failure);
|
||||||
|
}
|
||||||
|
}
|
||||||
+9
@@ -134,6 +134,15 @@ public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {
|
|||||||
return connectionLimit;
|
return connectionLimit;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Logs a {@code @MessageMapping} method's failure with the line the other transports write: a
|
||||||
|
* persistence failure by its classification only, a client-side code not at all.
|
||||||
|
*/
|
||||||
|
@Bean
|
||||||
|
StompHandlerFailureLog stompHandlerFailureLog() {
|
||||||
|
return new StompHandlerFailureLog();
|
||||||
|
}
|
||||||
|
|
||||||
@Bean
|
@Bean
|
||||||
LiveEventStompBroadcaster liveEventStompBroadcaster(
|
LiveEventStompBroadcaster liveEventStompBroadcaster(
|
||||||
SimpMessagingTemplate messaging,
|
SimpMessagingTemplate messaging,
|
||||||
|
|||||||
+1
-1
@@ -32,7 +32,7 @@ class SafeStompSubProtocolErrorHandlerTest {
|
|||||||
|
|
||||||
@Test
|
@Test
|
||||||
void aWrappedCarrierFailureReportsItsOwnCode() {
|
void aWrappedCarrierFailureReportsItsOwnCode() {
|
||||||
// given: the broker wraps a use-case failure before it reaches the error handler
|
// given: Spring wraps a failure raised while the frame was processed (an interceptor's)
|
||||||
Throwable failure =
|
Throwable failure =
|
||||||
new MessagingException(
|
new MessagingException(
|
||||||
"SECRET_SENTINEL", new MappingException("SECRET_SENTINEL mapping detail"));
|
"SECRET_SENTINEL", new MappingException("SECRET_SENTINEL mapping detail"));
|
||||||
|
|||||||
+185
@@ -0,0 +1,185 @@
|
|||||||
|
package dev.caskeleton.adapter.inbound.websocket.stomp;
|
||||||
|
|
||||||
|
import static org.assertj.core.api.Assertions.assertThat;
|
||||||
|
|
||||||
|
import ch.qos.logback.classic.Level;
|
||||||
|
import ch.qos.logback.classic.Logger;
|
||||||
|
import ch.qos.logback.classic.spi.ILoggingEvent;
|
||||||
|
import ch.qos.logback.core.read.ListAppender;
|
||||||
|
import dev.caskeleton.shared.error.ApiErrorCarrier;
|
||||||
|
import dev.caskeleton.shared.error.ApiErrorCode;
|
||||||
|
import dev.caskeleton.shared.error.OperationalError;
|
||||||
|
import dev.caskeleton.shared.error.PersistenceFailureException;
|
||||||
|
import java.sql.SQLException;
|
||||||
|
import java.util.HashMap;
|
||||||
|
import java.util.List;
|
||||||
|
import org.junit.jupiter.api.Test;
|
||||||
|
import org.slf4j.LoggerFactory;
|
||||||
|
import org.springframework.context.support.StaticApplicationContext;
|
||||||
|
import org.springframework.messaging.Message;
|
||||||
|
import org.springframework.messaging.handler.annotation.MessageMapping;
|
||||||
|
import org.springframework.messaging.simp.SimpMessageHeaderAccessor;
|
||||||
|
import org.springframework.messaging.simp.SimpMessageType;
|
||||||
|
import org.springframework.messaging.simp.SimpMessagingTemplate;
|
||||||
|
import org.springframework.messaging.support.ExecutorSubscribableChannel;
|
||||||
|
import org.springframework.messaging.support.MessageBuilder;
|
||||||
|
import org.springframework.stereotype.Controller;
|
||||||
|
import org.springframework.web.socket.messaging.WebSocketAnnotationMethodMessageHandler;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* A {@code @MessageMapping} method that throws is handled on the inbound channel's executor, so the
|
||||||
|
* failure never reaches {@link SafeStompSubProtocolErrorHandler}: Spring's method handler logs it
|
||||||
|
* and stops. Without an exception handler that line is the whole exception, a persistence failure's
|
||||||
|
* SQL cause included. Driven through Spring's real STOMP method handler, so the advice is proven to
|
||||||
|
* be the one the handler picks.
|
||||||
|
*/
|
||||||
|
class StompHandlerFailureLogTest {
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aServerSideCarrierFromAMessageMappingIsLoggedAtErrorWithTheFailure() {
|
||||||
|
// when
|
||||||
|
List<ILoggingEvent> logged = loggedWhileHandling("/app/recovery-required");
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(logged)
|
||||||
|
.singleElement()
|
||||||
|
.extracting(
|
||||||
|
ILoggingEvent::getLevel,
|
||||||
|
ILoggingEvent::getFormattedMessage,
|
||||||
|
event -> event.getThrowableProxy().getMessage())
|
||||||
|
.containsExactly(
|
||||||
|
Level.ERROR,
|
||||||
|
"failure classified as IDEMPOTENCY_RECOVERY_REQUIRED (category=DATA_INTEGRITY,"
|
||||||
|
+ " retryable=false)",
|
||||||
|
"claim requires reconciliation: CHARGE_CARD::v1::3f9a");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aPersistenceFailureFromAMessageMappingIsLoggedByItsClassificationWithoutItsCause() {
|
||||||
|
// when
|
||||||
|
List<ILoggingEvent> logged = loggedWhileHandling("/app/persistence");
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(logged)
|
||||||
|
.singleElement()
|
||||||
|
.extracting(ILoggingEvent::getFormattedMessage, ILoggingEvent::getThrowableProxy)
|
||||||
|
.containsExactly(
|
||||||
|
"persistence failure classified as DB_UNAVAILABLE (category=TRANSIENT_DEPENDENCY,"
|
||||||
|
+ " retryable=true)",
|
||||||
|
null);
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aClientSideCarrierFromAMessageMappingIsNotLogged() {
|
||||||
|
// when
|
||||||
|
List<ILoggingEvent> logged = loggedWhileHandling("/app/bad-parameter");
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(logged).isEmpty();
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void anUnrecognisedFailureFromAMessageMappingIsLoggedAtErrorWithTheFailure() {
|
||||||
|
// when
|
||||||
|
List<ILoggingEvent> logged = loggedWhileHandling("/app/unrecognised");
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(logged)
|
||||||
|
.singleElement()
|
||||||
|
.extracting(
|
||||||
|
ILoggingEvent::getLevel,
|
||||||
|
ILoggingEvent::getFormattedMessage,
|
||||||
|
event -> event.getThrowableProxy().getClassName())
|
||||||
|
.containsExactly(
|
||||||
|
Level.ERROR,
|
||||||
|
"unhandled failure in a STOMP message handler",
|
||||||
|
IllegalStateException.class.getName());
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Every ERROR or WARN line written anywhere while one message to {@code destination} is handled.
|
||||||
|
*/
|
||||||
|
private static List<ILoggingEvent> loggedWhileHandling(String destination) {
|
||||||
|
StaticApplicationContext context = new StaticApplicationContext();
|
||||||
|
context.registerSingleton("failingController", FailingController.class);
|
||||||
|
context.registerSingleton("stompHandlerFailureLog", StompHandlerFailureLog.class);
|
||||||
|
context.refresh();
|
||||||
|
// The handler @EnableWebSocketMessageBroker wires; it is the one that reads @ControllerAdvice.
|
||||||
|
WebSocketAnnotationMethodMessageHandler handler =
|
||||||
|
new WebSocketAnnotationMethodMessageHandler(
|
||||||
|
new ExecutorSubscribableChannel(),
|
||||||
|
new ExecutorSubscribableChannel(),
|
||||||
|
new SimpMessagingTemplate(new ExecutorSubscribableChannel()));
|
||||||
|
handler.setDestinationPrefixes(List.of("/app"));
|
||||||
|
handler.setApplicationContext(context);
|
||||||
|
handler.afterPropertiesSet();
|
||||||
|
Message<byte[]> message =
|
||||||
|
MessageBuilder.withPayload(new byte[0])
|
||||||
|
.setHeader(SimpMessageHeaderAccessor.MESSAGE_TYPE_HEADER, SimpMessageType.MESSAGE)
|
||||||
|
.setHeader(SimpMessageHeaderAccessor.DESTINATION_HEADER, destination)
|
||||||
|
.setHeader(SimpMessageHeaderAccessor.SESSION_ID_HEADER, "session-1")
|
||||||
|
.setHeader(SimpMessageHeaderAccessor.SESSION_ATTRIBUTES, new HashMap<String, Object>())
|
||||||
|
.build();
|
||||||
|
|
||||||
|
Logger root = (Logger) LoggerFactory.getLogger(org.slf4j.Logger.ROOT_LOGGER_NAME);
|
||||||
|
ListAppender<ILoggingEvent> appender = new ListAppender<>();
|
||||||
|
appender.start();
|
||||||
|
root.addAppender(appender);
|
||||||
|
try {
|
||||||
|
handler.handleMessage(message);
|
||||||
|
} finally {
|
||||||
|
root.detachAppender(appender);
|
||||||
|
appender.stop();
|
||||||
|
context.close();
|
||||||
|
}
|
||||||
|
return appender.list.stream()
|
||||||
|
.filter(event -> event.getLevel().isGreaterOrEqual(Level.WARN))
|
||||||
|
.toList();
|
||||||
|
}
|
||||||
|
|
||||||
|
/** A feature's STOMP controller whose use case fails in each of the ways that matter. */
|
||||||
|
@Controller
|
||||||
|
static class FailingController {
|
||||||
|
|
||||||
|
@MessageMapping("/recovery-required")
|
||||||
|
void recoveryRequired() {
|
||||||
|
throw new CarrierException(
|
||||||
|
OperationalError.IDEMPOTENCY_RECOVERY_REQUIRED,
|
||||||
|
"claim requires reconciliation: CHARGE_CARD::v1::3f9a");
|
||||||
|
}
|
||||||
|
|
||||||
|
@MessageMapping("/persistence")
|
||||||
|
void persistence() {
|
||||||
|
throw new PersistenceFailureException(
|
||||||
|
OperationalError.DB_UNAVAILABLE,
|
||||||
|
"08006",
|
||||||
|
new SQLException("jdbc:postgresql://db.internal/customer?password=secret", "08006"));
|
||||||
|
}
|
||||||
|
|
||||||
|
@MessageMapping("/bad-parameter")
|
||||||
|
void badParameter() {
|
||||||
|
throw new CarrierException(OperationalError.BAD_PARAMETER, "bad input");
|
||||||
|
}
|
||||||
|
|
||||||
|
@MessageMapping("/unrecognised")
|
||||||
|
void unrecognised() {
|
||||||
|
throw new IllegalStateException("boom");
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/** A use-case failure carrying a shared code. */
|
||||||
|
private static final class CarrierException extends RuntimeException implements ApiErrorCarrier {
|
||||||
|
private static final long serialVersionUID = 1L;
|
||||||
|
private final transient ApiErrorCode code;
|
||||||
|
|
||||||
|
CarrierException(ApiErrorCode code, String message) {
|
||||||
|
super(message);
|
||||||
|
this.code = code;
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public ApiErrorCode errorCode() {
|
||||||
|
return code;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
+5
@@ -117,6 +117,11 @@ class WebSocketAutoConfigurationTest {
|
|||||||
});
|
});
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void theStompHandlerFailureLogIsRegisteredWhenTheChannelIsOn() {
|
||||||
|
runner.run(context -> assertThat(context).hasSingleBean(StompHandlerFailureLog.class));
|
||||||
|
}
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
void switchedOffHoldsNothing() {
|
void switchedOffHoldsNothing() {
|
||||||
runner
|
runner
|
||||||
|
|||||||
@@ -288,8 +288,12 @@ retryable. A record still `EXECUTING` when its lease ran out has an unknown effe
|
|||||||
program answers `RECOVERY_REQUIRED` and leaves the record as it is, because the holder may still be
|
program answers `RECOVERY_REQUIRED` and leaves the record as it is, because the holder may still be
|
||||||
running. The holder's late completion or failure goes through the transition program as it would
|
running. The holder's late completion or failure goes through the transition program as it would
|
||||||
have inside the lease, and the next claim replays or retries it; only the lease is final — `RENEW`
|
have inside the lease, and the next claim replays or retries it; only the lease is final — `RENEW`
|
||||||
refuses one that has run out, and `INSPECT` reports somebody else's expired execution as
|
refuses one that has run out with `LEASE_EXPIRED` (not `NOT_OWNER`: the holder still completes the
|
||||||
`RECOVERY_REQUIRED`. The PostgreSQL store answers the same; the shared `IdempotencyStoreContract`
|
record, re-review 2026-11-04 RR5-01-02), and `INSPECT` reports somebody else's expired execution as
|
||||||
|
`RECOVERY_REQUIRED`. The transition program reads the lease for a start only: a claim whose lease
|
||||||
|
ran out is answered `LEASE_EXPIRED` and not started, so nothing runs and the next claim takes it
|
||||||
|
over (it used to start, and every other request was then told "recovery required" for work that
|
||||||
|
had just begun; README 15). The PostgreSQL store answers the same; the shared `IdempotencyStoreContract`
|
||||||
holds both to it on a real server (re-review 2026-11-04 RR-01-11 — this store used to take the
|
holds both to it on a real server (re-review 2026-11-04 RR-01-11 — this store used to take the
|
||||||
record over and run the work a second time; owner decision 2026-11-04 — both stores then abandoned
|
record over and run the work a second time; owner decision 2026-11-04 — both stores then abandoned
|
||||||
the record, and a holder that outlived its lease lost its result).
|
the record, and a holder that outlived its lease lost its result).
|
||||||
|
|||||||
@@ -88,7 +88,10 @@ strictTestLanes {
|
|||||||
// the explicit-only topology lane alone, so no gate ever ran it (RR-04-05).
|
// the explicit-only topology lane alone, so no gate ever ran it (RR-04-05).
|
||||||
'dev.caskeleton.adapter.outbound.cache.redis.idempotency.LiveRedisIdempotencyStoreContractTest',
|
'dev.caskeleton.adapter.outbound.cache.redis.idempotency.LiveRedisIdempotencyStoreContractTest',
|
||||||
'dev.caskeleton.adapter.outbound.cache.redis.LiveRedisSemanticPortsTest',
|
'dev.caskeleton.adapter.outbound.cache.redis.LiveRedisSemanticPortsTest',
|
||||||
'dev.caskeleton.adapter.outbound.cache.redis.capability.LiveRedisSemanticScriptAclProbeTest'
|
'dev.caskeleton.adapter.outbound.cache.redis.capability.LiveRedisSemanticScriptAclProbeTest',
|
||||||
|
// The runbook's Redis repair, run as written under the lane's ACL (re-review
|
||||||
|
// 2026-11-04 RR4-03-02).
|
||||||
|
'dev.caskeleton.adapter.outbound.cache.redis.idempotency.LiveRedisIdempotencyRunbookTest'
|
||||||
rejectSkipped = true
|
rejectSkipped = true
|
||||||
systemProperty 'redis.container.acl-file', new File(redisAclDirectory, 'lane-fixture-accounts.acl').absolutePath
|
systemProperty 'redis.container.acl-file', new File(redisAclDirectory, 'lane-fixture-accounts.acl').absolutePath
|
||||||
inputDirectory redisAclDirectory
|
inputDirectory redisAclDirectory
|
||||||
@@ -96,3 +99,10 @@ strictTestLanes {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// LiveRedisIdempotencyRunbookTest reads its blocks out of the runbook an operator follows rather than
|
||||||
|
// keeping a copy, so the runbook is an input of the lane: editing a block reruns it against Redis.
|
||||||
|
tasks.named('redisContainerContractTest', Test) {
|
||||||
|
def idempotencyRunbook = new File(rootProject.projectDir.parentFile, 'docs/runbooks/idempotency-unavailable.md')
|
||||||
|
inputs.file(idempotencyRunbook).withPathSensitivity(PathSensitivity.RELATIVE).withPropertyName('idempotencyRunbook')
|
||||||
|
systemProperty 'idempotency.runbook', idempotencyRunbook.absolutePath
|
||||||
|
}
|
||||||
|
|||||||
+26
-4
@@ -108,7 +108,17 @@ public final class IdempotencyScripts {
|
|||||||
return {'IN_PROGRESS', attempt, rev, owner, '', tostring(leaseUntil - nowMillis)}
|
return {'IN_PROGRESS', attempt, rev, owner, '', tostring(leaseUntil - nowMillis)}
|
||||||
""";
|
""";
|
||||||
|
|
||||||
/** A generic owner+revision compare-and-set transition. */
|
/**
|
||||||
|
* A generic owner+revision compare-and-set transition.
|
||||||
|
*
|
||||||
|
* <p>A start ({@code CLAIMED} to {@code EXECUTING}) also needs the claim's lease to be running,
|
||||||
|
* judged by the server clock as {@link #CLAIM} judges it: a claim whose lease ran out is answered
|
||||||
|
* {@code LEASE_EXPIRED} and not started, so nothing runs and the next claim takes it over. This
|
||||||
|
* program used to start it, and every other request was then told "recovery required" for an
|
||||||
|
* execution that had just begun; the PostgreSQL store refused it (re-review 2026-11-04 README 15,
|
||||||
|
* {@code IdempotencyStoreContract}). Completion and failure read no lease: the holder's late
|
||||||
|
* result is recorded (owner decision 2026-11-04).
|
||||||
|
*/
|
||||||
private static final String TRANSITION =
|
private static final String TRANSITION =
|
||||||
"""
|
"""
|
||||||
local state = redis.call('HGET', KEYS[1], 'state')
|
local state = redis.call('HGET', KEYS[1], 'state')
|
||||||
@@ -142,6 +152,14 @@ public final class IdempotencyScripts {
|
|||||||
if state ~= ARGV[4] then
|
if state ~= ARGV[4] then
|
||||||
return {'WRONG_STATE', attempt, rev, owner, state, ''}
|
return {'WRONG_STATE', attempt, rev, owner, state, ''}
|
||||||
end
|
end
|
||||||
|
if state == 'CLAIMED' then
|
||||||
|
local t = redis.call('TIME')
|
||||||
|
local nowMillis = (tonumber(t[1]) * 1000) + math.floor(tonumber(t[2]) / 1000)
|
||||||
|
local leaseUntil = tonumber(redis.call('HGET', KEYS[1], 'leaseUntil'))
|
||||||
|
if leaseUntil ~= nil and leaseUntil <= nowMillis then
|
||||||
|
return {'LEASE_EXPIRED', attempt, rev, owner, '', ''}
|
||||||
|
end
|
||||||
|
end
|
||||||
redis.call('HSET', KEYS[1], 'state', ARGV[5], 'rev', rev + 1)
|
redis.call('HSET', KEYS[1], 'state', ARGV[5], 'rev', rev + 1)
|
||||||
if ARGV[6] ~= '' then
|
if ARGV[6] ~= '' then
|
||||||
redis.call('HSET', KEYS[1], 'resp', ARGV[6])
|
redis.call('HSET', KEYS[1], 'resp', ARGV[6])
|
||||||
@@ -179,8 +197,10 @@ public final class IdempotencyScripts {
|
|||||||
*
|
*
|
||||||
* <p>A lease that has already run out is not renewed: a resend may have been told "recovery
|
* <p>A lease that has already run out is not renewed: a resend may have been told "recovery
|
||||||
* required" since, and a lease brought back would answer the next one "in progress" for the same
|
* required" since, and a lease brought back would answer the next one "in progress" for the same
|
||||||
* unknown effect. The holder can still complete or fail the record. The PostgreSQL store refuses
|
* unknown effect. The answer is {@code LEASE_EXPIRED}, not {@code NOT_OWNER}: the holder still
|
||||||
* the same renewal ({@code IdempotencyStoreContract}, owner decision 2026-11-04).
|
* owns the record and can still complete or fail it (re-review 2026-11-04 RR5-01-02). The
|
||||||
|
* PostgreSQL store refuses the same renewal ({@code IdempotencyStoreContract}, owner decision
|
||||||
|
* 2026-11-04).
|
||||||
*/
|
*/
|
||||||
private static final String RENEW =
|
private static final String RENEW =
|
||||||
"""
|
"""
|
||||||
@@ -216,7 +236,7 @@ public final class IdempotencyScripts {
|
|||||||
local nowMillis = (tonumber(t[1]) * 1000) + math.floor(tonumber(t[2]) / 1000)
|
local nowMillis = (tonumber(t[1]) * 1000) + math.floor(tonumber(t[2]) / 1000)
|
||||||
local leaseUntil = tonumber(redis.call('HGET', KEYS[1], 'leaseUntil'))
|
local leaseUntil = tonumber(redis.call('HGET', KEYS[1], 'leaseUntil'))
|
||||||
if leaseUntil ~= nil and leaseUntil <= nowMillis then
|
if leaseUntil ~= nil and leaseUntil <= nowMillis then
|
||||||
return {'NOT_OWNER', attempt, rev, owner, '', ''}
|
return {'LEASE_EXPIRED', attempt, rev, owner, '', ''}
|
||||||
end
|
end
|
||||||
redis.call('HSET', KEYS[1],
|
redis.call('HSET', KEYS[1],
|
||||||
'leaseUntil', nowMillis + tonumber(ARGV[4]), 'rev', rev + 1,
|
'leaseUntil', nowMillis + tonumber(ARGV[4]), 'rev', rev + 1,
|
||||||
@@ -366,6 +386,8 @@ public final class IdempotencyScripts {
|
|||||||
ALREADY,
|
ALREADY,
|
||||||
ABSENT,
|
ABSENT,
|
||||||
NOT_OWNER,
|
NOT_OWNER,
|
||||||
|
/** The caller still holds the record, but its processing lease has run out. */
|
||||||
|
LEASE_EXPIRED,
|
||||||
OPERATION_CONFLICT,
|
OPERATION_CONFLICT,
|
||||||
WRONG_STATE,
|
WRONG_STATE,
|
||||||
CLAIMED,
|
CLAIMED,
|
||||||
|
|||||||
+2
@@ -175,6 +175,7 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort
|
|||||||
ScriptStatus.ALREADY, IdempotencyStartOutcome.ALREADY_STARTED_SAME_OPERATION,
|
ScriptStatus.ALREADY, IdempotencyStartOutcome.ALREADY_STARTED_SAME_OPERATION,
|
||||||
ScriptStatus.ABSENT, IdempotencyStartOutcome.ABSENT,
|
ScriptStatus.ABSENT, IdempotencyStartOutcome.ABSENT,
|
||||||
ScriptStatus.NOT_OWNER, IdempotencyStartOutcome.NOT_OWNER,
|
ScriptStatus.NOT_OWNER, IdempotencyStartOutcome.NOT_OWNER,
|
||||||
|
ScriptStatus.LEASE_EXPIRED, IdempotencyStartOutcome.LEASE_EXPIRED,
|
||||||
ScriptStatus.WRONG_STATE, IdempotencyStartOutcome.NOT_CLAIMED,
|
ScriptStatus.WRONG_STATE, IdempotencyStartOutcome.NOT_CLAIMED,
|
||||||
ScriptStatus.OPERATION_CONFLICT, IdempotencyStartOutcome.OPERATION_CONFLICT),
|
ScriptStatus.OPERATION_CONFLICT, IdempotencyStartOutcome.OPERATION_CONFLICT),
|
||||||
IdempotencyStartOutcome.INDETERMINATE,
|
IdempotencyStartOutcome.INDETERMINATE,
|
||||||
@@ -204,6 +205,7 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort
|
|||||||
ScriptStatus.ALREADY, IdempotencyRenewOutcome.ALREADY_RENEWED_SAME_OPERATION,
|
ScriptStatus.ALREADY, IdempotencyRenewOutcome.ALREADY_RENEWED_SAME_OPERATION,
|
||||||
ScriptStatus.ABSENT, IdempotencyRenewOutcome.ABSENT,
|
ScriptStatus.ABSENT, IdempotencyRenewOutcome.ABSENT,
|
||||||
ScriptStatus.NOT_OWNER, IdempotencyRenewOutcome.NOT_OWNER,
|
ScriptStatus.NOT_OWNER, IdempotencyRenewOutcome.NOT_OWNER,
|
||||||
|
ScriptStatus.LEASE_EXPIRED, IdempotencyRenewOutcome.LEASE_EXPIRED,
|
||||||
ScriptStatus.WRONG_STATE, IdempotencyRenewOutcome.NOT_IN_PROGRESS,
|
ScriptStatus.WRONG_STATE, IdempotencyRenewOutcome.NOT_IN_PROGRESS,
|
||||||
ScriptStatus.OPERATION_CONFLICT, IdempotencyRenewOutcome.OPERATION_CONFLICT),
|
ScriptStatus.OPERATION_CONFLICT, IdempotencyRenewOutcome.OPERATION_CONFLICT),
|
||||||
IdempotencyRenewOutcome.INDETERMINATE,
|
IdempotencyRenewOutcome.INDETERMINATE,
|
||||||
|
|||||||
+203
@@ -0,0 +1,203 @@
|
|||||||
|
package dev.caskeleton.adapter.outbound.cache.redis.idempotency;
|
||||||
|
|
||||||
|
import static org.assertj.core.api.Assertions.assertThat;
|
||||||
|
|
||||||
|
import dev.caskeleton.adapter.outbound.cache.redis.LiveRedisRuntime;
|
||||||
|
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisConnectionKind;
|
||||||
|
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisLease;
|
||||||
|
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisRuntimeOwner;
|
||||||
|
import dev.caskeleton.adapter.outbound.cache.redis.runtime.key.RedisNamespace;
|
||||||
|
import dev.caskeleton.application.idempotency.IdempotencyClaimAttempt;
|
||||||
|
import dev.caskeleton.application.idempotency.IdempotencyClaimOutcome;
|
||||||
|
import dev.caskeleton.application.idempotency.IdempotencyClaimRequest;
|
||||||
|
import dev.caskeleton.application.idempotency.IdempotencyFailureDisposition;
|
||||||
|
import dev.caskeleton.application.idempotency.IdempotencyInspectionOutcome;
|
||||||
|
import dev.caskeleton.application.idempotency.IdempotencyInspectionRequest;
|
||||||
|
import dev.caskeleton.application.idempotency.IdempotencyOwner;
|
||||||
|
import dev.caskeleton.application.idempotency.IdempotencyScopeDigest;
|
||||||
|
import dev.caskeleton.application.idempotency.RequestFingerprint;
|
||||||
|
import dev.caskeleton.application.transaction.OperationId;
|
||||||
|
import io.lettuce.core.ScriptOutputType;
|
||||||
|
import java.io.IOException;
|
||||||
|
import java.nio.charset.StandardCharsets;
|
||||||
|
import java.nio.file.Files;
|
||||||
|
import java.nio.file.Path;
|
||||||
|
import java.time.Clock;
|
||||||
|
import java.time.Duration;
|
||||||
|
import java.util.UUID;
|
||||||
|
import java.util.concurrent.TimeUnit;
|
||||||
|
import java.util.regex.Matcher;
|
||||||
|
import java.util.regex.Pattern;
|
||||||
|
import org.junit.jupiter.api.AfterEach;
|
||||||
|
import org.junit.jupiter.api.BeforeAll;
|
||||||
|
import org.junit.jupiter.api.BeforeEach;
|
||||||
|
import org.junit.jupiter.api.Tag;
|
||||||
|
import org.junit.jupiter.api.Test;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The Redis repair in {@code docs/runbooks/idempotency-unavailable.md}, run as written against a
|
||||||
|
* real server under the lane's ACL.
|
||||||
|
*
|
||||||
|
* <p>The runbook used to have the operator check the record's state and then delete it with a
|
||||||
|
* second command; a record that expired between the two and was claimed again by a new request was
|
||||||
|
* deleted while that request ran, and the next request with the key ran the work a second time
|
||||||
|
* (re-review 2026-11-04 RR4-03-02). The repair is now one Lua program that checks and deletes
|
||||||
|
* atomically. The application accounts are denied {@code EVAL}, so the runbook loads it and runs it
|
||||||
|
* by digest, as the service's own scripts run — and this test runs it the same way, as the advanced
|
||||||
|
* account, with the record key rendered from the runbook's key template rather than from the
|
||||||
|
* adapter: a wrong template finds no record and fails here.
|
||||||
|
*
|
||||||
|
* <p>The blocks are read out of the runbook, not copied, as the PostgreSQL runbook lanes read
|
||||||
|
* theirs: a copy would pass while the document an operator follows is wrong.
|
||||||
|
*/
|
||||||
|
@Tag("redis-topology")
|
||||||
|
class LiveRedisIdempotencyRunbookTest {
|
||||||
|
|
||||||
|
private static final Pattern SCRIPT_LOAD = Pattern.compile("^SCRIPT LOAD \"(.+)\"$");
|
||||||
|
|
||||||
|
private static final Pattern EVALSHA = Pattern.compile("^EVALSHA <[^>]+> 1 <key>$");
|
||||||
|
|
||||||
|
private static final IdempotencyScopeDigest SCOPE =
|
||||||
|
new IdempotencyScopeDigest("d".repeat(64), 1, "CHARGE_CARD");
|
||||||
|
|
||||||
|
private static final RequestFingerprint FINGERPRINT = new RequestFingerprint("e".repeat(64));
|
||||||
|
|
||||||
|
private static String runbook;
|
||||||
|
|
||||||
|
private RedisNamespace namespace;
|
||||||
|
|
||||||
|
private RedisRuntimeOwner owner;
|
||||||
|
|
||||||
|
private RedisIdempotencyStoreAdapter store;
|
||||||
|
|
||||||
|
@BeforeAll
|
||||||
|
static void readRunbook() throws IOException {
|
||||||
|
String path = System.getProperty("idempotency.runbook");
|
||||||
|
if (path == null || path.isBlank()) {
|
||||||
|
throw new IllegalStateException(
|
||||||
|
"system property idempotency.runbook must name the runbook this lane runs");
|
||||||
|
}
|
||||||
|
runbook = Files.readString(Path.of(path), StandardCharsets.UTF_8);
|
||||||
|
}
|
||||||
|
|
||||||
|
@BeforeEach
|
||||||
|
void openStore() {
|
||||||
|
namespace =
|
||||||
|
new RedisNamespace("prod", "order", "r" + UUID.randomUUID().toString().substring(0, 8));
|
||||||
|
owner = LiveRedisRuntime.open(namespace, true);
|
||||||
|
store =
|
||||||
|
new RedisIdempotencyStoreAdapter(
|
||||||
|
owner,
|
||||||
|
new RedisIdempotencyStoreAdapter.IdempotencyKeys(namespace, 1),
|
||||||
|
new IdempotencyScripts(),
|
||||||
|
Clock.systemUTC(),
|
||||||
|
Duration.ofSeconds(2));
|
||||||
|
}
|
||||||
|
|
||||||
|
@AfterEach
|
||||||
|
void closeOwner() {
|
||||||
|
owner.close();
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void theRunbookDeleteRemovesAnAbandonedRecordSoTheKeyRunsAgain() throws Exception {
|
||||||
|
// given
|
||||||
|
IdempotencyOwner executing = executing(store.newClaimAttempt(new OperationId("op-abandon")));
|
||||||
|
store.markFailed(
|
||||||
|
executing,
|
||||||
|
IdempotencyFailureDisposition.EFFECT_UNKNOWN_ABANDONED,
|
||||||
|
Duration.ofHours(1),
|
||||||
|
new OperationId("op-abandon"));
|
||||||
|
|
||||||
|
// when
|
||||||
|
long deleted = runTheRunbookDelete();
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(deleted).isEqualTo(1);
|
||||||
|
assertThat(store.claim(claim(store.newClaimAttempt(new OperationId("op-again")))))
|
||||||
|
.isInstanceOf(IdempotencyClaimOutcome.Acquired.class);
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void theRunbookDeleteLeavesARecordThatIsNoLongerAbandoned() throws Exception {
|
||||||
|
// given
|
||||||
|
// What the operator's key holds when the abandoned record expired after they looked at it and
|
||||||
|
// a new request claimed the key and started: the delete must leave that request's record.
|
||||||
|
IdempotencyClaimAttempt running = store.newClaimAttempt(new OperationId("op-running"));
|
||||||
|
IdempotencyOwner executing = executing(running);
|
||||||
|
|
||||||
|
// when
|
||||||
|
long deleted = runTheRunbookDelete();
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(deleted).isZero();
|
||||||
|
var holder = store.inspect(new IdempotencyInspectionRequest(SCOPE, FINGERPRINT, running));
|
||||||
|
assertThat(holder.outcome()).isEqualTo(IdempotencyInspectionOutcome.EXECUTING_SAME_OPERATION);
|
||||||
|
assertThat(holder.owner()).contains(executing);
|
||||||
|
}
|
||||||
|
|
||||||
|
private IdempotencyOwner executing(IdempotencyClaimAttempt attempt) {
|
||||||
|
IdempotencyOwner claimed =
|
||||||
|
((IdempotencyClaimOutcome.Acquired) store.claim(claim(attempt))).owner();
|
||||||
|
return store.markExecutionStarted(claimed, attempt.operationId()).owner().orElseThrow();
|
||||||
|
}
|
||||||
|
|
||||||
|
private static IdempotencyClaimRequest claim(IdempotencyClaimAttempt attempt) {
|
||||||
|
return new IdempotencyClaimRequest(
|
||||||
|
SCOPE, FINGERPRINT, attempt, Duration.ofSeconds(30), Duration.ofHours(1), "json-v2", 1);
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Runs the runbook's two lines as an operator would: load the program, then run it by the digest
|
||||||
|
* the load printed, on the key the runbook's template names.
|
||||||
|
*/
|
||||||
|
private long runTheRunbookDelete() throws Exception {
|
||||||
|
String[] lines = block("idempotency-delete-abandoned").strip().split("\n");
|
||||||
|
assertThat(lines).as("the repair is a load and one run").hasSize(2);
|
||||||
|
Matcher load = SCRIPT_LOAD.matcher(lines[0].strip());
|
||||||
|
assertThat(load.matches()).as("first line loads the program: %s", lines[0]).isTrue();
|
||||||
|
assertThat(EVALSHA.matcher(lines[1].strip()).matches())
|
||||||
|
.as("second line runs it by digest on the one key: %s", lines[1])
|
||||||
|
.isTrue();
|
||||||
|
byte[] key = recordKeyFromTheRunbook().getBytes(StandardCharsets.UTF_8);
|
||||||
|
try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) {
|
||||||
|
var commands = lease.driver().commands();
|
||||||
|
String digest =
|
||||||
|
commands
|
||||||
|
.scriptLoad(load.group(1).getBytes(StandardCharsets.UTF_8))
|
||||||
|
.toCompletableFuture()
|
||||||
|
.get(2, TimeUnit.SECONDS);
|
||||||
|
return commands
|
||||||
|
.<Long>evalsha(digest, ScriptOutputType.INTEGER, key)
|
||||||
|
.toCompletableFuture()
|
||||||
|
.get(2, TimeUnit.SECONDS);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/** The record key, from the runbook's template filled in as an operator would. */
|
||||||
|
private String recordKeyFromTheRunbook() {
|
||||||
|
return block("idempotency-record-key")
|
||||||
|
.strip()
|
||||||
|
.replace("<APP_REDIS_NAMESPACE_ENVIRONMENT>", namespace.environment())
|
||||||
|
.replace("<APP_REDIS_NAMESPACE_SERVICE>", namespace.service())
|
||||||
|
.replace("<APP_REDIS_NAMESPACE_DOMAIN>", namespace.domain())
|
||||||
|
.replace("<digest version>", Integer.toString(SCOPE.keyDigestVersion()))
|
||||||
|
.replace("<operation code>", SCOPE.operationCode())
|
||||||
|
.replace("<scope digest>", SCOPE.digest());
|
||||||
|
}
|
||||||
|
|
||||||
|
/** The fenced block that follows {@code <!-- runbook-redis: id -->}. */
|
||||||
|
private static String block(String id) {
|
||||||
|
String marker = "<!-- runbook-redis: " + id + " -->";
|
||||||
|
int at = runbook.indexOf(marker);
|
||||||
|
if (at < 0) {
|
||||||
|
throw new IllegalStateException("the idempotency runbook has no Redis block marked " + id);
|
||||||
|
}
|
||||||
|
int open = runbook.indexOf("```\n", at);
|
||||||
|
int close = runbook.indexOf("```", open + 4);
|
||||||
|
if (open < 0 || close < 0) {
|
||||||
|
throw new IllegalStateException("the block marked " + id + " is not a closed fence");
|
||||||
|
}
|
||||||
|
return runbook.substring(open + 4, close);
|
||||||
|
}
|
||||||
|
}
|
||||||
+79
-1
@@ -364,7 +364,85 @@ class RedisIdempotencyStoreAdapterTest {
|
|||||||
var renewed = store.renew(executing, Duration.ofSeconds(30), OPERATION);
|
var renewed = store.renew(executing, Duration.ofSeconds(30), OPERATION);
|
||||||
|
|
||||||
// then
|
// then
|
||||||
assertThat(renewed.outcome()).isEqualTo(IdempotencyRenewOutcome.NOT_OWNER);
|
// The holder still owns the record — it still completes it — so not NOT_OWNER (RR5-01-02).
|
||||||
|
assertThat(renewed.outcome()).isEqualTo(IdempotencyRenewOutcome.LEASE_EXPIRED);
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("lease가 지난 실행 전 claim은 주인도 시작할 수 없다")
|
||||||
|
void aClaimWhoseLeaseRanOutBeforeItStartedIsNotStarted() {
|
||||||
|
// given
|
||||||
|
// The live contract proves the program; this proves the fixture's copy of TRANSITION refuses
|
||||||
|
// the late start as the program does (re-review 2026-11-04 README 15).
|
||||||
|
IdempotencyOwner claimed =
|
||||||
|
((IdempotencyClaimOutcome.Acquired) store.claim(claim(store.newClaimAttempt(OPERATION))))
|
||||||
|
.owner();
|
||||||
|
gateway.advance(Duration.ofSeconds(60));
|
||||||
|
|
||||||
|
// when
|
||||||
|
var started = store.markExecutionStarted(claimed, OPERATION);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(started.outcome()).isEqualTo(IdempotencyStartOutcome.LEASE_EXPIRED);
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("lease가 지나 시작을 거절당한 claim은 다음 claim이 attempt 2로 넘겨받는다")
|
||||||
|
void aClaimWhoseLateStartWasRefusedIsTakenOver() {
|
||||||
|
// given
|
||||||
|
IdempotencyOwner claimed =
|
||||||
|
((IdempotencyClaimOutcome.Acquired) store.claim(claim(store.newClaimAttempt(OPERATION))))
|
||||||
|
.owner();
|
||||||
|
gateway.advance(Duration.ofSeconds(60));
|
||||||
|
store.markExecutionStarted(claimed, OPERATION);
|
||||||
|
|
||||||
|
// when
|
||||||
|
IdempotencyClaimOutcome next = store.claim(claim(store.newClaimAttempt(OTHER_OPERATION)));
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(next)
|
||||||
|
.isInstanceOfSatisfying(
|
||||||
|
IdempotencyClaimOutcome.TakenOverClaimed.class,
|
||||||
|
takenOver -> assertThat(takenOver.owner().attempt()).isEqualTo(2));
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("lease가 지난 실행의 주인이 늦게 보고한 재시도 가능 실패 뒤에는 다음 claim이 넘겨받는다")
|
||||||
|
void aLateRetryableFailureOfAnExpiredExecutionLetsTheNextClaimTakeOver() {
|
||||||
|
// given
|
||||||
|
// The late markFailed through the fixture's copy of TRANSITION, which no test reached
|
||||||
|
// (re-review 2026-11-04 RR5-01-04).
|
||||||
|
IdempotencyOwner late = executing();
|
||||||
|
gateway.advance(Duration.ofSeconds(60));
|
||||||
|
store.claim(claim(store.newClaimAttempt(OTHER_OPERATION)));
|
||||||
|
store.markFailed(
|
||||||
|
late, IdempotencyFailureDisposition.NO_EFFECT_RETRYABLE, Duration.ofHours(1), OPERATION);
|
||||||
|
|
||||||
|
// when
|
||||||
|
IdempotencyClaimOutcome next = store.claim(claim(store.newClaimAttempt(OTHER_OPERATION)));
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(next).isInstanceOf(IdempotencyClaimOutcome.TakenOverClaimed.class);
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("lease가 지난 실행의 주인이 늦게 보고한 효과 불명 실패 뒤에도 다음 claim은 회복 필요를 받는다")
|
||||||
|
void aLateUnknownEffectOfAnExpiredExecutionKeepsTheNextClaimInRecovery() {
|
||||||
|
// given
|
||||||
|
IdempotencyOwner late = executing();
|
||||||
|
gateway.advance(Duration.ofSeconds(60));
|
||||||
|
store.claim(claim(store.newClaimAttempt(OTHER_OPERATION)));
|
||||||
|
store.markFailed(
|
||||||
|
late,
|
||||||
|
IdempotencyFailureDisposition.EFFECT_UNKNOWN_ABANDONED,
|
||||||
|
Duration.ofHours(1),
|
||||||
|
OPERATION);
|
||||||
|
|
||||||
|
// when
|
||||||
|
IdempotencyClaimOutcome next = store.claim(claim(store.newClaimAttempt(OTHER_OPERATION)));
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(next).isInstanceOf(IdempotencyClaimOutcome.RecoveryRequired.class);
|
||||||
}
|
}
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
|
|||||||
@@ -43,7 +43,11 @@ no reactive (`WebClient`/Reactor Netty) surface; it was removed on 2026-09-25 (d
|
|||||||
`HttpDeadlineExceededException`. A streaming download's setup (up to the response headers) runs
|
`HttpDeadlineExceededException`. A streaming download's setup (up to the response headers) runs
|
||||||
inside the same deadline; after hand-over each body gap is bounded by `read-idle` and nothing else,
|
inside the same deadline; after hand-over each body gap is bounded by `read-idle` and nothing else,
|
||||||
on both transports — on the JDK transport, which has no socket read timeout, a per-stream watchdog
|
on both transports — on the JDK transport, which has no socket read timeout, a per-stream watchdog
|
||||||
on its own daemon thread (`httpclient-jdk-read-idle`) bounds each read's wait. A body that fails
|
bounds each read's wait. The watchdogs share one daemon thread (`httpclient-jdk-read-idle`): the
|
||||||
|
first stream that needs it starts it, it ends 60 s after the last wake it had queued, and the next
|
||||||
|
stream starts it again. It inherits no thread-locals from the request thread that starts it and
|
||||||
|
uses this module's class loader as its context loader, so it pins neither a request's state nor a
|
||||||
|
redeployed application's loader. A body that fails
|
||||||
after hand-over throws `HttpBodyReadException`, an `IOException` as `InputStream.read` promises,
|
after hand-over throws `HttpBodyReadException`, an `IOException` as `InputStream.read` promises,
|
||||||
whose `failure()` is the same stable exception a buffered call throws
|
whose `failure()` is the same stable exception a buffered call throws
|
||||||
(`HttpResponseTimeoutException` for a stalled body, `HttpResponseTruncatedException` for a cut
|
(`HttpResponseTimeoutException` for a stalled body, `HttpResponseTruncatedException` for a cut
|
||||||
|
|||||||
@@ -227,14 +227,18 @@ strictTestLanes {
|
|||||||
// name's fail-closed selection is proven before a release tag, not first on one (review 2026-11-01
|
// name's fail-closed selection is proven before a release tag, not first on one (review 2026-11-01
|
||||||
// 08-01).
|
// 08-01).
|
||||||
//
|
//
|
||||||
// httpClientFailureInjectionTest joins the main stage too (review 2026-11-01 05-06, 05-16). It is
|
// httpClientFailureInjectionTest is deliberately not in mainCheck. It is the only lane that proves
|
||||||
// the only lane that proves the deadline and evidence contracts against real TCP faults — a slow
|
// the deadline and evidence contracts against real TCP faults — a slow drip, a cut stream, a refused
|
||||||
// drip, a cut stream, a refused connect — and it was reachable only through integrationCheck, so a
|
// connect — and review 2026-11-01 05-06/05-16 put it in the main stage because it was reachable only
|
||||||
// main-branch build could go green with those contracts broken. The main stage already runs Docker
|
// through integrationCheck, which then ran on no main-branch build. That premise no longer holds:
|
||||||
// lanes (MinIO), so the lane's fail-closed Docker requirement costs that stage nothing new; it stays
|
// integration-main.yml's `integration-check` job runs integrationCheck (an integration lane, so this
|
||||||
// out of `check` for the reason above.
|
// one) on every push to main and nightly, in the same workflow run as the `main-check` job. In both
|
||||||
|
// stages, every main push started a second Toxiproxy and httpbin and ran every fault twice without
|
||||||
|
// covering anything the first run did not (review 2026-11-03 README §8, closed in round 9; the
|
||||||
|
// cache-redis container lane left mainCheck for the same reason). verifyStrictLaneStages still fails
|
||||||
|
// if no executed stage reaches it. It stays out of `check` for the reason above.
|
||||||
tasks.named('mainCheck') {
|
tasks.named('mainCheck') {
|
||||||
dependsOn 'spring70CompatibilityTest', 'httpClientFailureInjectionTest'
|
dependsOn 'spring70CompatibilityTest'
|
||||||
}
|
}
|
||||||
|
|
||||||
tasks.named('check') {
|
tasks.named('check') {
|
||||||
|
|||||||
+51
-18
@@ -9,6 +9,7 @@ import java.util.Objects;
|
|||||||
import java.util.concurrent.ScheduledExecutorService;
|
import java.util.concurrent.ScheduledExecutorService;
|
||||||
import java.util.concurrent.ScheduledFuture;
|
import java.util.concurrent.ScheduledFuture;
|
||||||
import java.util.concurrent.ScheduledThreadPoolExecutor;
|
import java.util.concurrent.ScheduledThreadPoolExecutor;
|
||||||
|
import java.util.concurrent.ThreadFactory;
|
||||||
import java.util.concurrent.TimeUnit;
|
import java.util.concurrent.TimeUnit;
|
||||||
import java.util.concurrent.atomic.AtomicBoolean;
|
import java.util.concurrent.atomic.AtomicBoolean;
|
||||||
|
|
||||||
@@ -33,19 +34,29 @@ import java.util.concurrent.atomic.AtomicBoolean;
|
|||||||
* it moves the queue off the shared scheduler but keeps a queue insertion and removal on every
|
* it moves the queue off the shared scheduler but keeps a queue insertion and removal on every
|
||||||
* read.
|
* read.
|
||||||
*
|
*
|
||||||
* <p>The watchdog wakes on a thread of its own: one daemon thread, {@code
|
* <p>The watchdog wakes on a thread of its own: at most one daemon thread, {@code
|
||||||
* httpclient-jdk-read-idle}, shared by every JDK stream and started with the first (re-review
|
* httpclient-jdk-read-idle}, shared by every JDK stream (re-review 2026-11-04 RR3-03-01). It used
|
||||||
* 2026-11-04 RR3-03-01). It used to wake through {@code CompletableFuture.delayedExecutor}, whose
|
* to wake through {@code CompletableFuture.delayedExecutor}, whose task runs on the common {@code
|
||||||
* task runs on the common {@code ForkJoinPool}; a service that filled that pool with blocking work
|
* ForkJoinPool}; a service that filled that pool with blocking work — {@code
|
||||||
* — {@code supplyAsync(blockingCall)} without an executor — held every timeout until a pool thread
|
* supplyAsync(blockingCall)} without an executor — held every timeout until a pool thread came
|
||||||
* came free, and a 300 ms {@code read-idle} ended after 2.7 s. The wake is O(1), and the close it
|
* free, and a 300 ms {@code read-idle} ended after 2.7 s. The wake is O(1), and the close it may do
|
||||||
* may do waits on no I/O — the JDK body marks itself closed, cancels its subscription and wakes the
|
* waits on no I/O — the JDK body marks itself closed, cancels its subscription and wakes the read —
|
||||||
* read — so both run on this thread, as the per-read timer before RR-03-13 closed on the JDK's
|
* so both run on this thread, as the per-read timer before RR-03-13 closed on the JDK's delay
|
||||||
* delay thread. Rejected: {@code delayedExecutor(delay, unit, Runnable::run)}, which judges on the
|
* thread. Rejected: {@code delayedExecutor(delay, unit, Runnable::run)}, which judges on the JDK's
|
||||||
* JDK's own delay thread — that thread fires every {@code CompletableFuture} timeout in the
|
* own delay thread — that thread fires every {@code CompletableFuture} timeout in the process, so a
|
||||||
* process, so a slow close there would delay them all, and it returns no handle to take a closed
|
* slow close there would delay them all, and it returns no handle to take a closed stream's wake
|
||||||
* stream's wake off the queue. Closing the stream cancels its pending wake, so a closed stream is
|
* off the queue. Closing the stream cancels its pending wake, so a closed stream is not kept
|
||||||
* not kept reachable until its {@code read-idle} passes.
|
* reachable until its {@code read-idle} passes.
|
||||||
|
*
|
||||||
|
* <p>The thread's lifetime (RR4-03-04). The first stream that schedules a wake starts it; once no
|
||||||
|
* wake has been queued for {@link #IDLE_THREAD_KEEP_ALIVE} it ends, and the next stream that needs
|
||||||
|
* it starts a new one. While reads keep coming a wake is always queued, so a busy service keeps one
|
||||||
|
* thread; an idle one keeps none. It used to live as long as the class did: the JVM's life for a
|
||||||
|
* runnable jar, but a WAR redeploy or a restart class loader left it holding the old loader. It
|
||||||
|
* takes nothing from the request thread that starts it — no inheritable thread-locals, and this
|
||||||
|
* class's own loader as its context loader — so it never keeps a request's state or a foreign
|
||||||
|
* loader alive while it waits. Restarting costs one thread start per idle spell, against a
|
||||||
|
* scheduled task per {@code read-idle} on every live stream.
|
||||||
*
|
*
|
||||||
* <p>{@link #skip} reads through this stream rather than delegating: the JDK body does not override
|
* <p>{@link #skip} reads through this stream rather than delegating: the JDK body does not override
|
||||||
* {@code skip}, so {@code InputStream.skip} ran many reads inside one guarded call and a long skip
|
* {@code skip}, so {@code InputStream.skip} ran many reads inside one guarded call and a long skip
|
||||||
@@ -56,6 +67,9 @@ final class ReadIdleInputStream extends FilterInputStream {
|
|||||||
/** The largest scratch buffer {@link #skip} reads into, as {@code InputStream.skip} uses. */
|
/** The largest scratch buffer {@link #skip} reads into, as {@code InputStream.skip} uses. */
|
||||||
private static final int SKIP_BUFFER_BYTES = 2048;
|
private static final int SKIP_BUFFER_BYTES = 2048;
|
||||||
|
|
||||||
|
/** How long the watchdog thread outlives the last wake it had queued. */
|
||||||
|
static final Duration IDLE_THREAD_KEEP_ALIVE = Duration.ofSeconds(60);
|
||||||
|
|
||||||
/** {@link #readStartedAt} while no read is waiting. */
|
/** {@link #readStartedAt} while no read is waiting. */
|
||||||
private static final long NOT_READING = Long.MIN_VALUE;
|
private static final long NOT_READING = Long.MIN_VALUE;
|
||||||
|
|
||||||
@@ -84,19 +98,38 @@ final class ReadIdleInputStream extends FilterInputStream {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* A watchdog scheduler as every stream gets it: one daemon thread, and a cancelled wake leaves
|
* A watchdog scheduler as every stream gets it: at most one daemon thread, which ends after
|
||||||
* the queue at once instead of when it would have fired.
|
* {@link #IDLE_THREAD_KEEP_ALIVE} with nothing queued, and a cancelled wake leaves the queue at
|
||||||
|
* once instead of when it would have fired.
|
||||||
*/
|
*/
|
||||||
static ScheduledThreadPoolExecutor newWatchdogs() {
|
static ScheduledThreadPoolExecutor newWatchdogs() {
|
||||||
|
return newWatchdogs(IDLE_THREAD_KEEP_ALIVE);
|
||||||
|
}
|
||||||
|
|
||||||
|
/** As {@link #newWatchdogs()}, with the thread ending after {@code idleThreadKeepAlive}. */
|
||||||
|
static ScheduledThreadPoolExecutor newWatchdogs(Duration idleThreadKeepAlive) {
|
||||||
|
ClassLoader ownLoader = ReadIdleInputStream.class.getClassLoader();
|
||||||
|
// factory(), not the builder: the builder is not thread-safe, and any request thread may be
|
||||||
|
// the one whose schedule() starts the worker.
|
||||||
|
ThreadFactory threads =
|
||||||
|
Thread.ofPlatform()
|
||||||
|
.name("httpclient-jdk-read-idle")
|
||||||
|
.daemon(true)
|
||||||
|
.inheritInheritableThreadLocals(false)
|
||||||
|
.factory();
|
||||||
ScheduledThreadPoolExecutor scheduler =
|
ScheduledThreadPoolExecutor scheduler =
|
||||||
new ScheduledThreadPoolExecutor(
|
new ScheduledThreadPoolExecutor(
|
||||||
1,
|
1,
|
||||||
runnable -> {
|
runnable -> {
|
||||||
Thread thread = new Thread(runnable, "httpclient-jdk-read-idle");
|
Thread thread = threads.newThread(runnable);
|
||||||
thread.setDaemon(true);
|
thread.setContextClassLoader(ownLoader);
|
||||||
return thread;
|
return thread;
|
||||||
});
|
});
|
||||||
scheduler.setRemoveOnCancelPolicy(true);
|
scheduler.setRemoveOnCancelPolicy(true);
|
||||||
|
// The worker exits only when the queue is empty as well as idle (ThreadPoolExecutor keeps the
|
||||||
|
// last worker while a task is queued), and the next schedule() starts one again.
|
||||||
|
scheduler.setKeepAliveTime(idleThreadKeepAlive.toNanos(), TimeUnit.NANOSECONDS);
|
||||||
|
scheduler.allowCoreThreadTimeOut(true);
|
||||||
return scheduler;
|
return scheduler;
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -213,7 +246,7 @@ final class ReadIdleInputStream extends FilterInputStream {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/** The scheduler every stream shares, started with the first stream that is read. */
|
/** The scheduler every stream shares; its thread comes and goes as described above. */
|
||||||
private static final class SharedWatchdogs {
|
private static final class SharedWatchdogs {
|
||||||
|
|
||||||
static final ScheduledExecutorService INSTANCE = newWatchdogs();
|
static final ScheduledExecutorService INSTANCE = newWatchdogs();
|
||||||
|
|||||||
+47
-10
@@ -7,8 +7,10 @@ import java.util.List;
|
|||||||
import java.util.Map;
|
import java.util.Map;
|
||||||
import java.util.NoSuchElementException;
|
import java.util.NoSuchElementException;
|
||||||
import java.util.Objects;
|
import java.util.Objects;
|
||||||
|
import java.util.Queue;
|
||||||
import java.util.Set;
|
import java.util.Set;
|
||||||
import java.util.concurrent.ConcurrentHashMap;
|
import java.util.concurrent.ConcurrentHashMap;
|
||||||
|
import java.util.concurrent.ConcurrentLinkedQueue;
|
||||||
import java.util.concurrent.ConcurrentMap;
|
import java.util.concurrent.ConcurrentMap;
|
||||||
import java.util.concurrent.Executors;
|
import java.util.concurrent.Executors;
|
||||||
import java.util.concurrent.ScheduledExecutorService;
|
import java.util.concurrent.ScheduledExecutorService;
|
||||||
@@ -31,6 +33,9 @@ public final class ClientRuntimeRegistry implements AutoCloseable {
|
|||||||
new ConcurrentHashMap<>();
|
new ConcurrentHashMap<>();
|
||||||
private final AtomicReference<ScheduledExecutorService> drainScheduler = new AtomicReference<>();
|
private final AtomicReference<ScheduledExecutorService> drainScheduler = new AtomicReference<>();
|
||||||
|
|
||||||
|
/** Threads the drain scheduler created, so close can wait for them to exit (stopDrainThread). */
|
||||||
|
private final Queue<Thread> drainThreads = new ConcurrentLinkedQueue<>();
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Generations that have been replaced but are not yet closed.
|
* Generations that have been replaced but are not yet closed.
|
||||||
*
|
*
|
||||||
@@ -140,21 +145,52 @@ public final class ClientRuntimeRegistry implements AutoCloseable {
|
|||||||
}
|
}
|
||||||
retired.clear();
|
retired.clear();
|
||||||
runtimes.clear();
|
runtimes.clear();
|
||||||
|
// The drain thread is stopped whether or not a runtime refused to close. Throwing first left
|
||||||
|
// the scheduler, and its thread, running after a failed shutdown.
|
||||||
|
try {
|
||||||
|
stopDrainThread();
|
||||||
|
} catch (RuntimeException failure) {
|
||||||
|
if (firstFailure == null) {
|
||||||
|
firstFailure = failure;
|
||||||
|
} else {
|
||||||
|
firstFailure.addSuppressed(failure);
|
||||||
|
}
|
||||||
|
}
|
||||||
if (firstFailure != null) {
|
if (firstFailure != null) {
|
||||||
throw firstFailure;
|
throw firstFailure;
|
||||||
}
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Stops the drain scheduler and waits for its thread to be gone.
|
||||||
|
*
|
||||||
|
* <p>A registry that returns while its drain thread is still alive leaks a thread per rotation
|
||||||
|
* cycle, which the resource-bound suite exists to catch. {@code awaitTermination} is not enough:
|
||||||
|
* the executor reports termination from inside the worker before that thread exits, so under load
|
||||||
|
* the thread could still be listed when close returned. Joining the thread is what makes "no
|
||||||
|
* thread left" true when this returns.
|
||||||
|
*/
|
||||||
|
private void stopDrainThread() {
|
||||||
ScheduledExecutorService scheduler = drainScheduler.getAndSet(null);
|
ScheduledExecutorService scheduler = drainScheduler.getAndSet(null);
|
||||||
if (scheduler != null) {
|
if (scheduler == null) {
|
||||||
// Await termination: a registry that returns while its drain thread is still alive would
|
return;
|
||||||
// leak a thread per rotation cycle, which the resource-bound suite exists to catch.
|
}
|
||||||
scheduler.shutdownNow();
|
scheduler.shutdownNow();
|
||||||
try {
|
long deadline = System.nanoTime() + TimeUnit.MILLISECONDS.toNanos(SHUTDOWN_AWAIT_MILLIS);
|
||||||
if (!scheduler.awaitTermination(SHUTDOWN_AWAIT_MILLIS, TimeUnit.MILLISECONDS)) {
|
try {
|
||||||
throw new IllegalStateException("http client drain scheduler did not terminate");
|
if (!scheduler.awaitTermination(SHUTDOWN_AWAIT_MILLIS, TimeUnit.MILLISECONDS)) {
|
||||||
}
|
throw new IllegalStateException("http client drain scheduler did not terminate");
|
||||||
} catch (InterruptedException interrupted) {
|
|
||||||
Thread.currentThread().interrupt();
|
|
||||||
}
|
}
|
||||||
|
for (Thread thread : drainThreads) {
|
||||||
|
long remaining = TimeUnit.NANOSECONDS.toMillis(deadline - System.nanoTime());
|
||||||
|
thread.join(Math.max(1L, remaining));
|
||||||
|
if (thread.isAlive()) {
|
||||||
|
throw new IllegalStateException("http client drain thread did not exit");
|
||||||
|
}
|
||||||
|
}
|
||||||
|
drainThreads.clear();
|
||||||
|
} catch (InterruptedException interrupted) {
|
||||||
|
Thread.currentThread().interrupt();
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -176,6 +212,7 @@ public final class ClientRuntimeRegistry implements AutoCloseable {
|
|||||||
runnable -> {
|
runnable -> {
|
||||||
Thread thread = new Thread(runnable, "httpclient-runtime-drain");
|
Thread thread = new Thread(runnable, "httpclient-runtime-drain");
|
||||||
thread.setDaemon(true);
|
thread.setDaemon(true);
|
||||||
|
drainThreads.add(thread);
|
||||||
return thread;
|
return thread;
|
||||||
});
|
});
|
||||||
if (drainScheduler.compareAndSet(null, created)) {
|
if (drainScheduler.compareAndSet(null, created)) {
|
||||||
|
|||||||
+121
-4
@@ -6,7 +6,11 @@ import static org.assertj.core.api.Assertions.catchThrowable;
|
|||||||
import java.io.IOException;
|
import java.io.IOException;
|
||||||
import java.io.InputStream;
|
import java.io.InputStream;
|
||||||
import java.net.SocketTimeoutException;
|
import java.net.SocketTimeoutException;
|
||||||
|
import java.net.URL;
|
||||||
|
import java.net.URLClassLoader;
|
||||||
import java.time.Duration;
|
import java.time.Duration;
|
||||||
|
import java.util.Arrays;
|
||||||
|
import java.util.List;
|
||||||
import java.util.concurrent.CountDownLatch;
|
import java.util.concurrent.CountDownLatch;
|
||||||
import java.util.concurrent.ForkJoinPool;
|
import java.util.concurrent.ForkJoinPool;
|
||||||
import java.util.concurrent.ScheduledThreadPoolExecutor;
|
import java.util.concurrent.ScheduledThreadPoolExecutor;
|
||||||
@@ -18,13 +22,15 @@ import org.junit.jupiter.api.Test;
|
|||||||
* What the JDK transport's read-idle bound promises: each read that waits longer than {@code
|
* What the JDK transport's read-idle bound promises: each read that waits longer than {@code
|
||||||
* read-idle} for the server ends the body, and nothing else does (re-review 2026-11-04 RR-03-12,
|
* read-idle} for the server ends the body, and nothing else does (re-review 2026-11-04 RR-03-12,
|
||||||
* RR-03-13); the watchdog keeps that time whatever the common pool is doing, and leaves nothing
|
* RR-03-13); the watchdog keeps that time whatever the common pool is doing, and leaves nothing
|
||||||
* scheduled for a stream that is closed or timed out (RR3-03-01).
|
* scheduled for a stream that is closed or timed out (RR3-03-01); and its thread ends when no
|
||||||
|
* stream needs it and holds nothing of the request thread that started it (RR4-03-04).
|
||||||
*/
|
*/
|
||||||
class ReadIdleInputStreamTest {
|
class ReadIdleInputStreamTest {
|
||||||
|
|
||||||
private static final Duration READ_IDLE = Duration.ofMillis(300);
|
private static final Duration READ_IDLE = Duration.ofMillis(300);
|
||||||
private static final Duration GAP = Duration.ofMillis(20);
|
private static final Duration GAP = Duration.ofMillis(20);
|
||||||
private static final Duration COMMON_POOL_HOLD = Duration.ofSeconds(3);
|
private static final Duration COMMON_POOL_HOLD = Duration.ofSeconds(3);
|
||||||
|
private static final Duration KEEP_ALIVE = Duration.ofMillis(50);
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
@DisplayName("데이터가 read-idle보다 짧은 간격으로 오면 read-idle보다 오래 걸리는 skip도 끝까지 건너뛴다")
|
@DisplayName("데이터가 read-idle보다 짧은 간격으로 오면 read-idle보다 오래 걸리는 skip도 끝까지 건너뛴다")
|
||||||
@@ -72,13 +78,16 @@ class ReadIdleInputStreamTest {
|
|||||||
}
|
}
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
@DisplayName("공용 ForkJoinPool이 블로킹 작업으로 차 있어도 멈춘 read는 read-idle 무렵에 끝난다")
|
@DisplayName("공용 ForkJoinPool이 블로킹 작업으로 차 있어도 멈춘 read는 read-idle 무렵에 watchdog 전용 스레드에서 끝난다")
|
||||||
void aStalledReadTimesOutOnTimeWhileTheCommonPoolIsBlocked() throws Exception {
|
void aStalledReadTimesOutOnTimeWhileTheCommonPoolIsBlocked() throws Exception {
|
||||||
// given
|
// given
|
||||||
// Every common-pool worker parks on a latch, which does not make the pool add a spare thread —
|
// Every common-pool worker parks on a latch, which does not make the pool add a spare thread —
|
||||||
// what a service's supplyAsync(blockingCall) without an executor does. The hold is bounded so
|
// what a service's supplyAsync(blockingCall) without an executor does. The hold is bounded so
|
||||||
// a watchdog that needs a pool worker still ends the read, late (re-review 2026-11-04
|
// a watchdog that needs a pool worker still ends the read, late (re-review 2026-11-04
|
||||||
// RR3-03-01: 300 ms read-idle timed out after 2,699 ms).
|
// RR3-03-01: 300 ms read-idle timed out after 2,699 ms). The timing alone does not catch that
|
||||||
|
// where the common pool's parallelism is 1 (two CPUs): the JDK then runs a delayed task on a
|
||||||
|
// new thread each time, on time. The thread that closed the stream does, on any machine
|
||||||
|
// (RR4-03-01).
|
||||||
int workers = Math.max(1, ForkJoinPool.getCommonPoolParallelism());
|
int workers = Math.max(1, ForkJoinPool.getCommonPoolParallelism());
|
||||||
CountDownLatch occupied = new CountDownLatch(workers);
|
CountDownLatch occupied = new CountDownLatch(workers);
|
||||||
CountDownLatch release = new CountDownLatch(1);
|
CountDownLatch release = new CountDownLatch(1);
|
||||||
@@ -91,7 +100,8 @@ class ReadIdleInputStreamTest {
|
|||||||
});
|
});
|
||||||
}
|
}
|
||||||
assertThat(occupied.await(5, TimeUnit.SECONDS)).as("every common-pool worker is held").isTrue();
|
assertThat(occupied.await(5, TimeUnit.SECONDS)).as("every common-pool worker is held").isTrue();
|
||||||
InputStream body = new ReadIdleInputStream(new StalledStream(), READ_IDLE);
|
StalledStream stalled = new StalledStream();
|
||||||
|
InputStream body = new ReadIdleInputStream(stalled, READ_IDLE);
|
||||||
long started = System.nanoTime();
|
long started = System.nanoTime();
|
||||||
try {
|
try {
|
||||||
// when
|
// when
|
||||||
@@ -101,6 +111,7 @@ class ReadIdleInputStreamTest {
|
|||||||
Duration waited = Duration.ofNanos(System.nanoTime() - started);
|
Duration waited = Duration.ofNanos(System.nanoTime() - started);
|
||||||
assertThat(failure).isInstanceOf(SocketTimeoutException.class);
|
assertThat(failure).isInstanceOf(SocketTimeoutException.class);
|
||||||
assertThat(waited).isGreaterThanOrEqualTo(READ_IDLE).isLessThan(READ_IDLE.multipliedBy(3));
|
assertThat(waited).isGreaterThanOrEqualTo(READ_IDLE).isLessThan(READ_IDLE.multipliedBy(3));
|
||||||
|
assertThat(stalled.closedBy()).isEqualTo("httpclient-jdk-read-idle");
|
||||||
} finally {
|
} finally {
|
||||||
release.countDown();
|
release.countDown();
|
||||||
}
|
}
|
||||||
@@ -144,6 +155,93 @@ class ReadIdleInputStreamTest {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("기다리는 스트림이 없으면 watchdog 스레드는 유지 시간 뒤 끝난다")
|
||||||
|
void theWatchdogThreadEndsWhenNoStreamNeedsIt() throws Exception {
|
||||||
|
// given
|
||||||
|
// A thread that never ended kept this class's loader alive for the life of the JVM — a WAR
|
||||||
|
// redeploy or a restart class loader leaked the old one (re-review 2026-11-04 RR4-03-04).
|
||||||
|
ScheduledThreadPoolExecutor watchdogs = ReadIdleInputStream.newWatchdogs(KEEP_ALIVE);
|
||||||
|
try {
|
||||||
|
try (InputStream body =
|
||||||
|
new ReadIdleInputStream(new DrippingStream(1, GAP), READ_IDLE, watchdogs)) {
|
||||||
|
body.read();
|
||||||
|
}
|
||||||
|
|
||||||
|
// when
|
||||||
|
int threadsLeft = poolSizeOnceSettled(watchdogs, KEEP_ALIVE.multipliedBy(40));
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(threadsLeft).isZero();
|
||||||
|
} finally {
|
||||||
|
watchdogs.shutdownNow();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("watchdog 스레드가 끝난 뒤의 스트림도 멈춘 read를 read-idle로 끝낸다")
|
||||||
|
void aStreamAfterTheWatchdogThreadEndedStillTimesOut() throws Exception {
|
||||||
|
// given
|
||||||
|
ScheduledThreadPoolExecutor watchdogs = ReadIdleInputStream.newWatchdogs(KEEP_ALIVE);
|
||||||
|
try {
|
||||||
|
try (InputStream first =
|
||||||
|
new ReadIdleInputStream(new DrippingStream(1, GAP), READ_IDLE, watchdogs)) {
|
||||||
|
first.read();
|
||||||
|
}
|
||||||
|
assertThat(poolSizeOnceSettled(watchdogs, KEEP_ALIVE.multipliedBy(40)))
|
||||||
|
.as("the first thread has ended")
|
||||||
|
.isZero();
|
||||||
|
InputStream next = new ReadIdleInputStream(new StalledStream(), READ_IDLE, watchdogs);
|
||||||
|
|
||||||
|
// when
|
||||||
|
Throwable failure = catchThrowable(next::read);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(failure)
|
||||||
|
.isInstanceOf(SocketTimeoutException.class)
|
||||||
|
.hasMessageContaining("read-idle");
|
||||||
|
} finally {
|
||||||
|
watchdogs.shutdownNow();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName(
|
||||||
|
"watchdog 스레드는 자기를 만든 요청 스레드의 inheritable thread-local과 context class loader를 물려받지 않는다")
|
||||||
|
void theWatchdogThreadHoldsNothingOfTheThreadThatStartedIt() throws Exception {
|
||||||
|
// given
|
||||||
|
// The thread is started by whichever request thread schedules the first wake, and now again
|
||||||
|
// after every idle spell. Inheriting from it kept that request's inheritable thread-locals
|
||||||
|
// and its context class loader for the thread's whole life (RR4-03-04).
|
||||||
|
InheritableThreadLocal<String> requestScoped = new InheritableThreadLocal<>();
|
||||||
|
requestScoped.set("request-42");
|
||||||
|
Thread current = Thread.currentThread();
|
||||||
|
ClassLoader requestLoader = current.getContextClassLoader();
|
||||||
|
ScheduledThreadPoolExecutor watchdogs = ReadIdleInputStream.newWatchdogs(KEEP_ALIVE);
|
||||||
|
try (URLClassLoader foreign = new URLClassLoader(new URL[0], null)) {
|
||||||
|
current.setContextClassLoader(foreign);
|
||||||
|
List<Object> seen;
|
||||||
|
try {
|
||||||
|
// when
|
||||||
|
seen =
|
||||||
|
watchdogs
|
||||||
|
.submit(
|
||||||
|
() ->
|
||||||
|
Arrays.<Object>asList(
|
||||||
|
requestScoped.get(), Thread.currentThread().getContextClassLoader()))
|
||||||
|
.get(5, TimeUnit.SECONDS);
|
||||||
|
} finally {
|
||||||
|
current.setContextClassLoader(requestLoader);
|
||||||
|
}
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(seen).containsExactly(null, ReadIdleInputStream.class.getClassLoader());
|
||||||
|
} finally {
|
||||||
|
requestScoped.remove();
|
||||||
|
watchdogs.shutdownNow();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
@DisplayName("호출자가 read 사이에 오래 머문 시간은 read-idle로 세지 않는다")
|
@DisplayName("호출자가 read 사이에 오래 머문 시간은 read-idle로 세지 않는다")
|
||||||
void timeTheCallerSpendsBetweenReadsIsNotIdle() throws Exception {
|
void timeTheCallerSpendsBetweenReadsIsNotIdle() throws Exception {
|
||||||
@@ -160,6 +258,16 @@ class ReadIdleInputStreamTest {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/** The scheduler's thread count once its keep-alive has had {@code atMost} to end them. */
|
||||||
|
private static int poolSizeOnceSettled(ScheduledThreadPoolExecutor watchdogs, Duration atMost)
|
||||||
|
throws InterruptedException {
|
||||||
|
long deadline = System.nanoTime() + atMost.toNanos();
|
||||||
|
while (watchdogs.getPoolSize() > 0 && System.nanoTime() < deadline) {
|
||||||
|
TimeUnit.MILLISECONDS.sleep(10);
|
||||||
|
}
|
||||||
|
return watchdogs.getPoolSize();
|
||||||
|
}
|
||||||
|
|
||||||
private static void awaitQuietly(CountDownLatch latch, Duration atMost) {
|
private static void awaitQuietly(CountDownLatch latch, Duration atMost) {
|
||||||
try {
|
try {
|
||||||
latch.await(atMost.toNanos(), TimeUnit.NANOSECONDS);
|
latch.await(atMost.toNanos(), TimeUnit.NANOSECONDS);
|
||||||
@@ -212,6 +320,12 @@ class ReadIdleInputStreamTest {
|
|||||||
private static final class StalledStream extends InputStream {
|
private static final class StalledStream extends InputStream {
|
||||||
|
|
||||||
private final CountDownLatch closed = new CountDownLatch(1);
|
private final CountDownLatch closed = new CountDownLatch(1);
|
||||||
|
private volatile String closedBy;
|
||||||
|
|
||||||
|
/** The name of the thread that closed this stream first, or {@code null} while open. */
|
||||||
|
String closedBy() {
|
||||||
|
return closedBy;
|
||||||
|
}
|
||||||
|
|
||||||
@Override
|
@Override
|
||||||
public int read() throws IOException {
|
public int read() throws IOException {
|
||||||
@@ -231,6 +345,9 @@ class ReadIdleInputStreamTest {
|
|||||||
|
|
||||||
@Override
|
@Override
|
||||||
public void close() {
|
public void close() {
|
||||||
|
if (closedBy == null) {
|
||||||
|
closedBy = Thread.currentThread().getName();
|
||||||
|
}
|
||||||
closed.countDown();
|
closed.countDown();
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
+34
-5
@@ -1,6 +1,7 @@
|
|||||||
package dev.caskeleton.adapter.outbound.httpclient.profile;
|
package dev.caskeleton.adapter.outbound.httpclient.profile;
|
||||||
|
|
||||||
import static org.assertj.core.api.Assertions.assertThat;
|
import static org.assertj.core.api.Assertions.assertThat;
|
||||||
|
import static org.assertj.core.api.Assertions.catchThrowable;
|
||||||
|
|
||||||
import dev.caskeleton.adapter.outbound.httpclient.testkit.ClientProfiles;
|
import dev.caskeleton.adapter.outbound.httpclient.testkit.ClientProfiles;
|
||||||
import java.time.Duration;
|
import java.time.Duration;
|
||||||
@@ -55,10 +56,38 @@ class ClientRuntimeRegistryTest {
|
|||||||
|
|
||||||
assertThat(first.state()).isEqualTo(ClientRuntimeState.CLOSED);
|
assertThat(first.state()).isEqualTo(ClientRuntimeState.CLOSED);
|
||||||
assertThat(second.state()).isEqualTo(ClientRuntimeState.CLOSED);
|
assertThat(second.state()).isEqualTo(ClientRuntimeState.CLOSED);
|
||||||
Set<String> threadNames =
|
assertThat(liveDrainThreads()).isEmpty();
|
||||||
Thread.getAllStackTraces().keySet().stream()
|
}
|
||||||
.map(Thread::getName)
|
|
||||||
.collect(Collectors.toSet());
|
@Test
|
||||||
assertThat(threadNames).noneMatch(name -> name.startsWith("httpclient-runtime-drain"));
|
void aRuntimeThatRefusesToCloseStillLeavesNoDrainThread() {
|
||||||
|
// given
|
||||||
|
ClientRuntime first = running(1);
|
||||||
|
ClientRuntime refusing =
|
||||||
|
new ClientRuntime(
|
||||||
|
ClientProfiles.builder("payment").build(),
|
||||||
|
new RuntimeGeneration(2),
|
||||||
|
() -> {
|
||||||
|
throw new IllegalStateException("pool refused to close");
|
||||||
|
});
|
||||||
|
ClientRuntimeRegistry registry = new ClientRuntimeRegistry(Map.of(first.name(), first));
|
||||||
|
ClientRuntimeLease lease = registry.acquire(first.name());
|
||||||
|
registry.swap(first.name(), refusing, Duration.ofSeconds(30));
|
||||||
|
|
||||||
|
// when
|
||||||
|
Throwable failure = catchThrowable(registry::close);
|
||||||
|
|
||||||
|
// then
|
||||||
|
lease.close();
|
||||||
|
assertThat(failure).hasMessage("pool refused to close");
|
||||||
|
assertThat(liveDrainThreads()).isEmpty();
|
||||||
|
}
|
||||||
|
|
||||||
|
private static Set<String> liveDrainThreads() {
|
||||||
|
return Thread.getAllStackTraces().keySet().stream()
|
||||||
|
.filter(Thread::isAlive)
|
||||||
|
.map(Thread::getName)
|
||||||
|
.filter(name -> name.startsWith("httpclient-runtime-drain"))
|
||||||
|
.collect(Collectors.toSet());
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -235,9 +235,16 @@ failure translation contract 다. 여기서는 SPI 구조와 fallback 근거만
|
|||||||
실제로 돌려 이 경우를 본다. reaper 는 provider 가 `postgresql` 일 때만 돈다.
|
실제로 돌려 이 경우를 본다. reaper 는 provider 가 `postgresql` 일 때만 돈다.
|
||||||
- **lease 가 지난 실행**: lease 가 지난 `EXECUTING` 행은 넘겨받지 않고 `RecoveryRequired` 로 답하며,
|
- **lease 가 지난 실행**: lease 가 지난 `EXECUTING` 행은 넘겨받지 않고 `RecoveryRequired` 로 답하며,
|
||||||
행은 바꾸지 않는다. 주인이 늦게 complete·markFailed 하면 그대로 기록되고, 다음 claim 은 그 결과를
|
행은 바꾸지 않는다. 주인이 늦게 complete·markFailed 하면 그대로 기록되고, 다음 claim 은 그 결과를
|
||||||
재생하거나 재시도한다. renew 는 이미 끝난 lease 를 늘리지 않는다. inspect 는 남의 lease 지난 실행을
|
재생하거나 재시도한다. renew 는 이미 끝난 lease 를 늘리지 않고, lease 가 지난 `CLAIMED` 는 주인도 시작할
|
||||||
|
수 없다 — 둘 다 `LEASE_EXPIRED`(전에는 `NOT_OWNER`, 재리뷰 RR5-01-02). inspect 는 남의 lease 지난 실행을
|
||||||
`ABANDONED` 로 보고한다. Redis store 도 같다(`IdempotencyStoreContract`, RR-01-11, 2026-11-04 소유자
|
`ABANDONED` 로 보고한다. Redis store 도 같다(`IdempotencyStoreContract`, RR-01-11, 2026-11-04 소유자
|
||||||
결정 — 전에는 행을 `ABANDONED`·`EXPIRED_EXECUTION` 으로 바꿔 늦은 결과를 버렸다).
|
결정 — 전에는 행을 `ABANDONED`·`EXPIRED_EXECUTION` 으로 바꿔 늦은 결과를 버렸다).
|
||||||
|
- **한 트랜잭션 안의 모양**: executor 를 유스케이스의 쓰기 트랜잭션 하나 안에서 부르면(템플릿의 모양)
|
||||||
|
claim 행은 그 트랜잭션이 끝날 때까지 커밋되지 않는다. 그래서 위의 "lease 가 지난 실행"을 다른 요청이
|
||||||
|
보는 일이 없다: 같은 키 요청은 `on conflict` 에서 기다렸다가 커밋이면 재생, 롤백이면 새 실행을 받는다.
|
||||||
|
롤백(작업 예외, 쓰기 트랜잭션 제한 30s)은 executor 가 남긴 실패 기록도 지운다. 이 store 가 막는 중복은
|
||||||
|
같은 트랜잭션 안의 DB 효과이고, 트랜잭션 밖 효과는 다음 요청에서 다시 일어날 수 있다
|
||||||
|
(`PostgreSqlIdempotencyIntegrationTest`, 재리뷰 RR5-01-05, `docs/web/http-contract.md` §2).
|
||||||
|
|
||||||
## outbox — `JpaOutboxStore` 외
|
## outbox — `JpaOutboxStore` 외
|
||||||
|
|
||||||
@@ -415,7 +422,8 @@ machine-readable SSOT다(개수는 registry가 소유한다). `selected` base ca
|
|||||||
`PostgreSqlIdempotencyStore`는 row lock을 얻은 뒤 `clock_timestamp()`를 평가한다.
|
`PostgreSqlIdempotencyStore`는 row lock을 얻은 뒤 `clock_timestamp()`를 평가한다.
|
||||||
claim takeover와 start/renew/complete/fail/release는 scope/state/owner/attempt/claim operation/
|
claim takeover와 start/renew/complete/fail/release는 scope/state/owner/attempt/claim operation/
|
||||||
state revision을 SQL predicate로 다시 검증한다. expired `CLAIMED`만 takeover하며 expired
|
state revision을 SQL predicate로 다시 검증한다. expired `CLAIMED`만 takeover하며 expired
|
||||||
`EXECUTING`은 `ABANDONED`로 닫고 reconciliation을 요구한다. raw client key는 저장하지 않고
|
`EXECUTING`은 행을 바꾸지 않고 reconciliation(`RecoveryRequired`)을 요구한다(2026-11-04 소유자 결정 —
|
||||||
|
이 문단은 그 전의 `ABANDONED`로 닫던 동작을 적고 있었다). raw client key는 저장하지 않고
|
||||||
versioned HMAC scope digest만 쓴다.
|
versioned HMAC scope digest만 쓴다.
|
||||||
|
|
||||||
Redis store·in-memory fake와 같은 계약(`IdempotencyStoreContract`)을 실 PostgreSQL에서 통과한다
|
Redis store·in-memory fake와 같은 계약(`IdempotencyStoreContract`)을 실 PostgreSQL에서 통과한다
|
||||||
|
|||||||
+4
-1
@@ -12,7 +12,10 @@ import org.springframework.jdbc.core.JdbcOperations;
|
|||||||
* revision — in its {@code where} clause, so the update count <em>is</em> the answer: one row means
|
* revision — in its {@code where} clause, so the update count <em>is</em> the answer: one row means
|
||||||
* this owner was still the owner at this revision, zero means something else moved the record and
|
* this owner was still the owner at this revision, zero means something else moved the record and
|
||||||
* the caller must not treat its own view as current. Reading the row and then updating on the scope
|
* the caller must not treat its own view as current. Reading the row and then updating on the scope
|
||||||
* alone would let a worker whose lease expired overwrite the state of the one that took over.
|
* alone would let a worker whose lease expired overwrite the state of the one that took over. Start
|
||||||
|
* and renew also require the lease to be running; the store has already compared the locked row
|
||||||
|
* with the owner tuple before it runs them, so for those two a zero is the lease that ran out
|
||||||
|
* ({@code LEASE_EXPIRED}).
|
||||||
*
|
*
|
||||||
* <p>Collected here rather than in the store because they are one family: same guard, same
|
* <p>Collected here rather than in the store because they are one family: same guard, same
|
||||||
* interpretation of the count, same reason a caller may not skip the guard. The store decides which
|
* interpretation of the count, same reason a caller may not skip the guard. The store decides which
|
||||||
|
|||||||
+9
-2
@@ -194,9 +194,13 @@ public final class PostgreSqlIdempotencyStore implements IdempotencyStorePort {
|
|||||||
if (mismatch != null) {
|
if (mismatch != null) {
|
||||||
return startResult(mismatch, null);
|
return startResult(mismatch, null);
|
||||||
}
|
}
|
||||||
|
// The row is locked and the owner, revision and state already match it, so the one condition
|
||||||
|
// left in START_SQL is the lease: a claim whose lease ran out is not started — nothing runs,
|
||||||
|
// and the next claim takes it over. It used to be answered NOT_OWNER, which says the record
|
||||||
|
// went to somebody else (re-review 2026-11-04 README 15, RR5-01-02).
|
||||||
int updated = transitions.start(owner, operationId.value(), startDigest);
|
int updated = transitions.start(owner, operationId.value(), startDigest);
|
||||||
if (updated != 1) {
|
if (updated != 1) {
|
||||||
return startResult(IdempotencyStartOutcome.NOT_OWNER, null);
|
return startResult(IdempotencyStartOutcome.LEASE_EXPIRED, null);
|
||||||
}
|
}
|
||||||
return startResult(
|
return startResult(
|
||||||
IdempotencyStartOutcome.STARTED, owner.withStateRevision(owner.stateRevision() + 1));
|
IdempotencyStartOutcome.STARTED, owner.withStateRevision(owner.stateRevision() + 1));
|
||||||
@@ -233,9 +237,12 @@ public final class PostgreSqlIdempotencyStore implements IdempotencyStorePort {
|
|||||||
if (mismatch != null) {
|
if (mismatch != null) {
|
||||||
return renewResult(mismatch, null);
|
return renewResult(mismatch, null);
|
||||||
}
|
}
|
||||||
|
// As for the start: with the row locked and matched, a renewal that updates nothing found the
|
||||||
|
// lease already ended. The holder still owns the row and still completes or fails it, so this
|
||||||
|
// is LEASE_EXPIRED, not NOT_OWNER (RR5-01-02).
|
||||||
int updated = transitions.renew(owner, processingLeaseTtl, operationId.value(), renewDigest);
|
int updated = transitions.renew(owner, processingLeaseTtl, operationId.value(), renewDigest);
|
||||||
if (updated != 1) {
|
if (updated != 1) {
|
||||||
return renewResult(IdempotencyRenewOutcome.NOT_OWNER, null);
|
return renewResult(IdempotencyRenewOutcome.LEASE_EXPIRED, null);
|
||||||
}
|
}
|
||||||
return renewResult(
|
return renewResult(
|
||||||
IdempotencyRenewOutcome.RENEWED, owner.withStateRevision(owner.stateRevision() + 1));
|
IdempotencyRenewOutcome.RENEWED, owner.withStateRevision(owner.stateRevision() + 1));
|
||||||
|
|||||||
+127
@@ -1,6 +1,7 @@
|
|||||||
package dev.caskeleton.adapter.outbound.persistence.readiness;
|
package dev.caskeleton.adapter.outbound.persistence.readiness;
|
||||||
|
|
||||||
import static org.assertj.core.api.Assertions.assertThat;
|
import static org.assertj.core.api.Assertions.assertThat;
|
||||||
|
import static org.assertj.core.api.Assertions.catchThrowable;
|
||||||
|
|
||||||
import dev.caskeleton.adapter.outbound.persistence.idempotency.postgresql.PostgreSqlIdempotencyStore;
|
import dev.caskeleton.adapter.outbound.persistence.idempotency.postgresql.PostgreSqlIdempotencyStore;
|
||||||
import dev.caskeleton.application.idempotency.IdempotencyClaimAttempt;
|
import dev.caskeleton.application.idempotency.IdempotencyClaimAttempt;
|
||||||
@@ -23,6 +24,7 @@ import java.time.Duration;
|
|||||||
import java.util.concurrent.CountDownLatch;
|
import java.util.concurrent.CountDownLatch;
|
||||||
import java.util.concurrent.Executors;
|
import java.util.concurrent.Executors;
|
||||||
import java.util.concurrent.Future;
|
import java.util.concurrent.Future;
|
||||||
|
import java.util.concurrent.TimeUnit;
|
||||||
import org.flywaydb.core.Flyway;
|
import org.flywaydb.core.Flyway;
|
||||||
import org.junit.jupiter.api.AfterAll;
|
import org.junit.jupiter.api.AfterAll;
|
||||||
import org.junit.jupiter.api.BeforeAll;
|
import org.junit.jupiter.api.BeforeAll;
|
||||||
@@ -254,6 +256,131 @@ class PostgreSqlIdempotencyIntegrationTest {
|
|||||||
.isEqualTo(1);
|
.isEqualTo(1);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The shape the template calls the store in — the executor inside the use case's one write
|
||||||
|
* transaction — never shows another request an execution past its lease: the claim row is not
|
||||||
|
* committed until the first request ends, so a same-key request waits on it instead of reading
|
||||||
|
* it. What decision 2026-11-04 describes (500 now, the late result replayed later) is the Redis
|
||||||
|
* store's; here the waiting request gets the replay directly (re-review 2026-11-04 RR5-01-05).
|
||||||
|
*/
|
||||||
|
@Test
|
||||||
|
void aSameKeyClaimWaitsForTheFirstTransactionPastItsLeaseAndReplaysTheResult() throws Exception {
|
||||||
|
// given
|
||||||
|
Duration lease = Duration.ofMillis(200);
|
||||||
|
CountDownLatch firstStarted = new CountDownLatch(1);
|
||||||
|
CountDownLatch allowFirstToFinish = new CountDownLatch(1);
|
||||||
|
IdempotencyClaimRequest firstRequest =
|
||||||
|
request(store.newClaimAttempt(new OperationId("claim-slow")), lease);
|
||||||
|
IdempotencyClaimRequest secondRequest =
|
||||||
|
request(store.newClaimAttempt(new OperationId("claim-resent")), lease);
|
||||||
|
|
||||||
|
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
|
||||||
|
Future<Void> first =
|
||||||
|
executor.submit(
|
||||||
|
() -> {
|
||||||
|
transactions.executeWithoutResult(
|
||||||
|
ignored -> {
|
||||||
|
IdempotencyOwner owner =
|
||||||
|
((IdempotencyClaimOutcome.Acquired) store.claim(firstRequest)).owner();
|
||||||
|
IdempotencyOwner executing =
|
||||||
|
store
|
||||||
|
.markExecutionStarted(owner, new OperationId("start-slow"))
|
||||||
|
.owner()
|
||||||
|
.orElseThrow();
|
||||||
|
firstStarted.countDown();
|
||||||
|
await(allowFirstToFinish);
|
||||||
|
store.complete(
|
||||||
|
executing,
|
||||||
|
new StoredResponse("slow-but-done"),
|
||||||
|
Duration.ofHours(1),
|
||||||
|
new OperationId("complete-slow"));
|
||||||
|
});
|
||||||
|
return null;
|
||||||
|
});
|
||||||
|
firstStarted.await();
|
||||||
|
Future<IdempotencyClaimOutcome> second =
|
||||||
|
executor.submit(() -> transactions.execute(ignored -> store.claim(secondRequest)));
|
||||||
|
// Long past the 200 ms lease, and the resend is still waiting on the uncommitted claim row.
|
||||||
|
TimeUnit.MILLISECONDS.sleep(600);
|
||||||
|
assertThat(second.isDone()).as("the resend waits instead of answering").isFalse();
|
||||||
|
allowFirstToFinish.countDown();
|
||||||
|
first.get();
|
||||||
|
|
||||||
|
// when
|
||||||
|
IdempotencyClaimOutcome resent = second.get();
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(resent)
|
||||||
|
.isInstanceOfSatisfying(
|
||||||
|
IdempotencyClaimOutcome.CompletedReplay.class,
|
||||||
|
replay -> assertThat(replay.response().payload()).isEqualTo("slow-but-done"));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The other side of the same shape: a first request whose transaction rolls back — the action
|
||||||
|
* threw, or the write transaction outlived its limit (30s, the default lease too) — takes its
|
||||||
|
* claim row with it, and with it the failure the executor recorded before rethrowing, even an
|
||||||
|
* unknown effect. The next same-key request runs the work afresh. Database effects rolled back
|
||||||
|
* with it; anything the action did outside the transaction may then happen twice (re-review
|
||||||
|
* 2026-11-04 RR5-01-05).
|
||||||
|
*/
|
||||||
|
@Test
|
||||||
|
void aSameKeyClaimAfterTheFirstTransactionRolledBackItsAbandonedRecordRunsAfresh()
|
||||||
|
throws Exception {
|
||||||
|
// given
|
||||||
|
CountDownLatch firstStarted = new CountDownLatch(1);
|
||||||
|
CountDownLatch allowFirstToFail = new CountDownLatch(1);
|
||||||
|
IdempotencyClaimRequest firstRequest =
|
||||||
|
request(store.newClaimAttempt(new OperationId("claim-fails")), Duration.ofSeconds(5));
|
||||||
|
IdempotencyClaimRequest secondRequest =
|
||||||
|
request(store.newClaimAttempt(new OperationId("claim-after")), Duration.ofSeconds(5));
|
||||||
|
|
||||||
|
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
|
||||||
|
Future<Void> first =
|
||||||
|
executor.submit(
|
||||||
|
() -> {
|
||||||
|
transactions.executeWithoutResult(
|
||||||
|
ignored -> {
|
||||||
|
IdempotencyOwner owner =
|
||||||
|
((IdempotencyClaimOutcome.Acquired) store.claim(firstRequest)).owner();
|
||||||
|
IdempotencyOwner executing =
|
||||||
|
store
|
||||||
|
.markExecutionStarted(owner, new OperationId("start-fails"))
|
||||||
|
.owner()
|
||||||
|
.orElseThrow();
|
||||||
|
firstStarted.countDown();
|
||||||
|
await(allowFirstToFail);
|
||||||
|
// What the executor does with an action that threw: record the unknown
|
||||||
|
// effect, then rethrow — which rolls the record back too.
|
||||||
|
store.markFailed(
|
||||||
|
executing,
|
||||||
|
IdempotencyFailureDisposition.EFFECT_UNKNOWN_ABANDONED,
|
||||||
|
Duration.ofHours(1),
|
||||||
|
new OperationId("fail-unknown"));
|
||||||
|
throw new IllegalStateException("the action failed");
|
||||||
|
});
|
||||||
|
return null;
|
||||||
|
});
|
||||||
|
firstStarted.await();
|
||||||
|
Future<IdempotencyClaimOutcome> second =
|
||||||
|
executor.submit(() -> transactions.execute(ignored -> store.claim(secondRequest)));
|
||||||
|
allowFirstToFail.countDown();
|
||||||
|
assertThat(catchThrowable(first::get))
|
||||||
|
.as("the first request's transaction rolled back")
|
||||||
|
.hasRootCauseInstanceOf(IllegalStateException.class);
|
||||||
|
|
||||||
|
// when
|
||||||
|
IdempotencyClaimOutcome resent = second.get();
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(resent)
|
||||||
|
.isInstanceOfSatisfying(
|
||||||
|
IdempotencyClaimOutcome.Acquired.class,
|
||||||
|
acquired -> assertThat(acquired.owner().attempt()).isEqualTo(1));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
void aRetriedFailureWithTheSameArgumentsIsConfirmedRatherThanAppliedTwice() {
|
void aRetriedFailureWithTheSameArgumentsIsConfirmedRatherThanAppliedTwice() {
|
||||||
IdempotencyOwner executing = claimAndStart("claim-fail-replay", "start-fail-replay");
|
IdempotencyOwner executing = claimAndStart("claim-fail-replay", "start-fail-replay");
|
||||||
|
|||||||
+140
@@ -4,6 +4,9 @@ import static org.assertj.core.api.Assertions.assertThat;
|
|||||||
import static org.assertj.core.api.Assertions.catchThrowable;
|
import static org.assertj.core.api.Assertions.catchThrowable;
|
||||||
|
|
||||||
import com.zaxxer.hikari.HikariDataSource;
|
import com.zaxxer.hikari.HikariDataSource;
|
||||||
|
import dev.caskeleton.adapter.outbound.persistence.testkit.migration.LockWaitMigrationInspector;
|
||||||
|
import java.nio.file.Files;
|
||||||
|
import java.nio.file.Path;
|
||||||
import java.sql.Connection;
|
import java.sql.Connection;
|
||||||
import java.sql.SQLException;
|
import java.sql.SQLException;
|
||||||
import java.sql.Statement;
|
import java.sql.Statement;
|
||||||
@@ -19,8 +22,11 @@ import org.flywaydb.core.Flyway;
|
|||||||
import org.junit.jupiter.api.AfterAll;
|
import org.junit.jupiter.api.AfterAll;
|
||||||
import org.junit.jupiter.api.BeforeAll;
|
import org.junit.jupiter.api.BeforeAll;
|
||||||
import org.junit.jupiter.api.DisplayName;
|
import org.junit.jupiter.api.DisplayName;
|
||||||
|
import org.junit.jupiter.api.Test;
|
||||||
|
import org.junit.jupiter.api.io.TempDir;
|
||||||
import org.junit.jupiter.params.ParameterizedTest;
|
import org.junit.jupiter.params.ParameterizedTest;
|
||||||
import org.junit.jupiter.params.provider.CsvSource;
|
import org.junit.jupiter.params.provider.CsvSource;
|
||||||
|
import org.junit.jupiter.params.provider.ValueSource;
|
||||||
import org.springframework.jdbc.core.JdbcTemplate;
|
import org.springframework.jdbc.core.JdbcTemplate;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
@@ -35,12 +41,22 @@ import org.springframework.jdbc.core.JdbcTemplate;
|
|||||||
* migration ends up applied. Bounded, it fails with {@code lock_not_available} long before that,
|
* migration ends up applied. Bounded, it fails with {@code lock_not_available} long before that,
|
||||||
* Flyway rolls it back whole, and the history still ends one version below. V21 has the same case
|
* Flyway rolls it back whole, and the history still ends one version below. V21 has the same case
|
||||||
* against a writer in {@code PostgreSqlOutboxOrderKeyRunbookIntegrationTest}.
|
* against a writer in {@code PostgreSqlOutboxOrderKeyRunbookIntegrationTest}.
|
||||||
|
*
|
||||||
|
* <p>The text check ({@link LockWaitMigrationInspector}) repeats which statements Flyway runs
|
||||||
|
* outside a transaction, where {@code SET LOCAL} bounds nothing. Two cases here hold that copy to
|
||||||
|
* Flyway itself on this server: the statements it names are exactly those Flyway refuses next to a
|
||||||
|
* {@code SET LOCAL} (default {@code mixed=false}), and a {@code VACUUM FULL} that Flyway runs
|
||||||
|
* anyway ({@code mixed=true}) waits out the reader despite its {@code SET LOCAL} (re-review
|
||||||
|
* 2026-11-03 round 4, RR4-02-01).
|
||||||
*/
|
*/
|
||||||
class PostgreSqlMigrationLockWaitIntegrationTest {
|
class PostgreSqlMigrationLockWaitIntegrationTest {
|
||||||
|
|
||||||
private static final String LOCK_NOT_AVAILABLE = "55P03";
|
private static final String LOCK_NOT_AVAILABLE = "55P03";
|
||||||
|
private static final String ACTIVE_SQL_TRANSACTION = "25001";
|
||||||
private static final Duration READER_STAYS = Duration.ofSeconds(15);
|
private static final Duration READER_STAYS = Duration.ofSeconds(15);
|
||||||
private static final Duration GIVES_UP_WITHIN = Duration.ofSeconds(10);
|
private static final Duration GIVES_UP_WITHIN = Duration.ofSeconds(10);
|
||||||
|
private static final String FLYWAY_REFUSES_A_MIXED_MIGRATION =
|
||||||
|
"Detected both transactional and non-transactional statements";
|
||||||
|
|
||||||
private static PostgreSqlReadinessSupport postgres;
|
private static PostgreSqlReadinessSupport postgres;
|
||||||
|
|
||||||
@@ -110,6 +126,130 @@ class PostgreSqlMigrationLockWaitIntegrationTest {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ParameterizedTest
|
||||||
|
@ValueSource(
|
||||||
|
strings = {
|
||||||
|
"VACUUM FULL probe",
|
||||||
|
"vacuum (full) probe",
|
||||||
|
"VACUUM ANALYZE probe",
|
||||||
|
"CREATE INDEX CONCURRENTLY ix_probe ON probe (id)",
|
||||||
|
"CREATE UNIQUE INDEX CONCURRENTLY ux_probe ON probe (id)",
|
||||||
|
"DROP INDEX CONCURRENTLY IF EXISTS ix_probe",
|
||||||
|
"REINDEX SCHEMA public",
|
||||||
|
"REINDEX (VERBOSE) DATABASE probe",
|
||||||
|
"CREATE DATABASE probe_other",
|
||||||
|
"DROP DATABASE IF EXISTS probe_other",
|
||||||
|
"ALTER SYSTEM SET work_mem = '8MB'",
|
||||||
|
"DISCARD ALL",
|
||||||
|
"REINDEX TABLE CONCURRENTLY probe",
|
||||||
|
"REINDEX (CONCURRENTLY) TABLE probe",
|
||||||
|
"REFRESH MATERIALIZED VIEW CONCURRENTLY probe_view",
|
||||||
|
"ALTER TYPE probe_status ADD VALUE 'b'",
|
||||||
|
"ANALYZE probe",
|
||||||
|
"ALTER TABLE probe ADD COLUMN c INT",
|
||||||
|
"CREATE INDEX ix_probe_plain ON probe (id)",
|
||||||
|
"COMMENT ON TABLE probe IS 'vacuum full'",
|
||||||
|
"DO $$ BEGIN PERFORM 1; END $$"
|
||||||
|
})
|
||||||
|
@DisplayName("검사기가 트랜잭션 밖이라고 보는 문장은 Flyway가 SET LOCAL 옆에서 거부하는 문장과 같다")
|
||||||
|
void theInspectorNamesExactlyTheStatementsFlywayRunsOutsideATransaction(
|
||||||
|
String statement, @TempDir Path stream) throws Exception {
|
||||||
|
try (HikariDataSource database = postgres.createDatabase(databaseName())) {
|
||||||
|
// given
|
||||||
|
new JdbcTemplate(database)
|
||||||
|
.execute(
|
||||||
|
"CREATE TABLE probe (id INT PRIMARY KEY);"
|
||||||
|
+ " CREATE MATERIALIZED VIEW probe_view AS SELECT id FROM probe;"
|
||||||
|
+ " CREATE UNIQUE INDEX ux_probe_view ON probe_view (id);"
|
||||||
|
+ " CREATE TYPE probe_status AS ENUM ('a')");
|
||||||
|
String sql = "SET LOCAL lock_timeout = '5s';\n" + statement + ";\n";
|
||||||
|
Files.writeString(stream.resolve("V1__probe.sql"), sql);
|
||||||
|
Flyway flyway =
|
||||||
|
Flyway.configure()
|
||||||
|
.dataSource(database)
|
||||||
|
.locations("filesystem:" + stream.toAbsolutePath())
|
||||||
|
.baselineOnMigrate(true)
|
||||||
|
.baselineVersion("0")
|
||||||
|
.load();
|
||||||
|
|
||||||
|
// when
|
||||||
|
Throwable thrown = catchThrowable(flyway::migrate);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(
|
||||||
|
new LockWaitMigrationInspector()
|
||||||
|
.statementsFlywayRunsOutsideATransaction(sql)
|
||||||
|
.isEmpty())
|
||||||
|
.as(
|
||||||
|
"Flyway %s %s outside a transaction (%s)",
|
||||||
|
refusedAsMixed(thrown) ? "runs" : "does not run", statement, thrown)
|
||||||
|
.isEqualTo(!refusedAsMixed(thrown));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName(
|
||||||
|
"mixed=true로 Flyway가 트랜잭션 밖에서 돌린 VACUUM FULL은 SET LOCAL lock_timeout이 있어도 읽는 트랜잭션이 끝날 때까지 기다린다")
|
||||||
|
void aVacuumFullFlywayRunsOutsideATransactionWaitsOutTheReaderDespiteSetLocal(
|
||||||
|
@TempDir Path stream) throws Exception {
|
||||||
|
try (HikariDataSource database = postgres.createDatabase(databaseName())) {
|
||||||
|
// given
|
||||||
|
new JdbcTemplate(database).execute("CREATE TABLE probe (id INT PRIMARY KEY)");
|
||||||
|
Files.writeString(
|
||||||
|
stream.resolve("V1__vacuum.sql"), "SET LOCAL lock_timeout = '1s';\nVACUUM FULL probe;\n");
|
||||||
|
Flyway mixed =
|
||||||
|
Flyway.configure()
|
||||||
|
.dataSource(database)
|
||||||
|
.locations("filesystem:" + stream.toAbsolutePath())
|
||||||
|
.baselineOnMigrate(true)
|
||||||
|
.baselineVersion("0")
|
||||||
|
.mixed(true)
|
||||||
|
.load();
|
||||||
|
|
||||||
|
// when
|
||||||
|
Attempt attempt = whileAReaderHolds(database, "probe", mixed::migrate);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(List.of(String.valueOf(attempt.thrown()), attempt.tookLessThan(GIVES_UP_WITHIN)))
|
||||||
|
.containsExactly("null", false);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName(
|
||||||
|
"Flyway는 REINDEX TABLE CONCURRENTLY를 트랜잭션 안에서 돌려 PostgreSQL이 거부하므로 executeInTransaction=false가 필요하다")
|
||||||
|
void flywayRunsReindexConcurrentlyInATransactionWherePostgresqlRefusesIt(@TempDir Path stream)
|
||||||
|
throws Exception {
|
||||||
|
try (HikariDataSource database = postgres.createDatabase(databaseName())) {
|
||||||
|
// given
|
||||||
|
new JdbcTemplate(database).execute("CREATE TABLE probe (id INT PRIMARY KEY)");
|
||||||
|
Files.writeString(stream.resolve("V1__reindex.sql"), "REINDEX TABLE CONCURRENTLY probe;\n");
|
||||||
|
Flyway flyway =
|
||||||
|
Flyway.configure()
|
||||||
|
.dataSource(database)
|
||||||
|
.locations("filesystem:" + stream.toAbsolutePath())
|
||||||
|
.baselineOnMigrate(true)
|
||||||
|
.baselineVersion("0")
|
||||||
|
.load();
|
||||||
|
|
||||||
|
// when
|
||||||
|
Throwable thrown = catchThrowable(flyway::migrate);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(new Attempt(thrown, Duration.ZERO).sqlState()).isEqualTo(ACTIVE_SQL_TRANSACTION);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Whether Flyway refused the migration for mixing statements it runs in and out of one. */
|
||||||
|
private static boolean refusedAsMixed(Throwable thrown) {
|
||||||
|
for (Throwable cause = thrown; cause != null; cause = cause.getCause()) {
|
||||||
|
if (String.valueOf(cause.getMessage()).contains(FLYWAY_REFUSES_A_MIXED_MIGRATION)) {
|
||||||
|
return true;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Runs the migration while another connection holds an open transaction that has read the table,
|
* Runs the migration while another connection holds an open transaction that has read the table,
|
||||||
* and that transaction ends on its own after {@link #READER_STAYS}.
|
* and that transaction ends on its own after {@link #READER_STAYS}.
|
||||||
|
|||||||
+130
-2
@@ -12,6 +12,7 @@ import org.junit.jupiter.api.DisplayName;
|
|||||||
import org.junit.jupiter.api.Test;
|
import org.junit.jupiter.api.Test;
|
||||||
import org.junit.jupiter.api.io.TempDir;
|
import org.junit.jupiter.api.io.TempDir;
|
||||||
import org.junit.jupiter.params.ParameterizedTest;
|
import org.junit.jupiter.params.ParameterizedTest;
|
||||||
|
import org.junit.jupiter.params.provider.CsvSource;
|
||||||
import org.junit.jupiter.params.provider.ValueSource;
|
import org.junit.jupiter.params.provider.ValueSource;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
@@ -48,7 +49,9 @@ class LockWaitMigrationInspectorTest {
|
|||||||
"REFRESH MATERIALIZED VIEW outbox_summary;",
|
"REFRESH MATERIALIZED VIEW outbox_summary;",
|
||||||
"CLUSTER outbox_event USING ix_outbox_event_status;",
|
"CLUSTER outbox_event USING ix_outbox_event_status;",
|
||||||
"VACUUM FULL outbox_event;",
|
"VACUUM FULL outbox_event;",
|
||||||
"CREATE TABLE IF NOT EXISTS ledger (id BIGINT);\nALTER TABLE ledger ADD c INT;"
|
"CREATE TABLE IF NOT EXISTS ledger (id BIGINT);\nALTER TABLE ledger ADD c INT;",
|
||||||
|
"REINDEX (CONCURRENTLY false) TABLE outbox_event;",
|
||||||
|
"REINDEX (VERBOSE) TABLE outbox_event;"
|
||||||
})
|
})
|
||||||
@DisplayName("이미 있는 테이블에 잠금을 거는 문장 앞에 SET LOCAL lock_timeout이 없으면 거부된다")
|
@DisplayName("이미 있는 테이블에 잠금을 거는 문장 앞에 SET LOCAL lock_timeout이 없으면 거부된다")
|
||||||
void aLockOnAnExistingTableWithoutABoundBeforeItIsRefused(String sql) {
|
void aLockOnAnExistingTableWithoutABoundBeforeItIsRefused(String sql) {
|
||||||
@@ -80,7 +83,11 @@ class LockWaitMigrationInspectorTest {
|
|||||||
"SET LOCAL lock_timeout TO 5000;\nDROP TRIGGER trg_outbox ON outbox_event;",
|
"SET LOCAL lock_timeout TO 5000;\nDROP TRIGGER trg_outbox ON outbox_event;",
|
||||||
"-- ALTER TABLE outbox_event ADD COLUMN c INT;\n/* DELETE FROM outbox_event; */\n"
|
"-- ALTER TABLE outbox_event ADD COLUMN c INT;\n/* DELETE FROM outbox_event; */\n"
|
||||||
+ "COMMENT ON TABLE outbox_event IS 'update outbox_event set status';",
|
+ "COMMENT ON TABLE outbox_event IS 'update outbox_event set status';",
|
||||||
"CREATE TABLE poster_copy AS SELECT * FROM poster;"
|
"CREATE TABLE poster_copy AS SELECT * FROM poster;",
|
||||||
|
"REINDEX (CONCURRENTLY) TABLE outbox_event;",
|
||||||
|
"REINDEX (VERBOSE, CONCURRENTLY) INDEX ux_outbox_event_aggregate_order;",
|
||||||
|
"GRANT SELECT, REFERENCES ON TABLE outbox_event TO reader;",
|
||||||
|
"REVOKE REFERENCES ON outbox_event FROM reader;"
|
||||||
})
|
})
|
||||||
@DisplayName("잠금 대기에 상한을 두었거나 잠글 기존 테이블이 없으면 통과한다")
|
@DisplayName("잠금 대기에 상한을 두었거나 잠글 기존 테이블이 없으면 통과한다")
|
||||||
void aBoundedOrLockFreeMigrationPasses(String sql) {
|
void aBoundedOrLockFreeMigrationPasses(String sql) {
|
||||||
@@ -168,4 +175,125 @@ class LockWaitMigrationInspectorTest {
|
|||||||
.hasMessageContaining("delete from notification_suppression")
|
.hasMessageContaining("delete from notification_suppression")
|
||||||
.hasMessageContaining("alter table notification_suppression");
|
.hasMessageContaining("alter table notification_suppression");
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ParameterizedTest
|
||||||
|
@ValueSource(
|
||||||
|
strings = {
|
||||||
|
"SET LOCAL lock_timeout = '5s';\nALTER TABLE outbox_event ADD COLUMN c INT;\n"
|
||||||
|
+ "CREATE INDEX CONCURRENTLY ix_outbox_c ON outbox_event (c);",
|
||||||
|
"SET LOCAL lock_timeout = '5s';\nALTER TABLE outbox_event ADD COLUMN c INT;\n"
|
||||||
|
+ "VACUUM ANALYZE outbox_event;",
|
||||||
|
"SET LOCAL lock_timeout = '5s';\nDROP INDEX CONCURRENTLY IF EXISTS ix_old;\n"
|
||||||
|
+ "ALTER TABLE outbox_event ADD COLUMN c INT;"
|
||||||
|
})
|
||||||
|
@DisplayName("Flyway가 스스로 트랜잭션 밖에서 돌리는 문장이 있는 마이그레이션의 SET LOCAL lock_timeout은 상한으로 세지 않는다")
|
||||||
|
void setLocalInAMigrationFlywayRunsOutsideATransactionIsNotABound(String sql) {
|
||||||
|
// given
|
||||||
|
MigrationResource migration = new MigrationResource("V99__change.sql", sql);
|
||||||
|
|
||||||
|
// when
|
||||||
|
Throwable refused = catchThrowable(() -> inspector.requireBoundedLockWait(migration));
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(refused)
|
||||||
|
.isInstanceOf(IllegalStateException.class)
|
||||||
|
.hasMessageContaining("alter table outbox_event")
|
||||||
|
.hasMessageContaining("Flyway runs this migration outside a transaction");
|
||||||
|
}
|
||||||
|
|
||||||
|
@ParameterizedTest
|
||||||
|
@ValueSource(
|
||||||
|
strings = {
|
||||||
|
"SET LOCAL lock_timeout = '5s';\nVACUUM FULL outbox_event;",
|
||||||
|
"VACUUM (FULL, ANALYZE) outbox_event;",
|
||||||
|
"SET LOCAL lock_timeout = '5s';\nREINDEX SCHEMA public;"
|
||||||
|
})
|
||||||
|
@DisplayName("트랜잭션 안에서 돌 수 없는 잠금 문장은 마이그레이션에 두지 말라는 이유로 거부된다")
|
||||||
|
void aLockingStatementThatCannotRunInATransactionIsRefusedAsAnOperationsStep(String sql) {
|
||||||
|
// given
|
||||||
|
MigrationResource migration = new MigrationResource("V99__change.sql", sql);
|
||||||
|
|
||||||
|
// when
|
||||||
|
Throwable refused = catchThrowable(() -> inspector.requireBoundedLockWait(migration));
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(refused)
|
||||||
|
.isInstanceOf(IllegalStateException.class)
|
||||||
|
.hasMessageContaining("cannot run in a transaction")
|
||||||
|
.hasMessageContaining("keep it out of migrations");
|
||||||
|
}
|
||||||
|
|
||||||
|
@ParameterizedTest
|
||||||
|
@CsvSource(
|
||||||
|
delimiter = '|',
|
||||||
|
quoteCharacter = '"',
|
||||||
|
value = {
|
||||||
|
"VACUUM FULL outbox_event | vacuum",
|
||||||
|
"vacuum (full) outbox_event | vacuum",
|
||||||
|
"CREATE INDEX CONCURRENTLY ix ON outbox_event (status) | create index concurrently",
|
||||||
|
"CREATE UNIQUE INDEX CONCURRENTLY ux ON outbox_event (id) | create unique index concurrently",
|
||||||
|
"DROP INDEX CONCURRENTLY IF EXISTS ix | drop index concurrently",
|
||||||
|
"REINDEX SCHEMA public | reindex schema",
|
||||||
|
"REINDEX (VERBOSE) DATABASE app | reindex database",
|
||||||
|
"CREATE DATABASE other | create database",
|
||||||
|
"ALTER SYSTEM SET work_mem = '8MB' | alter system",
|
||||||
|
"DISCARD ALL | discard all",
|
||||||
|
"REINDEX TABLE CONCURRENTLY outbox_event | \"\"",
|
||||||
|
"REINDEX (CONCURRENTLY) TABLE outbox_event | \"\"",
|
||||||
|
"REFRESH MATERIALIZED VIEW CONCURRENTLY outbox_summary | \"\"",
|
||||||
|
"ALTER TYPE outbox_status ADD VALUE 'PARKED' | \"\"",
|
||||||
|
"ANALYZE outbox_event | \"\"",
|
||||||
|
"COMMENT ON TABLE outbox_event IS 'vacuum full' | \"\"",
|
||||||
|
"DO $$ BEGIN PERFORM 1; END $$ | \"\""
|
||||||
|
})
|
||||||
|
@DisplayName("Flyway가 PostgreSQL 12 이상에서 트랜잭션 밖으로 빼는 문장만 그렇게 판정한다")
|
||||||
|
void onlyTheStatementsFlywayRunsOutsideATransactionAreNamed(String statement, String expected) {
|
||||||
|
// given
|
||||||
|
String sql = "SET LOCAL lock_timeout = '5s';\n" + statement + ";";
|
||||||
|
|
||||||
|
// when
|
||||||
|
List<String> outside = inspector.statementsFlywayRunsOutsideATransaction(sql);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(outside).isEqualTo(expected.isEmpty() ? List.of() : List.of(expected));
|
||||||
|
}
|
||||||
|
|
||||||
|
@ParameterizedTest
|
||||||
|
@ValueSource(
|
||||||
|
strings = {
|
||||||
|
"executeInTransaction=FALSE\n",
|
||||||
|
"executeInTransaction = false\n",
|
||||||
|
"executeInTransaction: false\n",
|
||||||
|
" executeInTransaction false \n"
|
||||||
|
})
|
||||||
|
@DisplayName("Flyway가 읽는 모든 모양의 executeInTransaction=false 설정에서 SET LOCAL lock_timeout은 상한이 아니다")
|
||||||
|
void everySpellingFlywayReadsAsOutsideATransactionMakesSetLocalNoBound(
|
||||||
|
String configuration, @TempDir Path stream) throws IOException {
|
||||||
|
// given
|
||||||
|
Path script = Files.writeString(stream.resolve("V99__change.sql"), BOUNDED_ALTER);
|
||||||
|
Files.writeString(stream.resolve("V99__change.sql.conf"), configuration);
|
||||||
|
|
||||||
|
// when
|
||||||
|
List<String> unbounded = inspector.unboundedLockingStatements(script);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(unbounded).singleElement(STRING).contains("alter table outbox_event");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("executeInTransaction=true 설정은 Flyway의 판정을 덮어 SET LOCAL lock_timeout을 상한으로 만든다")
|
||||||
|
void executeInTransactionTrueOverridesFlywaysDetection(@TempDir Path stream) throws IOException {
|
||||||
|
// given
|
||||||
|
Path script =
|
||||||
|
Files.writeString(
|
||||||
|
stream.resolve("V99__change.sql"),
|
||||||
|
BOUNDED_ALTER + "\nDROP INDEX CONCURRENTLY IF EXISTS ix_old;");
|
||||||
|
Files.writeString(stream.resolve("V99__change.sql.conf"), "executeInTransaction=true\n");
|
||||||
|
|
||||||
|
// when
|
||||||
|
List<String> unbounded = inspector.unboundedLockingStatements(script);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(unbounded).isEmpty();
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
+49
-1
@@ -1,10 +1,12 @@
|
|||||||
package dev.caskeleton.adapter.outbound.persistence.testkit.migration;
|
package dev.caskeleton.adapter.outbound.persistence.testkit.migration;
|
||||||
|
|
||||||
import static org.assertj.core.api.Assertions.assertThat;
|
import static org.assertj.core.api.Assertions.assertThat;
|
||||||
|
import static org.assertj.core.api.Assertions.catchThrowable;
|
||||||
|
|
||||||
import java.io.IOException;
|
import java.io.IOException;
|
||||||
import java.nio.file.Files;
|
import java.nio.file.Files;
|
||||||
import java.nio.file.Path;
|
import java.nio.file.Path;
|
||||||
|
import java.util.List;
|
||||||
import java.util.Set;
|
import java.util.Set;
|
||||||
import org.junit.jupiter.api.DisplayName;
|
import org.junit.jupiter.api.DisplayName;
|
||||||
import org.junit.jupiter.api.Test;
|
import org.junit.jupiter.api.Test;
|
||||||
@@ -13,7 +15,8 @@ import org.junit.jupiter.api.io.TempDir;
|
|||||||
/**
|
/**
|
||||||
* One definition of a versioned migration for every check that walks a tree (re-review 2026-11-03
|
* One definition of a versioned migration for every check that walks a tree (re-review 2026-11-03
|
||||||
* round 3, RR3-02-03): the operating trees' checks once skipped {@code V22_1__} while the sample's
|
* round 3, RR3-02-03): the operating trees' checks once skipped {@code V22_1__} while the sample's
|
||||||
* counted it.
|
* counted it. The gRPC ledger's list in the optional build is compiled from this same source
|
||||||
|
* (README 12, r6-b; r9).
|
||||||
*/
|
*/
|
||||||
class VersionedMigrationFilesTest {
|
class VersionedMigrationFilesTest {
|
||||||
|
|
||||||
@@ -45,4 +48,49 @@ class VersionedMigrationFilesTest {
|
|||||||
"postgresql/V22_1__outbox_fix.sql",
|
"postgresql/V22_1__outbox_fix.sql",
|
||||||
"postgresql/V22.2__outbox_index.sql");
|
"postgresql/V22.2__outbox_index.sql");
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("버전 마이그레이션을 Flyway 순서대로, 버전의 각 부분을 수로 비교해 돌려준다")
|
||||||
|
void theMigrationsComeInFlywaysOrderEachVersionPartComparedAsANumber(@TempDir Path tree)
|
||||||
|
throws IOException {
|
||||||
|
// given
|
||||||
|
for (String file :
|
||||||
|
Set.of(
|
||||||
|
"V10__e.sql",
|
||||||
|
"V2.10__d.sql",
|
||||||
|
"V2_1__c.sql",
|
||||||
|
"V002__b.sql",
|
||||||
|
"V1__a.sql",
|
||||||
|
"V2__b.sql.conf",
|
||||||
|
"R__view.sql")) {
|
||||||
|
Files.writeString(tree.resolve(file), "SELECT 1;");
|
||||||
|
}
|
||||||
|
|
||||||
|
// when
|
||||||
|
List<String> ordered =
|
||||||
|
VersionedMigrationFiles.inVersionOrder(tree).stream()
|
||||||
|
.map(file -> file.getFileName().toString())
|
||||||
|
.toList();
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(ordered)
|
||||||
|
.containsExactly("V1__a.sql", "V002__b.sql", "V2_1__c.sql", "V2.10__d.sql", "V10__e.sql");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("Flyway가 같은 버전으로 보는 두 마이그레이션은 둘 다 이름을 대며 거부한다")
|
||||||
|
void twoMigrationsFlywayReadsAsOneVersionAreRefusedByName(@TempDir Path tree) throws IOException {
|
||||||
|
// given
|
||||||
|
Files.writeString(tree.resolve("V1__a.sql"), "SELECT 1;");
|
||||||
|
Files.writeString(tree.resolve("V1_0__b.sql"), "SELECT 1;");
|
||||||
|
|
||||||
|
// when
|
||||||
|
Throwable refused = catchThrowable(() -> VersionedMigrationFiles.inVersionOrder(tree));
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(refused)
|
||||||
|
.isInstanceOf(IllegalStateException.class)
|
||||||
|
.hasMessageContaining("V1__a.sql")
|
||||||
|
.hasMessageContaining("V1_0__b.sql");
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
+236
-27
@@ -1,6 +1,7 @@
|
|||||||
package dev.caskeleton.adapter.outbound.persistence.testkit.migration;
|
package dev.caskeleton.adapter.outbound.persistence.testkit.migration;
|
||||||
|
|
||||||
import java.io.IOException;
|
import java.io.IOException;
|
||||||
|
import java.io.Reader;
|
||||||
import java.nio.file.Files;
|
import java.nio.file.Files;
|
||||||
import java.nio.file.Path;
|
import java.nio.file.Path;
|
||||||
import java.util.ArrayList;
|
import java.util.ArrayList;
|
||||||
@@ -10,6 +11,7 @@ import java.util.Locale;
|
|||||||
import java.util.Map;
|
import java.util.Map;
|
||||||
import java.util.NavigableMap;
|
import java.util.NavigableMap;
|
||||||
import java.util.Objects;
|
import java.util.Objects;
|
||||||
|
import java.util.Properties;
|
||||||
import java.util.TreeMap;
|
import java.util.TreeMap;
|
||||||
import java.util.regex.Matcher;
|
import java.util.regex.Matcher;
|
||||||
import java.util.regex.Pattern;
|
import java.util.regex.Pattern;
|
||||||
@@ -44,12 +46,23 @@ import java.util.regex.Pattern;
|
|||||||
* {@code CREATE TABLE IF NOT EXISTS} does not count as creating it, because the table may already
|
* {@code CREATE TABLE IF NOT EXISTS} does not count as creating it, because the table may already
|
||||||
* be there. The bound in force at a statement is the last {@code lock_timeout} setting before it,
|
* be there. The bound in force at a statement is the last {@code lock_timeout} setting before it,
|
||||||
* and it counts only as {@code SET LOCAL} with a value that is not zero: {@code 0}, {@code DEFAULT}
|
* and it counts only as {@code SET LOCAL} with a value that is not zero: {@code 0}, {@code DEFAULT}
|
||||||
* and {@code RESET} wait without end, a plain {@code SET} outlives the migration. A migration
|
* and {@code RESET} wait without end, a plain {@code SET} outlives the migration. Comments and
|
||||||
* Flyway runs outside a transaction ({@code executeInTransaction=false} in its {@code .sql.conf},
|
* quoted literals are not read as statements. The check reads text, not a parse tree: it is a guard
|
||||||
* read by {@link #unboundedLockingStatements(Path)}) has no bound at all: {@code SET LOCAL} there
|
* against the forgotten line for the statements above, not a proof that no other statement waits
|
||||||
* only warns. Comments and quoted literals are not read as statements. The check reads text, not a
|
* (re-review 2026-11-03 round 3, RR3-02-01).
|
||||||
* parse tree: it is a guard against the forgotten line for the statements above, not a proof that
|
*
|
||||||
* no other statement waits (re-review 2026-11-03 round 3, RR3-02-01).
|
* <p>A migration Flyway runs outside a transaction has no bound at all: {@code SET LOCAL} there
|
||||||
|
* only warns. Flyway decides that the way {@link #statementsFlywayRunsOutsideATransaction(String)}
|
||||||
|
* repeats: {@code executeInTransaction} in the script's {@code .sql.conf} when there is one (read
|
||||||
|
* by {@link #unboundedLockingStatements(Path)}), and otherwise the script's own statements — one
|
||||||
|
* that PostgreSQL refuses inside a transaction ({@code VACUUM}, {@code CREATE INDEX CONCURRENTLY},
|
||||||
|
* ...) puts the whole script outside one. With Flyway's default {@code mixed=false} such a script
|
||||||
|
* that holds any other statement is refused at deploy; with {@code mixed=true} it runs, unbounded.
|
||||||
|
* A locking statement that cannot run in a transaction itself ({@code VACUUM FULL}, a
|
||||||
|
* non-concurrent {@code REINDEX SCHEMA}) can never be bounded and is refused with the advice to
|
||||||
|
* keep it out of migrations (re-review 2026-11-03 round 4, RR4-02-01). The check assumes Flyway's
|
||||||
|
* defaults, as the template runs it: {@code executeInTransaction=true} and {@code mixed=false} for
|
||||||
|
* the whole run.
|
||||||
*/
|
*/
|
||||||
public final class LockWaitMigrationInspector {
|
public final class LockWaitMigrationInspector {
|
||||||
|
|
||||||
@@ -61,6 +74,14 @@ public final class LockWaitMigrationInspector {
|
|||||||
/** A possibly qualified name, captured as group 1: the table the statement locks. */
|
/** A possibly qualified name, captured as group 1: the table the statement locks. */
|
||||||
private static final String NAME = "(" + OTHER_NAME + ")";
|
private static final String NAME = "(" + OTHER_NAME + ")";
|
||||||
|
|
||||||
|
/**
|
||||||
|
* A parenthesised option list ({@code REINDEX (VERBOSE) TABLE t}) that does not turn {@code
|
||||||
|
* CONCURRENTLY} on; {@code (CONCURRENTLY)} and {@code (CONCURRENTLY true)} do, {@code
|
||||||
|
* (CONCURRENTLY false)} does not.
|
||||||
|
*/
|
||||||
|
private static final String NOT_CONCURRENT_OPTIONS =
|
||||||
|
"\\((?![^)]*\\bconcurrently\\b(?!\\s*(?:false|off|0)\\b))[^)]*\\)";
|
||||||
|
|
||||||
private static final Pattern CREATED_TABLE =
|
private static final Pattern CREATED_TABLE =
|
||||||
Pattern.compile(
|
Pattern.compile(
|
||||||
"\\bcreate\\s+(?:(?:temp|temporary|unlogged)\\s+)?(?:table|materialized\\s+view)\\s+"
|
"\\bcreate\\s+(?:(?:temp|temporary|unlogged)\\s+)?(?:table|materialized\\s+view)\\s+"
|
||||||
@@ -77,7 +98,9 @@ public final class LockWaitMigrationInspector {
|
|||||||
+ NAME),
|
+ NAME),
|
||||||
Pattern.compile("\\bdrop\\s+index\\s+(?!concurrently\\b)"),
|
Pattern.compile("\\bdrop\\s+index\\s+(?!concurrently\\b)"),
|
||||||
Pattern.compile(
|
Pattern.compile(
|
||||||
"\\breindex\\s+(?:\\([^)]*\\)\\s+)?(?:(?:index|table)\\s+(?!concurrently\\b)"
|
"\\breindex\\s+(?:"
|
||||||
|
+ NOT_CONCURRENT_OPTIONS
|
||||||
|
+ "\\s+)?(?:(?:index|table)\\s+(?!concurrently\\b)"
|
||||||
+ NAME
|
+ NAME
|
||||||
+ "|(?:schema|database|system)\\b(?!\\s+concurrently\\b))"),
|
+ "|(?:schema|database|system)\\b(?!\\s+concurrently\\b))"),
|
||||||
Pattern.compile("\\brefresh\\s+materialized\\s+view\\s+(?!concurrently\\b)" + NAME),
|
Pattern.compile("\\brefresh\\s+materialized\\s+view\\s+(?!concurrently\\b)" + NAME),
|
||||||
@@ -90,7 +113,8 @@ public final class LockWaitMigrationInspector {
|
|||||||
+ "(?:\\s+(?:freeze|verbose|analyze)\\b)*(?:\\s+"
|
+ "(?:\\s+(?:freeze|verbose|analyze)\\b)*(?:\\s+"
|
||||||
+ NAME
|
+ NAME
|
||||||
+ ")?"),
|
+ ")?"),
|
||||||
Pattern.compile("\\breferences\\s+" + NAME),
|
// Not GRANT/REVOKE ... REFERENCES ON t: a privilege, not a foreign key.
|
||||||
|
Pattern.compile("\\breferences\\s+(?!on\\b)" + NAME),
|
||||||
Pattern.compile(
|
Pattern.compile(
|
||||||
"\\bcreate\\s+(?:or\\s+replace\\s+)?(?:constraint\\s+)?trigger\\s+"
|
"\\bcreate\\s+(?:or\\s+replace\\s+)?(?:constraint\\s+)?trigger\\s+"
|
||||||
+ OTHER_NAME
|
+ OTHER_NAME
|
||||||
@@ -118,9 +142,33 @@ public final class LockWaitMigrationInspector {
|
|||||||
private static final Pattern DURATION =
|
private static final Pattern DURATION =
|
||||||
Pattern.compile("[0-9.]+\\s*[a-z]*", Pattern.CASE_INSENSITIVE);
|
Pattern.compile("[0-9.]+\\s*[a-z]*", Pattern.CASE_INSENSITIVE);
|
||||||
|
|
||||||
/** The line in a migration's {@code .sql.conf} that makes Flyway run it outside a transaction. */
|
/**
|
||||||
private static final Pattern OUTSIDE_A_TRANSACTION =
|
* The statements Flyway runs outside a transaction on PostgreSQL 12 and later, as Flyway 11's
|
||||||
Pattern.compile("(?m)^\\s*executeInTransaction\\s*=\\s*false\\s*$");
|
* {@code PostgreSQLParser#detectCanExecuteInTransaction} lists them: the statement's leading
|
||||||
|
* words outside parentheses, lower case and one space apart, match one of these in full. {@code
|
||||||
|
* ALTER TYPE ... ADD VALUE} is on Flyway's list only below PostgreSQL 12. {@code REINDEX TABLE
|
||||||
|
* CONCURRENTLY} is not on it: Flyway runs it in the transaction and PostgreSQL refuses it there.
|
||||||
|
* {@code postgresqlMigrationLockWaitIntegrationTest} holds this list to Flyway itself on real
|
||||||
|
* PostgreSQL, so a Flyway upgrade that changes it fails there rather than here.
|
||||||
|
*/
|
||||||
|
private static final List<Pattern> FLYWAY_OUTSIDE_A_TRANSACTION =
|
||||||
|
List.of(
|
||||||
|
Pattern.compile("(?:create|drop) (?:database|tablespace|subscription)"),
|
||||||
|
Pattern.compile("alter system"),
|
||||||
|
Pattern.compile("(?:create|drop)(?: unique)? index concurrently"),
|
||||||
|
Pattern.compile("reindex(?: verbose)? (?:schema|database|system)"),
|
||||||
|
Pattern.compile("vacuum"),
|
||||||
|
Pattern.compile("discard all"));
|
||||||
|
|
||||||
|
/** Flyway stops looking after this many words of a statement and runs it in the transaction. */
|
||||||
|
private static final int FLYWAY_DETECTION_WORDS = 10;
|
||||||
|
|
||||||
|
/** A word Flyway reads as a keyword: unquoted, starting with a letter or underscore. */
|
||||||
|
private static final Pattern WORD = Pattern.compile("[a-z_][a-z0-9_$]*");
|
||||||
|
|
||||||
|
/** A dollar-quoted body ({@code $$ ... $$}, {@code $fn$ ... $fn$}), which holds no statement. */
|
||||||
|
private static final Pattern DOLLAR_QUOTED =
|
||||||
|
Pattern.compile("\\$([a-z_][a-z0-9_]*)?\\$.*?\\$\\1\\$", Pattern.DOTALL);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Fails when the migration locks a table it did not create before it bounds the wait.
|
* Fails when the migration locks a table it did not create before it bounds the wait.
|
||||||
@@ -137,42 +185,66 @@ public final class LockWaitMigrationInspector {
|
|||||||
migration.name()
|
migration.name()
|
||||||
+ " waits without a bound for a lock on a table already in use ("
|
+ " waits without a bound for a lock on a table already in use ("
|
||||||
+ String.join(", ", unbounded)
|
+ String.join(", ", unbounded)
|
||||||
+ "). Put SET LOCAL lock_timeout = '5s'; before the first of them: while it waits, every"
|
+ "). In a migration Flyway runs in a transaction, put SET LOCAL lock_timeout = '5s';"
|
||||||
+ " read and write of the table queues behind it. LOCAL, so the setting ends with the"
|
+ " before the first of them: while it waits, every read and write of the table queues"
|
||||||
+ " migration's transaction (docs/jpa/migration-guide.md, \"Bound the lock wait\")");
|
+ " behind it. LOCAL, so the setting ends with the migration's transaction"
|
||||||
|
+ " (docs/jpa/migration-guide.md, \"Bound the lock wait\")");
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* The statements that wait for a lock on an existing table without a {@code SET LOCAL
|
* The statements that wait for a lock on an existing table without a {@code SET LOCAL
|
||||||
* lock_timeout} in force, each as its leading words and table; empty when there are none. The
|
* lock_timeout} in force, each as its leading words and table; empty when there are none. The
|
||||||
* script is taken to run in a transaction, as Flyway runs a migration by default.
|
* script is taken to have no {@code .sql.conf}: Flyway runs it in a transaction unless it holds a
|
||||||
|
* statement Flyway runs outside one ({@link #statementsFlywayRunsOutsideATransaction(String)}).
|
||||||
*/
|
*/
|
||||||
public List<String> unboundedLockingStatements(String sql) {
|
public List<String> unboundedLockingStatements(String sql) {
|
||||||
return unboundedLockingStatements(sql, true);
|
return unboundedLockingStatements(sql, Configured.NOTHING);
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* The same, for a migration file on disk: a {@code <script>.conf} beside it that sets {@code
|
* The same, for a migration file on disk: {@code executeInTransaction} in a {@code <script>.conf}
|
||||||
* executeInTransaction=false} makes every statement found unbounded, each named with the reason.
|
* beside it decides in or out of a transaction instead of Flyway's own detection, read the way
|
||||||
|
* Flyway reads it (a properties file, {@code true} or {@code false} in any case).
|
||||||
|
*
|
||||||
|
* @throws IllegalStateException when the {@code .conf} sets {@code executeInTransaction} to
|
||||||
|
* something Flyway would refuse
|
||||||
*/
|
*/
|
||||||
public List<String> unboundedLockingStatements(Path script) throws IOException {
|
public List<String> unboundedLockingStatements(Path script) throws IOException {
|
||||||
Path configuration = script.resolveSibling(script.getFileName() + ".conf");
|
Path configuration = script.resolveSibling(script.getFileName() + ".conf");
|
||||||
boolean inTransaction =
|
Configured configured =
|
||||||
!Files.exists(configuration)
|
Files.exists(configuration) ? executeInTransaction(configuration) : Configured.NOTHING;
|
||||||
|| !OUTSIDE_A_TRANSACTION.matcher(Files.readString(configuration)).find();
|
return unboundedLockingStatements(Files.readString(script), configured);
|
||||||
return unboundedLockingStatements(Files.readString(script), inTransaction);
|
|
||||||
}
|
}
|
||||||
|
|
||||||
private List<String> unboundedLockingStatements(String sql, boolean inTransaction) {
|
/**
|
||||||
|
* The statements of the script Flyway runs outside a transaction, each as the leading words that
|
||||||
|
* made it so ({@code vacuum}, {@code create index concurrently}); empty when Flyway runs the
|
||||||
|
* script in one. One of them is enough to put the whole script outside a transaction, and next to
|
||||||
|
* any other statement it makes Flyway refuse the script unless {@code mixed=true}. A {@code
|
||||||
|
* .sql.conf} that sets {@code executeInTransaction} overrides this; the text alone cannot say.
|
||||||
|
*/
|
||||||
|
public List<String> statementsFlywayRunsOutsideATransaction(String sql) {
|
||||||
if (sql == null) {
|
if (sql == null) {
|
||||||
return List.of();
|
return List.of();
|
||||||
}
|
}
|
||||||
String text = withoutCommentsAndLiterals(sql).toLowerCase(Locale.ROOT).replaceAll("\\s+", " ");
|
return outsideATransaction(normalized(sql)).stream().map(Statement::words).toList();
|
||||||
|
}
|
||||||
|
|
||||||
|
private List<String> unboundedLockingStatements(String sql, Configured configured) {
|
||||||
|
if (sql == null) {
|
||||||
|
return List.of();
|
||||||
|
}
|
||||||
|
String text = normalized(sql);
|
||||||
Map<String, Integer> createdAt = new HashMap<>();
|
Map<String, Integer> createdAt = new HashMap<>();
|
||||||
Matcher created = CREATED_TABLE.matcher(text);
|
Matcher created = CREATED_TABLE.matcher(text);
|
||||||
while (created.find()) {
|
while (created.find()) {
|
||||||
createdAt.putIfAbsent(table(created.group(1)), created.start());
|
createdAt.putIfAbsent(table(created.group(1)), created.start());
|
||||||
}
|
}
|
||||||
|
List<Statement> outside = outsideATransaction(text);
|
||||||
|
boolean inTransaction =
|
||||||
|
configured == Configured.NOTHING
|
||||||
|
? outside.isEmpty()
|
||||||
|
: configured == Configured.IN_A_TRANSACTION;
|
||||||
NavigableMap<Integer, Boolean> bounds = inTransaction ? bounds(text) : new TreeMap<>();
|
NavigableMap<Integer, Boolean> bounds = inTransaction ? bounds(text) : new TreeMap<>();
|
||||||
List<Located> found = new ArrayList<>();
|
List<Located> found = new ArrayList<>();
|
||||||
for (Pattern pattern : LOCKING) {
|
for (Pattern pattern : LOCKING) {
|
||||||
@@ -187,9 +259,7 @@ public final class LockWaitMigrationInspector {
|
|||||||
statement.start(),
|
statement.start(),
|
||||||
inTransaction
|
inTransaction
|
||||||
? named
|
? named
|
||||||
: named
|
: named + " (" + whyUnbounded(statement.start(), outside, configured) + ")"));
|
||||||
+ " (executeInTransaction=false: SET LOCAL does nothing outside a"
|
|
||||||
+ " transaction; move it to a migration that runs in one)"));
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@@ -199,6 +269,135 @@ public final class LockWaitMigrationInspector {
|
|||||||
.toList();
|
.toList();
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Why a locking statement at {@code at} has no bound in a script that runs outside a transaction.
|
||||||
|
*/
|
||||||
|
private static String whyUnbounded(int at, List<Statement> outside, Configured configured) {
|
||||||
|
for (Statement statement : outside) {
|
||||||
|
if (statement.start() <= at && at < statement.end()) {
|
||||||
|
return "cannot run in a transaction, so no SET LOCAL can bound its wait: keep it out of"
|
||||||
|
+ " migrations and run it by hand as an operations step, outside deploys";
|
||||||
|
}
|
||||||
|
}
|
||||||
|
if (configured == Configured.OUTSIDE_A_TRANSACTION) {
|
||||||
|
return "executeInTransaction=false: SET LOCAL does nothing outside a transaction; move it to"
|
||||||
|
+ " a migration that runs in one";
|
||||||
|
}
|
||||||
|
return "Flyway runs this migration outside a transaction because of "
|
||||||
|
+ outside.get(0).words()
|
||||||
|
+ ": SET LOCAL does nothing there, and with mixed=false Flyway refuses the migration; put "
|
||||||
|
+ outside.get(0).words()
|
||||||
|
+ " in a migration of its own";
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The statements Flyway runs outside a transaction, found the way Flyway finds them: each
|
||||||
|
* statement's words outside parentheses, up to {@link #FLYWAY_DETECTION_WORDS} words in all,
|
||||||
|
* matched one more word at a time against {@link #FLYWAY_OUTSIDE_A_TRANSACTION}.
|
||||||
|
*/
|
||||||
|
private static List<Statement> outsideATransaction(String text) {
|
||||||
|
String statements = blankedDollarQuotes(text);
|
||||||
|
List<Statement> outside = new ArrayList<>();
|
||||||
|
int start = 0;
|
||||||
|
while (start < statements.length()) {
|
||||||
|
int end = statements.indexOf(';', start);
|
||||||
|
if (end < 0) {
|
||||||
|
end = statements.length();
|
||||||
|
}
|
||||||
|
String words = flywayWordsOutsideATransaction(statements.substring(start, end));
|
||||||
|
if (words != null) {
|
||||||
|
outside.add(new Statement(start, end, words));
|
||||||
|
}
|
||||||
|
start = end + 1;
|
||||||
|
}
|
||||||
|
return outside;
|
||||||
|
}
|
||||||
|
|
||||||
|
/** The leading words that put this one statement outside a transaction, or null when none do. */
|
||||||
|
private static String flywayWordsOutsideATransaction(String statement) {
|
||||||
|
StringBuilder leading = new StringBuilder();
|
||||||
|
int words = 0;
|
||||||
|
int depth = 0;
|
||||||
|
int i = 0;
|
||||||
|
while (i < statement.length()) {
|
||||||
|
char c = statement.charAt(i);
|
||||||
|
if (c == '(') {
|
||||||
|
depth++;
|
||||||
|
i++;
|
||||||
|
} else if (c == ')') {
|
||||||
|
depth = Math.max(0, depth - 1);
|
||||||
|
i++;
|
||||||
|
} else if (c == '"') {
|
||||||
|
int close = statement.indexOf('"', i + 1);
|
||||||
|
i = close < 0 ? statement.length() : close + 1;
|
||||||
|
} else {
|
||||||
|
Matcher word = WORD.matcher(statement).region(i, statement.length());
|
||||||
|
if (!word.lookingAt()) {
|
||||||
|
i++;
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
i = word.end();
|
||||||
|
words++;
|
||||||
|
if (words > FLYWAY_DETECTION_WORDS) {
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
if (depth == 0) {
|
||||||
|
leading.append(leading.isEmpty() ? "" : " ").append(word.group());
|
||||||
|
for (Pattern outside : FLYWAY_OUTSIDE_A_TRANSACTION) {
|
||||||
|
if (outside.matcher(leading).matches()) {
|
||||||
|
return leading.toString();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
|
||||||
|
/** The text with every dollar-quoted body blanked, keeping every other character in place. */
|
||||||
|
private static String blankedDollarQuotes(String text) {
|
||||||
|
StringBuilder blanked = new StringBuilder(text);
|
||||||
|
Matcher quoted = DOLLAR_QUOTED.matcher(text);
|
||||||
|
while (quoted.find()) {
|
||||||
|
for (int i = quoted.start(); i < quoted.end(); i++) {
|
||||||
|
blanked.setCharAt(i, ' ');
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return blanked.toString();
|
||||||
|
}
|
||||||
|
|
||||||
|
/** The script as the patterns read it: no comments or literals, lower case, single spaces. */
|
||||||
|
private static String normalized(String sql) {
|
||||||
|
return withoutCommentsAndLiterals(sql).toLowerCase(Locale.ROOT).replaceAll("\\s+", " ");
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* {@code executeInTransaction} from a script's {@code .sql.conf}, read as Flyway reads it: a
|
||||||
|
* properties file whose value is {@code true} or {@code false} in any case.
|
||||||
|
*/
|
||||||
|
private static Configured executeInTransaction(Path configuration) throws IOException {
|
||||||
|
Properties properties = new Properties();
|
||||||
|
try (Reader reader = Files.newBufferedReader(configuration)) {
|
||||||
|
properties.load(reader);
|
||||||
|
}
|
||||||
|
String value = properties.getProperty("executeInTransaction");
|
||||||
|
if (value == null) {
|
||||||
|
return Configured.NOTHING;
|
||||||
|
}
|
||||||
|
String trimmed = value.trim();
|
||||||
|
if (trimmed.equalsIgnoreCase("true")) {
|
||||||
|
return Configured.IN_A_TRANSACTION;
|
||||||
|
}
|
||||||
|
if (trimmed.equalsIgnoreCase("false")) {
|
||||||
|
return Configured.OUTSIDE_A_TRANSACTION;
|
||||||
|
}
|
||||||
|
throw new IllegalStateException(
|
||||||
|
configuration
|
||||||
|
+ " sets executeInTransaction to '"
|
||||||
|
+ trimmed
|
||||||
|
+ "'; Flyway accepts only true or false");
|
||||||
|
}
|
||||||
|
|
||||||
/** Each {@code lock_timeout} setting by position: whether it bounds the statements after it. */
|
/** Each {@code lock_timeout} setting by position: whether it bounds the statements after it. */
|
||||||
private static NavigableMap<Integer, Boolean> bounds(String text) {
|
private static NavigableMap<Integer, Boolean> bounds(String text) {
|
||||||
NavigableMap<Integer, Boolean> bounds = new TreeMap<>();
|
NavigableMap<Integer, Boolean> bounds = new TreeMap<>();
|
||||||
@@ -272,4 +471,14 @@ public final class LockWaitMigrationInspector {
|
|||||||
}
|
}
|
||||||
|
|
||||||
private record Located(int at, String statement) {}
|
private record Located(int at, String statement) {}
|
||||||
|
|
||||||
|
/** What a script's {@code .sql.conf} says about the transaction; nothing leaves it to Flyway. */
|
||||||
|
private enum Configured {
|
||||||
|
NOTHING,
|
||||||
|
IN_A_TRANSACTION,
|
||||||
|
OUTSIDE_A_TRANSACTION
|
||||||
|
}
|
||||||
|
|
||||||
|
/** A statement Flyway runs outside a transaction: where it is and the words that decided it. */
|
||||||
|
private record Statement(int start, int end, String words) {}
|
||||||
}
|
}
|
||||||
|
|||||||
+52
@@ -1,8 +1,12 @@
|
|||||||
package dev.caskeleton.adapter.outbound.persistence.testkit.migration;
|
package dev.caskeleton.adapter.outbound.persistence.testkit.migration;
|
||||||
|
|
||||||
import java.io.IOException;
|
import java.io.IOException;
|
||||||
|
import java.math.BigInteger;
|
||||||
import java.nio.file.Files;
|
import java.nio.file.Files;
|
||||||
import java.nio.file.Path;
|
import java.nio.file.Path;
|
||||||
|
import java.util.ArrayList;
|
||||||
|
import java.util.Arrays;
|
||||||
|
import java.util.List;
|
||||||
import java.util.Objects;
|
import java.util.Objects;
|
||||||
import java.util.SortedMap;
|
import java.util.SortedMap;
|
||||||
import java.util.TreeMap;
|
import java.util.TreeMap;
|
||||||
@@ -19,6 +23,12 @@ import java.util.stream.Stream;
|
|||||||
* checks and the sample stream's. Two copies had drifted: the operating trees' skipped {@code
|
* checks and the sample stream's. Two copies had drifted: the operating trees' skipped {@code
|
||||||
* V22_1__} while the sample's counted it, so a decimal version in an operating tree was neither
|
* V22_1__} while the sample's counted it, so a decimal version in an operating tree was neither
|
||||||
* pinned nor held to the lock-wait rule (re-review 2026-11-03 round 3, RR3-02-03).
|
* pinned nor held to the lock-wait rule (re-review 2026-11-03 round 3, RR3-02-03).
|
||||||
|
*
|
||||||
|
* <p>The gRPC ledger's lanes use it too. They live in the optional build, which cannot depend on
|
||||||
|
* this testkit, so {@code grpc-operation-ledger-jpa} compiles this one file from here into its
|
||||||
|
* integration-test sources at build time (its {@code build.gradle}, {@code
|
||||||
|
* sharedMigrationFileSources}) instead of keeping a copy that could drift (re-review README 12,
|
||||||
|
* r6-b; r9). Hence the rule for this file: the JDK only, nothing else from this testkit.
|
||||||
*/
|
*/
|
||||||
public final class VersionedMigrationFiles {
|
public final class VersionedMigrationFiles {
|
||||||
|
|
||||||
@@ -41,7 +51,49 @@ public final class VersionedMigrationFiles {
|
|||||||
return migrations;
|
return migrations;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Every versioned migration below {@code root} in the order Flyway applies them: by version, its
|
||||||
|
* parts compared as numbers, a missing part as zero ({@code V2 < V2_1 < V2.10 < V10}, and {@code
|
||||||
|
* V1} is {@code V1_0}).
|
||||||
|
*
|
||||||
|
* @throws IllegalStateException naming both files when two have the same version, which Flyway
|
||||||
|
* refuses as well
|
||||||
|
*/
|
||||||
|
public static List<Path> inVersionOrder(Path root) throws IOException {
|
||||||
|
List<Path> ordered = new ArrayList<>(under(root).values());
|
||||||
|
ordered.sort((left, right) -> compareVersions(version(left), version(right)));
|
||||||
|
for (int i = 1; i < ordered.size(); i++) {
|
||||||
|
if (compareVersions(version(ordered.get(i - 1)), version(ordered.get(i))) == 0) {
|
||||||
|
throw new IllegalStateException(
|
||||||
|
ordered.get(i - 1).getFileName()
|
||||||
|
+ " and "
|
||||||
|
+ ordered.get(i).getFileName()
|
||||||
|
+ " have the same version; Flyway refuses two migrations with one version");
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return ordered;
|
||||||
|
}
|
||||||
|
|
||||||
private static boolean isVersioned(Path file) {
|
private static boolean isVersioned(Path file) {
|
||||||
return VERSIONED.matcher(file.getFileName().toString()).matches();
|
return VERSIONED.matcher(file.getFileName().toString()).matches();
|
||||||
}
|
}
|
||||||
|
|
||||||
|
private static BigInteger[] version(Path file) {
|
||||||
|
String name = file.getFileName().toString();
|
||||||
|
return Arrays.stream(name.substring(1, name.indexOf("__")).split("[._]"))
|
||||||
|
.map(BigInteger::new)
|
||||||
|
.toArray(BigInteger[]::new);
|
||||||
|
}
|
||||||
|
|
||||||
|
private static int compareVersions(BigInteger[] left, BigInteger[] right) {
|
||||||
|
for (int i = 0; i < Math.max(left.length, right.length); i++) {
|
||||||
|
BigInteger l = i < left.length ? left[i] : BigInteger.ZERO;
|
||||||
|
BigInteger r = i < right.length ? right[i] : BigInteger.ZERO;
|
||||||
|
int compared = l.compareTo(r);
|
||||||
|
if (compared != 0) {
|
||||||
|
return compared;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return 0;
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
+7
-2
@@ -277,6 +277,10 @@ public final class InMemorySemanticRedisCommands implements SemanticRedisCommand
|
|||||||
if (!state.equals(fromState)) {
|
if (!state.equals(fromState)) {
|
||||||
return reply("WRONG_STATE", attempt, rev, owner, state, "");
|
return reply("WRONG_STATE", attempt, rev, owner, state, "");
|
||||||
}
|
}
|
||||||
|
// As the program: a claim whose lease ran out is not started (re-review 2026-11-04 README 15).
|
||||||
|
if ("CLAIMED".equals(state) && Long.parseLong(field(rendered, "leaseUntil")) <= now()) {
|
||||||
|
return reply("LEASE_EXPIRED", attempt, rev, owner, "", "");
|
||||||
|
}
|
||||||
setField(rendered, "state", toState);
|
setField(rendered, "state", toState);
|
||||||
setField(rendered, "rev", Long.toString(rev + 1));
|
setField(rendered, "rev", Long.toString(rev + 1));
|
||||||
if (!payload.isEmpty()) {
|
if (!payload.isEmpty()) {
|
||||||
@@ -321,9 +325,10 @@ public final class InMemorySemanticRedisCommands implements SemanticRedisCommand
|
|||||||
if (!"EXECUTING".equals(state)) {
|
if (!"EXECUTING".equals(state)) {
|
||||||
return reply("WRONG_STATE", attempt, rev, owner, state, "");
|
return reply("WRONG_STATE", attempt, rev, owner, state, "");
|
||||||
}
|
}
|
||||||
// As the program: a lease that already ran out is not brought back.
|
// As the program: a lease that already ran out is not brought back, and its holder is told so
|
||||||
|
// rather than that it no longer owns the record (RR5-01-02).
|
||||||
if (Long.parseLong(field(rendered, "leaseUntil")) <= now()) {
|
if (Long.parseLong(field(rendered, "leaseUntil")) <= now()) {
|
||||||
return reply("NOT_OWNER", attempt, rev, owner, "", "");
|
return reply("LEASE_EXPIRED", attempt, rev, owner, "", "");
|
||||||
}
|
}
|
||||||
setField(rendered, "leaseUntil", Long.toString(now() + Long.parseLong(leaseMillis)));
|
setField(rendered, "leaseUntil", Long.toString(now() + Long.parseLong(leaseMillis)));
|
||||||
setField(rendered, "rev", Long.toString(rev + 1));
|
setField(rendered, "rev", Long.toString(rev + 1));
|
||||||
|
|||||||
@@ -498,6 +498,9 @@ ArchUnit 규칙이 **금지**하는 타입을 fixture 가 일부러 import 해
|
|||||||
spring-webmvc 를 통해 transitive 로 도착한다.
|
spring-webmvc 를 통해 transitive 로 도착한다.
|
||||||
- `kafka-clients` / `jakarta.ws.rs-api` — transport-free 도메인 이벤트 fixture
|
- `kafka-clients` / `jakarta.ws.rs-api` — transport-free 도메인 이벤트 fixture
|
||||||
(domain-modeling-guardrails)가 금지된 broker/wire/HTTP 패키지를 import 한다.
|
(domain-modeling-guardrails)가 금지된 broker/wire/HTTP 패키지를 import 한다.
|
||||||
|
- `graphql-java` (`architectureTestCompileOnly`) — `SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`의
|
||||||
|
사용자 전송 타입 목록 중 `graphql..` 항목을 증명하는 fixture(`GraphQlJavaSystemCallerFixture`)가
|
||||||
|
graphql-java 타입 하나만 쓴다. runtime 은 GraphQL adapter 가 이미 같은 버전을 싣는다(lock 동일).
|
||||||
- `spring-cloud-context` — `@RefreshScope` 금지(no-refresh-scope) fixture 용. Spring Cloud 는
|
- `spring-cloud-context` — `@RefreshScope` 금지(no-refresh-scope) fixture 용. Spring Cloud 는
|
||||||
production 에 없고 규칙은 애너테이션을 FQN 문자열로 참조한다. BOM 이 spring-cloud 좌표를 관리하지
|
production 에 없고 규칙은 애너테이션을 FQN 문자열로 참조한다. BOM 이 spring-cloud 좌표를 관리하지
|
||||||
않아 버전을 명시 고정한다.
|
않아 버전을 명시 고정한다.
|
||||||
|
|||||||
@@ -278,6 +278,10 @@ dependencies {
|
|||||||
// architecture-only: positive-control fixture imports Kafka TopicPartition to prove domain code
|
// architecture-only: positive-control fixture imports Kafka TopicPartition to prove domain code
|
||||||
// cannot depend on broker SDK types. The shipped main/test compile classpaths must not inherit it.
|
// cannot depend on broker SDK types. The shipped main/test compile classpaths must not inherit it.
|
||||||
architectureTestCompileOnly 'org.apache.kafka:kafka-clients'
|
architectureTestCompileOnly 'org.apache.kafka:kafka-clients'
|
||||||
|
// architecture-only: the system-caller fixture for the `graphql..` entry of the user-transport
|
||||||
|
// type list is a raw graphql-java data fetcher. The adapter brings graphql-java onto this source
|
||||||
|
// set's runtime already (capabilityProjects); compile-only here so no shipped graph changes.
|
||||||
|
architectureTestCompileOnly 'com.graphql-java:graphql-java'
|
||||||
// Kafka producer ownership lives in adapter:outbound:messaging. The composition root sees only
|
// Kafka producer ownership lives in adapter:outbound:messaging. The composition root sees only
|
||||||
// the adapter module; it no longer implements the broker seam itself.
|
// the adapter module; it no longer implements the broker seam itself.
|
||||||
testCompileOnly 'jakarta.ws.rs:jakarta.ws.rs-api' // jakarta.ws.rs..
|
testCompileOnly 'jakarta.ws.rs:jakarta.ws.rs-api' // jakarta.ws.rs..
|
||||||
|
|||||||
@@ -52,8 +52,8 @@ com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,architectureTestAnn
|
|||||||
com.google.protobuf:protobuf-java-util:3.25.5=architectureTestRuntimeClasspath,conditionalTransportBuildContractTestRuntimeClasspath,qualificationRuntimeClasspath
|
com.google.protobuf:protobuf-java-util:3.25.5=architectureTestRuntimeClasspath,conditionalTransportBuildContractTestRuntimeClasspath,qualificationRuntimeClasspath
|
||||||
com.google.protobuf:protobuf-java:3.25.5=architectureTestRuntimeClasspath,conditionalTransportBuildContractTestRuntimeClasspath,qualificationRuntimeClasspath
|
com.google.protobuf:protobuf-java:3.25.5=architectureTestRuntimeClasspath,conditionalTransportBuildContractTestRuntimeClasspath,qualificationRuntimeClasspath
|
||||||
com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,architectureTestAnnotationProcessor,conditionalTransportBuildContractTestAnnotationProcessor,integrationTestAnnotationProcessor,systemTestAnnotationProcessor,testAnnotationProcessor
|
com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,architectureTestAnnotationProcessor,conditionalTransportBuildContractTestAnnotationProcessor,integrationTestAnnotationProcessor,systemTestAnnotationProcessor,testAnnotationProcessor
|
||||||
com.graphql-java:graphql-java:25.0=architectureTestRuntimeClasspath,conditionalTransportBuildContractTestRuntimeClasspath,qualificationRuntimeClasspath
|
com.graphql-java:graphql-java:25.0=architectureTestCompileClasspath,architectureTestRuntimeClasspath,conditionalTransportBuildContractTestRuntimeClasspath,qualificationRuntimeClasspath
|
||||||
com.graphql-java:java-dataloader:6.0.0=architectureTestRuntimeClasspath,conditionalTransportBuildContractTestRuntimeClasspath,qualificationRuntimeClasspath
|
com.graphql-java:java-dataloader:6.0.0=architectureTestCompileClasspath,architectureTestRuntimeClasspath,conditionalTransportBuildContractTestRuntimeClasspath,qualificationRuntimeClasspath
|
||||||
com.h2database:h2:2.4.240=bootRunH2Classpath
|
com.h2database:h2:2.4.240=bootRunH2Classpath
|
||||||
com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins
|
com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins
|
||||||
com.jayway.jsonpath:json-path:2.10.0=architectureTestCompileClasspath,architectureTestRuntimeClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,systemTestCompileClasspath,systemTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
|
com.jayway.jsonpath:json-path:2.10.0=architectureTestCompileClasspath,architectureTestRuntimeClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,systemTestCompileClasspath,systemTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
|
||||||
@@ -260,7 +260,7 @@ org.ow2.asm:asm:9.10.1=spotbugs
|
|||||||
org.ow2.asm:asm:9.7.1=architectureTestCompileClasspath,architectureTestRuntimeClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,qualificationRuntimeClasspath,systemTestCompileClasspath,systemTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
|
org.ow2.asm:asm:9.7.1=architectureTestCompileClasspath,architectureTestRuntimeClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,qualificationRuntimeClasspath,systemTestCompileClasspath,systemTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
|
||||||
org.pcollections:pcollections:4.0.1=annotationProcessor,architectureTestAnnotationProcessor,conditionalTransportBuildContractTestAnnotationProcessor,integrationTestAnnotationProcessor,systemTestAnnotationProcessor,testAnnotationProcessor
|
org.pcollections:pcollections:4.0.1=annotationProcessor,architectureTestAnnotationProcessor,conditionalTransportBuildContractTestAnnotationProcessor,integrationTestAnnotationProcessor,systemTestAnnotationProcessor,testAnnotationProcessor
|
||||||
org.postgresql:postgresql:42.7.13=architectureTestRuntimeClasspath,bootRunH2Classpath,integrationTestRuntimeClasspath,qualificationRuntimeClasspath,testRuntimeClasspath
|
org.postgresql:postgresql:42.7.13=architectureTestRuntimeClasspath,bootRunH2Classpath,integrationTestRuntimeClasspath,qualificationRuntimeClasspath,testRuntimeClasspath
|
||||||
org.reactivestreams:reactive-streams:1.0.4=architectureTestRuntimeClasspath,bootRunH2Classpath,conditionalTransportBuildContractTestRuntimeClasspath,integrationTestRuntimeClasspath,qualificationRuntimeClasspath,testRuntimeClasspath
|
org.reactivestreams:reactive-streams:1.0.4=architectureTestCompileClasspath,architectureTestRuntimeClasspath,bootRunH2Classpath,conditionalTransportBuildContractTestRuntimeClasspath,integrationTestRuntimeClasspath,qualificationRuntimeClasspath,testRuntimeClasspath
|
||||||
org.reflections:reflections:0.10.2=checkstyle
|
org.reflections:reflections:0.10.2=checkstyle
|
||||||
org.rnorth.duct-tape:duct-tape:1.0.8=architectureTestCompileClasspath,architectureTestRuntimeClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,systemTestCompileClasspath,testCompileClasspath,testRuntimeClasspath
|
org.rnorth.duct-tape:duct-tape:1.0.8=architectureTestCompileClasspath,architectureTestRuntimeClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,systemTestCompileClasspath,testCompileClasspath,testRuntimeClasspath
|
||||||
org.skyscreamer:jsonassert:1.5.3=architectureTestCompileClasspath,architectureTestRuntimeClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,systemTestCompileClasspath,systemTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
|
org.skyscreamer:jsonassert:1.5.3=architectureTestCompileClasspath,architectureTestRuntimeClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,systemTestCompileClasspath,systemTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
|
||||||
|
|||||||
+121
-17
@@ -32,6 +32,7 @@ import dev.caskeleton.application.usecase.QueryUseCase;
|
|||||||
import java.util.HashSet;
|
import java.util.HashSet;
|
||||||
import java.util.List;
|
import java.util.List;
|
||||||
import java.util.Set;
|
import java.util.Set;
|
||||||
|
import java.util.TreeSet;
|
||||||
import org.springframework.boot.health.actuate.endpoint.HealthEndpoint;
|
import org.springframework.boot.health.actuate.endpoint.HealthEndpoint;
|
||||||
import org.springframework.boot.health.contributor.Health;
|
import org.springframework.boot.health.contributor.Health;
|
||||||
import org.springframework.boot.health.contributor.HealthIndicator;
|
import org.springframework.boot.health.contributor.HealthIndicator;
|
||||||
@@ -489,20 +490,35 @@ class ApplicationBoundaryArchitectureTest {
|
|||||||
"org.springframework.messaging.handler.annotation.MessageMapping"))
|
"org.springframework.messaging.handler.annotation.MessageMapping"))
|
||||||
.as("user-transport types (web, JAX-RS, GraphQL, gRPC, WebSocket/STOMP endpoints)");
|
.as("user-transport types (web, JAX-RS, GraphQL, gRPC, WebSocket/STOMP endpoints)");
|
||||||
|
|
||||||
|
/** Spring's configuration stereotype, which {@code @AutoConfiguration} carries as well. */
|
||||||
|
private static final String CONFIGURATION =
|
||||||
|
"org.springframework.context.annotation.Configuration";
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* A class a user request comes in through: it lives in a user-transport package or is built from
|
* A class a user request comes in through: it lives in a user-transport package, or it is built
|
||||||
* a user-transport type. A configuration that only registers a system caller is neither, which is
|
* from a user-transport type and is not a configuration.
|
||||||
* why the rule below names these rather than every inbound class.
|
*
|
||||||
|
* <p>A configuration is the composition root, not a way in. A feature's configuration that
|
||||||
|
* registers its message handler beside a {@code WebMvcConfigurer} or its controller names web
|
||||||
|
* types without any request passing through it (review 2026-11-04 RR4-01-02). Leaving it out
|
||||||
|
* opens nothing: a controller the configuration builds is checked itself, by its package or its
|
||||||
|
* own transport types, and anything it is handed is a dependency of the controller.
|
||||||
*/
|
*/
|
||||||
private static final DescribedPredicate<JavaClass> ARE_USER_TRANSPORTS =
|
private static final DescribedPredicate<JavaClass> ARE_USER_TRANSPORTS =
|
||||||
new DescribedPredicate<>(
|
new DescribedPredicate<>(
|
||||||
"are user transports (in a user-transport package or built from one)") {
|
"are user transports (in a user-transport package, or a non-configuration built from"
|
||||||
|
+ " one)") {
|
||||||
@Override
|
@Override
|
||||||
public boolean test(JavaClass candidate) {
|
public boolean test(JavaClass candidate) {
|
||||||
return ARE_USER_TRANSPORT_TYPES.test(candidate)
|
if (ARE_USER_TRANSPORT_TYPES.test(candidate)) {
|
||||||
|| candidate.getDirectDependenciesFromSelf().stream()
|
return true;
|
||||||
.anyMatch(
|
}
|
||||||
dependency -> ARE_USER_TRANSPORT_TYPES.test(dependency.getTargetClass()));
|
if (candidate.isAnnotatedWith(CONFIGURATION)
|
||||||
|
|| candidate.isMetaAnnotatedWith(CONFIGURATION)) {
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
return candidate.getDirectDependenciesFromSelf().stream()
|
||||||
|
.anyMatch(dependency -> ARE_USER_TRANSPORT_TYPES.test(dependency.getTargetClass()));
|
||||||
}
|
}
|
||||||
};
|
};
|
||||||
|
|
||||||
@@ -525,6 +541,30 @@ class ApplicationBoundaryArchitectureTest {
|
|||||||
}
|
}
|
||||||
};
|
};
|
||||||
|
|
||||||
|
/** The packages this code base owns: a type here is one the dependency rules can follow. */
|
||||||
|
private static final String PROJECT_PACKAGE_PREFIX = "dev.caskeleton.";
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Every type a system caller can be handed as: the caller itself, and each project class or
|
||||||
|
* interface it extends or implements. A "run now" endpoint that injects the job by the job's own
|
||||||
|
* interface depends on that interface, not on the job, so the rule below has to stop there too
|
||||||
|
* (review 2026-11-04 RR4-01-01). A type outside the project — {@code Runnable}, {@code
|
||||||
|
* ApplicationRunner} — cannot be a target: any class may depend on it for its own reasons, so
|
||||||
|
* {@code SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES} keeps system callers from having one.
|
||||||
|
*/
|
||||||
|
private static final DescribedPredicate<JavaClass> ARE_TYPES_A_SYSTEM_CALLER_IS_HANDED_AS =
|
||||||
|
new DescribedPredicate<>(
|
||||||
|
"are @SystemCaller classes, nested in one, or project types one extends or implements") {
|
||||||
|
@Override
|
||||||
|
public boolean test(JavaClass candidate) {
|
||||||
|
if (ARE_SYSTEM_CALLERS.test(candidate)) {
|
||||||
|
return true;
|
||||||
|
}
|
||||||
|
return candidate.getName().startsWith(PROJECT_PACKAGE_PREFIX)
|
||||||
|
&& candidate.getAllSubclasses().stream().anyMatch(ARE_SYSTEM_CALLERS);
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* A {@link SystemInvoked} use case is a write with no permission check, so no user request may
|
* A {@link SystemInvoked} use case is a write with no permission check, so no user request may
|
||||||
* reach it. A user comes in through a transport; the system comes in through a delivery or a tick
|
* reach it. A user comes in through a transport; the system comes in through a delivery or a tick
|
||||||
@@ -582,27 +622,91 @@ class ApplicationBoundaryArchitectureTest {
|
|||||||
* The other way round: a user transport does not reach a {@link SystemCaller}, directly or
|
* The other way round: a user transport does not reach a {@link SystemCaller}, directly or
|
||||||
* through classes in between. A "run now" endpoint handed the job bean never names the {@link
|
* through classes in between. A "run now" endpoint handed the job bean never names the {@link
|
||||||
* SystemInvoked} use case, so the rules above do not see it, yet a user request then runs a write
|
* SystemInvoked} use case, so the rules above do not see it, yet a user request then runs a write
|
||||||
* no permission guards (review 2026-11-04 RR3-01-01). The configuration that registers the
|
* no permission guards (review 2026-11-04 RR3-01-01). Reaching the job's own interface, or any
|
||||||
* handler is no transport and may depend on it.
|
* project type the job extends or implements, counts as reaching the job: that is the type the
|
||||||
|
* endpoint is handed when it injects by interface (RR4-01-01). A configuration is no transport
|
||||||
|
* and may register the handler beside web beans (RR4-01-02).
|
||||||
*
|
*
|
||||||
* <p>Like every rule here it reads class dependencies. A lookup at run time ({@code getBean},
|
* <p>It reads class dependencies, so it sees every typed path, including {@code
|
||||||
* {@code ObjectProvider}) is not a dependency and is not seen.
|
* ObjectProvider<TheJob>} and {@code getBean(TheJob.class)}: both name the type. It cannot see a
|
||||||
|
* path that names no type the job is handed as — a lookup by bean name or by {@code Object}, or a
|
||||||
|
* configuration that passes a user transport a function wrapping the job ({@code job::run} as a
|
||||||
|
* {@code Runnable}). Manual 07 「시스템이 부르는 쓰기」 lists those paths and what holds them.
|
||||||
*/
|
*/
|
||||||
@ArchTest
|
@ArchTest
|
||||||
static final ArchRule USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS =
|
static final ArchRule USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS =
|
||||||
noClasses()
|
noClasses()
|
||||||
.that(ARE_USER_TRANSPORTS)
|
.that(ARE_USER_TRANSPORTS)
|
||||||
.should()
|
.should()
|
||||||
.transitivelyDependOnClassesThat(ARE_SYSTEM_CALLERS)
|
.transitivelyDependOnClassesThat(ARE_TYPES_A_SYSTEM_CALLER_IS_HANDED_AS)
|
||||||
.as(
|
.as(
|
||||||
"USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS: a class a user request comes in "
|
"USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS: a class a user request comes in "
|
||||||
+ "through (a user-transport package, or built from a web, JAX-RS, GraphQL, gRPC "
|
+ "through (a user-transport package, or a non-configuration built from a web, "
|
||||||
+ "or WebSocket type) does not reach a @SystemCaller, directly or through other "
|
+ "JAX-RS, GraphQL, gRPC or WebSocket type) does not reach a @SystemCaller or a "
|
||||||
+ "classes — the system caller runs a @SystemInvoked write with no permission "
|
+ "project type one extends or implements, directly or through other classes — "
|
||||||
+ "check. A user-triggered run of the same work is its own use case with "
|
+ "the system caller runs a @SystemInvoked write with no permission check. A "
|
||||||
|
+ "user-triggered run of the same work is its own use case with "
|
||||||
+ "@RequiresPermission (manual 07 「시스템이 부르는 쓰기」)")
|
+ "@RequiresPermission (manual 07 「시스템이 부르는 쓰기」)")
|
||||||
.allowEmptyShould(true);
|
.allowEmptyShould(true);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* A system caller is handed out only as types the rule above can follow. A supertype outside the
|
||||||
|
* project — {@code Runnable}, {@code Callable}, {@code ApplicationRunner}, {@code TimerTask} — is
|
||||||
|
* one any class may depend on for its own reasons, so an endpoint that injects the job as one
|
||||||
|
* looks like every other user of the interface, and a rule that refused the dependency would
|
||||||
|
* refuse them all (review 2026-11-04 RR4-01-01). The job therefore has none: the scheduler calls
|
||||||
|
* its {@code @Scheduled} method, a configuration that registers it with a task scheduler passes
|
||||||
|
* {@code job::run}, and a message handler implements the platform's {@code MessageHandler}, which
|
||||||
|
* is a project type. Anonymous and local classes are exempt: no bean has their type, and a
|
||||||
|
* function a system caller hands out from inside itself is reached only through the caller.
|
||||||
|
*/
|
||||||
|
@ArchTest
|
||||||
|
static final ArchRule SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES =
|
||||||
|
classes()
|
||||||
|
.that(ARE_SYSTEM_CALLERS)
|
||||||
|
.and()
|
||||||
|
.areNotAnonymousClasses()
|
||||||
|
.and()
|
||||||
|
.areNotLocalClasses()
|
||||||
|
.should(haveNoSupertypeOutsideTheProject())
|
||||||
|
.as(
|
||||||
|
"SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES: a @SystemCaller extends and implements "
|
||||||
|
+ "only project types (dev.caskeleton..), so every type it can be injected as is "
|
||||||
|
+ "one USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS follows. Instead of Runnable or "
|
||||||
|
+ "ApplicationRunner, use a @Scheduled method, an @EventListener, or pass job::run "
|
||||||
|
+ "where the job is registered (manual 07 「시스템이 부르는 쓰기」)")
|
||||||
|
.allowEmptyShould(true);
|
||||||
|
|
||||||
|
private static ArchCondition<JavaClass> haveNoSupertypeOutsideTheProject() {
|
||||||
|
return new ArchCondition<>("have no supertype outside the project") {
|
||||||
|
@Override
|
||||||
|
public void check(JavaClass item, ConditionEvents events) {
|
||||||
|
Set<String> foreign = new TreeSet<>();
|
||||||
|
for (JavaClass superclass : item.getAllRawSuperclasses()) {
|
||||||
|
if (!superclass.isEquivalentTo(Object.class)
|
||||||
|
&& !superclass.getName().startsWith(PROJECT_PACKAGE_PREFIX)) {
|
||||||
|
foreign.add(superclass.getName());
|
||||||
|
}
|
||||||
|
}
|
||||||
|
for (JavaClass type : item.getAllRawInterfaces()) {
|
||||||
|
if (!type.getName().startsWith(PROJECT_PACKAGE_PREFIX)) {
|
||||||
|
foreign.add(type.getName());
|
||||||
|
}
|
||||||
|
}
|
||||||
|
if (!foreign.isEmpty()) {
|
||||||
|
events.add(
|
||||||
|
SimpleConditionEvent.violated(
|
||||||
|
item,
|
||||||
|
item.getName()
|
||||||
|
+ " is a @SystemCaller with supertypes outside the project "
|
||||||
|
+ foreign
|
||||||
|
+ "; an endpoint injecting it as one of them is invisible to "
|
||||||
|
+ "USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS"));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* {@link IntegrationEventDrafts} is where contract id, version, destination and correlation are
|
* {@link IntegrationEventDrafts} is where contract id, version, destination and correlation are
|
||||||
* decided for every feature. A feature that calls the ten-field draft constructor itself restates
|
* decided for every feature. A feature that calls the ten-field draft constructor itself restates
|
||||||
|
|||||||
+1
@@ -165,6 +165,7 @@ class ArchRuleDiscoveryContractTest {
|
|||||||
"SHARED_CONTRACT_CONTAINS_ONLY_OPERATIONAL_CONTRACT_PACKAGES",
|
"SHARED_CONTRACT_CONTAINS_ONLY_OPERATIONAL_CONTRACT_PACKAGES",
|
||||||
"STARTUP_FAILURES_ARE_RAISED_THROUGH_THE_TYPED_FACTORY",
|
"STARTUP_FAILURES_ARE_RAISED_THROUGH_THE_TYPED_FACTORY",
|
||||||
"SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS",
|
"SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS",
|
||||||
|
"SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES",
|
||||||
"SYSTEM_INVOKED_USE_CASES_DECLARE_NO_PERMISSION",
|
"SYSTEM_INVOKED_USE_CASES_DECLARE_NO_PERMISSION",
|
||||||
"TEMPLATE_PACKAGES_DO_NOT_DEPEND_ON_FEATURE_PACKAGES",
|
"TEMPLATE_PACKAGES_DO_NOT_DEPEND_ON_FEATURE_PACKAGES",
|
||||||
"THROWABLES_ARE_NAMED_EXCEPTION",
|
"THROWABLES_ARE_NAMED_EXCEPTION",
|
||||||
|
|||||||
+158
@@ -8,16 +8,25 @@ import com.tngtech.archunit.lang.EvaluationResult;
|
|||||||
import dev.caskeleton.application.architecture.violations.ApplicationDiagnosticFrameworkViolation;
|
import dev.caskeleton.application.architecture.violations.ApplicationDiagnosticFrameworkViolation;
|
||||||
import dev.caskeleton.bootstrap.architecture.allowed.adapter.inbound.messaging.SystemCallerHandlerFixture;
|
import dev.caskeleton.bootstrap.architecture.allowed.adapter.inbound.messaging.SystemCallerHandlerFixture;
|
||||||
import dev.caskeleton.bootstrap.architecture.allowed.adapter.inbound.messaging.SystemCallerHandlerRegistrationFixture;
|
import dev.caskeleton.bootstrap.architecture.allowed.adapter.inbound.messaging.SystemCallerHandlerRegistrationFixture;
|
||||||
|
import dev.caskeleton.bootstrap.architecture.allowed.adapter.inbound.web.PingControllerFixture;
|
||||||
import dev.caskeleton.bootstrap.architecture.allowed.application.CleanProjectionQueryPort;
|
import dev.caskeleton.bootstrap.architecture.allowed.application.CleanProjectionQueryPort;
|
||||||
|
import dev.caskeleton.bootstrap.architecture.allowed.configuration.SystemCallerBesideControllerRegistrationFixture;
|
||||||
|
import dev.caskeleton.bootstrap.architecture.allowed.configuration.SystemCallerBesideWebMvcRegistrationFixture;
|
||||||
import dev.caskeleton.bootstrap.architecture.fixtures.application.RootWriteTransactionBoundaryUseCase;
|
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.SystemCallerRestControllerFixture;
|
||||||
import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.messaging.UnmarkedSystemInvokedHandlerFixture;
|
import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.messaging.UnmarkedSystemInvokedHandlerFixture;
|
||||||
|
import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.scheduler.IndirectlyRunnableSystemJobFixture;
|
||||||
|
import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.scheduler.InterfaceExposedSystemJobFixture;
|
||||||
|
import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.scheduler.RunNowJobFixture;
|
||||||
|
import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.scheduler.RunnableSystemJobFixture;
|
||||||
|
import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.scheduler.ScheduledWorkFixture;
|
||||||
import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.scheduler.SystemCallerWithNestedEndpointFixture;
|
import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.scheduler.SystemCallerWithNestedEndpointFixture;
|
||||||
import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.scheduler.SystemJobLauncherFixture;
|
import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.scheduler.SystemJobLauncherFixture;
|
||||||
import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.web.controller.SystemCallerControllerFixture;
|
import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.web.controller.SystemCallerControllerFixture;
|
||||||
import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.web.controller.SystemCallerInvokingControllerFixture;
|
import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.web.controller.SystemCallerInvokingControllerFixture;
|
||||||
import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.web.controller.SystemCallerRelayingControllerFixture;
|
import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.web.controller.SystemCallerRelayingControllerFixture;
|
||||||
import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.web.controller.SystemInvokedCallingControllerFixture;
|
import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.web.controller.SystemInvokedCallingControllerFixture;
|
||||||
|
import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.web.controller.SystemJobInterfaceInvokingControllerFixture;
|
||||||
import dev.caskeleton.bootstrap.architecture.violations.adapter.outbound.RawExternalResponseFixture;
|
import dev.caskeleton.bootstrap.architecture.violations.adapter.outbound.RawExternalResponseFixture;
|
||||||
import dev.caskeleton.bootstrap.architecture.violations.adapter.outbound.messaging.GenericTypeLeakingAdapterFixture;
|
import dev.caskeleton.bootstrap.architecture.violations.adapter.outbound.messaging.GenericTypeLeakingAdapterFixture;
|
||||||
import dev.caskeleton.bootstrap.architecture.violations.application.BulkWriteWithoutWriteAccessUseCase;
|
import dev.caskeleton.bootstrap.architecture.violations.application.BulkWriteWithoutWriteAccessUseCase;
|
||||||
@@ -219,6 +228,54 @@ class ArchitectureViolationFixtureTest {
|
|||||||
SystemCallerHandlerFixture.class,
|
SystemCallerHandlerFixture.class,
|
||||||
SystemInvokedFixtureUseCase.class);
|
SystemInvokedFixtureUseCase.class);
|
||||||
|
|
||||||
|
// Review 2026-11-04 RR4-01-02: a feature configuration that registers its handler beside its web
|
||||||
|
// beans. A configuration is the composition root, not a transport, whatever web type it names.
|
||||||
|
private static final JavaClasses SYSTEM_CALLER_BESIDE_WEB_MVC_REGISTRATION_FIXTURE_ONLY =
|
||||||
|
new ClassFileImporter()
|
||||||
|
.importClasses(
|
||||||
|
SystemCallerBesideWebMvcRegistrationFixture.class,
|
||||||
|
SystemCallerHandlerFixture.class,
|
||||||
|
SystemInvokedFixtureUseCase.class);
|
||||||
|
|
||||||
|
private static final JavaClasses SYSTEM_CALLER_BESIDE_CONTROLLER_REGISTRATION_FIXTURE_ONLY =
|
||||||
|
new ClassFileImporter()
|
||||||
|
.importClasses(
|
||||||
|
SystemCallerBesideControllerRegistrationFixture.class,
|
||||||
|
PingControllerFixture.class,
|
||||||
|
SystemCallerHandlerFixture.class,
|
||||||
|
SystemInvokedFixtureUseCase.class);
|
||||||
|
|
||||||
|
// Review 2026-11-04 RR4-01-01: the "run now" endpoint handed the job by the job's own interface.
|
||||||
|
private static final JavaClasses CONTROLLER_CALLING_A_SYSTEM_JOB_BY_INTERFACE_FIXTURE_ONLY =
|
||||||
|
new ClassFileImporter()
|
||||||
|
.importClasses(
|
||||||
|
SystemJobInterfaceInvokingControllerFixture.class,
|
||||||
|
RunNowJobFixture.class,
|
||||||
|
InterfaceExposedSystemJobFixture.class,
|
||||||
|
SystemInvokedFixtureUseCase.class);
|
||||||
|
|
||||||
|
// A system caller that is a Runnable — directly, or through a project interface that extends it.
|
||||||
|
// Nothing tells an endpoint injecting a Runnable from any other use of it, so the job may not be
|
||||||
|
// one.
|
||||||
|
private static final JavaClasses RUNNABLE_SYSTEM_JOB_FIXTURE_ONLY =
|
||||||
|
new ClassFileImporter()
|
||||||
|
.importClasses(RunnableSystemJobFixture.class, SystemInvokedFixtureUseCase.class);
|
||||||
|
|
||||||
|
private static final JavaClasses INDIRECTLY_RUNNABLE_SYSTEM_JOB_FIXTURE_ONLY =
|
||||||
|
new ClassFileImporter()
|
||||||
|
.importClasses(
|
||||||
|
IndirectlyRunnableSystemJobFixture.class,
|
||||||
|
ScheduledWorkFixture.class,
|
||||||
|
SystemInvokedFixtureUseCase.class);
|
||||||
|
|
||||||
|
// The job behind a project interface: the dependency rule follows that interface instead.
|
||||||
|
private static final JavaClasses SYSTEM_JOB_BEHIND_A_PROJECT_INTERFACE_FIXTURE_ONLY =
|
||||||
|
new ClassFileImporter()
|
||||||
|
.importClasses(
|
||||||
|
InterfaceExposedSystemJobFixture.class,
|
||||||
|
RunNowJobFixture.class,
|
||||||
|
SystemInvokedFixtureUseCase.class);
|
||||||
|
|
||||||
// An endpoint nested in a marked job: the mark exempts nested classes, so they carry its claim.
|
// An endpoint nested in a marked job: the mark exempts nested classes, so they carry its claim.
|
||||||
private static final JavaClasses ENDPOINT_NESTED_IN_A_SYSTEM_CALLER_FIXTURE_ONLY =
|
private static final JavaClasses ENDPOINT_NESTED_IN_A_SYSTEM_CALLER_FIXTURE_ONLY =
|
||||||
new ClassFileImporter()
|
new ClassFileImporter()
|
||||||
@@ -234,6 +291,13 @@ class ArchitectureViolationFixtureTest {
|
|||||||
.importPackages(
|
.importPackages(
|
||||||
"dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.messaging.jaxrs");
|
"dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.messaging.jaxrs");
|
||||||
|
|
||||||
|
// The `graphql..` entry of the transport-type list: a raw graphql-java data fetcher that names no
|
||||||
|
// other transport type. importPackages, so the compile-only graphql-java types are never linked.
|
||||||
|
private static final JavaClasses GRAPHQL_JAVA_SYSTEM_CALLER_FIXTURE_ONLY =
|
||||||
|
new ClassFileImporter()
|
||||||
|
.importPackages(
|
||||||
|
"dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.messaging.graphqljava");
|
||||||
|
|
||||||
// Review 2026-11-03 RR-01-03: one class that builds the draft by hand.
|
// Review 2026-11-03 RR-01-03: one class that builds the draft by hand.
|
||||||
private static final JavaClasses HAND_BUILT_DRAFT_FIXTURE_ONLY =
|
private static final JavaClasses HAND_BUILT_DRAFT_FIXTURE_ONLY =
|
||||||
new ClassFileImporter().importClasses(HandBuiltIntegrationEventDraftFixture.class);
|
new ClassFileImporter().importClasses(HandBuiltIntegrationEventDraftFixture.class);
|
||||||
@@ -319,6 +383,87 @@ class ArchitectureViolationFixtureTest {
|
|||||||
assertThat(result.getFailureReport().getDetails()).isEmpty();
|
assertThat(result.getFailureReport().getDetails()).isEmpty();
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aConfigurationThatRegistersASystemCallerBesideAWebMvcConfigurerMayDependOnIt() {
|
||||||
|
// when
|
||||||
|
EvaluationResult result =
|
||||||
|
ApplicationBoundaryArchitectureTest.USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS.evaluate(
|
||||||
|
SYSTEM_CALLER_BESIDE_WEB_MVC_REGISTRATION_FIXTURE_ONLY);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(result.getFailureReport().getDetails()).isEmpty();
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aConfigurationThatRegistersASystemCallerBesideAControllerMayDependOnIt() {
|
||||||
|
// when
|
||||||
|
EvaluationResult result =
|
||||||
|
ApplicationBoundaryArchitectureTest.USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS.evaluate(
|
||||||
|
SYSTEM_CALLER_BESIDE_CONTROLLER_REGISTRATION_FIXTURE_ONLY);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(result.getFailureReport().getDetails()).isEmpty();
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aControllerThatCallsASystemJobThroughTheJobsInterfaceIsCaught() {
|
||||||
|
// when
|
||||||
|
EvaluationResult result =
|
||||||
|
ApplicationBoundaryArchitectureTest.USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS.evaluate(
|
||||||
|
CONTROLLER_CALLING_A_SYSTEM_JOB_BY_INTERFACE_FIXTURE_ONLY);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(result.getFailureReport().getDetails())
|
||||||
|
.anySatisfy(
|
||||||
|
detail ->
|
||||||
|
assertThat(detail)
|
||||||
|
.contains(SystemJobInterfaceInvokingControllerFixture.class.getName())
|
||||||
|
.contains(RunNowJobFixture.class.getName()));
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aSystemCallerThatIsARunnableIsCaught() {
|
||||||
|
// when
|
||||||
|
EvaluationResult result =
|
||||||
|
ApplicationBoundaryArchitectureTest.SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES.evaluate(
|
||||||
|
RUNNABLE_SYSTEM_JOB_FIXTURE_ONLY);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(result.getFailureReport().getDetails())
|
||||||
|
.anySatisfy(
|
||||||
|
detail ->
|
||||||
|
assertThat(detail)
|
||||||
|
.contains(RunnableSystemJobFixture.class.getName())
|
||||||
|
.contains(Runnable.class.getName()));
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aSystemCallerBehindAProjectInterfaceThatExtendsRunnableIsCaught() {
|
||||||
|
// when
|
||||||
|
EvaluationResult result =
|
||||||
|
ApplicationBoundaryArchitectureTest.SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES.evaluate(
|
||||||
|
INDIRECTLY_RUNNABLE_SYSTEM_JOB_FIXTURE_ONLY);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(result.getFailureReport().getDetails())
|
||||||
|
.anySatisfy(
|
||||||
|
detail ->
|
||||||
|
assertThat(detail)
|
||||||
|
.contains(IndirectlyRunnableSystemJobFixture.class.getName())
|
||||||
|
.contains(Runnable.class.getName()));
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aSystemCallerBehindAProjectInterfacePassesTheSupertypeRule() {
|
||||||
|
// when
|
||||||
|
EvaluationResult result =
|
||||||
|
ApplicationBoundaryArchitectureTest.SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES.evaluate(
|
||||||
|
SYSTEM_JOB_BEHIND_A_PROJECT_INTERFACE_FIXTURE_ONLY);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(result.getFailureReport().getDetails()).isEmpty();
|
||||||
|
}
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
void anEndpointNestedInASystemCallerIsCaught() {
|
void anEndpointNestedInASystemCallerIsCaught() {
|
||||||
EvaluationResult result =
|
EvaluationResult result =
|
||||||
@@ -337,6 +482,19 @@ class ArchitectureViolationFixtureTest {
|
|||||||
assertThat(result.hasViolation()).isTrue();
|
assertThat(result.hasViolation()).isTrue();
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aGraphQlJavaDataFetcherMarkedAsASystemCallerIsCaught() {
|
||||||
|
// when
|
||||||
|
EvaluationResult result =
|
||||||
|
ApplicationBoundaryArchitectureTest.SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS
|
||||||
|
.evaluate(GRAPHQL_JAVA_SYSTEM_CALLER_FIXTURE_ONLY);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(result.getFailureReport().getDetails())
|
||||||
|
.anySatisfy(
|
||||||
|
detail -> assertThat(detail).contains("graphql.schema.DataFetchingEnvironment"));
|
||||||
|
}
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
void aFeatureThatBuildsAnIntegrationEventDraftByHandIsCaught() {
|
void aFeatureThatBuildsAnIntegrationEventDraftByHandIsCaught() {
|
||||||
EvaluationResult result =
|
EvaluationResult result =
|
||||||
|
|||||||
+2
-2
@@ -111,10 +111,10 @@ class TemplatePackageOwnershipRuleTest {
|
|||||||
"a name in TemplatePackageOwnership.APPLICATION_PACKAGES that no longer exists was"
|
"a name in TemplatePackageOwnership.APPLICATION_PACKAGES that no longer exists was"
|
||||||
+ " renamed or removed without the list (and the table in"
|
+ " renamed or removed without the list (and the table in"
|
||||||
+ " src/application-core/CLAUDE.md) following it")
|
+ " src/application-core/CLAUDE.md) following it")
|
||||||
.containsAll(TemplatePackageOwnership.APPLICATION_PACKAGES);
|
.containsAll(TemplatePackageOwnership.APPLICATION_PACKAGES.keySet());
|
||||||
assertThat(domain)
|
assertThat(domain)
|
||||||
.as("TemplatePackageOwnership.DOMAIN_PACKAGES names a package that no longer exists")
|
.as("TemplatePackageOwnership.DOMAIN_PACKAGES names a package that no longer exists")
|
||||||
.containsAll(TemplatePackageOwnership.DOMAIN_PACKAGES);
|
.containsAll(TemplatePackageOwnership.DOMAIN_PACKAGES.keySet());
|
||||||
}
|
}
|
||||||
|
|
||||||
private static Set<String> topLevelPackages(JavaClasses classes, String root) {
|
private static Set<String> topLevelPackages(JavaClasses classes, String root) {
|
||||||
|
|||||||
+14
@@ -0,0 +1,14 @@
|
|||||||
|
package dev.caskeleton.bootstrap.architecture.allowed.adapter.inbound.web;
|
||||||
|
|
||||||
|
import org.springframework.web.bind.annotation.GetMapping;
|
||||||
|
import org.springframework.web.bind.annotation.RestController;
|
||||||
|
|
||||||
|
/** A user transport that depends on no system caller. */
|
||||||
|
@RestController
|
||||||
|
public class PingControllerFixture {
|
||||||
|
|
||||||
|
@GetMapping("/fixture/ping")
|
||||||
|
public String ping() {
|
||||||
|
return "pong";
|
||||||
|
}
|
||||||
|
}
|
||||||
+6
@@ -0,0 +1,6 @@
|
|||||||
|
/**
|
||||||
|
* "Allowed-as-data" web endpoint for the system-caller rules: a controller in a user-transport
|
||||||
|
* package that reaches no system caller. A configuration may register it beside a system caller
|
||||||
|
* (review 2026-11-04 RR4-01-02).
|
||||||
|
*/
|
||||||
|
package dev.caskeleton.bootstrap.architecture.allowed.adapter.inbound.web;
|
||||||
+21
@@ -0,0 +1,21 @@
|
|||||||
|
package dev.caskeleton.bootstrap.architecture.allowed.configuration;
|
||||||
|
|
||||||
|
import dev.caskeleton.bootstrap.architecture.allowed.adapter.inbound.messaging.SystemCallerHandlerFixture;
|
||||||
|
import dev.caskeleton.bootstrap.architecture.allowed.adapter.inbound.web.PingControllerFixture;
|
||||||
|
import org.springframework.context.annotation.Bean;
|
||||||
|
import org.springframework.context.annotation.Configuration;
|
||||||
|
|
||||||
|
/** One feature configuration: the feature's controller and its message handler. */
|
||||||
|
@Configuration(proxyBeanMethods = false)
|
||||||
|
public class SystemCallerBesideControllerRegistrationFixture {
|
||||||
|
|
||||||
|
@Bean
|
||||||
|
PingControllerFixture pingController() {
|
||||||
|
return new PingControllerFixture();
|
||||||
|
}
|
||||||
|
|
||||||
|
@Bean
|
||||||
|
SystemCallerHandlerFixture systemCallerHandler() {
|
||||||
|
return new SystemCallerHandlerFixture();
|
||||||
|
}
|
||||||
|
}
|
||||||
+21
@@ -0,0 +1,21 @@
|
|||||||
|
package dev.caskeleton.bootstrap.architecture.allowed.configuration;
|
||||||
|
|
||||||
|
import dev.caskeleton.bootstrap.architecture.allowed.adapter.inbound.messaging.SystemCallerHandlerFixture;
|
||||||
|
import org.springframework.context.annotation.Bean;
|
||||||
|
import org.springframework.context.annotation.Configuration;
|
||||||
|
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
|
||||||
|
|
||||||
|
/** One feature configuration: a web MVC customisation and the feature's message handler. */
|
||||||
|
@Configuration(proxyBeanMethods = false)
|
||||||
|
public class SystemCallerBesideWebMvcRegistrationFixture {
|
||||||
|
|
||||||
|
@Bean
|
||||||
|
WebMvcConfigurer featureWebMvcConfigurer() {
|
||||||
|
return new WebMvcConfigurer() {};
|
||||||
|
}
|
||||||
|
|
||||||
|
@Bean
|
||||||
|
SystemCallerHandlerFixture systemCallerHandler() {
|
||||||
|
return new SystemCallerHandlerFixture();
|
||||||
|
}
|
||||||
|
}
|
||||||
+9
@@ -0,0 +1,9 @@
|
|||||||
|
/**
|
||||||
|
* "Allowed-as-data" composition for {@code USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS}: a
|
||||||
|
* feature's configuration that registers its message handler beside its web beans — a {@code
|
||||||
|
* WebMvcConfigurer}, or the feature's controller. A configuration is the composition root, not a
|
||||||
|
* way a user request comes in, so naming a web type does not make it a user transport (review
|
||||||
|
* 2026-11-04 RR4-01-02). Manual 09 「소비」 step 4 registers the handler in "this leaf's configuration
|
||||||
|
* class", which is where both kinds of bean meet.
|
||||||
|
*/
|
||||||
|
package dev.caskeleton.bootstrap.architecture.allowed.configuration;
|
||||||
+23
@@ -0,0 +1,23 @@
|
|||||||
|
package dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.messaging.graphqljava;
|
||||||
|
|
||||||
|
import dev.caskeleton.application.security.SystemCaller;
|
||||||
|
import dev.caskeleton.bootstrap.architecture.violations.application.SystemInvokedFixtureUseCase;
|
||||||
|
import graphql.schema.DataFetchingEnvironment;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Negative fixture for {@code SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS}: a raw
|
||||||
|
* graphql-java data fetcher in a system-driven package carrying the mark. It names only a {@code
|
||||||
|
* graphql..} type — no Spring for GraphQL annotation — so it is caught by that one entry of the
|
||||||
|
* transport-type list or not at all (review 2026-11-04 r6-a). Loaded with {@code importPackages}:
|
||||||
|
* graphql-java is compile-only for this source set.
|
||||||
|
*/
|
||||||
|
@SystemCaller(reason = "fixture: a graphql-java data fetcher hiding in the messaging package")
|
||||||
|
public class GraphQlJavaSystemCallerFixture {
|
||||||
|
|
||||||
|
private final SystemInvokedFixtureUseCase useCase = new SystemInvokedFixtureUseCase();
|
||||||
|
|
||||||
|
public Object get(DataFetchingEnvironment environment) {
|
||||||
|
useCase.handle();
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
}
|
||||||
+19
@@ -0,0 +1,19 @@
|
|||||||
|
package dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.scheduler;
|
||||||
|
|
||||||
|
import dev.caskeleton.application.security.SystemCaller;
|
||||||
|
import dev.caskeleton.bootstrap.architecture.violations.application.SystemInvokedFixtureUseCase;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Negative fixture for {@code SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES}: the job's declared
|
||||||
|
* interface is a project type, but that interface extends {@link Runnable}.
|
||||||
|
*/
|
||||||
|
@SystemCaller(reason = "fixture: registered with a task scheduler through a project interface")
|
||||||
|
public final class IndirectlyRunnableSystemJobFixture implements ScheduledWorkFixture {
|
||||||
|
|
||||||
|
private final SystemInvokedFixtureUseCase useCase = new SystemInvokedFixtureUseCase();
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public void run() {
|
||||||
|
useCase.handle();
|
||||||
|
}
|
||||||
|
}
|
||||||
+19
@@ -0,0 +1,19 @@
|
|||||||
|
package dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.scheduler;
|
||||||
|
|
||||||
|
import dev.caskeleton.application.security.SystemCaller;
|
||||||
|
import dev.caskeleton.bootstrap.architecture.violations.application.SystemInvokedFixtureUseCase;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* A marked scheduled job behind its own project interface. The job itself is a legitimate system
|
||||||
|
* caller; the violation is the endpoint that is handed it as {@link RunNowJobFixture}.
|
||||||
|
*/
|
||||||
|
@SystemCaller(reason = "fixture: the scheduler ticks it")
|
||||||
|
public final class InterfaceExposedSystemJobFixture implements RunNowJobFixture {
|
||||||
|
|
||||||
|
private final SystemInvokedFixtureUseCase useCase = new SystemInvokedFixtureUseCase();
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public void run() {
|
||||||
|
useCase.handle();
|
||||||
|
}
|
||||||
|
}
|
||||||
+11
@@ -0,0 +1,11 @@
|
|||||||
|
package dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.scheduler;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* A scheduled job's own interface: what a "run now" endpoint is handed when it injects the job by
|
||||||
|
* interface rather than by class. The dependency then points from the job to this interface, so a
|
||||||
|
* rule that only looks for the job class does not see the endpoint (review 2026-11-04 RR4-01-01).
|
||||||
|
*/
|
||||||
|
public interface RunNowJobFixture {
|
||||||
|
|
||||||
|
void run();
|
||||||
|
}
|
||||||
+21
@@ -0,0 +1,21 @@
|
|||||||
|
package dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.scheduler;
|
||||||
|
|
||||||
|
import dev.caskeleton.application.security.SystemCaller;
|
||||||
|
import dev.caskeleton.bootstrap.architecture.violations.application.SystemInvokedFixtureUseCase;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Negative fixture for {@code SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES}: a marked job that is a
|
||||||
|
* {@link Runnable}. Any class may depend on {@code Runnable}, so no dependency rule can tell an
|
||||||
|
* endpoint that injects this bean as one from any other use of the interface; the job must not be
|
||||||
|
* one (review 2026-11-04 RR4-01-01).
|
||||||
|
*/
|
||||||
|
@SystemCaller(reason = "fixture: registered with a task scheduler as a Runnable")
|
||||||
|
public final class RunnableSystemJobFixture implements Runnable {
|
||||||
|
|
||||||
|
private final SystemInvokedFixtureUseCase useCase = new SystemInvokedFixtureUseCase();
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public void run() {
|
||||||
|
useCase.handle();
|
||||||
|
}
|
||||||
|
}
|
||||||
+7
@@ -0,0 +1,7 @@
|
|||||||
|
package dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.scheduler;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* A project interface that extends {@link Runnable}: a job behind it is still a {@code Runnable}
|
||||||
|
* bean, so the supertype check reads the whole hierarchy, not only the declared interfaces.
|
||||||
|
*/
|
||||||
|
public interface ScheduledWorkFixture extends Runnable {}
|
||||||
+26
@@ -0,0 +1,26 @@
|
|||||||
|
package dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.web.controller;
|
||||||
|
|
||||||
|
import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.scheduler.RunNowJobFixture;
|
||||||
|
import org.springframework.web.bind.annotation.PostMapping;
|
||||||
|
import org.springframework.web.bind.annotation.RestController;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Negative fixture for {@code USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS}: a "run now" endpoint
|
||||||
|
* that injects the system job by its interface. It names neither the job class nor the {@code
|
||||||
|
* SystemInvoked} use case, yet a user request runs a write no permission guards (review 2026-11-04
|
||||||
|
* RR4-01-01).
|
||||||
|
*/
|
||||||
|
@RestController
|
||||||
|
public class SystemJobInterfaceInvokingControllerFixture {
|
||||||
|
|
||||||
|
private final RunNowJobFixture job;
|
||||||
|
|
||||||
|
public SystemJobInterfaceInvokingControllerFixture(RunNowJobFixture job) {
|
||||||
|
this.job = job;
|
||||||
|
}
|
||||||
|
|
||||||
|
@PostMapping("/fixture/run-now-by-interface")
|
||||||
|
public void runNow() {
|
||||||
|
job.run();
|
||||||
|
}
|
||||||
|
}
|
||||||
+59
-40
@@ -5,64 +5,80 @@ import com.tngtech.archunit.core.domain.JavaClass;
|
|||||||
import com.tngtech.archunit.lang.ArchCondition;
|
import com.tngtech.archunit.lang.ArchCondition;
|
||||||
import com.tngtech.archunit.lang.ConditionEvents;
|
import com.tngtech.archunit.lang.ConditionEvents;
|
||||||
import com.tngtech.archunit.lang.SimpleConditionEvent;
|
import com.tngtech.archunit.lang.SimpleConditionEvent;
|
||||||
|
import java.util.Map;
|
||||||
import java.util.Optional;
|
import java.util.Optional;
|
||||||
import java.util.Set;
|
import java.util.Set;
|
||||||
import java.util.TreeSet;
|
import java.util.TreeSet;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Which top-level packages under the application and domain roots the template owns, and which are
|
* Which top-level packages under the application and domain roots the template owns, which leaf
|
||||||
* a service's business features.
|
* owns each, and which packages are a service's business features.
|
||||||
*
|
*
|
||||||
* <p>This is the machine copy of the "Package ownership" table in {@code
|
* <p>This is the machine copy of the "Package ownership" tables in {@code
|
||||||
* src/application-core/CLAUDE.md}, which is the rule book. A template change that adds, renames or
|
* src/application-core/CLAUDE.md}, which are the rule book. A template change that adds, renames,
|
||||||
* removes one of these packages changes the table and this class together; {@code
|
* moves or removes one of these packages changes the table and this class together. Two tests hold
|
||||||
* TemplatePackageOwnershipRuleTest} fails when a name here no longer exists, so a rename cannot
|
* them to it: {@code TemplatePackageOwnershipDocumentTest} (document-contract lane, main stage)
|
||||||
* leave the old name behind.
|
* fails when the table and this class differ in a name or an owning leaf, or when a listed package
|
||||||
|
* is missing from the leaf the table names; {@code TemplatePackageOwnershipRuleTest}
|
||||||
|
* (architectureTest, pull request) fails when a name here exists in no production class.
|
||||||
|
*
|
||||||
|
* <p>It lives in the {@code test} source set, not in {@code architectureTest} beside the rules that
|
||||||
|
* use it, because the document-contract lane runs on the {@code test} source set and the
|
||||||
|
* architecture suite compiles against its output: one list both lanes read, rather than a copy in
|
||||||
|
* each (original review 2026-11-01 §16.3).
|
||||||
*
|
*
|
||||||
* <p>Everything under the two roots that is not listed is a business feature package, which is what
|
* <p>Everything under the two roots that is not listed is a business feature package, which is what
|
||||||
* lets a derived service add {@code dev.caskeleton.application.invoice} without touching this list.
|
* lets a derived service add {@code dev.caskeleton.application.invoice} without touching this list.
|
||||||
* The roots are parameters so the rules can be proven on fixture packages; production uses {@link
|
* The same openness is why a new template package that nobody lists cannot be caught: features are
|
||||||
* #PRODUCTION}.
|
* generated into the same leaves ({@code scripts/new-feature.sh}), so an unlisted package looks
|
||||||
|
* like one. The roots are parameters so the rules can be proven on fixture packages; production
|
||||||
|
* uses {@link #PRODUCTION}.
|
||||||
*/
|
*/
|
||||||
record TemplatePackageOwnership(String applicationRoot, String domainRoot) {
|
record TemplatePackageOwnership(String applicationRoot, String domainRoot) {
|
||||||
|
|
||||||
/** Template-owned {@code dev.caskeleton.application.<name>} packages, across every leaf. */
|
/**
|
||||||
static final Set<String> APPLICATION_PACKAGES =
|
* Template-owned {@code dev.caskeleton.application.<name>} packages, to the leaf id that owns
|
||||||
Set.of(
|
* each.
|
||||||
|
*/
|
||||||
|
static final Map<String, String> APPLICATION_PACKAGES =
|
||||||
|
Map.ofEntries(
|
||||||
// application-core: the use case kernel
|
// application-core: the use case kernel
|
||||||
"usecase",
|
Map.entry("usecase", "application-core"),
|
||||||
"command",
|
Map.entry("command", "application-core"),
|
||||||
"query",
|
Map.entry("query", "application-core"),
|
||||||
"capability",
|
Map.entry("capability", "application-core"),
|
||||||
"transaction",
|
Map.entry("transaction", "application-core"),
|
||||||
"security",
|
Map.entry("security", "application-core"),
|
||||||
"tenant",
|
Map.entry("tenant", "application-core"),
|
||||||
"observability",
|
Map.entry("observability", "application-core"),
|
||||||
"secret",
|
Map.entry("secret", "application-core"),
|
||||||
// application-core: platform features
|
// application-core: platform features
|
||||||
"messaging",
|
Map.entry("messaging", "application-core"),
|
||||||
"outbox",
|
Map.entry("outbox", "application-core"),
|
||||||
"idempotency",
|
Map.entry("idempotency", "application-core"),
|
||||||
"operation",
|
Map.entry("operation", "application-core"),
|
||||||
"lease",
|
Map.entry("lease", "application-core"),
|
||||||
"lock",
|
Map.entry("lock", "application-core"),
|
||||||
"cache",
|
Map.entry("cache", "application-core"),
|
||||||
"realtime",
|
Map.entry("realtime", "application-core"),
|
||||||
// capability leaves that share the application root
|
// capability leaves that share the application root
|
||||||
"notification",
|
Map.entry("notification", "application-notification"),
|
||||||
"fileserver",
|
Map.entry("fileserver", "application-fileserver"),
|
||||||
"objectstorage");
|
Map.entry("objectstorage", "application-objectstorage"));
|
||||||
|
|
||||||
/** Template-owned {@code dev.caskeleton.domain.<name>} packages. */
|
/**
|
||||||
static final Set<String> DOMAIN_PACKAGES = Set.of("identifier", "stereotype");
|
* Template-owned {@code dev.caskeleton.domain.<name>} packages, to the leaf id that owns each.
|
||||||
|
*/
|
||||||
|
static final Map<String, String> DOMAIN_PACKAGES =
|
||||||
|
Map.of("identifier", "domain-core", "stereotype", "domain-core");
|
||||||
|
|
||||||
static final TemplatePackageOwnership PRODUCTION =
|
static final TemplatePackageOwnership PRODUCTION =
|
||||||
new TemplatePackageOwnership("dev.caskeleton.application", "dev.caskeleton.domain");
|
new TemplatePackageOwnership("dev.caskeleton.application", "dev.caskeleton.domain");
|
||||||
|
|
||||||
/** Every name a business feature package may not take, sorted for messages. */
|
/** Every name a business feature package may not take, sorted for messages. */
|
||||||
static Set<String> templateNames() {
|
static Set<String> templateNames() {
|
||||||
Set<String> names = new TreeSet<>(APPLICATION_PACKAGES);
|
Set<String> names = new TreeSet<>(APPLICATION_PACKAGES.keySet());
|
||||||
names.addAll(DOMAIN_PACKAGES);
|
names.addAll(DOMAIN_PACKAGES.keySet());
|
||||||
return names;
|
return names;
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -99,8 +115,10 @@ record TemplatePackageOwnership(String applicationRoot, String domainRoot) {
|
|||||||
}
|
}
|
||||||
|
|
||||||
private boolean isTemplate(String packageName) {
|
private boolean isTemplate(String packageName) {
|
||||||
return segment(packageName, applicationRoot).map(APPLICATION_PACKAGES::contains).orElse(false)
|
return segment(packageName, applicationRoot)
|
||||||
|| segment(packageName, domainRoot).map(DOMAIN_PACKAGES::contains).orElse(false);
|
.map(APPLICATION_PACKAGES::containsKey)
|
||||||
|
.orElse(false)
|
||||||
|
|| segment(packageName, domainRoot).map(DOMAIN_PACKAGES::containsKey).orElse(false);
|
||||||
}
|
}
|
||||||
|
|
||||||
private boolean isFeature(String packageName) {
|
private boolean isFeature(String packageName) {
|
||||||
@@ -109,11 +127,12 @@ record TemplatePackageOwnership(String applicationRoot, String domainRoot) {
|
|||||||
|
|
||||||
private Optional<String> featureName(String packageName) {
|
private Optional<String> featureName(String packageName) {
|
||||||
Optional<String> application =
|
Optional<String> application =
|
||||||
segment(packageName, applicationRoot).filter(name -> !APPLICATION_PACKAGES.contains(name));
|
segment(packageName, applicationRoot)
|
||||||
|
.filter(name -> !APPLICATION_PACKAGES.containsKey(name));
|
||||||
if (application.isPresent()) {
|
if (application.isPresent()) {
|
||||||
return application;
|
return application;
|
||||||
}
|
}
|
||||||
return segment(packageName, domainRoot).filter(name -> !DOMAIN_PACKAGES.contains(name));
|
return segment(packageName, domainRoot).filter(name -> !DOMAIN_PACKAGES.containsKey(name));
|
||||||
}
|
}
|
||||||
|
|
||||||
/** The first package segment strictly below {@code root}, if the package is below it. */
|
/** The first package segment strictly below {@code root}, if the package is below it. */
|
||||||
+133
@@ -0,0 +1,133 @@
|
|||||||
|
package dev.caskeleton.bootstrap.architecture;
|
||||||
|
|
||||||
|
import static org.assertj.core.api.Assertions.assertThat;
|
||||||
|
|
||||||
|
import com.fasterxml.jackson.databind.JsonNode;
|
||||||
|
import com.fasterxml.jackson.databind.ObjectMapper;
|
||||||
|
import dev.caskeleton.bootstrap.contract.support.RepositoryContractResources;
|
||||||
|
import java.io.IOException;
|
||||||
|
import java.nio.file.Files;
|
||||||
|
import java.nio.file.Path;
|
||||||
|
import java.util.ArrayList;
|
||||||
|
import java.util.List;
|
||||||
|
import java.util.Map;
|
||||||
|
import java.util.TreeMap;
|
||||||
|
import java.util.regex.Matcher;
|
||||||
|
import java.util.regex.Pattern;
|
||||||
|
import org.junit.jupiter.api.Tag;
|
||||||
|
import org.junit.jupiter.api.Test;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The template package list exists twice — the "Package ownership" tables in {@code
|
||||||
|
* src/application-core/CLAUDE.md}, which people and agents read, and {@link
|
||||||
|
* TemplatePackageOwnership}, which the architecture rules read — and nothing held the two together
|
||||||
|
* (original review 2026-11-01 §16.3). Changing either one alone fails here: a name or an owning
|
||||||
|
* leaf that differs, or a listed package that is not in the leaf the table says owns it.
|
||||||
|
*
|
||||||
|
* <p>A document-contract lane test (main stage): it compares the build with a repository document.
|
||||||
|
*/
|
||||||
|
@Tag("document-contract")
|
||||||
|
class TemplatePackageOwnershipDocumentTest {
|
||||||
|
|
||||||
|
private static final String RULE_BOOK = "src/application-core/CLAUDE.md";
|
||||||
|
private static final String REGISTRY = "src/config/architecture/modules.json";
|
||||||
|
private static final String APPLICATION_TABLE = "| Package (`dev.caskeleton.application.*`) |";
|
||||||
|
private static final String DOMAIN_TABLE = "| Package (`dev.caskeleton.domain.*`) |";
|
||||||
|
private static final Pattern PACKAGE_NAME = Pattern.compile("`([a-z][a-z0-9]*)`");
|
||||||
|
|
||||||
|
private final Path root = RepositoryContractResources.fromSystemProperty().repositoryRoot();
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void theApplicationTableAndTheMachineCopyNameTheSamePackagesAndOwningLeaves() throws IOException {
|
||||||
|
// when
|
||||||
|
Map<String, String> table = ownershipTable(APPLICATION_TABLE);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(table)
|
||||||
|
.as(
|
||||||
|
"the application table in %s and TemplatePackageOwnership.APPLICATION_PACKAGES differ;"
|
||||||
|
+ " the table is the rule book, change both in the same commit",
|
||||||
|
RULE_BOOK)
|
||||||
|
.isEqualTo(new TreeMap<>(TemplatePackageOwnership.APPLICATION_PACKAGES));
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void theDomainTableAndTheMachineCopyNameTheSamePackagesAndOwningLeaves() throws IOException {
|
||||||
|
// when
|
||||||
|
Map<String, String> table = ownershipTable(DOMAIN_TABLE);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(table)
|
||||||
|
.as(
|
||||||
|
"the domain table in %s and TemplatePackageOwnership.DOMAIN_PACKAGES differ; the table"
|
||||||
|
+ " is the rule book, change both in the same commit",
|
||||||
|
RULE_BOOK)
|
||||||
|
.isEqualTo(new TreeMap<>(TemplatePackageOwnership.DOMAIN_PACKAGES));
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void everyListedPackageIsInTheLeafTheTableSaysOwnsIt() throws IOException {
|
||||||
|
// given
|
||||||
|
Map<String, Path> leafSources = leafSourcePaths();
|
||||||
|
List<Path> listed = new ArrayList<>();
|
||||||
|
ownershipTable(APPLICATION_TABLE)
|
||||||
|
.forEach(
|
||||||
|
(name, leaf) -> listed.add(packageDirectory(leafSources, leaf, "application", name)));
|
||||||
|
ownershipTable(DOMAIN_TABLE)
|
||||||
|
.forEach((name, leaf) -> listed.add(packageDirectory(leafSources, leaf, "domain", name)));
|
||||||
|
|
||||||
|
// when
|
||||||
|
List<Path> missing =
|
||||||
|
listed.stream().filter(directory -> !Files.isDirectory(root.resolve(directory))).toList();
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(missing)
|
||||||
|
.as(
|
||||||
|
"packages %s lists are not in the leaf its \"Owning leaf\" column names; a package was"
|
||||||
|
+ " moved or removed without the table (and TemplatePackageOwnership) following it",
|
||||||
|
RULE_BOOK)
|
||||||
|
.isEmpty();
|
||||||
|
}
|
||||||
|
|
||||||
|
/** One ownership table of the rule book: package name to owning leaf id. */
|
||||||
|
private Map<String, String> ownershipTable(String header) throws IOException {
|
||||||
|
List<String> lines = Files.readAllLines(root.resolve(RULE_BOOK));
|
||||||
|
int start = -1;
|
||||||
|
for (int i = 0; i < lines.size(); i++) {
|
||||||
|
if (lines.get(i).startsWith(header)) {
|
||||||
|
start = i;
|
||||||
|
break;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
assertThat(start).as("%s has no table headed %s", RULE_BOOK, header).isNotNegative();
|
||||||
|
Map<String, String> owners = new TreeMap<>();
|
||||||
|
// header, then the |---| separator, then rows until the first line that is not a row
|
||||||
|
for (int i = start + 2; i < lines.size() && lines.get(i).startsWith("|"); i++) {
|
||||||
|
String[] cells = lines.get(i).split("\\|", -1);
|
||||||
|
String leaf = cells[2].strip();
|
||||||
|
Matcher name = PACKAGE_NAME.matcher(cells[1]);
|
||||||
|
while (name.find()) {
|
||||||
|
owners.put(name.group(1), leaf);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
assertThat(owners).as("the table headed %s in %s has no rows", header, RULE_BOOK).isNotEmpty();
|
||||||
|
return owners;
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Leaf id to its repository-relative source directory, from the module registry. */
|
||||||
|
private Map<String, Path> leafSourcePaths() throws IOException {
|
||||||
|
JsonNode registry = new ObjectMapper().readTree(root.resolve(REGISTRY).toFile());
|
||||||
|
Map<String, Path> sources = new TreeMap<>();
|
||||||
|
for (JsonNode module : registry.get("modules")) {
|
||||||
|
sources.put(module.get("id").asText(), Path.of(module.get("source_path").asText()));
|
||||||
|
}
|
||||||
|
return sources;
|
||||||
|
}
|
||||||
|
|
||||||
|
private static Path packageDirectory(
|
||||||
|
Map<String, Path> leafSources, String leaf, String rootPackage, String name) {
|
||||||
|
Path source = leafSources.get(leaf);
|
||||||
|
assertThat(source).as("owning leaf '%s' is not registered in %s", leaf, REGISTRY).isNotNull();
|
||||||
|
return source.resolve(Path.of("src", "main", "java", "dev", "caskeleton", rootPackage, name));
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -160,9 +160,15 @@ Enforcement:
|
|||||||
- `NamingConventionTest.TEMPLATE_PACKAGES_DO_NOT_DEPEND_ON_FEATURE_PACKAGES`: a feature class written
|
- `NamingConventionTest.TEMPLATE_PACKAGES_DO_NOT_DEPEND_ON_FEATURE_PACKAGES`: a feature class written
|
||||||
into a template package keeps the template's name but imports its own domain, and that import is
|
into a template package keeps the template's name but imports its own domain, and that import is
|
||||||
what fails.
|
what fails.
|
||||||
- The machine copy of these tables is `TemplatePackageOwnership` (app-bootstrap `architectureTest`).
|
- These tables are the rule book; the machine copy the rules read is `TemplatePackageOwnership`
|
||||||
`TemplatePackageOwnershipRuleTest` fails when it names a package that no longer exists; a new
|
(app-bootstrap `src/test`, so both the architecture suite and the document-contract lane see it).
|
||||||
template package joins both the tables and that class in the same change.
|
`TemplatePackageOwnershipDocumentTest` (document-contract lane, `mainCheck`) fails when the tables
|
||||||
|
and that class differ in a package name or owning leaf, or when a listed package is not in the
|
||||||
|
leaf the table names; `TemplatePackageOwnershipRuleTest` (architectureTest) fails when a listed
|
||||||
|
name exists in no production class. A new template package joins both in the same change.
|
||||||
|
- Not caught: a new template package that nobody lists. Features are generated into the same leaves
|
||||||
|
(`scripts/new-feature.sh`), so an unlisted package is indistinguishable from a feature. Listing it
|
||||||
|
is part of adding it.
|
||||||
- Rejected alternatives: allowing only the listed top-level packages (every derived feature would
|
- Rejected alternatives: allowing only the listed top-level packages (every derived feature would
|
||||||
have to edit the template's list — a merge conflict per feature), and a separate
|
have to edit the template's list — a merge conflict per feature), and a separate
|
||||||
`application-platform` leaf for the platform packages (review 2026-11-01 01-10 (b): clearer
|
`application-platform` leaf for the platform packages (review 2026-11-01 01-10 (b): clearer
|
||||||
@@ -209,8 +215,12 @@ it. Its system caller constructs it — a composition module for a scheduler, a
|
|||||||
enforced — a `@SystemInvoked` bean fails startup, an inbound adapter that depends on one without
|
enforced — a `@SystemInvoked` bean fails startup, an inbound adapter that depends on one without
|
||||||
being a `@SystemCaller` fails `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`,
|
being a `@SystemCaller` fails `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`,
|
||||||
`SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS` keeps the mark (and classes nested in a marked
|
`SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS` keeps the mark (and classes nested in a marked
|
||||||
one) off user transports, and `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS` keeps a user transport
|
one) off user transports, `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS` keeps a user transport
|
||||||
from calling a system caller. A composition with `@RequiresPermission`
|
from calling a system caller (by its class or by a project interface it implements), and
|
||||||
|
`SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES` keeps a system caller from being a `Runnable` or any
|
||||||
|
other type outside the project, which no dependency rule could follow. Paths that name no type (a
|
||||||
|
bean looked up by name, a function a configuration hands over) are not seen; manual 07 lists them
|
||||||
|
and what holds them. A composition with `@RequiresPermission`
|
||||||
beans but no enforcing advisor fails startup too (`composition:service-runtime`
|
beans but no enforcing advisor fails startup too (`composition:service-runtime`
|
||||||
`PermissionEnforcementGuard`, both checks).
|
`PermissionEnforcementGuard`, both checks).
|
||||||
|
|
||||||
@@ -272,8 +282,10 @@ generation; the V1 `IdempotencyScope`/`tryBegin` API is gone.
|
|||||||
could not prove the outcome, so do not blindly retry.
|
could not prove the outcome, so do not blindly retry.
|
||||||
- Every store answers an execution whose processing lease ran out with `RecoveryRequired` and never
|
- Every store answers an execution whose processing lease ran out with `RecoveryRequired` and never
|
||||||
takes it over; only a claim that never started or a retryable failure is taken over. The answer
|
takes it over; only a claim that never started or a retryable failure is taken over. The answer
|
||||||
leaves the record to its holder: the holder's late `complete`/`markFailed` is recorded, a lease that
|
leaves the record to its holder: the holder's first late `complete`/`markFailed` is recorded, a
|
||||||
ran out is not renewed (owner decision 2026-11-04). A record lives for the lease plus the replay TTL. `IdempotencyStoreContract` holds Redis and PostgreSQL to both on
|
lease that ran out is not renewed and a claim whose lease ran out is not started — both answer
|
||||||
|
`LEASE_EXPIRED`, not `NOT_OWNER`, and the executor turns a refused start into "not applied"
|
||||||
|
(owner decision 2026-11-04, re-review RR5-01-02·03). A record lives for the lease plus the replay TTL. `IdempotencyStoreContract` holds Redis and PostgreSQL to both on
|
||||||
real servers; the in-memory fake models no time, so it runs only the contract's time-free cases
|
real servers; the in-memory fake models no time, so it runs only the contract's time-free cases
|
||||||
(re-review 2026-11-04 RR-01-11, RR-03-11, RR3-03-04).
|
(re-review 2026-11-04 RR-01-11, RR-03-11, RR3-03-04).
|
||||||
|
|
||||||
|
|||||||
@@ -269,7 +269,11 @@ application 계층이 claim·replay·복구 **정책** 을 소유하고, 저장
|
|||||||
한 번 실행됐을지 모르는 작업을 재시도로 두 번 돌리지 않기 위해서다.
|
한 번 실행됐을지 모르는 작업을 재시도로 두 번 돌리지 않기 위해서다.
|
||||||
- processing lease 와 replay TTL 은 따로 간다. 만료된 `CLAIMED` 만 다른 caller 가 가져갈 수 있고,
|
- processing lease 와 replay TTL 은 따로 간다. 만료된 `CLAIMED` 만 다른 caller 가 가져갈 수 있고,
|
||||||
만료된 `EXECUTING` 은 다른 caller 에게 `RECOVERY_REQUIRED` 로 답하되 기록은 그대로 둔다. 주인이 늦게
|
만료된 `EXECUTING` 은 다른 caller 에게 `RECOVERY_REQUIRED` 로 답하되 기록은 그대로 둔다. 주인이 늦게
|
||||||
보고한 결과·실패는 기록된다(2026-11-04 소유자 결정).
|
보고한 결과·실패는 기록된다 — 먼저 온 보고 하나만 남고 뒤의 보고는 거절된다(2026-11-04 소유자 결정,
|
||||||
|
재리뷰 RR5-01-03). lease 가 이미 끝났으면 주인도 시작(`markExecutionStarted`)과 `renew` 를 할 수 없고
|
||||||
|
`LEASE_EXPIRED` 를 받는다. 이 값은 `NOT_OWNER`(기록이 남에게 넘어감)와 다르다: 시작 전이면 아무것도
|
||||||
|
돌지 않았고 다음 claim 이 넘겨받으며, executor 는 503 `IDEMPOTENCY_UNAVAILABLE`(실행 전 거부)로 답한다.
|
||||||
|
실행 중이면 주인은 여전히 `complete`·`markFailed` 할 수 있다(RR5-01-02).
|
||||||
- 생성은 app-bootstrap `IdempotencyProviderSelectionConfig` 가 한 번 한다(`IdempotencySettings`:
|
- 생성은 app-bootstrap `IdempotencyProviderSelectionConfig` 가 한 번 한다(`IdempotencySettings`:
|
||||||
processing lease 30s, replay TTL 24h(최대 72h), failure retention 24h(replay TTL 이상), codec id `json-v2`,
|
processing lease 30s, replay TTL 24h(최대 72h), failure retention 24h(replay TTL 이상), codec id `json-v2`,
|
||||||
policy revision 2). 유스케이스나 샘플 설정이 직접 만들지 않는다.
|
policy revision 2). 유스케이스나 샘플 설정이 직접 만들지 않는다.
|
||||||
@@ -326,7 +330,7 @@ application 계층이 claim·replay·복구 **정책** 을 소유하고, 저장
|
|||||||
|
|
||||||
- `IdempotencyRequestMismatchException`(422 `IDEMPOTENT_REQUEST_MISMATCH`),
|
- `IdempotencyRequestMismatchException`(422 `IDEMPOTENT_REQUEST_MISMATCH`),
|
||||||
`IdempotencyInFlightException`(409 `IDEMPOTENT_IN_FLIGHT`),
|
`IdempotencyInFlightException`(409 `IDEMPOTENT_IN_FLIGHT`),
|
||||||
`IdempotencyUnavailableException`(store 에 닿지 못함),
|
`IdempotencyUnavailableException`(실행 전 거부: store 에 닿지 못함, 또는 claim 의 lease 가 시작 전에 끝남),
|
||||||
`IdempotencyRecoveryRequiredException`(첫 시도가 효과를 냈는지 증명하지 못함).
|
`IdempotencyRecoveryRequiredException`(첫 시도가 효과를 냈는지 증명하지 못함).
|
||||||
- 모두 **프레임워크-free, application 소유**(`AuthorizationDeniedException` 선례). web adapter 가
|
- 모두 **프레임워크-free, application 소유**(`AuthorizationDeniedException` 선례). web adapter 가
|
||||||
경계에서 HTTP 코드로 매핑한다. 진단 메시지는 scope digest 만 **로그용으로** 담고, 클라이언트에는
|
경계에서 HTTP 코드로 매핑한다. 진단 메시지는 scope digest 만 **로그용으로** 담고, 클라이언트에는
|
||||||
|
|||||||
+10
-1
@@ -170,7 +170,9 @@ public final class IdempotencyExecutor {
|
|||||||
case UNAVAILABLE -> throw new IdempotencyUnavailableException();
|
case UNAVAILABLE -> throw new IdempotencyUnavailableException();
|
||||||
// ABSENT, FAILED_RETRYABLE, ABANDONED and OPERATION_CONFLICT all mean the same thing here:
|
// ABSENT, FAILED_RETRYABLE, ABANDONED and OPERATION_CONFLICT all mean the same thing here:
|
||||||
// this caller cannot prove what happened to its own attempt, and guessing is the one thing an
|
// this caller cannot prove what happened to its own attempt, and guessing is the one thing an
|
||||||
// owner-safe store exists to prevent.
|
// owner-safe store exists to prevent. ABANDONED includes somebody else's execution whose
|
||||||
|
// lease ran out, which may still complete — this caller's attempt is not that execution
|
||||||
|
// either way, so it is not run.
|
||||||
default ->
|
default ->
|
||||||
throw recovery(request.scope(), "an indeterminate claim could not be resumed safely");
|
throw recovery(request.scope(), "an indeterminate claim could not be resumed safely");
|
||||||
};
|
};
|
||||||
@@ -190,6 +192,13 @@ public final class IdempotencyExecutor {
|
|||||||
case STARTED, ALREADY_STARTED_SAME_OPERATION ->
|
case STARTED, ALREADY_STARTED_SAME_OPERATION ->
|
||||||
runStarted(request, advanced(started, owner), action, codec);
|
runStarted(request, advanced(started, owner), action, codec);
|
||||||
case UNAVAILABLE -> throw new IdempotencyUnavailableException();
|
case UNAVAILABLE -> throw new IdempotencyUnavailableException();
|
||||||
|
// The claim's lease ran out before it started, so the store did not start it: nothing ran,
|
||||||
|
// and the next same-key request takes the claim over. "Not applied" is the truth here;
|
||||||
|
// "recovery required" would send the client after an effect that cannot exist (RR5-01-02).
|
||||||
|
case LEASE_EXPIRED ->
|
||||||
|
throw new IdempotencyUnavailableException(
|
||||||
|
"the claim's processing lease ran out before the action started; nothing ran: "
|
||||||
|
+ diagnostic(request.scope()));
|
||||||
case INDETERMINATE -> {
|
case INDETERMINATE -> {
|
||||||
if (alreadyRetried) {
|
if (alreadyRetried) {
|
||||||
throw recovery(
|
throw recovery(
|
||||||
|
|||||||
+26
-1
@@ -1,14 +1,39 @@
|
|||||||
package dev.caskeleton.application.idempotency;
|
package dev.caskeleton.application.idempotency;
|
||||||
|
|
||||||
/** Outcomes of an owner-safe processing lease renewal. */
|
/**
|
||||||
|
* Outcomes of an owner-safe processing lease renewal.
|
||||||
|
*
|
||||||
|
* <p>Each value has one meaning (re-review 2026-11-04 RR5-01-02). In particular {@link #NOT_OWNER}
|
||||||
|
* and {@link #LEASE_EXPIRED} are not the same refusal: after the first the handle is worth nothing,
|
||||||
|
* after the second its holder still completes or fails the record.
|
||||||
|
*/
|
||||||
public enum IdempotencyRenewOutcome {
|
public enum IdempotencyRenewOutcome {
|
||||||
|
/** The lease was extended; the returned handle carries the advanced revision. */
|
||||||
RENEWED(true),
|
RENEWED(true),
|
||||||
|
/** This exact renewal was already applied (a lost reply); the handle is the current one. */
|
||||||
ALREADY_RENEWED_SAME_OPERATION(true),
|
ALREADY_RENEWED_SAME_OPERATION(true),
|
||||||
|
/** No record exists: it expired, or was never there. */
|
||||||
ABSENT(false),
|
ABSENT(false),
|
||||||
|
/**
|
||||||
|
* The record belongs to somebody else, or this handle's revision is stale. The caller no longer
|
||||||
|
* holds the record.
|
||||||
|
*/
|
||||||
NOT_OWNER(false),
|
NOT_OWNER(false),
|
||||||
|
/** The record is not executing: it has not started, or it has already ended. */
|
||||||
NOT_IN_PROGRESS(false),
|
NOT_IN_PROGRESS(false),
|
||||||
|
/**
|
||||||
|
* The caller still holds the executing record, but its processing lease has already run out, so
|
||||||
|
* it is not renewed: a resend may have been answered "recovery required" since, and a lease that
|
||||||
|
* came back would answer the next one "in progress" for the same unknown effect. Nothing else
|
||||||
|
* changes — {@link IdempotencyStorePort#complete} and {@link IdempotencyStorePort#markFailed}
|
||||||
|
* with the same handle are still recorded (owner decision 2026-11-04).
|
||||||
|
*/
|
||||||
|
LEASE_EXPIRED(false),
|
||||||
|
/** The same operation id already renewed with different arguments. */
|
||||||
OPERATION_CONFLICT(false),
|
OPERATION_CONFLICT(false),
|
||||||
|
/** The store may have applied the renewal; inspect before relying on either answer. */
|
||||||
INDETERMINATE(false),
|
INDETERMINATE(false),
|
||||||
|
/** The store refused before anything could have happened. */
|
||||||
UNAVAILABLE(false);
|
UNAVAILABLE(false);
|
||||||
|
|
||||||
private final boolean carriesOwner;
|
private final boolean carriesOwner;
|
||||||
|
|||||||
+20
@@ -2,13 +2,33 @@ package dev.caskeleton.application.idempotency;
|
|||||||
|
|
||||||
/** Outcomes of the CLAIMED to EXECUTING owner-safe transition. */
|
/** Outcomes of the CLAIMED to EXECUTING owner-safe transition. */
|
||||||
public enum IdempotencyStartOutcome {
|
public enum IdempotencyStartOutcome {
|
||||||
|
/** The claim is now executing; the returned handle carries the advanced revision. */
|
||||||
STARTED(true),
|
STARTED(true),
|
||||||
|
/** This exact start was already applied (a lost reply); the handle is the current one. */
|
||||||
ALREADY_STARTED_SAME_OPERATION(true),
|
ALREADY_STARTED_SAME_OPERATION(true),
|
||||||
|
/** No record exists: it expired, was released, or was never there. */
|
||||||
ABSENT(false),
|
ABSENT(false),
|
||||||
|
/**
|
||||||
|
* The record belongs to somebody else — the claim was taken over — or this handle's revision is
|
||||||
|
* stale.
|
||||||
|
*/
|
||||||
NOT_OWNER(false),
|
NOT_OWNER(false),
|
||||||
|
/** The record is not a claim waiting to start: it is executing or has ended. */
|
||||||
NOT_CLAIMED(false),
|
NOT_CLAIMED(false),
|
||||||
|
/**
|
||||||
|
* The caller still holds the claim, but its processing lease ran out before it started, so it is
|
||||||
|
* not started and nothing ran. The lease is the window a claim has to start in: once it has run
|
||||||
|
* out the next claim takes the record over and runs it, as it does when the holder never comes
|
||||||
|
* back. Starting anyway would leave an execution that every other request is told is past its
|
||||||
|
* lease — "recovery required" instead of "in progress" — from its first moment. Both stores
|
||||||
|
* refuse the same start (re-review 2026-11-04 README 15 — the Redis store started it).
|
||||||
|
*/
|
||||||
|
LEASE_EXPIRED(false),
|
||||||
|
/** The same operation id already started this record with different arguments. */
|
||||||
OPERATION_CONFLICT(false),
|
OPERATION_CONFLICT(false),
|
||||||
|
/** The store may have applied the start; inspect before relying on either answer. */
|
||||||
INDETERMINATE(false),
|
INDETERMINATE(false),
|
||||||
|
/** The store refused before anything could have happened. */
|
||||||
UNAVAILABLE(false);
|
UNAVAILABLE(false);
|
||||||
|
|
||||||
private final boolean carriesOwner;
|
private final boolean carriesOwner;
|
||||||
|
|||||||
+9
-5
@@ -9,13 +9,17 @@ import java.time.Duration;
|
|||||||
* <p>Providers (Redis, PostgreSQL) contribute only this store; the {@link IdempotencyExecutor} that
|
* <p>Providers (Redis, PostgreSQL) contribute only this store; the {@link IdempotencyExecutor} that
|
||||||
* drives it is assembled once by the composition root.
|
* drives it is assembled once by the composition root.
|
||||||
*
|
*
|
||||||
* <p>The processing lease decides only what <em>other</em> callers are told. A claim whose lease
|
* <p>The processing lease is the window a claim has to start in, and after that it decides only
|
||||||
* ran out before it started is taken over; an execution whose lease ran out is answered {@link
|
* what <em>other</em> callers are told. A claim whose lease ran out before it started is not
|
||||||
|
* started by its holder ({@link IdempotencyStartOutcome#LEASE_EXPIRED}) and is taken over by the
|
||||||
|
* next claim; an execution whose lease ran out is answered {@link
|
||||||
* IdempotencyClaimOutcome.RecoveryRequired} and left exactly as it is, because its holder may still
|
* IdempotencyClaimOutcome.RecoveryRequired} and left exactly as it is, because its holder may still
|
||||||
* be running. The holder's {@link #complete} and {@link #markFailed} are recorded whether or not
|
* be running. The holder's {@link #complete} and {@link #markFailed} are recorded whether or not
|
||||||
* the lease has run out — the holder's last report is the one the record keeps — while {@link
|
* the lease has run out, and the record keeps the first of them — its completion or its failure,
|
||||||
* #renew} refuses a lease that has already ended. Only the record's own lifetime ends it: once it
|
* whichever comes first; a later report is refused and changes nothing. {@link #renew} refuses a
|
||||||
* is gone, every call answers {@code ABSENT} (owner decision 2026-11-04; {@code
|
* lease that has already ended ({@link IdempotencyRenewOutcome#LEASE_EXPIRED}) without taking the
|
||||||
|
* record from its holder. Only the record's own lifetime ends it: once it is gone, every call
|
||||||
|
* answers {@code ABSENT} (owner decision 2026-11-04; re-review 2026-11-04 RR5-01-02·03; {@code
|
||||||
* IdempotencyStoreContract}).
|
* IdempotencyStoreContract}).
|
||||||
*/
|
*/
|
||||||
public interface IdempotencyStorePort {
|
public interface IdempotencyStorePort {
|
||||||
|
|||||||
+8
-1
@@ -8,7 +8,10 @@ import dev.caskeleton.shared.error.OperationalError;
|
|||||||
* Fail-closed signal raised before an action when request-replay coordination is unavailable.
|
* Fail-closed signal raised before an action when request-replay coordination is unavailable.
|
||||||
*
|
*
|
||||||
* <p>Only before the action: the request certainly did not apply. A store that stops answering
|
* <p>Only before the action: the request certainly did not apply. A store that stops answering
|
||||||
* after the action ran is {@link IdempotencyCompletionUnknownException} instead.
|
* after the action ran is {@link IdempotencyCompletionUnknownException} instead. The store refusing
|
||||||
|
* to start a claim whose processing lease already ran out is the same answer for the client — the
|
||||||
|
* action did not run, and a same-key resend takes the claim over — and carries its own message, so
|
||||||
|
* a log does not send the operator after a store outage that is not there.
|
||||||
*/
|
*/
|
||||||
public final class IdempotencyUnavailableException extends RuntimeException
|
public final class IdempotencyUnavailableException extends RuntimeException
|
||||||
implements ApiErrorCarrier {
|
implements ApiErrorCarrier {
|
||||||
@@ -19,6 +22,10 @@ public final class IdempotencyUnavailableException extends RuntimeException
|
|||||||
super("idempotency coordination is unavailable");
|
super("idempotency coordination is unavailable");
|
||||||
}
|
}
|
||||||
|
|
||||||
|
IdempotencyUnavailableException(String message) {
|
||||||
|
super(message);
|
||||||
|
}
|
||||||
|
|
||||||
@Override
|
@Override
|
||||||
public ApiErrorCode errorCode() {
|
public ApiErrorCode errorCode() {
|
||||||
return OperationalError.IDEMPOTENCY_UNAVAILABLE;
|
return OperationalError.IDEMPOTENCY_UNAVAILABLE;
|
||||||
|
|||||||
+11
-5
@@ -22,11 +22,17 @@ import java.lang.annotation.Target;
|
|||||||
*
|
*
|
||||||
* <p>The marked adapter constructs the use case it calls with {@code new} from the ports it is
|
* <p>The marked adapter constructs the use case it calls with {@code new} from the ports it is
|
||||||
* given and keeps it to itself: the use case is never a bean ({@code PermissionEnforcementGuard}
|
* given and keeps it to itself: the use case is never a bean ({@code PermissionEnforcementGuard}
|
||||||
* refuses one), and no user transport depends on the adapter, directly or through other classes
|
* refuses one), and no user transport depends on the adapter or on a project type it extends or
|
||||||
* ({@code USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS}). The rules read class dependencies; a bean
|
* implements, directly or through other classes ({@code
|
||||||
* looked up at run time ({@code getBean}, {@code ObjectProvider}) is not seen. The three system
|
* USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS}). The adapter has no supertype outside the project
|
||||||
* callers and where each lives are listed in manual 07 「시스템이 부르는 쓰기」. Review 2026-11-03 RR-01-12,
|
* ({@code SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES}): not {@code Runnable}, not {@code
|
||||||
* decision 9.1; review 2026-11-04 RR3-01-01.
|
* ApplicationRunner}, because an endpoint injecting it as one of those looks like any other user of
|
||||||
|
* the interface. The rules read class dependencies, so every path that names a type is seen, {@code
|
||||||
|
* ObjectProvider} and {@code getBean(Type.class)} included; a lookup by bean name or as {@code
|
||||||
|
* Object}, and a configuration that hands a user transport a function wrapping the adapter, name
|
||||||
|
* none and are not. The three system callers, where each lives, and those unseen paths are in
|
||||||
|
* manual 07 「시스템이 부르는 쓰기」. Review 2026-11-03 RR-01-12, decision 9.1; review 2026-11-04 RR3-01-01,
|
||||||
|
* RR4-01-01.
|
||||||
*/
|
*/
|
||||||
@Documented
|
@Documented
|
||||||
@Retention(RetentionPolicy.RUNTIME)
|
@Retention(RetentionPolicy.RUNTIME)
|
||||||
|
|||||||
+5
-4
@@ -24,10 +24,11 @@ import java.lang.annotation.Target;
|
|||||||
* composition:service-runtime} {@code PermissionEnforcementGuard}), an inbound adapter that depends
|
* composition:service-runtime} {@code PermissionEnforcementGuard}), an inbound adapter that depends
|
||||||
* on it without being a {@link SystemCaller} fails the architecture rule {@code
|
* on it without being a {@link SystemCaller} fails the architecture rule {@code
|
||||||
* ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES}, and a user transport that depends on the
|
* ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES}, and a user transport that depends on the
|
||||||
* system caller fails {@code USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS} (review 2026-11-03
|
* system caller, or on a project interface it implements, fails {@code
|
||||||
* RR-01-02, RR-01-12; review 2026-11-04 RR3-01-01). It is not a way to silence the rule that a
|
* USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS} (review 2026-11-03 RR-01-02, RR-01-12; review
|
||||||
* mutating use case declares a permission: a write a user triggers declares one, and a write both a
|
* 2026-11-04 RR3-01-01, RR4-01-01). It is not a way to silence the rule that a mutating use case
|
||||||
* user and the system trigger is two use cases.
|
* declares a permission: a write a user triggers declares one, and a write both a user and the
|
||||||
|
* system trigger is two use cases.
|
||||||
*/
|
*/
|
||||||
@Documented
|
@Documented
|
||||||
@Retention(RetentionPolicy.RUNTIME)
|
@Retention(RetentionPolicy.RUNTIME)
|
||||||
|
|||||||
+37
@@ -185,6 +185,43 @@ class IdempotencyExecutorTest {
|
|||||||
assertThat(ran).isFalse();
|
assertThat(ran).isFalse();
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* A claim whose lease ran out before it started is not started, so nothing ran and the next
|
||||||
|
* same-key request takes the claim over. That is "not applied, resend with the same key" — the
|
||||||
|
* unavailable answer — and not "recovery required", which would send the client and the operator
|
||||||
|
* after an effect that cannot exist (re-review 2026-11-04 README 15, RR5-01-02).
|
||||||
|
*/
|
||||||
|
@Test
|
||||||
|
@DisplayName(
|
||||||
|
"claim의 lease가 시작 전에 끝나 시작을 거절당하면 action을 돌리지 않고 실행 전 거부(IDEMPOTENCY_UNAVAILABLE)로 알린다")
|
||||||
|
void aStartRefusedForAnExpiredLeaseIsARefusalBeforeTheActionRuns() {
|
||||||
|
// given
|
||||||
|
FakeStore store = new FakeStore();
|
||||||
|
store.claim = new IdempotencyClaimOutcome.Acquired(owner(0), LEASE_UNTIL);
|
||||||
|
store.start = IdempotencyStartOutcome.LEASE_EXPIRED;
|
||||||
|
AtomicBoolean ran = new AtomicBoolean();
|
||||||
|
|
||||||
|
// when
|
||||||
|
Throwable thrown =
|
||||||
|
catchThrowable(
|
||||||
|
() ->
|
||||||
|
executor(store)
|
||||||
|
.execute(
|
||||||
|
SCOPE,
|
||||||
|
FINGERPRINT,
|
||||||
|
ATTEMPT,
|
||||||
|
() -> {
|
||||||
|
ran.set(true);
|
||||||
|
return new IdempotentAction.Outcome.Success<>("created");
|
||||||
|
},
|
||||||
|
codec()));
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(errorCodeOf(thrown)).isEqualTo("IDEMPOTENCY_UNAVAILABLE");
|
||||||
|
assertThat(thrown).hasMessageContaining("processing lease ran out before the action started");
|
||||||
|
assertThat(ran).isFalse();
|
||||||
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* The runbook's first step for a recovery-required answer is to find the record, and the scope
|
* The runbook's first step for a recovery-required answer is to find the record, and the scope
|
||||||
* digest is the only identity the lifecycle holds; the ERROR line of a 5xx carrier prints the
|
* digest is the only identity the lifecycle holds; the ERROR line of a 5xx carrier prints the
|
||||||
|
|||||||
+160
-6
@@ -22,6 +22,7 @@ import dev.caskeleton.application.idempotency.RequestFingerprint;
|
|||||||
import dev.caskeleton.application.idempotency.StoredResponse;
|
import dev.caskeleton.application.idempotency.StoredResponse;
|
||||||
import dev.caskeleton.application.transaction.OperationId;
|
import dev.caskeleton.application.transaction.OperationId;
|
||||||
import java.time.Duration;
|
import java.time.Duration;
|
||||||
|
import java.util.Optional;
|
||||||
import java.util.function.Supplier;
|
import java.util.function.Supplier;
|
||||||
import org.junit.jupiter.api.Assumptions;
|
import org.junit.jupiter.api.Assumptions;
|
||||||
import org.junit.jupiter.api.DisplayName;
|
import org.junit.jupiter.api.DisplayName;
|
||||||
@@ -44,11 +45,17 @@ import org.junit.jupiter.api.Test;
|
|||||||
* that (re-review 2026-11-04 RR-01-11 — the Redis store took it over and ran it a second
|
* that (re-review 2026-11-04 RR-01-11 — the Redis store took it over and ran it a second
|
||||||
* time, the PostgreSQL store did not);
|
* time, the PostgreSQL store did not);
|
||||||
* <li>that answer leaves the record as it is. The execution may still be running, so its holder
|
* <li>that answer leaves the record as it is. The execution may still be running, so its holder
|
||||||
* can still record its result or its failure, and the next claim then replays or retries
|
* can still record its result or its failure — whichever it reports first — and the next
|
||||||
* accordingly; only the lease is final — the holder cannot renew it back, and an inspection
|
* claim then replays, retries or keeps answering "recovery required" accordingly; only the
|
||||||
|
* lease is final — the holder cannot renew it back ({@code LEASE_EXPIRED}), and an inspection
|
||||||
* by anyone else reports what a claim would answer (owner decision 2026-11-04: both stores
|
* by anyone else reports what a claim would answer (owner decision 2026-11-04: both stores
|
||||||
* used to abandon the record, so a first request that outlived the lease got a 500 for work
|
* used to abandon the record, so a first request that outlived the lease got a 500 for work
|
||||||
* that took effect, and its result was lost);
|
* that took effect, and its result was lost; re-review 2026-11-04 RR5-01-04: the late
|
||||||
|
* failures were not followed to the next claim);
|
||||||
|
* <li>a claim whose lease ran out before it started is not started by its holder either ({@code
|
||||||
|
* LEASE_EXPIRED}): nothing ran, so the next claim takes it over and runs it (re-review
|
||||||
|
* 2026-11-04 README 15 — the Redis store started it, the PostgreSQL store refused it as
|
||||||
|
* {@code NOT_OWNER});
|
||||||
* <li>a record outlives its processing lease by the replay TTL, whatever the two are set to. A
|
* <li>a record outlives its processing lease by the replay TTL, whatever the two are set to. A
|
||||||
* record that expired first — Redis at its key TTL, PostgreSQL at the reaper — let the next
|
* record that expired first — Redis at its key TTL, PostgreSQL at the reaper — let the next
|
||||||
* claim of a running operation acquire it fresh (re-review 2026-11-04 RR-03-11), and one that
|
* claim of a running operation acquire it fresh (re-review 2026-11-04 RR-03-11), and one that
|
||||||
@@ -369,6 +376,34 @@ public abstract class IdempotencyStoreContract {
|
|||||||
.isEqualTo(IdempotencyCompleteOutcome.RESPONSE_CONFLICT);
|
.isEqualTo(IdempotencyCompleteOutcome.RESPONSE_CONFLICT);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("완료된 기록에 주인이 실패를 뒤늦게 보고해도 기록은 완료 결과를 그대로 재생한다")
|
||||||
|
void aFailureReportedAfterTheCompletionDoesNotReplaceTheCompletedResult() {
|
||||||
|
// given
|
||||||
|
// The record keeps the holder's first final report, not its last (re-review 2026-11-04
|
||||||
|
// RR5-01-03): a store that let the later report overwrite would turn a result that took effect
|
||||||
|
// into a failure, and an unknown-effect one into a second run.
|
||||||
|
IdempotencyStorePort store = subject();
|
||||||
|
IdempotencyOwner executing = executing(store);
|
||||||
|
store.complete(
|
||||||
|
executing, new StoredResponse("{\"done\":true}"), Duration.ofHours(1), OPERATION);
|
||||||
|
store.markFailed(
|
||||||
|
executing,
|
||||||
|
IdempotencyFailureDisposition.NO_EFFECT_RETRYABLE,
|
||||||
|
Duration.ofHours(1),
|
||||||
|
OPERATION);
|
||||||
|
|
||||||
|
// when
|
||||||
|
IdempotencyClaimOutcome next =
|
||||||
|
store.claim(claim(store.newClaimAttempt(OTHER_OPERATION), FINGERPRINT));
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(next)
|
||||||
|
.isInstanceOfSatisfying(
|
||||||
|
IdempotencyClaimOutcome.CompletedReplay.class,
|
||||||
|
replay -> assertThat(replay.response().payload()).isEqualTo("{\"done\":true}"));
|
||||||
|
}
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
@DisplayName("STARTED 전이는 새 revision의 핸들을 돌려준다")
|
@DisplayName("STARTED 전이는 새 revision의 핸들을 돌려준다")
|
||||||
void startingAdvancesTheRevision() {
|
void startingAdvancesTheRevision() {
|
||||||
@@ -557,7 +592,7 @@ public abstract class IdempotencyStoreContract {
|
|||||||
@DisplayName("lease가 지난 실행도 주인이 늦게 보고한 재시도 가능 실패는 기록된다")
|
@DisplayName("lease가 지난 실행도 주인이 늦게 보고한 재시도 가능 실패는 기록된다")
|
||||||
void anExpiredExecutionsHolderCanStillReportARetryableFailure() {
|
void anExpiredExecutionsHolderCanStillReportARetryableFailure() {
|
||||||
// given
|
// given
|
||||||
// The holder's last report is taken whatever it says (owner decision 2026-11-04): a failure it
|
// The holder's report is taken whatever it says (owner decision 2026-11-04): a failure it
|
||||||
// proved had no effect frees the key exactly as it would have inside the lease.
|
// proved had no effect frees the key exactly as it would have inside the lease.
|
||||||
IdempotencyStorePort store = subject();
|
IdempotencyStorePort store = subject();
|
||||||
Duration lease = processingLease();
|
Duration lease = processingLease();
|
||||||
@@ -577,6 +612,78 @@ public abstract class IdempotencyStoreContract {
|
|||||||
assertThat(outcome).isEqualTo(IdempotencyFailOutcome.MARKED_RETRYABLE);
|
assertThat(outcome).isEqualTo(IdempotencyFailOutcome.MARKED_RETRYABLE);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("lease가 지난 실행의 주인이 늦게 보고한 재시도 가능 실패 뒤에는 다음 claim이 attempt 2로 넘겨받는다")
|
||||||
|
void aLateRetryableFailureLetsTheNextClaimTakeOver() {
|
||||||
|
// given
|
||||||
|
// The late failure followed to what it promised — the next same-key request runs — which no
|
||||||
|
// case checked (re-review 2026-11-04 RR5-01-04).
|
||||||
|
IdempotencyStorePort store = subject();
|
||||||
|
Duration lease = processingLease();
|
||||||
|
IdempotencyOwner late = executingWith(store, lease, Duration.ofHours(24));
|
||||||
|
elapse(lease.multipliedBy(2));
|
||||||
|
store.claim(claim(store.newClaimAttempt(OTHER_OPERATION), FINGERPRINT, lease));
|
||||||
|
store.markFailed(
|
||||||
|
late, IdempotencyFailureDisposition.NO_EFFECT_RETRYABLE, Duration.ofHours(1), OPERATION);
|
||||||
|
|
||||||
|
// when
|
||||||
|
IdempotencyClaimOutcome next =
|
||||||
|
store.claim(claim(store.newClaimAttempt(OTHER_OPERATION), FINGERPRINT, lease));
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(next)
|
||||||
|
.isInstanceOfSatisfying(
|
||||||
|
IdempotencyClaimOutcome.TakenOverClaimed.class,
|
||||||
|
takenOver -> assertThat(takenOver.owner().attempt()).isEqualTo(2));
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("lease가 지난 실행도 주인이 늦게 보고한 효과 불명 실패는 포기로 기록된다")
|
||||||
|
void anExpiredExecutionsHolderCanStillReportAnUnknownEffect() {
|
||||||
|
// given
|
||||||
|
IdempotencyStorePort store = subject();
|
||||||
|
Duration lease = processingLease();
|
||||||
|
IdempotencyOwner late = executingWith(store, lease, Duration.ofHours(24));
|
||||||
|
elapse(lease.multipliedBy(2));
|
||||||
|
store.claim(claim(store.newClaimAttempt(OTHER_OPERATION), FINGERPRINT, lease));
|
||||||
|
|
||||||
|
// when
|
||||||
|
IdempotencyFailOutcome outcome =
|
||||||
|
store.markFailed(
|
||||||
|
late,
|
||||||
|
IdempotencyFailureDisposition.EFFECT_UNKNOWN_ABANDONED,
|
||||||
|
Duration.ofHours(1),
|
||||||
|
OPERATION);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(outcome).isEqualTo(IdempotencyFailOutcome.MARKED_ABANDONED);
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("lease가 지난 실행의 주인이 늦게 보고한 효과 불명 실패 뒤에도 다음 claim은 회복 필요를 받는다")
|
||||||
|
void aLateUnknownEffectKeepsTheNextClaimInRecovery() {
|
||||||
|
// given
|
||||||
|
// The other half of RR5-01-04: an unknown effect reported late must not free the key. A store
|
||||||
|
// that recorded it as retryable would let the next claim run the work a second time.
|
||||||
|
IdempotencyStorePort store = subject();
|
||||||
|
Duration lease = processingLease();
|
||||||
|
IdempotencyOwner late = executingWith(store, lease, Duration.ofHours(24));
|
||||||
|
elapse(lease.multipliedBy(2));
|
||||||
|
store.claim(claim(store.newClaimAttempt(OTHER_OPERATION), FINGERPRINT, lease));
|
||||||
|
store.markFailed(
|
||||||
|
late,
|
||||||
|
IdempotencyFailureDisposition.EFFECT_UNKNOWN_ABANDONED,
|
||||||
|
Duration.ofHours(1),
|
||||||
|
OPERATION);
|
||||||
|
|
||||||
|
// when
|
||||||
|
IdempotencyClaimOutcome next =
|
||||||
|
store.claim(claim(store.newClaimAttempt(OTHER_OPERATION), FINGERPRINT, lease));
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(next).isInstanceOf(IdempotencyClaimOutcome.RecoveryRequired.class);
|
||||||
|
}
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
@DisplayName("다른 요청이 lease가 지난 남의 실행을 inspect하면 claim과 같이 회복 필요(ABANDONED)로 보고된다")
|
@DisplayName("다른 요청이 lease가 지난 남의 실행을 inspect하면 claim과 같이 회복 필요(ABANDONED)로 보고된다")
|
||||||
void inspectingAnotherHoldersExpiredExecutionReportsWhatAClaimWouldAnswer() {
|
void inspectingAnotherHoldersExpiredExecutionReportsWhatAClaimWouldAnswer() {
|
||||||
@@ -612,8 +719,55 @@ public abstract class IdempotencyStoreContract {
|
|||||||
var renewed = store.renew(late, lease, OPERATION);
|
var renewed = store.renew(late, lease, OPERATION);
|
||||||
|
|
||||||
// then
|
// then
|
||||||
assertThat(renewed.outcome()).isNotEqualTo(IdempotencyRenewOutcome.RENEWED);
|
// LEASE_EXPIRED, not NOT_OWNER: the holder still owns the record and still completes it
|
||||||
assertThat(renewed.owner()).isEmpty();
|
// (RR5-01-02).
|
||||||
|
assertThat(renewed)
|
||||||
|
.extracting(IdempotencyMutationResult::outcome, IdempotencyMutationResult::owner)
|
||||||
|
.containsExactly(IdempotencyRenewOutcome.LEASE_EXPIRED, Optional.empty());
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("처리 lease가 지난 실행 전 claim은 주인도 시작할 수 없다")
|
||||||
|
void aClaimWhoseLeaseRanOutBeforeItStartedIsNotStarted() {
|
||||||
|
// given
|
||||||
|
// Starting it would leave an execution every other request is told is past its lease, from
|
||||||
|
// its first moment (re-review 2026-11-04 README 15: the Redis store started it).
|
||||||
|
IdempotencyStorePort store = subject();
|
||||||
|
Duration lease = processingLease();
|
||||||
|
IdempotencyOwner claimed =
|
||||||
|
ownerOf(store.claim(claim(store.newClaimAttempt(OPERATION), FINGERPRINT, lease)));
|
||||||
|
elapse(lease.multipliedBy(2));
|
||||||
|
|
||||||
|
// when
|
||||||
|
IdempotencyMutationResult<IdempotencyStartOutcome> started =
|
||||||
|
store.markExecutionStarted(claimed, OPERATION);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(started)
|
||||||
|
.extracting(IdempotencyMutationResult::outcome, IdempotencyMutationResult::owner)
|
||||||
|
.containsExactly(IdempotencyStartOutcome.LEASE_EXPIRED, Optional.empty());
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("lease가 지나 시작을 거절당한 claim은 아무것도 실행하지 않았으므로 다음 claim이 attempt 2로 넘겨받는다")
|
||||||
|
void aClaimWhoseLateStartWasRefusedIsTakenOverByTheNextClaim() {
|
||||||
|
// given
|
||||||
|
IdempotencyStorePort store = subject();
|
||||||
|
Duration lease = processingLease();
|
||||||
|
IdempotencyOwner claimed =
|
||||||
|
ownerOf(store.claim(claim(store.newClaimAttempt(OPERATION), FINGERPRINT, lease)));
|
||||||
|
elapse(lease.multipliedBy(2));
|
||||||
|
store.markExecutionStarted(claimed, OPERATION);
|
||||||
|
|
||||||
|
// when
|
||||||
|
IdempotencyClaimOutcome next =
|
||||||
|
store.claim(claim(store.newClaimAttempt(OTHER_OPERATION), FINGERPRINT, lease));
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(next)
|
||||||
|
.isInstanceOfSatisfying(
|
||||||
|
IdempotencyClaimOutcome.TakenOverClaimed.class,
|
||||||
|
takenOver -> assertThat(takenOver.owner().attempt()).isEqualTo(2));
|
||||||
}
|
}
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
|
|||||||
@@ -16,7 +16,7 @@ capability, and the files it reads are declared as that test task's inputs.
|
|||||||
| `ca.java-library` / `ca.spring-library` / `ca.spring-config` | leaf-level composition of the Java/quality conventions for plain and Spring libraries |
|
| `ca.java-library` / `ca.spring-library` / `ca.spring-config` | leaf-level composition of the Java/quality conventions for plain and Spring libraries |
|
||||||
| `ca.platform-module` / `ca.grpc-platform-module` | what a vendored platform leaf (`messaging:*`, `grpc:*`, `grpc-advanced:*`) is: `java-library`, plus the gRPC BOM for the leaves that had it |
|
| `ca.platform-module` / `ca.grpc-platform-module` | what a vendored platform leaf (`messaging:*`, `grpc:*`, `grpc-advanced:*`) is: `java-library`, plus the gRPC BOM for the leaves that had it |
|
||||||
| `ca.strict-test-lane` | the one "named tests ran, none skipped" mechanism: tagged / named / own-source-set `Test` lanes that fail when they execute nothing, miss a `requires` class, or (with `rejectSkipped`) skip anything. `mainStage()` moves a tagged lane out of `test` into the leaf's `mainCheck`; `explicitOnly(reason)` keeps a lane that needs an outside input out of every aggregate, and the aggregate prints the reason. Extra test source sets are Gradle `jvm-test-suite` suites declared in the leaf (`testing { suites { … } }`); a lane named after its suite makes the suite's own `Test` task strict, and `ca.java-conventions` gives every suite the BOM's JUnit |
|
| `ca.strict-test-lane` | the one "named tests ran, none skipped" mechanism: tagged / named / own-source-set `Test` lanes that fail when they execute nothing, miss a `requires` class, or (with `rejectSkipped`) skip anything. `mainStage()` moves a tagged lane out of `test` into the leaf's `mainCheck`; `explicitOnly(reason)` keeps a lane that needs an outside input out of every aggregate, and the aggregate prints the reason. Extra test source sets are Gradle `jvm-test-suite` suites declared in the leaf (`testing { suites { … } }`); a lane named after its suite makes the suite's own `Test` task strict, and `ca.java-conventions` gives every suite the BOM's JUnit |
|
||||||
| `ca.strict-lane-stages` (root of each build with strict lanes: the main build and optional-platforms) | the other half of the lane mechanism: `verifyStrictLaneStages --dry-run` fails when a strict lane of that build that is not `explicitOnly` is in the task plan of no declared stage that a workflow executes, or when a declared stage is executed by no workflow. A `--dry-run`, a command for another build (the build a command starts is its step's `working-directory`, or the job's or workflow's `defaults.run.working-directory`, moved by each `cd <literal relative path>` the same `run:` shell surely ran before it — alone on its line, before `;`, or joined to the command by `&&` alone — then joined with `-p`; the plugin reads this build's own directory from where it sits under the repository that holds `.github/workflows`), a command after a directory change the reader does not follow (`cd "$VAR"`, `cd -`, `cd ~`, an absolute path, `pushd`/`popd`, a `cd` inside `if`/`for`/`while`/`case`, `{ }` or after a subshell, one joined with `||` or `|`, and the lines after a `cd` that shares an `&&` list with other commands — not guessed, and the failure names each such command with its reason), a command under `continue-on-error` or an `if:` other than `always()`/`success()`/`!cancelled()`, and a command of a workflow that starts only on `workflow_dispatch` do not count, and a lane the command removes with `-x` is not covered — matched the way Gradle matches task and project names, abbreviations included (`TaskSelectors`, a copy of Gradle's internal `NameMatcher`). A `run:` input of a `uses:` step is not a command. The plan is Gradle's own; the workflows are read for their `run:` steps with YAML folding applied (review 2026-11-01 08-01, 2026-11-03 RR-06-03/04, 2026-11-04 RR2-04-04, owner decision 2026-11-04 on `cd`) |
|
| `ca.strict-lane-stages` (root of each build with strict lanes: the main build and optional-platforms) | the other half of the lane mechanism: `verifyStrictLaneStages --dry-run` fails when a strict lane of that build that is not `explicitOnly` is in the task plan of no declared stage that a workflow executes, or when a declared stage is executed by no workflow. The `run:` scripts are parsed as bash (`ShellScript`: quotes, comments, heredoc bodies, substitutions and compound commands are read as the shell reads them, so a `cd` in a heredoc or a string is data). A `--dry-run` (also a bundle such as `-qm`), a command line Gradle rejects (`-mx`: only the first letter of a bundle takes a value; the reader follows Gradle 9.0's parser, probed in round 9), a command for another build (the build a command starts is its step's `working-directory`, or the job's or workflow's `defaults.run.working-directory`, moved by each `cd <literal relative path>` the same `run:` shell surely ran before it — alone in its list, or before the command in the same `&&` list — then joined with `-p`; the plugin reads this build's own directory from where it sits under the repository that holds `.github/workflows`), a command after a directory change the reader does not follow (`cd "$VAR"`, `cd -`, `cd ~`, an absolute path, `pushd`/`popd`, `builtin cd`, `eval`/`source`, a `cd` anywhere inside a compound command or a function body, one joined with `\|\|`, piped or in the background, and the lines after a `cd` that shares an `&&` list with other commands — not guessed), a command whose failure cannot fail its step (`\|\| true` or any `\|\|`, a pipe's left side without `pipefail` — on with `shell: bash` or a top-level `set -o pipefail` —, `!`, `&`, the condition or body of `if`/`while`/`for`/`case`, a function body, `$( )`, `bash -c`, after `set +e` or a top-level `exit`, and an `&&` list that is not the script's last command; a step whose `shell:` is not the default, `bash` or `sh`), a command under `continue-on-error` or an `if:` other than `always()`/`success()`/`!cancelled()`, and a command of a workflow that starts only on `workflow_dispatch` do not count — the failure names every command that names the stage but does not execute it, with its reason or the other build it starts, and a lane the command removes with `-x` is not covered — matched the way Gradle matches task and project names, abbreviations included (`TaskSelectors`, a copy of Gradle's internal `NameMatcher`). A `run:` input of a `uses:` step is not a command. The plan is Gradle's own; the workflows are read for their `run:` steps with YAML folding applied (review 2026-11-01 08-01, 2026-11-03 RR-06-03/04, 2026-11-04 RR2-04-04, owner decision 2026-11-04 on `cd`, RR5-02-01/02/03 in round 9) |
|
||||||
| `ca.redis-topology-lane` | the Redis topology lane (mode selection, `-P` property validation, per-mode required classes) the redis-sdk-topology workflow drives |
|
| `ca.redis-topology-lane` | the Redis topology lane (mode selection, `-P` property validation, per-mode required classes) the redis-sdk-topology workflow drives |
|
||||||
| `ca.api-surface` | read-only public API surface verification with a separate update task, wired into the leaf's `check` (owner decision 20); optionally holds other leaves' imports to a reviewed adopter subset (`adopterBaseline`) |
|
| `ca.api-surface` | read-only public API surface verification with a separate update task, wired into the leaf's `check` (owner decision 20); optionally holds other leaves' imports to a reviewed adopter subset (`adopterBaseline`) |
|
||||||
| `ca.config-contract` | app-bootstrap's `verifyEnvKeys` (moved from the deleted build-tools included build; owner decision 4 keeps the task in app-bootstrap) |
|
| `ca.config-contract` | app-bootstrap's `verifyEnvKeys` (moved from the deleted build-tools included build; owner decision 4 keeps the task in app-bootstrap) |
|
||||||
|
|||||||
File diff suppressed because it is too large
Load Diff
+20
-13
@@ -33,16 +33,19 @@ import org.gradle.api.execution.TaskExecutionGraph;
|
|||||||
* as a workflow runs it — a lane the command removes with {@code -x} is not covered, matched
|
* as a workflow runs it — a lane the command removes with {@code -x} is not covered, matched
|
||||||
* the way Gradle matches it, abbreviations included ({@link TaskSelectors});
|
* the way Gradle matches it, abbreviations included ({@link TaskSelectors});
|
||||||
* <li>every declared stage is executed by a workflow — a {@code --dry-run}, a command for another
|
* <li>every declared stage is executed by a workflow — a {@code --dry-run}, a command for another
|
||||||
* build, a command under {@code continue-on-error} or an {@code if:} other than a status
|
* build, a command whose failure cannot fail its step ({@code || true}, a pipe without
|
||||||
* function, and a command of a workflow that starts only on {@code workflow_dispatch} do not
|
* {@code pipefail}, an {@code if} condition and the other shapes {@code ShellScript} names),
|
||||||
* count (review 2026-11-03 RR-06-04, 2026-11-04 RR2-04-04).
|
* a command line Gradle rejects, a command under {@code continue-on-error} or an {@code if:}
|
||||||
|
* other than a status function, and a command of a workflow that starts only on {@code
|
||||||
|
* workflow_dispatch} do not count (review 2026-11-03 RR-06-04, 2026-11-04 RR2-04-04 and
|
||||||
|
* RR5-02-02).
|
||||||
* </ol>
|
* </ol>
|
||||||
*
|
*
|
||||||
* <p>Each build that holds strict lanes applies it at its own root: the main build, and the
|
* <p>Each build that holds strict lanes applies it at its own root: the main build, and the
|
||||||
* optional-platforms build. A command executes this build when it starts in this build's directory
|
* optional-platforms build. A command executes this build when it starts in this build's directory
|
||||||
* — its step's {@code working-directory}, moved by the {@code cd} commands the same shell surely
|
* — its step's {@code working-directory}, moved by the {@code cd} commands the same shell surely
|
||||||
* ran before it, joined with its {@code -p}, from the repository root, which is where GitHub keeps
|
* ran before it, joined with its {@code -p}, from the repository root, which is where GitHub keeps
|
||||||
* {@code .github/workflows} ({@link WorkflowGradleInvocations} says which {@code cd} it follows).
|
* {@code .github/workflows} ({@code ShellScript} says which {@code cd} it follows).
|
||||||
* A stage named only by commands that do not count is reported with each command's reason. Applied
|
* A stage named only by commands that do not count is reported with each command's reason. Applied
|
||||||
* to the main build only, it said "every strict lane" while the optional build's performance lane
|
* to the main build only, it said "every strict lane" while the optional build's performance lane
|
||||||
* ran nowhere (RR-06-03).</p>
|
* ran nowhere (RR-06-03).</p>
|
||||||
@@ -148,10 +151,10 @@ public final class StrictLaneStagesPlugin implements Plugin<Project> {
|
|||||||
+ " for the build in "
|
+ " for the build in "
|
||||||
+ buildDirectory
|
+ buildDirectory
|
||||||
+ " (a --dry-run, a command started in another directory, a command after a cd this"
|
+ " (a --dry-run, a command started in another directory, a command after a cd this"
|
||||||
+ " check does not follow, a command under continue-on-error or an if: other than"
|
+ " check does not follow, a command whose failure cannot fail its step, a command"
|
||||||
+ " always()/success()/!cancelled(), and a workflow that starts only on"
|
+ " under continue-on-error or an if: other than always()/success()/!cancelled(),"
|
||||||
+ " workflow_dispatch do not count)"
|
+ " and a workflow that starts only on workflow_dispatch do not count)"
|
||||||
+ notCounted(invocationsByWorkflow, stage));
|
+ notCounted(invocationsByWorkflow, stage, buildDirectory));
|
||||||
continue;
|
continue;
|
||||||
}
|
}
|
||||||
Task stageTask = root.getTasks().findByPath(stage);
|
Task stageTask = root.getTasks().findByPath(stage);
|
||||||
@@ -188,16 +191,20 @@ public final class StrictLaneStagesPlugin implements Plugin<Project> {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* The commands that name {@code stage} but do not count, each with why: a workflow that calls the
|
* The commands that name {@code stage} but do not execute it for this build, each with why — its
|
||||||
* stage in a way this check does not read is told so, instead of failing as if it never did.
|
* uncounted reason, the other build it starts (review 2026-11-04 RR5-02-03: a typo in a {@code cd}
|
||||||
|
* or a {@code cd src} under {@code working-directory: src} is named, not hidden), or a dry run: a
|
||||||
|
* workflow that calls the stage in a way this check does not count is told so, instead of failing
|
||||||
|
* as if it never did.
|
||||||
*/
|
*/
|
||||||
private static String notCounted(
|
private static String notCounted(
|
||||||
Map<String, List<WorkflowGradleInvocations.Invocation>> invocationsByWorkflow, String stage) {
|
Map<String, List<WorkflowGradleInvocations.Invocation>> invocationsByWorkflow,
|
||||||
|
String stage,
|
||||||
|
String buildDirectory) {
|
||||||
List<String> lines = new ArrayList<>();
|
List<String> lines = new ArrayList<>();
|
||||||
invocationsByWorkflow.forEach(
|
invocationsByWorkflow.forEach(
|
||||||
(workflow, invocations) ->
|
(workflow, invocations) ->
|
||||||
invocations.stream()
|
invocations.stream()
|
||||||
.filter(invocation -> invocation.uncountedReason() != null)
|
|
||||||
.filter(invocation -> invocation.requests(stage))
|
.filter(invocation -> invocation.requests(stage))
|
||||||
.forEach(
|
.forEach(
|
||||||
invocation ->
|
invocation ->
|
||||||
@@ -206,7 +213,7 @@ public final class StrictLaneStagesPlugin implements Plugin<Project> {
|
|||||||
+ ": gradlew "
|
+ ": gradlew "
|
||||||
+ String.join(" ", invocation.tasks())
|
+ String.join(" ", invocation.tasks())
|
||||||
+ " — "
|
+ " — "
|
||||||
+ invocation.uncountedReason())));
|
+ invocation.whyNotExecuting(buildDirectory))));
|
||||||
return lines.isEmpty()
|
return lines.isEmpty()
|
||||||
? ""
|
? ""
|
||||||
: "; commands that name it but do not count:\n " + String.join("\n ", lines);
|
: "; commands that name it but do not count:\n " + String.join("\n ", lines);
|
||||||
|
|||||||
+225
-297
@@ -6,6 +6,7 @@ import java.util.Deque;
|
|||||||
import java.util.LinkedHashSet;
|
import java.util.LinkedHashSet;
|
||||||
import java.util.List;
|
import java.util.List;
|
||||||
import java.util.Locale;
|
import java.util.Locale;
|
||||||
|
import java.util.Map;
|
||||||
import java.util.Set;
|
import java.util.Set;
|
||||||
import java.util.regex.Matcher;
|
import java.util.regex.Matcher;
|
||||||
import java.util.regex.Pattern;
|
import java.util.regex.Pattern;
|
||||||
@@ -20,28 +21,30 @@ import java.util.regex.Pattern;
|
|||||||
* dropped before anything is matched, so a task named only in a comment is not "run".
|
* dropped before anything is matched, so a task named only in a comment is not "run".
|
||||||
*
|
*
|
||||||
* <p>A command is read with what decides whether it gates anything (review 2026-11-03 RR-06-04):
|
* <p>A command is read with what decides whether it gates anything (review 2026-11-03 RR-06-04):
|
||||||
* its {@code -x} exclusions (spelled {@code -x task}, {@code -xtask}, {@code --exclude-task task}
|
* its {@code -x} exclusions and {@code -m}, read the way Gradle 9.0's command-line parser reads
|
||||||
* or {@code --exclude-task=task}, as Gradle reads them), and the {@code continue-on-error} and
|
* them (see {@code gradleInvocation}), and the {@code continue-on-error} and {@code if:} of its step
|
||||||
* {@code if:} of its step and its job. A command whose failure cannot fail the run, or that runs
|
* and its job. A command whose failure cannot fail the run, or that runs only under a condition
|
||||||
* only under a condition other than a status function, is still returned, with the reason it does
|
* other than a status function, is still returned, with the reason it does not count. So is a
|
||||||
* not count. So is a command of a workflow that starts only on {@code workflow_dispatch}: nothing
|
* command of a workflow that starts only on {@code workflow_dispatch}: nothing runs it unless
|
||||||
* runs it unless someone asks, the same reason an {@code if:} on the event name does not count
|
* someone asks, the same reason an {@code if:} on the event name does not count (review 2026-11-04
|
||||||
* (review 2026-11-04 RR2-04-04).
|
* RR2-04-04).
|
||||||
|
*
|
||||||
|
* <p>The script itself is read by {@code ShellScript}, in the shell the step runs: GitHub's default
|
||||||
|
* {@code bash -e}, {@code shell: bash} ({@code bash -eo pipefail}) or {@code shell: sh} ({@code sh
|
||||||
|
* -e}), from the step, the job's or the workflow's {@code defaults.run.shell}. A step in any other
|
||||||
|
* shell is returned with that reason (round 9). Inside the script a command counts only when its
|
||||||
|
* failure certainly fails the step — not after {@code ||}, before {@code ||}, in a pipe's left side
|
||||||
|
* without {@code pipefail}, under {@code if}/{@code while}, in the background, and so on
|
||||||
|
* (README 15, RR5-02-02) — and {@code gradlew} has to be the command, not an argument of
|
||||||
|
* {@code echo}.
|
||||||
*
|
*
|
||||||
* <p>Which build a command starts is where it starts: the step's {@code working-directory} (or the
|
* <p>Which build a command starts is where it starts: the step's {@code working-directory} (or the
|
||||||
* job's or the workflow's {@code defaults.run.working-directory}), then each {@code cd} the same
|
* job's or the workflow's {@code defaults.run.working-directory}), then each {@code cd} the same
|
||||||
* shell ran before it, then its {@code -p} (also {@code -pdir} and {@code --project-dir}), as a
|
* shell surely ran before it ({@code ShellScript} says which it follows), then its {@code -p}, as a
|
||||||
* path from the repository root (owner decision 2026-11-04). A {@code cd} is followed only when it
|
* path from the repository root (owner decision 2026-11-04). A command after a directory change
|
||||||
* is certain to have run before the command and where it went: {@code cd <literal relative path>}
|
* that is not followed gets an uncounted reason naming it, so it counts for no build. A {@code
|
||||||
* at the top level of the script, either alone on its line or before {@code ;} (GitHub runs
|
* run:} that is an input of a {@code uses:} step ({@code with: run:}) is not a shell command and is
|
||||||
* {@code bash -e}, so a failed {@code cd} ends the step), or joined to the command by {@code &&}
|
* not read.
|
||||||
* alone. Every other directory change is not guessed — {@code cd "$VAR"}, {@code cd -}, {@code cd
|
|
||||||
* ~}, an absolute path, {@code pushd}/{@code popd}, a {@code cd} inside {@code if}/{@code for}/
|
|
||||||
* {@code while}/{@code case}, braces or after a subshell, one joined with {@code ||} or {@code |},
|
|
||||||
* and one that shares an {@code &&} list with other commands, after which a failed {@code cd} lets
|
|
||||||
* the next line run in the old directory: the commands after it get an uncounted reason naming it,
|
|
||||||
* so they count for no build. A {@code run:} that is an input of a {@code uses:} step ({@code with:
|
|
||||||
* run:}) is not a shell command and is not read.
|
|
||||||
*/
|
*/
|
||||||
public final class WorkflowGradleInvocations {
|
public final class WorkflowGradleInvocations {
|
||||||
private static final Pattern RUN_KEY = Pattern.compile("^(\\s*)(?:-\\s+)?run:(.*)$");
|
private static final Pattern RUN_KEY = Pattern.compile("^(\\s*)(?:-\\s+)?run:(.*)$");
|
||||||
@@ -54,40 +57,46 @@ public final class WorkflowGradleInvocations {
|
|||||||
/** Conditions under which a step still runs on every run whose earlier steps passed. */
|
/** Conditions under which a step still runs on every run whose earlier steps passed. */
|
||||||
private static final Set<String> STATUS_CONDITIONS =
|
private static final Set<String> STATUS_CONDITIONS =
|
||||||
Set.of("always()", "success()", "!cancelled()", "true");
|
Set.of("always()", "success()", "!cancelled()", "true");
|
||||||
/** Command separators: a list ends at {@code ;} (and a line end); the others join commands. */
|
/**
|
||||||
private static final Pattern SEPARATOR = Pattern.compile(";|&&|\\|\\||\\|");
|
* Gradle 9.0's command-line options that take a value, by every name it accepts. Probed against
|
||||||
/** Words that change the shell's directory. */
|
* the 9.0.0 distribution (round 9): {@code gradle -q<letter> --unknown} answers "No argument was
|
||||||
private static final Set<String> DIRECTORY_COMMANDS = Set.of("cd", "pushd", "popd");
|
* provided" for these, and so does {@code --<name>} at the end of a command line.
|
||||||
/** A {@code cd} argument this reader follows: relative, with no variable, glob or {@code ~}. */
|
*/
|
||||||
private static final Pattern LITERAL_RELATIVE_PATH =
|
private static final Set<String> GRADLE_VALUE_OPTIONS =
|
||||||
Pattern.compile("[A-Za-z0-9._][A-Za-z0-9._/-]*");
|
|
||||||
/** Reserved words that open a compound command whose body runs conditionally or repeatedly. */
|
|
||||||
private static final Set<String> COMPOUND_OPENERS = Set.of("if", "while", "until", "{");
|
|
||||||
/** Reserved words whose compound command's first line is a header, not a command. */
|
|
||||||
private static final Set<String> COMPOUND_HEADERS = Set.of("for", "select", "case");
|
|
||||||
private static final Set<String> COMPOUND_CLOSERS = Set.of("fi", "done", "esac", "}");
|
|
||||||
private static final Set<String> COMMAND_PREFIXES =
|
|
||||||
Set.of("then", "do", "else", "elif", "!", "time");
|
|
||||||
private static final Set<String> OPTIONS_WITH_VALUE =
|
|
||||||
Set.of(
|
Set.of(
|
||||||
"-p",
|
"D", "F", "I", "M", "P", "g", "p", "x",
|
||||||
"--project-dir",
|
"system-prop", "dependency-verification", "init-script", "write-verification-metadata",
|
||||||
"-x",
|
"project-prop", "gradle-user-home", "project-dir", "exclude-task",
|
||||||
"--exclude-task",
|
"configuration-cache-problems", "console", "include-build", "max-workers", "priority",
|
||||||
"--tests",
|
"project-cache-dir", "update-locks", "warning-mode");
|
||||||
"-I",
|
/** Gradle 9.0's command-line options that take no value, probed the same way. */
|
||||||
"--init-script",
|
private static final Set<String> GRADLE_FLAGS =
|
||||||
"--warning-mode",
|
Set.of(
|
||||||
"--console",
|
"?", "a", "d", "h", "i", "m", "q", "s", "t", "v", "w", "S", "U", "V",
|
||||||
"--max-workers",
|
"help", "no-rebuild", "build-cache", "no-build-cache", "configuration-cache",
|
||||||
"-g",
|
"no-configuration-cache", "configure-on-demand", "no-configure-on-demand", "continue",
|
||||||
"--gradle-user-home",
|
"no-continue", "debug", "daemon", "no-daemon", "export-keys", "foreground", "info",
|
||||||
"-c",
|
"dry-run", "offline", "parallel", "no-parallel", "problems-report", "no-problems-report",
|
||||||
"--settings-file",
|
"profile", "property-upgrade-report", "quiet", "refresh-keys", "rerun-tasks",
|
||||||
"-b",
|
"full-stacktrace", "stacktrace", "scan", "no-scan", "status", "stop", "continuous",
|
||||||
"--build-file",
|
"refresh-dependencies", "show-version", "version", "warn", "watch-fs", "no-watch-fs",
|
||||||
"--include-build",
|
"write-locks");
|
||||||
"--priority");
|
/**
|
||||||
|
* Options of Gradle's built-in tasks that take a value. Gradle hands an option it does not know to
|
||||||
|
* the task before it; these are read with their value so that {@code help --task ci} does not
|
||||||
|
* read as running {@code ci}.
|
||||||
|
*/
|
||||||
|
private static final Set<String> TASK_OPTIONS_WITH_VALUE =
|
||||||
|
Set.of(
|
||||||
|
"tests", "task", "group", "configuration", "dependency", "type", "dsl", "project-name",
|
||||||
|
"package", "test-framework", "gradle-version", "distribution-type",
|
||||||
|
"gradle-distribution-url", "gradle-distribution-sha256-sum", "network-timeout");
|
||||||
|
/** The shells whose failure handling the reader follows, as GitHub starts them. */
|
||||||
|
private static final Map<String, ShellScript.Options> SHELLS =
|
||||||
|
Map.of(
|
||||||
|
"", new ShellScript.Options(true, false),
|
||||||
|
"bash", new ShellScript.Options(true, true),
|
||||||
|
"sh", new ShellScript.Options(true, false));
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* One Gradle command.
|
* One Gradle command.
|
||||||
@@ -132,10 +141,22 @@ public final class WorkflowGradleInvocations {
|
|||||||
* the repository root such as {@code src}.
|
* the repository root such as {@code src}.
|
||||||
*/
|
*/
|
||||||
public boolean executes(String taskPath, String buildDirectory) {
|
public boolean executes(String taskPath, String buildDirectory) {
|
||||||
return buildDirectory().equals(normalized(buildDirectory))
|
return requests(taskPath) && whyNotExecuting(buildDirectory) == null;
|
||||||
&& !dryRun
|
}
|
||||||
&& uncountedReason == null
|
|
||||||
&& requests(taskPath);
|
/**
|
||||||
|
* Why this command does not execute and gate on the tasks it names in the build in {@code
|
||||||
|
* buildDirectory}, or {@code null} when it does: its uncounted reason, another build, or a dry
|
||||||
|
* run.
|
||||||
|
*/
|
||||||
|
public String whyNotExecuting(String buildDirectory) {
|
||||||
|
if (uncountedReason != null) {
|
||||||
|
return uncountedReason;
|
||||||
|
}
|
||||||
|
if (!buildDirectory().equals(normalized(buildDirectory))) {
|
||||||
|
return "it starts the build in " + buildDirectory() + ", not " + normalized(buildDirectory);
|
||||||
|
}
|
||||||
|
return dryRun ? "it only plans the tasks (--dry-run)" : null;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** Whether the command names the task at {@code taskPath}, whatever build it starts. */
|
/** Whether the command names the task at {@code taskPath}, whatever build it starts. */
|
||||||
@@ -169,7 +190,11 @@ public final class WorkflowGradleInvocations {
|
|||||||
* The script of one {@code run:} step, the directory it runs in, and why its commands gate
|
* The script of one {@code run:} step, the directory it runs in, and why its commands gate
|
||||||
* nothing, if they do not.
|
* nothing, if they do not.
|
||||||
*/
|
*/
|
||||||
private record RunStep(String script, String workingDirectory, String uncountedReason) {}
|
private record RunStep(
|
||||||
|
String script,
|
||||||
|
String workingDirectory,
|
||||||
|
ShellScript.Options shell,
|
||||||
|
String uncountedReason) {}
|
||||||
|
|
||||||
private WorkflowGradleInvocations() {}
|
private WorkflowGradleInvocations() {}
|
||||||
|
|
||||||
@@ -182,141 +207,28 @@ public final class WorkflowGradleInvocations {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Where the shell of a {@code run:} script is: a path from the repository root ({@code null} for
|
* The Gradle commands of one step, each with where its shell is when it runs and why it does not
|
||||||
* the root), or, once a directory change is not followed, why — the first such reason is kept.
|
* count, if it does not: the step's reason first, then an unread directory, then the shell's.
|
||||||
*/
|
|
||||||
private record ShellDirectory(String path, String unread) {
|
|
||||||
static ShellDirectory at(String path) {
|
|
||||||
return new ShellDirectory(path, null);
|
|
||||||
}
|
|
||||||
|
|
||||||
ShellDirectory cd(String target) {
|
|
||||||
return unread != null
|
|
||||||
? this
|
|
||||||
: at(Invocation.normalized((path == null ? "." : path) + "/" + target));
|
|
||||||
}
|
|
||||||
|
|
||||||
ShellDirectory unreadBecause(String reason) {
|
|
||||||
return unread != null ? this : new ShellDirectory(path, reason);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
/** One command of a shell list and the operator ({@code &&}, {@code ||}, {@code |}) before it. */
|
|
||||||
private record Link(String operator, String command) {}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* The Gradle commands of one step, each starting where the step's shell is when it runs: the
|
|
||||||
* step's working directory moved by the {@code cd} commands before it that are certain to have
|
|
||||||
* run (see the class comment).
|
|
||||||
*/
|
*/
|
||||||
private static List<Invocation> stepInvocations(RunStep step) {
|
private static List<Invocation> stepInvocations(RunStep step) {
|
||||||
List<Invocation> invocations = new ArrayList<>();
|
List<Invocation> invocations = new ArrayList<>();
|
||||||
ShellDirectory shell = ShellDirectory.at(step.workingDirectory());
|
for (ShellScript.Command command :
|
||||||
int depth = 0;
|
ShellScript.commands(step.script(), step.workingDirectory(), step.shell())) {
|
||||||
boolean subshell = false;
|
String reason = step.uncountedReason();
|
||||||
for (List<Link> list : shellLists(step.script())) {
|
if (reason == null && command.unreadDirectory() != null) {
|
||||||
ShellDirectory current = shell;
|
reason = "the directory it starts in is not read: " + command.unreadDirectory();
|
||||||
String listCd = null;
|
|
||||||
int commands = 0;
|
|
||||||
for (int index = 0; index < list.size(); index++) {
|
|
||||||
Link link = list.get(index);
|
|
||||||
List<String> words = new ArrayList<>(List.of(link.command().trim().split("\\s+")));
|
|
||||||
words.removeIf(String::isEmpty);
|
|
||||||
if (words.isEmpty()) {
|
|
||||||
continue;
|
|
||||||
}
|
|
||||||
commands++;
|
|
||||||
int first = 0;
|
|
||||||
boolean header = false;
|
|
||||||
while (first < words.size()) {
|
|
||||||
String word = words.get(first);
|
|
||||||
if (COMPOUND_HEADERS.contains(word)) {
|
|
||||||
depth++;
|
|
||||||
header = true;
|
|
||||||
break;
|
|
||||||
} else if (COMPOUND_OPENERS.contains(word)) {
|
|
||||||
depth++;
|
|
||||||
} else if (COMPOUND_CLOSERS.contains(word)) {
|
|
||||||
depth = Math.max(0, depth - 1);
|
|
||||||
} else if (word.startsWith("(")) {
|
|
||||||
// Where a subshell ends is not read, so a cd anywhere after it is not followed.
|
|
||||||
subshell = true;
|
|
||||||
if (word.length() > 1) {
|
|
||||||
words.set(first, word.substring(1));
|
|
||||||
break;
|
|
||||||
}
|
|
||||||
} else if (!COMMAND_PREFIXES.contains(word)) {
|
|
||||||
break;
|
|
||||||
}
|
|
||||||
first++;
|
|
||||||
}
|
|
||||||
String text = "`" + link.command().trim() + "`";
|
|
||||||
if (listCd != null && !"&&".equals(link.operator())) {
|
|
||||||
current =
|
|
||||||
current.unreadBecause(
|
|
||||||
text + " follows " + listCd + " through " + link.operator()
|
|
||||||
+ ", so it may run where that cd did not take the shell");
|
|
||||||
}
|
|
||||||
if (words.stream()
|
|
||||||
.map(WorkflowGradleInvocations::bareWord)
|
|
||||||
.anyMatch(DIRECTORY_COMMANDS::contains)) {
|
|
||||||
listCd = text;
|
|
||||||
List<String> command = header ? List.of() : words.subList(first, words.size());
|
|
||||||
String next = index + 1 < list.size() ? list.get(index + 1).operator() : null;
|
|
||||||
String target =
|
|
||||||
command.size() == 2 && command.get(0).equals("cd")
|
|
||||||
&& LITERAL_RELATIVE_PATH.matcher(unquote(command.get(1))).matches()
|
|
||||||
? unquote(command.get(1))
|
|
||||||
: null;
|
|
||||||
if (target == null) {
|
|
||||||
current =
|
|
||||||
current.unreadBecause(
|
|
||||||
text + " is not a cd to a literal relative path (a variable, -, ~, an absolute"
|
|
||||||
+ " path, pushd and popd are not followed)");
|
|
||||||
} else if (depth > 0 || subshell) {
|
|
||||||
current =
|
|
||||||
current.unreadBecause(
|
|
||||||
text + " runs inside if/for/while/case, { } or after a subshell ( ), so whether"
|
|
||||||
+ " it ran before the command is not read");
|
|
||||||
} else if (isConditionalOrPiped(link.operator()) || isConditionalOrPiped(next)) {
|
|
||||||
current =
|
|
||||||
current.unreadBecause(
|
|
||||||
text + " is joined with || or |, so it may not have run, or ran in a subshell");
|
|
||||||
} else {
|
|
||||||
current = current.cd(target);
|
|
||||||
}
|
|
||||||
continue;
|
|
||||||
}
|
|
||||||
String reason = step.uncountedReason();
|
|
||||||
if (reason == null && current.unread() != null) {
|
|
||||||
reason = "the directory it starts in is not read: " + current.unread();
|
|
||||||
}
|
|
||||||
Invocation invocation = gradleInvocation(link.command(), current.path(), reason);
|
|
||||||
if (invocation != null) {
|
|
||||||
invocations.add(invocation);
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
if (listCd != null) {
|
if (reason == null) {
|
||||||
shell =
|
reason = command.uncountedReason();
|
||||||
commands == 1
|
}
|
||||||
? current
|
Invocation invocation = gradleInvocation(command.words(), command.directory(), reason);
|
||||||
: current.unreadBecause(
|
if (invocation != null) {
|
||||||
listCd + " shares an && list with other commands, and if it failed the shell"
|
invocations.add(invocation);
|
||||||
+ " went on to the next line in the old directory");
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
return invocations;
|
return invocations;
|
||||||
}
|
}
|
||||||
|
|
||||||
private static boolean isConditionalOrPiped(String operator) {
|
|
||||||
return "||".equals(operator) || "|".equals(operator);
|
|
||||||
}
|
|
||||||
|
|
||||||
/** A word without the quotes, parentheses and braces around it: {@code "cd} is {@code cd}. */
|
|
||||||
private static String bareWord(String word) {
|
|
||||||
return word.replaceAll("^[\"'`({]+|[\"'`)};]+$", "");
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Lines of a folded ({@code >}) {@code run:} block that start with an option right after a blank
|
* Lines of a folded ({@code >}) {@code run:} block that start with an option right after a blank
|
||||||
* line. YAML turns the blank line into a line break, so the option becomes a shell command of its
|
* line. YAML turns the blank line into a line break, so the option becomes a shell command of its
|
||||||
@@ -383,10 +295,22 @@ public final class WorkflowGradleInvocations {
|
|||||||
if (uncounted == null) {
|
if (uncounted == null) {
|
||||||
uncounted = dispatchOnly;
|
uncounted = dispatchOnly;
|
||||||
}
|
}
|
||||||
String directory = workingDirectory(lines, index);
|
String directory = runSetting(lines, index, "working-directory");
|
||||||
|
String shellName = runSetting(lines, index, "shell");
|
||||||
|
ShellScript.Options shell = SHELLS.get(shellName == null ? "" : shellName);
|
||||||
|
if (uncounted == null && shell == null) {
|
||||||
|
uncounted =
|
||||||
|
"its step runs in shell: "
|
||||||
|
+ shellName
|
||||||
|
+ ", whose failure handling this reader does not follow (only the default, bash"
|
||||||
|
+ " and sh are read)";
|
||||||
|
}
|
||||||
|
if (shell == null) {
|
||||||
|
shell = SHELLS.get("");
|
||||||
|
}
|
||||||
Matcher header = BLOCK_HEADER.matcher(value);
|
Matcher header = BLOCK_HEADER.matcher(value);
|
||||||
if (!header.matches()) {
|
if (!header.matches()) {
|
||||||
scripts.add(new RunStep(stripScalarComment(value), directory, uncounted));
|
scripts.add(new RunStep(stripScalarComment(value), directory, shell, uncounted));
|
||||||
continue;
|
continue;
|
||||||
}
|
}
|
||||||
List<String> block = new ArrayList<>();
|
List<String> block = new ArrayList<>();
|
||||||
@@ -405,6 +329,7 @@ public final class WorkflowGradleInvocations {
|
|||||||
new RunStep(
|
new RunStep(
|
||||||
header.group(1).equals("|") ? String.join("\n", content) : fold(content),
|
header.group(1).equals("|") ? String.join("\n", content) : fold(content),
|
||||||
directory,
|
directory,
|
||||||
|
shell,
|
||||||
uncounted));
|
uncounted));
|
||||||
}
|
}
|
||||||
return scripts;
|
return scripts;
|
||||||
@@ -485,31 +410,32 @@ public final class WorkflowGradleInvocations {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* The directory the {@code run:} at {@code runIndex} runs in: its step's {@code
|
* The {@code run:} setting {@code key} ({@code working-directory} or {@code shell}) of the step
|
||||||
* working-directory}, else its job's, else the workflow's {@code defaults.run.working-directory};
|
* at {@code runIndex}: its step's, else its job's {@code defaults.run}, else the workflow's;
|
||||||
* {@code null} for the repository root.
|
* {@code null} when none is written.
|
||||||
*/
|
*/
|
||||||
private static String workingDirectory(List<String> lines, int runIndex) {
|
private static String runSetting(List<String> lines, int runIndex, String key) {
|
||||||
StepScope step = stepScope(lines, runIndex);
|
StepScope step = stepScope(lines, runIndex);
|
||||||
String directory = mappingValue(lines, step.start(), step.keyIndent(), "working-directory");
|
String value = mappingValue(lines, step.start(), step.keyIndent(), key);
|
||||||
if (directory != null) {
|
if (value != null) {
|
||||||
return directory;
|
return value;
|
||||||
}
|
}
|
||||||
int jobHeader = jobHeader(lines, runIndex);
|
int jobHeader = jobHeader(lines, runIndex);
|
||||||
if (jobHeader >= 0) {
|
if (jobHeader >= 0) {
|
||||||
int jobKeyIndent = childIndent(lines, jobHeader);
|
int jobKeyIndent = childIndent(lines, jobHeader);
|
||||||
if (jobKeyIndent > indentOf(lines.get(jobHeader))) {
|
if (jobKeyIndent > indentOf(lines.get(jobHeader))) {
|
||||||
directory = defaultsWorkingDirectory(lines, jobHeader + 1, jobKeyIndent);
|
value = defaultsRunSetting(lines, jobHeader + 1, jobKeyIndent, key);
|
||||||
if (directory != null) {
|
if (value != null) {
|
||||||
return directory;
|
return value;
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
return defaultsWorkingDirectory(lines, 0, 0);
|
return defaultsRunSetting(lines, 0, 0, key);
|
||||||
}
|
}
|
||||||
|
|
||||||
/** {@code defaults.run.working-directory} of the mapping whose keys sit at {@code keyIndent}. */
|
/** {@code defaults.run.<key>} of the mapping whose keys sit at {@code keyIndent}. */
|
||||||
private static String defaultsWorkingDirectory(List<String> lines, int start, int keyIndent) {
|
private static String defaultsRunSetting(
|
||||||
|
List<String> lines, int start, int keyIndent, String key) {
|
||||||
int defaults = mappingKey(lines, start, keyIndent, "defaults");
|
int defaults = mappingKey(lines, start, keyIndent, "defaults");
|
||||||
if (defaults < 0) {
|
if (defaults < 0) {
|
||||||
return null;
|
return null;
|
||||||
@@ -521,7 +447,7 @@ public final class WorkflowGradleInvocations {
|
|||||||
}
|
}
|
||||||
int directoryIndent = childIndent(lines, run);
|
int directoryIndent = childIndent(lines, run);
|
||||||
return directoryIndent > runIndent
|
return directoryIndent > runIndent
|
||||||
? mappingValue(lines, run + 1, directoryIndent, "working-directory")
|
? mappingValue(lines, run + 1, directoryIndent, key)
|
||||||
: null;
|
: null;
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -725,119 +651,121 @@ public final class WorkflowGradleInvocations {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* The script as shell lists: a list ends at {@code ;} or at a line end that does not follow an
|
* The Gradle command a simple command runs, or {@code null} when it names no {@code gradlew}. A
|
||||||
* operator, and its commands are joined by {@code &&}, {@code ||} or {@code |}. Comments are
|
* {@code gradlew} that is not the command the shell runs ({@code echo ./gradlew ci}) is returned
|
||||||
* dropped first, so a separator inside one splits nothing.
|
* with that reason.
|
||||||
|
*
|
||||||
|
* <p>The arguments are read the way Gradle 9.0's {@code CommandLineParser} reads them (checked
|
||||||
|
* against the 9.0.0 distribution in round 9, and pinned by {@code StrictLaneStagesFunctionalTest}):
|
||||||
|
* after {@code --} every word is a task; {@code --name} and {@code --name=value} are long options,
|
||||||
|
* and Gradle also takes a short name there ({@code --m}); {@code -c=value} gives a one-letter
|
||||||
|
* option a value; a word that is a whole option name after one dash is that option ({@code
|
||||||
|
* -dry-run}); otherwise the letters are a bundle in which only the first may take a value, as
|
||||||
|
* the rest of the word ({@code -xtask}, {@code -pdir}) — {@code -qm} is a dry run, and {@code
|
||||||
|
* -mx} is a command line Gradle rejects, because {@code -x} needs a value it is not given there.
|
||||||
|
* A rejected command runs nothing, so it does not count.
|
||||||
*/
|
*/
|
||||||
private static List<List<Link>> shellLists(String script) {
|
private static Invocation gradleInvocation(
|
||||||
List<List<Link>> lists = new ArrayList<>();
|
List<String> words, String workingDirectory, String uncountedReason) {
|
||||||
List<Link> list = new ArrayList<>();
|
int at = ShellScript.commandWord(words);
|
||||||
String operator = null;
|
int start = at >= 0 && at < words.size() && isGradlew(words.get(at)) ? at : -1;
|
||||||
for (String line : script.replace("\\\n", " ").split("\n", -1)) {
|
String reason = uncountedReason;
|
||||||
String code = withoutComment(line);
|
if (start < 0) {
|
||||||
if (operator == null && !list.isEmpty()) {
|
for (int index = 0; index < words.size(); index++) {
|
||||||
lists.add(list);
|
if (isGradlew(words.get(index))) {
|
||||||
list = new ArrayList<>();
|
start = index;
|
||||||
}
|
break;
|
||||||
Matcher separator = SEPARATOR.matcher(code);
|
|
||||||
int start = 0;
|
|
||||||
while (separator.find()) {
|
|
||||||
list.add(new Link(operator, code.substring(start, separator.start())));
|
|
||||||
start = separator.end();
|
|
||||||
if (separator.group().equals(";")) {
|
|
||||||
lists.add(list);
|
|
||||||
list = new ArrayList<>();
|
|
||||||
operator = null;
|
|
||||||
} else {
|
|
||||||
operator = separator.group();
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
String rest = code.substring(start);
|
if (start < 0) {
|
||||||
if (!rest.isBlank() || operator == null) {
|
return null;
|
||||||
list.add(new Link(operator, rest));
|
|
||||||
operator = null;
|
|
||||||
}
|
}
|
||||||
}
|
if (reason == null) {
|
||||||
if (!list.isEmpty()) {
|
reason =
|
||||||
lists.add(list);
|
"it is an argument of `"
|
||||||
}
|
+ String.join(" ", words.subList(0, start))
|
||||||
return lists;
|
+ "`, not the command the shell runs";
|
||||||
}
|
|
||||||
|
|
||||||
/** The line up to a {@code #} that starts a word, which the shell reads as a comment. */
|
|
||||||
private static String withoutComment(String line) {
|
|
||||||
for (int index = 0; index < line.length(); index++) {
|
|
||||||
if (line.charAt(index) == '#'
|
|
||||||
&& (index == 0 || Character.isWhitespace(line.charAt(index - 1)))) {
|
|
||||||
return line.substring(0, index);
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
return line;
|
|
||||||
}
|
|
||||||
|
|
||||||
private static Invocation gradleInvocation(
|
|
||||||
String command, String workingDirectory, String uncountedReason) {
|
|
||||||
List<String> tokens = new ArrayList<>();
|
|
||||||
for (String token : command.trim().split("\\s+")) {
|
|
||||||
if (token.startsWith("#")) {
|
|
||||||
break;
|
|
||||||
}
|
|
||||||
if (!token.isEmpty()) {
|
|
||||||
tokens.add(unquote(token));
|
|
||||||
}
|
|
||||||
}
|
|
||||||
int start = -1;
|
|
||||||
for (int index = 0; index < tokens.size(); index++) {
|
|
||||||
if (tokens.get(index).equals("gradlew") || tokens.get(index).endsWith("/gradlew")) {
|
|
||||||
start = index;
|
|
||||||
break;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
if (start < 0) {
|
|
||||||
return null;
|
|
||||||
}
|
|
||||||
String projectDir = null;
|
String projectDir = null;
|
||||||
boolean dryRun = false;
|
boolean dryRun = false;
|
||||||
|
String rejected = null;
|
||||||
List<String> tasks = new ArrayList<>();
|
List<String> tasks = new ArrayList<>();
|
||||||
List<String> excluded = new ArrayList<>();
|
List<String> excluded = new ArrayList<>();
|
||||||
for (int index = start + 1; index < tokens.size(); index++) {
|
boolean onlyTasks = false;
|
||||||
String token = tokens.get(index);
|
for (int index = start + 1; index < words.size(); index++) {
|
||||||
if (token.equals("--dry-run") || token.equals("-m")) {
|
String word = words.get(index);
|
||||||
dryRun = true;
|
String name = null;
|
||||||
} else if (token.equals("-p") || token.equals("--project-dir")) {
|
String value = null;
|
||||||
projectDir = index + 1 < tokens.size() ? tokens.get(index + 1) : "";
|
if (onlyTasks || !word.startsWith("-") || word.equals("-")) {
|
||||||
index++;
|
tasks.add(word);
|
||||||
} else if (token.startsWith("--project-dir=")) {
|
continue;
|
||||||
projectDir = token.substring("--project-dir=".length());
|
} else if (word.equals("--")) {
|
||||||
} else if (token.equals("-x") || token.equals("--exclude-task")) {
|
onlyTasks = true;
|
||||||
if (index + 1 < tokens.size()) {
|
continue;
|
||||||
excluded.add(tokens.get(index + 1));
|
} else if (word.startsWith("--")) {
|
||||||
|
int equals = word.indexOf('=');
|
||||||
|
name = equals < 0 ? word.substring(2) : word.substring(2, equals);
|
||||||
|
value = equals < 0 ? null : word.substring(equals + 1);
|
||||||
|
if (value != null && GRADLE_FLAGS.contains(name) && rejected == null) {
|
||||||
|
rejected = "Gradle rejects " + word + ": --" + name + " takes no value";
|
||||||
|
}
|
||||||
|
} else if (word.length() > 2 && word.charAt(2) == '=') {
|
||||||
|
name = word.substring(1, 2);
|
||||||
|
value = word.substring(3);
|
||||||
|
if (GRADLE_FLAGS.contains(name) && rejected == null) {
|
||||||
|
rejected = "Gradle rejects " + word + ": -" + name + " takes no value";
|
||||||
|
}
|
||||||
|
} else if (GRADLE_VALUE_OPTIONS.contains(word.substring(1))
|
||||||
|
|| GRADLE_FLAGS.contains(word.substring(1))) {
|
||||||
|
name = word.substring(1);
|
||||||
|
} else {
|
||||||
|
String first = word.substring(1, 2);
|
||||||
|
if (GRADLE_VALUE_OPTIONS.contains(first)) {
|
||||||
|
name = first;
|
||||||
|
value = word.substring(2);
|
||||||
|
} else {
|
||||||
|
for (int letter = 1; letter < word.length(); letter++) {
|
||||||
|
String option = word.substring(letter, letter + 1);
|
||||||
|
if (!GRADLE_FLAGS.contains(option)) {
|
||||||
|
if (rejected == null) {
|
||||||
|
rejected =
|
||||||
|
"Gradle rejects "
|
||||||
|
+ word
|
||||||
|
+ ": -"
|
||||||
|
+ option
|
||||||
|
+ (GRADLE_VALUE_OPTIONS.contains(option)
|
||||||
|
? " takes a value, and only the first letter of a bundle can have one"
|
||||||
|
: " is not a Gradle option");
|
||||||
|
}
|
||||||
|
break;
|
||||||
|
}
|
||||||
|
dryRun |= option.equals("m");
|
||||||
|
}
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
if (value == null
|
||||||
|
&& (GRADLE_VALUE_OPTIONS.contains(name) || TASK_OPTIONS_WITH_VALUE.contains(name))) {
|
||||||
|
value = index + 1 < words.size() ? words.get(++index) : "";
|
||||||
|
}
|
||||||
|
switch (name) {
|
||||||
|
case "m", "dry-run" -> dryRun = true;
|
||||||
|
case "x", "exclude-task" -> excluded.add(value);
|
||||||
|
case "p", "project-dir" -> projectDir = value;
|
||||||
|
default -> {
|
||||||
|
// an option that does not decide which tasks run, or where
|
||||||
}
|
}
|
||||||
index++;
|
|
||||||
} else if (token.startsWith("--exclude-task=")) {
|
|
||||||
excluded.add(token.substring("--exclude-task=".length()));
|
|
||||||
} else if (token.startsWith("-x") && token.length() > 2) {
|
|
||||||
// Gradle takes a short option's value attached, the way it takes -Dkey=value:
|
|
||||||
// -xgrpcPerformanceTest excludes that task (review 2026-11-04 RR3-04-02).
|
|
||||||
excluded.add(token.substring(2));
|
|
||||||
} else if (token.startsWith("-p") && token.length() > 2) {
|
|
||||||
projectDir = token.substring(2);
|
|
||||||
} else if (OPTIONS_WITH_VALUE.contains(token)) {
|
|
||||||
index++;
|
|
||||||
} else if (!token.startsWith("-")) {
|
|
||||||
tasks.add(token);
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
return new Invocation(workingDirectory, projectDir, tasks, dryRun, excluded, uncountedReason);
|
if (reason == null) {
|
||||||
|
reason = rejected;
|
||||||
|
}
|
||||||
|
return new Invocation(workingDirectory, projectDir, tasks, dryRun, excluded, reason);
|
||||||
}
|
}
|
||||||
|
|
||||||
private static String unquote(String token) {
|
private static boolean isGradlew(String word) {
|
||||||
if (token.length() >= 2
|
return word.equals("gradlew") || word.endsWith("/gradlew");
|
||||||
&& (token.startsWith("'") && token.endsWith("'")
|
|
||||||
|| token.startsWith("\"") && token.endsWith("\""))) {
|
|
||||||
return token.substring(1, token.length() - 1);
|
|
||||||
}
|
|
||||||
return token;
|
|
||||||
}
|
}
|
||||||
|
|
||||||
private static int indentOf(String line) {
|
private static int indentOf(String line) {
|
||||||
|
|||||||
+111
@@ -1,6 +1,7 @@
|
|||||||
package dev.caskeleton.buildlogic.strictlane;
|
package dev.caskeleton.buildlogic.strictlane;
|
||||||
|
|
||||||
import static org.assertj.core.api.Assertions.assertThat;
|
import static org.assertj.core.api.Assertions.assertThat;
|
||||||
|
import static org.assertj.core.api.Assertions.catchThrowable;
|
||||||
|
|
||||||
import java.nio.file.Files;
|
import java.nio.file.Files;
|
||||||
import java.nio.file.Path;
|
import java.nio.file.Path;
|
||||||
@@ -494,6 +495,116 @@ class StrictLaneStagesFunctionalTest {
|
|||||||
.contains("cd \"$GITHUB_WORKSPACE/src\"");
|
.contains("cd \"$GITHUB_WORKSPACE/src\"");
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("단계를 부르지만 다른 빌드로 읽힌 명령도 실패 메시지에 그 빌드 디렉터리와 함께 적는다")
|
||||||
|
void aStageCalledForAnotherBuildIsNamedWithThatBuildInTheFailure() throws Exception {
|
||||||
|
// given
|
||||||
|
leafLanes(
|
||||||
|
"""
|
||||||
|
lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' }
|
||||||
|
""");
|
||||||
|
workflow(
|
||||||
|
"""
|
||||||
|
jobs:
|
||||||
|
main:
|
||||||
|
steps:
|
||||||
|
- run: cd src && ./gradlew ci --stacktrace
|
||||||
|
- run: cd scr && ./gradlew integrationCheck
|
||||||
|
- working-directory: src
|
||||||
|
run: cd src && ./gradlew integrationCheck
|
||||||
|
""");
|
||||||
|
|
||||||
|
// when
|
||||||
|
BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").buildAndFail();
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(result.getOutput())
|
||||||
|
.contains("stage :integrationCheck is executed by no workflow")
|
||||||
|
.contains("main.yml: gradlew integrationCheck — it starts the build in scr, not src")
|
||||||
|
.contains("main.yml: gradlew integrationCheck — it starts the build in src/src, not src");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("실패를 막지 못하는 모양으로만 부른 단계는 실행으로 세지 않고, 실패 메시지에 그 이유를 적는다")
|
||||||
|
void aStageCalledOnlyInShapesThatCannotFailTheStepFailsNamingWhy() throws Exception {
|
||||||
|
// given
|
||||||
|
leafLanes(
|
||||||
|
"""
|
||||||
|
lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' }
|
||||||
|
""");
|
||||||
|
workflow(
|
||||||
|
"""
|
||||||
|
defaults:
|
||||||
|
run:
|
||||||
|
working-directory: src
|
||||||
|
jobs:
|
||||||
|
main:
|
||||||
|
steps:
|
||||||
|
- run: ./gradlew :ci --stacktrace
|
||||||
|
- run: ./gradlew :integrationCheck || true
|
||||||
|
- run: ./gradlew :integrationCheck | tee integration.log
|
||||||
|
- run: |
|
||||||
|
if ./gradlew :integrationCheck; then echo passed; fi
|
||||||
|
""");
|
||||||
|
|
||||||
|
// when
|
||||||
|
BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").buildAndFail();
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(result.getOutput())
|
||||||
|
.contains("stage :integrationCheck is executed by no workflow")
|
||||||
|
.contains("strict lane :leaf:databaseLane is in no executed stage")
|
||||||
|
.contains("|| true")
|
||||||
|
.contains("pipefail")
|
||||||
|
.contains("condition of if");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("짧은 플래그 묶음 -qm은 Gradle이 계획만 하는 명령이고, 검사도 그 단계를 실행으로 세지 않는다")
|
||||||
|
void aBundledDryRunFlagOnlyPlansInGradleAndDoesNotCountAsAnExecution() throws Exception {
|
||||||
|
// given
|
||||||
|
leafLanes(
|
||||||
|
"""
|
||||||
|
lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' }
|
||||||
|
""");
|
||||||
|
workflow(
|
||||||
|
EXECUTING_WORKFLOW.replace(
|
||||||
|
"./gradlew :integrationCheck --continue", "./gradlew -qm :integrationCheck"));
|
||||||
|
BuildResult gradle = runner("-qm", ":ci").build();
|
||||||
|
|
||||||
|
// when
|
||||||
|
BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").buildAndFail();
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(gradle.getOutput()).contains(":leaf:test SKIPPED").contains(":ci SKIPPED");
|
||||||
|
assertThat(result.getOutput()).contains("stage :integrationCheck is executed by no workflow");
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("값을 받는 옵션이 묶음 첫 글자가 아니면 Gradle이 명령을 거부하고, 검사도 그 이유로 세지 않는다")
|
||||||
|
void aValueOptionLaterInABundleIsRejectedByGradleAndDoesNotCount() throws Exception {
|
||||||
|
// given
|
||||||
|
leafLanes(
|
||||||
|
"""
|
||||||
|
lane('databaseLane') { integration(); tag = 'db'; description = 'Real database.' }
|
||||||
|
""");
|
||||||
|
workflow(
|
||||||
|
EXECUTING_WORKFLOW.replace(
|
||||||
|
"./gradlew :integrationCheck --continue", "./gradlew -mx :leaf:test :integrationCheck"));
|
||||||
|
// TestKit reports a command line Gradle rejects as an exception, not as a failed build.
|
||||||
|
Throwable gradle = catchThrowable(() -> runner("-mx", ":leaf:test", ":ci").build());
|
||||||
|
|
||||||
|
// when
|
||||||
|
BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").buildAndFail();
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(gradle)
|
||||||
|
.hasStackTraceContaining("No argument was provided for command-line option '-x'");
|
||||||
|
assertThat(result.getOutput())
|
||||||
|
.contains("stage :integrationCheck is executed by no workflow")
|
||||||
|
.contains("Gradle rejects -mx");
|
||||||
|
}
|
||||||
|
|
||||||
private void leafLanes(String lanes) throws Exception {
|
private void leafLanes(String lanes) throws Exception {
|
||||||
Files.writeString(
|
Files.writeString(
|
||||||
gradleRoot.resolve("leaf/build.gradle"),
|
gradleRoot.resolve("leaf/build.gradle"),
|
||||||
|
|||||||
+376
@@ -497,6 +497,382 @@ class WorkflowGradleInvocationsTest {
|
|||||||
});
|
});
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("실패가 처리되거나 상태가 버려지는 gradlew는 실행으로 세지 않고 그 이유를 남긴다")
|
||||||
|
void gradlewWhoseFailureIsHandledOrDroppedDoesNotCountAndSaysWhy() {
|
||||||
|
// given
|
||||||
|
String workflow =
|
||||||
|
"""
|
||||||
|
jobs:
|
||||||
|
main:
|
||||||
|
steps:
|
||||||
|
- working-directory: src
|
||||||
|
run: ./gradlew :ci || true
|
||||||
|
- working-directory: src
|
||||||
|
run: ./gradlew :ci | tee ci.log
|
||||||
|
- working-directory: src
|
||||||
|
run: |
|
||||||
|
! ./gradlew :ci
|
||||||
|
- working-directory: src
|
||||||
|
run: ./gradlew :ci &
|
||||||
|
- working-directory: src
|
||||||
|
run: echo ./gradlew :ci
|
||||||
|
- working-directory: src
|
||||||
|
run: echo "$(./gradlew :ci)"
|
||||||
|
""";
|
||||||
|
|
||||||
|
// when
|
||||||
|
List<Invocation> invocations = WorkflowGradleInvocations.read(workflow);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(invocations)
|
||||||
|
.hasSize(6)
|
||||||
|
.allSatisfy(
|
||||||
|
invocation -> {
|
||||||
|
assertThat(invocation.requests(":ci")).isTrue();
|
||||||
|
assertThat(invocation.uncountedReason()).isNotBlank();
|
||||||
|
assertThat(invocation.executes(":ci", "src")).isFalse();
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("조건·반복·함수 본문 안에서만 도는 gradlew는 매번 실행된다고 볼 수 없으므로 세지 않는다")
|
||||||
|
void gradlewThatRunsOnlyUnderAConditionOrInALoopOrFunctionDoesNotCount() {
|
||||||
|
// given
|
||||||
|
String workflow =
|
||||||
|
"""
|
||||||
|
defaults:
|
||||||
|
run:
|
||||||
|
working-directory: src
|
||||||
|
jobs:
|
||||||
|
main:
|
||||||
|
steps:
|
||||||
|
- run: |
|
||||||
|
if ./gradlew :ci; then echo passed; fi
|
||||||
|
- run: |
|
||||||
|
while ./gradlew :ci; do break; done
|
||||||
|
- run: |
|
||||||
|
if [ -n "$RUN" ]; then
|
||||||
|
./gradlew :ci
|
||||||
|
fi
|
||||||
|
- run: |
|
||||||
|
for attempt in 1; do ./gradlew :ci; done
|
||||||
|
- run: |
|
||||||
|
case "$MODE" in
|
||||||
|
full) ./gradlew :ci ;;
|
||||||
|
esac
|
||||||
|
- run: |
|
||||||
|
gate() {
|
||||||
|
./gradlew :ci
|
||||||
|
}
|
||||||
|
""";
|
||||||
|
|
||||||
|
// when
|
||||||
|
List<Invocation> invocations = WorkflowGradleInvocations.read(workflow);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(invocations)
|
||||||
|
.hasSize(6)
|
||||||
|
.allSatisfy(
|
||||||
|
invocation -> {
|
||||||
|
assertThat(invocation.uncountedReason()).isNotBlank();
|
||||||
|
assertThat(invocation.executes(":ci", "src")).isFalse();
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("앞 명령이 실패하면 건너뛰거나 실패를 삼키는 && 목록의 gradlew는 스크립트의 마지막 명령일 때만 센다")
|
||||||
|
void gradlewInAnAndListCountsOnlyWhenTheListIsTheScriptsLastCommand() {
|
||||||
|
// given
|
||||||
|
String workflow =
|
||||||
|
"""
|
||||||
|
defaults:
|
||||||
|
run:
|
||||||
|
working-directory: src
|
||||||
|
jobs:
|
||||||
|
main:
|
||||||
|
steps:
|
||||||
|
- run: |
|
||||||
|
test -d build && ./gradlew :ci
|
||||||
|
echo done
|
||||||
|
- run: |
|
||||||
|
./gradlew :ci && echo passed
|
||||||
|
echo done
|
||||||
|
- run: test -d build && ./gradlew :ci
|
||||||
|
- run: ./gradlew :ci && echo passed
|
||||||
|
""";
|
||||||
|
|
||||||
|
// when
|
||||||
|
List<Invocation> invocations = WorkflowGradleInvocations.read(workflow);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(invocations)
|
||||||
|
.extracting(invocation -> invocation.executes(":ci", "src"))
|
||||||
|
.containsExactly(false, false, true, true);
|
||||||
|
assertThat(invocations.subList(0, 2))
|
||||||
|
.allSatisfy(invocation -> assertThat(invocation.uncountedReason()).contains("&&"));
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("exit-on-error를 끈 뒤나 최상위 exit 뒤의 gradlew는 단계를 실패시키지 못하므로 세지 않는다")
|
||||||
|
void gradlewAfterExitOnErrorIsTurnedOffOrAfterExitDoesNotCount() {
|
||||||
|
// given
|
||||||
|
String workflow =
|
||||||
|
"""
|
||||||
|
defaults:
|
||||||
|
run:
|
||||||
|
working-directory: src
|
||||||
|
jobs:
|
||||||
|
main:
|
||||||
|
steps:
|
||||||
|
- run: |
|
||||||
|
set +e
|
||||||
|
./gradlew :ci
|
||||||
|
echo done
|
||||||
|
- run: |
|
||||||
|
set +o errexit
|
||||||
|
./gradlew :ci
|
||||||
|
echo done
|
||||||
|
- run: |
|
||||||
|
exit 0
|
||||||
|
./gradlew :ci
|
||||||
|
""";
|
||||||
|
|
||||||
|
// when
|
||||||
|
List<Invocation> invocations = WorkflowGradleInvocations.read(workflow);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(invocations)
|
||||||
|
.hasSize(3)
|
||||||
|
.allSatisfy(
|
||||||
|
invocation -> {
|
||||||
|
assertThat(invocation.uncountedReason()).isNotBlank();
|
||||||
|
assertThat(invocation.executes(":ci", "src")).isFalse();
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("pipefail이 확실히 켜진 셸에서는 파이프 앞의 gradlew 실패도 단계를 실패시키므로 센다")
|
||||||
|
void gradlewPipedUnderPipefailCounts() {
|
||||||
|
// given
|
||||||
|
String workflow =
|
||||||
|
"""
|
||||||
|
jobs:
|
||||||
|
main:
|
||||||
|
steps:
|
||||||
|
- working-directory: src
|
||||||
|
shell: bash
|
||||||
|
run: ./gradlew :ci | tee ci.log
|
||||||
|
- working-directory: src
|
||||||
|
run: |
|
||||||
|
set -euo pipefail
|
||||||
|
./gradlew :ci | tee ci.log
|
||||||
|
- working-directory: src
|
||||||
|
run: |
|
||||||
|
set -o pipefail
|
||||||
|
./gradlew :ci 2>&1 | tee ci.log
|
||||||
|
defaulted:
|
||||||
|
defaults:
|
||||||
|
run:
|
||||||
|
shell: bash
|
||||||
|
working-directory: src
|
||||||
|
steps:
|
||||||
|
- run: ./gradlew :ci |& tee ci.log
|
||||||
|
""";
|
||||||
|
|
||||||
|
// when
|
||||||
|
List<Invocation> invocations = WorkflowGradleInvocations.read(workflow);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(invocations)
|
||||||
|
.hasSize(4)
|
||||||
|
.allSatisfy(
|
||||||
|
invocation -> {
|
||||||
|
assertThat(invocation.uncountedReason()).isNull();
|
||||||
|
assertThat(invocation.executes(":ci", "src")).isTrue();
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("bash와 sh 밖의 셸로 도는 단계의 gradlew는 실패 처리를 읽지 않으므로 세지 않는다")
|
||||||
|
void gradlewInAStepWhoseShellIsNotBashOrShDoesNotCount() {
|
||||||
|
// given
|
||||||
|
String workflow =
|
||||||
|
"""
|
||||||
|
jobs:
|
||||||
|
main:
|
||||||
|
steps:
|
||||||
|
- working-directory: src
|
||||||
|
shell: pwsh
|
||||||
|
run: ./gradlew :ci
|
||||||
|
- working-directory: src
|
||||||
|
shell: bash {0}
|
||||||
|
run: ./gradlew :ci
|
||||||
|
- working-directory: src
|
||||||
|
shell: sh
|
||||||
|
run: ./gradlew :ci
|
||||||
|
""";
|
||||||
|
|
||||||
|
// when
|
||||||
|
List<Invocation> invocations = WorkflowGradleInvocations.read(workflow);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(invocations).hasSize(3);
|
||||||
|
assertThat(invocations.get(0).uncountedReason()).contains("shell: pwsh");
|
||||||
|
assertThat(invocations.get(1).uncountedReason()).contains("shell: bash {0}");
|
||||||
|
assertThat(invocations.get(2).executes(":ci", "src")).isTrue();
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("셸이 그 자리에서 실행하지 않는 heredoc·여러 줄 문자열·이스케이프한 세미콜론 뒤의 cd는 따라가지 않는다")
|
||||||
|
void aCdTheShellDoesNotRunThereIsNotFollowed() {
|
||||||
|
// given
|
||||||
|
String workflow =
|
||||||
|
"""
|
||||||
|
jobs:
|
||||||
|
main:
|
||||||
|
steps:
|
||||||
|
- run: |
|
||||||
|
cat > enter.sh <<'EOF'
|
||||||
|
cd src
|
||||||
|
EOF
|
||||||
|
./gradlew :ci
|
||||||
|
- run: |
|
||||||
|
echo "first
|
||||||
|
cd src
|
||||||
|
"
|
||||||
|
./gradlew :ci
|
||||||
|
- run: echo a \\; cd src && ./gradlew :ci
|
||||||
|
""";
|
||||||
|
|
||||||
|
// when
|
||||||
|
List<Invocation> invocations = WorkflowGradleInvocations.read(workflow);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(invocations)
|
||||||
|
.hasSize(3)
|
||||||
|
.allSatisfy(
|
||||||
|
invocation -> {
|
||||||
|
assertThat(invocation.buildDirectory()).isEqualTo(".");
|
||||||
|
assertThat(invocation.executes(":ci", "src")).isFalse();
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("함수 본문의 cd는 부르는 곳을 읽지 않으므로 따라가지 않고, 그 뒤 명령은 이유를 대며 세지 않는다")
|
||||||
|
void aCdInAFunctionBodyIsNotFollowedAndTheCommandsAfterItDoNotCount() {
|
||||||
|
// given
|
||||||
|
String workflow =
|
||||||
|
"""
|
||||||
|
jobs:
|
||||||
|
main:
|
||||||
|
steps:
|
||||||
|
- run: |
|
||||||
|
enter() {
|
||||||
|
cd src
|
||||||
|
}
|
||||||
|
./gradlew :ci
|
||||||
|
""";
|
||||||
|
|
||||||
|
// when
|
||||||
|
List<Invocation> invocations = WorkflowGradleInvocations.read(workflow);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(invocations)
|
||||||
|
.singleElement()
|
||||||
|
.satisfies(
|
||||||
|
invocation -> {
|
||||||
|
assertThat(invocation.uncountedReason()).contains("cd src");
|
||||||
|
assertThat(invocation.executes(":ci", "src")).isFalse();
|
||||||
|
assertThat(invocation.executes(":ci", ".")).isFalse();
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("산술 확장·산술 명령·산술 for가 있는 스크립트도 셸 문법으로 읽어 마지막 gradlew를 센다")
|
||||||
|
void aScriptWithArithmeticIsReadAsShellAndItsLastGradlewCounts() {
|
||||||
|
// given
|
||||||
|
String workflow =
|
||||||
|
"""
|
||||||
|
jobs:
|
||||||
|
main:
|
||||||
|
steps:
|
||||||
|
- working-directory: src
|
||||||
|
run: |
|
||||||
|
echo $(( 1 + 2 )) "$(( 3 * 4 ))"
|
||||||
|
(( attempts = 1 ))
|
||||||
|
for ((i = 0; i < attempts; i++)); do echo "$i"; done
|
||||||
|
./gradlew :ci
|
||||||
|
""";
|
||||||
|
|
||||||
|
// when
|
||||||
|
List<Invocation> invocations = WorkflowGradleInvocations.read(workflow);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(invocations)
|
||||||
|
.singleElement()
|
||||||
|
.satisfies(
|
||||||
|
invocation -> {
|
||||||
|
assertThat(invocation.uncountedReason()).isNull();
|
||||||
|
assertThat(invocation.executes(":ci", "src")).isTrue();
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("짧은 플래그 묶음은 Gradle처럼 첫 글자만 값을 붙여 받는 것으로 읽는다")
|
||||||
|
void bundledShortOptionsAreReadTheWayGradleReadsThem() {
|
||||||
|
// given
|
||||||
|
String workflow =
|
||||||
|
"""
|
||||||
|
- run: ./gradlew -qm :ci
|
||||||
|
- run: ./gradlew -sm :ci
|
||||||
|
- run: ./gradlew -dry-run :ci
|
||||||
|
- run: ./gradlew --m :ci
|
||||||
|
- run: ./gradlew :ci -x=:leaf:test
|
||||||
|
- run: ./gradlew -exclude-task :leaf:test :ci
|
||||||
|
- run: ./gradlew --x :leaf:test :ci
|
||||||
|
- run: ./gradlew -p=optional-platforms :ci
|
||||||
|
- run: ./gradlew -- :ci -x
|
||||||
|
""";
|
||||||
|
|
||||||
|
// when
|
||||||
|
List<Invocation> invocations = WorkflowGradleInvocations.read(workflow);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(invocations).extracting(Invocation::dryRun)
|
||||||
|
.containsExactly(true, true, true, true, false, false, false, false, false);
|
||||||
|
assertThat(invocations.subList(4, 7))
|
||||||
|
.allSatisfy(
|
||||||
|
invocation -> assertThat(invocation.excludedTasks()).containsExactly(":leaf:test"));
|
||||||
|
assertThat(invocations.get(7).projectDir()).isEqualTo("optional-platforms");
|
||||||
|
assertThat(invocations.get(8).tasks()).containsExactly(":ci", "-x");
|
||||||
|
assertThat(invocations.get(8).excludedTasks()).isEmpty();
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
@DisplayName("Gradle이 거부하는 짧은 플래그 묶음의 명령은 단계를 실행하지 못하므로 그 이유와 함께 세지 않는다")
|
||||||
|
void aCommandLineGradleRejectsDoesNotCountAndSaysWhy() {
|
||||||
|
// given
|
||||||
|
String workflow =
|
||||||
|
"""
|
||||||
|
- run: ./gradlew -mx :leaf:test :ci
|
||||||
|
- run: ./gradlew -qpoptional-platforms :ci
|
||||||
|
- run: ./gradlew -m=yes :ci
|
||||||
|
""";
|
||||||
|
|
||||||
|
// when
|
||||||
|
List<Invocation> invocations = WorkflowGradleInvocations.read(workflow);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(invocations)
|
||||||
|
.hasSize(3)
|
||||||
|
.allSatisfy(
|
||||||
|
invocation -> {
|
||||||
|
assertThat(invocation.uncountedReason()).contains("Gradle rejects");
|
||||||
|
assertThat(invocation.executes(":ci", ".")).isFalse();
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
@DisplayName("uses 단계의 with 입력에 적힌 run은 셸 명령이 아니므로 읽지 않는다")
|
@DisplayName("uses 단계의 with 입력에 적힌 run은 셸 명령이 아니므로 읽지 않는다")
|
||||||
void aRunInputOfAnActionIsNotAShellCommand() {
|
void aRunInputOfAnActionIsNotAShellCommand() {
|
||||||
|
|||||||
@@ -45,7 +45,7 @@ executor, 설정 기본값이 함께 빠진다(그때 KEYED use case는 executor
|
|||||||
| 언제 | 키 |
|
| 언제 | 키 |
|
||||||
| --- | --- |
|
| --- | --- |
|
||||||
| 켤 때 | `APP_IDEMPOTENCY_PROVIDER` (`redis` 또는 `postgresql`), 그리고 그 provider 모듈의 줄과 env |
|
| 켤 때 | `APP_IDEMPOTENCY_PROVIDER` (`redis` 또는 `postgresql`), 그리고 그 provider 모듈의 줄과 env |
|
||||||
| 조정할 때 | `APP_IDEMPOTENCY_PROCESSING_LEASE`(≤1h), `APP_IDEMPOTENCY_TTL`(≤72h, processing lease 이상), `APP_IDEMPOTENCY_FAILURE_RETENTION`(≤30d, `APP_IDEMPOTENCY_TTL` 이상) |
|
| 조정할 때 | `APP_IDEMPOTENCY_PROCESSING_LEASE`(≤1h), `APP_IDEMPOTENCY_TTL`(≤72h, processing lease 이상, `APP_IDEMPOTENCY_FAILURE_RETENTION` 이하 — 24h보다 올리면 failure retention도 함께 올린다), `APP_IDEMPOTENCY_FAILURE_RETENTION`(≤30d, `APP_IDEMPOTENCY_TTL` 이상) |
|
||||||
|
|
||||||
## 설계 결정 참조 (app-bootstrap에서 옮김)
|
## 설계 결정 참조 (app-bootstrap에서 옮김)
|
||||||
|
|
||||||
@@ -73,7 +73,7 @@ executor, 설정 기본값이 함께 빠진다(그때 KEYED use case는 executor
|
|||||||
| --- | --- | --- | --- |
|
| --- | --- | --- | --- |
|
||||||
| `provider` | `APP_IDEMPOTENCY_PROVIDER` | `disabled` | `disabled` \| `redis` \| `postgresql` |
|
| `provider` | `APP_IDEMPOTENCY_PROVIDER` | `disabled` | `disabled` \| `redis` \| `postgresql` |
|
||||||
| `processing-lease` | `APP_IDEMPOTENCY_PROCESSING_LEASE` | 30s | 1h |
|
| `processing-lease` | `APP_IDEMPOTENCY_PROCESSING_LEASE` | 30s | 1h |
|
||||||
| `replay-ttl` | `APP_IDEMPOTENCY_TTL` | 24h | 72h, 그리고 `processing-lease` 이상 |
|
| `replay-ttl` | `APP_IDEMPOTENCY_TTL` | 24h | 72h, 그리고 `processing-lease` 이상·`failure-retention` 이하 |
|
||||||
| `failure-retention` | `APP_IDEMPOTENCY_FAILURE_RETENTION` | 24h | 30d, 그리고 `replay-ttl` 이상 |
|
| `failure-retention` | `APP_IDEMPOTENCY_FAILURE_RETENTION` | 24h | 30d, 그리고 `replay-ttl` 이상 |
|
||||||
| `response-codec-id` | — | `json-v2` | 1–64자 |
|
| `response-codec-id` | — | `json-v2` | 1–64자 |
|
||||||
| `policy-revision` | — | 2 | 양수 |
|
| `policy-revision` | — | 2 | 양수 |
|
||||||
|
|||||||
+4
-2
@@ -13,8 +13,10 @@ app:
|
|||||||
provider: ${APP_IDEMPOTENCY_PROVIDER:disabled}
|
provider: ${APP_IDEMPOTENCY_PROVIDER:disabled}
|
||||||
# Lifecycle policy (IdempotencySettings), the same whichever provider holds the records.
|
# Lifecycle policy (IdempotencySettings), the same whichever provider holds the records.
|
||||||
# replay-ttl must not be shorter than processing-lease (startup fails otherwise): a duplicate
|
# replay-ttl must not be shorter than processing-lease (startup fails otherwise): a duplicate
|
||||||
# told to resend with the same key may come back anywhere inside the lease. A record lives
|
# told to resend with the same key may come back anywhere inside the lease. Nor may it be
|
||||||
# for the lease plus the replay TTL in both stores.
|
# longer than failure-retention (startup fails too): an abandoned record would go before a
|
||||||
|
# completed one, and a same-key resend would run the work again. A record lives for the
|
||||||
|
# lease plus the replay TTL in both stores.
|
||||||
processing-lease: ${APP_IDEMPOTENCY_PROCESSING_LEASE:30s}
|
processing-lease: ${APP_IDEMPOTENCY_PROCESSING_LEASE:30s}
|
||||||
replay-ttl: ${APP_IDEMPOTENCY_TTL:24h}
|
replay-ttl: ${APP_IDEMPOTENCY_TTL:24h}
|
||||||
failure-retention: ${APP_IDEMPOTENCY_FAILURE_RETENTION:24h}
|
failure-retention: ${APP_IDEMPOTENCY_FAILURE_RETENTION:24h}
|
||||||
|
|||||||
+2
-1
@@ -38,7 +38,8 @@ import org.springframework.util.ClassUtils;
|
|||||||
* ports its own bean method receives (manual 07 「시스템이 부르는 쓰기」 lists them). The guard looks at bean
|
* ports its own bean method receives (manual 07 「시스템이 부르는 쓰기」 lists them). The guard looks at bean
|
||||||
* types only, so all of them start. The static paths are the architecture rules': {@code
|
* types only, so all of them start. The static paths are the architecture rules': {@code
|
||||||
* ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES} refuses a user transport that constructs one
|
* ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES} refuses a user transport that constructs one
|
||||||
* itself, and {@code USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS} one that calls the system caller.
|
* itself, and {@code USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS} one that calls the system caller
|
||||||
|
* by its class or by a project interface it implements.
|
||||||
*/
|
*/
|
||||||
final class PermissionEnforcementGuard implements SmartInitializingSingleton, BeanFactoryAware {
|
final class PermissionEnforcementGuard implements SmartInitializingSingleton, BeanFactoryAware {
|
||||||
|
|
||||||
|
|||||||
@@ -16,6 +16,22 @@ configurations {
|
|||||||
integrationTestRuntimeOnly.extendsFrom testRuntimeOnly
|
integrationTestRuntimeOnly.extendsFrom testRuntimeOnly
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// 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.
|
||||||
|
// 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')) {
|
||||||
|
include 'dev/caskeleton/adapter/outbound/persistence/testkit/migration/VersionedMigrationFiles.java'
|
||||||
|
}
|
||||||
|
into(layout.buildDirectory.dir('generated/sources/sharedMigrationFiles/java'))
|
||||||
|
}
|
||||||
|
sourceSets.integrationTest.java.srcDir(sharedMigrationFileSources)
|
||||||
|
|
||||||
// Durable mutation idempotency: the operation ledger entity, its state machine, the vendor-neutral
|
// Durable mutation idempotency: the operation ledger entity, its state machine, the vendor-neutral
|
||||||
// repository port and the Spring Data JPA binding, plus the migration that owns the unique
|
// repository port and the Spring Data JPA binding, plus the migration that owns the unique
|
||||||
// constraint the whole contract rests on.
|
// constraint the whole contract rests on.
|
||||||
|
|||||||
+5
-4
@@ -36,10 +36,11 @@ import org.testcontainers.postgresql.PostgreSQLContainer;
|
|||||||
*
|
*
|
||||||
* <p>Every migration after V001 is held to this, read from the tree itself ({@link
|
* <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.
|
* GrpcOperationLedgerMigrations#inOrder()}), so a V004 is checked without anyone naming it here.
|
||||||
* This is the ledger tree's lock-wait rule: the optional build cannot reach the persistence-jpa
|
* This is the ledger tree's lock-wait rule: the optional build cannot depend on the persistence-jpa
|
||||||
* testkit whose text check the other trees run, and a copy of that check would drift (re-review
|
* testkit whose text check the other trees run (it compiles only the testkit's file list, {@code
|
||||||
* 2026-11-03 round 3, RR3-02-04). A later migration that does not touch the ledger at all fails
|
* VersionedMigrationFiles}), and a copy of that check would drift (re-review 2026-11-03 round 3,
|
||||||
* here too, on purpose: say so in this test rather than let the rule pass it unseen.
|
* RR3-02-04). A later migration that does not touch the ledger at all fails here too, on purpose:
|
||||||
|
* say so in this test rather than let the rule pass it unseen.
|
||||||
*/
|
*/
|
||||||
@Testcontainers(disabledWithoutDocker = true)
|
@Testcontainers(disabledWithoutDocker = true)
|
||||||
class GrpcOperationLedgerMigrationLockWaitIT {
|
class GrpcOperationLedgerMigrationLockWaitIT {
|
||||||
|
|||||||
+9
-18
@@ -1,21 +1,22 @@
|
|||||||
package dev.caskeleton.grpc.ledger;
|
package dev.caskeleton.grpc.ledger;
|
||||||
|
|
||||||
|
import dev.caskeleton.adapter.outbound.persistence.testkit.migration.VersionedMigrationFiles;
|
||||||
import java.io.IOException;
|
import java.io.IOException;
|
||||||
import java.io.InputStream;
|
import java.io.InputStream;
|
||||||
import java.nio.charset.StandardCharsets;
|
import java.nio.charset.StandardCharsets;
|
||||||
import java.nio.file.Files;
|
|
||||||
import java.nio.file.Path;
|
import java.nio.file.Path;
|
||||||
import java.util.Arrays;
|
|
||||||
import java.util.Comparator;
|
|
||||||
import java.util.List;
|
import java.util.List;
|
||||||
import java.util.stream.Stream;
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* The ledger's Flyway scripts in version order, as one SQL text for a test database.
|
* The ledger's Flyway scripts in version order, as one SQL text for a test database.
|
||||||
*
|
*
|
||||||
* <p>One list for every PostgreSQL lane, so a new migration is applied by all of them or by none.
|
* <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
|
* The list is the tree on disk, not a copy of it: a hand-kept list let a V004 that nobody added to
|
||||||
* it go unapplied and unchecked by every lane (re-review 2026-11-03 round 3, RR3-02-04).
|
* it go unapplied and unchecked by every lane (re-review 2026-11-03 round 3, RR3-02-04). Which file
|
||||||
|
* is a versioned migration, and in what order Flyway applies them, is the persistence-jpa testkit's
|
||||||
|
* {@link VersionedMigrationFiles}, the definition the main build's trees use; this lane compiles
|
||||||
|
* that file from there ({@code sharedMigrationFileSources} in this leaf's {@code build.gradle})
|
||||||
|
* rather than keep a second regular expression of its own (re-review README 12, r6-b; r9).
|
||||||
*/
|
*/
|
||||||
final class GrpcOperationLedgerMigrations {
|
final class GrpcOperationLedgerMigrations {
|
||||||
|
|
||||||
@@ -32,13 +33,9 @@ final class GrpcOperationLedgerMigrations {
|
|||||||
* Flyway's order: by version, its parts compared as numbers.
|
* Flyway's order: by version, its parts compared as numbers.
|
||||||
*/
|
*/
|
||||||
static List<String> inOrder() throws IOException {
|
static List<String> inOrder() throws IOException {
|
||||||
try (Stream<Path> files = Files.list(TREE)) {
|
return VersionedMigrationFiles.inVersionOrder(TREE).stream()
|
||||||
return files
|
.map(file -> file.getFileName().toString())
|
||||||
.map(file -> file.getFileName().toString())
|
.toList();
|
||||||
.filter(name -> name.matches("V\\d+(?:[._]\\d+)*__.+\\.sql"))
|
|
||||||
.sorted(Comparator.comparing(GrpcOperationLedgerMigrations::version, Arrays::compare))
|
|
||||||
.toList();
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
|
|
||||||
/** Every migration's SQL, concatenated in version order. */
|
/** Every migration's SQL, concatenated in version order. */
|
||||||
@@ -66,12 +63,6 @@ final class GrpcOperationLedgerMigrations {
|
|||||||
return read(fileName);
|
return read(fileName);
|
||||||
}
|
}
|
||||||
|
|
||||||
private static int[] version(String fileName) {
|
|
||||||
return Arrays.stream(fileName.substring(1, fileName.indexOf("__")).split("[._]"))
|
|
||||||
.mapToInt(Integer::parseInt)
|
|
||||||
.toArray();
|
|
||||||
}
|
|
||||||
|
|
||||||
private static String read(String fileName) throws IOException {
|
private static String read(String fileName) throws IOException {
|
||||||
String path = LOCATION + fileName;
|
String path = LOCATION + fileName;
|
||||||
try (InputStream stream =
|
try (InputStream stream =
|
||||||
|
|||||||
@@ -81,6 +81,17 @@ Spring/Lettuce 타입을 노출하지 않는다.
|
|||||||
타입별 handler 를 따로 두지 않는다. `IllegalArgumentException` 은 모든 전송에서 `BAD_PARAMETER`
|
타입별 handler 를 따로 두지 않는다. `IllegalArgumentException` 은 모든 전송에서 `BAD_PARAMETER`
|
||||||
(400 / GraphQL `REQUEST` / gRPC `INVALID_ARGUMENT`)다.
|
(400 / GraphQL `REQUEST` / gRPC `INVALID_ARGUMENT`)다.
|
||||||
|
|
||||||
|
### ServerFailureLog — 모든 전송이 같은 로그 줄로
|
||||||
|
- carrier로 답한 실패의 서버 로그 줄을 정한다. web·GraphQL·gRPC·STOMP 어댑터가 이 클래스 하나를 쓴다
|
||||||
|
(재리뷰 RR4-03-03 전에는 web만 로그를 남겼다).
|
||||||
|
- `PersistenceFailureException`: status와 상관없이 `persistence failure classified as <code> (...)`만.
|
||||||
|
cause·예외는 붙이지 않는다(SQL 값·제약 이름·자격 증명·endpoint가 들 수 있다).
|
||||||
|
- `DependencyFailureException`: `dependency failure classified as <code> (..., dependency=<이름>)` + 예외.
|
||||||
|
- 그 밖의 5xx carrier: `failure classified as <code> (...)` + 예외. 4xx carrier는 남기지 않는다(응답이지
|
||||||
|
사고가 아니다). `IDEMPOTENCY_RECOVERY_REQUIRED`는 예외 메시지 끝의 scope digest로 runbook이 기록을 찾는다.
|
||||||
|
- 전송은 자기 상관 정보를 뒤에 붙인다: gRPC ` (method=<서비스/메서드>)`, GraphQL ` (executionId=<id>)`.
|
||||||
|
예외는 늘 마지막 인자라 SLF4J가 예외로 받는다.
|
||||||
|
|
||||||
### OperationalError (enum)
|
### OperationalError (enum)
|
||||||
스켈레톤 공통 운영/전송/보안 에러 코드의 집합이다. `USER_NOT_FOUND` 같은 **도메인 전용 코드는
|
스켈레톤 공통 운영/전송/보안 에러 코드의 집합이다. `USER_NOT_FOUND` 같은 **도메인 전용 코드는
|
||||||
여기 두지 않고** 그 코드를 쓰는 모듈에 둔다.
|
여기 두지 않고** 그 코드를 쓰는 모듈에 둔다.
|
||||||
|
|||||||
@@ -0,0 +1,102 @@
|
|||||||
|
package dev.caskeleton.shared.error;
|
||||||
|
|
||||||
|
import java.util.Arrays;
|
||||||
|
import java.util.Optional;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The server-log line a transport writes when it answers a failure with an {@link
|
||||||
|
* ApiErrorCarrier}'s code — one policy for every transport, so the web, GraphQL and gRPC adapters
|
||||||
|
* cannot drift apart.
|
||||||
|
*
|
||||||
|
* <p>Three cases, unchanged from the web adapter where they started:
|
||||||
|
*
|
||||||
|
* <ul>
|
||||||
|
* <li>{@link PersistenceFailureException}: the classification only, whatever the status. Its
|
||||||
|
* cause can hold SQL values, constraint names, credentials and endpoints, so neither the
|
||||||
|
* cause nor the exception is attached.
|
||||||
|
* <li>{@link DependencyFailureException}: the classification, the dependency name, and the
|
||||||
|
* exception, whatever the status.
|
||||||
|
* <li>Any other carrier with a server-side (5xx) code: the classification and the exception. A
|
||||||
|
* carrier's message is the server-log detail it was built for — {@code
|
||||||
|
* IDEMPOTENCY_RECOVERY_REQUIRED} ends with the scope digest the runbook looks the record up
|
||||||
|
* by ({@code docs/runbooks/idempotency-unavailable.md}).
|
||||||
|
* </ul>
|
||||||
|
*
|
||||||
|
* <p>A client-side carrier is not logged: it is an answer, not an incident. The line is written in
|
||||||
|
* the SLF4J style — {@code {}} placeholders, with an attached exception as the last argument — so a
|
||||||
|
* transport hands {@link #format(String)} and {@link #arguments(Object...)} straight to {@code
|
||||||
|
* Logger.error}. A transport adds its own correlation (a gRPC method, a GraphQL execution id) as a
|
||||||
|
* suffix; the failure stays last.
|
||||||
|
*/
|
||||||
|
public final class ServerFailureLog {
|
||||||
|
|
||||||
|
private final String format;
|
||||||
|
private final Object[] values;
|
||||||
|
private final Throwable attached;
|
||||||
|
|
||||||
|
private ServerFailureLog(String format, Object[] values, Throwable attached) {
|
||||||
|
this.format = format;
|
||||||
|
this.values = values;
|
||||||
|
this.attached = attached;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The line for a failure answered with {@code code}, or empty when nothing is logged.
|
||||||
|
*
|
||||||
|
* @param failure the carrier the transport found — not a wrapper around it, so its type decides
|
||||||
|
* what may be attached
|
||||||
|
* @param code the code the transport answers with
|
||||||
|
*/
|
||||||
|
public static Optional<ServerFailureLog> of(Throwable failure, ApiErrorCode code) {
|
||||||
|
if (failure instanceof PersistenceFailureException) {
|
||||||
|
return Optional.of(
|
||||||
|
new ServerFailureLog(
|
||||||
|
"persistence failure classified as {} (category={}, retryable={})",
|
||||||
|
new Object[] {code.code(), code.category(), code.retryable()},
|
||||||
|
null));
|
||||||
|
}
|
||||||
|
if (failure instanceof DependencyFailureException dependency) {
|
||||||
|
return Optional.of(
|
||||||
|
new ServerFailureLog(
|
||||||
|
"dependency failure classified as {} (category={}, retryable={}, dependency={})",
|
||||||
|
new Object[] {
|
||||||
|
code.code(), code.category(), code.retryable(), dependency.dependencyName()
|
||||||
|
},
|
||||||
|
failure));
|
||||||
|
}
|
||||||
|
if (code.httpStatus() >= 500) {
|
||||||
|
return Optional.of(
|
||||||
|
new ServerFailureLog(
|
||||||
|
"failure classified as {} (category={}, retryable={})",
|
||||||
|
new Object[] {code.code(), code.category(), code.retryable()},
|
||||||
|
failure));
|
||||||
|
}
|
||||||
|
return Optional.empty();
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The message pattern, followed by the transport's own placeholders.
|
||||||
|
*
|
||||||
|
* @param transportSuffix the transport's correlation placeholders, such as {@code "
|
||||||
|
* (method={})"}; empty for none
|
||||||
|
*/
|
||||||
|
public String format(String transportSuffix) {
|
||||||
|
return format + transportSuffix;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The pattern's values, then the values for the transport's suffix, then the exception when it is
|
||||||
|
* attached — last, where SLF4J takes it as the exception rather than a value.
|
||||||
|
*
|
||||||
|
* @param transportValues the values for the suffix passed to {@link #format(String)}
|
||||||
|
*/
|
||||||
|
public Object[] arguments(Object... transportValues) {
|
||||||
|
Object[] arguments =
|
||||||
|
Arrays.copyOf(values, values.length + transportValues.length + (attached == null ? 0 : 1));
|
||||||
|
System.arraycopy(transportValues, 0, arguments, values.length, transportValues.length);
|
||||||
|
if (attached != null) {
|
||||||
|
arguments[arguments.length - 1] = attached;
|
||||||
|
}
|
||||||
|
return arguments;
|
||||||
|
}
|
||||||
|
}
|
||||||
+129
@@ -0,0 +1,129 @@
|
|||||||
|
package dev.caskeleton.shared.error;
|
||||||
|
|
||||||
|
import static org.assertj.core.api.Assertions.assertThat;
|
||||||
|
|
||||||
|
import java.sql.SQLException;
|
||||||
|
import java.util.Optional;
|
||||||
|
import org.junit.jupiter.api.Test;
|
||||||
|
|
||||||
|
class ServerFailureLogTest {
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aServerSideCarrierIsLoggedWithTheFailureAttached() {
|
||||||
|
// given
|
||||||
|
RuntimeException failure =
|
||||||
|
new CarrierException(
|
||||||
|
OperationalError.IDEMPOTENCY_RECOVERY_REQUIRED,
|
||||||
|
"claim requires reconciliation: CHARGE_CARD::v1::3f9a");
|
||||||
|
|
||||||
|
// when
|
||||||
|
Optional<ServerFailureLog> line =
|
||||||
|
ServerFailureLog.of(failure, OperationalError.IDEMPOTENCY_RECOVERY_REQUIRED);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(line)
|
||||||
|
.get()
|
||||||
|
.extracting(log -> log.format(""), log -> log.arguments())
|
||||||
|
.containsExactly(
|
||||||
|
"failure classified as {} (category={}, retryable={})",
|
||||||
|
new Object[] {
|
||||||
|
"IDEMPOTENCY_RECOVERY_REQUIRED", Category.DATA_INTEGRITY, false, failure
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aPersistenceFailureIsLoggedByItsClassificationWithoutItsCause() {
|
||||||
|
// given
|
||||||
|
PersistenceFailureException failure =
|
||||||
|
new PersistenceFailureException(
|
||||||
|
OperationalError.DB_UNIQUE_VIOLATION,
|
||||||
|
"persistence failure classified from SQLState=23505",
|
||||||
|
new SQLException("detail=(alice@example.test) password=secret", "23505"));
|
||||||
|
|
||||||
|
// when
|
||||||
|
Optional<ServerFailureLog> line =
|
||||||
|
ServerFailureLog.of(failure, OperationalError.DB_UNIQUE_VIOLATION);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(line)
|
||||||
|
.get()
|
||||||
|
.extracting(log -> log.format(""), log -> log.arguments())
|
||||||
|
.containsExactly(
|
||||||
|
"persistence failure classified as {} (category={}, retryable={})",
|
||||||
|
new Object[] {"DB_UNIQUE_VIOLATION", Category.CONFLICT, false});
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aDependencyFailureNamesTheDependencyAndAttachesTheFailure() {
|
||||||
|
// given
|
||||||
|
DependencyFailureException failure =
|
||||||
|
new DependencyFailureException(
|
||||||
|
OperationalError.DEPENDENCY_TIMEOUT, "payment-service", "read timeout", null);
|
||||||
|
|
||||||
|
// when
|
||||||
|
Optional<ServerFailureLog> line =
|
||||||
|
ServerFailureLog.of(failure, OperationalError.DEPENDENCY_TIMEOUT);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(line)
|
||||||
|
.get()
|
||||||
|
.extracting(log -> log.format(""), log -> log.arguments())
|
||||||
|
.containsExactly(
|
||||||
|
"dependency failure classified as {} (category={}, retryable={}, dependency={})",
|
||||||
|
new Object[] {
|
||||||
|
"DEPENDENCY_TIMEOUT", Category.TRANSIENT_DEPENDENCY, true, "payment-service", failure
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aClientSideCarrierIsNotLogged() {
|
||||||
|
// when
|
||||||
|
Optional<ServerFailureLog> line =
|
||||||
|
ServerFailureLog.of(
|
||||||
|
new CarrierException(OperationalError.BAD_PARAMETER, "bad input"),
|
||||||
|
OperationalError.BAD_PARAMETER);
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(line).isEmpty();
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void aTransportsOwnFieldsGoBetweenTheClassificationAndTheAttachedFailure() {
|
||||||
|
// given
|
||||||
|
RuntimeException failure =
|
||||||
|
new CarrierException(OperationalError.IDEMPOTENCY_RECOVERY_REQUIRED, "digest");
|
||||||
|
ServerFailureLog line =
|
||||||
|
ServerFailureLog.of(failure, OperationalError.IDEMPOTENCY_RECOVERY_REQUIRED).orElseThrow();
|
||||||
|
|
||||||
|
// when
|
||||||
|
Object[] arguments = line.arguments("orders.v1.Orders/Charge");
|
||||||
|
|
||||||
|
// then
|
||||||
|
assertThat(new Object[] {line.format(" (method={})"), arguments})
|
||||||
|
.containsExactly(
|
||||||
|
"failure classified as {} (category={}, retryable={}) (method={})",
|
||||||
|
new Object[] {
|
||||||
|
"IDEMPOTENCY_RECOVERY_REQUIRED",
|
||||||
|
Category.DATA_INTEGRITY,
|
||||||
|
false,
|
||||||
|
"orders.v1.Orders/Charge",
|
||||||
|
failure
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
/** A feature exception carrying a shared code, as an application failure does. */
|
||||||
|
private static final class CarrierException extends RuntimeException implements ApiErrorCarrier {
|
||||||
|
private static final long serialVersionUID = 1L;
|
||||||
|
private final transient ApiErrorCode code;
|
||||||
|
|
||||||
|
CarrierException(ApiErrorCode code, String message) {
|
||||||
|
super(message);
|
||||||
|
this.code = code;
|
||||||
|
}
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public ApiErrorCode errorCode() {
|
||||||
|
return code;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
Reference in New Issue
Block a user