fix!: 2차 재리뷰가 찾은 결함 29건을 고친다

문제: 재리뷰 수정 커밋(bbe944bd)만 다시 본 2차 재리뷰가 Important 7건,
Minor 22건을 찾았다. 결과 불명 503 뒤 같은 키를 다시 보내면 Redis
store가 lease 지난 실행을 넘겨받아 작업을 다시 돌렸다. replay TTL이
lease보다 짧으면 lease 도중 key가 사라져 같은 키가 두 번 실행됐다.
@SystemInvoked 규칙이 매뉴얼 09장의 이벤트 소비 경로까지 막았다. V22가
outbox_event에 가장 강한 잠금을 lock_timeout 없이 걸었다. prod의
fixture- 거부가 HOSTNAME 같은 비밀 아닌 값까지 막았다. 데모 허용 목록의
test·demo 프로필로 sample이 뜨지 않았다. 기동 rule bean의 @Value 필드가
조용히 null이 됐다.

방법: 영역별 4묶음이 test-driven-development 절차로 실패 테스트를
먼저 쓰고 고쳤다. 결정은 재리뷰 README 9.1절이다.
- 두 멱등성 store가 같은 계약을 따른다. lease가 지난 실행 기록은 다시
  돌리지 않고 포기로 표시해 500 RECOVERY_REQUIRED로 답한다. 기록 수명은
  lease + replay TTL이고, replay-ttl < processing-lease면 기동이 실패한다.
- 사용자 transport만 @SystemInvoked use case에 닿지 못한다. 메시지
  handler·scheduler는 새 표시 @SystemCaller(reason)를 달고 use case를
  생성자에서 new로 만든다. 매뉴얼 경로를 테스트로 고정했다.
- 아직 어디에도 적용되지 않은 마이그레이션(V20·V22·알림 V11~V13·sample
  V8_1·grpc V002·V003)에 lock_timeout 5s를 넣고, 텍스트 검사기와 실 PG
  lane을 더했다. 이미 배포된 24개는 동결 목록으로 둔다.
- fixture- 검사는 비밀로 분류된 값만 본다. sample은 local·test·demo에서
  object storage를 끈다. 기동 rule bean에 주입 멤버가 있으면 모든
  프로필에서 기동이 실패한다. 리뷰어가 제안한 "static @Bean 선언 강제"는
  문제없는 등록을 막고 @Value 필드는 통과시켜서 버렸다.
- 이 수정 전에 move된 파일의 쿼터 차이를 찾는 쿼리와 재계산 SQL을
  docs/fileserver/operations.md에 적었다.

위험·한계: lease 뒤 늦게 끝난 첫 시도의 결과는 기록되지 않는다(그 요청도
500). @SystemCaller가 없는 메시지 handler, 주입 멤버가 있는 기동 rule,
working-directory 없이 ./gradlew를 부르는 workflow 명령은 파생 서비스에서
새로 실패하거나 세지지 않는다(업그레이드 안내 B-14~16·B-36·B-39).
spotbugsTestFixtures는 게이트 밖이고 기준 커밋에서도 실패하며, 새 검사기의
정규식 경고 8건이 더해졌다. 실제 CI runner 실행은 확인하지 못했다(Gitea
repo의 Actions가 꺼져 있다).

검증: ci, 두 빌드의 verifyStrictLaneStages --dry-run, mainCheck,
:integrationCheck, -p optional-platforms ci integrationCheck
performanceCheck, :performanceCheck, :releaseCheck(-PgitRevision),
verify-compose-profile-contracts(18 lane) 첫 실행 통과. 쿼터 재계산
SQL은 실 PostgreSQL 16에서 차이 2행 → 0행을 확인했다.

Refs: docs/reviews/2026-11-03-rereview/README.md 9·9.1·10절
BREAKING CHANGE: replay-ttl < processing-lease 설정은 기동 실패, ledger
release가 claim token을 받는다, HttpBodyReadException(IOException 하위)이
본문 실패를 싣는다, 기동 rule·비밀 목록 bean의 주입 멤버 금지,
verifyStrictLaneStages가 workflow 명령의 working-directory로 빌드를 정한다.
This commit is contained in:
DongHyeonka
2026-11-04 01:47:50 +09:00
parent ecc74b7df7
commit 1885bf8da7
168 changed files with 5511 additions and 602 deletions
@@ -1,7 +1,8 @@
name: object-storage-qualification
# Only pull requests that touch object storage start the MinIO container (review BUILD-계획-B3). The
# MinIO lanes left the object storage leaf's `check`; they run in its `mainCheck` on main and here.
# MinIO lanes left the object storage leaf's `check`; they run in the root `integrationCheck` (main push
# and nightly, integration-main.yml) and here.
on:
pull_request:
paths:
+3 -2
View File
@@ -82,8 +82,9 @@ root `CLAUDE.md`는 이 목록의 동기화된 요약이다. 두 문서가 어
`releaseCheck`, optional-platforms 빌드: `-p optional-platforms`로 부르는 `ci`·`integrationCheck`·
`performanceCheck`·`releaseCheck`) 중 하나에 들어 있는지, 그리고 workflow의 접힌(`>`) run 블록이 빈
줄 때문에 옵션을 별개 명령으로 떼어 내지 않는지 검사한다. 두 빌드가 각자 검사를 돌린다. `-x`로 뺀
lane, `continue-on-error` 아래 명령, 상태 함수(`always()`·`success()`·`!cancelled()`)가 아닌 `if:`
아래 명령은 실행으로 세지 않는다.
lane(Gradle처럼 축약 이름도 맞춰 본다), `continue-on-error` 아래 명령, 상태 함수(`always()`·`success()`·
`!cancelled()`)가 아닌 `if:` 아래 명령, `workflow_dispatch`로만 시작하는 workflow의 명령은 실행으로 세지
않는다. 명령이 어느 빌드를 실행하는지는 `working-directory`와 `-p`를 합친 디렉터리로 정한다.
작업 파일의 소유 leaf는 registry의 `source_path`로 판단하고 가장 가까운 `src/**/CLAUDE.md`를
함께 읽는다. focused test는 registry의 `gradle_path`에서
+4 -2
View File
@@ -40,8 +40,10 @@ If this summary drifts from `AGENTS.md`, `AGENTS.md` wins and this summary must
`releaseCheck` and the named repository-wide gates). `verifyStrictLaneStages --dry-run` (pull
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
command removes with `-x` and a command under `continue-on-error` or a non-status `if:` do not
count — or a folded workflow `run:` block splits an option off its command.
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;
the build a command runs is its `working-directory` joined with `-p` — or a folded workflow
`run:` block splits an option off its command.
Commit policy is `human-only`: agents do not stage, commit, amend, or push implementation changes.
@@ -83,6 +83,17 @@ load-check-save let two commits that both read `IN_PROGRESS` both write; now exa
A claim whose conflicting row is purged between insert and read retries the insert once instead of
failing the call.
`release(identity, claimToken)` is fenced the same way (re-review 2026-11-03 round 2, RR-01-15): it is a
conditional `DELETE … WHERE state = 'IN_PROGRESS' AND claim_attempt = :attempt` and returns whether it
deleted. It used to delete by key alone, so any caller could erase the claim of the attempt that held
it, or a finished record a retry replays. The counter lives in the row, so a deleted row's key starts
again at attempt 1: the token separates the attempts of one row, not attempts across a delete. Both
deletions are limited accordingly — release only for a claim whose owner is known to be gone, purge
only for rows finished longer ago than any retry. Rejected: dropping `release` from the port
(`markFailed` then `reclaimFailed` keeps the counter, but a deployment that must free a key for a
different request has no other path), and a tombstone row that keeps the counter (a second state to
purge, for a window the two limits already close).
Chosen over the claim moment as the token (`WHERE claimed_at = :claimedAt`), which needs no column:
PostgreSQL stores microseconds while `Instant` carries nanoseconds, so the token a caller holds and
the one stored can differ by rounding, and two processes' clocks can give two attempts the same
+1 -1
View File
@@ -39,7 +39,7 @@ lanes and CI; it is not a deployment artifact.
| GraphQL transport | `backend.graphql.enabled` / `APP_GRAPHQL_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:inbound:graphql')`) | leaf-level | On when present; `false` also excludes Spring GraphQL's own auto-configuration, so no `/graphql` (`GraphQlCapabilityActivationTest`). `graphqlTransportQualificationTest` runs the HTTP boundary. The deployment-mode/runtime-profile rule is the module's own `GraphQlPlatformStartupValidator`. The default jar does not ship GraphQL, so a compose lane that exercises it runs the qualification jar. |
| Object storage | `app.object-storage.enabled` / `APP_OBJECTSTORAGE_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:objectstorage')`) | MinIO only | Own `ObjectStorageAutoConfiguration` (was bound through bootstrap's properties scan); on when present, `false` leaves only the explicit legacy seam (`ObjectStorageAutoConfigurationTest`). `app-bootstrap:integrationTest` assembles it against digest-pinned MinIO. |
| gRPC platform | — (build-level) | yes | **no** | yes | Absent from the main build entirely: `optional-platforms` is a separate Gradle build, so the switch is the `include`, not an environment variable. `-p optional-platforms ci` runs on every PR and `integrationCheck` certifies the operation ledger against real PostgreSQL. |
| gRPC transport (`adapter:inbound:grpc`) | `ca-skeleton.grpc.server.enabled` (no `APP_*` row), `true` | yes | yes (one line: `runtimeOnly project(':adapter:inbound:grpc')`) | leaf-level | Own `AutoConfiguration.imports` (`GrpcServerConfig`); on when present, and the loopback plaintext listener still needs `ca-skeleton.grpc.server.allow-insecure-local=true` (`GrpcSafeActivationTest`, `grpcTransportQualificationTest`). |
| gRPC transport (`adapter:inbound:grpc`) | `app.grpc.server.enabled` / `APP_GRPC_SERVER_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:inbound:grpc')`) | leaf-level | Own `AutoConfiguration.imports` (`GrpcServerConfig`); on when present, and the loopback plaintext listener still needs `app.grpc.server.allow-insecure-local=true` (`GrpcSafeActivationTest`, `grpcTransportQualificationTest`). |
| WebSocket transport | `app.websocket.enabled` / `APP_WEBSOCKET_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:inbound:websocket')`) | — | Own `AutoConfiguration.imports` (`WebSocketConfig`), on in a servlet app when present (`WebSocketAutoConfigurationTest`); `ConditionalTransportBuildContractTest` asserts it has no default production edge. |
| Web Advanced library (`adapter:inbound:web-advanced`) | — (build-level; three `backend.web.advanced.*.enabled` switches inside) | yes | **no** | — | No composition root depends on it; `app-bootstrap` takes it `testRuntimeOnly` for the ArchUnit import. No real-provider lane: `webAdvancedTest` (the `web-advanced` tag, run by `release.yml` → `web-stable-release-gate`) is unit and context-runner level. The Nginx lane went with the proxy library on 2026-09-25. |
+69
View File
@@ -126,3 +126,72 @@ curl -s -X POST "$ADMIN/internal/fileserver/uploads:cleanup?maxItems=500&maxByte
If the deferrals are all `ACTIVE_WRITER_LEASE`, the backlog resolves itself as those uploads expire.
Never delete staging content to clear a backlog: an upload that is mid-flight will corrupt.
## Namespace quota drift
**Signal** — a namespace's usage (`fileserver.quota` rejections, or the drift query below) disagrees
with the bytes its files actually hold. The known cause is history: before the 2026-11 maturity
review, `move` relocated a file without moving its quota. The bytes of every file moved before that
fix are still booked on the namespace it left, and deleting such a file reclaims from the namespace
it now lives in, where the reclaim stops at zero and leaves the old booking behind. A derived
service that moved files across namespaces before taking the fix has this drift; one that never did
should see none.
What the ledger must equal: quota is committed when a file is published and reclaimed when cleanup
deletes its content, so a namespace's committed bytes are the sizes of its published files that are
not yet `DELETED`. The query compares the two and changes nothing.
```sql
WITH booked AS (
SELECT scope_value AS namespace, sum(committed_bytes) AS booked_bytes
FROM fs_quota_reservation
WHERE scope_type = 'namespace' AND status = 'COMMITTED'
GROUP BY scope_value),
held AS (
SELECT namespace, sum(actual_size) AS held_bytes
FROM fs_file
WHERE published_at IS NOT NULL AND state <> 'DELETED'
GROUP BY namespace)
SELECT coalesce(b.namespace, h.namespace) AS namespace,
coalesce(b.booked_bytes, 0) AS booked_bytes,
coalesce(h.held_bytes, 0) AS held_bytes,
coalesce(b.booked_bytes, 0) - coalesce(h.held_bytes, 0) AS drift_bytes
FROM booked b
FULL JOIN held h ON h.namespace = b.namespace
WHERE coalesce(b.booked_bytes, 0) <> coalesce(h.held_bytes, 0);
```
A positive `drift_bytes` is booked capacity no file holds (the namespace a file left); a negative one
is held content nothing booked (the namespace it arrived in). While uploads, copies, moves or
cleanup run, a row can show a drift that only means work in flight, so judge drift with the
fileserver's writes stopped.
To correct a namespace, stop every fileserver write to it first — uploads, copy, move, delete, and
the cleanup worker (`APP_FILESERVER_PLATFORM_CLEANUP_ENABLED=false`) — because the statement below
recomputes from `fs_file` and a publish or reclaim that lands between its two steps would be lost.
It zeroes the namespace's committed rows and books the recomputed total as one row; the per-row
split has no meaning once reclaims have drawn rows down, and enforcement only ever reads the sum.
`RESERVED` rows (uploads in progress) are left alone.
```sql
BEGIN;
SET LOCAL lock_timeout = '5s';
UPDATE fs_quota_reservation
SET committed_bytes = 0, version = version + 1, updated_at = now()
WHERE scope_type = 'namespace' AND scope_value = :'namespace'
AND status = 'COMMITTED' AND committed_bytes > 0;
INSERT INTO fs_quota_reservation (
reservation_id, scope_type, scope_value, reserved_bytes, committed_bytes,
expires_at, status, version, created_at, updated_at)
SELECT gen_random_uuid(), 'namespace', :'namespace', held, held,
now(), 'COMMITTED', 0, now(), now()
FROM (SELECT coalesce(sum(actual_size), 0) AS held
FROM fs_file
WHERE namespace = :'namespace'
AND published_at IS NOT NULL AND state <> 'DELETED') AS recomputed
WHERE held > 0;
COMMIT;
```
Run it with `psql -v namespace=<name>`, then run the drift query again: the namespace must be gone
from its result before writes resume.
+15 -3
View File
@@ -106,9 +106,12 @@ instead, so a long download is not cut at an arbitrary total (design §15.3). Th
transports. The JDK transport keeps its exchange-wide timeout off a streamed body and bounds each
read with its own `read-idle` timer, because the JDK client has no socket read timeout; 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 as `HttpResponseTimeoutException` (a gap longer than `read-idle`)
or `HttpResponseTruncatedException` (the connection ended early), stage `RESPONSE_BODY`, evidence
`PARTIAL_RESPONSE`.
failure after hand-over is thrown from `read` as `HttpBodyReadException` — an `IOException`, as
`InputStream` promises, so `catch (IOException)` still sees it — whose `failure()` is
`HttpResponseTimeoutException` (a wait longer than `read-idle`) or `HttpResponseTruncatedException`
(the connection ended early), stage `RESPONSE_BODY`, evidence `PARTIAL_RESPONSE` (re-review
2026-11-04 RR-03-14). On the JDK transport `read-idle` bounds each read's wait, `skip` included, and
time the caller spends between reads does not count (RR-03-12).
### Removed settings
@@ -140,6 +143,15 @@ RR-04-01):
| The caller's own deadline (`HttpOperation.deadline()`, when earlier than `total-call`) | Not recorded; the permission is given back | The caller ran out of time. Counting it opened the circuit on a healthy upstream whenever callers passed short budgets |
| The profile's `timeout.total-call` | Recorded as a failure | `total-call` is the operator's statement of how long a healthy upstream may take; a slow-drip upstream that never trips a per-gap timeout is seen only through it |
The first row has a blind spot (re-review 2026-11-04 RR-03-16). The attempt is let off whenever the
caller's deadline was the earlier one and had passed when the attempt failed — the code does not ask
whether the upstream was still answering within the profile's limits. If every caller of a profile
passes a budget shorter than `connect` or `response-header`, an upstream that hangs (drops packets,
never answers) ends every attempt at the caller's deadline first, so no attempt is recorded and the
circuit never opens; every call waits out its own budget. A failure that comes before the caller's
deadline — a refused connection — is still counted. For such a profile, set `connect` and
`response-header` shorter than the shortest caller budget.
| Property | Default | Meaning |
|---|---|---|
| `failure-rate-threshold` | `50` | Percent of failed calls in the window that opens the circuit, 1–100 |
+5
View File
@@ -111,6 +111,11 @@ evidence, replayability, stage, retryability, attempt, elapsed, remaining deadli
| `HttpUnknownTransportException` | the engine failed in a way no category above describes; the metadata evidence, not the type, says whether it was sent | never |
| `HttpAmbiguousExecutionException` | a non-idempotent request was sent and the outcome is unknown | never — reconcile instead |
A streamed body that fails after hand-over is the one place these arrive wrapped: `read` throws
`HttpBodyReadException`, an `IOException` as `InputStream` promises, and its `failure()` is the
`HttpResponseTimeoutException` or `HttpResponseTruncatedException` above (re-review 2026-11-04
RR-03-14).
## Traces
```text
+9 -2
View File
@@ -85,8 +85,15 @@ reason those are ID references.
bidirectional pair, on `@Entity`, `@MappedSuperclass` and `@Embeddable` types: an association that
declares `mappedBy` (only that inverse half is reported), and two entities whose associations point
at each other without `mappedBy` (both halves are reported — the `@JoinColumn` form above, review
RR-03-04). A class that links to itself is a pair only when a second member points back the other
way (`@ManyToOne parent` with `@OneToMany children`). `JpaProductionArchitectureTest` (app-bootstrap
RR-03-04). That last check also refuses two entities that each hold their own foreign key to the
other (`Order.@OneToOne latestInvoice` with `Invoice.@ManyToOne order`). It is not one link mapped
twice, and the message says so; it is refused on purpose, because the two tables then reference each
other: neither row can be inserted or deleted first, one key has to be nullable and written by a
second `UPDATE`, and the entity graph is a cycle. Keep the association on one side and give the other
an ID or a query (re-review round 2, RR-02-15). A class that links to itself is a pair only when a
second member points back the other way (`@ManyToOne parent` with `@OneToMany children`); two
`@ManyToOne` links of a class to itself (a manager and a mentor) pass, because both keys point into
the one table and there are no two tables to order. `JpaProductionArchitectureTest` (app-bootstrap
`architectureTest`) runs it over the production graph and `SampleArchitectureTest` over the sample.
The failure message names the fields and these alternatives.
+28
View File
@@ -32,6 +32,34 @@ reason, and an approval (design §8.4).
Only Flyway's structured error codes reach the exception. Its messages embed the script path and
part of the failing statement.
## Bound the lock wait
A migration that locks a table already in use starts with `SET LOCAL lock_timeout = '5s';`, before
the first statement that takes the lock. `ALTER TABLE` takes the strongest lock there is, which
conflicts even with a plain read; a non-concurrent `CREATE INDEX` takes one that stops every write;
`UPDATE` and `DELETE` wait on the rows other transactions hold. Unbounded, the migration waits for
the oldest open transaction that touched the table — an operator's forgotten `BEGIN` in psql has no
deadline — and every read and write that arrives meanwhile queues behind the migration, holding a
pool connection while it waits. With the bound, the migration fails after five seconds, Flyway
rolls it back whole, the database stays on the version before it and the new release does not
start: a failed deploy instead of an outage. Deploy again when the transaction has ended.
`LOCAL`, because a plain `SET` outlives the migration on the pooled connection Flyway borrowed and
changes every statement that later runs on it. A statement on a table the same migration created a
moment earlier waits for nothing and needs no bound.
Enforced, not remembered: `LockWaitMigrationInspector` (persistence-jpa testkit) reads a script
and names every statement that locks an existing table before the bound. `MigrationLockWaitTest`
runs it over every tree this leaf's database runs, `SampleMigrationLockWaitTest` over the sample's
stream; a service stream copies the latter with its own directory. The migrations released before
the rule wait unbounded and stay that way (they are applied, and applied files are never edited);
the test lists them and refuses any new one. `PostgreSqlMigrationLockWaitIntegrationTest`
(`postgresqlMigrationLockWaitIntegrationTest`) and the gRPC ledger's
`GrpcOperationLedgerMigrationLockWaitIT` show on real PostgreSQL that a bounded migration gives up
within the bound while another transaction holds the table, and leaves the version below it. 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).
## Concurrent index builds
`CREATE INDEX CONCURRENTLY` cannot run inside a transaction block, and Flyway wraps migrations in
+6
View File
@@ -128,6 +128,12 @@ capability 스트림 db/migration/jpa/<capability> 각자 histor
(리뷰 README 13.2, 09-02).
- 기존 데이터가 새 제약을 어기면 마이그레이션이 이유를 남기고 멈추게 쓴다(`V8_1`의 `DO $$` 블록). 조용히
지우지 않는다.
- 운영 중인 테이블을 잠그는 문장(`ALTER TABLE`, `CONCURRENTLY` 없는 `CREATE INDEX`, `UPDATE`·`DELETE`)이 있으면
그 앞에 `SET LOCAL lock_timeout = '5s';`를 둔다(`V8_1`, `V22`). 상한이 없으면 그 테이블을 건드린 열린
트랜잭션 하나(`ALTER TABLE`이면 읽기만 한 것도) 뒤에서 마이그레이션이 끝없이 기다리고, 그동안 뒤에 온 그
테이블의 쓰기(`ALTER TABLE`이면 읽기까지)가 모두 마이그레이션 뒤에 줄을 선다. 상한이 있으면 5초 뒤 실패·롤백되고 새 버전이 뜨지 않을 뿐이다. 자기 스트림에도
`SampleMigrationLockWaitTest`처럼 `LockWaitMigrationInspector`(persistence-jpa testkit) 검사를 둔다
(`docs/jpa/migration-guide.md` "Bound the lock wait").
## 지금 이해하면 되는 것
+5
View File
@@ -54,6 +54,11 @@ DB 커밋 중 연결 끊김 ─────────────────
| 500 `IDEMPOTENCY_RECOVERY_REQUIRED` | 이전 시도 효과를 증명 못함 | 재전송·재실행 모두 위험. 업무 데이터로 확인 |
| 500 `DB_COMPLETION_UNKNOWN`, `retryable=false` | DB 커밋 중 연결 끊김. 커밋됐을 수도 있음 | 키 없이 재시도 금지. KEYED면 같은 키로 재전송하면 서버가 판정 |
같은 키 재전송은 작업을 다시 돌리지 않는다. 첫 시도가 실행을 시작한 뒤 processing lease(기본 30s)가
지나면 두 저장소 모두 그 기록을 넘겨주지 않고 500 `IDEMPOTENCY_RECOVERY_REQUIRED`로 답한다. 넘겨받는 것은
실행 전 claim과 재시도 가능한 실패뿐이다. 기록은 lease + `replay-ttl` 동안 남고, `replay-ttl`이 lease보다
짧으면 기동이 실패한다(`IdempotencyStoreContract`, 재리뷰 2026-11-04 RR-01-11·RR-03-11).
409를 `retryable=true`로 바꾼 이유(리뷰 02-01 결정): 같은 키 재전송은 서버가 안전하게 판정하므로 다시
보내는 것이 맞고, 새 키로 보내면 서버가 막지 못한다. 짝 프론트 분류기도 이 표를 따른다.
+26 -9
View File
@@ -64,18 +64,34 @@ JWT의 `realm_access.roles`와 **자기 client**(`app.security.audience`)의 `re
## 시스템이 부르는 쓰기: `@SystemInvoked`
스케줄러·relay처럼 사람이 아니라 시스템이 부르는 쓰기 유스케이스는 `@RequiresPermission` 대신
스케줄러·relay·메시지 소비자처럼 사람이 아니라 시스템이 부르는 쓰기 유스케이스는 `@RequiresPermission` 대신
`@SystemInvoked(reason = "...")`를 단다(`src/application-core/src/main/java/dev/caskeleton/application/security/SystemInvoked.java`).
스케줄러 스레드에는 인증이 없어 권한 선언은 장식이 되기 때문이다. 이 표시가 붙은 유스케이스는 **권한
검사가 없는 쓰기**이므로 전송 계층이 닿으면 안 된다. 그래서 두 가지가 막는다.
스케줄러·소비 스레드에는 인증(`Authentication`)이 없어서 권한 선언은 매번 거부되거나 아예 검사되지 않는
장식이 되기 때문이다. 이 표시가 붙은 유스케이스는 **권한 검사가 없는 쓰기**다. 그래서 사용자 요청이
닿으면 안 된다.
| 막는 것 | 어디 |
| --- | --- |
| bean으로 등록하면 기동 실패. 조립 모듈이 `new`로 만들어 스케줄러에만 준다(예: `composition:outbox-relay`) | `src/composition/service-runtime/src/main/java/dev/caskeleton/composition/runtime/authorization/PermissionEnforcementGuard.java` |
| inbound adapter가 그 클래스를 직접 쓰면 빌드 실패 | `INBOUND_ADAPTERS_DO_NOT_REACH_SYSTEM_INVOKED_USE_CASES`(`ApplicationBoundaryArchitectureTest`) |
```text
사용자 요청 ─▶ web·GraphQL·gRPC·WebSocket ──✗──▶ @SystemInvoked 유스케이스 (빌드 실패)
시스템 ─▶ 스케줄러(조립 모듈이 new로 넘김) ─────▶ @SystemInvoked 유스케이스
시스템 ─▶ 메시지 handler(@SystemCaller, 직접 new) ─▶ @SystemInvoked 유스케이스
어디서든 ─▶ @SystemInvoked 유스케이스를 bean으로 등록 ──✗ (기동 실패)
```
- 사용자 전송: 사용자가 보낸 요청이 들어오는 inbound adapter다(web·GraphQL·gRPC·WebSocket).
- 시스템 호출자: broker 전달이나 시간(tick)이 깨우는 코드다. 사용자 요청은 여기로 들어오지 않는다.
| 규칙 | 무엇을 막나 | 어디 |
| --- | --- | --- |
| 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`) |
| 표시 검사 | `@SystemCaller`는 `..adapter.inbound.messaging..`·`..adapter.inbound.scheduler..`에만 있고, 사용자 전송 타입(controller·GraphQL·STOMP mapping·gRPC·servlet)에 의존하지 않는다 | `SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`(같은 파일) |
규칙은 "누가 닿으면 안 되나"가 아니라 "누가 닿아도 되나"를 적는다. 그래서 나중에 새 전송이 생겨도 따로
고치지 않아도 막힌다. 메시지 소비자의 작업 순서는 09장 「소비」 4단계다.
D4 실패(`MUTATING_USE_CASES_DECLARE_REQUIRED_PERMISSION`)를 끄려고 이 표시를 쓰지 않는다. 사용자가 부르는
쓰기라면 권한을 선언하고 역할에 매핑한다.
쓰기라면 권한을 선언하고 역할에 매핑한다. 같은 쓰기를 사용자도 시스템도 부르면 유스케이스를 둘로 나눈다
(사용자용 `@RequiresPermission`, 시스템용 `@SystemInvoked`). 업무 규칙은 domain에 두고 둘이 같이 쓴다.
## web 없는 조립
@@ -86,6 +102,7 @@ web이 빠진 조립(gRPC 전용·배치 전용)에는 `@RequiresPermission`을
## 지금 이해하면 되는 것
- 쓰기 = `@RequiresPermission` + non-final + bean + 역할 매핑.
- 시스템만 부르는 쓰기 = `@SystemInvoked` + bean 아님 + 전송에서 안 닿음.
- 시스템만 부르는 쓰기 = `@SystemInvoked` + bean 아님 + 사용자 전송에서 안 닿음. 부르는 쪽은 스케줄러
조립이나 `@SystemCaller` 메시지 handler뿐이다.
- 객체 판정은 유스케이스 안, 남의 것은 404.
- 역할은 자기 client 것만 읽는다.
+40 -7
View File
@@ -73,7 +73,9 @@ draft는 `IntegrationEventDrafts.draft(contract, eventId, aggregate, order, occu
시각(벽시계)은 쓰지 않는다 — 서버 시계가 어긋나면 순서가 뒤집힌다(리뷰 06-07). 벽시계 번호를 쓰던
서비스가 포트로 옮기면 V21 floor 덕분에 새 번호는 옛 번호 뒤에서 시작한다. 그래서 첫 번호가 1이
아니라 약 1.7×10¹⁵일 수 있다. 소비자는 번호를 "마지막으로 본 값보다 큰가"로만 비교하고 연속성을
가정하지 않는다.
가정하지 않는다. 비교는 aggregate identity(tenant scope 포함) 단위다. tenant scope를 바꾸는 배포는 옛
버전 인스턴스를 모두 멈춘 뒤 새 버전을 띄운다 — 섞여 돌면 새 scope의 번호가 옛 버전이 방금 쓴 번호보다
작을 수 있다(runbook `outbox-dead-letter.md` §8, 재리뷰 2차 RR-02-10).
## relay와 실패
@@ -112,17 +114,47 @@ Kafka ─▶ platform consumer ─▶ (INBOX_TRANSACTIONAL이면) InboxMessageHa
적용한다.
3. destination을 선언한다: `guarantees.external-side-effect: INBOX_TRANSACTIONAL`, `consumer.group`,
`retry.mode`·`retry.max-attempts`, `dlq.destination`. 예: `src/adapter/inbound/messaging/README.md`.
4. handler(`MessageHandler<T>`)를 `adapter:inbound:messaging`에 둔다. delivery 하나를 use case 호출
하나로 바꾸고 업무 규칙은 use case에 둔다. use case는 평소처럼 `tx.inWrite`로 쓴다. 바깥 inbox
트랜잭션에 합류한다.
4. 쓰기 use case와 handler를 만든다. 소비 스레드에는 인증이 없어서 `@RequiresPermission` use case는
매번 거부된다. 그래서 handler가 부르는 쓰기 use case는 `@SystemInvoked`이고, handler는 그 use case를
**직접 `new`로 만들어 혼자 들고 있는** `@SystemCaller`다(07장 「시스템이 부르는 쓰기」). 이 방법 하나만
기동 가드와 빌드 규칙을 모두 통과한다.
- use case: `@SystemInvoked(reason = ...)` + `@UseCaseCapability(WRITE, …, WRITE_REPOSITORY)`. 평소처럼
`tx.inWrite`로 쓰고, 바깥 inbox 트랜잭션에 합류한다. 업무 규칙은 여기에 둔다.
- handler(`MessageHandler<T>`): `adapter:inbound:messaging`(또는 서비스의 `..adapter.inbound.messaging..`
패키지)에 두고 `@SystemCaller(reason = ...)`를 단다. 생성자가 port를 받아 use case를 만든다.
delivery 하나를 use case 호출 하나로 바꾼다.
- bean은 handler 하나다. use case를 bean으로 등록하면 `PermissionEnforcementGuard`가 기동을 막는다.
표시 없이 use case에 의존하면 `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`가 빌드를 막는다.
```java
@SystemCaller(reason = "order-events 소비자: platform consumer 스레드만 부른다")
public final class OrderCreatedHandler implements MessageHandler<OrderCreatedEnvelope> {
private final ProjectOrderUseCase useCase; // @SystemInvoked, bean 아님
public OrderCreatedHandler(TransactionPort tx, OrderProjectionPort projections) {
this.useCase = new ProjectOrderUseCase(tx, projections);
}
// destination(), handle(delivery) → useCase.project(...)
}
@Bean // 이 leaf의 설정 클래스
OrderCreatedHandler orderCreatedHandler(TransactionPort tx, OrderProjectionPort projections) {
return new OrderCreatedHandler(tx, projections);
}
```
같은 쓰기를 사용자 요청(HTTP 등)도 부르면 use case를 둘로 나눈다. 사용자용은 `@RequiresPermission`,
소비용은 `@SystemInvoked`이고 업무 규칙은 domain에 둔다. payload는 다른 서비스가 보낸 입력이므로 use
case가 검증한다 — 권한 검사가 없다는 것이지 검증이 없다는 것이 아니다.
5. payload 타입을 정한다. 템플릿 relay가 보낸 메시지의 payload는 canonical envelope JSON 전체다
(`eventId`, `payload` 등). handler의 record는 그 모양이다. 등록 코드는 쓰지 않는다: handler의
`destination()`(계약 id, record class)과 `schemaVersions()`(읽는 payloadVersion, 기본 v1)가 decode
목록이 된다. 발행 쪽이 v2를 보내기 시작하면 handler가 `schemaVersions()`에 v2를 더한다 — 선언하지 않은
버전은 `SCHEMA_VERSION_NOT_REGISTERED`로 DLQ에 간다.
6. 테스트 본보기: `InboxRedeliveryIntegrationTest`(lane `messagingInboxRedeliveryIntegrationTest`, 실제
Kafka + PostgreSQL). offset을 되감아 다시 전달해도, 처리 중 예외 뒤 재전달돼도 효과와 inbox 행이
하나인지 본다.
6. 테스트 본보기: `SystemInvokedConsumePathTest`(단위, 4단계 모양이 권한 가드 아래에서 기동하고 delivery가
use case에 한 번 닿는지, use case를 bean으로 두면 기동이 막히는지)와 `InboxRedeliveryIntegrationTest`
(lane `messagingInboxRedeliveryIntegrationTest`, 실제 Kafka + PostgreSQL, 같은 handler 모양). offset을
되감아 다시 전달해도, 처리 중 예외 뒤 재전달돼도 효과와 inbox 행이 하나인지 본다.
### 판단 지점
@@ -162,3 +194,4 @@ Kafka ─▶ platform consumer ─▶ (INBOX_TRANSACTIONAL이면) InboxMessageHa
- 계약(id·버전·schema·해시)을 먼저 정하고 계약 bean을 등록한다.
- 전달은 적어도 한 번. 소비자는 inbox(`INBOX_TRANSACTIONAL`)로 예약과 업무 쓰기를 한 트랜잭션에 묶는다.
- 실패한 처리는 예약까지 롤백되어 재전달에서 다시 처리된다. inbox 보존 기간은 재전달 창보다 길게.
- 소비 handler = `@SystemCaller` + `@SystemInvoked` use case를 직접 `new`. use case는 bean이 아니다.
+3 -1
View File
@@ -154,7 +154,9 @@ consume 계약은 `MessageHandler<T>` 하나다. handler를 bean으로 등록하
실제 왕복·중복 제거·DLQ는 `MessagingKafkaConsumeQualificationTest`(Kafka + PostgreSQL Testcontainers)가 확인한다.
애플리케이션 경로(앱 outbox relay가 발행 → `adapter:inbound:messaging`이 조립한 inbox와 JPA 트랜잭션 →
handler)의 중복 전달·실패 재처리는 `InboxRedeliveryIntegrationTest`(lane
`messagingInboxRedeliveryIntegrationTest`)가 확인한다.
`messagingInboxRedeliveryIntegrationTest`)가 확인한다. 애플리케이션 handler가 쓰기 use case를 부르는 방법
(`@SystemCaller` handler가 `@SystemInvoked` use case를 직접 만든다)은 `docs/manual/09-outbox-events.md`
「소비」 4단계다.
### 복합 키
+8 -2
View File
@@ -1601,7 +1601,9 @@ env_keys:
- name: APP_IDEMPOTENCY_TTL
# app.capabilities.idempotency.replay-ttl: how long a completed response stays
# replayable. One value for every provider; IdempotencySettings refuses more than 72h at startup.
# replayable. One value for every provider; IdempotencySettings refuses more than 72h, and less
# than APP_IDEMPOTENCY_PROCESSING_LEASE, at startup (re-review 2026-11-04 RR-03-11). Each record
# lives for the processing lease plus this value in both stores.
type: duration
default: 24h
allowed_values: null
@@ -1609,7 +1611,7 @@ env_keys:
required: false
reload_policy: restart-only
owner_branch: feature-rate-limit-idempotency-contract
validation: spring_duration_shorthand_le_72h
validation: spring_duration_shorthand_le_72h_ge_processing_lease
compatibility_impact: behavior-change
required_test: idempotency-contract:ttl-applied
@@ -1663,6 +1665,10 @@ env_keys:
required_test: redis-idempotency-contract:key-namespace
- name: APP_IDEMPOTENCY_PROCESSING_LEASE
# app.capabilities.idempotency.processing-lease: how long one attempt holds its claim. Longer
# than the in-flight Retry-After (2s), at most 1h, and not longer than APP_IDEMPOTENCY_TTL. A
# claim whose lease runs out is taken over only if it never started; an execution whose lease
# ran out is answered IDEMPOTENCY_RECOVERY_REQUIRED and never run again.
type: duration
default: 30s
allowed_values: null
+8 -2
View File
@@ -390,7 +390,10 @@ metrics:
allowed_values: [PENDING, IN_FLIGHT, PUBLISHED, FAILED, DEAD, PARKED]
percentiles: null
histogram_buckets: null
# DEAD > 0: the claim moves a row it will not hand out to DEAD without a relay result, so
# outbox.publisher.published.total{outcome=DEAD} misses it (re-review round 2, RR-02-12).
alert_severity_thresholds:
p1: "DEAD > 0 (runbook://outbox/dead-letter)"
p2: "PENDING size growing for 10m"
owner_branch: feature-domain-event-outbox-contract
log_field_mapping: [status]
@@ -550,8 +553,11 @@ metrics:
- name: outcome
cardinality_limit: 2
allowed_values: [admitted, refused]
percentiles: [0.5, 0.9, 0.95, 0.99]
histogram_buckets: slo_driven
# As RedisLaneMetrics registers it: a percentile histogram (publishPercentileHistogram, expected
# range 1ms..10s) and no client-side percentiles and no SLO boundaries. The p99 below is a
# histogram_quantile over the buckets (re-review 2026-11-04 RR-03-17).
percentiles: null
histogram_buckets: percentile_histogram
alert_severity_thresholds:
p2: "SCRIPT admitted p99 > 100ms for 10m (the correctness lane is queueing)"
p3: "CACHE_SCRIPT admitted p99 > 100ms for 30m"
+5 -3
View File
@@ -10,9 +10,11 @@
# (feature-secrets-config-source-contract 2026-05-22: "dev/local sentinel value prefix = __LOCAL_DEV_").
# - prod profile에서 `__LOCAL_DEV_` prefix 발견 시 startup fail
# (feature-secrets-config-source-contract 2026-05-22).
# - prod profile에서 `fixture-` prefix 값(이 저장소에 적힌 lane fixture 비밀번호 — infra/redis-sdk/acl,
# compose lane의 REDIS_LANE_*)도 같은 이유로 startup fail. 어떤 변수 이름이든 검사한다
# (review 2026-11-03 RR-07-04).
# - prod profile에서 비밀값이 `fixture-`로 시작하면(이 저장소에 적힌 lane fixture 비밀번호 —
# infra/redis-sdk/acl, compose lane의 REDIS_LANE_*) 같은 이유로 startup fail (review 2026-11-03
# RR-07-04). 비밀값만 본다: 이 파일의 `secret` 행(SecretSourceValidator.CLASSIFIED_SECRETS,
# SecretsClassificationRegistryTest가 1:1로 묶음), 모듈이 기여한 비밀, `secret://…/<VAR>` 참조가
# 가리키는 변수. HOSTNAME·앱 이름 같은 비밀이 아닌 값은 보지 않는다 (review 2026-11-04 RR2-04-01).
# - Masking 기본 = `full_except_last_4` (feature-secrets-config-source-contract 2026-05-22:
# "full mask except last 4 chars for non-secret tokens"). 진짜 secret(password/private key)은 `full`.
# - Naming suffix는 보조 신호 (feature-secrets-config-source-contract: "_TOKEN, _KEY, _PASSWORD").
@@ -143,3 +143,44 @@ Important 7건:
| RR-02-09 V22 잠금 | V21과 같은 `SET LOCAL lock_timeout`과 같은 모양의 lane 테스트 | 같은 커밋 안의 두 마이그레이션이 다른 규칙을 따르면 안 된다 |
멈추는 기준: 3차 수정 뒤 그 diff만 보는 확인 리뷰에서 새 Important가 0이면 멈춘다.
## 10. 3차 수정 결과 (2026-11-04)
9.1절 결정대로 2차 재리뷰 발견 29건(Important 7, Minor 22)을 영역 묶음 4개가 `ecc74b7d`에서 `test-driven-development` 스킬 절차로 RED→GREEN 했다. 오케스트레이터가 합쳤다. 하위 에이전트 없음.
| 묶음 | 발견 | 상태 | 검증 (에이전트) | 처리 내용 | 결정 |
|---|---|---|---|---|---|
| r5-a 멱등성·outbound | RR-01-11, RR-03-11~18 | 완료 | leaf check 9, Redis 컨테이너 계약, PG 멱등성 계약 19/19, `postgresqlIdempotencyIntegrationTest` 8/8, architectureCheck, verifyEnvKeys, documentContractTest, topology standalone·cluster | RR-01-11 Redis CLAIM이 lease 지난 EXECUTING을 ABANDONED로 바꾸고 `RECOVERY_REQUIRED`로 답한다(PG와 같음, RED 실 Redis), 공유 계약에 시간 케이스 5개. RR-03-11 두 store의 기록 수명을 lease + replay TTL로(claim·takeover·renew), `replay-ttl < processing-lease`면 기동 실패(RED 실 Redis·PG). RR-03-12 skip을 read 단위로(RED). RR-03-13 read마다 걸던 타이머를 스트림당 watchdog 하나로(read당 2.6–3.1µs → 25–32ns). RR-03-14 본문 실패를 `IOException` 하위 `HttpBodyReadException`으로(RED). RR-03-15 시스템 속성 목록을 Spring과 비교(RED). RR-03-16 breaker 맹점 문서. RR-03-17 listener 첫 실패 WARN(RED). RR-03-18 문서 | lease가 지난 실행은 abandon해서, 늦게 끝난 첫 시도의 결과도 기록하지 않는다(9.1절 "다시 돌리지 않는다"와 같은 방향, PG 동작 유지). cluster topology 첫 실행의 캐시 테스트 2건 실패는 재실행·기준 커밋에서 재현 안 됨 |
| r5-b core·inbound | RR-01-12~17 | 완료 | application-core·fileserver·web·graphql·grpc·inbound messaging·service-runtime check, app-bootstrap architectureTest, architectureCheck, verifyDependencyLocks, inbox Kafka+PG, gRPC ledger PG 44, jpaPlatformContract | RR-01-12 새 표시 `@SystemCaller(reason)`: 메시지 handler·scheduler가 `@SystemInvoked` use case를 생성자에서 `new`로 만든다. ArchUnit `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`·`SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`, 매뉴얼 09장 경로를 `SystemInvokedConsumePathTest`로 고정. RR-01-13 `/error` status 접기를 문서·`EnvelopeErrorControllerTest`로. RR-01-14 `GraphQlClientPolicy`의 page 규칙 복사본 삭제. RR-01-15 ledger `release(identity, claimToken)`(RED 2). RR-01-16 `DirectTransactionPort`가 스레드별 트랜잭션(RED). RR-01-17 쿼터 롤백 계약 케이스(RED) | scheduler 패키지도 `@SystemCaller` 허용, `/error`는 코드 표에 없는 status를 class 코드로 접는다, release도 claim token으로 막는다 |
| r5-c persistence·messaging | RR-02-09~16 | 완료 | persistence-jpa(587)·persistence-notification·starter-kafka·outbox-relay·application-core·sample check, 실 PG lane 11개, `-p optional-platforms integrationCheck`, architectureCheck, documentContractTest, verifyStrictLaneStages | RR-02-09 V20·V22·알림 V11~V13·sample V8_1·grpc V002·V003에 `SET LOCAL lock_timeout = '5s'`, 텍스트 검사기 `LockWaitMigrationInspector`(testkit)와 실 PG lane `postgresqlMigrationLockWaitIntegrationTest`(RED 9). RR-02-10 scope를 바꾸는 배포는 rolling 금지 문서. RR-02-11 모르는 상태 값은 집계에서 빼고 WARN 1회(RED). RR-02-12 claim이 DEAD로 옮길 때 `last_failure_code`를 쓰고 `outbox.pending.size{status=DEAD} > 0` p1 경보(RED 단위·실 PG). RR-02-13 Javadoc. RR-02-14 runbook 숫자를 상수와 비교하는 document-contract lane. RR-02-15 메시지·가이드·fixture. RR-02-16 header 테스트, 업그레이드 안내 B-39 | 브리프에 없던 V20·V8_1도 같은 근거(아직 어디에도 미적용)로 수정. 규칙 이전에 배포된 마이그레이션 24개는 고칠 수 없어 동결 목록(줄기만 함). DEAD 원인 코드는 claim의 row lock 아래 flush |
| r5-d bootstrap·build·sample | RR2-04-01~06 | 완료 | support·app-bootstrap·sample·objectstorage check, app-bootstrap systemTest·documentContractTest, sample systemTest·webSystemTest, `-p build-logic check`, 두 빌드 verifyStrictLaneStages, verifyEnvKeys, compose 18 lane, `docker build`와 실제 기동(프로필 없음 exit 71, `demo` 8초 ready) | RR2-04-01 prod `fixture-` 검사는 비밀값만(레지스트리 `secret` 행, 모듈 기여 비밀, `secret://…/<VAR>` 대상)(RED). RR2-04-02 sample `application.yml`이 `local`·`test`·`demo`에서 object storage를 끔(RED 9). RR2-04-03 rule·비밀 목록 bean에 주입 멤버·`@ConfigurationProperties`가 있으면 모든 프로필에서 기동 실패(RED 4). RR2-04-04 축약 `-x`, `workflow_dispatch` 전용 workflow, `working-directory`+`-p`, `uses:`의 `with: run:`(RED 7). RR2-04-05 lane json의 `APP_` 밖 키 거부, `property:` 행은 설정 metadata에 있을 때만 읽힘(RED 2). RR2-04-06 문서 | 리뷰어 제안 "static @Bean 선언 강제" 대신 bean이 실제로 필요로 하는 것을 본다(선언 강제는 문제없는 등록을 막고 `@Value` 필드는 통과시킨다). `workflowProjectDirectory` 설정을 없애고 저장소 구조로 정한다 — `working-directory` 없이 `./gradlew`를 부르는 workflow 명령은 실행으로 세지 않는다(B-36). `ca.spring-config`의 `compileJava`가 `processResources` 뒤에 돈다 |
### 10.1 합칠 때 오케스트레이터가 한 것
- 업그레이드 안내 `docs/upgrade/2026-11-maturity-review.md`를 세 방향(r5-b·r5-c·r5-d)에서 손으로 합쳤다. B-14·B-15는 r5-d, B-16은 r5-b, B-39는 r5-c.
- RR-01-17의 남은 절반(이 수정 전에 move된 파일의 장부)을 직접 마무리했다. `docs/fileserver/operations.md` 「Namespace quota drift」에 차이를 찾는 쿼리와 namespace 하나를 다시 계산하는 SQL을 적었다. 실 PostgreSQL 16에 V1 스키마와 move 전 상태(출발 +100, 도착 −100, 삭제된 파일, 진행 중 예약)를 넣고 돌려, 차이 2행 → 0행, `RESERVED` 행은 그대로인 것을 확인했다. 업그레이드 안내 4절의 "재계산 SQL은 아직 없다"를 이 절로 바꿨다.
- 프론트 인계 문서에 이번 계약 변화(같은 키 재전송은 작업을 다시 돌리지 않음, `replay-ttl` 24h, `/error` status 접기)를 더했다.
### 10.2 게이트 (2026-11-04, 합친 메인 작업 트리, 공유 잠금)
첫 실행에서 모두 통과했다.
| 게이트 | 결과 | 시간 | 실행 직전 부하(1분) |
|---|---|---|---|
| `ci` | rc=0 | 6분 22초 | 7.75 |
| `verifyStrictLaneStages --dry-run` (주 빌드 / `-p optional-platforms`) | rc=0 / rc=0 | 10초 / 3초 | 16.51 / 15.10 |
| `mainCheck` | rc=0 | 3분 6초 | 14.37 |
| `:integrationCheck` | rc=0 | 14분 22초 | 15.03 |
| `-p optional-platforms ci integrationCheck performanceCheck` | rc=0 | 1분 3초 | 1.88 |
| `:performanceCheck` | rc=0 | 22초 | 9.69 |
| `:releaseCheck -PgitRevision=<HEAD>` | rc=0 | 3초 | 7.63 |
| `scripts/verify-compose-profile-contracts.sh` | rc=0, 18 lane | 4초 | 7.82 |
`integrationCheck`는 입력이 없는 lane 4개(`redisTopologyTest` 3개, `objectStorageAwsQualificationTest`)를 이름을 대며 뺐다(설계대로). 이 절과 `docs/fileserver/operations.md`·업그레이드 안내 문구는 `ci`가 도는 동안 고쳤다. 그 뒤의 `mainCheck`(document-contract lane 포함)는 고친 문서로 돌았다.
### 10.3 남은 것
- `spotbugsTestFixtures`: 게이트 밖이고 `ecc74b7d`에서도 실패한다. r5-c의 새 검사기(`LockWaitMigrationInspector`)가 정규식 ReDoS 경고 8건을 더했다(입력은 저장소 마이그레이션 파일뿐).
- 실제 CI runner 실행: Gitea repo의 Actions가 꺼져 있어(`has_actions: false`) workflow가 돈 적이 없다. 켜는 것은 소유자 일이다.
- 소유자 확인이 필요한 기본값: 10절 "결정" 칸 — 특히 lease 뒤 늦게 끝난 첫 시도의 결과를 버리는 것, workflow 명령에 `working-directory`가 필요해진 것.
- 다음: 이 수정 커밋만 보는 확인 리뷰. 새 Important가 0이면 멈춘다(9.1절).
+8 -2
View File
@@ -4,7 +4,7 @@ category: INTERNAL
error_codes: [MIGRATION_FAILED]
severity: P1
owner: oncall
last_updated: 2026-07-29
last_updated: 2026-11-04
status: active
---
@@ -40,7 +40,13 @@ status: active
4. Check whether any owned relation was created without a successful history entry. Compare only
against the owned tables in the reviewed migration; do not drop unrelated relations.
5. Classify the failure:
- lock/statement timeout: remove the blocker or reduce rollout concurrency, then rerun;
- lock/statement timeout: remove the blocker or reduce rollout concurrency, then rerun. A
migration that locks a table already in use gives up after its own `SET LOCAL lock_timeout`
(5 s; SQLState `55P03` `lock_not_available`) and rolls back whole, so the history ends one
version below it. The blocker is a transaction that touched the table and is still open —
often an idle-in-transaction session: `SELECT pid, state, xact_start, query FROM
pg_stat_activity WHERE xact_start < now() - interval '5 seconds' ORDER BY xact_start;`. End
it, then rerun (`docs/jpa/migration-guide.md` "Bound the lock wait");
- SQL/data precondition: create a new forward migration that makes the precondition explicit;
a duplicate outbox order key stopping V21 (`ux_outbox_event_aggregate_order`) is the known
case — clean it up with `outbox-dead-letter.md` §8 and rerun, the migration stays as it is;
+23 -4
View File
@@ -4,7 +4,7 @@ category: INTERNAL
error_codes: [OUTBOX_DEAD_LETTER]
severity: P1
owner: oncall
last_updated: 2026-11-03
last_updated: 2026-11-04
status: stub
---
@@ -16,7 +16,10 @@ status: stub
- alert name: `outbox_dead_letter`
- alert payload 필수 field: `error.code=OUTBOX_DEAD_LETTER`, `event_type`, `event_id`, `correlation_id`, `runbook_link`
- 임계: `outbox.publisher.published.total{outcome=DEAD}` > 0 (DEAD 전이는 자동 회복이 없으므로 단건도 점검 대상)
- 임계: `outbox.publisher.published.total{outcome=DEAD}` > 0 또는 `outbox.pending.size{status=DEAD}` > 0 (DEAD 전이는
자동 회복이 없으므로 단건도 점검 대상). 두 번째 조건이 필요한 이유: claim이 행을 DEAD로 옮기는 경우
(`ATTEMPT_COUNTERS_INCONSISTENT`, `UNREADABLE_ROW`)는 relay 결과를 거치지 않아 첫 번째 카운터가 오르지 않는다
(재리뷰 2026-11-03 2차 RR-02-12)
## 2. First Response (5분 이내)
@@ -26,7 +29,8 @@ status: stub
`last_failure_code`에 남는다. ERROR가 없고 WARN `outbox claim moved a row ... to DEAD`만 있으면 relay가 아니라
claim이 행을 DEAD로 옮긴 것이다 — `error.reason`이 `ATTEMPT_COUNTERS_INCONSISTENT`면 `deferred_attempt_count`를
되돌리지 않은 수동 재발행이 원인이니 §4의 SQL로 다시 재발행한다. `UNREADABLE_ROW`면 행 자체가 event로 읽히지
않는다(canonical 봉투 없음, 저장된 해시와 바이트 불일치)
않는다(canonical 봉투 없음, 저장된 해시와 바이트 불일치). 이 경우에도 같은 코드가 행의 `last_failure_code`에
남는다 — 그 전 발행 실패의 코드는 덮어쓴다
2. DB에서 DEAD row 확인: `SELECT * FROM outbox_event WHERE status = 'DEAD' ORDER BY occurred_at;`
3. **차단 영향 파악 (중요)**: strict per-aggregate FIFO 정책상 DEAD row는 같은 aggregate(`tenant_scope`, `aggregate_type`, `aggregate_id`)의 후행 이벤트를 계속 차단함. 순서는 `(aggregate_sequence, event_index)`로 비교한다(claim SQL `PostgreSqlOutboxClaimRepository`와 같은 키) —
`SELECT count(*) FROM outbox_event b WHERE b.status <> 'PUBLISHED' AND EXISTS (SELECT 1 FROM outbox_event d WHERE d.status='DEAD' AND d.tenant_scope=b.tenant_scope AND d.aggregate_type=b.aggregate_type AND d.aggregate_id=b.aggregate_id AND (d.aggregate_sequence < b.aggregate_sequence OR (d.aggregate_sequence = b.aggregate_sequence AND d.event_index < b.event_index)));`
@@ -121,10 +125,24 @@ V21이 하는 일은 세 가지 더 있다.
5초 안에 못 잡으면 V21이 실패하고 V20에 남는다(`MIGRATION_FAILED`). 덜 바쁜 시각에 다시 배포하거나
Step 0으로 인덱스를 먼저 만든다.
V20(`deferred_attempt_count`)과 V22(`last_failure_code`)도 같은 상한을 둔다(재리뷰 2026-11-03 2차 RR-02-09).
둘 다 `ALTER TABLE outbox_event`라 가장 강한 잠금(ACCESS EXCLUSIVE)을 건다. 이 잠금은 읽기와도 충돌하므로,
`outbox_event`를 읽기만 한 트랜잭션 하나(운영자가 `BEGIN` 안에서 조회하고 둔 psql 세션 포함)가 열려 있어도
기다린다. 5초 안에 못 잡으면 그 마이그레이션이 실패·롤백되고 DB는 한 버전 아래(V19 또는 V21)에 남으며 새 버전은
기동하지 않는다(`MIGRATION_FAILED`, exit 70). 열린 트랜잭션을 찾아 끝낸 뒤 다시 배포한다 —
`SELECT pid, state, xact_start, query FROM pg_stat_activity WHERE xact_start < now() - interval '5 seconds' ORDER BY xact_start;`
rolling 배포 중 아직 옛 버전인 인스턴스가 벽시계 번호로 쓴 행은 floor보다 크다. 새 버전의 counter는
그 aggregate의 가장 큰 행 번호보다 작아지지 않으므로 그 행 뒤에 번호를 준다. 서로 커밋되지 않은 채
겹친 옛·새 쓰기 사이의 순서는 보장하지 않는다 — 옛 벽시계 방식도 보장하지 않던 것이다.
이 "그 행 뒤에"는 **같은 aggregate identity**의 행에만 성립한다. tenant scope를 바꾸는 배포에서는 옛 버전이
옛 scope로, 새 버전이 새 scope로 쓴다. 새 버전의 counter는 옛 scope 행을 보지 못하므로 floor + 1부터 시작하고,
rolling 중 옛 버전이 방금 쓴 번호(floor보다 초당 10⁶씩 큰 벽시계 번호)보다 **작은** 번호를 준다(재리뷰
2026-11-03 2차 RR-02-10, 실 PG 확인). scope를 무시하고 aggregate id로 "마지막 번호보다 작으면 버린다"를 구현한
소비자는 그 사이 새 이벤트를 버린다. 그래서 **tenant scope를 바꾸는 배포는 rolling으로 하지 않는다**: 옛 버전
인스턴스를 모두 멈춘 뒤(옛·새 버전이 함께 쓰는 구간 없이) 새 버전을 띄운다.
tenant scope를 바꾼 서비스(샘플은 `portfolio` → 단일 scope)는 배포 전에 옛 scope의 미발행 행이
없는지 확인한다. 옛 scope 행과 새 scope 행은 서로 다른 aggregate로 보여 claim gate가 서로를 막지 않고,
partition key도 달라 다른 partition으로 간다.
@@ -231,7 +249,8 @@ Step 1을 다시 돌려 0행이면 배포한다. 정리와 배포 사이에 옛
확인 쿼리, 정리 SQL, Step 0의 인덱스 SQL은 이 문서에서 그대로 읽어 실제 PostgreSQL에서 실행하는
테스트가 있다(`PostgreSqlOutboxOrderKeyRunbookIntegrationTest`, lane
`postgresqlOutboxOrderKeyRunbookIntegrationTest`). 같은 lane이 V21의 counter·floor, 잠금 대기 실패,
INVALID 인덱스 거부도 본다. 이 절의 `runbook-sql` 블록을 고치면 그 lane을 다시 돌린다.
INVALID 인덱스 거부도 본다. 이 절의 `runbook-sql` 블록을 고치면 그 lane을 다시 돌린다. V20·V22의 잠금 대기
실패는 `PostgreSqlMigrationLockWaitIntegrationTest`(lane `postgresqlMigrationLockWaitIntegrationTest`)가 본다.
---
+9 -2
View File
@@ -4,7 +4,7 @@ category: TRANSIENT_DEPENDENCY
error_codes: [OUTBOX_PUBLISH_FAILED]
severity: P2
owner: oncall
last_updated: 2026-11-03
last_updated: 2026-11-04
status: stub
---
@@ -86,7 +86,8 @@ status: stub
**Step 1 — 찾기 (읽기 전용).** 미룬 claim(`deferred_attempt_count`)이 10번 이상인 FAILED 행이다. backoff 상한이
5분이라 10번은 적어도 약 35분 동안 계속 실패했다는 뜻이다. `outbox.retry.long.size`·`outbox.retry.long.age`가
같은 기준(`OutboxMetrics.LONG_RETRY_DEFERRED_CLAIMS`)으로 센다.
같은 기준(`OutboxMetrics.LONG_RETRY_DEFERRED_CLAIMS`)으로 센다. 아래 SQL의 숫자를 바꾸면 그 상수도 같이 바꾼다 —
`OutboxLongRetryRunbookContractTest`(lane `:composition:outbox-relay:outboxRelayDocumentContractTest`)가 둘을 비교한다.
<!-- runbook-sql: long-retries -->
```sql
@@ -114,6 +115,12 @@ UPDATE outbox_event SET status = 'PARKED' WHERE event_id = '<id>' AND status = '
`UPDATE 0`이면 그 사이 relay가 행을 claim해 IN_FLIGHT다. `next_attempt_at`이 지난 뒤 다시 실행한다.
보류된 행 수는 `outbox.pending.size{status=PARKED}`로 보인다.
**롤백 전에 보류를 푼다.** `PARKED`는 이 버전(`bbe944bd` 이후)에 생긴 상태다. 그보다 옛 버전은 이 이름을 몰라
상태별 집계 전체가 실패하고, `outbox.pending.size` 게이지가 PENDING까지 통째로 꺼진다 — `PENDING size growing`
경보의 입력이 사라진다(재리뷰 2026-11-03 2차 RR-02-11). 옛 버전으로 롤백해야 하면 그 전에 보류한 행을 모두
Step 3으로 재개하거나 버린다. 이 버전부터는 모르는 상태가 있어도 그 상태만 빼고 세고 WARN 한 번으로 이름을
말한다(`outbox_event holds rows in a status this version does not know`).
**Step 3 — 재개(resume) 또는 버리기(skip).** 원인을 고쳤으면 재개한다. 행은 FAILED로 돌아가 바로 claim
대상이 된다. 시도 횟수는 그대로 둔다(미룬 claim은 예산을 쓰지 않으므로 DEAD로 바로 가지 않는다).
+10 -8
View File
@@ -47,7 +47,9 @@ Redis liveness 실패만으로 pod를 재시작하지 않는다. 재시작 폭
로그와 health detail에서 확인한다. timeout이나 연결 끊김은 미실행 증거가 아니다.
- readiness는 최신 health detail의 state/reason/requirement로 본다. optional cache의 degraded serving과
required coordination/session의 fail-closed 결정을 같은 availability 의미로 합치지 않는다.
- reconnect, cache source-load, session repository error 지표의 변화를 함께 본다.
- 재연결은 `redis.lane.connections.opened.total`과 `discarded.total`을 함께 본다(Cluster `TRANSACTION`
lane은 borrow마다 열어 opened가 꾸준히 오른다 — `cache-redis/README.md`). cache source-load·session
repository 오류 지표는 내보내는 코드가 없다(설계만 있음).
- Redis server 측에서는 memory/eviction, rejected clients, replication link/lag,
persistence error, Cluster coverage를 operator dashboard에서 확인한다.
- `NOSCRIPT`, result-schema mismatch, ACL denial, TLS/auth failure, OOM, timeout을 서로 다른
@@ -57,21 +59,21 @@ Redis liveness 실패만으로 pod를 재시작하지 않는다. 재시작 폭
- `redis.lane.*` meter의 tag는 닫힌 lane 이름뿐이다. key, subject, session id, token, endpoint,
exception text, script/SHA, value 같은 identity/wire material을 metric이나 ticket에 복사하지 않는다.
- semantic operation 계측은 logical provider가 실제로 반환한 hit/miss/denied/conflict/
unavailable/indeterminate 결과를 기록한다. cache의 `stale`/`skipped`, session의
`tombstoned`/`absolute_expired`도 정상 hit/miss와 분리한다. meter registry, classifier,
monotonic ticker 장애는 command 결과나 원래 exception instance를 바꾸지 않는다.
- semantic operation 단위 계측(hit/miss/denied/conflict/unavailable/indeterminate 결과, cache의
`stale`/`skipped`, session의 `tombstoned`/`absolute_expired`)은 **설계만 있고 내보내지 않는다**
(`redis.capability.*`, 위 Detection 절). operation 결과는 로그와 health detail로 본다. `redis.lane.*`
계측(listener)이 실패해도 borrow 결과나 원래 exception은 바뀌지 않는다. 처음 실패는 WARN 로그 한 줄로
남고(`RedisRuntimeOwner`), 그 뒤는 DEBUG다 — 지표가 통째로 비면 그 WARN을 찾는다.
- route 응답이 설정된 byte/collection bound를 넘으면 동일 logical operation을
`unavailable`로 종료한다. GET/read-only 응답은 `not_applied`, mutation VALUE/MULTI 응답은
서버 실행 여부를 되돌릴 수 없으므로 `indeterminate`다. 앞선 `success` 표본과 이 실패를 두
operation으로 합산하지 않는다.
서버 실행 여부를 되돌릴 수 없으므로 `indeterminate`다.
- Spring 종료의 dependency order는 invalidation subscription 같은 capability dependent를 먼저
닫고, capability bean을 닫은 다음 canonical registry가 router admission을 닫아 in-flight를
bounded drain하고 마지막에 runtime을 닫는 순서다. 종료 중 새 command를 허용하거나 drain
timeout 뒤 무기한 기다리지 않는다.
- 현재 composition에는 active Redis scheduler나 dormant credential-rotation coordinator가 없다.
존재하지 않는 lifecycle coordinator를 복구 절차에서 찾거나 수동 호출하지 않는다.
- 이 meter와 단일-process lifecycle test는 Sentinel/Cluster failover, TLS/ACL 배포 적합성,
- `redis.lane.*` meter와 단일-process lifecycle test는 Sentinel/Cluster failover, TLS/ACL 배포 적합성,
k3s multi-node, L1/L2 분산 일관성, distributed session 동작의 qualification 증거가 아니다.
해당 label은 별도 topology/conformance lane의 실제 증거가 있어야 한다.
+34 -22
View File
@@ -21,13 +21,13 @@
|---|---|---|---|
| 1 | JWT 모드면 `APP_SECURITY_JWT_AUDIENCE`에 이 서비스의 client id를 쉼표로 넣는다 | 기동 실패 `APP_SECURITY_JWT_AUDIENCE (app.security.audience) is required` | JWT 모드(기본값) 전부 |
| 2 | dev·prod 환경 변수의 `APP_FLYWAY_ENABLED` 값을 확인한다 | `false`가 남아 있으면 이제 정말로 마이그레이션이 안 돈다 | persistence-jpa 선택 |
| 3 | prod 설정 어디에도 `fixture-`로 시작하는 값이 없게 한다 | prod 기동 실패(exit 78) | prod 배포 전부 |
| 4 | 직접 만든 `StartupRule`·`RequiredProductionSecrets` bean을 `static @Bean`, 의존성 없이 바꾼다 | 기동 실패 `startup rule '<이름>' created [...]`(exit 78) | 자기 rule이 있는 서비스 |
| 3 | prod 비밀값(레지스트리 `secret` 행, 모듈이 기여한 비밀, `secret://…/<VAR>`이 가리키는 변수)이 `fixture-`로 시작하지 않게 한다 | prod 기동 실패(exit 78) | prod 배포 전부 |
| 4 | 직접 만든 `StartupRule`·`RequiredProductionSecrets` bean을 `static @Bean`, 의존성 없이 바꾸고, 그 클래스에서 `@Value`·`@Autowired` 멤버와 `@ConfigurationProperties`를 뺀다 | 기동 실패 `startup rule '<이름>' created [...]` 또는 `'<이름>' (...) is a StartupRule or RequiredProductionSecrets ... but it needs one`(exit 78) | 자기 rule이 있는 서비스 |
| 5 | 직접 구현한 outbox·발행·알림·파일 서버 포트를 새 시그니처로 고친다(3.1절) | 컴파일 오류 | 해당 포트를 구현·호출하는 서비스 |
| 6 | `dev.caskeleton.application.outbound.*` import를 `application.secret.*`·`application.objectstorage.content.CallBudget`으로 바꾼다 | 컴파일 오류 | 해당 타입을 쓰는 서비스 |
| 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 |
| 9 | 이 브랜치의 이전 V21을 적용한 개발 DB를 다시 만든다(4.2절) | Flyway checksum 불일치로 기동 실패(exit 70) | 이 브랜치를 미리 받아 돌린 개발 DB |
| 9 | 이 브랜치의 이전 V21(또는 3차 수정 전 V20·V22·V11~V13·V8_1·V002·V003)을 적용한 개발 DB를 다시 만든다(4.2절) | Flyway checksum 불일치로 기동 실패(exit 70) | 이 브랜치를 미리 받아 돌린 개발 DB |
| 10 | 자기 SecurityFilterChain이 있으면 `DispatcherType.ERROR`를 허용한다 | 핸들러 밖 오류가 401로 바뀌어 나간다 | 자기 보안 체인을 둔 서비스 |
| 11 | 짝 프론트(또는 다른 클라이언트)에 7절 계약을 맞추게 한다 | 409를 재시도 불가로 읽거나, `null` 키를 기대하다 깨진다 | HTTP 클라이언트가 있는 서비스 |
| 12 | 자기 Flyway 마이그레이션 번호가 템플릿의 새 번호와 겹치지 않는지 본다(4절) | 같은 버전 두 개로 Flyway 실패 | 같은 stream에 자기 마이그레이션을 둔 서비스 |
@@ -56,8 +56,9 @@
| B-07 | 패키지 이동: `dev.caskeleton.application.outbound.SecretSourcePort`·`SecretReference` → `dev.caskeleton.application.secret.*`. `dev.caskeleton.application.outbound.CallBudget` → `dev.caskeleton.application.objectstorage.content.CallBudget`(leaf `application-objectstorage`). `application.outbound` 패키지 삭제 | `package dev.caskeleton.application.outbound does not exist` | import를 바꾼다. `CallBudget`을 쓰는 leaf가 `application-objectstorage`에 의존해도 되는지 `modules.json` 간선을 확인 | `5786126c` · `src/application-core/.../secret/`, `src/application-objectstorage/.../content/CallBudget.java` |
| B-08 | `shared-contract`에서 `dev.caskeleton.shared.operation.Operation`·`OperationStatus` 삭제. sample-portfolio(`...sample.portfolio.adapter.inbound.web.operation`)로 옮겨졌다 | import 실패 | 쓰고 있었다면 자기 inbound adapter로 복사한다 | `1400dc15` · `src/shared-contract/src/main/java/dev/caskeleton/shared/operation/`(삭제) |
| B-09 | `SecuritySettings`(adapter:inbound:web): `audience`가 `String` → `List<String>`. `@ConfigurationProperties` 제거, `SecuritySettings.bind(Environment)`로 strict 바인딩. 생성자 `(String, String, List)` → `(String, List<String>, List<String>)`. `bootstrap.security.AuthenticationModeSettings` 삭제 | `audience()`를 문자열로 쓰는 코드, 직접 생성하는 테스트 컴파일 오류 | `List<String>`으로 바꾼다. 인증 모드는 `SecuritySettings.authMode()`에서 읽는다 | `34565130`(List), `5786126c`(strict·삭제) · `src/adapter/inbound/web/.../settings/SecuritySettings.java` |
| 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` | import 실패. 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-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` |
### 3.2 설정·기동 — 기동이 실패하거나 런타임 예외가 난다
@@ -65,9 +66,9 @@
|---|---|---|---|---|
| B-12 | JWT 모드에서 `APP_SECURITY_JWT_AUDIENCE` 필수(빈 값 거부, `${...}`가 안 풀린 값도 없는 값으로 봄). 토큰 `aud`가 목록 중 하나를 담아야 통과. `resource_access` role은 audience에 적은 client 것만 읽는다(realm role은 그대로) | 기동 실패 `APP_SECURITY_JWT_AUDIENCE (app.security.audience) is required`(exit 코드 확인 못 함). `.env.example`이 `APP_SECURITY_JWT_AUDIENCE=`(빈 값)를 싣고 있다. 다른 client의 role에 기대던 권한이 사라짐 | client id를 쉼표로 넣는다. 다른 client role로 권한을 받던 사용자가 있는지 IdP에서 확인 | `34565130`(필수·role), `1400dc15`(안 풀린 `${...}`) · `src/adapter/inbound/web/.../auth/JwtDecoderConfig.java`, `.../JwtToAuthenticatedPrincipalConverter.java`, `.../settings/SecuritySettings.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-`로 시작하는 설정 값(변수 이름 무관)을 거부. 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 경로를 새 이름으로 | `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`만 받아야 한다 | non-static `@Bean`이거나 다른 bean을 받으면 기동 실패 `startup rule '<이름>' created [<bean>] while creating it ... Declare the rule with a static @Bean method ...`(exit 78) | rule 선언을 `static`으로, 인자를 위 셋으로 줄인다. 다른 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`, `INBOUND_ADAPTERS_DO_NOT_REACH_SYSTEM_INVOKED_USE_CASES` 추가 | 기동 실패 `@SystemInvoked use cases are registered as beans ...` 또는 `beans declare @RequiresPermission but no advisor enforces it ...`(exit 72). inbound adapter가 그 유스케이스를 부르면 architectureTest 실패 | 시스템만 부르는 쓰기 유스케이스는 composition에서 `new`로 만들어 호출자(scheduler 등)에 넘긴다. `@RequiresPermission`을 쓰면 web adapter(`MethodSecurityConfig`)가 조립돼 있어야 한다 | `1400dc15`, `bbe944bd` · `src/composition/service-runtime/.../authorization/PermissionEnforcementGuard.java`, `src/application-core/.../security/SystemInvoked.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 경로를 새 이름으로 | `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 '<이름>' created [<bean>] while creating it ... Declare the rule with a static @Bean method ...`, 위 멤버가 있으면 `'<이름>' (...) is a StartupRule or RequiredProductionSecrets ... but it needs one: [...]`(둘 다 exit 78, 후자는 모든 프로필) | 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` 추가, 새 표시 `@SystemCaller` | 기동 실패 `@SystemInvoked use cases are registered as beans ...` 또는 `beans declare @RequiresPermission but no advisor enforces it ...`(exit 72). `@SystemCaller`가 아닌 inbound adapter가 그 유스케이스를 부르면 architectureTest 실패 | 시스템만 부르는 쓰기 유스케이스는 composition에서 `new`로 만들어 호출자(scheduler 등)에 넘기거나, 메시지 handler면 handler에 `@SystemCaller`를 달고 생성자에서 `new`로 만든다(매뉴얼 09장 「소비」 4단계). `@RequiresPermission`을 쓰면 web adapter(`MethodSecurityConfig`)가 조립돼 있어야 한다 | `1400dc15`, `bbe944bd` · `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-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` |
@@ -75,10 +76,10 @@
| B-21 | 트랜잭션 제한: `TransactionPort` 쓰기·읽기 트랜잭션 30초(`app.persistence-jpa.transaction.write-timeout`·`read-timeout`, env 키 아님) | 30초를 넘는 트랜잭션은 문장이 취소되고 `DB_QUERY_CANCELED`로 실패 | 긴 일괄 작업은 쪼갠다. 꼭 필요하면 프로필 yml에서 값을 올린다 | `1400dc15` · `persistence-jpa.yml` |
| B-22 | 격리 수준을 Hikari에서 고정: `spring.datasource.hikari.transaction-isolation: TRANSACTION_READ_COMMITTED`. 다른 값이면 거부. `TransactionPort`는 트랜잭션마다 격리 수준을 정하지 않는다 | 다른 격리 수준을 설정했다면 기동 실패(`HikariPoolConstraintValidator`) | 값을 지운다. 더 높은 격리가 필요한 곳은 따로 설계한다 | `1400dc15` · `src/adapter/outbound/persistence-jpa/.../startup/HikariPoolConstraintValidator.java` |
| B-23 | H2 드라이버가 운영 jar에서 빠짐(persistence-jpa `runtimeOnly` → `testRuntimeOnly`). `bootRunH2` 작업만 따로 넣는다 | `APP_PERSISTENCE_VENDOR=h2`로 `bootRunH2` 밖에서 띄우면 드라이버가 없다(정확한 오류 확인 못 함) | 로컬은 Compose PostgreSQL 또는 `bootRunH2`를 쓴다 | `1400dc15` · `src/adapter/outbound/persistence-jpa/build.gradle` |
| B-24 | `APP_IDEMPOTENCY_PROCESSING_LEASE`는 2초(`IdempotencyExecutor.IN_FLIGHT_RETRY_AFTER`)보다 길어야 한다 | 2초 이하면 기동 실패 | 값을 2초보다 길게(기본 30s) | `5786126c`, `bbe944bd` · `src/composition/idempotency/.../IdempotencySettings.java` |
| B-24 | `APP_IDEMPOTENCY_PROCESSING_LEASE`는 2초(`IdempotencyExecutor.IN_FLIGHT_RETRY_AFTER`)보다 길어야 한다. `APP_IDEMPOTENCY_TTL`(replay TTL)은 그 lease보다 짧으면 안 된다(재리뷰 RR-03-11) | 2초 이하면, 또는 replay TTL < lease면 기동 실패 | lease를 2초보다 길게(기본 30s), replay TTL을 lease 이상으로(기본 24h) | `5786126c`, `bbe944bd`, 3차 수정 · `src/composition/idempotency/.../IdempotencySettings.java` |
| B-25 | 알림 콜백 본문 상한 65508 → 65251(바인딩에서 상한 검사) | `.env`에 옛 예제 값 `APP_NOTIFICATION_PLATFORM_CALLBACK_MAX_BODY_BYTES=65508`이 있으면 기동 실패 `max-body-bytes must be 1..65251` | 값을 지우거나 65251 이하로 | `5786126c` · `src/adapter/outbound/notification/.../autoconfigure/NotificationPlatformSettings.java` |
| B-26 | `config/module-defaults/`에 같은 이름 파일이 둘이거나, 두 파일이 같은 키를 실으면 기동 실패 | 기동 실패 `two capability modules ship config/module-defaults/<file>` 또는 `... both ship <key>`(exit 78) | 자기 leaf의 module-defaults 파일 이름·키가 템플릿 모듈과 겹치지 않게 한다 | `1400dc15` · `src/adapter/outbound/support/.../startup/ModuleDefaultsEnvironmentPostProcessor.java` |
| B-27 | (sample-portfolio를 남겨 둔 경우) 데모 계정은 활성 프로필이 모두 `local`·`test`·`demo` 중 하나일 때만. 프로필이 없어도 거부 | 기동 실패 `the sample's demo accounts authenticate only under the local, test or demo profile` | `SPRING_PROFILES_ACTIVE=local` 등으로 띄우거나 sample 보안 설정을 지운다 | `5786126c`, `bbe944bd` · `src/sample-portfolio/.../security/SampleDemoAccountsProductionGuard.java` |
| B-27 | (sample-portfolio를 남겨 둔 경우) 데모 계정은 활성 프로필이 모두 `local`·`test`·`demo` 중 하나일 때만. 프로필이 없어도 거부 | 기동 실패 `the sample's demo accounts authenticate only under the local, test or demo profile` | `SPRING_PROFILES_ACTIVE=demo`(이미지·jar), `local`(bootRun)로 띄우거나 sample 보안 설정을 지운다. 세 프로필 모두 sample `application.yml`이 object storage를 끈다(RR2-04-02) | `5786126c`, `bbe944bd` · `src/sample-portfolio/.../security/SampleDemoAccountsProductionGuard.java` |
### 3.3 HTTP wire — 응답이 달라진다
@@ -88,7 +89,7 @@
|---|---|---|---|---|
| B-28 | 처리 중 409 `IDEMPOTENT_IN_FLIGHT`: `retryable` false→true, `Retry-After: 2` 추가. gRPC trailer `error-retryable`과 GraphQL extension `retryable`도 true | 409를 "재시도 금지"로 처리하던 클라이언트가 틀린다 | **같은 `Idempotency-Key`로** `Retry-After` 뒤 재전송하게 한다. 새 키 금지 | `34565130` · `src/shared-contract/.../error/OperationalError.java`, `docs/registries/error-codes.yaml` |
| B-29 | Envelope의 `null` 필드를 키째 생략: 성공은 `error` 키 없음, 실패는 `data` 키 없음, `meta.page`·`meta.correlationId`·`error.details`도 값이 없으면 키 없음. 빈 목록은 그대로 | `"error": null`·`"data": null`을 기대하던 클라이언트·계약 테스트가 깨진다 | `success`로 가르고 키 존재로 판단하지 않는다 | `34565130` · `src/adapter/inbound/web/.../envelope/EnvelopeWireFormatConfig.java` |
| B-30 | 새 코드 `IDEMPOTENCY_COMPLETION_UNKNOWN`(503, `TRANSIENT_DEPENDENCY`, retryable=true): 작업 실행 **뒤** complete 단계에서 멱등성 저장소가 응답하지 않음. 전에는 `IDEMPOTENCY_UNAVAILABLE` | 503을 "적용 안 됨"으로 읽던 클라이언트가 새 키로 다시 보내 중복이 생길 수 있다 | `error.code`로 가른다. 결과 불명이므로 같은 키로만 재전송 | `bbe944bd` · `src/application-core/.../idempotency/IdempotencyCompletionUnknownException.java`, `IdempotencyExecutor.java` |
| B-30 | 새 코드 `IDEMPOTENCY_COMPLETION_UNKNOWN`(503, `TRANSIENT_DEPENDENCY`, retryable=true): 작업 실행 **뒤** complete 단계에서 멱등성 저장소가 응답하지 않음. 전에는 `IDEMPOTENCY_UNAVAILABLE` | 503을 "적용 안 됨"으로 읽던 클라이언트가 새 키로 다시 보내 중복이 생길 수 있다 | `error.code`로 가른다. 결과 불명이므로 같은 키로만 재전송. 실행 중 lease가 지난 기록은 두 저장소 모두 500 `IDEMPOTENCY_RECOVERY_REQUIRED`로 답한다 — Redis 저장소는 전에 넘겨받아 작업을 다시 돌렸다(재리뷰 RR-01-11) | `bbe944bd`, 3차 수정 · `src/application-core/.../idempotency/IdempotencyCompletionUnknownException.java`, `IdempotencyExecutor.java`, `src/adapter/outbound/cache-redis/.../idempotency/IdempotencyScripts.java` |
| B-31 | 핸들러 밖 오류(`/error` 디스패치)를 `EnvelopeErrorController`가 실패 Envelope로 답한다. 전에는 Boot `/error` 맵이 `success:true`로 감싸져 요청 경로까지 실려 나갔다. 기본 JWT 체인에서 익명 400이 401로 바뀌지 않는다. 4xx·5xx 본문은 `success:true`로 감싸지 않는다. 보안 체인이 `DispatcherType.ERROR`를 허용한다 | 오류 본문 모양이 바뀐다. 자기 SecurityFilterChain이 ERROR 디스패치를 막으면 400이 401로 나간다 | 자기 체인에 `auth.dispatcherTypeMatchers(DispatcherType.ERROR).permitAll()`을 넣는다(템플릿 `SecurityConfig`와 같게) | `bbe944bd` · `src/adapter/inbound/web/.../error/EnvelopeErrorController.java`, `.../auth/SecurityConfig.java` |
| B-32 | 새·바뀐 오류 코드: 비동기 요청 timeout 500 `INTERNAL_ERROR` → 503 `REQUEST_TIMEOUT`(retryable). `IDEMPOTENCY_KEY_INVALID` 400(`details.reason`=`MISSING`·`MALFORMED`, `IdempotencyKeyHeader.parse`를 쓰는 엔드포인트, sample은 `BAD_PARAMETER`에서 바뀜). web-advanced 예외 10종이 모두 500 `INTERNAL_ERROR`였다가 각자 코드(`ADMISSION_REFUSED` 503 등) | 코드로 분기하던 클라이언트가 새 코드를 모른다 | 클라이언트 분기표에 더한다. web-advanced 표는 `src/adapter/inbound/web-advanced/README.md` 「오류 응답」 | `1400dc15` · `src/adapter/inbound/web/.../error/WebTransportError.java`, `HttpStatusErrorCodes.java`, `src/adapter/inbound/web-advanced/.../error/WebAdvancedError.java` |
| B-33 | DB 실패 분류: 낙관적 잠금 충돌 500 → 409 `DB_OPTIMISTIC_CONFLICT`. 커밋 단계 연결 끊김(08xxx, 40003 등)을 재시도 가능으로 답하던 것 → 500 `DB_COMPLETION_UNKNOWN`(retryable=false) | 응답 status·code가 바뀐다 | 409는 다시 읽고 재시도, `DB_COMPLETION_UNKNOWN`은 업무 데이터로 결과를 확인 | `34565130`, `1400dc15` · `src/adapter/outbound/persistence-jpa/.../failure/PersistenceExceptionTranslator.java` |
@@ -99,7 +100,7 @@
|---|---|---|---|---|
| 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-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`를 읽는다. SpotBugs 신뢰도 HIGH → MEDIUM | 등록 안 한 leaf, 단계에 안 걸린 자기 lane, 자기 코드의 MEDIUM 발견이 `ci`·`qualityCheck`를 막는다 | leaf를 등록하거나 지운다. 자기 lane은 단계에 건다. SpotBugs 발견은 고치거나 이유를 단 제외로 | `1400dc15`, `34565130`, `bbe944bd`, `5786126c` · `src/build-logic/.../ModuleRegistry.java`, `.../strictlane/StrictLaneStagesPlugin.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`)와 `-p`를 합친 디렉터리로 정하고, `workflow_dispatch`로만 시작하는 workflow의 명령은 세지 않으며, 축약한 `-x`도 Gradle처럼 맞춰 본다(RR2-04-04). `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` 없이 `./gradlew`를 부르는 자기 workflow 단계는 실행으로 세지 않는다 | leaf를 등록하거나 지운다. 자기 lane은 단계에 건다. 단계를 부르는 workflow 명령에 `working-directory`를 둔다. SpotBugs 발견은 고치거나 이유를 단 제외로 | `1400dc15`, `34565130`, `bbe944bd`, `5786126c` · `src/build-logic/.../ModuleRegistry.java`, `.../strictlane/StrictLaneStagesPlugin.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` |
### 3.5 모듈 registry·새 leaf
@@ -114,26 +115,37 @@
| stream (history 표) | 버전 | 하는 일 | 기존 데이터 영향 | 실패 조건 | 근거 |
|---|---|---|---|---|---|
| postgresql (`flyway_schema_history`, persistence-jpa 선택 시) | V20 | `outbox_event.deferred_attempt_count INTEGER NOT NULL DEFAULT 0` + CHECK ≥ 0 | 기존 행 0. 지난 claim은 전부 시도 예산에 센다 | 확인된 것 없음 | `1400dc15` |
| postgresql (`flyway_schema_history`, persistence-jpa 선택 시) | V20 | `outbox_event.deferred_attempt_count INTEGER NOT NULL DEFAULT 0` + CHECK ≥ 0 | 기존 행 0. 지난 claim은 전부 시도 예산에 센다 | `outbox_event`를 건드린 트랜잭션이 열려 있어 5초 안에 잠금을 못 잡으면 실패·롤백, V19에 남음(exit 70) | `1400dc15`, 3차 수정(RR-02-09) |
| 〃 | V21 | `outbox_aggregate_sequence`(aggregate별 counter), `outbox_aggregate_sequence_floor`(V21 적용 시각 마이크로초 한 행), 남은 행 최대 번호로 counter 미리 생성, 유일 인덱스 `ux_outbox_event_aggregate_order (tenant_scope, aggregate_type, aggregate_id, aggregate_sequence, event_index)` | 새로 생기는 aggregate의 첫 번호가 floor+1(약 1.7×10¹⁵)부터. 순서 열이 NULL인 옛 행은 비교 안 함 | ① 같은 순서 키 행이 이미 둘 이상 → 실패, V21 전체 롤백, V20에 남음(exit 70). ② `SET LOCAL lock_timeout = '5s'` 안에 `outbox_event` 잠금을 못 잡으면 실패·롤백. ③ 같은 이름 인덱스가 유효한 유일 인덱스가 아니면(실패한 CONCURRENTLY) `RAISE EXCEPTION` | `1400dc15`, `bbe944bd` · `docs/runbooks/outbox-dead-letter.md` §8 |
| 〃 | V22 | `outbox_event.last_failure_code VARCHAR(120)` NULL, 기본값 없음. 새 상태 `PARKED`는 DDL 없음 | 행 재작성 없음. 기존 행은 다음 실패 때까지 NULL | 확인된 것 없음 | `bbe944bd` |
| notification (`flyway_jpa_notification_history`, notification-platform 선택 시) | V11 | `notification_reconciliation_job.claimed_until timestamptz`, `claim_fence bigint NOT NULL DEFAULT 0` + CHECK | 기존 job은 fence 0, lease 없음 | 확인된 것 없음 | `34565130` |
| 〃 | V12 | `notification_suppression`의 `(tenant_id, normalized_target_hmac, reason)` 중복 행을 **삭제**(만료 없는 것 > 늦은 만료 > 이른 `effective_at` > 이른 `created_at` > 작은 id 순으로 하나 남김) 후 UNIQUE `uk_notification_suppression_target` | 지운 행의 `SuppressionId`는 더 이상 조회되지 않는다. 되돌리려면 백업 필요 | 확인된 것 없음(잠금 대기 제한 없음) | `1400dc15` |
| 〃 | V13 | `notification_request.acceptance varchar(40) NOT NULL DEFAULT 'ACCEPTED'` + CHECK(`ACCEPTED`, `DROPPED_AS_DUPLICATE`) | 기존 요청은 모두 `ACCEPTED` | 확인된 것 없음 | `5786126c` |
| sample (`flyway_sample_schema_history`, sample-portfolio를 남긴 경우) | V8_1 | 유일 인덱스 `uq_poster_title_ci ON poster (upper(title))` | 없음 | 대소문자만 다른 제목이 있으면 `poster has titles that differ only by case or repeat: ...`로 실패 | `34565130` |
| grpc-ledger (optional-platforms, history 표 확인 못 함) | V002 | 부분 인덱스 `ix_grpc_operation_ledger_finished_completed_at` (일반 `CREATE INDEX`) | 없음 | 큰 ledger면 만드는 동안 쓰기가 멈춘다. 파일 주석은 손으로 `CONCURRENTLY`를 먼저 돌리라고 한다 | `1400dc15` |
| 〃 | V003 | `grpc_operation_ledger.claim_attempt BIGINT NOT NULL DEFAULT 1` + CHECK > 0 | 기존 행은 첫 시도(1) | 확인된 것 없음 | `bbe944bd` |
| 〃 | V22 | `outbox_event.last_failure_code VARCHAR(120)` NULL, 기본값 없음. 새 상태 `PARKED`는 DDL 없음 | 행 재작성 없음. 기존 행은 다음 실패 때까지 NULL | `outbox_event`를 건드린(읽기만 한 것도) 트랜잭션이 열려 있어 5초(`SET LOCAL lock_timeout`) 안에 잠금을 못 잡으면 실패·롤백, V21에 남음(exit 70) | `bbe944bd`, 3차 수정(RR-02-09) |
| notification (`flyway_jpa_notification_history`, notification-platform 선택 시) | V11 | `notification_reconciliation_job.claimed_until timestamptz`, `claim_fence bigint NOT NULL DEFAULT 0` + CHECK | 기존 job은 fence 0, lease 없음 | 그 표를 건드린 트랜잭션이 열려 있어 5초 안에 잠금을 못 잡으면 실패·롤백, V10에 남음(exit 70) | `34565130`, 3차 수정(RR-02-09) |
| 〃 | V12 | `notification_suppression`의 `(tenant_id, normalized_target_hmac, reason)` 중복 행을 **삭제**(만료 없는 것 > 늦은 만료 > 이른 `effective_at` > 이른 `created_at` > 작은 id 순으로 하나 남김) 후 UNIQUE `uk_notification_suppression_target` | 지운 행의 `SuppressionId`는 더 이상 조회되지 않는다. 되돌리려면 백업 필요 | 그 표를 건드린 트랜잭션이 열려 있어 5초 안에 잠금(행 잠금 포함)을 못 잡으면 실패·롤백(삭제도 롤백), V11에 남음(exit 70) | `1400dc15`, 3차 수정(RR-02-09) |
| 〃 | V13 | `notification_request.acceptance varchar(40) NOT NULL DEFAULT 'ACCEPTED'` + CHECK(`ACCEPTED`, `DROPPED_AS_DUPLICATE`) | 기존 요청은 모두 `ACCEPTED` | 그 표를 건드린 트랜잭션이 열려 있어 5초 안에 잠금을 못 잡으면 실패·롤백, V12에 남음(exit 70) | `5786126c`, 3차 수정(RR-02-09) |
| sample (`flyway_sample_schema_history`, sample-portfolio를 남긴 경우) | V8_1 | 유일 인덱스 `uq_poster_title_ci ON poster (upper(title))` | 없음 | 대소문자만 다른 제목이 있으면 `poster has titles that differ only by case or repeat: ...`로 실패. `poster`에 쓴 트랜잭션이 열려 있어 5초 안에 잠금을 못 잡으면 실패·롤백, V8에 남음 | `34565130`, 3차 수정(RR-02-09) |
| grpc-ledger (optional-platforms, history 표 확인 못 함) | V002 | 부분 인덱스 `ix_grpc_operation_ledger_finished_completed_at` (일반 `CREATE INDEX`) | 없음 | 큰 ledger면 만드는 동안 쓰기가 멈춘다. 파일 주석은 손으로 `CONCURRENTLY`를 먼저 돌리라고 한다. ledger에 쓴 트랜잭션이 열려 있어 5초 안에 잠금을 못 잡으면 실패·롤백, V001에 남음 | `1400dc15`, 3차 수정(RR-02-09) |
| 〃 | V003 | `grpc_operation_ledger.claim_attempt BIGINT NOT NULL DEFAULT 1` + CHECK > 0 | 기존 행은 첫 시도(1) | ledger를 건드린 트랜잭션이 열려 있어 5초 안에 잠금을 못 잡으면 실패·롤백, V002에 남음 | `bbe944bd`, 3차 수정(RR-02-09) |
- **새로 연결된 stream**: `adapter:inbound:messaging`을 `runtimeOnly`로 넣으면 platform의 `V1101__messaging_inbox.sql`을
`MessagingInboxSchemaStream`이 `flyway_messaging_inbox_history`에 적용한다(baseline 1100). 넣지 않으면 영향 없음
(`src/adapter/inbound/messaging/README.md`).
- **잠금 대기 상한(3차 수정, RR-02-09)**: 위 표에서 이미 쓰이는 테이블을 잠그는 마이그레이션은 모두 그 잠금 앞에
`SET LOCAL lock_timeout = '5s'`를 둔다. 실패하면 SQLState `55P03`이고, 열린 트랜잭션을 끝낸 뒤 다시 배포한다
(`docs/runbooks/migration-failed.md` "Classify the failure"). 자기 스트림에도 같은 규칙과 검사
(`LockWaitMigrationInspector`, 예: `SampleMigrationLockWaitTest`)를 둔다(`docs/jpa/migration-guide.md` "Bound the lock wait").
- **번호 충돌**: 템플릿이 이제 postgresql V20~V22, notification V11~V13, sample V8_1, grpc V002·V003을 쓴다. 파생 서비스가 같은
위치에 같은 번호를 두었다면 Flyway가 같은 버전 두 개로 실패한다. 자기 마이그레이션은 템플릿과 떨어진 번호대로 옮긴다
(이미 적용된 파일 이름을 바꾸면 checksum·history가 어긋나므로 운영 DB에 적용된 것이면 DB 담당과 정한다).
- **migration-on-startup=false로 운영하는 서비스**: `infra/postgres/apply-capability-streams.sh`가 바뀌었다(stream을
`/flyway/streams/<name>`에서 먼저 찾음). 운영자가 직접 적용한다.
### 4.2 이 브랜치의 이전 V21을 적용한 DB
### 4.2 이 브랜치의 이전 V21(과 3차 수정 전 V20·V22·V11~V13·V8_1·V002·V003)을 적용한 DB
3차 수정(RR-02-09)은 이 브랜치가 더한 마이그레이션 중 이미 쓰이는 테이블을 잠그는 여덟 개(postgresql V20·V22,
notification V11·V12·V13, sample V8_1, grpc-ledger V002·V003)에 `SET LOCAL lock_timeout`을 넣으려고 파일을 직접
고쳤다. V21과 같은 전제(어느 배포에도 적용되지 않음)다. 그 이전 내용을 적용한 개발 DB도 아래 V21과 같이 checksum
불일치로 기동이 실패하므로 다시 만든다. 새 checksum은 `applied-migrations.sha256`에 있다(sample·grpc-ledger는 고정 목록
없음).
V21은 `bbe944bd`에서 V22를 따로 두지 않고 직접 고쳤다(floor 표와 counter 미리 만들기를 넣음). `1400dc15`·`5786126c` 시점의
V21(sha256 `f830cda5…`)을 적용한 DB는 새 V21(sha256 `21744ea1…`, `src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256`)과
@@ -182,7 +194,7 @@ V21 실패의 분류는 `docs/runbooks/migration-failed.md` "Classify the failur
| 영역 | 바뀐 것 | 영향 | 근거 |
|---|---|---|---|
| outbox relay | 일시 거부(`REJECTED_RETRYABLE`)·무응답(`AMBIGUOUS`)은 시도 예산을 쓰지 않고 최대 5분 간격(`OutboxBackoffPolicy.MAX_DELAY`)으로 끝없이 재시도. 실패 원인 코드를 `last_failure_code`에 남김. 수동 보류 상태 `PARKED`. 지표 `outbox.retry.long.size`·`outbox.retry.long.age` | 진짜 인증 오류도 DEAD가 아니라 계속 재시도한다. 경보는 새 지표로 잡는다. 처분 SQL은 `docs/runbooks/outbox-dead-letter.md`·`outbox-publish-failed.md` | `34565130`, `1400dc15`, `bbe944bd` |
| outbox relay | 일시 거부(`REJECTED_RETRYABLE`)·무응답(`AMBIGUOUS`)은 시도 예산을 쓰지 않고 최대 5분 간격(`OutboxBackoffPolicy.MAX_DELAY`)으로 끝없이 재시도. 실패 원인 코드를 `last_failure_code`에 남김. 수동 보류 상태 `PARKED`. 지표 `outbox.retry.long.size`·`outbox.retry.long.age`. claim이 DEAD로 옮긴 행(`ATTEMPT_COUNTERS_INCONSISTENT`·`UNREADABLE_ROW`)도 그 이유를 `last_failure_code`에 쓰고, 경보에 `outbox.pending.size{status=DEAD}` > 0을 더함(RR-02-12). 이 버전이 모르는 상태 값은 `outbox.pending.size`에서 빼고 WARN 한 번(RR-02-11) | 진짜 인증 오류도 DEAD가 아니라 계속 재시도한다. 경보는 새 지표로 잡는다. 처분 SQL은 `docs/runbooks/outbox-dead-letter.md`·`outbox-publish-failed.md` | `34565130`, `1400dc15`, `bbe944bd` |
| outbox append | 읽기 전용 트랜잭션 안의 `append`도 거부(`CallerTransaction.requireReadWrite`). 전에는 트랜잭션 밖만 거부했고 읽기 전용에서는 이벤트가 조용히 사라졌다 | `inRead` 안에서 이벤트를 쓰던 코드가 이제 예외로 드러난다 | `5786126c` · `JpaOutboxStore.java` |
| 순서 번호 | aggregate 순서 번호를 DB counter가 매긴다(`OutboxAggregateSequencePort.nextSequence`). 한 aggregate에 이벤트가 하나면 `AggregateOrder.first()`. 같은 순서 키 두 번째 append는 유일 인덱스가 거부(정확한 오류 코드 확인 못 함) | 소비자가 보는 번호가 새 aggregate에서 floor+1부터 시작해 크게 뛴다. 벽시계로 번호를 만들던 코드는 바꾼다 | `1400dc15`, `bbe944bd` |
| durable operation | operation id가 UUIDv7(`UuidV7DurableOperationIdFactory`). 제출 이벤트의 event id·aggregate id가 UUIDv7이고 tenant scope는 `global` | 전에는 이 이벤트가 messaging bridge에서 전부 DEAD가 됐다(커밋 `1400dc15` 본문). 소비자가 보는 id 모양이 바뀐다 | `1400dc15`, `bbe944bd` · `SubmitDurableOperationUseCase.java` |
@@ -192,7 +204,7 @@ V21 실패의 분류는 `docs/runbooks/migration-failed.md` "Classify the failur
| GraphQL | 크기를 선언하지 않은 list를 원소 20개로 계산, `first`·`last` 둘 다면 큰 쪽. per-parent 경고 임계 10(`APP_GRAPHQL_PER_PARENT_FETCH_WARNING_THRESHOLD`). deadline instrumentation이 `REQUEST_TIMEOUT` | 전에 통과하던 깊은 목록 쿼리가 복잡도로 거부될 수 있다. 필요한 필드에 `estimatedListSize`를 선언 | `34565130`, `1400dc15`, `bbe944bd` |
| WebSocket | 노드당 STOMP 세션 1000개(`APP_WEBSOCKET_MAX_CONNECTIONS`), 초과 시 연결 후 1013으로 닫음. 메시지 64KB, 송신 버퍼 512KB, 송신 시간 10s, 첫 메시지 60s를 명시 | 동시 연결이 많은 서비스는 상한을 올린다 | `1400dc15` · `env-keys.yaml` |
| gRPC 서버(inbound adapter) | 수신 메시지 1 MiB(io.grpc 기본 4 MiB에서 줄어듦), 메타데이터 8 KiB, 연결당 동시 호출 100, 실행 스레드 32·대기열 256, 기본 deadline 10s, keepalive 30s/10s, 최대 연결 수명 30분, drain 2s | 1 MiB를 넘는 메시지는 거부된다 | `1400dc15` · `src/adapter/inbound/grpc/.../GrpcServerSettings.java` |
| 파일 서버 | 정리 worker 기본 켜짐(`APP_FILESERVER_PLATFORM_CLEANUP_ENABLED` false→true, 끄면 기동 경고). copy·move 대상은 기본 namespace만(`APP_FILESERVER_PLATFORM_TARGET_NAMESPACES`, 그 밖은 `ACCESS_DENIED`). namespace 쿼터 상한(`APP_FILESERVER_PLATFORM_QUOTA_NAMESPACE_LIMIT`, 비우면 무제한, 넘으면 413 `QUOTA_EXCEEDED`). move가 쿼터를 옮긴다 | 다른 namespace로 copy·move하던 서비스는 허용 목록을 설정해야 한다. 정리 worker가 물리 객체를 지운다 | `5786126c`, `bbe944bd` · `CopyFileApplicationUseCase.java`, `env-keys.yaml` |
| 파일 서버 | 정리 worker 기본 켜짐(`APP_FILESERVER_PLATFORM_CLEANUP_ENABLED` false→true, 끄면 기동 경고). copy·move 대상은 기본 namespace만(`APP_FILESERVER_PLATFORM_TARGET_NAMESPACES`, 그 밖은 `ACCESS_DENIED`). namespace 쿼터 상한(`APP_FILESERVER_PLATFORM_QUOTA_NAMESPACE_LIMIT`, 비우면 무제한, 넘으면 413 `QUOTA_EXCEEDED`). move가 쿼터를 옮긴다 | 다른 namespace로 copy·move하던 서비스는 허용 목록을 설정해야 한다. 정리 worker가 물리 객체를 지운다. 이 수정 전에 다른 namespace로 move된 파일의 바이트는 여전히 출발 namespace 사용량에 잡혀 있고 도착 namespace에는 없다 — 그 파일을 지우면 도착 namespace에서 회수되어(0에서 멈춘다) 출발 쪽은 그대로 남는다. 상한을 켜기 전에 `docs/fileserver/operations.md` 「Namespace quota drift」의 쿼리로 namespace별 차이를 보고, 있으면 같은 절의 재계산 SQL로 고친다(쓰기를 멈춘 뒤, 재리뷰 RR-01-17) | `5786126c`, `bbe944bd` · `CopyFileApplicationUseCase.java`, `env-keys.yaml` |
| 알림 | SES 콜백 replay 허용 차이 5m→1h. 중복 제거 창에서 버린 제출을 `CANCELED`·`DROPPED_AS_DUPLICATE`로 저장해 같은 멱등성 키에 같은 영수증. reconciliation job은 DB lease로 소유. INGEST_ONLY도 accept 때 route 이름 기록 | 콜백·영수증 결과가 바뀐다 | `34565130`, `5786126c` |
| Redis | 캐시 조건부 쓰기가 자기 SCRIPT lane(`APP_CACHE_REDIS_MAXIMUM_SCRIPT_CONNECTIONS`, 기본 4)을 쓴다. registry에서 `redis.capability.*` 지표 6개를 빼고 `redis.lane.*` 6개를 더했다 | Redis 연결이 캐시 lane만큼 늘어난다. 옛 지표 이름으로 만든 대시보드·경보는 바꾼다 | `bbe944bd` · `docs/registries/metrics.yaml` |
| 설정 바인딩 | strict 설정에서 선택 숫자·크기·기간 키의 빈 값은 "미설정". 목록 원소 아래 오타 키도 거부(`StrictSettingsBinder`) | `.env.example`의 빈 값으로 기동 가능. 목록 원소 아래 오타는 이제 기동 실패 | `5786126c` · `StrictSettingsBinder.java` |
+22 -9
View File
@@ -56,9 +56,16 @@ JSON 응답은 모두 `Envelope` 하나의 모양이다(소유자 결정 2). **
컨트롤러에 닿기 전에 거부된 요청(보안 방화벽이 막은 경로, 필터의 `sendError`, 필터가 던진 예외)도 같은
실패 Envelope다. 컨테이너가 `/error`로 넘긴 요청을 `EnvelopeErrorController`가 status에 맞는 코드로 답한다.
본문에 요청 경로나 시각을 싣지 않는다. 원래 status가 그대로 나가고, 기본 JWT 체인에서도 익명 400이 401로
바뀌지 않는다(재리뷰 RR-02-02). 다만 요청 id 필터를 지나기 전에 끊긴 응답은 `meta`의 id 키가 빠질 수 있다.
클라이언트는 `meta`의 모르는 키를 무시한다.
본문에 요청 경로나 시각을 싣지 않는다. 기본 JWT 체인에서도 익명 400이 401로 바뀌지 않는다(재리뷰 RR-02-02).
다만 요청 id 필터를 지나기 전에 끊긴 응답은 `meta`의 id 키가 빠질 수 있다. 클라이언트는 `meta`의 모르는 키를
무시한다.
status는 코드 표(`HttpStatusErrorCodes`)에 있는 것만 그대로 나간다: 401·403·404·405·406·412·413·414·415·429·503.
표에 없는 status는 그 class의 코드로 접힌다 — 4xx(408·409·410·422 등)는 `BAD_PARAMETER` 400, 5xx(501·502·504
등)는 `INTERNAL_ERROR` 500(재리뷰 RR-01-13, `EnvelopeErrorControllerTest`). `error.code`와 status가 registry
(`docs/registries/error-codes.yaml`)와 어긋나지 않게 하려는 것이다. 클라이언트는 status가 아니라 `error.code`로
가르기 때문이다. 필터가 다른 status를 내야 하면 `sendError` 대신 그 status의 코드로 `EnvelopeResponseWriter`를
쓰거나, 표에 행을 더한다.
4xx·5xx status로 나가는 본문은 `success:true`로 감싸지 않는다. 실패 Envelope가 아닌 본문을 오류 status로
돌려주는 핸들러는 그 본문이 그대로 나간다.
@@ -105,13 +112,19 @@ JSON 응답은 모두 `Envelope` 하나의 모양이다(소유자 결정 2). **
| 작업 실행 뒤 결과 기록(complete 단계) 중 저장소 응답 없음 — **결과 불명** | 503 | `IDEMPOTENCY_COMPLETION_UNKNOWN` | `true` | 없음 | "적용되지 않았다"고 알리지 않는다. **같은 키로** 나중에 다시 보낸다. 새 키 금지 |
| 이전 시도의 효과를 증명할 수 없음 | 500 | `IDEMPOTENCY_RECOVERY_REQUIRED` | `false` | 없음 | 재전송도 재실행도 안전하지 않다. 업무 데이터로 결과를 확인한다 |
- **결과 불명이 무엇을 뜻하나.** 작업은 이미 돌았다. 그 작업의 트랜잭션 안 DB 변경은 예외와 함께
롤백되지만, 트랜잭션 밖 효과(다른 시스템 호출, 메시지)는 일어났을 수 있다. 그래서 실행 전 거부와 같은
- **결과 불명이 무엇을 뜻하나.** 작업은 이미 돌았다. 유스케이스가 executor를 쓰기 트랜잭션 안에서
불렀다면 그 트랜잭션의 DB 변경은 예외와 함께 롤백된다. 작업이 자기 트랜잭션을 따로 커밋했다면 그 변경은
남는다. 트랜잭션 밖 효과(다른 시스템 호출, 메시지)는 일어났을 수 있다. 그래서 실행 전 거부와 같은
503이어도 code가 다르다. 클라이언트는 status가 아니라 `error.code`로 가른다.
- **같은 키로 다시 보내면 서버가 판정한다.** 결과가 실제로는 기록됐으면 재생(첫 요청의 성공 응답), 첫 시도의
processing lease가 아직 남았으면 409 `IDEMPOTENT_IN_FLIGHT`, lease가 지났으면 500
`IDEMPOTENCY_RECOVERY_REQUIRED`다. 새 키로 보내면 서버는 다른 요청으로 보고 막지 못한다
(재리뷰 2026-11-03 README 4절 결정, RR-02-03).
- **같은 키로 다시 보내면 서버가 판정하고, 작업을 다시 돌리지 않는다.** 결과가 실제로는 기록됐으면
재생(첫 요청의 성공 응답), 첫 시도의 processing lease(`processing-lease`, 기본 30s)가 아직 남았으면 409
`IDEMPOTENT_IN_FLIGHT`, lease가 지났으면 500 `IDEMPOTENCY_RECOVERY_REQUIRED`다. lease가 지난 실행 기록을 다음
요청이 만나면 두 저장소(PostgreSQL·Redis) 모두 넘겨주지 않고 포기(abandoned)로 표시한다 — 그 뒤 첫 시도가
늦게 끝나도 결과는 기록되지 않고 그 요청도 500을 받는다. 새 키로 보내면 서버는 다른 요청으로 보고 막지 못한다
(재리뷰 2026-11-03 README 4절 결정 RR-02-03, 2026-11-04 9.1절 결정 RR-01-11).
- **서버가 기억하는 기간.** 완료된 응답은 완료부터 `replay-ttl`(기본 24h), 끝나지 않은 시도의 기록은
claim부터 processing lease + `replay-ttl` 동안 남는다. 그 뒤 같은 키는 새 요청으로 실행된다.
`replay-ttl`이 `processing-lease`보다 짧으면 기동이 실패한다(재리뷰 2026-11-04 RR-03-11).
## 3. 헤더
+6 -3
View File
@@ -8,9 +8,12 @@ a real Redis, that line alone gives anyone who can reach the server and read thi
control of it (`CONFIG`, `MODULE`, every key). A deployment writes its own ACL file of the same
shape: the application accounts it actually uses, passwords from its secret store, and none of the
lane-only accounts (review 2026-11-03 RR-07-04). The application enforces its half of that: under
the `prod` runtime profile it refuses to start while any setting or environment variable holds a
value beginning with `fixture-` (`SecretSourceValidator`), so a deployment that copied a lane's
`REDIS_LANE_*` values stops before it connects.
the `prod` runtime profile it refuses to start while a secret holds a value beginning with
`fixture-` (`SecretSourceValidator`): a key the secrets registry classifies `secret`, or the
variable a `secret://…/<VAR>` credential reference names. A deployment that copied a lane's
`APP_REDIS_AUTHENTICATION_*_REFERENCE` and `REDIS_LANE_*` values stops before it connects. Values
that are not secrets — a pod's `HOSTNAME`, an application name — are not read, because `fixture-`
is an ordinary word as well.
One file per `CommandAccess` level. Each account is deliberately narrower than the SDK's own rules:
the account is the last enforcement boundary and a permit issued inside the process never widens it,
+3 -1
View File
@@ -121,6 +121,7 @@ APP_RATE_LIMIT_REFILL_TOKENS=100
APP_RATE_LIMIT_REFILL_PERIOD=1s
APP_RATE_LIMIT_MAXIMUM_COST=10
APP_RATE_LIMIT_CLEANUP_GRACE=5s
# Replay TTL: at most 72h and not shorter than APP_IDEMPOTENCY_PROCESSING_LEASE (startup fails).
APP_IDEMPOTENCY_TTL=24h
# disabled | redis | postgresql. postgresql refuses a non-PostgreSQL data source, so bootRunH2
# runs with disabled or redis.
@@ -294,7 +295,8 @@ APP_GRAPHQL_PER_PARENT_FETCH_WARNING_THRESHOLD=10
# Optional build-composition: these bind only when :adapter:inbound:websocket is present.
# The default bootJar does not contain that leaf.
APP_WEBSOCKET_ENABLED=true
# Explicit offs for two more capabilities that are on when present (the Compose lanes set them).
# Switches for two more capabilities that are on when present: `true` here is their default, and
# `false` is the explicit off the Compose lanes set.
APP_OBJECTSTORAGE_ENABLED=true
APP_GRPC_SERVER_ENABLED=true
APP_WEBSOCKET_ENDPOINT=/ws
+8 -2
View File
@@ -5,14 +5,20 @@
# Builds and runs the REFERENCE app (SamplePortfolioApplication), not the
# production composition root (CaSkeletonApplication) that src/Dockerfile builds.
# The sample is the demo-friendly entrypoint: its application.yml self-provides
# defaults for every env placeholder, so the only external dependency it needs
# to boot is a reachable PostgreSQL (datasource + Flyway sample migrations).
# defaults for every env placeholder, so what it needs to boot is a demo profile
# and a reachable PostgreSQL (datasource + Flyway sample migrations).
#
# The profile is not baked in. The demo accounts (a published admin password) start only under an
# explicitly active `demo`, `local` or `test` profile (SampleDemoAccountsProductionGuard), and an
# image that defaulted to one would carry them into any deployment that ran it as is. Without
# SPRING_PROFILES_ACTIVE the container stops with exit code 71 and says so.
#
# Build (no build-args required — this is a disposable demo, not a release artifact):
# docker build -f src/Dockerfile.sample src/ -t ca-sample:local
#
# Run (point APP_DATASOURCE_URL at a reachable Postgres; localhost default shown):
# docker run --rm -p 8080:8080 -p 9001:9001 \
# -e SPRING_PROFILES_ACTIVE=demo \
# -e APP_DATASOURCE_URL=jdbc:postgresql://host.docker.internal:5432/ca_skeleton \
# ca-sample:local
#
+2 -1
View File
@@ -236,7 +236,8 @@ drift하기 시작하면 그때 자동화합니다. 진짜 항목을 상대로,
`postgresql` 은 PostgreSQL data source 가 아니면 기동을 거부하므로 `bootRunH2` 에서는
`disabled` 나 `redis` 를 씁니다.
- **`APP_IDEMPOTENCY_TTL`** — 완료 응답을 재생할 수 있는 기간(`replay-ttl`). duration(예: `24h`).
최대 72h 이고 넘으면 기동을 거부합니다. (D6)
최대 72h 이고 넘으면 기동을 거부합니다. (D6) `APP_IDEMPOTENCY_PROCESSING_LEASE`(기본 30s)보다
짧아도 기동을 거부합니다.
### Async executor
@@ -23,7 +23,10 @@ import java.time.Duration;
* @param maxFragments most accepted fragment definitions
* @param maxInputListElements most accepted elements in one input list
* @param defaultPageSize page size used for cost when a connection omits {@code first}/{@code last}
* @param maxPageSize largest accepted page size
* @param maxPageSize largest accepted page size. This record only holds the two numbers; the page a
* resolver serves is decided by {@code GraphQlConnectionPolicy.effectivePageSize} and the page
* a document is charged for by the complexity scorer — one rule each, not a third copy here
* (review 2026-11-03 RR-01-14)
* @param maxComplexity largest accepted pre-execution complexity score
* @param maxExecutionTime request execution budget
* @param introspectionAllowed whether this profile may run introspection
@@ -92,20 +95,6 @@ public record GraphQlClientPolicy(
false);
}
/**
* The effective page size for a connection request.
*
* <p>An omitted {@code first}/{@code last} must cost the default page size rather than one, or a
* client could bypass the cost budget simply by leaving the argument out.
*/
public int effectivePageSize(Integer first, Integer last) {
int requested = first != null ? first : last != null ? last : defaultPageSize;
if (requested < 1) {
throw new IllegalArgumentException("page size must be positive");
}
return requested;
}
private static void requirePositive(long value, String name) {
if (value < 1) {
throw new IllegalArgumentException(name + " must be positive");
@@ -91,6 +91,18 @@ class GraphQlConnectionAssemblerTest {
.hasMessageContaining("exceeds the maximum");
}
/** The {@code last} case of the page-size rule that used to be copied in the client policy. */
@Test
void aBackwardPageIsSizedByItsLastAndAnOmittedOneByTheDefault() {
var policy = GraphQlConnectionPolicy.from(clientPolicy());
assertThat(
List.of(
policy.effectivePageSize(GraphQlConnectionRequest.backward(30, null)),
policy.effectivePageSize(GraphQlConnectionRequest.backward(null, null))))
.containsExactly(30, 20);
}
@Test
void totalCountIsOptInRatherThanAlwaysComputed() {
var connection =
@@ -38,15 +38,6 @@ class GraphQlClientPolicyTest {
.isInstanceOf(IllegalArgumentException.class);
}
@Test
void omittedPageSizeCostsTheDefaultRatherThanOne() {
GraphQlClientPolicy policy = policy(65536, 20, 100, Duration.ofSeconds(5));
assertThat(policy.effectivePageSize(null, null)).isEqualTo(20);
assertThat(policy.effectivePageSize(50, null)).isEqualTo(50);
assertThat(policy.effectivePageSize(null, 30)).isEqualTo(30);
}
@Test
void productionProfileCanRequireNamedOperations() {
GraphQlClientPolicy publicProfile =
+3
View File
@@ -10,6 +10,9 @@
else: the platform decodes what its `destination()` and `schemaVersions()` declare.
- Boundaries: no business rule in a handler (HARD-STOP 4); no persistence entity or repository; no
broker SDK type. Allowed edges come only from the registry entry.
- A handler that calls a write use case is `@SystemCaller(reason = ...)` and constructs the
`@SystemInvoked` use case itself; the use case is never a bean (manual 09 「소비」 step 4,
`ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`, `SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`).
- Tests: focused auto-configuration and inbox behavior tests; `./gradlew :adapter:inbound:messaging:check`.
The real Kafka + PostgreSQL redelivery lane is `messagingInboxRedeliveryIntegrationTest`
(`:integrationCheck`).
+24 -1
View File
@@ -31,6 +31,10 @@ Kafka ─▶ platform consumer (starter-kafka)
만든다. platform은 애플리케이션의 datasource·트랜잭션을 스스로 고르지 않는다는 기존 설계를 그대로 둔다.
- 애플리케이션의 handler(`MessageHandler<T>` 구현)는 이 leaf에 둔다. 컨트롤러가 HTTP 요청을 use case
호출로 바꾸듯 delivery를 use case 호출 하나로 바꾸는 inbound adapter다. 업무 규칙은 use case에 둔다.
- 쓰기 use case를 부르는 handler는 `@SystemCaller(reason = ...)`이고, `@SystemInvoked` use case를 생성자에서
`new`로 만들어 혼자 든다. use case는 bean이 아니다. 소비 스레드에는 인증이 없어 `@RequiresPermission`
use case는 매번 거부되기 때문이다. 작업 순서는 `docs/manual/09-outbox-events.md` 「소비」 4단계, 규칙은
07장 「시스템이 부르는 쓰기」(리뷰 2026-11-03 RR-01-12, 결정 9.1).
## 추가할 한 줄
@@ -85,7 +89,8 @@ app:
destination: order-events-dlq
```
handler 예시는 `MessagingInboxAutoConfigurationTest#exampleHandler`다.
handler 예시: 쓰기 use case를 부르는 모양은 `SystemInvokedConsumePathTest`의 `OrderCreatedHandler`, 실제 Kafka +
PostgreSQL에서 같은 모양은 `InboxRedeliveryIntegrationTest`의 `ProjectionHandler`다.
## 고른 방법과 버린 대안
@@ -96,6 +101,19 @@ handler 예시는 `MessagingInboxAutoConfigurationTest#exampleHandler`다.
(HARD-STOP 4).
- 버림: `adapter:outbound:messaging`(발행 bridge)에 소비까지 넣기 — 발행 bridge는
`messaging-core-api`만 보는 anti-corruption 경계이고, 소비는 inbound 방향이다.
- 고름(RR-01-12): handler가 `@SystemCaller`를 달고 `@SystemInvoked` use case를 직접 `new`로 만든다. 사용자
요청이 들어오는 전송(web·GraphQL·gRPC·WebSocket)만 그 use case에 닿지 못하고, 표시는 ArchUnit이 검사한다
(`SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`: messaging·scheduler inbound 패키지에만, 사용자 전송
타입에 의존하지 않음). 기동 가드는 바꾸지 않는다: `@SystemInvoked` bean은 예외 없이 실패다.
- 버림: use case를 bean으로 두고 가드에 "handler만 주입받으면 허용" 예외 — 누가 주입받는지는 기동 때
확정되지 않는다(`ObjectProvider`, `getBean`, 나중에 추가된 bean). 예외 조건이 곧 우회 경로가 된다.
- 버림: handler는 `CommandUseCase` 인터페이스만 받고 조립 모듈이 `new`로 넣기 — 소비자마다 composition
모듈이 필요하거나 app-bootstrap에 업무 조립이 들어간다(위 HARD-STOP 4). 조립 클래스도 결국 그 use case
클래스에 의존한다.
- 버림: ArchUnit 대상에서 messaging 패키지를 통째로 빼기 — 클래스에 표시가 없어 의도가 안 보이고, 그
패키지의 아무 클래스(HTTP endpoint 포함)나 닿는다.
- 버림: 사용자 전송 패키지만 나열해 금지 — 나중에 새 전송이 생기면 조용히 열린다. 규칙은 "닿아도 되는
쪽"을 적는다.
- 버림: application-core에 소비 포트를 새로 만들어 platform `MessageHandler`로 감싸는 범용 bridge —
payload 타입 매핑과 결과 매핑 규칙을 먼저 정해야 해서 이번 범위보다 크다. 지금은 handler가 직접
use case를 부른다.
@@ -104,12 +122,17 @@ handler 예시는 `MessagingInboxAutoConfigurationTest#exampleHandler`다.
- 단위: `MessagingInboxAutoConfigurationTest` — 조립 조건, inbox 마이그레이션 stream 조립 스위치, runner의
커밋·롤백, in-memory inbox로 중복 1회. decode 목록은 starter `MessagingConsumeConfigurationTest`.
- 단위: `SystemInvokedConsumePathTest` — 이 leaf의 inbox와 `composition:service-runtime`의 권한 가드를 함께
띄워, `@SystemCaller` handler가 만든 `@SystemInvoked` use case로 기동하고 같은 delivery 두 번에 쓰기가
한 번인지, use case를 bean으로 두면 기동이 실패하는지 본다.
- 실제 Kafka + PostgreSQL: `InboxRedeliveryIntegrationTest`(lane `messagingInboxRedeliveryIntegrationTest`).
Kafka capability, outbox relay, persistence-jpa, 이 leaf를 auto-configuration으로 띄운다. 앱 relay가
PostgreSQL outbox 행을 Kafka로 발행하고, 소비자가 inbox 예약과 업무 쓰기를 한 JPA 트랜잭션에서 한다.
- offset을 0으로 되감고 다시 띄워 같은 레코드를 다시 읽혀도 handler 호출 1회, 업무 행 1개, inbox 행 1개.
- handler가 업무 쓰기 뒤 예외를 던지면 예약과 쓰기가 함께 롤백되고, platform 재시도에서 다시 처리돼
handler 호출 2회, 업무 행 1개, inbox 행 1개.
- handler는 4단계 모양(`@SystemCaller` + 직접 만든 `@SystemInvoked` use case)이고, `composition:service-runtime`이
classpath에 있어 서비스와 같은 권한 가드 아래에서 기동한다.
- 소비 leaf가 기동하면 inbox 마이그레이션만 `flyway_messaging_inbox_history`에 적용되고 platform outbox
표는 생기지 않는다.
- 테스트는 payload 타입을 등록하지 않고 inbox 표도 만들지 않는다 — 서비스가 받는 그대로다.
+6 -1
View File
@@ -46,6 +46,12 @@ dependencies {
implementation 'org.springframework:spring-tx'
testImplementation 'org.springframework.boot:spring-boot-starter-test'
// The consume path a service runs (review 2026-11-03 RR-01-12): the permission guard every
// service takes from composition:service-runtime, the typed startup failure it raises, and the
// transaction port's fake. Test edges are outside the registry gate.
testImplementation project(':composition:service-runtime')
testImplementation project(':adapter:outbound:support')
testImplementation testFixtures(project(':application-core'))
}
testing {
@@ -73,7 +79,6 @@ dependencies {
integrationTestImplementation project(':adapter:outbound:persistence-jpa')
integrationTestImplementation project(':application-core')
integrationTestImplementation testFixtures(project(':application-core'))
integrationTestImplementation project(':shared-contract')
integrationTestImplementation project(':messaging:messaging-core-api')
integrationTestImplementation project(':messaging:messaging-spring-boot-starter')
integrationTestImplementation 'org.springframework:spring-jdbc'
+41 -5
View File
@@ -1,6 +1,7 @@
# This is a Gradle generated file for dependency locking.
# Manual edits can break the build and are not advised.
# This file is expected to be part of source control.
aopalliance:aopalliance:1.0=integrationTestRuntimeClasspath,testRuntimeClasspath
at.yawk.lz4:lz4-java:1.10.1=integrationTestRuntimeClasspath
biz.aQute.bnd:biz.aQute.bnd.annotation:7.1.0=integrationTestCompileClasspath,testCompileClasspath
ch.qos.logback:logback-classic:1.5.38=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
@@ -14,6 +15,7 @@ com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,integrationTest
com.github.docker-java:docker-java-api:3.7.1=integrationTestCompileClasspath,integrationTestRuntimeClasspath
com.github.docker-java:docker-java-transport-zerodep:3.7.1=integrationTestCompileClasspath,integrationTestRuntimeClasspath
com.github.docker-java:docker-java-transport:3.7.1=integrationTestCompileClasspath,integrationTestRuntimeClasspath
com.github.f4b6a3:uuid-creator:6.1.1=integrationTestRuntimeClasspath,testRuntimeClasspath
com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor
com.github.luben:zstd-jni:1.5.6-10=integrationTestRuntimeClasspath
com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs
@@ -53,9 +55,28 @@ commons-logging:commons-logging:1.3.6=compileClasspath,integrationTestCompileCla
info.picocli:picocli:4.7.7=checkstyle
io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor
io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,integrationTestAnnotationProcessor,testAnnotationProcessor
io.micrometer:context-propagation:1.2.1=integrationTestRuntimeClasspath,testRuntimeClasspath
io.micrometer:micrometer-commons:1.16.7=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.micrometer:micrometer-core:1.16.7=integrationTestCompileClasspath,integrationTestRuntimeClasspath
io.micrometer:micrometer-core:1.16.7=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testRuntimeClasspath
io.micrometer:micrometer-jakarta9:1.16.7=integrationTestRuntimeClasspath,testRuntimeClasspath
io.micrometer:micrometer-observation:1.16.7=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.micrometer:micrometer-tracing-bridge-otel:1.6.7=integrationTestRuntimeClasspath,testRuntimeClasspath
io.micrometer:micrometer-tracing:1.6.7=integrationTestRuntimeClasspath,testRuntimeClasspath
io.opentelemetry.semconv:opentelemetry-semconv:1.37.0=integrationTestRuntimeClasspath,testRuntimeClasspath
io.opentelemetry:opentelemetry-api:1.55.0=integrationTestRuntimeClasspath,testRuntimeClasspath
io.opentelemetry:opentelemetry-common:1.55.0=integrationTestRuntimeClasspath,testRuntimeClasspath
io.opentelemetry:opentelemetry-context:1.55.0=integrationTestRuntimeClasspath,testRuntimeClasspath
io.opentelemetry:opentelemetry-exporter-common:1.55.0=integrationTestRuntimeClasspath,testRuntimeClasspath
io.opentelemetry:opentelemetry-exporter-otlp-common:1.55.0=integrationTestRuntimeClasspath,testRuntimeClasspath
io.opentelemetry:opentelemetry-exporter-otlp:1.55.0=integrationTestRuntimeClasspath,testRuntimeClasspath
io.opentelemetry:opentelemetry-exporter-sender-jdk:1.55.0=integrationTestRuntimeClasspath,testRuntimeClasspath
io.opentelemetry:opentelemetry-extension-trace-propagators:1.55.0=integrationTestRuntimeClasspath,testRuntimeClasspath
io.opentelemetry:opentelemetry-sdk-common:1.55.0=integrationTestRuntimeClasspath,testRuntimeClasspath
io.opentelemetry:opentelemetry-sdk-extension-autoconfigure-spi:1.55.0=integrationTestRuntimeClasspath,testRuntimeClasspath
io.opentelemetry:opentelemetry-sdk-logs:1.55.0=integrationTestRuntimeClasspath,testRuntimeClasspath
io.opentelemetry:opentelemetry-sdk-metrics:1.55.0=integrationTestRuntimeClasspath,testRuntimeClasspath
io.opentelemetry:opentelemetry-sdk-trace:1.55.0=integrationTestRuntimeClasspath,testRuntimeClasspath
io.opentelemetry:opentelemetry-sdk:1.55.0=integrationTestRuntimeClasspath,testRuntimeClasspath
io.projectreactor:reactor-core:3.8.7=integrationTestRuntimeClasspath
jakarta.activation:jakarta.activation-api:2.1.4=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
jakarta.annotation:jakarta.annotation-api:3.0.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
@@ -68,7 +89,7 @@ jaxen:jaxen:2.0.6=spotbugs
net.bytebuddy:byte-buddy-agent:1.17.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
net.bytebuddy:byte-buddy:1.17.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
net.java.dev.jna:jna:5.18.1=integrationTestCompileClasspath,integrationTestRuntimeClasspath
net.logstash.logback:logstash-logback-encoder:8.0=integrationTestRuntimeClasspath
net.logstash.logback:logstash-logback-encoder:8.0=integrationTestRuntimeClasspath,testRuntimeClasspath
net.minidev:accessors-smart:2.6.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
net.minidev:json-smart:2.6.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs
@@ -109,7 +130,7 @@ org.glassfish.jaxb:jaxb-core:4.0.9=integrationTestRuntimeClasspath
org.glassfish.jaxb:jaxb-runtime:4.0.9=integrationTestRuntimeClasspath
org.glassfish.jaxb:txw2:4.0.9=integrationTestRuntimeClasspath
org.hamcrest:hamcrest:3.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.hdrhistogram:HdrHistogram:2.2.2=integrationTestRuntimeClasspath
org.hdrhistogram:HdrHistogram:2.2.2=integrationTestRuntimeClasspath,testRuntimeClasspath
org.hibernate.models:hibernate-models:1.0.1=integrationTestRuntimeClasspath
org.hibernate.orm:hibernate-core:7.2.24.Final=integrationTestRuntimeClasspath
org.javassist:javassist:3.28.0-GA=checkstyle
@@ -125,7 +146,7 @@ org.junit.platform:junit-platform-engine:6.0.3=integrationTestRuntimeClasspath,t
org.junit.platform:junit-platform-launcher:6.0.3=integrationTestRuntimeClasspath,testRuntimeClasspath
org.junit:junit-bom:6.0.3=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.junit:junit-bom:6.1.0=spotbugs
org.latencyutils:LatencyUtils:2.0.3=integrationTestRuntimeClasspath
org.latencyutils:LatencyUtils:2.0.3=integrationTestRuntimeClasspath,testRuntimeClasspath
org.mockito:mockito-core:5.20.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath,mockitoAgent,testCompileClasspath,testRuntimeClasspath
org.mockito:mockito-junit-jupiter:5.20.0=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.objenesis:objenesis:3.3=integrationTestRuntimeClasspath,testRuntimeClasspath
@@ -150,21 +171,30 @@ org.slf4j:jul-to-slf4j:2.0.18=integrationTestCompileClasspath,integrationTestRun
org.slf4j:slf4j-api:2.0.18=integrationTestCompileClasspath,integrationTestRuntimeClasspath,spotbugs,spotbugsSlf4j,testCompileClasspath,testRuntimeClasspath
org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.18=checkstyle
org.springframework.boot:spring-boot-actuator:4.0.8=integrationTestRuntimeClasspath
org.springframework.boot:spring-boot-actuator-autoconfigure:4.0.8=integrationTestRuntimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-actuator:4.0.8=integrationTestRuntimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-autoconfigure:4.0.8=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-configuration-processor:4.0.8=annotationProcessor
org.springframework.boot:spring-boot-data-commons:4.0.8=integrationTestRuntimeClasspath
org.springframework.boot:spring-boot-data-jpa:4.0.8=integrationTestRuntimeClasspath
org.springframework.boot:spring-boot-flyway:4.0.8=integrationTestRuntimeClasspath
org.springframework.boot:spring-boot-health:4.0.8=integrationTestRuntimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-hibernate:4.0.8=integrationTestRuntimeClasspath
org.springframework.boot:spring-boot-http-converter:4.0.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-jackson:4.0.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-jdbc:4.0.8=integrationTestRuntimeClasspath
org.springframework.boot:spring-boot-jpa:4.0.8=integrationTestRuntimeClasspath
org.springframework.boot:spring-boot-micrometer-metrics:4.0.8=integrationTestRuntimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-micrometer-observation:4.0.8=integrationTestRuntimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-micrometer-tracing-opentelemetry:4.0.8=integrationTestRuntimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-micrometer-tracing:4.0.8=integrationTestRuntimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-opentelemetry:4.0.8=integrationTestRuntimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-persistence:4.0.8=integrationTestRuntimeClasspath
org.springframework.boot:spring-boot-resttestclient:4.0.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-security:4.0.8=integrationTestRuntimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-servlet:4.0.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-sql:4.0.8=integrationTestRuntimeClasspath
org.springframework.boot:spring-boot-starter-actuator:4.0.8=integrationTestRuntimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-data-jpa:4.0.8=integrationTestRuntimeClasspath
org.springframework.boot:spring-boot-starter-flyway:4.0.8=integrationTestRuntimeClasspath
org.springframework.boot:spring-boot-starter-jackson-test:4.0.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
@@ -172,6 +202,8 @@ org.springframework.boot:spring-boot-starter-jackson:4.0.8=integrationTestCompil
org.springframework.boot:spring-boot-starter-jdbc:4.0.8=integrationTestRuntimeClasspath
org.springframework.boot:spring-boot-starter-json:4.0.8=integrationTestRuntimeClasspath
org.springframework.boot:spring-boot-starter-logging:4.0.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-micrometer-metrics:4.0.8=integrationTestRuntimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-security:4.0.8=integrationTestRuntimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-test:4.0.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-tomcat-runtime:4.0.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-tomcat:4.0.8=integrationTestCompileClasspath,integrationTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
@@ -190,6 +222,10 @@ org.springframework.data:spring-data-commons:4.0.7=integrationTestRuntimeClasspa
org.springframework.data:spring-data-jpa:4.0.7=integrationTestRuntimeClasspath
org.springframework.integration:spring-integration-core:7.0.6=integrationTestRuntimeClasspath
org.springframework.integration:spring-integration-jdbc:7.0.6=integrationTestRuntimeClasspath
org.springframework.security:spring-security-config:7.0.7=integrationTestRuntimeClasspath,testRuntimeClasspath
org.springframework.security:spring-security-core:7.0.7=integrationTestRuntimeClasspath,testRuntimeClasspath
org.springframework.security:spring-security-crypto:7.0.7=integrationTestRuntimeClasspath,testRuntimeClasspath
org.springframework.security:spring-security-web:7.0.7=integrationTestRuntimeClasspath,testRuntimeClasspath
org.springframework:spring-aop:7.0.9=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-aspects:7.0.9=integrationTestRuntimeClasspath
org.springframework:spring-beans:7.0.9=compileClasspath,integrationTestCompileClasspath,integrationTestRuntimeClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
@@ -3,9 +3,15 @@ package dev.caskeleton.adapter.inbound.messaging;
import static org.assertj.core.api.Assertions.assertThat;
import static org.awaitility.Awaitility.await;
import dev.caskeleton.application.capability.Idempotency;
import dev.caskeleton.application.capability.RepositoryAccess;
import dev.caskeleton.application.capability.UseCaseCapability;
import dev.caskeleton.application.messaging.event.ValidatedIntegrationEvent;
import dev.caskeleton.application.outbox.OutboxAppendPort;
import dev.caskeleton.application.outbox.testkit.OutboxEvents;
import dev.caskeleton.application.security.SystemCaller;
import dev.caskeleton.application.security.SystemInvoked;
import dev.caskeleton.application.transaction.TransactionMode;
import dev.caskeleton.application.transaction.TransactionPort;
import dev.caskeleton.messaging.api.MessageId;
import dev.caskeleton.messaging.api.MessageType;
@@ -14,8 +20,6 @@ import dev.caskeleton.messaging.api.delivery.MessageDelivery;
import dev.caskeleton.messaging.api.delivery.MessageHandler;
import dev.caskeleton.messaging.api.destination.DestinationName;
import dev.caskeleton.messaging.api.destination.MessageDestination;
import dev.caskeleton.shared.concurrency.DomainContextPropagator;
import dev.caskeleton.shared.concurrency.ThreadLocalDomainContextPropagator;
import java.time.Clock;
import java.time.Duration;
import java.time.Instant;
@@ -60,8 +64,11 @@ import org.testcontainers.postgresql.PostgreSQLContainer;
* from the PostgreSQL outbox and publishes it through the platform bridge; the platform consumer
* decodes it and, because the destination declares {@code INBOX_TRANSACTIONAL}, runs the handler
* inside the inbox this leaf assembles — the platform's JDBC inbox over the application datasource
* and a runner over the application's (JPA) transaction manager. The handler writes its effect the
* way a use case does, through the application's {@code TransactionPort}.
* and a runner over the application's (JPA) transaction manager. The handler is the shape manual 09
* 「소비」 step 4 teaches (review 2026-11-03 RR-01-12): a {@code @SystemCaller} that constructs the
* {@code @SystemInvoked} write use case it calls, which writes through the application's {@code
* TransactionPort}. {@code composition:service-runtime} is on the classpath as it is in a service,
* so its permission guard looks at this context and lets it start: the use case is not a bean.
*
* <p>What only this lane can show is that those parts share one transaction for real: a JDBC inbox
* that took a connection of its own, or a runner over a different transaction manager, passes every
@@ -387,7 +394,15 @@ class InboxRedeliveryIntegrationTest {
}
}
/** A use case's write, in the application's transaction (joined, never opened beside it). */
/**
* A write only the consumer calls, in the application's transaction (joined, never opened beside
* it). No permission: the consumer thread has no {@code Authentication}.
*/
@SystemInvoked(reason = "the lane's consumer calls it for each delivery")
@UseCaseCapability(
transactionMode = TransactionMode.WRITE,
idempotency = Idempotency.NOT_IDEMPOTENT,
repositoryAccess = RepositoryAccess.WRITE_REPOSITORY)
static final class RecordProjection {
private final TransactionPort transactions;
private final JdbcTemplate jdbc;
@@ -407,14 +422,18 @@ class InboxRedeliveryIntegrationTest {
}
}
/** The shape of an application handler: one delivery, one use case call. */
/**
* The shape of an application handler: one delivery, one use case call. It constructs its use
* case from the ports its bean method receives, so the use case is never a bean.
*/
@SystemCaller(reason = "the platform consumer calls it for each lane delivery")
static final class ProjectionHandler implements MessageHandler<LaneEvent> {
private final Handled handled;
private final RecordProjection useCase;
ProjectionHandler(Handled handled, RecordProjection useCase) {
ProjectionHandler(Handled handled, TransactionPort transactions, JdbcTemplate jdbc) {
this.handled = handled;
this.useCase = useCase;
this.useCase = new RecordProjection(transactions, jdbc);
}
@Override
@@ -445,14 +464,7 @@ class InboxRedeliveryIntegrationTest {
@Bean
ProjectionHandler projectionHandler(
Handled handled, TransactionPort transactions, DataSource dataSource) {
return new ProjectionHandler(
handled, new RecordProjection(transactions, new JdbcTemplate(dataSource)));
}
/** What composition:service-runtime gives a service; the JPA audit context reads it. */
@Bean
DomainContextPropagator domainContextPropagator() {
return new ThreadLocalDomainContextPropagator();
return new ProjectionHandler(handled, transactions, new JdbcTemplate(dataSource));
}
@Bean
@@ -0,0 +1,286 @@
package dev.caskeleton.adapter.inbound.messaging;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.outbound.support.startup.StartupFailureException;
import dev.caskeleton.application.capability.Idempotency;
import dev.caskeleton.application.capability.RepositoryAccess;
import dev.caskeleton.application.capability.UseCaseCapability;
import dev.caskeleton.application.security.SystemCaller;
import dev.caskeleton.application.security.SystemInvoked;
import dev.caskeleton.application.transaction.TransactionMode;
import dev.caskeleton.application.transaction.TransactionPort;
import dev.caskeleton.application.transaction.testkit.DirectTransactionPort;
import dev.caskeleton.composition.runtime.authorization.PermissionEnforcementConfig;
import dev.caskeleton.messaging.api.ContentType;
import dev.caskeleton.messaging.api.MessageEnvelope;
import dev.caskeleton.messaging.api.MessageId;
import dev.caskeleton.messaging.api.MessageType;
import dev.caskeleton.messaging.api.ProducerId;
import dev.caskeleton.messaging.api.SchemaVersion;
import dev.caskeleton.messaging.api.TraceContext;
import dev.caskeleton.messaging.api.delivery.DeliveryContext;
import dev.caskeleton.messaging.api.delivery.DeliveryMetadata;
import dev.caskeleton.messaging.api.delivery.HandleResult;
import dev.caskeleton.messaging.api.delivery.MessageDelivery;
import dev.caskeleton.messaging.api.delivery.MessageHandler;
import dev.caskeleton.messaging.api.destination.DestinationName;
import dev.caskeleton.messaging.api.destination.MessageDestination;
import dev.caskeleton.messaging.api.header.MessageHeaders;
import dev.caskeleton.messaging.inbox.IdempotentConsumer;
import dev.caskeleton.messaging.inbox.InboxMessageHandler;
import dev.caskeleton.messaging.reliability.InboxRepository;
import java.time.Instant;
import java.util.ArrayList;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Optional;
import java.util.Set;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionStage;
import javax.sql.DataSource;
import org.junit.jupiter.api.Test;
import org.mockito.Mockito;
import org.springframework.boot.autoconfigure.AutoConfigurations;
import org.springframework.boot.test.context.runner.ApplicationContextRunner;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.transaction.PlatformTransactionManager;
import org.springframework.transaction.TransactionDefinition;
import org.springframework.transaction.support.AbstractPlatformTransactionManager;
import org.springframework.transaction.support.DefaultTransactionStatus;
/**
* The consume path manual 09 「소비」 step 4 teaches, assembled the way a service assembles it: this
* leaf's inbox, the permission guard every service runs ({@code composition:service-runtime}), and
* a handler that calls a write use case only the system calls (review 2026-11-03 RR-01-12, decision
* 9.1).
*
* <p>The use case is {@code @SystemInvoked}: a consumer thread has no {@code Authentication}, so a
* permission gate would refuse every delivery. The handler is {@code @SystemCaller} and constructs
* the use case from the ports its bean method receives; the use case is never a bean, which is the
* one condition under which the guard lets a system-invoked use case into a running service. The
* architecture rules that check the marks run over production code in {@code
* :app-bootstrap:architectureTest}; this test checks that the same shape starts and runs.
*/
class SystemInvokedConsumePathTest {
private static final Instant NOW = Instant.parse("2026-11-04T09:00:00Z");
private static final DestinationName ORDERS = new DestinationName("order-events");
private final ApplicationContextRunner runner =
new ApplicationContextRunner()
.withConfiguration(
AutoConfigurations.of(
MessagingInboxAutoConfiguration.class, PermissionEnforcementConfig.class))
.withBean(DataSource.class, () -> Mockito.mock(DataSource.class))
.withBean(PlatformTransactionManager.class, NoTransactions::new)
.withBean(TransactionPort.class, DirectTransactionPort::new)
.withBean(InMemoryOrderProjections.class, InMemoryOrderProjections::new)
.withPropertyValues("app.runtime.migration-on-startup=false");
@Test
void aHandlerThatConstructsItsSystemInvokedUseCaseStartsUnderThePermissionGuard() {
// when
runner
.withUserConfiguration(OrderConsumerConfig.class)
.run(
context -> {
// then
assertThat(context)
.hasNotFailed()
.hasSingleBean(OrderCreatedHandler.class)
.doesNotHaveBean(ProjectOrderUseCase.class);
});
}
@Test
void aDeliveryReachesTheSystemInvokedUseCaseOnceThroughTheInbox() {
runner
.withUserConfiguration(OrderConsumerConfig.class)
.run(
context -> {
// given: the platform's inbox around the assembled handler, over this leaf's runner
IdempotentConsumer inbox =
new IdempotentConsumer(
new InMemoryInbox(),
context.getBean(IdempotentConsumer.TransactionRunner.class));
MessageHandler<String> consumer =
new InboxMessageHandler<>(
context.getBean(OrderCreatedHandler.class),
inbox,
"order-projection",
() -> NOW);
MessageDelivery<String> delivery = delivery("o-1");
consumer.handle(delivery).toCompletableFuture().join();
// when
consumer.handle(delivery).toCompletableFuture().join();
// then
assertThat(context.getBean(InMemoryOrderProjections.class).recorded)
.containsExactly("o-1");
});
}
/** The way the guard refuses: the use case as a bean, which any transport could inject. */
@Test
void registeringTheSystemInvokedUseCaseAsABeanFailsStartup() {
// when
runner
.withUserConfiguration(UseCaseAsABeanConfig.class)
.run(
context -> {
// then
assertThat(context.getStartupFailure())
.isInstanceOf(StartupFailureException.class)
.hasMessageContaining("never registered as a bean")
.hasMessageContaining(ProjectOrderUseCase.class.getName());
});
}
private static MessageDelivery<String> delivery(String orderId) {
return new MessageDelivery<>(
new MessageEnvelope<>(
MessageId.newId(),
new MessageType("order.created"),
new SchemaVersion(1),
NOW,
Optional.empty(),
new ProducerId("orders"),
Optional.empty(),
Optional.empty(),
ContentType.JSON,
Optional.empty(),
Optional.empty(),
Optional.empty(),
TraceContext.none(),
MessageHeaders.empty(),
orderId),
new DeliveryMetadata(
ORDERS, 1, false, Optional.empty(), Optional.empty(), Optional.empty(), NOW),
new DeliveryContext(NOW.plusSeconds(30), false, "order-projection"));
}
/** The application's write port for the projection; this test owns it, so its fake is here. */
interface OrderProjectionPort {
void record(String orderId);
}
static final class InMemoryOrderProjections implements OrderProjectionPort {
private final List<String> recorded = new ArrayList<>();
@Override
public void record(String orderId) {
recorded.add(orderId);
}
}
/** A write only the consumer calls: no permission, because its caller has no Authentication. */
@SystemInvoked(reason = "the order-events consumer calls it for each delivery")
@UseCaseCapability(
transactionMode = TransactionMode.WRITE,
idempotency = Idempotency.IDEMPOTENT,
repositoryAccess = RepositoryAccess.WRITE_REPOSITORY)
static final class ProjectOrderUseCase {
private final TransactionPort tx;
private final OrderProjectionPort projections;
ProjectOrderUseCase(TransactionPort tx, OrderProjectionPort projections) {
this.tx = tx;
this.projections = projections;
}
void project(String orderId) {
tx.inWrite(
() -> {
projections.record(orderId);
return null;
});
}
}
/** Manual 09 step 4: one delivery, one use case call; the handler owns its use case. */
@SystemCaller(reason = "the platform consumer calls it for each order-events delivery")
static final class OrderCreatedHandler implements MessageHandler<String> {
private final ProjectOrderUseCase useCase;
OrderCreatedHandler(TransactionPort tx, OrderProjectionPort projections) {
this.useCase = new ProjectOrderUseCase(tx, projections);
}
@Override
public MessageDestination<String> destination() {
return new MessageDestination<>(ORDERS, new MessageType("order.created"), String.class);
}
@Override
public CompletionStage<HandleResult> handle(MessageDelivery<String> delivery) {
useCase.project(delivery.message().payload());
return CompletableFuture.completedFuture(HandleResult.success());
}
}
@Configuration(proxyBeanMethods = false)
static class OrderConsumerConfig {
@Bean
OrderCreatedHandler orderCreatedHandler(
TransactionPort tx, InMemoryOrderProjections projections) {
return new OrderCreatedHandler(tx, projections);
}
}
@Configuration(proxyBeanMethods = false)
static class UseCaseAsABeanConfig {
@Bean
ProjectOrderUseCase projectOrderUseCase(
TransactionPort tx, InMemoryOrderProjections projections) {
return new ProjectOrderUseCase(tx, projections);
}
@Bean
OrderCreatedHandler orderCreatedHandler(
TransactionPort tx, InMemoryOrderProjections projections) {
return new OrderCreatedHandler(tx, projections);
}
}
/** The inbox runner's transaction manager; the mocked datasource has nothing to open. */
private static final class NoTransactions extends AbstractPlatformTransactionManager {
private static final long serialVersionUID = 1L;
@Override
protected Object doGetTransaction() {
return new Object();
}
@Override
protected void doBegin(Object transaction, TransactionDefinition definition) {}
@Override
protected void doCommit(DefaultTransactionStatus status) {}
@Override
protected void doRollback(DefaultTransactionStatus status) {}
}
private static final class InMemoryInbox implements InboxRepository {
private final Set<String> reserved = new LinkedHashSet<>();
@Override
public boolean reserve(MessageId messageId, String consumerId, Instant now) {
return reserved.add(messageId.value() + "|" + consumerId);
}
@Override
public boolean isProcessed(MessageId messageId, String consumerId) {
return reserved.contains(messageId.value() + "|" + consumerId);
}
@Override
public int purgeProcessedBefore(Instant processedBefore, int limit) {
return 0;
}
}
}
@@ -28,6 +28,14 @@ import tools.jackson.databind.ObjectMapper;
* status is classified by the same table the exception handler uses, and the body is the failure
* envelope, with nothing from the request in it.
*
* <p>The status sent is the code's registered status. A status in {@link HttpStatusErrorCodes}
* keeps its value; any other folds into the code of its class — {@code BAD_PARAMETER} 400 for a
* 4xx, {@code INTERNAL_ERROR} 500 for a 5xx — so the {@code error.code} a client branches on never
* disagrees with the status beside it (review 2026-11-03 RR-01-13). Rejected: keeping the
* dispatched status beside the folded code, which is what Boot did but would send {@code
* BAD_PARAMETER} with a 409 the registry does not give it. A filter that needs another status
* writes that status's code with {@link EnvelopeResponseWriter} or adds a row to the table.
*
* <p>Written straight to the response by {@link EnvelopeResponseWriter}, like the other refusals
* made outside a converter. An error dispatch has no handler of its own to negotiate for, and a
* browser's {@code Accept: text/html} would otherwise turn the error into a 406 about the error.
@@ -0,0 +1,58 @@
package dev.caskeleton.adapter.inbound.web.error;
import static org.assertj.core.api.Assertions.assertThat;
import jakarta.servlet.RequestDispatcher;
import java.util.List;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.CsvSource;
import org.springframework.mock.web.MockHttpServletRequest;
import org.springframework.mock.web.MockHttpServletResponse;
import tools.jackson.databind.ObjectMapper;
/**
* Which status and code the container's error dispatch is answered with (review 2026-11-03
* RR-01-13). A status in {@link HttpStatusErrorCodes} keeps its value; any other folds to the code
* of its class and that code's registered status, so the {@code error.code} a client branches on
* never disagrees with {@code docs/registries/error-codes.yaml}.
*/
class EnvelopeErrorControllerTest {
private final ObjectMapper mapper = new ObjectMapper();
private final EnvelopeErrorController controller = new EnvelopeErrorController(mapper);
@DisplayName("오류 디스패치 status: 표에 있으면 그대로, 없으면 4xx는 400·5xx는 500으로 접힌다")
@ParameterizedTest(name = "{0} → {1} {2}")
@CsvSource({
"401, 401, UNAUTHENTICATED",
"404, 404, ROUTE_NOT_FOUND",
"429, 429, RATE_LIMIT_EXCEEDED",
"409, 400, BAD_PARAMETER",
"422, 400, BAD_PARAMETER",
"500, 500, INTERNAL_ERROR",
"502, 500, INTERNAL_ERROR",
"504, 500, INTERNAL_ERROR"
})
void anErrorDispatchKeepsATabledStatusAndFoldsAnyOtherIntoItsClassCode(
int dispatched, int answered, String code) throws Exception {
// given
MockHttpServletRequest request = new MockHttpServletRequest("GET", "/error");
request.setAttribute(RequestDispatcher.ERROR_STATUS_CODE, dispatched);
MockHttpServletResponse response = new MockHttpServletResponse();
// when
controller.error(request, response);
// then
assertThat(
List.of(
response.getStatus(),
mapper
.readTree(response.getContentAsString())
.path("error")
.path("code")
.asString()))
.containsExactly(answered, code);
}
}
+16 -3
View File
@@ -215,7 +215,7 @@ typed SDK's — tagged `lane=<name>` (`RedisLaneMetrics`; rows in `docs/registri
| --- | --- | --- |
| `redis.lane.acquire.wait.seconds` (`outcome` = `admitted`/`refused`) | timer, histogram | how long a borrow queued for a connection; a growing admitted p99 comes before refusals |
| `redis.lane.acquire.refused.total` (`reason` = `saturated`/`closing`/`interrupted`/`connect_failed`) | counter | a borrow that got no connection, nothing sent; `saturated` on `SCRIPT` is the starvation this lane exists to prevent |
| `redis.lane.connections.opened.total` | counter | new connections; after warm-up every one is a reconnect |
| `redis.lane.connections.opened.total` | counter | new connections; after warm-up a pooled lane opens one only to replace a discarded one. A routed lease (a Cluster `TRANSACTION` borrow) is opened for each borrow and closed after it without being counted as discarded, so on that lane a steady rate is normal use, not reconnects |
| `redis.lane.connections.discarded.total` (`reason` = `invalidated`/`broken`) | counter | connections closed instead of pooled — `invalidated` is a timed-out or failed call (the lease is not reused), and is what the reconnects replace |
| `redis.lane.connections.active`, `redis.lane.connections.pending` | gauge | connections lent out now; borrows waiting now |
@@ -283,6 +283,18 @@ A lost renewal reply is recognised by what the renewal recorded — the revision
the lease it asked for: the same lease is `ALREADY_RENEWED_SAME_OPERATION` with the current handle,
a different lease is `OPERATION_CONFLICT`.
A lease that runs out is taken over only from a claim that never started or an attempt marked
retryable. A record still `EXECUTING` when its lease ran out has an unknown effect: the claim
program marks it `ABANDONED` and answers `RECOVERY_REQUIRED`, and the late holder can no longer
complete it. 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 record over and
run the work a second time).
The record key lives for the processing lease plus the replay TTL (`afterLease`, kept on the record),
and a renewal stretches it to the new lease plus that margin. With the replay TTL alone, a replay
TTL shorter than the lease dropped the key of a running operation and the next claim ran it again,
and one equal to the lease left no record to answer `RECOVERY_REQUIRED` from (RR-03-11).
Redis `TIME` determines lease deadlines. A failure after a command may have executed is returned
as an indeterminate outcome; the adapter does not convert an ambiguous write into a clean
unavailable result that would invite duplicate execution.
@@ -334,8 +346,9 @@ Useful focused checks:
./gradlew architectureCheck
```
`redisContainerContractTest` runs the cache-region and lease port contracts (the ones the in-memory
fakes pass) and the live semantic-port tests against a Redis it starts itself, under the standalone
`redisContainerContractTest` runs the cache-region, lease and idempotency-store port contracts (the
ones the in-memory fakes pass; the idempotency contract's timed cases run only here, on the server's
own clock) and the live semantic-port tests against a Redis it starts itself, under the standalone
topology's ACL file. It is in `integrationCheck` (integration-main.yml's `integration-check` job), and
only there: listing it in `mainCheck` as well ran it twice on every push to main. The image is
`config/testing/container-images.properties` `redis`.
@@ -30,19 +30,36 @@ public final class IdempotencyScripts {
* <p>The fingerprint is compared before anything else. Two different requests that hash to the
* same idempotency scope are a client error, and treating the second as a replay of the first
* would return somebody else's response.
*
* <p>A lease that ran out is taken over only when nothing can have happened under it: a claim
* that never started, or an attempt its holder marked retryable. A record that was {@code
* EXECUTING} has an unknown effect, so it is abandoned and answered {@code RECOVERY_REQUIRED} —
* running it again is the duplicate this store exists to prevent, and it is what a client
* resending after a result-unknown 503 was promised would not happen (re-review 2026-11-04
* RR-01-11). The PostgreSQL store answers the same; {@code IdempotencyStoreContract} holds both
* to it.
*
* <p>The key lives for the lease plus the replay TTL ({@code afterLease}), not for the replay TTL
* alone. With the replay TTL alone, a replay TTL shorter than the lease dropped the key while the
* holder still ran and the next claim acquired it fresh — a second run (RR-03-11); and a replay
* TTL equal to the lease dropped it with the lease, leaving no record to answer "recovery
* required" from. {@code afterLease} is kept on the record so {@link #RENEW} can keep the same
* margin behind a lease it extends.
*/
private static final String CLAIM =
"""
local state = redis.call('HGET', KEYS[1], 'state')
local t = redis.call('TIME')
local nowMillis = (tonumber(t[1]) * 1000) + math.floor(tonumber(t[2]) / 1000)
local leaseMillis = tonumber(ARGV[6])
local afterLease = tonumber(ARGV[7])
if state == false then
redis.call('HSET', KEYS[1],
'state', 'CLAIMED', 'owner', ARGV[1], 'attempt', 1, 'rev', 1,
'op', ARGV[2], 'fp', ARGV[3], 'codec', ARGV[4], 'policy', ARGV[5],
'leaseUntil', nowMillis + tonumber(ARGV[6]))
redis.call('PEXPIRE', KEYS[1], ARGV[7])
return {'ACQUIRED', 1, 1, ARGV[1], '', tostring(nowMillis + tonumber(ARGV[6]))}
'leaseUntil', nowMillis + leaseMillis, 'afterLease', afterLease)
redis.call('PEXPIRE', KEYS[1], leaseMillis + afterLease)
return {'ACQUIRED', 1, 1, ARGV[1], '', tostring(nowMillis + leaseMillis)}
end
local fingerprint = redis.call('HGET', KEYS[1], 'fp')
if fingerprint ~= ARGV[3] then
@@ -68,15 +85,23 @@ public final class IdempotencyScripts {
redis.call('HGET', KEYS[1], 'leaseUntil')}
end
local leaseUntil = tonumber(redis.call('HGET', KEYS[1], 'leaseUntil'))
if state == 'FAILED_RETRYABLE' or (leaseUntil ~= nil and leaseUntil <= nowMillis) then
-- The previous holder's processing lease expired, or they marked the attempt retryable.
-- Taking over bumps the attempt so the new holder can tell it is not the first.
local leaseOver = leaseUntil ~= nil and leaseUntil <= nowMillis
if state == 'EXECUTING' and leaseOver then
-- The holder started and its lease ran out: whether the work took effect is unknown.
-- Abandon it, so the late holder cannot complete over the verdict, and keep the key's TTL:
-- the record stays as evidence for its remaining afterLease window.
redis.call('HSET', KEYS[1], 'state', 'ABANDONED', 'rev', rev + 1)
return {'RECOVERY_REQUIRED', attempt, rev + 1, owner, '', ''}
end
if state == 'FAILED_RETRYABLE' or (state == 'CLAIMED' and leaseOver) then
-- Nothing ran under the previous holder: they never started, or they marked the attempt
-- retryable. Taking over bumps the attempt so the new holder can tell it is not the first.
redis.call('HSET', KEYS[1],
'state', 'CLAIMED', 'owner', ARGV[1], 'attempt', attempt + 1, 'rev', rev + 1,
'op', ARGV[2], 'leaseUntil', nowMillis + tonumber(ARGV[6]))
redis.call('PEXPIRE', KEYS[1], ARGV[7])
'op', ARGV[2], 'leaseUntil', nowMillis + leaseMillis, 'afterLease', afterLease)
redis.call('PEXPIRE', KEYS[1], leaseMillis + afterLease)
return {'TAKEN_OVER', attempt + 1, rev + 1, ARGV[1], '',
tostring(nowMillis + tonumber(ARGV[6]))}
tostring(nowMillis + leaseMillis)}
end
return {'IN_PROGRESS', attempt, rev, owner, '', tostring(leaseUntil - nowMillis)}
""";
@@ -142,11 +167,13 @@ public final class IdempotencyScripts {
* the same renewal; with a different lease it is a different request, because confirming it would
* leave the caller believing it holds the record for a lease the record does not carry.
*
* <p>The key's own TTL is stretched to cover the new lease. Claim sets it to the replay TTL,
* which may be shorter than a lease renewed past it; the key then expired while the holder was
* still executing, and the next request got a fresh claim and ran the side effect again (review
* 2026-11-03 RR-04-08). The TTL is only ever lengthened here — completion sets the replay TTL
* again.
* <p>The key's own TTL is stretched to cover the new lease and the {@code afterLease} margin the
* claim recorded behind it, so a renewed lease ends with the same evidence window as the first.
* Without it a lease renewed past the key's TTL expired the key while the holder was still
* executing, and the next request got a fresh claim and ran the side effect again (review
* 2026-11-03 RR-04-08, re-review 2026-11-04 RR-03-11). A record claimed before {@code afterLease}
* existed has none and keeps only the lease. The TTL is only ever lengthened here — completion
* sets the replay TTL again.
*/
private static final String RENEW =
"""
@@ -183,9 +210,11 @@ public final class IdempotencyScripts {
redis.call('HSET', KEYS[1],
'leaseUntil', nowMillis + tonumber(ARGV[4]), 'rev', rev + 1,
'renewedFromRev', ARGV[2], 'renewedLease', ARGV[4])
local keep = tonumber(ARGV[4])
+ tonumber(redis.call('HGET', KEYS[1], 'afterLease') or '0')
local ttl = redis.call('PTTL', KEYS[1])
if ttl >= 0 and ttl < tonumber(ARGV[4]) then
redis.call('PEXPIRE', KEYS[1], ARGV[4])
if ttl >= 0 and ttl < keep then
redis.call('PEXPIRE', KEYS[1], keep)
end
return {'APPLIED', attempt, rev + 1, owner, '', ''}
""";
@@ -130,6 +130,7 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort
request.responseCodecId(),
Integer.toString(request.policyRevision()),
Long.toString(request.processingLeaseTtl().toMillis()),
// How long the record outlives its lease: the key lives for both.
Long.toString(request.replayTtl().toMillis())))),
now),
IdempotencyClaimOutcome.Unavailable::new,
@@ -353,8 +353,8 @@ class RedisIdempotencyStoreAdapterTest {
}
@Test
@DisplayName("lease를 넘겨받은 뒤 이전 owner는 renew할 수 없다")
void aTakenOverOwnerCannotRenew() {
@DisplayName("lease가 지나 다른 요청이 회복 필요로 판정한 실행은 이전 owner가 renew할 수 없다")
void anOwnerWhoseExpiredExecutionWasAbandonedCannotRenew() {
// given
IdempotencyOwner executing = executing();
gateway.advance(Duration.ofSeconds(60));
@@ -368,7 +368,26 @@ class RedisIdempotencyStoreAdapterTest {
}
@Test
@DisplayName("an expired processing lease can be taken over, and the attempt increments")
@DisplayName("lease가 지난 실행 중 기록은 넘겨주지 않고 회복 필요로 답한다")
void anExpiredExecutionIsAnsweredRecoveryRequiredNotTakenOver() {
// given
IdempotencyOwner executing = executing();
gateway.advance(Duration.ofSeconds(60));
// when
IdempotencyClaimOutcome next = store.claim(claim(store.newClaimAttempt(OTHER_OPERATION)));
// then
// TAKEN_OVER would run work whose effect is unknown a second time. The live contract proves
// the program; this proves the fixture's copy of it agrees.
assertThat(next)
.isInstanceOfSatisfying(
IdempotencyClaimOutcome.RecoveryRequired.class,
recovery -> assertThat(recovery.currentAttempt()).isEqualTo(executing.attempt()));
}
@Test
@DisplayName("an expired claim that never started can be taken over, and the attempt increments")
void anExpiredLeaseIsTakenOver() {
store.claim(claim(store.newClaimAttempt(OPERATION)));
@@ -28,7 +28,10 @@ class RedisServerTimeScriptContractTest {
String transition = script(IdempotencyScripts.class, "TRANSITION");
assertThat(claim).contains("redis.call('TIME')");
assertThat(claim).contains("leaseUntil', nowMillis + tonumber(ARGV[6])");
assertThat(claim).contains("local leaseMillis = tonumber(ARGV[6])");
assertThat(claim).contains("leaseUntil', nowMillis + leaseMillis");
// The key outlives the lease by the replay TTL (re-review 2026-11-04 RR-03-11).
assertThat(claim).contains("redis.call('PEXPIRE', KEYS[1], leaseMillis + afterLease)");
assertThat(transition).contains("redis.call('TIME')");
assertThat(transition).contains("leaseUntil', nowMillis + tonumber(ARGV[7])");
}
+4 -3
View File
@@ -43,9 +43,10 @@ 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
inside the same deadline; after hand-over each body gap is bounded by `read-idle` and nothing else,
on both transports — the JDK transport arms its own per-read timer for this, because the JDK client
has no socket read timeout. A body that fails after hand-over throws the same stable exceptions as
a buffered call (`HttpResponseTimeoutException` for a stalled body, `HttpResponseTruncatedException`
for a cut one).
has no socket read timeout. A body that fails after hand-over throws `HttpBodyReadException`, an
`IOException` as `InputStream.read` promises, whose `failure()` is the same stable exception a
buffered call throws (`HttpResponseTimeoutException` for a stalled body,
`HttpResponseTruncatedException` for a cut one).
- **Evidence.** Each attempt reports `NOT_SENT`, `SENT_NO_RESPONSE`, `RESPONSE_RECEIVED`, or
`PARTIAL_RESPONSE`. `NOT_SENT` is only claimed when a stage failure proves it.
- **Retry.** Never from the HTTP method alone. Idempotency, body replayability, evidence, deadline,
@@ -0,0 +1,42 @@
package dev.caskeleton.adapter.outbound.httpclient.api.error;
import java.io.IOException;
import java.util.Objects;
/**
* A streamed response body failed after it was handed over; {@link #failure()} says how.
*
* <p>An {@link IOException}, because {@code InputStream.read} promises one: a caller that reads the
* body with {@code catch (IOException)} — to delete a partial file, to retry — still sees the
* failure. The classified failure the gateway would have thrown for a buffered call ({@link
* HttpResponseTimeoutException} for a stalled body, {@link HttpResponseTruncatedException} for a
* cut one, stage {@code RESPONSE_BODY}, evidence {@code PARTIAL_RESPONSE}) is the cause and {@link
* #failure()}, for a retry policy or a log that branches on category.
*
* <p>Re-review 2026-11-04 RR-03-14: the body threw the unchecked {@link HttpClientException}
* itself, which a {@code catch (IOException)} let through. Rejected: keeping the unchecked type and
* only documenting it — the {@code InputStream} contract is what every reader of a stream relies
* on, and a document does not reach a library that reads the stream for its caller.
*/
public final class HttpBodyReadException extends IOException {
private static final long serialVersionUID = 1L;
/**
* Wraps a classified body failure.
*
* @param failure the classified failure; its message is the caller-safe phrase
*/
public HttpBodyReadException(HttpClientException failure) {
super(Objects.requireNonNull(failure, "classified body failure").getMessage(), failure);
}
/**
* The classified failure: category, metadata and evidence.
*
* @return the failure this exception carries
*/
public HttpClientException failure() {
return (HttpClientException) getCause();
}
}
@@ -17,6 +17,16 @@ public interface BlockingStreamingResponse extends AutoCloseable {
Map<String, List<String>> headers();
/**
* The body, bounded after hand-over by {@code read-idle} per wait.
*
* <p>A read that fails throws {@link
* dev.caskeleton.adapter.outbound.httpclient.api.error.HttpBodyReadException} — an {@code
* IOException} whose {@code failure()} is the classified {@code HttpResponseTimeoutException}
* (stalled) or {@code HttpResponseTruncatedException} (cut).
*
* @return the body stream; closing the response closes it
*/
InputStream body();
@Override
@@ -9,6 +9,7 @@ import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.Collections;
import java.util.Objects;
import java.util.Set;
import java.util.TreeSet;
@@ -19,6 +20,7 @@ import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpMethod;
import org.springframework.http.client.AbstractBufferingClientHttpRequest;
import org.springframework.http.client.ClientHttpResponse;
import org.springframework.util.StringUtils;
/**
* A JDK request for a streaming download, whose timeouts end at the response headers (review
@@ -40,6 +42,9 @@ import org.springframework.http.client.ClientHttpResponse;
*/
final class JdkStreamingClientHttpRequest extends AbstractBufferingClientHttpRequest {
/** The JDK property that lets a deployment send some restricted headers after all. */
private static final String ALLOW_RESTRICTED_HEADERS = "jdk.httpclient.allowRestrictedHeaders";
/** Headers the JDK client refuses to set, as Spring's own JDK request lists them. */
private static final Set<String> RESTRICTED_HEADERS = restrictedHeaders();
@@ -120,9 +125,21 @@ final class JdkStreamingClientHttpRequest extends AbstractBufferingClientHttpReq
}
}
private static Set<String> restrictedHeaders() {
/**
* Spring's {@code JdkClientHttpRequest.disallowedHeaders()}, which is private, step for step: the
* five names, less any the {@code jdk.httpclient.allowRestrictedHeaders} property allows. A fixed
* copy ignored the property, so a deployment that set it sent {@code Host} on ordinary calls and
* dropped it on streamed ones (re-review 2026-11-04 RR-03-15). {@code
* JdkStreamingRestrictedHeadersTest} compares the two lists for several property values, so a
* Spring change shows up as a failing test rather than as two lists that quietly differ.
*/
static Set<String> restrictedHeaders() {
Set<String> restricted = new TreeSet<>(String.CASE_INSENSITIVE_ORDER);
restricted.addAll(Set.of("connection", "content-length", "expect", "host", "upgrade"));
return restricted;
String allowed = System.getProperty(ALLOW_RESTRICTED_HEADERS);
if (allowed != null) {
restricted.removeAll(StringUtils.commaDelimitedListToSet(allowed));
}
return Collections.unmodifiableSet(restricted);
}
}
@@ -15,24 +15,48 @@ import java.util.concurrent.atomic.AtomicBoolean;
* RR-04-03).
*
* <p>The JDK client has no socket read timeout, so a streamed body that stopped arriving held the
* caller's thread and the connection forever. Each read arms a timer on the JDK's shared delay
* scheduler; when it fires the stream is closed, which wakes the blocked read, and the read reports
* a {@link SocketTimeoutException} — the same exception Apache's socket timeout raises, so one
* classifier reading names both. A read that returns first disarms its timer.
* caller's thread and the connection forever. A read that has waited {@code read-idle} for the
* server closes the stream, which wakes it, and it reports a {@link SocketTimeoutException} — the
* same exception Apache's socket timeout raises, so one classifier reading names both. Only the
* time a read spends waiting counts: time the caller spends between reads is not the server's.
*
* <p>One watchdog per stream, not a timer per read (re-review 2026-11-04 RR-03-13). A read only
* records when it started; the watchdog wakes once per {@code read-idle}, closes the stream if the
* read in progress has waited that long, and otherwise sleeps until that read's deadline. Arming a
* timer on every read put a task on the JVM's single delay scheduler and took it off again —
* measured at about 3 µs a read, and a JVM-wide ceiling near 0.5–0.75 million reads a second shared
* with every other {@code CompletableFuture} timeout in the process. The watchdog costs a clock
* read and two volatile writes per read, and one scheduled task per {@code read-idle} while reads
* keep coming. Rejected: a transport-owned {@code ScheduledExecutorService} with a timer per read —
* it moves the queue off the shared scheduler but keeps a queue insertion and removal on every
* read.
*
* <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
* over a steady body timed out as one long wait (re-review 2026-11-04 RR-03-12).
*/
final class ReadIdleInputStream extends FilterInputStream {
/** The largest scratch buffer {@link #skip} reads into, as {@code InputStream.skip} uses. */
private static final int SKIP_BUFFER_BYTES = 2048;
/** {@link #readStartedAt} while no read is waiting. */
private static final long NOT_READING = Long.MIN_VALUE;
@FunctionalInterface
private interface Read {
long run() throws IOException;
}
private final Duration readIdle;
private final long readIdleNanos;
private final AtomicBoolean watchdogArmed = new AtomicBoolean();
private final AtomicBoolean idled = new AtomicBoolean();
private volatile long readStartedAt = NOT_READING;
private volatile boolean closed;
ReadIdleInputStream(InputStream delegate, Duration readIdle) {
super(Objects.requireNonNull(delegate, "body stream"));
this.readIdle = Objects.requireNonNull(readIdle, "read idle timeout");
this.readIdleNanos = Objects.requireNonNull(readIdle, "read idle timeout").toNanos();
}
@Override
@@ -47,14 +71,33 @@ final class ReadIdleInputStream extends FilterInputStream {
@Override
public long skip(long count) throws IOException {
return guarded(() -> super.skip(count));
if (count <= 0) {
return 0;
}
byte[] scratch = new byte[(int) Math.min(SKIP_BUFFER_BYTES, count)];
long remaining = count;
while (remaining > 0) {
int read = read(scratch, 0, (int) Math.min(scratch.length, remaining));
if (read < 0) {
break;
}
remaining -= read;
}
return count - remaining;
}
@Override
public void close() throws IOException {
closed = true;
super.close();
}
private long guarded(Read read) throws IOException {
requireNotIdled();
CompletableFuture<Void> timer = new CompletableFuture<>();
CompletableFuture<Void> expiry =
timer.completeOnTimeout(null, readIdle.toNanos(), TimeUnit.NANOSECONDS).thenRun(this::idle);
readStartedAt = System.nanoTime();
if (!watchdogArmed.get() && watchdogArmed.compareAndSet(false, true)) {
watchFrom(readStartedAt);
}
try {
long result = read.run();
requireNotIdled();
@@ -63,9 +106,37 @@ final class ReadIdleInputStream extends FilterInputStream {
requireNotIdled();
throw failure;
} finally {
// Completing first skips the idle action and lets the scheduler drop the pending task.
timer.cancel(false);
expiry.cancel(false);
readStartedAt = NOT_READING;
}
}
/** Wakes the watchdog when a read that started at {@code started} reaches read-idle. */
private void watchFrom(long started) {
long left = Math.max(0, readIdleNanos - (System.nanoTime() - started));
CompletableFuture.delayedExecutor(left, TimeUnit.NANOSECONDS).execute(this::watch);
}
private void watch() {
if (closed || idled.get()) {
return;
}
long started = readStartedAt;
if (started != NOT_READING) {
// The second read of readStartedAt: a read that ended at its deadline and was followed at
// once by another must not have the new one closed under it.
if (System.nanoTime() - started >= readIdleNanos && readStartedAt == started) {
idle();
} else {
watchFrom(started);
}
return;
}
watchdogArmed.set(false);
// A read that started after the check above saw the watchdog armed and left it alone; look
// again, or that read would wait unwatched.
started = readStartedAt;
if (started != NOT_READING && watchdogArmed.compareAndSet(false, true)) {
watchFrom(started);
}
}
@@ -79,7 +150,7 @@ final class ReadIdleInputStream extends FilterInputStream {
}
/**
* After the timer fired, whatever the read returned — data, end of stream or "closed" — is not
* After the watchdog fired, whatever the read returned — data, end of stream or "closed" — is not
* the rest of the body.
*/
private void requireNotIdled() throws SocketTimeoutException {
@@ -23,10 +23,14 @@ import java.util.function.Supplier;
* circuit error: the upstream never saw the request, and counting our own back-pressure as upstream
* failure would open the breaker on a healthy dependency.
*
* <p>An attempt its caller abandoned is not recorded either, for the same reason: an attempt that a
* caller's own deadline ended while the upstream was still answering within the profile's limits is
* the caller running out of time, not the upstream failing (review 2026-11-03 RR-04-01). Its
* permission is given back instead.
* <p>An attempt its caller abandoned is not recorded either: an attempt that failed after a
* caller's own deadline — set earlier than the profile's, and passed by the time it failed — is
* taken as the caller running out of time, not the upstream failing (review 2026-11-03 RR-04-01).
* Its permission is given back instead. The check does not ask whether the upstream was still
* answering within the profile's limits, and that is a blind spot: when every caller's budget is
* shorter than the stage timeouts, a hung upstream ends each attempt at the caller's deadline first
* and is never recorded, so the circuit never opens (re-review 2026-11-04 RR-03-16,
* docs/httpclient/configuration-reference.md "Two deadlines").
*/
public final class AttemptResiliencePipeline {
@@ -1,5 +1,6 @@
package dev.caskeleton.adapter.outbound.httpclient.restclient;
import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpBodyReadException;
import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpClientException;
import java.io.FilterInputStream;
import java.io.IOException;
@@ -14,7 +15,9 @@ import java.util.function.Function;
* <p>A streamed body is read after the gateway has returned, so the gateway's own failure mapping
* never sees it. Without this a read-idle timeout or a cut connection reached the caller as the
* engine's bare {@code IOException} — no category, no evidence, nothing a retry policy or a log
* could branch on. Closing is the caller's own act and is passed through unclassified.
* could branch on. Each failure is thrown as {@link HttpBodyReadException}: still an {@code
* IOException}, as {@code InputStream} promises, carrying the classified failure (re-review
* 2026-11-04 RR-03-14). Closing is the caller's own act and is passed through unclassified.
*/
final class ClassifiedBodyInputStream extends FilterInputStream {
@@ -31,7 +34,7 @@ final class ClassifiedBodyInputStream extends FilterInputStream {
try {
return super.read();
} catch (IOException failure) {
throw classifier.apply(failure);
throw new HttpBodyReadException(classifier.apply(failure));
}
}
@@ -40,7 +43,7 @@ final class ClassifiedBodyInputStream extends FilterInputStream {
try {
return super.read(buffer, offset, length);
} catch (IOException failure) {
throw classifier.apply(failure);
throw new HttpBodyReadException(classifier.apply(failure));
}
}
@@ -49,7 +52,7 @@ final class ClassifiedBodyInputStream extends FilterInputStream {
try {
return super.skip(count);
} catch (IOException failure) {
throw classifier.apply(failure);
throw new HttpBodyReadException(classifier.apply(failure));
}
}
@@ -58,7 +61,7 @@ final class ClassifiedBodyInputStream extends FilterInputStream {
try {
return super.available();
} catch (IOException failure) {
throw classifier.apply(failure);
throw new HttpBodyReadException(classifier.apply(failure));
}
}
}
@@ -0,0 +1,69 @@
package dev.caskeleton.adapter.outbound.httpclient.jdk;
import static org.assertj.core.api.Assertions.assertThat;
import java.lang.reflect.Method;
import java.util.List;
import java.util.Locale;
import java.util.Set;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.parallel.ResourceLock;
import org.junit.jupiter.api.parallel.Resources;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.ValueSource;
/**
* The streaming JDK request drops the same headers Spring's own JDK request drops, so a profile
* sends the same headers whether the call streams or not (re-review 2026-11-04 RR-03-15).
*
* <p>Spring computes its list from the {@code jdk.httpclient.allowRestrictedHeaders} system
* property; the streaming request used to keep a fixed copy that ignored it, and a deployment that
* set the property sent {@code Host} on ordinary calls and silently dropped it on streamed ones.
* Spring's list is private, so it is read reflectively: if Spring renames it, this test fails and
* says so, rather than the two lists drifting apart unseen.
*/
@ResourceLock(Resources.SYSTEM_PROPERTIES)
class JdkStreamingRestrictedHeadersTest {
private static final String ALLOW_PROPERTY = "jdk.httpclient.allowRestrictedHeaders";
@ParameterizedTest
@ValueSource(
strings = {"", "host", "Host,upgrade", "connection,content-length,expect,host,upgrade"})
@DisplayName("jdk.httpclient.allowRestrictedHeaders 값이 무엇이든 스트리밍 요청이 버리는 헤더는 Spring JDK 요청과 같다")
void theStreamingRequestDropsWhatSpringsJdkRequestDrops(String allowed) throws Exception {
// given
String previous = System.getProperty(ALLOW_PROPERTY);
if (allowed.isEmpty()) {
System.clearProperty(ALLOW_PROPERTY);
} else {
System.setProperty(ALLOW_PROPERTY, allowed);
}
try {
// when
Set<String> streaming = JdkStreamingClientHttpRequest.restrictedHeaders();
// then
assertThat(lowerCased(streaming)).isEqualTo(lowerCased(springsDisallowedHeaders()));
} finally {
if (previous == null) {
System.clearProperty(ALLOW_PROPERTY);
} else {
System.setProperty(ALLOW_PROPERTY, previous);
}
}
}
@SuppressWarnings("unchecked")
private static Set<String> springsDisallowedHeaders() throws Exception {
Method disallowed =
Class.forName("org.springframework.http.client.JdkClientHttpRequest")
.getDeclaredMethod("disallowedHeaders");
disallowed.setAccessible(true);
return (Set<String>) disallowed.invoke(null);
}
private static List<String> lowerCased(Set<String> names) {
return names.stream().map(name -> name.toLowerCase(Locale.ROOT)).sorted().toList();
}
}
@@ -0,0 +1,152 @@
package dev.caskeleton.adapter.outbound.httpclient.jdk;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.catchThrowable;
import java.io.IOException;
import java.io.InputStream;
import java.net.SocketTimeoutException;
import java.time.Duration;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.TimeUnit;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
/**
* 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,
* RR-03-13).
*/
class ReadIdleInputStreamTest {
private static final Duration READ_IDLE = Duration.ofMillis(300);
private static final Duration GAP = Duration.ofMillis(20);
@Test
@DisplayName("데이터가 read-idle보다 짧은 간격으로 오면 read-idle보다 오래 걸리는 skip도 끝까지 건너뛴다")
void aSkipLongerThanReadIdleOverASteadyBodySucceeds() throws IOException {
// given
// 40 bytes at 20 ms apart: 800 ms in all, every gap well inside the 300 ms bound.
try (InputStream body = new ReadIdleInputStream(new DrippingStream(40, GAP), READ_IDLE)) {
// when
long skipped = body.skip(40);
// then
assertThat(skipped).isEqualTo(40);
}
}
@Test
@DisplayName("데이터가 read-idle보다 짧은 간격으로 오면 본문 전체가 read-idle보다 오래 걸려도 끝까지 읽힌다")
void aSteadyBodyLongerThanReadIdleIsReadToTheEnd() throws IOException {
// given
try (InputStream body = new ReadIdleInputStream(new DrippingStream(40, GAP), READ_IDLE)) {
// when
byte[] read = body.readAllBytes();
// then
assertThat(read).hasSize(40);
}
}
@Test
@DisplayName("한 read가 read-idle보다 오래 서버를 기다리면 SocketTimeoutException으로 끝난다")
void aReadThatWaitsLongerThanReadIdleTimesOut() {
// given
long started = System.nanoTime();
InputStream body = new ReadIdleInputStream(new StalledStream(), READ_IDLE);
// when
Throwable failure = catchThrowable(body::read);
// then
Duration waited = Duration.ofNanos(System.nanoTime() - started);
assertThat(failure).isInstanceOf(SocketTimeoutException.class);
assertThat(waited).isGreaterThanOrEqualTo(READ_IDLE).isLessThan(READ_IDLE.multipliedBy(3));
}
@Test
@DisplayName("호출자가 read 사이에 오래 머문 시간은 read-idle로 세지 않는다")
void timeTheCallerSpendsBetweenReadsIsNotIdle() throws Exception {
// given
try (InputStream body = new ReadIdleInputStream(new DrippingStream(2, GAP), READ_IDLE)) {
int first = body.read();
TimeUnit.MILLISECONDS.sleep(READ_IDLE.multipliedBy(2).toMillis());
// when
int second = body.read();
// then
assertThat(new int[] {first, second}).containsExactly('x', 'x');
}
}
/** Gives one byte per read, each after {@code gap}. */
private static final class DrippingStream extends InputStream {
private final Duration gap;
private int remaining;
private DrippingStream(int bytes, Duration gap) {
this.remaining = bytes;
this.gap = gap;
}
@Override
public int read() throws IOException {
if (remaining == 0) {
return -1;
}
try {
TimeUnit.NANOSECONDS.sleep(gap.toNanos());
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
throw new IOException("interrupted", interrupted);
}
remaining--;
return 'x';
}
@Override
public int read(byte[] buffer, int offset, int length) throws IOException {
if (length == 0) {
return 0;
}
int value = read();
if (value < 0) {
return -1;
}
buffer[offset] = (byte) value;
return 1;
}
}
/** Never answers until closed, as a server that stopped sending does; closing wakes the read. */
private static final class StalledStream extends InputStream {
private final CountDownLatch closed = new CountDownLatch(1);
@Override
public int read() throws IOException {
try {
closed.await();
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
throw new IOException("interrupted", interrupted);
}
throw new IOException("closed");
}
@Override
public int read(byte[] buffer, int offset, int length) throws IOException {
return read();
}
@Override
public void close() {
closed.countDown();
}
}
}
@@ -4,6 +4,8 @@ import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.catchThrowable;
import dev.caskeleton.adapter.outbound.httpclient.api.OperationName;
import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpBodyReadException;
import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpClientException;
import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpResponseTimeoutException;
import dev.caskeleton.adapter.outbound.httpclient.api.operation.AttemptStage;
import dev.caskeleton.adapter.outbound.httpclient.api.operation.ExecutionEvidence;
@@ -71,7 +73,7 @@ class StreamingBodyLifetimeTest {
@EnumSource(
value = TransportType.class,
names = {"APACHE", "JDK"})
@DisplayName("본문 사이 공백이 read-idle을 넘으면 분류된 응답 시간 초과로 끝난다")
@DisplayName("본문 사이 공백이 read-idle을 넘으면 IOException인 본문 읽기 실패에 분류된 응답 시간 초과를 실어 끝난다")
void aBodyGapLongerThanReadIdleEndsWithAClassifiedTimeout(TransportType transport)
throws Exception {
try (MockHttpServer server = MockHttpServer.start();
@@ -93,9 +95,13 @@ class StreamingBodyLifetimeTest {
// then
Duration elapsed = Duration.ofNanos(System.nanoTime() - started);
assertThat(failure).isInstanceOf(HttpResponseTimeoutException.class);
// An IOException, as InputStream.read promises, so a caller's catch (IOException) still
// sees it; the classified failure rides on it (re-review 2026-11-04 RR-03-14).
assertThat(failure).isInstanceOf(HttpBodyReadException.class);
assertThat(elapsed).isLessThan(STALL_GAP);
HttpResponseTimeoutException timeout = (HttpResponseTimeoutException) failure;
HttpClientException classified = ((HttpBodyReadException) failure).failure();
assertThat(classified).isInstanceOf(HttpResponseTimeoutException.class);
HttpResponseTimeoutException timeout = (HttpResponseTimeoutException) classified;
assertThat(timeout.metadata().stage()).isEqualTo(AttemptStage.RESPONSE_BODY);
assertThat(timeout.metadata().evidence()).isEqualTo(ExecutionEvidence.PARTIAL_RESPONSE);
}
@@ -55,9 +55,8 @@ public final class SesEventNormalizer {
default -> event(NormalizedEventType.UNKNOWN, type, messageId, occurredAt);
});
// One SNS delivery carries one SES event, so the delivery's id is the event's. It is what makes
// a redelivery a duplicate in the ledger: the other identity, the event fingerprint, is keyed
// by
// the active HMAC key and changes when the key rotates (review 2026-11-03 RR-07-07).
// a redelivery a duplicate in the ledger: the other identity, the event fingerprint, uses the
// active HMAC key and changes when the key rotates (review 2026-11-03 RR-07-07).
return events.stream().map(event -> withEventId(event, providerEventId)).toList();
}
+4 -2
View File
@@ -105,8 +105,10 @@ testImplementation testFixtures(project(':adapter:outbound:objectstorage'))
### MinIO qualification lanes
`objectStorageMinioContractTest` and `objectStorageMinioFaultTest` (in `mainCheck`) run a real MinIO
and Toxiproxy. Their images are read from one file,
`objectStorageMinioContractTest` and `objectStorageMinioFaultTest` run a real MinIO and Toxiproxy.
They run in the root `integrationCheck` (main push and nightly) and in
`.github/workflows/object-storage-qualification.yml` on pull requests that touch object storage —
not in this leaf's `mainCheck`, which ran them a second time on every main push. Their images are read from one file,
`src/test/resources/object-storage/minio-provider-evidence.json`, whose `image` digest is the
release the `status`, `excludedProfiles` and `limitations` beside it were measured on.
`MinioQualificationImage` (in `src/test`, checked by the leaf's `test` without Docker) reads it.
@@ -0,0 +1,10 @@
{
"properties": [
{
"name": "app.object-storage.enabled",
"type": "java.lang.Boolean",
"description": "Whether the object-storage capability is on. It is on whenever this module is on the classpath; false turns it off and leaves only the explicit legacy seam. Read by @ConditionalOnProperty, which the configuration processor cannot see, so it is declared here for the environment contract (verifyEnvKeys) and the IDE.",
"defaultValue": true
}
]
}
@@ -38,7 +38,7 @@ packages.
| `startup` | package-private startup policy (`JpaStartupAutoConfiguration`): Flyway migration strategy, datasource env/product checks, OSIV/DDL/Hikari/TLS/H2 guards, the `jpaplatform` actuator view, the readiness `db` contribution. Moved here from app-bootstrap |
| `cache`, `envers`, `querydsl`, `security`, `observation` | opt-in library capabilities and the runtime-role verifier |
| `experimental` | multi-tenancy, RLS, schema/database tenancy, read replica — library code a deployment constructs itself; no flag turns it on |
| `testkit` (`src/testFixtures/java`) | ArchUnit rules, fixtures, query/plan assertions, PostgreSQL matrix, failure injection, Flyway validate gate and concurrent-index inspector |
| `testkit` (`src/testFixtures/java`) | ArchUnit rules, fixtures, query/plan assertions, PostgreSQL matrix, failure injection, Flyway validate gate, concurrent-index inspector and lock-wait inspector |
`springdata`, `hibernate` (`.batch`, `.bulk`, `.stateless`, statement inspector), `postgresql`
(`.error`, `.lock`, `.constraint`, `.json`, `.array`, `.range`, `.copy`), `api.query`, `envers`,
@@ -93,6 +93,9 @@ not grow by wiring accident.
- A caller that retries re-runs the whole use case in a new transaction and a new Persistence
Context.
- OSIV is false in every runtime profile; Flyway owns schema change and Hibernate only validates.
- A migration that locks a table already in use starts with `SET LOCAL lock_timeout = '5s';`
(`docs/jpa/migration-guide.md` "Bound the lock wait"). `MigrationLockWaitTest` refuses one
without it; its list of migrations released before the rule only ever shrinks.
- Metric tags, exception messages, and logs carry no SQL parameters, entity ids, tenant ids, or PII.
- Contracts run against real PostgreSQL. H2 never satisfies one.
+22 -5
View File
@@ -227,9 +227,14 @@ failure translation contract 다. 여기서는 SPI 구조와 fallback 근거만
- **PostgreSQL 전용**: data source 가 PostgreSQL 이 아니면 기동을 거부한다. `bootRunH2` 는
provider 를 `disabled` 나 `redis` 로 둔다.
- **응답 크기**: 완료 응답은 8 KiB 이하만 행에 inline 저장하고, 넘으면 거부한다.
- **만료**: store 가 완료·실패 때 `expires_at` 을 앞으로 옮기고, `IdempotencyReaper`
(`IdempotencyRecordJpaRepository` 사용, 기본 10분 간격 `reaper-interval`)가 지난 행을 지운다.
reaper 는 provider 가 `postgresql` 일 때만 돈다.
- **만료**: claim 은 `expires_at` 을 처리 lease 끝 + replay TTL 로 두고, renew 는 lease 를 늘린 만큼
`expires_at` 도 뒤로 민다. 완료·실패 때 다시 앞으로 옮긴다. `IdempotencyReaper`
(`IdempotencyRecordJpaRepository` 사용, 기본 10분 간격 `reaper-interval`)가 상태와 상관없이 지난 행을
지운다. 그래서 `expires_at` 이 lease 보다 먼저 오면 실행 중인 행이 지워지고 다음 claim 이 같은 작업을
다시 돌린다(재리뷰 2026-11-04 RR-03-11). 공유 계약의 PostgreSQL lane 은 시간을 흘린 뒤 이 reaper 를
실제로 돌려 이 경우를 본다. reaper 는 provider 가 `postgresql` 일 때만 돈다.
- **lease 가 지난 실행**: lease 가 지난 `EXECUTING` 행은 넘겨받지 않고 `ABANDONED` 로 바꿔
`RecoveryRequired` 로 답한다. Redis store 도 같다(`IdempotencyStoreContract`, RR-01-11).
## outbox — `JpaOutboxStore` 외
@@ -297,8 +302,11 @@ A가 FAILED로 바꾸면 다시 발행되고(중복 전달), A의 늦은 PUBLISH
owner는 비우고 token은 그대로 둔다(token은 증가만 한다). 1 row면 `APPLIED`, 0 row면 `STALE`.
`findById` + setter 경로와 `@Version`은 쓰지 않는다.
- **실패 원인 코드(`V22`)**: `markFailed`·`markDeferred`·`markDead`는 같은 조건부 UPDATE에서
`last_failure_code`를 쓴다(publisher가 붙인 코드, 없으면 결과·예외 타입 이름). entity 필드는 읽기
전용이라 append INSERT와 claim flush는 이 열을 건드리지 않는다. `longRetries(n, now)`는 미룬 claim이
`last_failure_code`를 쓴다(publisher가 붙인 코드, 없으면 결과·예외 타입 이름). append INSERT는 이 열을
쓰지 않는다. claim이 행을 DEAD로 옮길 때(`ATTEMPT_COUNTERS_INCONSISTENT`, `UNREADABLE_ROW`)는 claim의 row
lock 아래 entity flush로 그 이유를 쓴다 — 앞선 발행 실패의 코드가 남아 원인을 잘못 가리키지 않게(재리뷰 2차
RR-02-12). 이 DEAD는 relay 결과를 거치지 않아 `outbox.publisher.published.total{outcome=DEAD}`에 안 잡히므로
경보는 `outbox.pending.size{status=DEAD}`로도 건다. `longRetries(n, now)`는 미룬 claim이
n번 이상인 FAILED 행 수와 가장 오래된 행의 나이를 센다(`outbox.retry.long.*` 게이지). 상태 `PARKED`는
DDL이 없다 — claim이 PENDING·FAILED·IN_FLIGHT만 고르고, FIFO 게이트는 PUBLISHED 아닌 모든 행을 막는 앞
행으로 본다. claim이 시도 횟수가 어긋난 행(`deferred_attempt_count > attempt_count`)을 만나면 DEAD로
@@ -356,6 +364,9 @@ A가 FAILED로 바꾸면 다시 발행되고(중복 전달), A의 늦은 PUBLISH
`JpaOutboxStore.oldestUnpublishedAgeSecondsByEventType` 가 `HashMap` 을 쓰는 건 키가
enum 이 아니라 String(event-type 이름)이기 때문이다 — `countByStatus()` 는 키가
`OutboxEventStatus` enum 이라 `EnumMap` 을 쓴다(두 반환 타입이 의도적으로 다름).
`status` 에는 CHECK 가 없어 이 버전이 모르는 상태(뒤 버전이 쓴 상태, 손으로 친 값)가 있을 수 있다.
`countByStatus()` 는 그 상태만 빼고 세고 처음 한 번 WARN 으로 이름과 행 수를 말한다. 예전에는 그 이름 하나로
집계 전체가 실패해 PENDING 게이지까지 꺼졌다(재리뷰 2차 RR-02-11).
### `OutboxReaper`
PUBLISHED row 는 이미 전달된 terminal-success record 라 무한 보관할 필요가 없다. reaper 가
@@ -374,6 +385,12 @@ machine-readable SSOT다(개수는 registry가 소유한다). `selected` base ca
구분하며, 실제 PostgreSQL 테스트 통과만으로 immutable 운영 evidence가 필요한 R2를 주장하지
않는다.
이미 쓰이는 테이블을 잠그는 migration은 그 잠금 앞에 `SET LOCAL lock_timeout = '5s';`를 둔다. 상한이 없으면
그 테이블을 건드린 열린 트랜잭션 하나 뒤에서 끝없이 기다리고, 그동안 뒤에 온 읽기·쓰기가 모두 migration 뒤에 줄을
선다(V22, 재리뷰 2차 RR-02-09). `MigrationLockWaitTest`가 이 leaf DB에 도는 모든 tree를 검사하고,
`postgresqlMigrationLockWaitIntegrationTest` lane이 실제 PostgreSQL에서 상한 안에 실패하는지 본다
(`docs/jpa/migration-guide.md` "Bound the lock wait").
적용된 versioned migration은 수정하지 않는다. Flyway가 기동할 때마다 checksum을 검사하므로
바꾼 파일은 이미 그것을 적용한 모든 DB의 기동을 막는다. 변경은 새 버전으로 추가하고,
`src/test/resources/db/applied-migrations.sha256`에 한 줄을 더한다
@@ -176,6 +176,7 @@ def readinessLanes = [
postgresqlSecurityBaselineIntegrationTest : ['PostgreSqlSecurityBaselineIntegrationTest',
'runtimeRoleCannotCreateInApplicationSchemaOrTempAndUsesTrustedSearchPath'],
postgresqlMigrationIntegrationTest : ['PostgreSqlMigrationIntegrationTest'],
postgresqlMigrationLockWaitIntegrationTest : ['PostgreSqlMigrationLockWaitIntegrationTest'],
postgresqlIntLockMigrationCompatibilityIntegrationTest : ['PostgreSqlIntLockMigrationCompatibilityIntegrationTest'],
postgresqlTransactionIntegrationTest : ['PostgreSqlTransactionIntegrationTest'],
postgresqlDistributedLockIntegrationTest : ['PostgreSqlDistributedLockIntegrationTest'],
@@ -17,6 +17,14 @@ import org.springframework.jdbc.core.JdbcOperations;
* rows back rather than an exception. That matters: a unique-violation would abort the caller's
* transaction, and the loser has to be able to read the winner's row in the same transaction to
* find out what happened.
*
* <p>A claimed row expires ({@code expires_at}, which the reaper purges on whatever the row's
* state) at the end of its processing lease plus the replay TTL — {@link #recordLifetimeMillis}. It
* used to expire at the replay TTL alone: with a replay TTL shorter than the lease the reaper
* deleted the row of a running operation and the next claim inserted a fresh one and ran it again
* (re-review 2026-11-04 RR-03-11), and with the two equal the row went with its lease, leaving
* nothing to answer "recovery required" from (RR-01-11). The Redis store keeps its key for the same
* span; {@code IdempotencyStoreContract} holds both to it.
*/
final class IdempotencyClaimGateway {
@@ -122,7 +130,7 @@ final class IdempotencyClaimGateway {
request.scope().digest(),
request.scope().operationCode(),
request.requestFingerprint().hex(),
request.replayTtl().toMillis(),
recordLifetimeMillis(request),
request.scope().digest(),
request.scope().keyDigestVersion(),
request.scope().operationCode(),
@@ -151,12 +159,21 @@ final class IdempotencyClaimGateway {
request.processingLeaseTtl().toMillis(),
request.policyRevision(),
request.responseCodecId(),
request.replayTtl().toMillis(),
recordLifetimeMillis(request),
request.scope().digest(),
row.state().name(),
row.stateRevision());
}
/**
* How long a claimed row lives: its processing lease, and then the replay TTL as the window in
* which a resend still finds it — "in progress" during the lease, "recovery required" after an
* execution outlived it.
*/
static long recordLifetimeMillis(IdempotencyClaimRequest request) {
return request.processingLeaseTtl().plus(request.replayTtl()).toMillis();
}
/**
* Abandons an execution whose lease expired, repeating the whole owner tuple.
*
@@ -39,11 +39,22 @@ final class IdempotencyTransitionGateway {
and processing_lease_until > clock_timestamp()
""";
/**
* Extends the lease, and moves {@code expires_at} with it: the row keeps the time it had past its
* old lease (the replay TTL the claim gave it), now past the new one. The right-hand side reads
* the row as it was before this update. Without the move a lease renewed past {@code expires_at}
* let the reaper delete a running operation's row (re-review 2026-11-04 RR-03-11); a row claimed
* before the margin existed keeps at least its new lease.
*/
private static final String RENEW_SQL =
"""
update idempotency_record
set state_revision = state_revision + 1,
processing_lease_until = clock_timestamp() + (? * interval '1 millisecond'),
expires_at = greatest(
expires_at,
clock_timestamp() + (? * interval '1 millisecond')
+ greatest(expires_at - processing_lease_until, interval '0')),
last_transition_operation_id = ?,
last_transition_kind = 'RENEW',
last_transition_result_digest = ?,
@@ -151,6 +162,7 @@ final class IdempotencyTransitionGateway {
return jdbc.update(
RENEW_SQL,
processingLeaseTtl.toMillis(),
processingLeaseTtl.toMillis(),
operationId,
resultDigest,
owner.scope().digest(),
@@ -28,6 +28,8 @@ import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;
import java.util.Set;
import java.util.concurrent.ConcurrentHashMap;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.slf4j.spi.LoggingEventBuilder;
@@ -52,6 +54,9 @@ public class JpaOutboxStore
private final OutboxEventJpaRepository repository;
private final OutboxClaimRepository claimRepository;
/** Status names {@link #countByStatus} has met and does not know; each is reported once. */
private final Set<String> reportedUnknownStatuses = ConcurrentHashMap.newKeySet();
public JpaOutboxStore(
OutboxEventJpaRepository repository, OutboxClaimRepository claimRepository) {
this.repository = repository;
@@ -106,8 +111,11 @@ public class JpaOutboxStore
* <p>The increment is an {@code UPDATE}, which holds the counter row's lock until the caller
* commits: a second writer of the same aggregate waits, then increments the committed value, so
* the numbers follow commit order. It never goes below the aggregate's highest outbox row, so a
* row an instance still on the wall-clock scheme writes during a rolling deploy comes first. The
* counter outlives the reaper's deletes, so a number is never handed out twice.
* row an instance still on the wall-clock scheme writes during a rolling deploy comes first — as
* long as it writes under the same identity. A row written under an identity this version does
* not use (a tenant scope the deploy changed) is invisible here, and the next number can be
* smaller than it; such a deploy stops the old writers first (runbook outbox-dead-letter §8,
* RR-02-10). The counter outlives the reaper's deletes, so a number is never handed out twice.
*
* <p>An aggregate's first number is inserted instead, after the larger of its highest remaining
* row and the floor V21 recorded — the moment it ran, above every clock number already sent for
@@ -150,7 +158,9 @@ public class JpaOutboxStore
* <p>The WARN names the cause. A row whose deferred claims outnumber its claims is not damaged:
* it is what a manual re-drive that reset {@code attempt_count} and left {@code
* deferred_attempt_count} produces (re-review 2026-11-03 RR-05-01), and "cannot read" sent the
* operator looking for corruption instead of re-running the corrected runbook SQL.
* operator looking for corruption instead of re-running the corrected runbook SQL. The row says
* it too: the same code goes into {@code last_failure_code}, in place of the code of whatever
* publish failure came before, which no longer explains the row (re-review round 2, RR-02-12).
*/
@Override
public List<OutboxLease> claimBatch(
@@ -165,8 +175,7 @@ public class JpaOutboxStore
entity.setLeaseOwner(owner);
entity.setLeaseToken(entity.getLeaseToken() + 1);
if (entity.getDeferredAttemptCount() > entity.getAttemptCount()) {
deadLetterOnClaim(entity)
.addKeyValue("error.reason", "ATTEMPT_COUNTERS_INCONSISTENT")
deadLetterOnClaim(entity, "ATTEMPT_COUNTERS_INCONSISTENT")
.log(
"outbox claim moved a row to DEAD: deferred_attempt_count ({}) exceeds"
+ " attempt_count ({}); a manual re-drive that did not reset"
@@ -180,8 +189,7 @@ public class JpaOutboxStore
try {
event = toClaimedOutboxEvent(entity);
} catch (RuntimeException unreadable) {
deadLetterOnClaim(entity)
.addKeyValue("error.reason", "UNREADABLE_ROW")
deadLetterOnClaim(entity, "UNREADABLE_ROW")
.setCause(unreadable)
.log("outbox claim moved a row it cannot read as an event to DEAD");
continue;
@@ -191,12 +199,17 @@ public class JpaOutboxStore
return List.copyOf(leases);
}
/** Moves a claimed row it will not hand out to DEAD and starts the WARN that says why. */
private static LoggingEventBuilder deadLetterOnClaim(OutboxEventEntity entity) {
/**
* Moves a claimed row it will not hand out to DEAD under {@code reason}, written to the row's
* {@code last_failure_code} and the WARN it starts.
*/
private static LoggingEventBuilder deadLetterOnClaim(OutboxEventEntity entity, String reason) {
entity.setStatus(OutboxEventStatus.DEAD.name());
entity.setLeaseOwner(null);
entity.setLastFailureCode(reason);
return log.atWarn()
.addKeyValue("event_id", entity.getEventId())
.addKeyValue("error.reason", reason)
.addKeyValue("runbook_link", "runbook://outbox/dead-letter");
}
@@ -256,17 +269,45 @@ public class JpaOutboxStore
CallerTransaction.require("outbox " + operation);
}
/**
* The rows per status this version knows. A status it does not know is left out and named once in
* a WARN: {@code status} has no CHECK, so a version meets a status written after it — an instance
* still on the version before PARKED during a rollout, the version an operator rolled back to, a
* value typed by hand. Failing the whole count on that name took every {@code
* outbox.pending.size} gauge down with it, the PENDING backlog the alert reads included
* (re-review round 2, RR-02-11).
*/
@Override
public Map<OutboxEventStatus, Long> countByStatus() {
List<Object[]> rows = repository.countGroupedByStatus();
Map<OutboxEventStatus, Long> result = new EnumMap<>(OutboxEventStatus.class);
for (Object[] row : rows) {
OutboxEventStatus status = OutboxEventStatus.valueOf((String) row[0]);
result.put(status, (Long) row[1]);
String name = (String) row[0];
Long count = (Long) row[1];
Optional<OutboxEventStatus> status = knownStatus(name);
if (status.isPresent()) {
result.put(status.get(), count);
} else if (reportedUnknownStatuses.add(name)) {
log.atWarn()
.addKeyValue("outbox.status", name)
.addKeyValue("row_count", count)
.log(
"outbox_event holds rows in a status this version does not know; they are left out"
+ " of outbox.pending.size. A later version or a manual UPDATE wrote it");
}
}
return result;
}
private static Optional<OutboxEventStatus> knownStatus(String name) {
for (OutboxEventStatus status : OutboxEventStatus.values()) {
if (status.name().equals(name)) {
return Optional.of(status);
}
}
return Optional.empty();
}
@Override
public Map<String, Long> oldestUnpublishedAgeSecondsByEventType(Instant now) {
List<Object[]> rows = repository.findOldestUnpublishedOccurredAtByEventType();
@@ -43,7 +43,7 @@ public class OutboxEventEntity implements Persistable<String> {
@Column(name = "occurred_at", nullable = false, updatable = false)
private Instant occurredAt;
/** Lifecycle status string: PENDING | IN_FLIGHT | PUBLISHED | FAILED | DEAD. */
/** Lifecycle status string: PENDING | IN_FLIGHT | PUBLISHED | FAILED | DEAD | PARKED. */
@Column(name = "status", nullable = false, length = 16)
private String status;
@@ -57,19 +57,19 @@ public class OutboxEventEntity implements Persistable<String> {
@Column(name = "deferred_attempt_count", nullable = false)
private int deferredAttemptCount;
/** Dual-purpose per status (PENDING / IN_FLIGHT / FAILED) — see README "outbox". */
/**
* The code of the row's last failed completion (V22): the publisher's own name for the failure,
* or the outcome or exception type when it gave none.
* Why the row last failed (V22): the publisher's own name for the failure, or the outcome or
* exception type when it gave none, or the claim's reason for moving the row to DEAD.
*
* <p>Read-only to the entity: only the relay's failed completions write it, each in its one
* fenced UPDATE ({@code OutboxEventJpaRepository#failLease} and its siblings). The append's
* INSERT and the claim's flush leave it out, so they neither clear a code nor need the column on
* a database that has not run V22 yet.
* <p>The relay's failed completions write it in their one fenced UPDATE ({@code
* OutboxEventJpaRepository#failLease} and its siblings); the claim writes it through this entity
* when it moves a row it will not hand out to DEAD, under the claim's row lock (re-review round
* 2, RR-02-12). The append's INSERT leaves it out, so a new row has none.
*/
@Column(name = "last_failure_code", length = 120, insertable = false, updatable = false)
@Column(name = "last_failure_code", length = 120, insertable = false)
private String lastFailureCode;
/** Dual-purpose per status (PENDING / IN_FLIGHT / FAILED) — see README "outbox". */
@Column(name = "next_attempt_at", nullable = false)
private Instant nextAttemptAt;
@@ -395,4 +395,8 @@ public class OutboxEventEntity implements Persistable<String> {
public String getLastFailureCode() {
return lastFailureCode;
}
public void setLastFailureCode(String lastFailureCode) {
this.lastFailureCode = lastFailureCode;
}
}
@@ -12,6 +12,20 @@
--
-- The default fills existing rows without a rewrite: every earlier claim counts against the
-- budget, which is what the relay assumed until now.
--
-- This file was edited after it was first written, before any deployment applied it (the branch
-- that added it was not merged), to add the bound below. applied-migrations.sha256 carries the
-- new checksum; a development database that applied the earlier text fails Flyway validation:
-- recreate it.
-- Bound the wait for the lock this migration takes (ACCESS EXCLUSIVE on outbox_event, held until it
-- commits). Unbounded, it queues behind any open transaction that has touched the table, and every
-- read and write of the table after it queues behind the migration — the relay's claim and every
-- business write that appends an event. Five seconds, then the migration fails, rolls back whole
-- and the database stays at V19: deploy again once that transaction has ended (re-review 2026-11-03
-- round 2, RR-02-09; the rule is docs/jpa/migration-guide.md "Bound the lock wait").
SET LOCAL lock_timeout = '5s';
ALTER TABLE outbox_event
ADD COLUMN deferred_attempt_count INTEGER NOT NULL DEFAULT 0
CONSTRAINT ck_outbox_event_deferred_attempt_count CHECK (deferred_attempt_count >= 0);
@@ -17,5 +17,19 @@
-- IN_FLIGHT only (so the partial index ix_outbox_event_eligible leaves PARKED out), and the order
-- gate and its index ix_outbox_event_unpublished_aggregate_order treat every status but PUBLISHED as
-- blocking — which is what holding a row in its aggregate's place means.
--
-- This file was edited after it was first written, before any deployment applied it (the branch
-- that added it was not merged), to add the bound below. applied-migrations.sha256 carries the
-- new checksum; a development database that applied the earlier text fails Flyway validation:
-- recreate it.
-- Bound the wait for the lock this migration takes (ACCESS EXCLUSIVE on outbox_event, held until it
-- commits). Unbounded, it queues behind any open transaction that has touched the table, and every
-- read and write of the table after it queues behind the migration — the relay's claim, the gauges
-- and every business write that appends an event. Five seconds, then the migration fails, rolls
-- back whole and the database stays at V21: deploy again once that transaction has ended (re-review
-- 2026-11-03 round 2, RR-02-09; the rule is docs/jpa/migration-guide.md "Bound the lock wait").
SET LOCAL lock_timeout = '5s';
ALTER TABLE outbox_event
ADD COLUMN last_failure_code VARCHAR(120);
@@ -1,18 +1,29 @@
package dev.caskeleton.adapter.outbound.persistence.idempotency.postgresql;
import dev.caskeleton.adapter.outbound.persistence.idempotency.jpa.IdempotencyReaper;
import dev.caskeleton.adapter.outbound.persistence.idempotency.jpa.IdempotencyRecordJpaRepository;
import dev.caskeleton.adapter.outbound.persistence.platform.JpaPlatformContractSupport;
import dev.caskeleton.adapter.outbound.persistence.transaction.SpringTransaction;
import dev.caskeleton.application.idempotency.IdempotencyStorePort;
import dev.caskeleton.application.idempotency.testkit.IdempotencyStoreContract;
import jakarta.persistence.EntityManagerFactory;
import java.time.Clock;
import java.time.Duration;
import java.util.Properties;
import java.util.function.Supplier;
import org.flywaydb.core.Flyway;
import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Tag;
import org.springframework.data.jpa.repository.support.JpaRepositoryFactory;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.jdbc.datasource.DataSourceTransactionManager;
import org.springframework.orm.jpa.JpaTransactionManager;
import org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean;
import org.springframework.orm.jpa.SharedEntityManagerCreator;
import org.springframework.orm.jpa.vendor.HibernateJpaVendorAdapter;
import org.springframework.transaction.support.TransactionTemplate;
/**
* The PostgreSQL store, against a real database through the shipped migrations, held to the same
@@ -20,7 +31,12 @@ import org.springframework.jdbc.datasource.DataSourceTransactionManager;
*
* <p>Every call runs in its own {@link SpringTransaction} write transaction, as the executor's
* calls do; the store refuses to run outside one. Time is the database's ({@code
* clock_timestamp()}), so the timed case lets it pass for real with a one-second lease.
* clock_timestamp()}), so the timed cases let it pass for real with a one-second lease.
*
* <p>Letting time pass also runs the deployment's own {@link IdempotencyReaper}, through the real
* Spring Data repository. The store never expires a row itself — the reaper deletes every row past
* {@code expires_at}, whatever its state — so a contract that slept without reaping could not see a
* row that would have been purged under a live lease (re-review 2026-11-04 RR-03-11).
*/
@Tag("jpa-contract")
class PostgreSqlIdempotencyStoreContractTest extends IdempotencyStoreContract {
@@ -28,6 +44,9 @@ class PostgreSqlIdempotencyStoreContractTest extends IdempotencyStoreContract {
private static JpaPlatformContractSupport support;
private static JdbcTemplate jdbc;
private static SpringTransaction transactions;
private static LocalContainerEntityManagerFactoryBean reaperPersistence;
private static IdempotencyReaper reaper;
private static TransactionTemplate reaperTransactions;
@BeforeAll
static void start() {
@@ -44,10 +63,37 @@ class PostgreSqlIdempotencyStoreContractTest extends IdempotencyStoreContract {
"update capability_schema_registry set lifecycle_state = 'ACTIVE' "
+ "where capability_id = 'jpa-idempotency-owner-safe-v2'");
transactions = new SpringTransaction(new DataSourceTransactionManager(support.dataSource()));
startReaper();
}
/**
* The reaper as a deployment builds it: its repository from Spring Data over the idempotency
* entity, its purge inside a JPA transaction (the {@code @Transactional} a bean proxy would add).
*/
private static void startReaper() {
reaperPersistence = new LocalContainerEntityManagerFactoryBean();
reaperPersistence.setDataSource(support.dataSource());
reaperPersistence.setJpaVendorAdapter(new HibernateJpaVendorAdapter());
reaperPersistence.setPackagesToScan(
"dev.caskeleton.adapter.outbound.persistence.idempotency.jpa.entity");
Properties properties = new Properties();
properties.setProperty("hibernate.jdbc.time_zone", "UTC");
reaperPersistence.setJpaProperties(properties);
reaperPersistence.afterPropertiesSet();
EntityManagerFactory entityManagers = reaperPersistence.getObject();
IdempotencyRecordJpaRepository repository =
new JpaRepositoryFactory(
SharedEntityManagerCreator.createSharedEntityManager(entityManagers))
.getRepository(IdempotencyRecordJpaRepository.class);
reaper = new IdempotencyReaper(repository, Clock.systemUTC());
reaperTransactions = new TransactionTemplate(new JpaTransactionManager(entityManagers));
}
@AfterAll
static void stop() {
if (reaperPersistence != null) {
reaperPersistence.destroy();
}
if (support != null) {
support.close();
}
@@ -81,6 +127,7 @@ class PostgreSqlIdempotencyStoreContractTest extends IdempotencyStoreContract {
Thread.currentThread().interrupt();
throw new IllegalStateException("interrupted while letting the lease run", interrupted);
}
reaperTransactions.executeWithoutResult(ignored -> reaper.reap());
}
/**
@@ -0,0 +1,205 @@
package dev.caskeleton.adapter.outbound.persistence.readiness;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.catchThrowable;
import com.zaxxer.hikari.HikariDataSource;
import java.sql.Connection;
import java.sql.SQLException;
import java.sql.Statement;
import java.time.Duration;
import java.util.List;
import java.util.Locale;
import java.util.UUID;
import java.util.concurrent.Executors;
import java.util.concurrent.ScheduledExecutorService;
import java.util.concurrent.ScheduledFuture;
import java.util.concurrent.TimeUnit;
import org.flywaydb.core.Flyway;
import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.CsvSource;
import org.springframework.jdbc.core.JdbcTemplate;
/**
* The migrations that lock a table already in use give up within their bound instead of stopping
* the table, against real PostgreSQL (re-review 2026-11-03 round 2, RR-02-09).
*
* <p>Each case is the deploy the bound exists for: a database one version below the migration, and
* a transaction that has read the table and stays open — an operator's {@code BEGIN} in psql, a
* report, an instance of the old version mid-request. The migration needs a lock that conflicts
* with that read. Unbounded, it waits until the reader leaves and every read and write of the table
* queues behind it meanwhile; the reader here leaves after fifteen seconds, so an unbounded
* 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
* against a writer in {@code PostgreSqlOutboxOrderKeyRunbookIntegrationTest}.
*/
class PostgreSqlMigrationLockWaitIntegrationTest {
private static final String LOCK_NOT_AVAILABLE = "55P03";
private static final Duration READER_STAYS = Duration.ofSeconds(15);
private static final Duration GIVES_UP_WITHIN = Duration.ofSeconds(10);
private static PostgreSqlReadinessSupport postgres;
@BeforeAll
static void setup() {
postgres = PostgreSqlReadinessSupport.start();
}
@AfterAll
static void cleanup() {
if (postgres != null) {
postgres.close();
}
}
@ParameterizedTest
@CsvSource({"20, outbox_event", "22, outbox_event"})
@DisplayName("outbox_event를 읽는 트랜잭션이 열려 있으면 그 테이블을 잠그는 outbox 마이그레이션은 상한 안에 실패하고 한 버전 아래에 남는다")
void anOutboxMigrationGivesUpOnAHeldTableAndLeavesTheVersionBelowIt(int version, String table)
throws Exception {
try (HikariDataSource database = postgres.createDatabase(databaseName())) {
// given
Flyway below = outboxStream(database, version - 1);
below.migrate();
// when
Attempt attempt =
whileAReaderHolds(database, table, outboxStream(database, version)::migrate);
// then
assertThat(
List.of(
String.valueOf(attempt.sqlState()),
attempt.tookLessThan(GIVES_UP_WITHIN),
below.info().current().getVersion().getVersion()))
.containsExactly(LOCK_NOT_AVAILABLE, true, String.valueOf(version - 1));
}
}
@ParameterizedTest
@CsvSource({
"11, notification_reconciliation_job",
"12, notification_suppression",
"13, notification_request"
})
@DisplayName("알림 테이블을 읽는 트랜잭션이 열려 있으면 그 테이블을 잠그는 알림 마이그레이션은 상한 안에 실패하고 한 버전 아래에 남는다")
void aNotificationMigrationGivesUpOnAHeldTableAndLeavesTheVersionBelowIt(
int version, String table) throws Exception {
try (HikariDataSource database = postgres.createDatabase(databaseName())) {
// given
applyCore(database);
Flyway below = notificationStream(database, version - 1);
below.baseline();
below.migrate();
// when
Attempt attempt =
whileAReaderHolds(database, table, notificationStream(database, version)::migrate);
// then
assertThat(
List.of(
String.valueOf(attempt.sqlState()),
attempt.tookLessThan(GIVES_UP_WITHIN),
below.info().current().getVersion().getVersion()))
.containsExactly(LOCK_NOT_AVAILABLE, true, String.valueOf(version - 1));
}
}
/**
* 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}.
*/
private static Attempt whileAReaderHolds(
HikariDataSource database, String table, Runnable migration) throws SQLException {
try (Connection reader = database.getConnection()) {
reader.setAutoCommit(false);
try (Statement statement = reader.createStatement()) {
statement.execute("SELECT count(*) FROM " + table);
}
ScheduledExecutorService release = Executors.newSingleThreadScheduledExecutor();
ScheduledFuture<Void> released =
release.schedule(
() -> {
reader.rollback();
return null;
},
READER_STAYS.toSeconds(),
TimeUnit.SECONDS);
try {
long started = System.nanoTime();
Throwable thrown = catchThrowable(migration::run);
return new Attempt(thrown, Duration.ofNanos(System.nanoTime() - started));
} finally {
released.cancel(true);
release.shutdownNow();
}
}
}
private static Flyway outboxStream(HikariDataSource database, int target) {
return Flyway.configure()
.dataSource(database)
.locations("classpath:db/migration/postgresql")
.target(String.valueOf(target))
.load();
}
private static Flyway notificationStream(HikariDataSource database, int target) {
PostgreSqlOptionalStreamLifecycle.Stream stream =
PostgreSqlOptionalStreamLifecycle.notificationPlatform();
return Flyway.configure()
.dataSource(database)
.locations(stream.location())
.table(stream.historyTable())
.baselineVersion("0")
.baselineOnMigrate(false)
.target(String.valueOf(target))
.load();
}
/** The core stream, applied and promoted: what a deployment has before any capability stream. */
private static void applyCore(HikariDataSource database) {
Flyway core =
Flyway.configure()
.dataSource(database)
.locations("classpath:db/migration/jpa/core")
.table("flyway_jpa_core_history")
.baselineVersion("0")
.baselineOnMigrate(false)
.load();
core.baseline();
core.migrate();
new JdbcTemplate(database)
.update(
"UPDATE capability_schema_registry SET lifecycle_state = 'ACTIVE'"
+ " WHERE capability_id = ?",
"jpa-flyway-migration");
}
private static String databaseName() {
return "lockwait_" + UUID.randomUUID().toString().replace("-", "").toLowerCase(Locale.ROOT);
}
/** What the migration did while the reader held the table. */
private record Attempt(Throwable thrown, Duration took) {
/** The SQLState of the first SQL failure in the cause chain, or null when it did not fail. */
String sqlState() {
for (Throwable cause = thrown; cause != null; cause = cause.getCause()) {
if (cause instanceof SQLException sql) {
return sql.getSQLState();
}
}
return null;
}
boolean tookLessThan(Duration bound) {
return took.compareTo(bound) < 0;
}
}
}
@@ -75,6 +75,30 @@ class PostgreSqlOutboxDispositionRunbookIntegrationTest {
}
}
/**
* A re-drive that reset {@code attempt_count} alone is refused by the next claim, which moves the
* row back to DEAD (RR-05-01). The row then says why: before, it kept the code of the publish
* failure that dead-lettered it first, and the operator went after a broker credential instead of
* re-running the corrected SQL (re-review round 2, RR-02-12).
*/
@Test
@DisplayName("deferred 횟수를 되돌리지 않은 재발행 행을 claim이 DEAD로 옮기면 행의 원인 코드도 그 이유로 바뀐다")
void theClaimThatRefusesAHalfRedrivenRowWritesWhyOnTheRow() throws SQLException {
try (Outbox outbox = Outbox.create()) {
// given: dead after a refused credential, then re-driven by SQL that left the deferred count
String redriven = outbox.append("order-" + UUID.randomUUID(), 1, OCCURRED);
outbox.setCounters(redriven, "PENDING", 0, 2);
outbox.setFailureCode(redriven, "KAFKA_AUTHENTICATIONEXCEPTION");
// when
List<String> claimed = outbox.claimedEventIds();
// then
assertThat(List.of(claimed, outbox.status(redriven), outbox.failureCode(redriven)))
.containsExactly(List.of(), "DEAD", "ATTEMPT_COUNTERS_INCONSISTENT");
}
}
@Test
@DisplayName("runbook 구간 재발행 SQL은 그 구간의 DEAD 행만 claim 가능하게 되돌린다")
void theWindowRedriveReturnsOnlyTheDeadRowsOfTheWindow() throws SQLException {
@@ -253,6 +277,11 @@ class PostgreSqlOutboxDispositionRunbookIntegrationTest {
"UPDATE outbox_event SET last_failure_code = ? WHERE event_id = ?", failureCode, eventId);
}
String failureCode(String eventId) {
return jdbc.queryForObject(
"SELECT last_failure_code FROM outbox_event WHERE event_id = ?", String.class, eventId);
}
String status(String eventId) {
return jdbc.queryForObject(
"SELECT status FROM outbox_event WHERE event_id = ?", String.class, eventId);
@@ -9,10 +9,8 @@ import java.nio.file.Path;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.HexFormat;
import java.util.List;
import java.util.Map;
import java.util.TreeMap;
import java.util.stream.Stream;
import org.junit.jupiter.api.Test;
/**
@@ -23,33 +21,6 @@ import org.junit.jupiter.api.Test;
*/
class AppliedMigrationImmutabilityTest {
/**
* Every tree whose migrations run against the database this leaf owns.
*
* <p>The notification capability's stream moved to {@code
* adapter:outbound:persistence-notification} with its bytes and its classpath location unchanged
* ({@code db/migration/jpa/notification-platform}), so a database that applied it still
* validates. Its pins stayed in this manifest and are checked where the files now live: moving a
* migration must not be the way it stops being frozen.
*
* <p>The fileserver stream ({@code db/migration/jpa/fileserver}, in {@code
* adapter:outbound:persistence-fileserver}) runs against the same database through the same
* Flyway history and was never pinned at all; it is checked here on the same terms.
*
* <p>The messaging platform's tree ({@code db/migration/messaging}, in {@code
* messaging-reliability-jdbc-postgresql}) runs against it too once the consume side is selected:
* {@code adapter:inbound:messaging} applies its inbox range (V11xx). The tree is pinned whole —
* the platform outbox range ships from the same location to deployments that use it, and an
* edited migration stops those just the same.
*/
private static final List<Path> MIGRATION_ROOTS =
List.of(
Path.of("src/main/resources/db/migration"),
Path.of("../persistence-notification/src/main/resources/db/migration"),
Path.of("../persistence-fileserver/src/main/resources/db/migration"),
Path.of(
"../../../messaging/messaging-reliability-jdbc-postgresql/src/main/resources/db/migration"));
private static final Path MANIFEST = Path.of("src/test/resources/db/applied-migrations.sha256");
@Test
@@ -94,20 +65,8 @@ class AppliedMigrationImmutabilityTest {
private static Map<String, String> currentChecksums() throws IOException {
Map<String, String> checksums = new TreeMap<>();
for (Path root : MIGRATION_ROOTS) {
try (Stream<Path> files = Files.walk(root)) {
for (Path file :
files
.filter(path -> path.getFileName().toString().matches("V\\d+__.+\\.sql"))
.toList()) {
String key = root.relativize(file).toString().replace('\\', '/');
String previous = checksums.put(key, sha256(Files.readString(file)));
if (previous != null) {
throw new IllegalStateException(
key + " exists in two migration trees; the classpath would load one at random");
}
}
}
for (Map.Entry<String, Path> migration : MigrationTrees.versionedMigrations().entrySet()) {
checksums.put(migration.getKey(), sha256(Files.readString(migration.getValue())));
}
return checksums;
}
@@ -0,0 +1,105 @@
package dev.caskeleton.adapter.outbound.persistence.migration;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.outbound.persistence.testkit.migration.LockWaitMigrationInspector;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.TreeMap;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
/**
* Every migration this leaf's database runs bounds its wait for a lock on a table already in use
* ({@link LockWaitMigrationInspector}; re-review 2026-11-03 round 2, RR-02-09).
*
* <p>V21 got the bound and V22, in the same commit, did not: a rule written into one file is not a
* rule for the next one. This test is.
*/
class MigrationLockWaitTest {
/**
* Migrations released before the rule, which wait without a bound and stay that way: they are
* applied (on {@code main} when the rule came in), and an applied migration is never edited
* ({@link AppliedMigrationImmutabilityTest}). Their waits are behind every database that ran
* them. Nothing is added here — a new migration bounds its wait.
*/
private static final Set<String> RELEASED_BEFORE_THE_RULE =
Set.of(
"jpa/core/V2__widen_capability_schema_stream.sql",
"jpa/idempotency/V2__request_hash_varchar.sql",
"postgresql/V5__int_lock_expired_after.sql",
"postgresql/V9__widen_capability_schema_stream.sql",
"postgresql/V10__idempotency_request_hash_varchar.sql",
"postgresql/V13__outbox_canonical_transport_compatibility.sql",
"postgresql/V14__validate_outbox_canonical_constraints.sql",
"postgresql/V16__outbox_canonical_hash_columns_varchar.sql",
"postgresql/V17__outbox_event_lease_fencing.sql",
"postgresql/V18__outbox_event_unpublished_aggregate_order.sql",
"postgresql/V19__outbox_event_canonical_only.sql",
"jpa/notification-platform/V4__notification_platform_alignment_and_activation.sql",
"jpa/notification-platform/V5__notification_recipient_expiry.sql",
"jpa/notification-platform/V6__notification_projection_facts.sql",
"jpa/notification-platform/V7__notification_collapse.sql",
"jpa/notification-platform/V8__notification_admin_claim.sql",
"jpa/notification-platform/V9__notification_evidence_certainty.sql",
"jpa/fileserver/V2__fileserver_recovery_and_staging_cleanup.sql",
"jpa/fileserver/V3__fileserver_fenced_cleanup_lease.sql",
"jpa/fileserver/V4__fileserver_upload_terminal_state.sql",
"jpa/fileserver/V5__fileserver_file_owner.sql",
"messaging/V1002__messaging_outbox_lease_fencing.sql",
"messaging/V1004__messaging_outbox_canonical_metadata.sql",
"messaging/V1005__messaging_outbox_ordering_key_index.sql");
private final LockWaitMigrationInspector inspector = new LockWaitMigrationInspector();
@Test
@DisplayName("규칙 이후의 모든 마이그레이션은 기존 테이블 잠금 앞에 SET LOCAL lock_timeout을 둔다")
void everyMigrationAfterTheRuleBoundsItsLockWait() throws IOException {
// given
Map<String, Path> migrations = MigrationTrees.versionedMigrations();
// when
Map<String, List<String>> unbounded = unboundedStatements(migrations);
// then
assertThat(unbounded.keySet())
.as(
"these wait for a table lock without a bound: %s. Put SET LOCAL lock_timeout = '5s';"
+ " first (docs/jpa/migration-guide.md, \"Bound the lock wait\")",
unbounded)
.isSubsetOf(RELEASED_BEFORE_THE_RULE);
}
@Test
@DisplayName("규칙 이전 목록의 파일은 모두 아직 있고 실제로 상한 없이 잠금을 기다린다")
void everyMigrationReleasedBeforeTheRuleStillExistsAndStillWaitsUnbounded() throws IOException {
// given
Map<String, Path> migrations = MigrationTrees.versionedMigrations();
// when
Map<String, List<String>> unbounded = unboundedStatements(migrations);
// then
assertThat(unbounded.keySet())
.as("an entry here that no longer exists or waits for nothing only hides the next file")
.containsAll(RELEASED_BEFORE_THE_RULE);
}
private Map<String, List<String>> unboundedStatements(Map<String, Path> migrations)
throws IOException {
Map<String, List<String>> unbounded = new TreeMap<>();
for (Map.Entry<String, Path> migration : migrations.entrySet()) {
List<String> statements =
inspector.unboundedLockingStatements(Files.readString(migration.getValue()));
if (!statements.isEmpty()) {
unbounded.put(migration.getKey(), statements);
}
}
return unbounded;
}
}
@@ -0,0 +1,70 @@
package dev.caskeleton.adapter.outbound.persistence.migration;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import java.util.Map;
import java.util.TreeMap;
import java.util.stream.Stream;
/**
* The migration trees that run against the database this leaf owns, read the one way every
* migration rule here reads them: {@link AppliedMigrationImmutabilityTest} pins their bytes and
* {@link MigrationLockWaitTest} holds them to the lock-wait rule. One list, so a tree added for one
* rule is not quietly missing from the other.
*/
final class MigrationTrees {
/**
* Every tree whose migrations run against the database this leaf owns.
*
* <p>The notification capability's stream moved to {@code
* adapter:outbound:persistence-notification} with its bytes and its classpath location unchanged
* ({@code db/migration/jpa/notification-platform}), so a database that applied it still
* validates. Its pins stayed in this manifest and are checked where the files now live: moving a
* migration must not be the way it stops being frozen.
*
* <p>The fileserver stream ({@code db/migration/jpa/fileserver}, in {@code
* adapter:outbound:persistence-fileserver}) runs against the same database through the same
* Flyway history and was never pinned at all; it is checked here on the same terms.
*
* <p>The messaging platform's tree ({@code db/migration/messaging}, in {@code
* messaging-reliability-jdbc-postgresql}) runs against it too once the consume side is selected:
* {@code adapter:inbound:messaging} applies its inbox range (V11xx). The tree is pinned whole —
* the platform outbox range ships from the same location to deployments that use it, and an
* edited migration stops those just the same.
*/
static final List<Path> ROOTS =
List.of(
Path.of("src/main/resources/db/migration"),
Path.of("../persistence-notification/src/main/resources/db/migration"),
Path.of("../persistence-fileserver/src/main/resources/db/migration"),
Path.of(
"../../../messaging/messaging-reliability-jdbc-postgresql/src/main/resources/db/migration"));
private MigrationTrees() {}
/**
* Every versioned migration, keyed by its path below its tree ({@code postgresql/V22__...sql}),
* the key {@code applied-migrations.sha256} uses.
*/
static Map<String, Path> versionedMigrations() throws IOException {
Map<String, Path> migrations = new TreeMap<>();
for (Path root : ROOTS) {
try (Stream<Path> files = Files.walk(root)) {
for (Path file :
files
.filter(path -> path.getFileName().toString().matches("V\\d+__.+\\.sql"))
.toList()) {
String key = root.relativize(file).toString().replace('\\', '/');
if (migrations.put(key, file) != null) {
throw new IllegalStateException(
key + " exists in two migration trees; the classpath would load one at random");
}
}
}
}
return migrations;
}
}
@@ -329,6 +329,27 @@ class JpaOutboxStoreTest {
"runbook_link", "runbook://outbox/dead-letter")));
}
/**
* The claim moves a row to DEAD without the relay, so no failed completion writes the row's
* failure code. Without this the row kept the code of its last publish failure, and an operator
* reading {@code last_failure_code} looked for the wrong cause (re-review round 2, RR-02-12).
*/
@Test
@DisplayName("claim이 읽을 수 없는 행을 DEAD로 옮기면 그 원인 코드를 행에 남긴다")
void claimBatchLeavesTheReasonOnARowItCannotRead() {
// given
OutboxEventEntity tampered = pendingEntity("evt-tampered", "worklog-42");
tampered.setEnvelopeSha256("2".repeat(64));
when(claimRepo.claimEligible(eq(NOW), eq(1))).thenReturn(List.of(tampered));
// when
adapter.claimBatch(OWNER, 1, NOW, IN_FLIGHT_TIMEOUT);
// then
assertThat(List.of(tampered.getStatus(), String.valueOf(tampered.getLastFailureCode())))
.containsExactly("DEAD", "UNREADABLE_ROW");
}
private static Map<String, Object> keyValues(ILoggingEvent event) {
Map<String, Object> values = new LinkedHashMap<>();
if (event.getKeyValuePairs() != null) {
@@ -421,6 +442,60 @@ class JpaOutboxStoreTest {
Map.of(OutboxEventStatus.PENDING, 5L, OutboxEventStatus.IN_FLIGHT, 2L));
}
/**
* The status column has no CHECK, and a version that does not know a status meets it: an instance
* still on the version before PARKED during a rollout, the version an operator rolled back to, a
* value typed by hand. One unknown name failed the whole count, and with it every
* outbox.pending.size gauge, including the PENDING one the backlog alert reads (re-review round
* 2, RR-02-11).
*/
@Test
@DisplayName("이 버전이 모르는 상태 값이 테이블에 있어도 아는 상태의 수는 그대로 센다")
void countByStatusStillCountsTheKnownStatusesWhenTheTableHoldsAnUnknownOne() {
// given
List<Object[]> rows =
List.of(
new Object[] {"PENDING", 5L}, new Object[] {"ARCHIVED", 3L}, new Object[] {"DEAD", 1L});
when(repo.countGroupedByStatus()).thenReturn(rows);
// when
Map<OutboxEventStatus, Long> counts = adapter.countByStatus();
// then
assertThat(counts)
.containsExactlyInAnyOrderEntriesOf(
Map.of(OutboxEventStatus.PENDING, 5L, OutboxEventStatus.DEAD, 1L));
}
@Test
@DisplayName("모르는 상태 값은 한 번만 WARN으로 그 이름과 행 수를 말한다")
void countByStatusWarnsOnceNamingAStatusItDoesNotKnow() {
// given
List<Object[]> rows = List.<Object[]>of(new Object[] {"ARCHIVED", 3L});
when(repo.countGroupedByStatus()).thenReturn(rows);
Logger storeLog = (Logger) LoggerFactory.getLogger(JpaOutboxStore.class);
ListAppender<ILoggingEvent> captured = new ListAppender<>();
captured.start();
storeLog.addAppender(captured);
// when
try {
for (int poll = 0; poll < 3; poll++) {
adapter.countByStatus();
}
} finally {
storeLog.detachAppender(captured);
}
// then
assertThat(captured.list)
.singleElement()
.satisfies(
warn ->
assertThat(List.of(warn.getLevel().toString(), keyValues(warn)))
.containsExactly("WARN", Map.of("outbox.status", "ARCHIVED", "row_count", 3L)));
}
// ---- oldestUnpublishedAgeSecondsByEventType ----
@Test
@@ -12,6 +12,8 @@ import dev.caskeleton.adapter.outbound.persistence.testkit.arch.entity.InverseMa
import dev.caskeleton.adapter.outbound.persistence.testkit.arch.entity.InverseOneToOneEntity;
import dev.caskeleton.adapter.outbound.persistence.testkit.arch.entity.JoinColumnChildEntity;
import dev.caskeleton.adapter.outbound.persistence.testkit.arch.entity.JoinColumnParentEntity;
import dev.caskeleton.adapter.outbound.persistence.testkit.arch.entity.MutualForeignKeyInvoiceEntity;
import dev.caskeleton.adapter.outbound.persistence.testkit.arch.entity.MutualForeignKeyOrderEntity;
import dev.caskeleton.adapter.outbound.persistence.testkit.arch.entity.NoDefaultConstructorEntity;
import dev.caskeleton.adapter.outbound.persistence.testkit.arch.entity.OrderEntity;
import dev.caskeleton.adapter.outbound.persistence.testkit.arch.entity.OwningChildEntity;
@@ -202,9 +204,32 @@ class JpaArchitectureRulesTest {
.isInstanceOf(AssertionError.class)
.hasMessageContaining("JoinColumnParentEntity.children")
.hasMessageContaining("JoinColumnChildEntity.parent")
.hasMessageContaining("two fields map one link")
.hasMessageContaining("one side only");
}
@Test
@DisplayName("서로 다른 외래 키로 서로를 가리키는 두 엔티티는 한 링크의 사본이 아니라 서로 참조하는 두 테이블로 거부된다")
void twoEntitiesThatEachHoldAForeignKeyToTheOtherAreRefusedForTheirMutualReference() {
// given
var classes =
new ClassFileImporter()
.importClasses(MutualForeignKeyOrderEntity.class, MutualForeignKeyInvoiceEntity.class);
// when
Throwable failure =
catchThrowable(
() -> JpaArchitectureRules.associationsAreMappedFromOneSideOnly().check(classes));
// then
assertThat(failure)
.isInstanceOf(AssertionError.class)
.hasMessageContaining("MutualForeignKeyOrderEntity.latestInvoice")
.hasMessageContaining("MutualForeignKeyInvoiceEntity.order")
.hasMessageContaining("each holds a foreign key to the other")
.hasMessageNotContaining("two fields map one link");
}
@Test
@DisplayName("단방향 연관관계는 통과한다")
void unidirectionalAssociationsPass() {
@@ -0,0 +1,30 @@
package dev.caskeleton.adapter.outbound.persistence.testkit.arch.entity;
import jakarta.persistence.Entity;
import jakarta.persistence.FetchType;
import jakarta.persistence.Id;
import jakarta.persistence.JoinColumn;
import jakarta.persistence.ManyToOne;
/** Refused by the association rule: the other half of {@link MutualForeignKeyOrderEntity}. */
@Entity
public class MutualForeignKeyInvoiceEntity {
@Id private Long id;
@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "order_id")
private MutualForeignKeyOrderEntity order;
protected MutualForeignKeyInvoiceEntity() {}
/** The identifier. */
public Long id() {
return id;
}
/** The order this invoice bills. */
public MutualForeignKeyOrderEntity order() {
return order;
}
}
@@ -0,0 +1,37 @@
package dev.caskeleton.adapter.outbound.persistence.testkit.arch.entity;
import jakarta.persistence.Entity;
import jakarta.persistence.FetchType;
import jakarta.persistence.Id;
import jakarta.persistence.JoinColumn;
import jakarta.persistence.OneToOne;
/**
* Refused by the association rule: two entities that each hold a foreign key to the other.
*
* <p>{@code latest_invoice_id} here and {@link MutualForeignKeyInvoiceEntity#order}'s {@code
* order_id} are two links, not one mapped twice, so nothing falls out of step. They are refused for
* another reason: the two tables reference each other, so neither row can be inserted or deleted
* first and one key must be nullable and written by a second UPDATE (re-review round 2, RR-02-15).
*/
@Entity
public class MutualForeignKeyOrderEntity {
@Id private Long id;
@OneToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "latest_invoice_id")
private MutualForeignKeyInvoiceEntity latestInvoice;
protected MutualForeignKeyOrderEntity() {}
/** The identifier. */
public Long id() {
return id;
}
/** The order's most recent invoice. */
public MutualForeignKeyInvoiceEntity latestInvoice() {
return latestInvoice;
}
}
@@ -0,0 +1,89 @@
package dev.caskeleton.adapter.outbound.persistence.testkit.migration;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.catchThrowable;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.ValueSource;
/**
* A migration that locks a table already in use bounds how long it waits for that lock (re-review
* 2026-11-03 round 2, RR-02-09).
*/
class LockWaitMigrationInspectorTest {
private final LockWaitMigrationInspector inspector = new LockWaitMigrationInspector();
@ParameterizedTest
@ValueSource(
strings = {
"ALTER TABLE outbox_event ADD COLUMN last_failure_code VARCHAR(120);",
"CREATE UNIQUE INDEX ux_poster_title ON poster (upper(title));",
"CREATE INDEX IF NOT EXISTS ix_ledger ON ONLY grpc_operation_ledger (completed_at);",
"DELETE FROM notification_suppression WHERE id = 1;",
"UPDATE outbox_event SET status = 'FAILED';",
"LOCK TABLE outbox_event IN SHARE MODE;",
"ALTER TABLE outbox_event ADD COLUMN c INT;\nSET LOCAL lock_timeout = '5s';",
"SET lock_timeout = '5s';\nALTER TABLE outbox_event ADD COLUMN c INT;"
})
@DisplayName("이미 있는 테이블에 잠금을 거는 문장 앞에 SET LOCAL lock_timeout이 없으면 거부된다")
void aLockOnAnExistingTableWithoutABoundBeforeItIsRefused(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("V99__change.sql")
.hasMessageContaining("SET LOCAL lock_timeout");
}
@ParameterizedTest
@ValueSource(
strings = {
"SET LOCAL lock_timeout = '5s';\nALTER TABLE outbox_event ADD COLUMN c INT;",
"-- bound first\nset local lock_timeout = '5s';\ndelete from notification_suppression;",
"CREATE TABLE ledger (id BIGINT);\nCREATE INDEX ix_ledger ON ledger (id);\n"
+ "ALTER TABLE ledger ADD COLUMN c INT;",
"CREATE TABLE IF NOT EXISTS public.ledger (id BIGINT);\nALTER TABLE ledger ADD c INT;",
"CREATE INDEX CONCURRENTLY ix_outbox ON outbox_event (status);",
"-- 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';",
"CREATE TABLE poster_copy AS SELECT * FROM poster;"
})
@DisplayName("잠금 대기에 상한을 두었거나 잠글 기존 테이블이 없으면 통과한다")
void aBoundedOrLockFreeMigrationPasses(String sql) {
// given
MigrationResource migration = new MigrationResource("V99__change.sql", sql);
// when
Throwable refused = catchThrowable(() -> inspector.requireBoundedLockWait(migration));
// then
assertThat(refused).isNull();
}
@Test
@DisplayName("거부 메시지는 상한 없이 잠금을 기다리는 문장과 대상 테이블을 모두 말한다")
void theRefusalNamesEveryUnboundedStatementAndItsTable() {
// given
MigrationResource migration =
new MigrationResource(
"V12__suppression_unique.sql",
"DELETE FROM notification_suppression WHERE id > 1;\n"
+ "ALTER TABLE notification_suppression ADD CONSTRAINT uk UNIQUE (id);");
// when
Throwable refused = catchThrowable(() -> inspector.requireBoundedLockWait(migration));
// then
assertThat(refused)
.hasMessageContaining("delete from notification_suppression")
.hasMessageContaining("alter table notification_suppression");
}
}
@@ -11,9 +11,9 @@
2ba4214941a5563613b0dcc4f7cbf5f1278e342b900268721466e4bdeaa2fef2 jpa/idempotency/V1__expand_owner_safe_v2.sql
95be788589f01e32c9179acc80817e227e81805f8d518e8a9ac36e1c31b51da7 jpa/idempotency/V2__request_hash_varchar.sql
4379872989af0c97b937ff48527c788a2ba0216218d4df9435eba8c6e053ad8d jpa/notification-platform/V10__variables_payload_envelope_guard.sql
fb1eee652330995e2f761dd0c0cb9ca137b1c50dd99253aa9958c3ec130cf74b jpa/notification-platform/V11__notification_reconciliation_claim_lease.sql
a4c3b56e74bdeaa32be2e716e377aa920bc327b4517bf3d6c6c753cdbcf5c745 jpa/notification-platform/V12__notification_suppression_target_unique.sql
11bd6a456f2d0eb10c89a6f675a7a3af43f2ae1abda061a6f793f9d5a252f144 jpa/notification-platform/V13__notification_request_acceptance.sql
be51fabd07220f9ef885534ba36ada5f1491baf24cdfb54d25d93a19ddc29926 jpa/notification-platform/V11__notification_reconciliation_claim_lease.sql
43f9429f91c07528154ec01b721649b2c25fa98857ac154c7c08f4655634657f jpa/notification-platform/V12__notification_suppression_target_unique.sql
d01aaf59f66834358abf18246faa9a9eb8dfa9f42097ca9d968c44edff564630 jpa/notification-platform/V13__notification_request_acceptance.sql
1ac7cc1c2509868eb0ce202e1917bb36846f98f17ad4922abe3fac0ef128199b jpa/notification-platform/V1__notification_platform_core.sql
0add67aa23580e51712f84fabe9b09e08401ef708cfa1b3292b120fdb5c12fa2 jpa/notification-platform/V2__notification_platform_contact_template_policy.sql
f5b98598a59cc4376f5d233b410f8a5ae9f3cd94156291ebdf2d0da5a66f34ef jpa/notification-platform/V3__notification_platform_inbox_admin.sql
@@ -39,9 +39,9 @@ c20f1803c6afe84ac323a9fac9007f9a1676ed5ed253b72286c8fc1dee7c21d1 messaging/V100
b8f571e6cada72a8f2776f4462509ce4b535c964c75b1c3cfb34b9dc07446d59 postgresql/V17__outbox_event_lease_fencing.sql
44cacbde7d1381ca5290fb8ec28005e8127ff6b453ff84277ec8d1b3293d76c8 postgresql/V18__outbox_event_unpublished_aggregate_order.sql
a0306e5b0fbcaf43984d256362dc4244aec57a0ce5031e4f5263be3762fe1caf postgresql/V19__outbox_event_canonical_only.sql
c997fa20e10b68e0ca1b30cd7275018deaadc99bb0370b7b806332e9826e5217 postgresql/V20__outbox_event_deferred_attempt_count.sql
25db296e55444636c8a017d9b736eecf4a839a9caf1733c0c4a5f37bae5a3161 postgresql/V20__outbox_event_deferred_attempt_count.sql
21744ea1aab2b29fbb3417b9a5c4389522199413048cc7035aa649ffcdd852cf postgresql/V21__outbox_aggregate_sequence.sql
459942722c69d43b15fdab34849c6e34bbca35727e800eca18fbc5b3eebe5f4c postgresql/V22__outbox_event_last_failure_code.sql
20da5649a29bf2305f0e04ab14003b21b7f120d867439fb01f1658c98179dba0 postgresql/V22__outbox_event_last_failure_code.sql
8ab106731d4d04d3719da0692069947736dc490ca46aa5a3ea9bdf65a5d956dc postgresql/V1__idempotency_record.sql
6b62a01a4eeb792b81015b4810ecc6f3f021e0a17dea50c871493f7694d4f0b9 postgresql/V3__outbox_event.sql
c57ab8a35a10079190ad8a563be58fae4147c9406c5bb752debb6998324ccdf6 postgresql/V4__int_lock.sql
@@ -36,6 +36,13 @@ import java.util.stream.Stream;
* pass.
* </ul>
*
* <p>Two to-one links the other way round — {@code Order.@OneToOne latestInvoice} and {@code
* Invoice.@ManyToOne order}, each with its own foreign key — are not one link mapped twice, and the
* report says so. They are refused all the same, on purpose: the two tables reference each other,
* so neither row can be inserted or deleted first, one of the keys has to be nullable and written
* by a second UPDATE, and the entity graph is a cycle. One side holds the association and the other
* holds an ID or asks a query (re-review round 2, RR-02-15).
*
* <p>A unidirectional {@code @OneToMany} with its own {@code @JoinColumn}, or a {@code @ManyToOne}
* nobody points back at, has nothing to keep in step and passes. A self-reference is a pair only
* when a second member of the same class points back the other way ({@code @ManyToOne parent} and
@@ -108,13 +115,28 @@ public final class SingleSidedAssociationCondition extends ArchCondition<JavaCla
+ name(target, counterpart)
+ " (@"
+ back.get().annotation()
+ ") point at each other without mappedBy: two fields map one link, and"
+ " the read-only one does not follow a change made through the other."
+ ") point at each other without mappedBy: "
+ why(own.annotation(), back.get().annotation())
+ ALTERNATIVE));
return;
}
}
/**
* Why a pair without {@code mappedBy} is refused. A collection and the to-one that points back,
* or two many-to-many collections, map one link from both ends; two to-one links are two foreign
* keys that reference each other's table.
*/
private static String why(String own, String back) {
if (own.equals(inverseOf(back)) && !own.equals("OneToOne")) {
return "two fields map one link, and the read-only one does not follow a change made through"
+ " the other.";
}
return "each holds a foreign key to the other, so the two tables reference each other: neither"
+ " row can be inserted or deleted first, and one key has to be nullable and written by a"
+ " second UPDATE.";
}
/** The annotation the other half of a pair carries. */
private static String inverseOf(String annotation) {
return switch (annotation) {
@@ -0,0 +1,164 @@
package dev.caskeleton.adapter.outbound.persistence.testkit.migration;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Objects;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
/**
* Refuses a migration that waits without a bound for a lock on a table already in use (re-review
* 2026-11-03 round 2, RR-02-09; {@code docs/jpa/migration-guide.md}, "Bound the lock wait").
*
* <p>{@code ALTER TABLE} takes the strongest lock there is, and a plain {@code CREATE INDEX} one
* that stops every write. Either waits behind any transaction that has so much as read the table,
* and while it waits, every read and write after it queues behind it: one forgotten {@code BEGIN}
* in an operator's session stops the outbox, the relay and every request that writes it for as long
* as that session stays open. {@code SET LOCAL lock_timeout} before the first such statement turns
* that into a migration that fails after the bound, rolls back whole and leaves the database on the
* version before it — a failed deploy, not an outage. {@code LOCAL}, because a plain {@code SET}
* outlives the migration on the pooled connection Flyway borrowed.
*
* <p>What counts as waiting for a lock: {@code ALTER TABLE}, {@code CREATE [UNIQUE] INDEX} and
* {@code DROP INDEX} without {@code CONCURRENTLY}, {@code LOCK TABLE}, {@code TRUNCATE}, {@code
* DROP TABLE}, and {@code UPDATE}/{@code DELETE} (they wait on the rows other transactions hold). A
* statement on a table this same migration created earlier waits for nothing and is left out.
* Comments and quoted literals are not read as statements. The check reads text, not a parse tree:
* it is a guard against the forgotten line, not a proof.
*/
public final class LockWaitMigrationInspector {
private static final String NAME =
"((?:\"[^\"]+\"|[a-z_][a-z0-9_$]*)(?:\\.(?:\"[^\"]+\"|[a-z_][a-z0-9_$]*))?)";
private static final Pattern CREATED_TABLE =
Pattern.compile(
"\\bcreate\\s+(?:(?:temp|temporary|unlogged)\\s+)?table\\s+(?:if\\s+not\\s+exists\\s+)?"
+ NAME);
/** Each pattern's group 1, when it has one, is the table the statement locks. */
private static final List<Pattern> LOCKING =
List.of(
Pattern.compile("\\balter\\s+table\\s+(?:if\\s+exists\\s+)?(?:only\\s+)?" + NAME),
Pattern.compile(
"\\bcreate\\s+(?:unique\\s+)?index\\s+(?!concurrently\\b)(?:if\\s+not\\s+exists\\s+)?"
+ "(?:[a-z0-9_$\"]+\\s+)??on\\s+(?:only\\s+)?"
+ NAME),
Pattern.compile("\\bdrop\\s+index\\s+(?!concurrently\\b)"),
Pattern.compile("\\block\\s+(?:table\\s+)?(?:only\\s+)?" + NAME),
Pattern.compile("\\btruncate\\s+(?:table\\s+)?(?:only\\s+)?" + NAME),
Pattern.compile("\\bdrop\\s+table\\s+(?:if\\s+exists\\s+)?" + NAME),
Pattern.compile("\\bdelete\\s+from\\s+(?:only\\s+)?" + NAME),
Pattern.compile(
"\\bupdate\\s+(?:only\\s+)?" + NAME + "(?:\\s+(?:as\\s+)?[a-z_]\\w*)?\\s+set\\b"));
private static final Pattern BOUND = Pattern.compile("\\bset\\s+local\\s+lock_timeout\\b");
/**
* Fails when the migration locks a table it did not create before it bounds the wait.
*
* @throws IllegalStateException naming the migration and every statement that waits unbounded
*/
public void requireBoundedLockWait(MigrationResource migration) {
Objects.requireNonNull(migration, "migration");
List<String> unbounded = unboundedLockingStatements(migration.sql());
if (unbounded.isEmpty()) {
return;
}
throw new IllegalStateException(
migration.name()
+ " waits without a bound for a lock on a table already in use ("
+ String.join(", ", unbounded)
+ "). Put SET LOCAL lock_timeout = '5s'; before the first of them: while it waits, every"
+ " read and write of the table queues 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 before any {@code SET LOCAL
* lock_timeout}, each as its leading words and table; empty when there are none.
*/
public List<String> unboundedLockingStatements(String sql) {
if (sql == null) {
return List.of();
}
String text = withoutCommentsAndLiterals(sql).toLowerCase(Locale.ROOT).replaceAll("\\s+", " ");
Map<String, Integer> createdAt = new HashMap<>();
Matcher created = CREATED_TABLE.matcher(text);
while (created.find()) {
createdAt.putIfAbsent(table(created.group(1)), created.start());
}
Matcher bound = BOUND.matcher(text);
int boundAt = bound.find() ? bound.start() : Integer.MAX_VALUE;
List<Located> found = new ArrayList<>();
for (Pattern pattern : LOCKING) {
Matcher statement = pattern.matcher(text);
while (statement.find()) {
if (statement.start() < boundAt && !createdEarlier(statement, createdAt)) {
found.add(new Located(statement.start(), statement.group().trim()));
}
}
}
return found.stream()
.sorted((left, right) -> Integer.compare(left.at(), right.at()))
.map(Located::statement)
.toList();
}
private static boolean createdEarlier(Matcher statement, Map<String, Integer> createdAt) {
if (statement.groupCount() < 1 || statement.group(1) == null) {
return false;
}
Integer at = createdAt.get(table(statement.group(1)));
return at != null && at < statement.start();
}
/** The unqualified, unquoted table name: {@code public.ledger} and {@code ledger} are one. */
private static String table(String name) {
String last = name.substring(name.lastIndexOf('.') + 1);
return last.replace("\"", "");
}
/**
* Blanks out comments and single-quoted literals, keeping every other character in place, so a
* word in a {@code COMMENT ON ... IS '...'} or a {@code -- } line is not read as a statement.
*/
private static String withoutCommentsAndLiterals(String sql) {
StringBuilder kept = new StringBuilder(sql.length());
int i = 0;
while (i < sql.length()) {
char c = sql.charAt(i);
if (c == '-' && i + 1 < sql.length() && sql.charAt(i + 1) == '-') {
int end = sql.indexOf('\n', i);
i = end < 0 ? sql.length() : end;
kept.append(' ');
} else if (c == '/' && i + 1 < sql.length() && sql.charAt(i + 1) == '*') {
int end = sql.indexOf("*/", i + 2);
i = end < 0 ? sql.length() : end + 2;
kept.append(' ');
} else if (c == '\'') {
i++;
while (i < sql.length()) {
if (sql.charAt(i) == '\'' && i + 1 < sql.length() && sql.charAt(i + 1) == '\'') {
i += 2;
} else if (sql.charAt(i) == '\'') {
i++;
break;
} else {
i++;
}
}
kept.append("''");
} else {
kept.append(c);
i++;
}
}
return kept.toString();
}
private record Located(int at, String statement) {}
}
@@ -42,7 +42,10 @@ without a contract (the serving-state read model, consent, inbox), and why, are
their own Flyway stream (`NotificationSchemaStream`, history table
`flyway_jpa_notification_history`). An applied file is never edited: add the next `V<n>__`, pin
its SHA-256 in `applied-migrations.sha256`, and add it to `NotificationFixtures.migrations()`.
A migration that deletes rows states in a SQL comment which row survives and why.
A migration that deletes rows states in a SQL comment which row survives and why. A migration
that locks an existing table starts with `SET LOCAL lock_timeout = '5s';`
(`docs/jpa/migration-guide.md` "Bound the lock wait"; `MigrationLockWaitTest` in persistence-jpa
refuses one without it).
- **Insert-or-update is decided by the database.** Never find-then-insert: insert with
`ON CONFLICT (<unique key>) DO NOTHING`, and when it inserted nothing, update the existing row
through the managed entity (`JpaSuppressionStore.upsert`, `JpaPolicyStores.Preferences.save`,
@@ -10,6 +10,19 @@
-- has passed, and every write after the claim names the fence it was claimed with, so a holder that
-- outlived its lease cannot reschedule or delete a job somebody else now holds. The provider call
-- stays outside any transaction, which is the reason for a lease rather than a long-held row lock.
--
-- This file was edited after it was first written, before any deployment applied it (the branch
-- that added it was not merged), to add the bound below. applied-migrations.sha256 carries the
-- new checksum; a development database that applied the earlier text fails Flyway validation:
-- recreate it.
-- Bound the wait for the lock this migration takes (ACCESS EXCLUSIVE on
-- notification_reconciliation_job, held until it commits). Unbounded, it queues behind any open
-- transaction that has touched the table, and every read and write of the table after it queues
-- behind the migration. Five seconds, then the migration fails, rolls back whole and the database
-- stays at V10: deploy again once that transaction has ended (re-review 2026-11-03 round 2,
-- RR-02-09; the rule is docs/jpa/migration-guide.md "Bound the lock wait").
SET LOCAL lock_timeout = '5s';
ALTER TABLE notification_reconciliation_job
ADD COLUMN IF NOT EXISTS claimed_until timestamptz,
@@ -14,6 +14,19 @@
-- 4. then the earlier created_at, then the smaller id, so the choice is deterministic.
-- The other rows are deleted. A SuppressionId an operator saw for a deleted duplicate no longer
-- resolves; the surviving row carries the same target and reason.
--
-- This file was edited after it was first written, before any deployment applied it (the branch
-- that added it was not merged), to add the bound below. applied-migrations.sha256 carries the
-- new checksum; a development database that applied the earlier text fails Flyway validation:
-- recreate it.
-- Bound the wait for the lock this migration takes (row locks for the DELETE, then ACCESS EXCLUSIVE
-- on notification_suppression, held until it commits). Unbounded, it queues behind any open
-- transaction that has touched the table, and every read and write of the table after it queues
-- behind the migration — every send checks it. Five seconds, then the migration fails, rolls back
-- whole and the database stays at V11: deploy again once that transaction has ended (re-review
-- 2026-11-03 round 2, RR-02-09; the rule is docs/jpa/migration-guide.md "Bound the lock wait").
SET LOCAL lock_timeout = '5s';
DELETE FROM notification_suppression AS s
USING (
@@ -7,6 +7,19 @@
-- column records why, so the stored receipt says "dropped" rather than "accepted".
--
-- Existing rows were all accepted submissions; the default records exactly that.
--
-- This file was edited after it was first written, before any deployment applied it (the branch
-- that added it was not merged), to add the bound below. applied-migrations.sha256 carries the
-- new checksum; a development database that applied the earlier text fails Flyway validation:
-- recreate it.
-- Bound the wait for the lock this migration takes (ACCESS EXCLUSIVE on notification_request, held
-- until it commits). Unbounded, it queues behind any open transaction that has touched the table,
-- and every read and write of the table after it queues behind the migration — every notification
-- submission writes it. Five seconds, then the migration fails, rolls back whole and the database
-- stays at V12: deploy again once that transaction has ended (re-review 2026-11-03 round 2,
-- RR-02-09; the rule is docs/jpa/migration-guide.md "Bound the lock wait").
SET LOCAL lock_timeout = '5s';
ALTER TABLE notification_request
ADD COLUMN IF NOT EXISTS acceptance varchar(40) NOT NULL DEFAULT 'ACCEPTED';
@@ -14,6 +14,7 @@ import java.util.Optional;
import java.util.Set;
import java.util.concurrent.Semaphore;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.atomic.AtomicBoolean;
import java.util.concurrent.atomic.AtomicReference;
import java.util.function.Consumer;
import org.slf4j.Logger;
@@ -58,6 +59,7 @@ public final class RedisRuntimeOwner implements AutoCloseable {
private final Duration acquireTimeout;
private final Duration drainTimeout;
private final RedisLaneListener listener;
private final AtomicBoolean listenerFailureLogged = new AtomicBoolean();
private final AtomicReference<State> state = new AtomicReference<>(State.OPEN);
private final Object monitor = new Object();
@@ -345,13 +347,25 @@ public final class RedisRuntimeOwner implements AutoCloseable {
/**
* Tells the listener, outside the lock, and never lets it fail the borrow or the return.
*
* <p>The first failure is logged at WARN, the rest at DEBUG. At DEBUG alone a listener that
* always fails — a meter registry that refuses the lane meters — emptied every lane meter with no
* trace in an operator's log; at WARN every time it would log on every borrow (re-review
* 2026-11-04 RR-03-17).
*
* @param event what to tell it
*/
private void report(Consumer<RedisLaneListener> event) {
try {
event.accept(listener);
} catch (RuntimeException failure) {
LOG.debug("a Redis lane listener failed; the borrow is unaffected", failure);
if (listenerFailureLogged.compareAndSet(false, true)) {
LOG.warn(
"a Redis lane listener failed; the borrow is unaffected, the lane meters may be"
+ " missing, and further listener failures are logged at DEBUG",
failure);
} else {
LOG.debug("a Redis lane listener failed; the borrow is unaffected", failure);
}
}
}
@@ -3,6 +3,10 @@ package dev.caskeleton.adapter.outbound.cache.redis.runtime.config;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.catchThrowable;
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.outbound.cache.redis.runtime.RedisDeploymentMode;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.command.SemanticRedisCommands;
import dev.caskeleton.adapter.outbound.cache.redis.runtime.connection.RedisAccount;
@@ -27,6 +31,7 @@ import java.util.Optional;
import java.util.concurrent.TimeUnit;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.slf4j.LoggerFactory;
/**
* The lanes' own meters: how long a borrow waited, why one was refused, and how often a connection
@@ -312,6 +317,39 @@ class RedisLaneMetricsTest {
}
}
@Test
@DisplayName("지표 기록이 처음 실패하면 WARN 한 줄을 남기고 그 뒤 실패는 WARN으로 되풀이하지 않는다")
void aFailingListenerIsReportedAtWarnOnlyTheFirstTime() {
// given
RedisLaneListener failing =
new RedisLaneListener() {
@Override
public void waited(RedisLane lane, Duration waited, boolean admitted) {
throw new IllegalStateException("meter registry rejected the sample");
}
};
Logger ownerLog = (Logger) LoggerFactory.getLogger(RedisRuntimeOwner.class);
ListAppender<ILoggingEvent> captured = new ListAppender<>();
captured.start();
ownerLog.addAppender(captured);
try (RedisRuntimeOwner owner =
new RedisRuntimeOwner(
client, laneLimits(1), Duration.ofMillis(50), Duration.ofSeconds(1), failing)) {
// when
for (int borrow = 0; borrow < 3; borrow++) {
owner.borrow(ContributedLane.EXCLUSIVE).close();
}
} finally {
ownerLog.detachAppender(captured);
}
// then
// Silent at DEBUG, a registry conflict that empties every lane meter left no trace in an
// operator's log; at WARN on every borrow, it would flood it (re-review 2026-11-04 RR-03-17).
assertThat(captured.list).filteredOn(event -> event.getLevel() == Level.WARN).hasSize(1);
}
@Test
@DisplayName("listener 없이 만든 owner는 아무 지표도 내지 않는다")
void anOwnerWithoutAListenerRecordsNothing() {
@@ -223,7 +223,15 @@ public final class InMemorySemanticRedisCommands implements SemanticRedisCommand
: reply("OWNER_OPERATION_CONFLICT", attempt, rev, owner, "", "");
}
long leaseUntil = Long.parseLong(field(rendered, "leaseUntil"));
if ("FAILED_RETRYABLE".equals(state) || leaseUntil <= nowMillis) {
boolean leaseOver = leaseUntil <= nowMillis;
// As the program: an expired EXECUTING record has an unknown effect, so it is abandoned and
// answered RECOVERY_REQUIRED, never taken over (re-review 2026-11-04 RR-01-11).
if ("EXECUTING".equals(state) && leaseOver) {
setField(rendered, "state", "ABANDONED");
setField(rendered, "rev", Long.toString(rev + 1));
return reply("RECOVERY_REQUIRED", attempt, rev + 1, owner, "", "");
}
if ("FAILED_RETRYABLE".equals(state) || ("CLAIMED".equals(state) && leaseOver)) {
setField(rendered, "state", "CLAIMED");
setField(rendered, "owner", ownerToken);
setField(rendered, "attempt", Long.toString(attempt + 1));
@@ -25,7 +25,11 @@ import org.springframework.core.env.Environment;
* <p>The runner enforces this: when creating or running a rule brings any other singleton into
* existence — a configuration class behind a non-static {@code @Bean} method, a settings bean the
* method takes — the boot fails with that bean's name, because a bean created before the
* post-processors would keep unbound settings for the whole run (RR-06-01).
* post-processors would keep unbound settings for the whole run (RR-06-01). The rule itself is held
* to the same reason: a rule class with an {@code @Value} or {@code @Autowired} member, or one
* bound with {@code @ConfigurationProperties}, fails the boot by name in every profile, because
* that member would stay {@code null} (RR2-04-03). Take what the rule needs from the environment
* {@link #violations(Environment)} is given.
*/
public interface StartupRule {
@@ -1,16 +1,22 @@
package dev.caskeleton.adapter.outbound.support.startup;
import java.lang.reflect.AnnotatedElement;
import java.util.ArrayList;
import java.util.IdentityHashMap;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Objects;
import java.util.Optional;
import java.util.Set;
import org.springframework.beans.factory.config.BeanFactoryPostProcessor;
import org.springframework.beans.factory.config.ConfigurableListableBeanFactory;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.core.Ordered;
import org.springframework.core.annotation.AnnotationAwareOrderComparator;
import org.springframework.core.annotation.MergedAnnotations;
import org.springframework.core.env.Environment;
import org.springframework.util.ClassUtils;
import org.springframework.util.ReflectionUtils;
/**
* Runs every {@link StartupRule} the context holds, once, after the bean definitions are known and
@@ -44,12 +50,44 @@ import org.springframework.core.env.Environment;
* whole run, and so does every other consumer of that singleton (RR-06-01). The {@code static}
* declaration used to be a sentence in Javadoc; now the runner checks it. Any singleton that comes
* into existence while a rule is created or run fails the boot with its name — unless it is itself
* a {@link StartupRule} or a {@link RequiredProductionSecrets}, the two kinds that are declared
* {@code static} and argument-free for exactly this reason (a non-static one creates its
* configuration class, which is reported).
* a {@link StartupRule} or a {@link RequiredProductionSecrets}, which are meant to be created here.
*
* <h2>What a rule or a secret list may not need</h2>
*
* <p>Those two kinds are created early by design, so they must need nothing a post-processor
* provides: no {@code @Value}, {@code @Autowired}, {@code @Inject} or {@code @Resource} member, no
* {@code @PostConstruct}/{@code @PreDestroy} callback, and no {@code @ConfigurationProperties}
* binding on the class or its {@code @Bean} method. Each of those stays unset or uncalled for the
* whole run, silently: a rule then reads {@code null} and its check is off, and a settings class
* that doubles as a secret list keeps its defaults in {@code prod}, where the secret guard reads it
* early, and only there (review 2026-11-04 RR2-04-03). The runner refuses such a bean by name
* before any rule runs, in every profile, and again by its runtime class when it is created.
*
* <p>Checked by what the bean needs rather than by how it is declared. Requiring a {@code static}
* factory method was the other way, and it checks the wrong thing: it refuses a rule registered
* with an instance supplier, which needs nothing, and passes a {@code static @Bean} that returns a
* class with an {@code @Value} field, which is the same silent {@code null}.
*/
public final class StartupRuleRunner implements BeanFactoryPostProcessor, Ordered {
/** The kinds the runner creates before any bean post-processor exists. */
private static final List<Class<?>> EARLY_KINDS =
List.of(StartupRule.class, RequiredProductionSecrets.class);
/**
* What the post-processors that do not exist yet act on: member injection ({@code
* AutowiredAnnotationBeanPostProcessor}, {@code CommonAnnotationBeanPostProcessor}) and lifecycle
* callbacks. Named, not imported, so the check needs no Jakarta API on the classpath.
*/
private static final List<String> POST_PROCESSED_MEMBER_ANNOTATIONS =
List.of(
"org.springframework.beans.factory.annotation.Value",
"org.springframework.beans.factory.annotation.Autowired",
"jakarta.inject.Inject",
"jakarta.annotation.Resource",
"jakarta.annotation.PostConstruct",
"jakarta.annotation.PreDestroy");
private final Environment environment;
/**
@@ -63,6 +101,14 @@ public final class StartupRuleRunner implements BeanFactoryPostProcessor, Ordere
@Override
public void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory) {
// Before anything is created, and whether or not this profile reads them: the secret guard
// creates every RequiredProductionSecrets bean under prod only, so a bean that cannot be
// created early must fail where it is written, not on the first production boot.
for (Class<?> earlyKind : EARLY_KINDS) {
for (String name : beanFactory.getBeanNamesForType(earlyKind, true, false)) {
refuseUnprocessedMembers(beanFactory, name, beanFactory.getType(name, false));
}
}
IdentityHashMap<StartupRule, String> names = new IdentityHashMap<>();
List<StartupRule> rules = new ArrayList<>();
for (String name : beanFactory.getBeanNamesForType(StartupRule.class, true, false)) {
@@ -95,7 +141,9 @@ public final class StartupRuleRunner implements BeanFactoryPostProcessor, Ordere
/**
* Fails when creating or running the rule {@code ruleName} brought a singleton into existence
* other than a rule or a {@link RequiredProductionSecrets}: that bean was built before the bean
* post-processors, so its settings are unbound and it is not proxied, for the rest of the run.
* post-processors, so its settings are unbound and it is not proxied, for the rest of the run. A
* rule or secret list it created is held to {@link #refuseUnprocessedMembers} by its runtime
* class, which a {@code @Bean} method's declared return type may hide.
*/
private static void refusePulledForward(
ConfigurableListableBeanFactory beanFactory,
@@ -104,9 +152,15 @@ public final class StartupRuleRunner implements BeanFactoryPostProcessor, Ordere
Set<String> before) {
Set<String> pulled = new LinkedHashSet<>();
for (String name : beanFactory.getSingletonNames()) {
if (!before.contains(name)
&& !beanFactory.isTypeMatch(name, StartupRule.class)
&& !beanFactory.isTypeMatch(name, RequiredProductionSecrets.class)) {
if (before.contains(name)) {
continue;
}
if (EARLY_KINDS.stream().anyMatch(kind -> beanFactory.isTypeMatch(name, kind))) {
Object singleton = beanFactory.getSingleton(name);
if (singleton != null) {
refuseUnprocessedMembers(beanFactory, name, ClassUtils.getUserClass(singleton));
}
} else {
pulled.add(name);
}
}
@@ -130,6 +184,49 @@ public final class StartupRuleRunner implements BeanFactoryPostProcessor, Ordere
+ " bean is not a rule: keep it a bean, ordered before what it protects.");
}
/**
* Fails when the rule or secret list {@code name} needs a bean post-processor: it is created
* before any exists, so what one would inject, bind or call never happens, for the whole run.
*/
private static void refuseUnprocessedMembers(
ConfigurableListableBeanFactory beanFactory, String name, Class<?> type) {
List<String> needs = new ArrayList<>();
if (beanFactory.findAnnotationOnBean(name, ConfigurationProperties.class, false) != null) {
needs.add("@ConfigurationProperties binding");
}
if (type != null) {
ReflectionUtils.doWithFields(
type, field -> postProcessedBy(field).ifPresent(by -> needs.add(field.getName() + by)));
ReflectionUtils.doWithMethods(
type,
method ->
postProcessedBy(method).ifPresent(by -> needs.add(method.getName() + "()" + by)));
}
if (needs.isEmpty()) {
return;
}
throw StartupFailures.envValidation(
"'"
+ name
+ "' ("
+ (type == null ? "unknown type" : type.getName())
+ ") is a StartupRule or RequiredProductionSecrets, which are created before any bean"
+ " post-processor exists, but it needs one: "
+ needs
+ ". None of that happens for the whole run, so the rule reads null or the settings"
+ " keep their defaults, silently. Read the value from the Environment the rule or"
+ " the secret list is given, or pass it to the constructor in a static @Bean method;"
+ " a settings class is not a secret list.");
}
private static Optional<String> postProcessedBy(AnnotatedElement member) {
MergedAnnotations annotations = MergedAnnotations.from(member);
return POST_PROCESSED_MEMBER_ANNOTATIONS.stream()
.filter(annotations::isPresent)
.findFirst()
.map(annotation -> " (@" + annotation.substring(annotation.lastIndexOf('.') + 1) + ")");
}
/**
* Runs one rule and raises its violations as its phase's typed failure.
*
@@ -8,12 +8,14 @@ import java.util.concurrent.atomic.AtomicInteger;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.ObjectProvider;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.autoconfigure.AutoConfigurations;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.boot.test.context.runner.ApplicationContextRunner;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import org.springframework.core.env.Environment;
class StartupRuleRunnerTest {
@@ -163,6 +165,81 @@ class StartupRuleRunnerTest {
});
}
@Test
@DisplayName("비밀 목록을 겸하는 JavaBean 설정 클래스는 일찍 만들어지면 바인딩되지 않으므로 그 bean 이름을 대며 기동을 실패시킨다")
void aSettingsClassThatIsAlsoAProductionSecretsListFailsTheBoot() {
// given
BindingSecretsSettings.SEEN.clear();
// when
runner
.withPropertyValues("probe2.name=bound")
.withUserConfiguration(SecretReadingRuleConfig.class, BindingSecretsConfig.class)
.run(
context -> {
// then
assertThat(BindingSecretsSettings.SEEN).doesNotContainNull();
assertThat(context.getStartupFailure())
.isInstanceOf(StartupFailureException.class)
.hasMessageContaining("probe2-")
.hasMessageContaining("@ConfigurationProperties");
});
}
@Test
@DisplayName("비밀 목록을 겸하는 JavaBean 설정 클래스는 그것을 읽는 규칙이 없어도 기동을 실패시킨다")
void aSettingsClassThatIsAlsoAProductionSecretsListFailsTheBootInEveryProfile() {
// when
runner
.withPropertyValues("probe2.name=bound")
.withUserConfiguration(BindingSecretsConfig.class)
.run(
context -> {
// then
assertThat(context.getStartupFailure())
.isInstanceOf(StartupFailureException.class)
.hasMessageContaining("probe2-");
});
}
@Test
@DisplayName("@Value 필드를 가진 규칙 클래스는 필드가 주입되지 않으므로 그 필드 이름을 대며 기동을 실패시킨다")
void aRuleClassWithAValueFieldFailsTheBootNamingTheField() {
// given
FieldInjectedRule.SEEN.clear();
// when
runner
.withPropertyValues("probe3.mode=strict")
.withUserConfiguration(FieldInjectedRuleImport.class)
.run(
context -> {
// then
assertThat(FieldInjectedRule.SEEN).doesNotContainNull();
assertThat(context.getStartupFailure())
.isInstanceOf(StartupFailureException.class)
.hasMessageContaining("FieldInjectedRule")
.hasMessageContaining("mode");
});
}
@Test
@DisplayName("static @Bean이 돌려준 규칙이라도 @Value 필드가 있으면 기동을 실패시킨다")
void aStaticBeanRuleWhoseClassHasAValueFieldFailsTheBoot() {
// when
runner
.withPropertyValues("probe3.mode=strict")
.withUserConfiguration(StaticFieldInjectedRuleConfig.class)
.run(
context -> {
// then
assertThat(context.getStartupFailure())
.isInstanceOf(StartupFailureException.class)
.hasMessageContaining("fieldInjectedRule")
.hasMessageContaining("mode");
});
}
private static StartupRule rule(StartupPhase phase, String summary, List<String> violations) {
return new StartupRule() {
@Override
@@ -257,6 +334,67 @@ class StartupRuleRunnerTest {
}
}
/** RR2-04-03 2-a: a JavaBean settings class that is also the module's secret list. */
@ConfigurationProperties("probe2")
public static class BindingSecretsSettings implements RequiredProductionSecrets {
static final List<String> SEEN = new ArrayList<>();
private String name;
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
@Override
public List<String> requiredSecrets(Environment environment) {
SEEN.add(name);
return List.of();
}
}
@Configuration(proxyBeanMethods = false)
@EnableConfigurationProperties(BindingSecretsSettings.class)
static class BindingSecretsConfig {}
/** RR2-04-03 2-b: the most common way to write a Spring component, as a rule. */
public static class FieldInjectedRule implements StartupRule {
static final List<String> SEEN = new ArrayList<>();
@Value("${probe3.mode}")
private String mode;
@Override
public StartupPhase phase() {
return StartupPhase.ENV_VALIDATION;
}
@Override
public String summary() {
return "field";
}
@Override
public List<String> violations(Environment environment) {
SEEN.add(mode);
return List.of();
}
}
@Configuration(proxyBeanMethods = false)
@Import(FieldInjectedRule.class)
static class FieldInjectedRuleImport {}
@Configuration(proxyBeanMethods = false)
static class StaticFieldInjectedRuleConfig {
@Bean
static StartupRule fieldInjectedRule() {
return new FieldInjectedRule();
}
}
@Configuration(proxyBeanMethods = false)
static class NonStaticSecretsConfig {
@Bean
+4 -1
View File
@@ -89,7 +89,10 @@ configurations, Redis as one 376-line class.
and the one `StartupRuleRunner` raises them before any other singleton exists (declare it with a
`static` `@Bean` method that takes only the `Environment`, the bean factory or an `ObjectProvider`
of static `RequiredProductionSecrets`; the runner fails the boot naming any other bean a rule
creates). A guard that needs another bean stays a bean. A
creates, and naming any rule or `RequiredProductionSecrets` that has an `@Value`/`@Autowired`/
`@Inject`/`@Resource` member, a `@PostConstruct`/`@PreDestroy` callback or a
`@ConfigurationProperties` binding — those are created before the post-processors and would stay
unset). A guard that needs another bean stays a bean. A
capability's production secrets are the capability's: its module contributes a
`RequiredProductionSecrets` bean, and `SecretSourceValidator` checks the names without knowing
which roles exist.
+6 -3
View File
@@ -129,11 +129,14 @@ README의 "startup" 절에 있다.
### SecretSourceValidator
- **prod 에서 깨지면 부팅 자체를 거부하는 fail-fast 가드다.** 두 가지 prod 불변식을 context refresh
완료 전에 강제한다. (1) `__LOCAL_DEV_` 접두사를 가진 dev/local 가짜 자격증명 값이 prod 프로파일에
도달하는 것은 잘못 로드된 사고이므로 부팅을 중단시킨다. `fixture-` 접두사 값도 같다. 이 저장소가
도달하는 것은 잘못 로드된 사고이므로 부팅을 중단시킨다. 비밀값이 `fixture-`로 시작해도 같다. 이 저장소가
lane용으로 적어 둔 공개 비밀번호(`infra/redis-sdk/acl`의 Redis ACL fixture, compose lane의
`REDIS_LANE_*`)라서, lane 환경이나 lane ACL 파일을 베낀 배포가 그대로 운영에 뜨는 것을 막는다
(review 2026-11-03 RR-07-04). 비밀이 아닌 설정값이라도 prod에서 `fixture-`로 시작하면 거부되니 이름을
바꾼다. 실패 메시지는 변수 이름만 적고 값은 적지 않는다. (2) 레지스트리에서 `secret` +
(review 2026-11-03 RR-07-04). 이 검사는 비밀값만 본다 — 레지스트리의 `secret` 행
(`CLASSIFIED_SECRETS`), 모듈이 기여한 비밀, `secret://…/<VAR>` 참조가 가리키는 변수
(review 2026-11-04 RR2-04-01). `fixture-`는 평범한 단어라서 `fixture-api` Deployment의 pod 이름
(`HOSTNAME`)이나 앱 이름까지 거부하면 운영에서만 기동이 막혔다. `__LOCAL_DEV_` 표시는 정당한 값이 가질
일이 없으니 모든 값을 본다. 실패 메시지는 변수 이름만 적고 값은 적지 않는다. (2) 레지스트리에서 `secret` +
`prod_default: null`로 분류된 모든 키는 prod 에서 비어 있지 않게 주입돼야 한다 — 빈 시크릿으로
부팅하는 것은 금지다. dev/local 프로파일은 두 검사를 건너뛴다(`__LOCAL_DEV_*`가 의도된 로컬
폴백이므로).
@@ -25,6 +25,7 @@ import dev.caskeleton.application.capability.UseCaseCapability;
import dev.caskeleton.application.messaging.event.IntegrationEventDraft;
import dev.caskeleton.application.messaging.event.IntegrationEventDrafts;
import dev.caskeleton.application.security.RequiresPermission;
import dev.caskeleton.application.security.SystemCaller;
import dev.caskeleton.application.security.SystemInvoked;
import dev.caskeleton.application.usecase.CommandUseCase;
import dev.caskeleton.application.usecase.QueryUseCase;
@@ -447,23 +448,109 @@ class ApplicationBoundaryArchitectureTest {
.allowEmptyShould(true);
/**
* A {@link SystemInvoked} use case is a write with no permission check, so no transport may reach
* it. A bean of one fails startup ({@code PermissionEnforcementGuard}); this closes the other
* path, an inbound adapter that constructs or calls one itself (review 2026-11-03 RR-01-02).
* The inbound packages the system drives rather than a user: a broker delivery, a schedule. Only
* a {@link SystemCaller} may live here and reach a {@link SystemInvoked} use case; every other
* inbound package — web, GraphQL, gRPC, WebSocket, and any transport added later — is a way a
* user request comes in. A new system-driven inbound family joins this list, nowhere else.
*/
private static final String[] SYSTEM_DRIVEN_INBOUND_PACKAGES = {
"..adapter.inbound.messaging..", "..adapter.inbound.scheduler.."
};
/**
* What makes a class a way in for a user request: a user-transport adapter package or the
* framework types an endpoint is built from. {@code org.springframework.messaging} is named only
* for STOMP ({@code simp}, {@code @MessageMapping}): a broker listener's {@code @Payload} and
* {@code @Header} live beside them and are a system consumer's, not a user's.
*/
private static final DescribedPredicate<JavaClass> ARE_USER_TRANSPORT_TYPES =
JavaClass.Predicates.resideInAnyPackage(
"..adapter.inbound.web..",
"..adapter.inbound.graphql..",
"..adapter.inbound.grpc..",
"..adapter.inbound.websocket..",
"org.springframework.web..",
"org.springframework.graphql..",
"org.springframework.messaging.simp..",
"io.grpc..",
"jakarta.servlet..",
"jakarta.websocket..")
.or(
com.tngtech.archunit.core.domain.properties.HasName.Predicates.name(
"org.springframework.stereotype.Controller"))
.or(
com.tngtech.archunit.core.domain.properties.HasName.Predicates.name(
"org.springframework.messaging.handler.annotation.MessageMapping"))
.as("user-transport types (web, GraphQL, gRPC, WebSocket/STOMP endpoints)");
/**
* A class marked {@link SystemCaller}, or nested in one: a handler's anonymous or inner helper
* calls the use case on the handler's behalf.
*/
private static final DescribedPredicate<JavaClass> ARE_SYSTEM_CALLERS =
new DescribedPredicate<>("are @SystemCaller classes or nested in one") {
@Override
public boolean test(JavaClass candidate) {
for (JavaClass type = candidate;
type != null;
type = type.getEnclosingClass().orElse(null)) {
if (type.isAnnotatedWith(SystemCaller.class)) {
return true;
}
}
return false;
}
};
/**
* 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
* (decision 9.1, review 2026-11-03 RR-01-12). An inbound adapter may depend on one only when it
* says it is the second kind — {@link SystemCaller} — and {@code
* SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS} checks that claim. The rule names who may,
* not who may not, so a transport added later is refused without editing it. A bean of one fails
* startup ({@code PermissionEnforcementGuard}).
*/
@ArchTest
static final ArchRule INBOUND_ADAPTERS_DO_NOT_REACH_SYSTEM_INVOKED_USE_CASES =
static final ArchRule ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES =
noClasses()
.that()
.resideInAPackage("..adapter.inbound..")
.and(DescribedPredicate.not(ARE_SYSTEM_CALLERS))
.should()
.dependOnClassesThat()
.areAnnotatedWith(SystemInvoked.class)
.as(
"INBOUND_ADAPTERS_DO_NOT_REACH_SYSTEM_INVOKED_USE_CASES: a @SystemInvoked use case "
"ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES: a @SystemInvoked use case "
+ "declares no permission because only the system calls it; an inbound adapter "
+ "that reaches it runs a write with no authorization check. Its composition "
+ "constructs it and hands it to the scheduler that calls it.")
+ "a user request reaches (web, GraphQL, gRPC, WebSocket) must not depend on it. "
+ "A message handler or scheduled job marks itself @SystemCaller(reason = ...) "
+ "and constructs the use case it calls (manual 09 「소비」 step 4); a scheduler "
+ "assembled in a composition module gets it the way the outbox relay does.")
.allowEmptyShould(true);
/**
* {@link SystemCaller} is a claim, so it is checked: the marked class lives in a system-driven
* inbound package and is no endpoint a user can call — a controller, a GraphQL or STOMP mapping,
* a gRPC service. Without this the mark would be the next way to silence the rule above (review
* 2026-11-03 RR-01-12).
*/
@ArchTest
static final ArchRule SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS =
classes()
.that()
.areAnnotatedWith(SystemCaller.class)
.should()
.resideInAnyPackage(SYSTEM_DRIVEN_INBOUND_PACKAGES)
.andShould(
com.tngtech.archunit.lang.conditions.ArchConditions.never(
com.tngtech.archunit.lang.conditions.ArchConditions.dependOnClassesThat(
ARE_USER_TRANSPORT_TYPES)))
.as(
"SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS: a @SystemCaller lives in a "
+ "system-driven inbound package (..adapter.inbound.messaging.., "
+ "..adapter.inbound.scheduler..) and depends on no user-transport type — the mark "
+ "says no user request reaches the class, so a user transport cannot carry it")
.allowEmptyShould(true);
/**
@@ -114,7 +114,6 @@ class ArchRuleDiscoveryContractTest {
"IDENTIFIER_ADAPTER_DOES_NOT_DEPEND_ON_OTHER_ADAPTERS_OR_BOOTSTRAP",
"INBOUND_ADAPTERS_DEPEND_ON_PORTS_NOT_APPLICATION_SERVICES",
"INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS",
"INBOUND_ADAPTERS_DO_NOT_REACH_SYSTEM_INVOKED_USE_CASES",
"INBOUND_PORT_IMPLEMENTATIONS_DECLARE_A_CAPABILITY",
"INBOUND_PORT_IMPLEMENTATIONS_DECLARE_CAPABILITY",
"INBOUND_PORT_IMPLEMENTATIONS_END_WITH_USE_CASE",
@@ -144,6 +143,7 @@ class ArchRuleDiscoveryContractTest {
"NO_UUID_RANDOM_IN_CONTROLLER",
"NO_VARCHAR_255_FOR_ID_COLUMN",
"NO_WEBSOCKET_HANDLER",
"ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES",
"ONLY_THE_PERSISTENCE_ADAPTER_HOLDS_A_MONGO_HANDLE",
"ONLY_THE_SECURITY_PACKAGE_HANDLES_KEY_MATERIAL",
"OPTIONAL_ADAPTER_BEANS_ARE_GATED_BY_CONDITIONAL_ON_PROPERTY",
@@ -164,6 +164,7 @@ class ArchRuleDiscoveryContractTest {
"REQUEST_DTOS_DO_NOT_SILENCE_UNKNOWN_FIELDS",
"SHARED_CONTRACT_CONTAINS_ONLY_OPERATIONAL_CONTRACT_PACKAGES",
"STARTUP_FAILURES_ARE_RAISED_THROUGH_THE_TYPED_FACTORY",
"SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS",
"SYSTEM_INVOKED_USE_CASES_DECLARE_NO_PERMISSION",
"TEMPLATE_PACKAGES_DO_NOT_DEPEND_ON_FEATURE_PACKAGES",
"THROWABLES_ARE_NAMED_EXCEPTION",
@@ -6,8 +6,12 @@ import com.tngtech.archunit.core.domain.JavaClasses;
import com.tngtech.archunit.core.importer.ClassFileImporter;
import com.tngtech.archunit.lang.EvaluationResult;
import dev.caskeleton.application.architecture.violations.ApplicationDiagnosticFrameworkViolation;
import dev.caskeleton.bootstrap.architecture.allowed.adapter.inbound.messaging.SystemCallerHandlerFixture;
import dev.caskeleton.bootstrap.architecture.allowed.application.CleanProjectionQueryPort;
import dev.caskeleton.bootstrap.architecture.fixtures.application.RootWriteTransactionBoundaryUseCase;
import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.messaging.SystemCallerRestControllerFixture;
import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.messaging.UnmarkedSystemInvokedHandlerFixture;
import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.web.controller.SystemCallerControllerFixture;
import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.web.controller.SystemInvokedCallingControllerFixture;
import dev.caskeleton.bootstrap.architecture.violations.adapter.outbound.RawExternalResponseFixture;
import dev.caskeleton.bootstrap.architecture.violations.adapter.outbound.messaging.GenericTypeLeakingAdapterFixture;
@@ -158,25 +162,90 @@ class ArchitectureViolationFixtureTest {
.importPackages("dev.caskeleton.bootstrap.architecture.violations.secrets");
// Review 2026-11-03 RR-01-02: the controller and the use case it reaches, and nothing else, so
// the rule is proven on the one dependency it forbids.
// the rule is proven on the one dependency it forbids. RR-01-12 narrowed the rule to user
// transports; this is the path it must still refuse.
private static final JavaClasses SYSTEM_INVOKED_FROM_TRANSPORT_FIXTURE_ONLY =
new ClassFileImporter()
.importClasses(
SystemInvokedCallingControllerFixture.class, SystemInvokedFixtureUseCase.class);
// Review 2026-11-03 RR-01-12: the consume path manual 09 teaches — a marked handler and the use
// case it constructs — and the same handler without the mark.
private static final JavaClasses SYSTEM_CALLER_HANDLER_FIXTURE_ONLY =
new ClassFileImporter()
.importClasses(SystemCallerHandlerFixture.class, SystemInvokedFixtureUseCase.class);
private static final JavaClasses UNMARKED_HANDLER_FIXTURE_ONLY =
new ClassFileImporter()
.importClasses(
UnmarkedSystemInvokedHandlerFixture.class, SystemInvokedFixtureUseCase.class);
// A user transport that carries the mark: by its package, and by being an HTTP endpoint inside a
// system-driven package.
private static final JavaClasses SYSTEM_CALLER_IN_A_USER_TRANSPORT_PACKAGE_FIXTURE_ONLY =
new ClassFileImporter().importClasses(SystemCallerControllerFixture.class);
private static final JavaClasses SYSTEM_CALLER_THAT_IS_AN_HTTP_ENDPOINT_FIXTURE_ONLY =
new ClassFileImporter().importClasses(SystemCallerRestControllerFixture.class);
// Review 2026-11-03 RR-01-03: one class that builds the draft by hand.
private static final JavaClasses HAND_BUILT_DRAFT_FIXTURE_ONLY =
new ClassFileImporter().importClasses(HandBuiltIntegrationEventDraftFixture.class);
@Test
void anInboundAdapterThatCallsASystemInvokedUseCaseIsCaught() {
void aWebAdapterThatCallsASystemInvokedUseCaseIsCaught() {
EvaluationResult result =
ApplicationBoundaryArchitectureTest.INBOUND_ADAPTERS_DO_NOT_REACH_SYSTEM_INVOKED_USE_CASES
ApplicationBoundaryArchitectureTest.ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES
.evaluate(SYSTEM_INVOKED_FROM_TRANSPORT_FIXTURE_ONLY);
assertThat(result.hasViolation()).isTrue();
}
@Test
void aMessageHandlerMarkedAsASystemCallerMayReachASystemInvokedUseCase() {
EvaluationResult result =
ApplicationBoundaryArchitectureTest.ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES
.evaluate(SYSTEM_CALLER_HANDLER_FIXTURE_ONLY);
assertThat(result.getFailureReport().getDetails()).isEmpty();
}
@Test
void aMessageHandlerThatReachesASystemInvokedUseCaseWithoutTheMarkIsCaught() {
EvaluationResult result =
ApplicationBoundaryArchitectureTest.ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES
.evaluate(UNMARKED_HANDLER_FIXTURE_ONLY);
assertThat(result.hasViolation()).isTrue();
}
@Test
void aMessageHandlerMarkedAsASystemCallerIsASystemDrivenInboundAdapter() {
EvaluationResult result =
ApplicationBoundaryArchitectureTest.SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS
.evaluate(SYSTEM_CALLER_HANDLER_FIXTURE_ONLY);
assertThat(result.getFailureReport().getDetails()).isEmpty();
}
@Test
void aWebAdapterMarkedAsASystemCallerIsCaught() {
EvaluationResult result =
ApplicationBoundaryArchitectureTest.SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS
.evaluate(SYSTEM_CALLER_IN_A_USER_TRANSPORT_PACKAGE_FIXTURE_ONLY);
assertThat(result.hasViolation()).isTrue();
}
@Test
void anHttpEndpointInAMessagingPackageMarkedAsASystemCallerIsCaught() {
EvaluationResult result =
ApplicationBoundaryArchitectureTest.SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS
.evaluate(SYSTEM_CALLER_THAT_IS_AN_HTTP_ENDPOINT_FIXTURE_ONLY);
assertThat(result.hasViolation()).isTrue();
}
@Test
void aFeatureThatBuildsAnIntegrationEventDraftByHandIsCaught() {
EvaluationResult result =
@@ -0,0 +1,18 @@
package dev.caskeleton.bootstrap.architecture.allowed.adapter.inbound.messaging;
import dev.caskeleton.application.security.SystemCaller;
import dev.caskeleton.bootstrap.architecture.violations.application.SystemInvokedFixtureUseCase;
/**
* The shape manual 09 teaches for a consumer: a handler the broker consumer drives, marked as a
* system caller, that constructs the system-invoked use case it calls and keeps it to itself.
*/
@SystemCaller(reason = "fixture: the broker consumer calls it for each delivery")
public final class SystemCallerHandlerFixture {
private final SystemInvokedFixtureUseCase useCase = new SystemInvokedFixtureUseCase();
public void handle() {
useCase.handle();
}
}
@@ -0,0 +1,9 @@
/**
* "Allowed-as-data" fixture for the system-caller rules (review 2026-11-03 RR-01-12): a message
* handler that the broker consumer drives, marked {@code @SystemCaller}, calling a
* {@code @SystemInvoked} use case it constructed itself. {@code
* ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES} and {@code
* SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS} must NOT flag it — it is the one legitimate
* way a consumer reaches a system write (manual 09 「소비」 step 4).
*/
package dev.caskeleton.bootstrap.architecture.allowed.adapter.inbound.messaging;
@@ -0,0 +1,23 @@
package dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.messaging;
import dev.caskeleton.application.security.SystemCaller;
import dev.caskeleton.bootstrap.architecture.violations.application.SystemInvokedFixtureUseCase;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
/**
* Negative fixture for {@code SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS}: an HTTP endpoint
* placed in a system-driven inbound package and marked as a system caller. The package is right;
* the class is still a user transport (review 2026-11-03 RR-01-12).
*/
@SystemCaller(reason = "fixture: an HTTP endpoint hiding in the messaging package")
@RestController
public class SystemCallerRestControllerFixture {
private final SystemInvokedFixtureUseCase useCase = new SystemInvokedFixtureUseCase();
@PostMapping("/fixture/system-write")
public void trigger() {
useCase.handle();
}
}
@@ -0,0 +1,17 @@
package dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.messaging;
import dev.caskeleton.bootstrap.architecture.violations.application.SystemInvokedFixtureUseCase;
/**
* Negative fixture for {@code ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES}: a handler in a
* system-driven inbound package that reaches a {@code @SystemInvoked} use case without saying it is
* a system caller. The package alone is not the mark (review 2026-11-03 RR-01-12).
*/
public final class UnmarkedSystemInvokedHandlerFixture {
private final SystemInvokedFixtureUseCase useCase = new SystemInvokedFixtureUseCase();
public void handle() {
useCase.handle();
}
}

Some files were not shown because too many files have changed in this diff Show More