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:
DongHyeonka
2026-11-04 22:46:05 +09:00
parent c508b1ba4b
commit 45d2a478b8
99 changed files with 5419 additions and 636 deletions
+5 -3
View File
@@ -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`에서
+3 -1
View File
@@ -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.
+4 -1
View File
@@ -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`
+33 -8
View File
@@ -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
+4 -1
View File
@@ -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) 검사를 둔다
+24 -10
View File
@@ -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 결정): 같은 키 재전송은 서버가 안전하게 판정하므로 다시
보내는 것이 맞고, 새 키로 보내면 서버가 막지 못한다. 짝 프론트 분류기도 이 표를 따른다. 보내는 것이 맞고, 새 키로 보내면 서버가 막지 못한다. 짝 프론트 분류기도 이 표를 따른다.
+27 -7
View File
@@ -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 것만 읽는다.
+6 -4
View File
@@ -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`를 따로 다시 돌렸다(통과).
+51 -10
View File
@@ -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
+5 -1
View File
@@ -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`)가 전부 바인딩한다.
--- ---
+15 -4
View File
@@ -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
View File
@@ -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
View File
@@ -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
View File
@@ -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
@@ -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);
@@ -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;
}
} }
+6
View File
@@ -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):
@@ -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;
@@ -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;
} }
} }
} }
+3 -1
View File
@@ -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`).
+3 -1
View File
@@ -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). 예외 조건이 곧 우회 경로가 된다.
@@ -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)));
+8 -3
View File
@@ -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>`만 보낸다.
@@ -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 {
@@ -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);
}
}
@@ -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,
@@ -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"));
@@ -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;
}
}
}
@@ -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
+6 -2
View File
@@ -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).
+11 -1
View File
@@ -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
}
@@ -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,
@@ -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,
@@ -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);
}
}
@@ -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
+5 -1
View File
@@ -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
+11 -7
View File
@@ -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') {
@@ -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();
@@ -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)) {
@@ -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();
} }
} }
@@ -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());
} }
} }
+10 -2
View File
@@ -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에서 통과한다
@@ -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
@@ -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));
@@ -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");
@@ -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}.
@@ -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();
}
} }
@@ -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");
}
} }
@@ -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) {}
} }
@@ -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;
}
} }
@@ -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));
+3
View File
@@ -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 좌표를 관리하지
않아 버전을 명시 고정한다. 않아 버전을 명시 고정한다.
+4
View File
@@ -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..
+3 -3
View File
@@ -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
@@ -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
@@ -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",
@@ -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 =
@@ -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) {
@@ -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";
}
}
@@ -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;
@@ -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();
}
}
@@ -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();
}
}
@@ -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;
@@ -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;
}
}
@@ -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();
}
}
@@ -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();
}
}
@@ -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();
}
@@ -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();
}
}
@@ -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 {}
@@ -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();
}
}
@@ -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. */
@@ -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));
}
}
+19 -7
View File
@@ -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).
+6 -2
View File
@@ -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 만 **로그용으로** 담고, 클라이언트에는
@@ -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(
@@ -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;
@@ -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,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,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;
@@ -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)
@@ -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)
@@ -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
@@ -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
+1 -1
View File
@@ -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) |
@@ -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);
@@ -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) {
@@ -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"),
@@ -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() {
+2 -2
View File
@@ -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 | 양수 |
@@ -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}
@@ -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.
@@ -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 {
@@ -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 =
+11
View File
@@ -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;
}
}
@@ -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;
}
}
}