fix!: 재리뷰가 찾은 결함과 색인에서 빠졌던 발견 5건을 고친다

문제: 성숙도 리뷰 수정을 다시 읽은 재리뷰(Critical 0, 회귀 0)가
Important 27건·Minor 41건을 찾았다. 수정이 새로 만든 결함이 많았다.
@SystemInvoked가 권한 규칙의 탈출구가 됐고, 데모 계정 거부가 정확히
prod일 때만 걸렸고, outbox 순서 번호가 업그레이드 때 뒤로 갔고,
GraphQL union 아래 복잡도가 0이었고, 서블릿 오류 응답이 success:true로
나갔고, 호출자 deadline이 breaker를 열었다. 원래 리뷰 색인이 06 영역
발견 5건(06-10~14)을 빠뜨려 그동안 처리되지 않았다.

방법: 영역별 7묶음이 test-driven-development 절차로 실패 테스트를
먼저 쓰고 고쳤다. 결정은 재리뷰 README 4절에 적었다: 순서 번호는 V21이
기록한 전역 floor부터, 데모 계정은 local·test·demo 허용 목록,
@SystemInvoked bean은 기동 실패, complete 단계 실패는
IDEMPOTENCY_COMPLETION_UNKNOWN(결과 불명), 캐시 조건부 쓰기는 별도
SCRIPT lane, strict lane 정책은 build cache 입력, 끝나지 않는 재시도
행은 원인 코드·지표·PARKED 절차. 레지스트리가 선언만 하고 아무 코드도
내보내지 않던 redis.capability.* 지표 6개는 빼고 runbook을 실제
지표(redis.lane.*) 기준으로 고쳤다.

위험·한계: V21을 V22 없이 직접 고쳤다(어느 배포에도 아직 없음). 이
브랜치의 V21을 적용한 개발 DB는 다시 만들어야 한다. 서블릿 오류
디스패치를 보안 체인이 허용한다. 발행·저장소 포트 시그니처가 바뀌어
파생 서비스 코드가 깨진다. prod에서 fixture-로 시작하는 설정값은
기동을 막는다. httpclient failure-injection lane의 main 단계 중복
실행은 이전 결정대로 남겼다. 실제 CI runner 실행은 확인하지 못했다.

검증: ci, mainCheck, :integrationCheck, -p optional-platforms ci
integrationCheck performanceCheck, :performanceCheck, :releaseCheck
(-PgitRevision), verify-compose-profile-contracts(18 lane) 통과.
첫 실행의 실패 2건(FindSecBugs 1, sample 동시 생성 테스트의 v4 event
id)은 고친 뒤 ci·integrationCheck·mainCheck를 다시 돌려 통과했다.

Refs: docs/reviews/2026-11-03-rereview/README.md 3·4·6·7절
BREAKING CHANGE: outbox 발행 포트와 저장소 포트 시그니처, 순서 번호
첫 값(V21 floor 다음), 샘플 데모 계정 프로필 허용 목록, 새 오류 코드
IDEMPOTENCY_COMPLETION_UNKNOWN, prod의 fixture- 값 거부, 기동 rule은
static·의존 없음이어야 한다.
This commit is contained in:
DongHyeonka
2026-11-03 23:29:35 +09:00
parent 7ef8d0b4cb
commit bbe944bd3c
406 changed files with 13493 additions and 1656 deletions
+13 -7
View File
@@ -69,7 +69,9 @@ Package root: `dev.caskeleton.application`.
| `capability.Idempotency` | `IDEMPOTENT` / `KEYED` / `NOT_IDEMPOTENT`. |
| `capability.RepositoryAccess` | `NONE` / `READ_REPOSITORY` / `WRITE_REPOSITORY`. |
| `messaging.contract.IntegrationEventContractContribution<P>` | Closed exact-record payload type, canonical component order, local schema identity/hash and provider-neutral descriptor contribution. |
| `messaging.event.IntegrationEventDraft<P>` | Typed semantic event before local encoding; never JSON, Kafka or persistence state. |
| `messaging.event.IntegrationEventDraft<P>` | Typed semantic event before local encoding; never JSON, Kafka or persistence state. Built only through `IntegrationEventDrafts` (`INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`). |
| `messaging.event.IntegrationEventDrafts` | The one way a feature builds a draft: contract id, version and destination from the contract, correlation from the request when canonical (else the event id), `SINGLE_TENANT_SCOPE` for a feature without tenants. |
| `messaging.event.IntegrationIdentity` | The one grammar and the length bounds of event, correlation/causation and aggregate ids. Test a value with `isCanonical(value, bound)`; never copy the pattern. |
| `messaging.event.ValidatedIntegrationEvent` | Stable semantic identities plus immutable exact encoded bytes and hashes, ready for a later durable append boundary. |
| `messaging.event.IntegrationEventEncoderPort` | Framework-free local draft-to-validated-event boundary implemented by an outbound adapter (the template's: `adapter:outbound:support` `JsonIntegrationEventEncoder`). |
| `outbox.OutboxAppendPort` | The one outbox append: a `ValidatedIntegrationEvent`, in the caller's write transaction. |
@@ -77,9 +79,10 @@ Package root: `dev.caskeleton.application`.
## Notification (NOTIF-ADR-005)
`..notification.platform..` (leaf `application-notification`) is canonical. The R1 types directly
under `dev.caskeleton.application.notification` were removed on 2026-09-25; only the simple
`NotificationPort`, `Notification` and `NotificationChannel` remain there.
None of the notification types are in this leaf. `..notification.platform..` and the simple
`NotificationPort`, `Notification` and `NotificationChannel` directly under
`dev.caskeleton.application.notification` all belong to leaf `application-notification`; the shared
package prefix is the only link. The R1 orchestration types were removed on 2026-09-25.
## Naming convention
@@ -197,9 +200,12 @@ application-core never self-registers with a DI framework. It is **not final**:
declares `@RequiresPermission`, the web adapter enforces it through a CGLIB proxy, and CGLIB cannot
subclass a final class (`RequiresPermissionProxyabilityTest`). It is registered as a bean for the
same reason — a use case built with `new` is never checked. A use case only the system calls (a
scheduler, a relay) carries `@SystemInvoked(reason = ...)` instead of a permission and is not a bean.
A composition with `@RequiresPermission` beans but no enforcing advisor fails startup
(`composition:service-runtime` `PermissionEnforcementGuard`).
scheduler, a relay) carries `@SystemInvoked(reason = ...)` instead of a permission and is not a bean:
it is a write with no permission check, so a transport must not reach it. Both halves are enforced —
a `@SystemInvoked` bean fails startup, and an inbound adapter that depends on one fails
`INBOUND_ADAPTERS_DO_NOT_REACH_SYSTEM_INVOKED_USE_CASES`. A composition with `@RequiresPermission`
beans but no enforcing advisor fails startup too (`composition:service-runtime`
`PermissionEnforcementGuard`, both checks).
## Allowed transactional shapes
+70 -47
View File
@@ -32,7 +32,16 @@ Cache도 같은 원칙을 따른다. `cache` 패키지에는 cache-redis가 구
- `IntegrationEventDraft`는 canonical event/aggregate/order/correlation identity와 typed payload를
보유한다. tenant가 없는 모드도 null 대신 canonical system tenant scope를
`AggregateIdentity`에 넣어 dedupe/order identity가 PostgreSQL nullable uniqueness에 기대지
않게 한다.
않게 한다. 새 event의 event id와 causation id는 정규 소문자 UUIDv7이어야 한다
(`IntegrationIdentity.isCanonicalUuidV7`). messaging platform의 `MessageId`가 그것만 바꾸지 않고
싣기 때문이다. draft가 거부하므로 그런 id는 업무 트랜잭션 안에서 실패하고, 커밋된 뒤 relay에서
DEAD가 되지 않는다(리뷰 2026-11-01 06-06, 재리뷰 2026-11-03 RR-05-04). 저장 문법 `EventId`는
이 규칙 전에 쓰인 행을 읽으려고 넓게 남아 있다.
- draft는 `IntegrationEventDrafts.draft(...)`로만 만든다. 계약 id·버전·목적지, correlation
fallback(요청 값이 `IntegrationIdentity` 문법에 맞지 않으면 event id), tenant 없는 기능의
`SINGLE_TENANT_SCOPE`가 거기 한 번 있다. 운영 코드가 생성자를 직접 부르면
`INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`가 막는다. 식별자 문법·길이는
`IntegrationIdentity`가 정본이고, 값을 미리 검사할 때는 `isCanonical(value, bound)`를 부른다.
- `IntegrationEventEncoderPort` 뒤의 adapter가 deterministic encoding을 수행하고
`ValidatedIntegrationEvent`를 돌려준다. 템플릿의 구현은 `adapter:outbound:support`의
`JsonIntegrationEventEncoder`다(envelope v1 + payload record의 결정적 JSON, 선언한 schema hash를
@@ -43,9 +52,38 @@ Cache도 같은 원칙을 따른다. `cache` 패키지에는 cache-redis가 구
payload/envelope byte limit, sensitivity classification, same-event requeue horizon만 표현한다.
physical topic, Kafka cluster/security topology는 deployment binding의 책임이다.
이 단계의 완성 범위는 **framework-free semantic contract R1**이다. JSON Schema validator와
deterministic writer, Kafka ACK producer, PostgreSQL outbox append/relay는 후속 R2 작업이며 여기서
구현되었거나 검증됐다고 주장하지 않는다.
이 절의 타입은 framework-free semantic contract다. 결정적 writer는 `adapter:outbound:support`의
`JsonIntegrationEventEncoder`, outbox append·claim은 `adapter:outbound:persistence-jpa`, relay 조립은
`composition:outbox-relay`, 발행은 `adapter:outbound:messaging`의 platform bridge가 맡는다. payload를
JSON Schema로 매번 검증하는 validator는 템플릿에 없다(서비스가 encoder bean을 바꿔 둔다).
### payload version 올리기 (리뷰 2026-11-01 06-10)
payload schema는 version마다 `contracts/messaging/<contract>/v<N>.schema.json` 파일 하나다. 한 번
출시한 version 파일은 고치지 않는다. 이미 그 version으로 쓰인 event가 outbox·broker·DLQ에 남아 있고,
소비자는 그 schema로 만들어져 있다. 그래서 schema를 가진 leaf는 출시한 version의 SHA-256을
`src/test/resources/contracts/released-payload-schemas.sha256`에 고정하고, testFixtures의
`ReleasedPayloadSchemaContract`를 상속한 테스트가 두 가지를 막는다.
- 출시한 version 파일의 바이트가 바뀌면 실패한다(필드 삭제·타입 변경 같은 깨지는 변경 포함).
- 고정되지 않은 version 파일이 있으면 실패한다. 새 version은 manifest에 한 줄을 더하는 순간 출시된다.
필드를 바꾸거나 지우거나 더하는 변경은 새 version으로 낸다(설계 문서 2026-07-28 §14.4 STRICT_VERSIONED).
1. 새 version 추가: `v<N+1>.schema.json`, 새 payload record, 새 `IntegrationEventContractContribution`.
옛 version의 contribution은 그대로 둔다. encoder catalog는 `(contractId, payloadVersion)`마다 하나라
두 version이 함께 등록된다.
2. 소비자 배포: 모든 소비자가 v<N>과 v<N+1>을 둘 다 읽게 한다. outbox에 이미 쌓인 v<N> 행은 저장된
바이트 그대로 나가므로, 생산자를 바꾼 뒤에도 한동안 두 version이 함께 도착한다.
3. 생산자 전환: draft를 v<N+1> contract로 만든다. 이 커밋에서 manifest에 v<N+1> 줄을 더한다.
4. 옛 version 제거: outbox·broker·DLQ·archive에 v<N>이 더 남지 않았을 때만 contribution과 파일을 지우고
manifest 줄도 지운다. 지우는 줄은 리뷰에서 보이는 변경이다.
고른 방법과 버린 대안: 출시한 version 파일의 해시 고정(위). 버린 대안 — 직전 version과 새 version의
JSON Schema diff로 호환성을 검사하는 fixture: payload schema가 닫혀 있어(`unevaluatedProperties: false`)
필드 하나를 더해도 옛 소비자의 검증이 깨지므로, diff는 거의 모든 새 version을 "깨짐"으로 판정한다.
설계도 diff heuristic으로 호환성을 주장하지 않기로 했다(§14.4). 외부 schema registry 도입 — 이 템플릿
범위에 비해 운영 비용이 크다.
---
@@ -367,9 +405,14 @@ claim → 트랜잭션 밖에서 발행 → at-least-once 보장.
- 발행 성공(`CONFIRMED`) → `inWrite { markPublished }` → `PUBLISHED`.
- 확정 거부(`REJECTED_BEFORE_SEND`·`REJECTED_AFTER_BROKER`) → 시도 예산과 무관하게 바로 `markDead`.
- 일시적 실패(`AMBIGUOUS`·`REJECTED_RETRYABLE`, 즉 `OutboxPublishOutcome.retryable()`) →
시도 예산을 쓰지 않고 항상 `markDeferred(nextAttemptAt)`(FAILED 전이 + 미룬 시도로 기록). broker 정지·종료 중·permit 부족·
시도 예산을 쓰지 않고 항상 `markDeferred(nextAttemptAt, failureCode)`(FAILED 전이 + 미룬 시도로 기록). broker 정지·종료 중·permit 부족·
credential 교체는 모든 행을 같은 방식으로 실패시키고 저절로 끝나므로, 예산을 쓰게 하면 몇 분
장애가 aggregate 머리마다 DEAD 행을 남긴다(2026-11-01 리뷰 06-01·06-03).
장애가 aggregate 머리마다 DEAD 행을 남긴다(2026-11-01 리뷰 06-01·06-03). 대가로 끝이 없다 —
저절로 풀리지 않는 원인(진짜 credential 오류, Kafka adapter가 이름을 모르는 broker 거부)이면
영원히 재시도된다. 그래서 모든 실패 전이는 원인 코드를 함께 적는다(`OutboxPublishAttempt.failureCode`:
publisher가 붙인 코드, 없으면 결과 이름, 던진 예외면 그 타입 이름 → 행 `last_failure_code`, 보고
`failureCode`). 오래 미룬 행은 `OutboxStorePort.longRetries`로 세고, 운영자는 그 행을 `PARKED`로
보류할 수 있다(재리뷰 2026-11-03 RR-05-03, publish-failed runbook §4.1).
- 발행 예외(`RuntimeException`, adapter가 분류하지 못한 실패): `budgetedAttemptCount() >=
maxAttempts` 면 `markDead`, 아니면 `markFailed(nextAttemptAt)`. 예산은 이 경우에만 쓴다 —
payload 자체 결함일 수 있는 실패가 aggregate를 영원히 막지 않게 하는 장치다.
@@ -411,6 +454,10 @@ claim → 트랜잭션 밖에서 발행 → at-least-once 보장.
`@RequiresPermission("outbox:relay")`는 D4 규칙을 통과시키려고 붙인 장식이었다(빈이 아니라 한
번도 검사되지 않았고, 빈이었다면 매 tick 거부됐다). ArchUnit D4는 `@SystemInvoked`를 권한 선언
대신 받고, `SYSTEM_INVOKED_USE_CASES_DECLARE_NO_PERMISSION`이 둘을 함께 다는 것을 막는다.
면제의 전제(전송 계층이 닿지 않는다)도 코드가 지킨다: `@SystemInvoked` 빈은
`PermissionEnforcementGuard`가 기동을 실패시키고, inbound adapter가 그 클래스에 의존하면
`INBOUND_ADAPTERS_DO_NOT_REACH_SYSTEM_INVOKED_USE_CASES`가 빌드를 실패시킨다(review 2026-11-03
RR-01-02).
### OutboxBackoffPolicy
@@ -439,7 +486,9 @@ claim → 트랜잭션 밖에서 발행 → at-least-once 보장.
- `OutboxEventStatus` — 행 상태 머신(D5). `PENDING → IN_FLIGHT → {PUBLISHED | FAILED | DEAD}`,
`FAILED → IN_FLIGHT`(재claim), `IN_FLIGHT 고아 → IN_FLIGHT`(I6). `DEAD` 는 FIFO 형제를 막는다 —
같은 aggregate 의 뒤 행 claim 을 차단하므로 runbook 개입이 필요하다.
같은 aggregate 의 뒤 행 claim 을 차단하므로 runbook 개입이 필요하다. `PARKED` 는 운영자만 만든다
(`FAILED → PARKED`, runbook SQL): claim 되지 않고 DEAD 처럼 FIFO 형제를 막는다. 재개는
`PARKED → FAILED`, 버리기는 `PARKED → PUBLISHED`. relay 의 어떤 전이도 `PARKED` 로 가거나 나오지 않는다.
- append 는 `OutboxAppendPort.append(ValidatedIntegrationEvent)` 하나다(2026-09-28, 소유자 결정 7).
use case 가 `IntegrationEventDraft` 를 만들고 `IntegrationEventEncoderPort` 로 encode 한 뒤 같은
write 트랜잭션 안에서 append 한다. consumer 의 중복 제거 키는 event id 다.
@@ -448,11 +497,11 @@ claim → 트랜잭션 밖에서 발행 → at-least-once 보장.
다음 실패 시 dead-letter 여부를 결정한다. 옛 `OutboxEvent`/`NewOutboxEvent`/`LegacyOutboxAppendPort`
(free-text payload 모델)는 삭제됐다.
- `OutboxRelayResult` — relay 한 사이클의 결과. `claimedCount` + per-event outcome 목록. 내부
`Outcome` enum 이 `OutboxEventStatus` 의 5값을 재사용하지 않고 4값(PUBLISHED/FAILED/DEAD/
STALE — 마지막은 lease 를 잃어 결과를 쓰지 못한 경우)을
`Outcome` enum 이 `OutboxEventStatus` 를 재사용하지 않고 5값(PUBLISHED/FAILED/DEAD/STALE/RELEASED —
STALE 은 lease 를 잃어 결과를 쓰지 못한 경우, RELEASED 는 멈추는 relay 가 쓰지 않은 claim 을 놓은 경우)을
따로 두는 이유: relay 관점은 "이번 실행에서 무슨 일이 있었나" 이지 "행의 현재 영속 상태" 가
아니다(후자는 store 가 5값으로 추적). 별도 enum 이 메트릭·스케줄러 로깅 consumer 에게 relay API
를 깔끔하게 유지해 준다.
아니다(후자는 store 가 `OutboxEventStatus` 로 추적). 이 5값이 `outbox.publisher.published.total` 의
`outcome` label 이다(`docs/registries/metrics.yaml`, 계약 테스트가 비교).
- `PublishPendingOutboxEventsCommand` — relay 커맨드 마커. 스케줄러 구동이라 caller 파라미터가
없고, 모든 운영 파라미터는 생성 시점에 주입된다(IdempotencyExecutor 선례). 호출마다 새 인스턴스를
만들 필요가 없게 `INSTANCE` 싱글톤을 제공한다.
@@ -522,40 +571,12 @@ application 계층은 락 획득/해제 계약만 알고, 실제 구현은 adapt
---
## Notification R1
## 알림 타입은 이 leaf에 없다 (application-notification)
R1 오케스트레이션 타입(`dev.caskeleton.application.notification` 직속, production consumer 0건)은
2026-09-25에 삭제했다. canonical은 `..notification.platform..`이다(NOTIF-ADR-005). 직속 패키지에는
단순 알림 포트 `NotificationPort`·`Notification`·`NotificationChannel`만 남았다.
## 알림 포트 (notification)
### NotificationPort
- named channel + 논리 route 로 알림을 전달하는 outbound 포트.
- 2-인자 overload 는 관례적 `"default"` route 를 쓰는 편의 메서드다. adapter 가
`app.notification.routes.<channel>.<route>` 에서 구체 provider 목록을 해석하므로, application
계층은 provider 선택과 분리된다(호출부에 provider id 가 없다).
- fan-out(route 당 여러 provider)은 adapter 관심사다. 어떤 provider 가 실패하면 adapter 가
fail-open 정책(관측만, 전파 안 함)을 적용하고, route 자체가 unbound 면
`AdapterDisabledException("notification", ...)` 을 던진다.
- outbound 포트의 `*Port` 접미사 명명 규칙을 따른다(CLAUDE.md).
### Notification (값 객체)
- transport-중립 알림 값으로, routing target 과 내용만 운반한다.
- **절대 logger(또는 dependency logger)에 넘기면 안 된다** — recipient 주소·body 가 로그 라인에
닿을 수 없게 하기 위함(PII 계약).
- `adapter-outbound` 에서 `application-core` 로 옮긴 이유: 유스케이스가 adapter 타입을 import 하지
않고도 알림을 만들어 `NotificationPort` 로 전달할 수 있게 하기 위함(clean-architecture
HARD-STOP #3).
### Channel
- 알림 채널 판별자(`EMAIL`/`SLACK`). provider 와 독립적으로 전달 매체를 식별한다.
- caller 가 `Channel` 값(compile-safe) + 논리 route 이름을 `NotificationPort` 에 넘기면 adapter 가
`app.notification.routes.<channel>.<route>` 로 provider 목록을 해석한다 — 도메인은 provider
세부를 들여다보지 않는다(HARD-STOP #4).
`NotificationPort`·`Notification`·`NotificationChannel`과 알림 플랫폼(`..notification.platform..`,
NOTIF-ADR-005)은 leaf `application-notification`(`src/application-notification`)이 소유한다. 패키지
이름이 `dev.caskeleton.application.notification`이라 이 leaf의 것처럼 보일 뿐이다. 설명과 규칙은 그
leaf의 코드 Javadoc과 `docs/notification/`이 정본이다. R1 오케스트레이션 타입은 2026-09-25에 삭제했다.
---
@@ -593,9 +614,11 @@ R1 오케스트레이션 타입(`dev.caskeleton.application.notification` 직속
벽시계(예전 샘플의 epoch 마이크로초)는 인스턴스 사이 시계 차이·NTP 되돌림·같은 마이크로초 두 건에서
커밋 순서와 달라진다.
- 계약(`OutboxAggregateSequenceContract`, fake `InMemoryOutboxAggregateSequences`와 JPA 구현이 공유):
aggregate마다 1부터 하나씩 커지고 aggregate끼리 독립이다. JPA 구현(`JpaOutboxStore`, V21
`outbox_aggregate_sequence`)은 counter row lock으로 같은 aggregate 쓰기를 직렬화하고, 기존 outbox
row의 최대 번호 다음에서 시작하며, reaper가 row를 지워도 번호를 다시 쓰지 않는다. 같은
aggregate마다 첫 번호부터 하나씩 커지고, 첫 쓰기 두 개가 겹쳐도 둘 다 성공하며, aggregate끼리
독립이다. 첫 번호는 구현마다 다르다(fake는 1). JPA 구현(`JpaOutboxStore`, V21
`outbox_aggregate_sequence`)은 counter row lock으로 같은 aggregate 쓰기를 직렬화하고, 남은 outbox
row의 최대 번호와 V21이 기록한 floor(적용 시각의 epoch 마이크로초) 중 큰 값 다음에서 시작한다.
그래서 reaper가 지웠거나 identity가 바뀐 aggregate도 옛 벽시계 번호보다 뒤에서 시작한다. 같은
`(tenant_scope, aggregate_type, aggregate_id, aggregate_sequence, event_index)` 두 번째 append는 V21
유일 인덱스가 append 시점에 거부한다.
- aggregate가 자체 version 열(낙관적 락)을 가지면 그 값을 써도 된다. 이 포트는 counter가 없는
+2 -1
View File
@@ -28,7 +28,8 @@ strictTestLanes {
description = 'Runs exact Messaging application contract qualification tests.'
requires 'dev.caskeleton.application.messaging.contract.IntegrationEventContractContributionTest',
'dev.caskeleton.application.messaging.event.IntegrationEventDraftTest',
'dev.caskeleton.application.messaging.event.ValidatedIntegrationEventTest'
'dev.caskeleton.application.messaging.event.ValidatedIntegrationEventTest',
'dev.caskeleton.application.messaging.contract.ApplicationPayloadSchemaReleaseTest'
rejectSkipped = true
}
}
@@ -0,0 +1,32 @@
package dev.caskeleton.application.idempotency;
import dev.caskeleton.shared.error.ApiErrorCarrier;
import dev.caskeleton.shared.error.ApiErrorCode;
import dev.caskeleton.shared.error.OperationalError;
/**
* The action ran, and the store did not answer when its result was being recorded.
*
* <p>Not {@link IdempotencyUnavailableException}: that one is raised before the action, so the
* request certainly did not apply. Here it may have. Effects inside the action's own transaction
* roll back with this exception; anything else the action did — a call to another system, a message
* — has happened. Telling the client "not applied" would invite a resend under a new key, which is
* the duplicate the key exists to prevent (re-review 2026-11-03, RR-02-03).
*
* <p>A resend with the same key is safe: the server judges it as a replay when the result was in
* fact recorded, as in-flight while the attempt's lease lasts, and as recovery-required after that.
*/
public final class IdempotencyCompletionUnknownException extends RuntimeException
implements ApiErrorCarrier {
private static final long serialVersionUID = 1L;
public IdempotencyCompletionUnknownException() {
super("idempotency store did not answer while recording a completed action; outcome unknown");
}
@Override
public ApiErrorCode errorCode() {
return OperationalError.IDEMPOTENCY_COMPLETION_UNKNOWN;
}
}
@@ -16,9 +16,26 @@ import java.util.Optional;
*
* <p>The action runs only after a confirmed start. This preserves request-replay evidence; it does
* not create a cross-store exactly-once boundary, and nothing here should be read as claiming one.
*
* <p>A store that does not answer is reported by when it stopped answering: before the action it is
* {@link IdempotencyUnavailableException} (not applied), after it {@link
* IdempotencyCompletionUnknownException} (outcome unknown). {@code docs/web/http-contract.md} §2
* gives the client behaviour for each.
*/
public final class IdempotencyExecutor {
/**
* How long a refused duplicate is told to wait before resending with the same key: the {@code
* Retry-After} of the in-flight 409, and the one value every transport and the lease check read.
* The executor does not wait itself; it refuses at once (docs/web/http-contract.md §2).
*
* <p>It must stay below the processing lease, so the resend arrives while the first attempt can
* still finish; an early one costs only another 409. {@code IdempotencySettings} refuses to start
* with a lease no longer than this, so the rule is enforced where the lease is configured rather
* than remembered (re-review 2026-11-03, RR-02-05).
*/
public static final Duration IN_FLIGHT_RETRY_AFTER = Duration.ofSeconds(2);
private final IdempotencyStorePort store;
private final Duration processingLeaseTtl;
private final Duration replayTtl;
@@ -230,7 +247,8 @@ public final class IdempotencyExecutor {
return switch (store.complete(
owner, response, replayTtl, request.claimAttempt().operationId())) {
case COMPLETED, ALREADY_COMPLETED_SAME_RESULT -> result;
case UNAVAILABLE -> throw new IdempotencyUnavailableException();
// The action has run. Reporting "unavailable" here would tell the client it did not.
case UNAVAILABLE -> throw new IdempotencyCompletionUnknownException();
case INDETERMINATE -> reconcileCompletion(request, result, codec, alreadyRetried);
default -> throw recovery("completion was not confirmed");
};
@@ -265,7 +283,7 @@ public final class IdempotencyExecutor {
}
yield complete(request, requireOwner(inspection), result, codec, true);
}
case UNAVAILABLE -> throw new IdempotencyUnavailableException();
case UNAVAILABLE -> throw new IdempotencyCompletionUnknownException();
default -> throw recovery("the completion response is indeterminate and was not reconciled");
};
}
@@ -8,7 +8,8 @@ import dev.caskeleton.shared.error.OperationalError;
* Raised when another attempt still holds the same {@link IdempotencyScopeDigest}. Framework-free,
* application-owned; every transport maps it to a {@code IDEMPOTENT_IN_FLIGHT} 409 (retryable=true
* — the result is unknown and the client resends with the same key, never a new one; {@code
* docs/web/http-contract.md}). The message carries only the opaque scope digest, for logs.
* docs/web/http-contract.md}). The message carries only the opaque scope digest, for logs. How long
* the client waits before resending is {@link IdempotencyExecutor#IN_FLIGHT_RETRY_AFTER}.
*/
public class IdempotencyInFlightException extends RuntimeException implements ApiErrorCarrier {
@@ -4,7 +4,12 @@ import dev.caskeleton.shared.error.ApiErrorCarrier;
import dev.caskeleton.shared.error.ApiErrorCode;
import dev.caskeleton.shared.error.OperationalError;
/** Fail-closed signal raised before an action when request-replay coordination is unavailable. */
/**
* Fail-closed signal raised before an action when request-replay coordination is unavailable.
*
* <p>Only before the action: the request certainly did not apply. A store that stops answering
* after the action ran is {@link IdempotencyCompletionUnknownException} instead.
*/
public final class IdempotencyUnavailableException extends RuntimeException
implements ApiErrorCarrier {
@@ -6,7 +6,16 @@ import dev.caskeleton.application.messaging.contract.LogicalDestinationId;
import java.time.Instant;
import java.util.Optional;
/** Feature-owned semantic event before local encoding and schema validation. */
/**
* Feature-owned semantic event before local encoding and schema validation.
*
* <p>A new event's id and causation id are canonical lower-case UUIDv7s ({@link
* IntegrationIdentity#isCanonicalUuidV7}). The messaging bridge sends the event under its id as the
* platform's message id and refuses any other spelling; refused there, the event was already
* committed and the relay could only park it, with every later event of its aggregate behind it.
* Refused here, the write that announces it fails instead (review 06-06, re-review 2026-11-03
* RR-05-04).
*/
public record IntegrationEventDraft<P extends IntegrationPayload>(
EventId eventId,
ContractId contractId,
@@ -33,11 +42,24 @@ public record IntegrationEventDraft<P extends IntegrationPayload>(
if (occurredAt == null) {
throw new IllegalArgumentException("occurredAt must not be null");
}
if (!IntegrationIdentity.isCanonicalUuidV7(eventId.value())) {
throw new IllegalArgumentException(
"eventId must be a canonical lower-case UUIDv7, the id the messaging platform carries;"
+ " was "
+ eventId.value());
}
IntegrationIdentity.requireCorrelation("correlationId", correlationId);
if (causationId == null) {
throw new IllegalArgumentException("causationId Optional must not be null");
}
causationId.ifPresent(value -> IntegrationIdentity.requireCorrelation("causationId", value));
causationId.ifPresent(
value -> {
if (!IntegrationIdentity.isCanonicalUuidV7(value)) {
throw new IllegalArgumentException(
"causationId must be a canonical lower-case UUIDv7, the id of the event that caused"
+ " this one");
}
});
if (featurePayload == null) {
throw new IllegalArgumentException("featurePayload must not be null");
}
@@ -1,16 +1,31 @@
package dev.caskeleton.application.messaging.event;
import dev.caskeleton.application.outbox.OutboxPublishOutcome;
import dev.caskeleton.application.outbox.OutboxPublishAttempt;
import java.time.Duration;
import java.util.Optional;
import java.util.concurrent.CompletionStage;
/**
* Application-owned boundary for publishing one fully validated integration event.
*
* <p>The application exposes its canonical event model and outcome vocabulary only. Broker,
* transport, codec, and messaging-platform types remain on the outbound side of the boundary.
* transport, codec, and messaging-platform types remain on the outbound side of the boundary; a
* publisher that knows why an attempt was not confirmed translates its reason into the attempt's
* failure code ({@link OutboxPublishAttempt}) rather than handing the platform's type across.
*/
@FunctionalInterface
public interface IntegrationEventPublishPort {
CompletionStage<OutboxPublishOutcome> publish(ValidatedIntegrationEvent event);
CompletionStage<OutboxPublishAttempt> publish(ValidatedIntegrationEvent event);
/**
* The longest one publish can take before the returned stage completes, when the publisher knows
* it. The outbox relay sizes its batch against it (see {@code
* OutboxMessagePublishPort#longestAttempt}).
*
* @return the longest attempt, or empty when unknown
*/
default Optional<Duration> longestAttempt() {
return Optional.empty();
}
}
@@ -48,6 +48,31 @@ public final class IntegrationIdentity {
&& PATTERN.matcher(value).matches();
}
/**
* The spelling of a new event's id and causation id: a canonical lower-case UUIDv7, the only id
* the messaging platform's {@code MessageId} carries unchanged. A UUID in upper case or in the
* short form reads back as a different string, and any other version is refused outright.
*/
public static final String UUID_V7_GRAMMAR =
"[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}";
private static final Pattern UUID_V7 = Pattern.compile(UUID_V7_GRAMMAR);
/**
* Whether {@code value} is a canonical lower-case UUIDv7 ({@link #UUID_V7_GRAMMAR}).
*
* <p>The stored identity grammar ({@link #GRAMMAR}) is wider, because rows appended before this
* rule may hold other ids and must still be read back. A new event is held to this one where it
* is drafted ({@link IntegrationEventDraft}), so an id the platform would refuse fails in the
* writer's transaction instead of parking the committed event in the relay (review 06-06).
*
* @param value the candidate; {@code null} is not one
* @return true for a canonical lower-case UUIDv7
*/
public static boolean isCanonicalUuidV7(String value) {
return value != null && UUID_V7.matcher(value).matches();
}
/** Refuses a correlation or causation id outside the grammar or the bound. */
static void requireCorrelation(String field, String value) {
if (!isCanonical(value, CORRELATION_MAX_LENGTH)) {
@@ -17,8 +17,10 @@ import dev.caskeleton.application.transaction.TransactionPort;
import dev.caskeleton.application.usecase.CommandUseCase;
import dev.caskeleton.shared.digest.Sha256;
import java.time.Clock;
import java.time.Instant;
import java.util.Objects;
import java.util.Optional;
import java.util.UUID;
/**
* Accepts long-running work: one transaction that writes the operation row and the outbox row.
@@ -141,7 +143,7 @@ public class SubmitDurableOperationUseCase
*/
private static IntegrationEventDraft<DurableOperationSubmitted> submittedEvent(
DurableOperation operation) {
String identity = canonicalIdentity(operation.operationId());
String identity = canonicalIdentity(operation.operationId(), operation.submittedAt());
// Single-tenant scope even when the command names a tenant: the event only wakes a worker, the
// tenant travels in the stored operation, and mapping a TenantId into the lower-case scope
// grammar is the messaging platform's decision, not this use case's.
@@ -158,18 +160,34 @@ public class SubmitDurableOperationUseCase
}
/**
* The operation id itself when it fits the integration-event identity grammar — every id the HTTP
* adapter mints does — and otherwise a digest of it.
* The operation id itself when it is a canonical lower-case UUIDv7 — every id the HTTP adapter
* mints is — and otherwise a UUIDv7 derived from it.
*
* <p>An operation id may contain {@code ~} or run to 128 characters, and an event id may do
* neither. The digest keeps the event deterministic for the operation, so a retry still produces
* the same event, and the payload carries the id unchanged for the worker.
* <p>The event id is the messaging platform's message id, which is a canonical lower-case UUIDv7;
* the draft refuses anything else, so an operation id a client chose ({@code ~report}, a v4, an
* upper-case spelling) cannot be the event id. The derived id keeps the event deterministic for
* the operation — the same id and submission time always give the same event id — and the payload
* carries the operation id unchanged for the worker. Its time field is the submission time, so it
* orders like a minted one; its other 74 bits are the SHA-256 of the operation id.
*
* <p>It replaced an {@code operation-<sha256>} digest, which fit the stored identity grammar and
* passed the append, and which the bridge then refused, parking the committed event (review
* 06-06, re-review 2026-11-03 RR-05-04).
*/
static String canonicalIdentity(DurableOperationId operationId) {
static String canonicalIdentity(DurableOperationId operationId, Instant submittedAt) {
String value = operationId.value();
if (IntegrationIdentity.isCanonical(value, IntegrationIdentity.EVENT_ID_MAX_LENGTH)) {
if (IntegrationIdentity.isCanonicalUuidV7(value)) {
return value;
}
return "operation-" + Sha256.ofUtf8(value).hex();
byte[] digest = Sha256.ofUtf8(value).bytes();
long millis = submittedAt.toEpochMilli() & 0xFFFF_FFFF_FFFFL;
long randA = ((digest[0] & 0x0FL) << 8) | (digest[1] & 0xFFL);
long mostSignificant = (millis << 16) | (0x7L << 12) | randA;
long randB = 0;
for (int i = 2; i < 10; i++) {
randB = (randB << 8) | (digest[i] & 0xFFL);
}
long leastSignificant = (randB & 0x3FFF_FFFF_FFFF_FFFFL) | 0x8000_0000_0000_0000L;
return new UUID(mostSignificant, leastSignificant).toString();
}
}
@@ -14,7 +14,9 @@ import dev.caskeleton.application.messaging.event.AggregateIdentity;
* version column already counts its writes may use that instead; this port is for the aggregates
* that keep no counter.
*
* <p>Contract, which {@code OutboxAggregateSequenceContract} holds every implementation to:
* <p>Contract, which {@code OutboxAggregateSequenceContract} holds every implementation to (one
* case per item; the reaper and seed half of the second item needs outbox rows and is a PostgreSQL
* case, {@code PostgreSqlOutboxAggregateSequenceIntegrationTest}):
*
* <ul>
* <li>Called inside the caller's write transaction ({@code TransactionPort.inWrite}), the same
@@ -22,8 +24,14 @@ import dev.caskeleton.application.messaging.event.AggregateIdentity;
* a second writer of the same aggregate waits for the first to commit or roll back; a rolled
* back number is handed out again.
* <li>Strictly greater than every number this port returned for the aggregate before, including
* for events the retention reaper has since deleted, and greater than any number an earlier
* outbox row of the aggregate carries.
* for events the retention reaper has since deleted, and greater than any number an outbox
* row of the aggregate carries when the call is made.
* <li>Where an implementation replaced an earlier numbering (the sample's wall clock), greater
* than any number that numbering could have sent for the aggregate — also for rows deleted
* since, or written under an identity that has since changed. The first number is therefore
* not necessarily 1: the JPA counter starts above the moment its migration ran, in epoch
* microseconds (review RR-03-02).
* <li>Two first calls for one aggregate that overlap both succeed, with consecutive numbers.
* <li>Independent per aggregate identity: one aggregate's numbers say nothing about another's.
* </ul>
*/
@@ -1,8 +1,9 @@
package dev.caskeleton.application.outbox;
/**
* Status state machine for a transactional outbox event row. {@code DEAD} blocks its aggregate's
* FIFO siblings until manually resolved. See README for the full transition diagram.
* Status state machine for a transactional outbox event row. {@code DEAD} and {@code PARKED} block
* their aggregate's FIFO siblings until manually resolved. See README for the full transition
* diagram.
*/
public enum OutboxEventStatus {
@@ -25,6 +26,9 @@ public enum OutboxEventStatus {
/**
* Publish failed transiently; {@code next_attempt_at} carries the backoff deadline. The row will
* be re-claimed once {@code now >= next_attempt_at}.
*
* <p>A row that failed for a reason of the moment (deferred, {@link
* OutboxStorePort#markDeferred}) stays here without end; {@code last_failure_code} says why.
*/
FAILED,
@@ -33,5 +37,16 @@ public enum OutboxEventStatus {
* see {@code OperationalError.OUTBOX_DEAD_LETTER}. While a row is DEAD its aggregate's FIFO queue
* is blocked.
*/
DEAD
DEAD,
/**
* Held by an operator: a FAILED row the relay would retry without end, taken out of the retry
* loop while its cause is found ({@code runbook://outbox/publish-failed}, "끝나지 않는 재시도").
*
* <p>No relay transition leads here and none leaves: only the runbook's park and resume SQL do.
* The claim never takes a parked row, and the row still blocks its aggregate's later events, so
* parking stops the retries without letting the aggregate's order slip. Resuming returns it to
* FAILED, due at once; skipping marks it PUBLISHED with the same approval a DEAD skip needs.
*/
PARKED
}
@@ -0,0 +1,24 @@
package dev.caskeleton.application.outbox;
/**
* The outbox rows that have been retrying for a long time ({@link OutboxStorePort#longRetries}).
*
* @param rows how many FAILED rows have collected at least the asked-for number of deferred claims
* @param oldestAgeSeconds the oldest such row's age since it occurred, in seconds; 0 when there is
* none
*/
public record OutboxLongRetries(long rows, long oldestAgeSeconds) {
/** No row is retrying long. */
public static final OutboxLongRetries NONE = new OutboxLongRetries(0, 0);
public OutboxLongRetries {
if (rows < 0 || oldestAgeSeconds < 0) {
throw new IllegalArgumentException(
"rows and oldestAgeSeconds must be >= 0, were " + rows + " and " + oldestAgeSeconds);
}
if (rows == 0 && oldestAgeSeconds != 0) {
throw new IllegalArgumentException("no row has no age, was " + oldestAgeSeconds);
}
}
}
@@ -1,5 +1,8 @@
package dev.caskeleton.application.outbox;
import java.time.Duration;
import java.util.Optional;
/**
* Outbound port for publishing a claimed outbox event to the message broker.
* <strong>Fail-closed</strong>: any publish failure MUST be surfaced by throwing a {@link
@@ -19,7 +22,8 @@ public interface OutboxMessagePublishPort {
void publish(ClaimedOutboxEvent event);
/**
* Publishes and reports what was achieved.
* Publishes and reports what was achieved, and the publisher's code for why when it was not a
* confirmation.
*
* <p>The throwing method above cannot express an ambiguous publish: a broker that accepted the
* frame and never confirmed it is reported the same way as one that refused it outright, and the
@@ -29,11 +33,26 @@ public interface OutboxMessagePublishPort {
* @param event the claimed outbox event
* @return what the attempt achieved
*/
default OutboxPublishOutcome publishForOutcome(ClaimedOutboxEvent event) {
default OutboxPublishAttempt publishForOutcome(ClaimedOutboxEvent event) {
publish(event);
// A method that either returns or throws can only report these two. Reporting CONFIRMED here
// is honest for such an adapter — it is what "returned without throwing" has always meant —
// and an adapter that can tell an ambiguous publish apart overrides this.
return OutboxPublishOutcome.CONFIRMED;
return OutboxPublishAttempt.confirmed();
}
/**
* The longest one publish can take before this port answers, when the port knows it.
*
* <p>The relay holds a whole batch under one lease while it publishes the rows one after another,
* so a batch whose worst case outlasts the lease is reclaimed and sent again by another instance.
* Only the port knows its worst case, so the relay's assembly asks it and refuses a batch size
* that does not fit (review 2026-11-01 06-12). Empty when the port cannot say; the check is then
* skipped, not guessed.
*
* @return the longest attempt, or empty when unknown
*/
default Optional<Duration> longestAttempt() {
return Optional.empty();
}
}
@@ -0,0 +1,103 @@
package dev.caskeleton.application.outbox;
import java.util.Objects;
import java.util.Optional;
import java.util.regex.Pattern;
/**
* What one publish attempt achieved, and — when it did not achieve a confirmation — the publisher's
* code for why.
*
* <p>The outcome decides what the relay does next; the code is for the operator. A refusal for now
* and an unanswered publish are retried without end (review 2026-11-01 README 15), so a row can
* keep failing for a reason no one sees: a credential that is really wrong, a topic policy the
* broker client has no name for. The outcome alone cannot tell those apart — a shutdown, a closed
* transport and a refused credential are all {@link OutboxPublishOutcome#REJECTED_RETRYABLE}. The
* code can, and the relay writes it on the row and into its failure report (re-review 2026-11-03
* RR-05-03).
*
* <p>The code is the publisher's stable, machine-readable name for the failure — a messaging
* platform failure code such as {@code KAFKA_AUTHENTICATIONEXCEPTION} or {@code
* PUBLISH_DEADLINE_EXCEEDED} — never a message: a message can carry an endpoint, a statement or a
* credential, and the row and the log are read by more people than the broker is.
*
* @param outcome what the attempt achieved
* @param failureCode the publisher's code for an attempt that was not confirmed; empty when the
* publisher named none, and always empty for a confirmed attempt
*/
public record OutboxPublishAttempt(OutboxPublishOutcome outcome, Optional<String> failureCode) {
/** The longest code a row keeps: the width of {@code outbox_event.last_failure_code}. */
public static final int FAILURE_CODE_MAX_LENGTH = 120;
/** Letters and digits, then any of {@code . _ : -}: a name, not a sentence. */
private static final Pattern FAILURE_CODE = Pattern.compile("[A-Za-z0-9][A-Za-z0-9._:-]*");
public OutboxPublishAttempt {
Objects.requireNonNull(outcome, "outcome must not be null");
Objects.requireNonNull(failureCode, "failureCode must not be null");
if (outcome == OutboxPublishOutcome.CONFIRMED && failureCode.isPresent()) {
throw new IllegalArgumentException("a confirmed publish has no failure code");
}
failureCode.ifPresent(
code -> {
if (!isFailureCode(code)) {
throw new IllegalArgumentException(
"failureCode must be 1-"
+ FAILURE_CODE_MAX_LENGTH
+ " characters matching "
+ FAILURE_CODE.pattern());
}
});
}
/** A publish the broker acknowledged. */
public static OutboxPublishAttempt confirmed() {
return new OutboxPublishAttempt(OutboxPublishOutcome.CONFIRMED, Optional.empty());
}
/**
* An attempt whose publisher reported only the outcome.
*
* @param outcome what the attempt achieved
* @return the attempt
*/
public static OutboxPublishAttempt of(OutboxPublishOutcome outcome) {
return new OutboxPublishAttempt(outcome, Optional.empty());
}
/**
* An attempt that was not confirmed, with the publisher's code for why.
*
* @param outcome what the attempt achieved; not {@link OutboxPublishOutcome#CONFIRMED}
* @param failureCode the publisher's code, see {@link #isFailureCode}
* @return the attempt
*/
public static OutboxPublishAttempt failed(OutboxPublishOutcome outcome, String failureCode) {
return new OutboxPublishAttempt(outcome, Optional.of(failureCode));
}
/**
* Whether {@code candidate} can be kept as a failure code. A publisher translating a foreign code
* asks first and falls back to a name of its own when the answer is no.
*
* @param candidate the code; {@code null} is not one
* @return true when it is 1-{@value #FAILURE_CODE_MAX_LENGTH} characters of the code grammar
*/
public static boolean isFailureCode(String candidate) {
return candidate != null
&& !candidate.isEmpty()
&& candidate.length() <= FAILURE_CODE_MAX_LENGTH
&& FAILURE_CODE.matcher(candidate).matches();
}
/**
* The code the relay records for this attempt: the publisher's, or the outcome's own name when
* the publisher gave none.
*
* @return a code that is never empty
*/
public String recordedFailureCode() {
return failureCode.orElse(outcome.name());
}
}
@@ -12,12 +12,14 @@ package dev.caskeleton.application.outbox;
* two outbox models is real:
*
* <ul>
* <li>the legacy {@code OutboxEventStatus.FAILED} is <em>retryable</em> and {@code DEAD} is
* terminal;
* <li>the platform's {@code OutboxStatus.FAILED} is a <em>definite rejection</em> and terminal,
* while {@code AMBIGUOUS} is the retryable one.
* <li>this application's {@code OutboxEventStatus.FAILED} ({@code outbox_event}) is
* <em>retryable</em> and {@code DEAD} is terminal;
* <li>the vendored platform's {@code OutboxStatus.FAILED} ({@code messaging_outbox}) is a
* <em>definite rejection</em> and terminal, while {@code AMBIGUOUS} is the retryable one.
* </ul>
*
* <p>The full correspondence is one table, at the head of {@code docs/messaging/outbox-inbox.md}.
*
* <p>Mapping those by name inverts both meanings: a definitely-rejected message would be retried
* forever and an unknown one would be parked. This type exists so no bridge is ever tempted to map
* enum names.
@@ -43,7 +45,7 @@ public enum OutboxPublishOutcome {
* Refused before anything was transmitted — validation, routing, an unknown destination.
*
* <p>Definite: nothing was stored anywhere, so a retry of the same payload fails the same way.
* This is what the legacy model calls {@code DEAD}, not what it calls {@code FAILED}.
* This is what this application's outbox calls {@code DEAD}, not what it calls {@code FAILED}.
*/
REJECTED_BEFORE_SEND,
@@ -17,6 +17,12 @@ import java.util.Objects;
* survives is the exception's class name and, when the exception carries a platform code, that one:
* enough to group failures and route a runbook, and nothing that is business content. The bounded
* code is {@link #code()}, which this allowlist already owned.
*
* <p>{@link #failureCode()} is the code the row records for the failure ({@code
* last_failure_code}): the publisher's own name for a refusal or an unanswered publish, or the
* outcome or exception type when it gave none. The cause type of a returned outcome is one of this
* package's carrier exceptions and says only which outcome it was; the failure code is what tells a
* refused credential from a closed transport (re-review 2026-11-03 RR-05-03).
*/
public record OutboxRelayFailureReport(
OperationalError code,
@@ -26,7 +32,8 @@ public record OutboxRelayFailureReport(
String correlationId,
int attemptCount,
Instant nextAttemptAt,
String causeType) {
String causeType,
String failureCode) {
public OutboxRelayFailureReport {
Objects.requireNonNull(code, "code must not be null");
@@ -35,6 +42,9 @@ public record OutboxRelayFailureReport(
requireNonBlank(aggregateId, "aggregateId");
requireNonBlank(correlationId, "correlationId");
requireNonBlank(causeType, "causeType");
if (!OutboxPublishAttempt.isFailureCode(failureCode)) {
throw new IllegalArgumentException("failureCode must be a bounded failure code");
}
if (attemptCount < 1) {
throw new IllegalArgumentException("attemptCount must be >= 1, was " + attemptCount);
}
@@ -58,7 +68,8 @@ public record OutboxRelayFailureReport(
String correlationId,
int attemptCount,
Instant nextAttemptAt,
RuntimeException cause) {
RuntimeException cause,
String failureCode) {
return new OutboxRelayFailureReport(
OperationalError.OUTBOX_PUBLISH_FAILED,
eventId,
@@ -67,7 +78,8 @@ public record OutboxRelayFailureReport(
correlationId,
attemptCount,
nextAttemptAt,
causeTypeOf(cause));
causeTypeOf(cause),
failureCode);
}
public static OutboxRelayFailureReport deadLetter(
@@ -76,7 +88,8 @@ public record OutboxRelayFailureReport(
String aggregateId,
String correlationId,
int attemptCount,
RuntimeException cause) {
RuntimeException cause,
String failureCode) {
return new OutboxRelayFailureReport(
OperationalError.OUTBOX_DEAD_LETTER,
eventId,
@@ -85,7 +98,8 @@ public record OutboxRelayFailureReport(
correlationId,
attemptCount,
null,
causeTypeOf(cause));
causeTypeOf(cause),
failureCode);
}
/**
@@ -5,8 +5,9 @@ import java.util.Objects;
/**
* Result returned by {@link PublishPendingOutboxEventsUseCase} after one relay cycle: the number of
* events claimed and a per-event {@link Outcome} list. See README for why {@code Outcome} is a
* separate 3-value enum rather than reusing {@link OutboxEventStatus}.
* events claimed and a per-event {@link Outcome} list. {@code Outcome} is the cycle's result, not a
* row status, which is why it does not reuse {@link OutboxEventStatus}: a row is never left {@code
* STALE} or {@code RELEASED}, and no cycle ends {@code IN_FLIGHT} or {@code PARKED}.
*
* @param claimedCount total number of events claimed from the store in this cycle
* @param outcomes per-event outcomes in the order they were processed
@@ -47,20 +48,21 @@ public record OutboxRelayResult(int claimedCount, List<EventOutcome> outcomes) {
/**
* Per-event relay cycle outcome.
*
* <p>Three values mirror the three terminal states reachable in a single relay cycle: broker ack
* ({@link #PUBLISHED}), transient failure below the retry cap ({@link #FAILED}), or retry cap
* exhausted ({@link #DEAD}). The fourth, {@link #STALE}, records a result this relay was no
* longer allowed to write.
* <p>Three values are the row transitions a cycle writes: broker ack ({@link #PUBLISHED}), a
* failure that will be retried ({@link #FAILED}), or one that will not ({@link #DEAD}). {@link
* #STALE} records a result this relay was no longer allowed to write, and {@link #RELEASED} a
* claim a stopping relay gave back unused. The counter {@code outbox.publisher.published.total}
* carries exactly these five as its {@code outcome} label.
*/
public enum Outcome {
/** Broker acknowledged the publish; row transitions to PUBLISHED. */
PUBLISHED,
/** Publish failed transiently; row transitions to FAILED with a backoff window. */
/** Publish failed and will be retried; row transitions to FAILED with a backoff window. */
FAILED,
/** All retry attempts exhausted; row transitions to DEAD. */
/** Refused for good, or the attempt budget is spent; row transitions to DEAD. */
DEAD,
/**
@@ -7,11 +7,12 @@ import java.util.Map;
/**
* Outbound port for relay-side access to the outbox store. All mutating operations ({@link
* #claimBatch}, {@link #markPublished}, {@link #markFailed}, {@link #markDead}) must be called
* inside a {@code TransactionPort.inWrite(...)} boundary owned by the relay; implementations must
* not open their own transaction. A completion applies only while the relay's {@link OutboxLease}
* still holds the row, so a relay that stalled past its claim cannot overwrite the relay that took
* the row over. See README for the claim/FIFO/in-flight-timeout/lease semantics.
* #claimBatch}, {@link #markPublished}, {@link #markFailed}, {@link #markDeferred}, {@link
* #releaseLease}, {@link #markDead}) must be called inside a {@code TransactionPort.inWrite(...)}
* boundary owned by the relay; implementations must not open their own transaction. A completion
* applies only while the relay's {@link OutboxLease} still holds the row, so a relay that stalled
* past its claim cannot overwrite the relay that took the row over. See README for the
* claim/FIFO/in-flight-timeout/lease semantics.
*/
public interface OutboxStorePort {
@@ -47,9 +48,11 @@ public interface OutboxStorePort {
*
* @param lease the claim this relay holds
* @param nextAttemptAt the earliest instant at which the event may be re-claimed
* @param failureCode why the attempt failed, kept on the row for the operator (see {@link
* OutboxPublishAttempt}); never a message
* @return {@link OutboxCompletion#STALE}, writing nothing, when the lease no longer holds the row
*/
OutboxCompletion markFailed(OutboxLease lease, Instant nextAttemptAt);
OutboxCompletion markFailed(OutboxLease lease, Instant nextAttemptAt, String failureCode);
/**
* Marks the leased event as failed for a reason that belongs to the moment — the broker did not
@@ -59,11 +62,16 @@ public interface OutboxStorePort {
* ClaimedOutboxEvent#budgetedAttemptCount()}). Must be called inside {@code
* TransactionPort.inWrite(...)}.
*
* <p>A deferred row is retried without end, so its failure code is what tells an operator a row
* that waits out an outage from one the broker will never take — a credential that is really
* wrong, a topic policy the broker client has no name for (re-review 2026-11-03 RR-05-03).
*
* @param lease the claim this relay holds
* @param nextAttemptAt the earliest instant at which the event may be re-claimed
* @param failureCode the publisher's code for the refusal or the unanswered publish
* @return {@link OutboxCompletion#STALE}, writing nothing, when the lease no longer holds the row
*/
OutboxCompletion markDeferred(OutboxLease lease, Instant nextAttemptAt);
OutboxCompletion markDeferred(OutboxLease lease, Instant nextAttemptAt, String failureCode);
/**
* Gives a claimed row back without having tried to publish it: the row is claimable again from
@@ -84,9 +92,11 @@ public interface OutboxStorePort {
* manually resolved (see README).
*
* @param lease the claim this relay holds
* @param failureCode why the row was dead-lettered: the refusal's code, or the type of the last
* unclassified failure
* @return {@link OutboxCompletion#STALE}, writing nothing, when the lease no longer holds the row
*/
OutboxCompletion markDead(OutboxLease lease);
OutboxCompletion markDead(OutboxLease lease, String failureCode);
/**
* Returns a count of unpublished rows grouped by {@link OutboxEventStatus} — gauge source for the
@@ -107,4 +117,21 @@ public interface OutboxStorePort {
* @return map from event type to oldest-unpublished-row age in seconds; absent when none
*/
Map<String, Long> oldestUnpublishedAgeSecondsByEventType(Instant now);
/**
* The rows that have been retrying for a long time — FAILED, with at least {@code
* minDeferredClaims} claims deferred — counted, with the age of the oldest. Gauge source for
* {@code outbox.retry.long.size} and {@code outbox.retry.long.age}. Called outside a transaction
* (read-only).
*
* <p>Deferred claims are the ones that do not spend the attempt budget, so they are also the ones
* with no end: a row that keeps collecting them is retried until someone looks. Counting them is
* how someone is told to look (re-review 2026-11-03 RR-05-03).
*
* @param minDeferredClaims how many deferred claims make a row long-retrying; at least 1
* @param now current wall-clock time used to compute age
* @return the count and the oldest row's age since it occurred; {@link OutboxLongRetries#NONE}
* when no row qualifies
*/
OutboxLongRetries longRetries(int minDeferredClaims, Instant now);
}
@@ -43,6 +43,9 @@ import java.util.function.Supplier;
public final class PublishPendingOutboxEventsUseCase
implements CommandUseCase<PublishPendingOutboxEventsCommand, OutboxRelayResult> {
/** The failure code of a thrown failure whose type has no simple name. */
static final String UNNAMED_FAILURE = "UNNAMED_EXCEPTION";
private final OutboxStorePort store;
private final OutboxMessagePublishPort publishPort;
private final OutboxRelayFailureReportPort failureReporter;
@@ -168,34 +171,56 @@ public final class PublishPendingOutboxEventsUseCase
*/
private OutboxRelayResult.Outcome publishOne(OutboxLease lease) {
ClaimedOutboxEvent event = lease.event();
OutboxPublishOutcome achieved;
OutboxPublishAttempt attempt;
try {
// The outcome-valued call, not the throwing one. An adapter that cannot tell an ambiguous
// publish apart still throws and is handled below exactly as before; one that can no longer
// has to pretend a message it may have stored was definitely not stored.
achieved = publishPort.publishForOutcome(event);
attempt = publishPort.publishForOutcome(event);
} catch (RuntimeException publishEx) {
// Publish failure: drive FAILED/DEAD state machine + typed report; do NOT rethrow.
return handlePublishFailure(lease, clock.instant(), publishEx);
}
OutboxPublishOutcome achieved = attempt.outcome();
if (achieved == OutboxPublishOutcome.AMBIGUOUS) {
// The message left this process and no acknowledgement arrived, so it may be stored. Treated
// as retryable and reported as such: the duplicate risk is the caller's to bound with an
// idempotency key, and the alternative — parking it — loses a message that was delivered.
// It does not spend the attempt budget: a broker that stopped answering fails every row this
// way, and parking them after three tries is what turned a short outage into DEAD rows.
return retryLater(lease, clock.instant(), new OutboxPublishAmbiguousException(), false);
//
// The same branch has no end for a refusal the broker client could not name. The Kafka
// adapter classifies a failure it does not recognise as ambiguous, so a record the broker
// will never take — a topic timestamp policy, a topic that does not exist — is retried here
// five minutes apart for as long as nobody looks, and its aggregate waits behind it. That is
// the price of not parking a delivered message, and it is paid in the open: the publisher's
// code is written on the row, outbox.retry.long.size counts the row once it has been deferred
// long enough, and the publish-failed runbook parks it (re-review 2026-11-03 RR-05-03).
return retryLater(
lease,
clock.instant(),
new OutboxPublishAmbiguousException(),
attempt.recordedFailureCode(),
false);
}
if (achieved == OutboxPublishOutcome.REJECTED_RETRYABLE) {
// Refused for a reason that is about the moment — shutdown, saturation, a closed transport,
// a credential being rotated — not about the message. Retried like an ambiguous outcome and
// for the same reason; the cause says it was a refusal, so no duplicate is suspected.
return retryLater(lease, clock.instant(), new OutboxPublishRefusedException(achieved), false);
// for the same reason; the cause says it was a refusal, so no duplicate is suspected. A
// credential that is really wrong ends up here too, for ever; the failure code is what tells
// it from a rotation.
return retryLater(
lease,
clock.instant(),
new OutboxPublishRefusedException(achieved),
attempt.recordedFailureCode(),
false);
}
if (achieved != OutboxPublishOutcome.CONFIRMED) {
// Definite refusal. Retrying the same payload fails the same way, so the attempt budget is
// not spent on it; the row is dead-lettered now rather than after the timer runs out.
return deadLetter(lease, new OutboxPublishRefusedException(achieved));
return deadLetter(
lease, new OutboxPublishRefusedException(achieved), attempt.recordedFailureCode());
}
// markPublished failure (if any) propagates: the row stays IN_FLIGHT and is
// recovered via the orphan visibility-timeout reclaim path.
@@ -220,11 +245,22 @@ public final class PublishPendingOutboxEventsUseCase
*/
private OutboxRelayResult.Outcome handlePublishFailure(
OutboxLease lease, Instant failedAt, RuntimeException cause) {
String failureCode = failureCodeOf(cause);
if (lease.event().budgetedAttemptCount() >= backoffPolicy.maxAttempts()) {
// All attempts exhausted — DEAD-letter the event.
return deadLetter(lease, cause);
return deadLetter(lease, cause, failureCode);
}
return retryLater(lease, failedAt, cause, true);
return retryLater(lease, failedAt, cause, failureCode, true);
}
/**
* The code a thrown failure is recorded under: its type's simple name, which is a type and not
* content. A type with no usable name — an anonymous class — is recorded as {@value
* #UNNAMED_FAILURE}.
*/
private static String failureCodeOf(RuntimeException cause) {
String name = cause.getClass().getSimpleName();
return OutboxPublishAttempt.isFailureCode(name) ? name : UNNAMED_FAILURE;
}
/**
@@ -234,15 +270,19 @@ public final class PublishPendingOutboxEventsUseCase
* only a {@code budgeted} failure is recorded as spending the budget.
*/
private OutboxRelayResult.Outcome retryLater(
OutboxLease lease, Instant failedAt, RuntimeException cause, boolean budgeted) {
OutboxLease lease,
Instant failedAt,
RuntimeException cause,
String failureCode,
boolean budgeted) {
ClaimedOutboxEvent event = lease.event();
Instant nextAttemptAt = backoffPolicy.nextAttemptAt(event.attemptCount(), failedAt);
OutboxCompletion completion =
tx.inWrite(
() ->
budgeted
? store.markFailed(lease, nextAttemptAt)
: store.markDeferred(lease, nextAttemptAt));
? store.markFailed(lease, nextAttemptAt, failureCode)
: store.markDeferred(lease, nextAttemptAt, failureCode));
if (completion == OutboxCompletion.STALE) {
return stale(lease, OutboxRelayResult.Outcome.FAILED);
}
@@ -255,13 +295,15 @@ public final class PublishPendingOutboxEventsUseCase
event.correlationId(),
event.attemptCount(),
nextAttemptAt,
cause));
cause,
failureCode));
return OutboxRelayResult.Outcome.FAILED;
}
private OutboxRelayResult.Outcome deadLetter(OutboxLease lease, RuntimeException cause) {
private OutboxRelayResult.Outcome deadLetter(
OutboxLease lease, RuntimeException cause, String failureCode) {
ClaimedOutboxEvent event = lease.event();
if (tx.inWrite(() -> store.markDead(lease)) == OutboxCompletion.STALE) {
if (tx.inWrite(() -> store.markDead(lease, failureCode)) == OutboxCompletion.STALE) {
return stale(lease, OutboxRelayResult.Outcome.DEAD);
}
reportFailure(
@@ -272,7 +314,8 @@ public final class PublishPendingOutboxEventsUseCase
event.aggregateId(),
event.correlationId(),
event.attemptCount(),
cause));
cause,
failureCode));
return OutboxRelayResult.Outcome.DEAD;
}
@@ -16,8 +16,13 @@ import java.lang.annotation.Target;
* architecture rule that otherwise requires a permission on every {@code WRITE_REPOSITORY} use case
* accepts it in place of one.
*
* <p>A use case marked this way must not become a Spring bean that a transport can reach; the
* composition that runs it constructs it directly.
* <p>A use case marked this way is a write with no permission check, so a transport must never
* reach it. The composition that runs it constructs it directly and hands it to its system caller.
* Both ways a transport could reach it are refused: a bean of it fails startup ({@code
* composition:service-runtime} {@code PermissionEnforcementGuard}), and an inbound adapter that
* depends on it fails the architecture rule {@code
* INBOUND_ADAPTERS_DO_NOT_REACH_SYSTEM_INVOKED_USE_CASES}. It is not a way to silence the rule that
* a mutating use case declares a permission: a write a user triggers declares one.
*/
@Documented
@Retention(RetentionPolicy.RUNTIME)
@@ -5,6 +5,7 @@ import static org.assertj.core.api.Assertions.assertThatThrownBy;
import static org.assertj.core.api.Assertions.catchThrowable;
import dev.caskeleton.application.transaction.OperationId;
import dev.caskeleton.shared.error.ApiErrorCarrier;
import java.time.Duration;
import java.time.Instant;
import java.util.Optional;
@@ -156,6 +157,94 @@ class IdempotencyExecutorTest {
assertThat(store.completeCalls).isEqualTo(1);
}
@Test
@DisplayName("claim 단계에서 저장소가 응답하지 않으면 action 을 돌리지 않고 실행 전 거부(IDEMPOTENCY_UNAVAILABLE)로 알린다")
void anUnavailableClaimIsARefusalBeforeTheActionRuns() {
// given
FakeStore store = new FakeStore();
store.claim = new IdempotencyClaimOutcome.Unavailable();
AtomicBoolean ran = new AtomicBoolean();
// when
Throwable thrown =
catchThrowable(
() ->
executor(store)
.execute(
SCOPE,
FINGERPRINT,
ATTEMPT,
() -> {
ran.set(true);
return new IdempotentAction.Outcome.Success<>("created");
},
codec()));
// then
assertThat(errorCodeOf(thrown)).isEqualTo("IDEMPOTENCY_UNAVAILABLE");
assertThat(ran).isFalse();
}
/**
* The action already ran when completion fails, so "refused before the action" would be false.
* Effects in the action's own transaction roll back with the exception; anything else it did has
* happened. The client must hear "outcome unknown" and resend with the same key, never "not
* applied" (re-review 2026-11-03 decision, RR-02-03).
*/
@Test
@DisplayName(
"action 뒤 complete 에서 저장소가 응답하지 않으면 실행 전 거부가 아니라 결과 불명(IDEMPOTENCY_COMPLETION_UNKNOWN)이다")
void anUnavailableCompletionAfterTheActionRanIsAnUnknownOutcome() {
// given
FakeStore store = startedStore();
store.complete = IdempotencyCompleteOutcome.UNAVAILABLE;
AtomicBoolean ran = new AtomicBoolean();
// when
Throwable thrown =
catchThrowable(
() ->
executor(store)
.execute(
SCOPE,
FINGERPRINT,
ATTEMPT,
() -> {
ran.set(true);
return new IdempotentAction.Outcome.Success<>("created");
},
codec()));
// then
assertThat(ran).isTrue();
assertThat(errorCodeOf(thrown)).isEqualTo("IDEMPOTENCY_COMPLETION_UNKNOWN");
}
@Test
@DisplayName("응답을 잃은 complete 를 확인하려는데 저장소가 응답하지 않아도 결과 불명(IDEMPOTENCY_COMPLETION_UNKNOWN)이다")
void anUnavailableInspectionOfALostCompletionIsAnUnknownOutcome() {
// given
FakeStore store = startedStore();
store.complete = IdempotencyCompleteOutcome.INDETERMINATE;
store.inspectionAfterComplete =
IdempotencyInspection.outcome(IdempotencyInspectionOutcome.UNAVAILABLE);
// when
Throwable thrown =
catchThrowable(
() ->
executor(store)
.execute(
SCOPE,
FINGERPRINT,
ATTEMPT,
() -> new IdempotentAction.Outcome.Success<>("created"),
codec()));
// then
assertThat(errorCodeOf(thrown)).isEqualTo("IDEMPOTENCY_COMPLETION_UNKNOWN");
}
@Test
@DisplayName("a replayed response that disagrees with this caller's is a recovery, not a result")
void aConflictingReplayIsNotReturned() {
@@ -282,6 +371,11 @@ class IdempotencyExecutorTest {
return store;
}
private static String errorCodeOf(Throwable thrown) {
assertThat(thrown).isInstanceOf(ApiErrorCarrier.class);
return ((ApiErrorCarrier) thrown).errorCode().code();
}
private static IdempotencyExecutor executor(FakeStore store) {
return new IdempotencyExecutor(
store, Duration.ofSeconds(30), Duration.ofHours(1), Duration.ofHours(1), "json-v2", 1);
@@ -21,6 +21,9 @@ class IdempotencyFailureCodeTest {
OperationalError.IDEMPOTENT_REQUEST_MISMATCH),
Arguments.of(
new IdempotencyUnavailableException(), OperationalError.IDEMPOTENCY_UNAVAILABLE),
Arguments.of(
new IdempotencyCompletionUnknownException(),
OperationalError.IDEMPOTENCY_COMPLETION_UNKNOWN),
Arguments.of(
new IdempotencyRecoveryRequiredException("outcome unknown"),
OperationalError.IDEMPOTENCY_RECOVERY_REQUIRED));
@@ -0,0 +1,18 @@
package dev.caskeleton.application.messaging.contract;
import dev.caskeleton.application.messaging.contract.testkit.ReleasedPayloadSchemaContract;
import java.nio.file.Path;
/** The payload schemas application-core publishes ({@code durable-operation.submitted}). */
class ApplicationPayloadSchemaReleaseTest extends ReleasedPayloadSchemaContract {
@Override
protected Path schemaRoot() {
return Path.of("src/main/resources/contracts/messaging");
}
@Override
protected Path manifest() {
return Path.of("src/test/resources/contracts/released-payload-schemas.sha256");
}
}
@@ -2,16 +2,83 @@ package dev.caskeleton.application.messaging.event;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import static org.assertj.core.api.Assertions.catchThrowable;
import dev.caskeleton.application.messaging.contract.ContractId;
import dev.caskeleton.application.messaging.contract.IntegrationPayload;
import dev.caskeleton.application.messaging.contract.LogicalDestinationId;
import java.time.Instant;
import java.util.Optional;
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;
class IntegrationEventDraftTest {
/** A canonical lower-case UUIDv7: the only spelling the messaging platform carries. */
private static final String EVENT_ID = "01994e11-4d88-7000-8000-0000000000e1";
private static final String CAUSATION_ID = "01994e11-4d88-7000-8000-0000000000c1";
/**
* The bridge sends an event under its id as the platform's {@code MessageId}, a canonical
* lower-case UUIDv7, and refuses any other — after the business transaction committed, as a DEAD
* row that blocks the aggregate. A draft is where such an id is refused first, in the writer's
* transaction (review 06-06, re-review 2026-11-03 RR-05-04).
*/
@ParameterizedTest
@ValueSource(
strings = {
"event-1",
"01994E11-4D88-7000-8000-0000000000E1",
"6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b",
"1-2-3-4-5"
})
@DisplayName("정규 소문자 UUIDv7이 아닌 event id로는 draft를 만들지 않는다")
void aDraftRefusesAnEventIdThatIsNotACanonicalUuidV7(String eventId) {
// given
EventId id = new EventId(eventId);
// when
Throwable thrown = catchThrowable(() -> draftWithIds(id, Optional.empty()));
// then
assertThat(thrown)
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("eventId must be a canonical lower-case UUIDv7");
}
@Test
@DisplayName("정규 소문자 UUIDv7이 아닌 causation id로는 draft를 만들지 않는다")
void aDraftRefusesACausationIdThatIsNotACanonicalUuidV7() {
// given
Optional<String> causation = Optional.of("cause-1");
// when
Throwable thrown = catchThrowable(() -> draftWithIds(new EventId(EVENT_ID), causation));
// then
assertThat(thrown)
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("causationId must be a canonical lower-case UUIDv7");
}
private static IntegrationEventDraft<TestPayload> draftWithIds(
EventId eventId, Optional<String> causationId) {
return new IntegrationEventDraft<>(
eventId,
new ContractId("portfolio.worklog.reserved"),
1,
new LogicalDestinationId("portfolio-domain-events"),
new AggregateIdentity("tenant-a", "worklog", "worklog-42"),
new AggregateOrder(17, 0),
Instant.parse("2026-07-28T05:10:30.123Z"),
"corr-1",
causationId,
new TestPayload("worklog-42"));
}
@Test
void eventIdAcceptsOnlyBoundedCanonicalUsAscii() {
assertThat(new EventId("A0:event.id-1").value()).isEqualTo("A0:event.id-1");
@@ -53,14 +120,14 @@ class IntegrationEventDraftTest {
@Test
void draftRequiresPositiveVersionTimeCanonicalCorrelationAndTypedPayload() {
TestPayload payload = new TestPayload("worklog-42");
IntegrationEventDraft<TestPayload> draft = draft(payload, Optional.of("cause-1"));
IntegrationEventDraft<TestPayload> draft = draft(payload, Optional.of(CAUSATION_ID));
assertThat(draft.featurePayload()).isSameAs(payload);
assertThat(draft.occurredAt()).isEqualTo(Instant.parse("2026-07-28T05:10:30.123Z"));
assertThatThrownBy(
() ->
new IntegrationEventDraft<>(
new EventId("event-1"),
new EventId(EVENT_ID),
new ContractId("portfolio.worklog.reserved"),
0,
new LogicalDestinationId("portfolio-domain-events"),
@@ -74,7 +141,7 @@ class IntegrationEventDraftTest {
assertThatThrownBy(
() ->
new IntegrationEventDraft<>(
new EventId("event-1"),
new EventId(EVENT_ID),
new ContractId("portfolio.worklog.reserved"),
1,
new LogicalDestinationId("portfolio-domain-events"),
@@ -103,7 +170,7 @@ class IntegrationEventDraftTest {
private static IntegrationEventDraft<TestPayload> draft(
TestPayload payload, Optional<String> causationId) {
return new IntegrationEventDraft<>(
new EventId("event-1"),
new EventId(EVENT_ID),
new ContractId("portfolio.worklog.reserved"),
1,
new LogicalDestinationId("portfolio-domain-events"),
@@ -13,7 +13,7 @@ import org.junit.jupiter.params.provider.ValueSource;
class IntegrationEventDraftsTest {
private static final EventId EVENT_ID = new EventId("event-1");
private static final EventId EVENT_ID = new EventId("01994e11-4d88-7000-8000-0000000000e1");
private static final Instant OCCURRED_AT = Instant.parse("2026-11-01T00:00:00.000001Z");
private static final AggregateIdentity AGGREGATE =
new AggregateIdentity(IntegrationEventDrafts.SINGLE_TENANT_SCOPE, "kit", "kit-1");
@@ -74,7 +74,7 @@ class IntegrationIdentityTest {
private static IntegrationEventDraft<TestPayload> draftWithCorrelation(String correlationId) {
return new IntegrationEventDraft<>(
new EventId("event-1"),
new EventId("01994e11-4d88-7000-8000-0000000000e1"),
new ContractId("portfolio.worklog.reserved"),
1,
new LogicalDestinationId("portfolio-domain-events"),
@@ -4,6 +4,7 @@ import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.application.idempotency.RequestFingerprint;
import dev.caskeleton.application.messaging.event.IntegrationIdentity;
import dev.caskeleton.application.messaging.event.ValidatedIntegrationEvent;
import dev.caskeleton.application.messaging.event.testkit.FakeIntegrationEventEncoder;
import dev.caskeleton.application.operation.testkit.InMemoryDurableOperationStore;
@@ -18,6 +19,8 @@ import java.time.ZoneOffset;
import java.util.List;
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;
/**
* The two writes that must not come apart.
@@ -30,7 +33,11 @@ import org.junit.jupiter.api.Test;
class SubmitDurableOperationUseCaseTest {
private static final Instant NOW = Instant.parse("2026-08-25T10:00:00Z");
private static final DurableOperationId ID = new DurableOperationId("op-1");
/** An id the HTTP adapter mints: a canonical lower-case UUIDv7, used as the event id itself. */
private static final String OPERATION_UUID = "01994e11-4d88-7000-8000-0000000000a1";
private static final DurableOperationId ID = new DurableOperationId(OPERATION_UUID);
// Both stores join the in-memory port's transactions and undo their writes when one rolls back,
// as the database does. A port that simply ran the action would let rollbackLeavesNothing pass
@@ -151,8 +158,8 @@ class SubmitDurableOperationUseCaseTest {
e -> e.contractId(),
e -> e.logicalDestinationId())
.containsExactly(
"op-1",
"op-1",
OPERATION_UUID,
OPERATION_UUID,
DurableOperationSubmittedContract.CONTRACT_ID,
DurableOperationSubmittedContract.DESTINATION);
}
@@ -166,21 +173,46 @@ class SubmitDurableOperationUseCaseTest {
// The worker reads what to run from the submission it claims; the request never travels.
assertThat(encoder.drafts())
.<Object>extracting(draft -> draft.featurePayload())
.containsExactly(new DurableOperationSubmitted("op-1", "reports.generate"));
.containsExactly(new DurableOperationSubmitted(OPERATION_UUID, "reports.generate"));
}
/**
* An event id is the platform's message id, a canonical lower-case UUIDv7, or the bridge parks
* the event after the operation committed. An operation id that is anything else — a client's own
* id, {@code ~} included — becomes a UUIDv7 derived from it and the submission time: the same
* operation always gets the same event id (review 06-06, re-review 2026-11-03 RR-05-04).
*/
@ParameterizedTest
@ValueSource(strings = {"~report", "op-1", "01994E11-4D88-7000-8000-0000000000A1"})
@DisplayName("UUIDv7이 아닌 operation id는 그 id에서 만든 같은 UUIDv7 event id가 된다")
void anOperationIdThatIsNotAUuidV7BecomesAStableUuidV7DerivedFromIt(String operationId) {
// given
DurableOperationId id = new DurableOperationId(operationId);
// when
String identity = SubmitDurableOperationUseCase.canonicalIdentity(id, NOW);
// then
assertThat(List.of(identity, SubmitDurableOperationUseCase.canonicalIdentity(id, NOW)))
.allMatch(IntegrationIdentity::isCanonicalUuidV7)
.containsOnly(identity)
.doesNotContain(operationId);
}
@Test
void anOperationIdOutsideTheEventIdGrammarBecomesAStableDigestIdentity() {
@DisplayName("UUIDv7이 아닌 operation id로 받은 작업도 outbox에 발행할 수 있는 event로 남는다")
void aSubmissionUnderAClientChosenIdStillAppendsAPublishableEvent() {
// given
DurableOperationId tilde = new DurableOperationId("~report");
DurableOperationId clientChosen = new DurableOperationId("~report");
// when
String identity = SubmitDurableOperationUseCase.canonicalIdentity(tilde);
useCase.handle(command(clientChosen, "c".repeat(64)));
// then
assertThat(List.of(identity, SubmitDurableOperationUseCase.canonicalIdentity(tilde)))
.allMatch(value -> value.matches("operation-[0-9a-f]{64}"))
.containsOnly(identity);
assertThat(outbox.appended())
.singleElement()
.extracting(event -> event.eventId().value())
.matches(IntegrationIdentity::isCanonicalUuidV7);
}
/** The in-memory outbox, failing its next append when told to. */
@@ -72,6 +72,6 @@ class OutboxPublishOutcomeTest {
assertThat(legacy.publishForOutcome(null))
.as("'returned without throwing' has always meant confirmed for such an adapter")
.isEqualTo(OutboxPublishOutcome.CONFIRMED);
.isEqualTo(OutboxPublishAttempt.confirmed());
}
}
@@ -7,12 +7,14 @@ import dev.caskeleton.shared.error.OperationalError;
import java.lang.reflect.RecordComponent;
import java.time.Instant;
import java.util.Arrays;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
class OutboxRelayFailureReportTest {
private static final Instant NEXT_ATTEMPT_AT = Instant.parse("2026-07-25T01:02:03Z");
private static final RuntimeException CAUSE = new RuntimeException("broker unavailable");
private static final String CODE = "KAFKA_TIMEOUTEXCEPTION";
@Test
void recordComponentsAreAnExactSafeAllowlist() {
@@ -29,14 +31,16 @@ class OutboxRelayFailureReportTest {
"nextAttemptAt",
// Not "cause": a Throwable component is a Throwable in the operational JSON, and the
// allowlist that guards every other field had no say over its message or stack.
"causeType");
"causeType",
// A bounded code, never a message (re-review 2026-11-03 RR-05-03).
"failureCode");
}
@Test
void retryableFailureFactoryCreatesPublishFailedReport() {
OutboxRelayFailureReport report =
OutboxRelayFailureReport.retryableFailure(
"evt-1", "WorkLogReserved", "agg-1", "corr-1", 2, NEXT_ATTEMPT_AT, CAUSE);
"evt-1", "WorkLogReserved", "agg-1", "corr-1", 2, NEXT_ATTEMPT_AT, CAUSE, CODE);
assertThat(report.code()).isEqualTo(OperationalError.OUTBOX_PUBLISH_FAILED);
assertThat(report.eventId()).isEqualTo("evt-1");
@@ -54,7 +58,7 @@ class OutboxRelayFailureReportTest {
void deadLetterFactoryCreatesTerminalReportWithoutRetryTime() {
OutboxRelayFailureReport report =
OutboxRelayFailureReport.deadLetter(
"evt-1", "WorkLogReserved", "agg-1", "corr-1", 3, CAUSE);
"evt-1", "WorkLogReserved", "agg-1", "corr-1", 3, CAUSE, CODE);
assertThat(report.code()).isEqualTo(OperationalError.OUTBOX_DEAD_LETTER);
assertThat(report.nextAttemptAt()).isNull();
@@ -75,7 +79,8 @@ class OutboxRelayFailureReportTest {
"corr-1",
1,
null,
CAUSE.getClass().getName()))
CAUSE.getClass().getName(),
CODE))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("code");
}
@@ -83,19 +88,26 @@ class OutboxRelayFailureReportTest {
@Test
void rejectsBlankIdentifiersAndEventType() {
assertThatThrownBy(
() -> OutboxRelayFailureReport.deadLetter(" ", "Event", "agg-1", "corr-1", 1, CAUSE))
() ->
OutboxRelayFailureReport.deadLetter(
" ", "Event", "agg-1", "corr-1", 1, CAUSE, CODE))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("eventId");
assertThatThrownBy(
() -> OutboxRelayFailureReport.deadLetter("evt-1", "", "agg-1", "corr-1", 1, CAUSE))
() ->
OutboxRelayFailureReport.deadLetter("evt-1", "", "agg-1", "corr-1", 1, CAUSE, CODE))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("eventType");
assertThatThrownBy(
() -> OutboxRelayFailureReport.deadLetter("evt-1", "Event", "\t", "corr-1", 1, CAUSE))
() ->
OutboxRelayFailureReport.deadLetter(
"evt-1", "Event", "\t", "corr-1", 1, CAUSE, CODE))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("aggregateId");
assertThatThrownBy(
() -> OutboxRelayFailureReport.deadLetter("evt-1", "Event", "agg-1", "\n", 1, CAUSE))
() ->
OutboxRelayFailureReport.deadLetter(
"evt-1", "Event", "agg-1", "\n", 1, CAUSE, CODE))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("correlationId");
}
@@ -104,7 +116,8 @@ class OutboxRelayFailureReportTest {
void rejectsAttemptCountBelowOne() {
assertThatThrownBy(
() ->
OutboxRelayFailureReport.deadLetter("evt-1", "Event", "agg-1", "corr-1", 0, CAUSE))
OutboxRelayFailureReport.deadLetter(
"evt-1", "Event", "agg-1", "corr-1", 0, CAUSE, CODE))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("attemptCount");
}
@@ -121,7 +134,8 @@ class OutboxRelayFailureReportTest {
"corr-1",
1,
null,
CAUSE.getClass().getName()))
CAUSE.getClass().getName(),
CODE))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("nextAttemptAt");
}
@@ -138,15 +152,29 @@ class OutboxRelayFailureReportTest {
"corr-1",
1,
NEXT_ATTEMPT_AT,
CAUSE.getClass().getName()))
CAUSE.getClass().getName(),
CODE))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("nextAttemptAt");
}
@Test
@DisplayName("원인 코드 자리에 문장을 넣으면 보고를 만들지 않는다")
void aSentenceIsRefusedAsAFailureCode() {
assertThatThrownBy(
() ->
OutboxRelayFailureReport.deadLetter(
"evt-1", "Event", "agg-1", "corr-1", 1, CAUSE, "connect to 10.0.0.7 failed"))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("failureCode");
}
@Test
void causeIsRequired() {
assertThatThrownBy(
() -> OutboxRelayFailureReport.deadLetter("evt-1", "Event", "agg-1", "corr-1", 1, null))
() ->
OutboxRelayFailureReport.deadLetter(
"evt-1", "Event", "agg-1", "corr-1", 1, null, CODE))
.isInstanceOf(NullPointerException.class)
.hasMessageContaining("cause");
}
@@ -131,7 +131,8 @@ class PublishPendingOutboxEventsUseCaseTest {
"correlation-evt-fail",
1,
nextAttemptAt,
brokerDown));
brokerDown,
"RuntimeException"));
}
@Test
@@ -155,7 +156,8 @@ class PublishPendingOutboxEventsUseCaseTest {
"agg-1",
"correlation-evt-dead",
3,
brokerDown));
brokerDown,
"RuntimeException"));
}
// ---- failure NOT swallowed ----
@@ -476,15 +478,15 @@ class PublishPendingOutboxEventsUseCaseTest {
}
@Override
public OutboxCompletion markFailed(OutboxLease lease, Instant retryAt) {
public OutboxCompletion markFailed(OutboxLease lease, Instant retryAt, String failureCode) {
markFailedCalls++;
return super.markFailed(lease, retryAt);
return super.markFailed(lease, retryAt, failureCode);
}
@Override
public OutboxCompletion markDead(OutboxLease lease) {
public OutboxCompletion markDead(OutboxLease lease, String failureCode) {
markDeadCalls++;
return super.markDead(lease);
return super.markDead(lease, failureCode);
}
OutboxEventStatus currentStatus() {
@@ -519,19 +521,20 @@ class PublishPendingOutboxEventsUseCaseTest {
}
@Override
public OutboxCompletion markFailed(OutboxLease lease, Instant nextAttemptAt) {
public OutboxCompletion markFailed(
OutboxLease lease, Instant nextAttemptAt, String failureCode) {
if (markFailedException != null) {
throw markFailedException;
}
return super.markFailed(lease, nextAttemptAt);
return super.markFailed(lease, nextAttemptAt, failureCode);
}
@Override
public OutboxCompletion markDead(OutboxLease lease) {
public OutboxCompletion markDead(OutboxLease lease, String failureCode) {
if (markDeadException != null) {
throw markDeadException;
}
return super.markDead(lease);
return super.markDead(lease, failureCode);
}
}
@@ -85,6 +85,58 @@ class TransientPublishFailureRelayTest {
.isNotNull();
}
@Test
@DisplayName("다시 시도할 거부는 publisher가 붙인 원인 코드를 행과 실패 보고에 남긴다")
void aRetryableRefusalLeavesThePublishersFailureCodeOnTheRowAndInTheReport() {
// given: the broker refused this producer's credentials
store.addClaimable(OutboxEvents.claimed("evt-credential", START.minusSeconds(1), 1));
port.answering(
OutboxPublishAttempt.failed(
OutboxPublishOutcome.REJECTED_RETRYABLE, "KAFKA_AUTHENTICATIONEXCEPTION"));
// when
relay.handle(PublishPendingOutboxEventsCommand.INSTANCE);
// then: what the outcome cannot say — a credential, not a shutdown — is on both
assertThat(
List.of(
store.lastFailureCode("evt-credential"),
reports.getFirst().failureCode(),
reports.getFirst().causeType()))
.containsExactly(
"KAFKA_AUTHENTICATIONEXCEPTION",
"KAFKA_AUTHENTICATIONEXCEPTION",
OutboxPublishRefusedException.class.getName());
}
@Test
@DisplayName("원인 코드 없이 응답이 없던 발행은 결과 이름을 원인 코드로 남긴다")
void anUnansweredPublishWithoutACodeIsRecordedUnderItsOutcomesName() {
// given
store.addClaimable(OutboxEvents.claimed("evt-silent", START.minusSeconds(1), 1));
port.answering(OutboxPublishAttempt.of(OutboxPublishOutcome.AMBIGUOUS));
// when
relay.handle(PublishPendingOutboxEventsCommand.INSTANCE);
// then
assertThat(store.lastFailureCode("evt-silent")).isEqualTo("AMBIGUOUS");
}
@Test
@DisplayName("분류되지 않고 던져진 실패는 예외 타입 이름을 원인 코드로 남긴다")
void anUnclassifiedThrownFailureIsRecordedUnderItsTypesName() {
// given
store.addClaimable(OutboxEvents.claimed("evt-thrown", START.minusSeconds(1), 1));
port.throwing(new IllegalStateException("driver said: host=10.0.0.7 password=hunter2"));
// when
relay.handle(PublishPendingOutboxEventsCommand.INSTANCE);
// then: the type, never the message
assertThat(store.lastFailureCode("evt-thrown")).isEqualTo("IllegalStateException");
}
@Test
@DisplayName("일시적 실패는 시도 예산을 다 쓴 행도 DEAD로 보내지 않는다")
void aTransientFailureNeverDeadLettersEvenPastTheAttemptBudget() {
@@ -37,7 +37,7 @@ class FakeOutboxMessagePublisherContractTest extends OutboxMessagePublishContrac
.answering(CLAIMED_EVENT_ID, OutboxPublishOutcome.REJECTED_BEFORE_SEND);
// when
OutboxPublishOutcome outcome = publisher.publishForOutcome(claimedRow());
OutboxPublishOutcome outcome = publisher.publishForOutcome(claimedRow()).outcome();
// then
assertThat(outcome).isEqualTo(OutboxPublishOutcome.REJECTED_BEFORE_SEND);
@@ -68,7 +68,7 @@ class FakeOutboxMessagePublisherContractTest extends OutboxMessagePublishContrac
.answering(OutboxPublishOutcome.REJECTED_RETRYABLE);
// when
OutboxPublishOutcome outcome = publisher.publishForOutcome(claimedRow());
OutboxPublishOutcome outcome = publisher.publishForOutcome(claimedRow()).outcome();
// then
assertThat(outcome).isEqualTo(OutboxPublishOutcome.REJECTED_RETRYABLE);
@@ -6,7 +6,9 @@ import dev.caskeleton.application.transaction.testkit.DirectTransactionPort;
class InMemoryOutboxAggregateSequenceContractTest extends OutboxAggregateSequenceContract {
private final InMemoryOutboxAggregateSequences sequences = new InMemoryOutboxAggregateSequences();
private final DirectTransactionPort transactions = new DirectTransactionPort();
private final InMemoryOutboxAggregateSequences sequences =
new InMemoryOutboxAggregateSequences(transactions);
@Override
protected OutboxAggregateSequencePort sequences() {
@@ -15,6 +17,6 @@ class InMemoryOutboxAggregateSequenceContractTest extends OutboxAggregateSequenc
@Override
protected TransactionPort transactions() {
return new DirectTransactionPort();
return transactions;
}
}
@@ -29,4 +29,9 @@ class InMemoryOutboxStoreLeaseFencingContractTest extends OutboxLeaseFencingCont
protected OutboxEventStatus statusOf(String eventId) {
return store.status(eventId);
}
@Override
protected String lastFailureCodeOf(String eventId) {
return store.lastFailureCode(eventId);
}
}
@@ -0,0 +1,4 @@
# SHA-256 (LF-normalized) of every released payload schema version in src/main/resources/contracts/messaging.
# A released version is never edited: a change goes into a new version (application-core README).
# Add a line when a version is released; change a line only for a version no one can have consumed.
4d2f780bf6c23fa548fc2b0e6ef02302e17fca44a20f21ebf5ba07aaac11a245 durable-operation.submitted/v1.schema.json
@@ -179,6 +179,25 @@ public abstract class CacheRegionContract {
assertThat(valueOf(region.lookup("k"))).isEqualTo("at-10");
}
/**
* 2^53 + 1 against 2^53: a floating-point parse reads both as the same number, so a provider that
* compares revisions as doubles refuses the newer one (review 2026-11-03 RR-01-06).
*/
@Test
@DisplayName("ONLY_IF_SOURCE_REVISION_NEWER는 2^53보다 큰 revision도 한 자리 차이를 구분한다")
void onlyIfSourceRevisionNewerTellsApartRevisionsAboveTwoToTheFiftyThird() {
// given
CacheRegionPort<String, String> region = region();
region.record("k", "at-2^53", upsert("9007199254740992"));
// when
CacheRecordOutcome outcome =
region.record("k", "at-2^53+1", newerThanStored("9007199254740993"));
// then
assertThat(outcome).isEqualTo(CacheRecordOutcome.RECORDED);
}
@Test
@DisplayName("ONLY_IF_SOURCE_REVISION_NEWER는 비어 있는 키에 기록한다")
void onlyIfSourceRevisionNewerRecordsIntoAnEmptyKey() {
@@ -22,6 +22,7 @@ import dev.caskeleton.application.idempotency.StoredResponse;
import dev.caskeleton.application.transaction.OperationId;
import java.time.Duration;
import java.util.function.Supplier;
import org.junit.jupiter.api.Assumptions;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
@@ -34,7 +35,10 @@ import org.junit.jupiter.api.Test;
* trusts, and those cases stay with each store's own tests. The one timed case is the one a caller
* relies on whichever store is composed — {@code renew} really extends the lease (review 05-02: the
* Redis store answered a renew as already applied and let the lease run out). A store reaches time
* through {@link #elapse(Duration)}; the in-memory fake has no expiry and leaves it a no-op.
* through {@link #elapse(Duration)}. A store that cannot move its clock — the in-memory fake, which
* models no expiry, and the Redis store over the command fake — keeps the default, which aborts the
* timed case so the report shows it skipped instead of passing a case that never ran its clock
* (review 2026-11-03 RR-01-06).
*
* <p>Every call goes through {@link #inTransaction(Supplier)}, the way the store's callers make it:
* the PostgreSQL store refuses to run outside an application-owned write transaction.
@@ -81,12 +85,16 @@ public abstract class IdempotencyStoreContract {
}
/**
* Lets {@code duration} pass on the clock the store trusts. A store without lease expiry keeps
* the default no-op.
* Lets {@code duration} pass on the clock the store trusts. The default aborts the calling test:
* a store without a clock the contract can move cannot run a timed case, and a no-op here would
* let that case pass without time ever passing.
*
* @param duration how long to let pass
*/
protected void elapse(Duration duration) {}
protected void elapse(Duration duration) {
Assumptions.abort(
"this store has no clock the contract can move, so the timed case does not run against it");
}
private IdempotencyStorePort subject() {
return new EachCallInTransaction(store());
@@ -360,6 +368,30 @@ public abstract class IdempotencyStoreContract {
assertThat(other).isInstanceOf(IdempotencyClaimOutcome.InProgress.class);
}
@Test
@DisplayName("renew한 처리 lease는 claim이 정한 replay TTL보다 길어도 그동안 기록이 사라져 다른 요청에 넘어가지 않는다")
void aLeaseRenewedPastTheReplayTtlKeepsTheRecord() {
// given
IdempotencyStorePort store = subject();
Duration lease = processingLease();
IdempotencyClaimRequest shortReplay =
new IdempotencyClaimRequest(
SCOPE, FINGERPRINT, store.newClaimAttempt(OPERATION), lease, lease, "json-v2", 1);
IdempotencyOwner claimed =
((IdempotencyClaimOutcome.Acquired) store.claim(shortReplay)).owner();
IdempotencyOwner executing =
store.markExecutionStarted(claimed, OPERATION).owner().orElseThrow();
store.renew(executing, lease.multipliedBy(3), OPERATION);
elapse(lease.multipliedBy(2));
// when
IdempotencyClaimOutcome other =
store.claim(claim(store.newClaimAttempt(OTHER_OPERATION), FINGERPRINT, lease));
// then
assertThat(other).isInstanceOf(IdempotencyClaimOutcome.InProgress.class);
}
/** Routes every call of the store through {@link #inTransaction(Supplier)}. */
private final class EachCallInTransaction implements IdempotencyStorePort {
@@ -0,0 +1,115 @@
package dev.caskeleton.application.messaging.contract.testkit;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.shared.digest.Sha256;
import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Map;
import java.util.TreeMap;
import java.util.regex.Pattern;
import java.util.stream.Stream;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
/**
* A released payload schema version is never edited (review 2026-11-01 06-10).
*
* <p>An event's payload schema is {@code contracts/messaging/<contract>/v<N>.schema.json}. Once a
* version has been published, consumers have been built against it and the outbox and the broker
* hold events written under it, so changing its bytes — a field removed, a type changed — breaks
* them in an order that depends on who deploys first. The encoder checks only that the declared
* hash is the file's hash, and both move together in one edit. The rule the messaging design sets
* (strict versioning: "같은 version file의 checksum 변경은 CI 실패") had nothing enforcing it.
*
* <p>The leaf that owns schemas pins each released version's SHA-256 in a manifest, as the
* persistence leaves pin applied migrations: an edited version fails, and a new version fails until
* it is pinned, which is the moment it is released. A change goes into a new version, and the
* version procedure (application-core README "payload version 올리기") is how consumers get it.
*
* <p>What this deliberately does not do is diff a version against the one before. A new version may
* change anything — that is why it is a new version, read by consumers that support it before a
* producer emits it — and the design does not claim compatibility from a JSON Schema diff.
*/
public abstract class ReleasedPayloadSchemaContract {
private static final Pattern SCHEMA_FILE = Pattern.compile("[^/]+/v[1-9][0-9]*\\.schema\\.json");
/** The directory holding {@code <contract>/v<N>.schema.json}, relative to the leaf. */
protected abstract Path schemaRoot();
/**
* The manifest of released versions: {@code <sha256> <contract>/v<N>.schema.json} per line,
* {@code #} comments allowed.
*/
protected abstract Path manifest();
@Test
@DisplayName("이미 출시한 payload schema 버전 파일은 바이트가 바뀌지 않는다")
void aReleasedPayloadSchemaVersionKeepsItsBytes() {
// given
Map<String, String> released = released();
// when
Map<String, String> current = current();
// then
assertThat(current)
.as(
"a released payload schema changed; put the change in a new version (%s)",
"application-core README, payload version 올리기")
.containsAllEntriesOf(released);
}
@Test
@DisplayName("모든 payload schema 버전 파일은 출시 목록에 고정돼 있다")
void everyPayloadSchemaVersionIsPinnedInTheManifest() {
// given
Map<String, String> released = released();
// when
Map<String, String> current = current();
// then
assertThat(released.keySet())
.as("pin a new payload schema version in %s when it is released", manifest())
.containsAll(current.keySet());
}
private Map<String, String> released() {
Map<String, String> pinned = new TreeMap<>();
try {
for (String line : Files.readAllLines(manifest(), StandardCharsets.UTF_8)) {
String trimmed = line.strip();
if (trimmed.isEmpty() || trimmed.startsWith("#")) {
continue;
}
String[] fields = trimmed.split("\\s+", 2);
pinned.put(fields[1], fields[0]);
}
} catch (IOException exception) {
throw new UncheckedIOException(exception);
}
return pinned;
}
/** Every version file under the root, by relative path, with the SHA-256 of its LF bytes. */
private Map<String, String> current() {
Map<String, String> hashes = new TreeMap<>();
try (Stream<Path> files = Files.walk(schemaRoot())) {
for (Path file : files.filter(Files::isRegularFile).toList()) {
String relative = schemaRoot().relativize(file).toString().replace('\\', '/');
if (SCHEMA_FILE.matcher(relative).matches()) {
String content = Files.readString(file, StandardCharsets.UTF_8).replace("\r\n", "\n");
hashes.put(relative, Sha256.ofUtf8(content).hex());
}
}
} catch (IOException exception) {
throw new UncheckedIOException(exception);
}
return hashes;
}
}
@@ -2,6 +2,7 @@ package dev.caskeleton.application.messaging.event.testkit;
import dev.caskeleton.application.messaging.event.IntegrationEventPublishPort;
import dev.caskeleton.application.messaging.event.ValidatedIntegrationEvent;
import dev.caskeleton.application.outbox.OutboxPublishAttempt;
import dev.caskeleton.application.outbox.OutboxPublishOutcome;
import java.util.ArrayList;
import java.util.List;
@@ -17,21 +18,32 @@ import java.util.concurrent.CompletionStage;
public final class FakeIntegrationEventPublisher implements IntegrationEventPublishPort {
private final List<ValidatedIntegrationEvent> published = new ArrayList<>();
private OutboxPublishOutcome answer = OutboxPublishOutcome.CONFIRMED;
private OutboxPublishAttempt answer = OutboxPublishAttempt.confirmed();
/**
* Answers every later publish with {@code outcome}.
* Answers every later publish with {@code outcome}, and for anything but a confirmation the
* outcome's own name as its failure code.
*
* @param outcome the outcome to report
* @return this fake
*/
public FakeIntegrationEventPublisher answering(OutboxPublishOutcome outcome) {
this.answer = Objects.requireNonNull(outcome, "outcome");
return answering(attemptOf(outcome));
}
/**
* Answers every later publish with {@code attempt}, failure code included.
*
* @param attempt the attempt to report
* @return this fake
*/
public FakeIntegrationEventPublisher answering(OutboxPublishAttempt attempt) {
this.answer = Objects.requireNonNull(attempt, "attempt");
return this;
}
@Override
public CompletionStage<OutboxPublishOutcome> publish(ValidatedIntegrationEvent event) {
public CompletionStage<OutboxPublishAttempt> publish(ValidatedIntegrationEvent event) {
published.add(Objects.requireNonNull(event, "event must not be null"));
return CompletableFuture.completedFuture(answer);
}
@@ -57,4 +69,17 @@ public final class FakeIntegrationEventPublisher implements IntegrationEventPubl
case REFUSES_AFTER_RECEIVING -> OutboxPublishOutcome.REJECTED_AFTER_BROKER;
};
}
/**
* The attempt a publisher that names its failures reports for {@code outcome}: the outcome, and
* unless it is a confirmation, a code — the outcome's name, standing in for a broker's own.
*
* @param outcome the outcome
* @return the attempt
*/
public static OutboxPublishAttempt attemptOf(OutboxPublishOutcome outcome) {
return outcome == OutboxPublishOutcome.CONFIRMED
? OutboxPublishAttempt.confirmed()
: OutboxPublishAttempt.failed(outcome, outcome.name());
}
}
@@ -132,7 +132,7 @@ public abstract class IntegrationEventEncoderContract {
LogicalDestinationId destination, IntegrationPayload payload) {
ContractId contractId = EncoderContractKitContract.CONTRACT_ID;
return new IntegrationEventDraft<>(
new EventId("event-1"),
new EventId("01994e11-4d88-7000-8000-0000000000e1"),
contractId,
1,
destination,
@@ -4,6 +4,7 @@ import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.application.messaging.event.IntegrationEventPublishPort;
import dev.caskeleton.application.messaging.event.ValidatedIntegrationEvent;
import dev.caskeleton.application.outbox.OutboxPublishAttempt;
import dev.caskeleton.application.outbox.OutboxPublishOutcome;
import dev.caskeleton.application.outbox.testkit.OutboxEvents;
import java.time.Instant;
@@ -15,12 +16,16 @@ import org.junit.jupiter.api.Test;
* What every {@link IntegrationEventPublishPort} promises, run by the platform bridge's test and
* the fake's test alike (review 2026-11-01 TEST-F-1).
*
* <p>The relay acts on the outcome alone: it marks a row published, retries it, or parks it. So the
* <p>The relay acts on the outcome: it marks a row published, retries it, or parks it. So the
* promise is the translation — each thing a broker can do with a message arrives as the one outcome
* that leads the relay to the right action. A bridge that reported a refusal of the moment as a
* definite rejection parked a committed event and its aggregate behind it (06-01); the bridge's own
* test caught it, the fake every use-case test ran on did not have to.
*
* <p>An attempt that was not confirmed also carries the publisher's code for why. The relay writes
* it on the row, and it is the only thing that tells a refused credential from a closed transport
* once both have been translated into the same outcome (re-review 2026-11-03 RR-05-03).
*
* <p>The event id is a canonical UUIDv7, the only spelling the platform carries.
*/
public abstract class IntegrationEventPublishContract {
@@ -106,9 +111,22 @@ public abstract class IntegrationEventPublishContract {
assertThat(outcome.retryable()).isFalse();
}
/** The contract's event, published and waited for. */
@Test
@DisplayName("확인되지 않은 발행은 publisher가 붙인 원인 코드를 함께 알린다")
void anUnconfirmedPublishCarriesThePublishersFailureCode() {
// given
IntegrationEventPublishPort port = publisherOverABrokerThat(BrokerAnswer.REFUSES_FOR_NOW);
// when
OutboxPublishAttempt attempt = port.publish(contractEvent()).toCompletableFuture().join();
// then
assertThat(attempt.failureCode()).isPresent();
}
/** The contract's event, published and waited for; the outcome is what these scenarios read. */
private static OutboxPublishOutcome publish(IntegrationEventPublishPort port) {
return port.publish(contractEvent()).toCompletableFuture().join();
return port.publish(contractEvent()).toCompletableFuture().join().outcome();
}
/** The event every scenario publishes. */
@@ -1,8 +1,10 @@
package dev.caskeleton.application.outbox.testkit;
import dev.caskeleton.application.messaging.event.testkit.FakeIntegrationEventPublisher;
import dev.caskeleton.application.outbox.ClaimedOutboxEvent;
import dev.caskeleton.application.outbox.OutboxMessagePublishPort;
import dev.caskeleton.application.outbox.OutboxPublishAmbiguousException;
import dev.caskeleton.application.outbox.OutboxPublishAttempt;
import dev.caskeleton.application.outbox.OutboxPublishOutcome;
import dev.caskeleton.application.outbox.OutboxPublishRefusedException;
import java.util.ArrayList;
@@ -19,18 +21,19 @@ import java.util.function.Consumer;
* it.
*
* <p>The relay's tests script it four ways: one outcome for every publish ({@link
* #answering(OutboxPublishOutcome)}), one outcome for one event ({@link #answering(String,
* OutboxPublishOutcome)}), an exception the broker client raised instead of answering ({@link
* #throwing}), and something that happens while the broker call is in progress ({@link
* #whenPublishing}) — a clock that moves, a stop request that arrives. A per-event script wins over
* the shared answer, and a thrown exception wins over both.
* #answering(OutboxPublishOutcome)}, or {@link #answering(OutboxPublishAttempt)} with the
* publisher's own failure code; an outcome alone carries its name as the code), one outcome for one
* event ({@link #answering(String, OutboxPublishOutcome)}), an exception the broker client raised
* instead of answering ({@link #throwing}), and something that happens while the broker call is in
* progress ({@link #whenPublishing}) — a clock that moves, a stop request that arrives. A per-event
* script wins over the shared answer, and a thrown exception wins over both.
*/
public final class FakeOutboxMessagePublisher implements OutboxMessagePublishPort {
private final List<ClaimedOutboxEvent> published = new ArrayList<>();
private final Map<String, OutboxPublishOutcome> answerPerEvent = new HashMap<>();
private final Map<String, OutboxPublishAttempt> answerPerEvent = new HashMap<>();
private final Map<String, RuntimeException> failurePerEvent = new HashMap<>();
private OutboxPublishOutcome answer = OutboxPublishOutcome.CONFIRMED;
private OutboxPublishAttempt answer = OutboxPublishAttempt.confirmed();
private RuntimeException failure;
private Consumer<ClaimedOutboxEvent> duringPublish = event -> {};
@@ -42,7 +45,18 @@ public final class FakeOutboxMessagePublisher implements OutboxMessagePublishPor
* @return this fake
*/
public FakeOutboxMessagePublisher answering(OutboxPublishOutcome outcome) {
this.answer = Objects.requireNonNull(outcome, "outcome");
return answering(FakeIntegrationEventPublisher.attemptOf(Objects.requireNonNull(outcome)));
}
/**
* Answers every later publish with {@code attempt} — an outcome with the publisher's own failure
* code — and stops throwing a failure set by {@link #throwing(RuntimeException)}.
*
* @param attempt the attempt to report
* @return this fake
*/
public FakeOutboxMessagePublisher answering(OutboxPublishAttempt attempt) {
this.answer = Objects.requireNonNull(attempt, "attempt");
this.failure = null;
return this;
}
@@ -57,7 +71,8 @@ public final class FakeOutboxMessagePublisher implements OutboxMessagePublishPor
*/
public FakeOutboxMessagePublisher answering(String eventId, OutboxPublishOutcome outcome) {
answerPerEvent.put(
Objects.requireNonNull(eventId, "eventId"), Objects.requireNonNull(outcome, "outcome"));
Objects.requireNonNull(eventId, "eventId"),
FakeIntegrationEventPublisher.attemptOf(Objects.requireNonNull(outcome, "outcome")));
return this;
}
@@ -101,7 +116,7 @@ public final class FakeOutboxMessagePublisher implements OutboxMessagePublishPor
@Override
public void publish(ClaimedOutboxEvent event) {
OutboxPublishOutcome outcome = publishForOutcome(event);
OutboxPublishOutcome outcome = publishForOutcome(event).outcome();
if (outcome == OutboxPublishOutcome.CONFIRMED) {
return;
}
@@ -112,7 +127,7 @@ public final class FakeOutboxMessagePublisher implements OutboxMessagePublishPor
}
@Override
public OutboxPublishOutcome publishForOutcome(ClaimedOutboxEvent event) {
public OutboxPublishAttempt publishForOutcome(ClaimedOutboxEvent event) {
published.add(Objects.requireNonNull(event, "event must not be null"));
// The answer is read after the side effect: a side effect that moves a clock past an outage or
// re-scripts the fake decides what this very call reports, as a broker that came back would.
@@ -2,16 +2,61 @@ package dev.caskeleton.application.outbox.testkit;
import dev.caskeleton.application.messaging.event.AggregateIdentity;
import dev.caskeleton.application.outbox.OutboxAggregateSequencePort;
import dev.caskeleton.application.transaction.testkit.DirectTransactionPort;
import java.util.HashMap;
import java.util.Map;
import java.util.Objects;
/** In-memory {@link OutboxAggregateSequencePort}: one counter per aggregate identity. */
/**
* In-memory {@link OutboxAggregateSequencePort}: one counter per aggregate identity.
*
* <p>Built over a {@link DirectTransactionPort}, it keeps the JPA counter's transaction rules, and
* {@link OutboxAggregateSequenceContract} holds it to them: a number is refused outside a write
* transaction, and a number taken by a transaction that rolls back is handed out again. Built with
* no port, it hands out numbers with or without a transaction and keeps them on rollback — for
* tests that seed events directly and do not model transactions, as {@code new
* InMemoryOutboxStore()} does.
*/
public final class InMemoryOutboxAggregateSequences implements OutboxAggregateSequencePort {
private final Map<AggregateIdentity, Long> last = new HashMap<>();
private final DirectTransactionPort transactions;
/** A counter that does not look at transactions. */
public InMemoryOutboxAggregateSequences() {
this.transactions = null;
}
/**
* A counter that joins {@code transactions} as the JPA counter joins the caller's.
*
* @param transactions the port the use case under test opens its transactions through
*/
public InMemoryOutboxAggregateSequences(DirectTransactionPort transactions) {
this.transactions = Objects.requireNonNull(transactions, "transactions");
}
@Override
public synchronized long nextSequence(AggregateIdentity aggregate) {
return last.merge(aggregate, 1L, Long::sum);
Objects.requireNonNull(aggregate, "aggregate must not be null");
if (transactions == null) {
return last.merge(aggregate, 1L, Long::sum);
}
if (!transactions.active() || transactions.readOnly()) {
throw new IllegalStateException(
"outbox nextSequence requires an active caller transaction (a write one)");
}
Long previous = last.get(aggregate);
long next = last.merge(aggregate, 1L, Long::sum);
transactions.onRollback(() -> restore(aggregate, previous));
return next;
}
private synchronized void restore(AggregateIdentity aggregate, Long previous) {
if (previous == null) {
last.remove(aggregate);
} else {
last.put(aggregate, previous);
}
}
}
@@ -6,6 +6,7 @@ import dev.caskeleton.application.outbox.OutboxAppendPort;
import dev.caskeleton.application.outbox.OutboxCompletion;
import dev.caskeleton.application.outbox.OutboxEventStatus;
import dev.caskeleton.application.outbox.OutboxLease;
import dev.caskeleton.application.outbox.OutboxLongRetries;
import dev.caskeleton.application.outbox.OutboxStorePort;
import dev.caskeleton.application.transaction.testkit.DirectTransactionPort;
import java.time.Duration;
@@ -126,7 +127,7 @@ public class InMemoryOutboxStore implements OutboxStorePort, OutboxAppendPort {
@Override
public OutboxCompletion markPublished(OutboxLease lease) {
OutboxCompletion completion = complete(lease, OutboxEventStatus.PUBLISHED, null);
OutboxCompletion completion = complete(lease, OutboxEventStatus.PUBLISHED, null, null);
if (completion == OutboxCompletion.APPLIED) {
published.add(lease.eventId());
}
@@ -134,8 +135,9 @@ public class InMemoryOutboxStore implements OutboxStorePort, OutboxAppendPort {
}
@Override
public OutboxCompletion markFailed(OutboxLease lease, Instant nextAttemptAt) {
OutboxCompletion completion = complete(lease, OutboxEventStatus.FAILED, nextAttemptAt);
public OutboxCompletion markFailed(OutboxLease lease, Instant nextAttemptAt, String failureCode) {
OutboxCompletion completion =
complete(lease, OutboxEventStatus.FAILED, nextAttemptAt, failureCode);
if (completion == OutboxCompletion.APPLIED) {
failed.put(lease.eventId(), nextAttemptAt);
}
@@ -143,8 +145,10 @@ public class InMemoryOutboxStore implements OutboxStorePort, OutboxAppendPort {
}
@Override
public OutboxCompletion markDeferred(OutboxLease lease, Instant nextAttemptAt) {
OutboxCompletion completion = complete(lease, OutboxEventStatus.FAILED, nextAttemptAt);
public OutboxCompletion markDeferred(
OutboxLease lease, Instant nextAttemptAt, String failureCode) {
OutboxCompletion completion =
complete(lease, OutboxEventStatus.FAILED, nextAttemptAt, failureCode);
if (completion == OutboxCompletion.APPLIED) {
rows.get(lease.eventId()).deferredAttemptCount++;
failed.put(lease.eventId(), nextAttemptAt);
@@ -154,7 +158,7 @@ public class InMemoryOutboxStore implements OutboxStorePort, OutboxAppendPort {
@Override
public OutboxCompletion releaseLease(OutboxLease lease, Instant claimableAt) {
OutboxCompletion completion = complete(lease, OutboxEventStatus.PENDING, claimableAt);
OutboxCompletion completion = complete(lease, OutboxEventStatus.PENDING, claimableAt, null);
if (completion == OutboxCompletion.APPLIED) {
Row row = rows.get(lease.eventId());
row.attemptCount--;
@@ -164,17 +168,20 @@ public class InMemoryOutboxStore implements OutboxStorePort, OutboxAppendPort {
}
@Override
public OutboxCompletion markDead(OutboxLease lease) {
OutboxCompletion completion = complete(lease, OutboxEventStatus.DEAD, null);
public OutboxCompletion markDead(OutboxLease lease, String failureCode) {
OutboxCompletion completion = complete(lease, OutboxEventStatus.DEAD, null, failureCode);
if (completion == OutboxCompletion.APPLIED) {
dead.add(lease.eventId());
}
return completion;
}
/** The same predicate the SQL completion carries: still IN_FLIGHT, same owner, same token. */
/**
* The same predicate the SQL completion carries: still IN_FLIGHT, same owner, same token. A
* failure code, when given, replaces the row's last one, as the SQL completion's does.
*/
private OutboxCompletion complete(
OutboxLease lease, OutboxEventStatus status, Instant nextAttemptAt) {
OutboxLease lease, OutboxEventStatus status, Instant nextAttemptAt, String failureCode) {
Row row = rows.get(lease.eventId());
if (row == null
|| row.status != OutboxEventStatus.IN_FLIGHT
@@ -187,6 +194,9 @@ public class InMemoryOutboxStore implements OutboxStorePort, OutboxAppendPort {
if (nextAttemptAt != null) {
row.nextAttemptAt = nextAttemptAt;
}
if (failureCode != null) {
row.lastFailureCode = failureCode;
}
return OutboxCompletion.APPLIED;
}
@@ -211,10 +221,38 @@ public class InMemoryOutboxStore implements OutboxStorePort, OutboxAppendPort {
return ages;
}
@Override
public OutboxLongRetries longRetries(int minDeferredClaims, Instant now) {
List<Row> retrying =
rows.values().stream()
.filter(row -> row.status == OutboxEventStatus.FAILED)
.filter(row -> row.deferredAttemptCount >= minDeferredClaims)
.toList();
if (retrying.isEmpty()) {
return OutboxLongRetries.NONE;
}
long oldest =
retrying.stream()
.mapToLong(row -> Duration.between(row.event.occurredAt(), now).toSeconds())
.max()
.orElseThrow();
return new OutboxLongRetries(retrying.size(), Math.max(0, oldest));
}
public OutboxEventStatus status(String eventId) {
return row(eventId).status;
}
/**
* The code the row's last failed completion recorded, or {@code null} before any failed.
*
* @param eventId the row
* @return the last failure code
*/
public String lastFailureCode(String eventId) {
return row(eventId).lastFailureCode;
}
public int attemptCount(String eventId) {
return row(eventId).attemptCount;
}
@@ -262,6 +300,7 @@ public class InMemoryOutboxStore implements OutboxStorePort, OutboxAppendPort {
private int attemptCount;
private int deferredAttemptCount;
private Instant nextAttemptAt;
private String lastFailureCode;
private String leaseOwner;
private long leaseToken;
@@ -1,10 +1,12 @@
package dev.caskeleton.application.outbox.testkit;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.catchThrowable;
import dev.caskeleton.application.messaging.event.AggregateIdentity;
import dev.caskeleton.application.outbox.OutboxAggregateSequencePort;
import dev.caskeleton.application.transaction.TransactionPort;
import dev.caskeleton.application.transaction.testkit.OverlappingWrites;
import java.util.ArrayList;
import java.util.List;
import java.util.UUID;
@@ -14,6 +16,10 @@ import org.junit.jupiter.api.Test;
/**
* What every {@link OutboxAggregateSequencePort} promises, run against the in-memory fake and the
* JPA adapter alike. Each test uses aggregates of its own, so a subclass may share one store.
*
* <p>Where an aggregate's numbers start is the implementation's: the fake starts at 1, the JPA
* counter above every number the replaced wall-clock scheme could have issued (V21). What every
* implementation promises is the step and the independence.
*/
public abstract class OutboxAggregateSequenceContract {
@@ -22,8 +28,8 @@ public abstract class OutboxAggregateSequenceContract {
protected abstract TransactionPort transactions();
@Test
@DisplayName("같은 aggregate의 순서 번호는 1부터 커밋마다 하나씩 커진다")
void anAggregatesNumbersStartAtOneAndGrowByOnePerCommittedWrite() {
@DisplayName("같은 aggregate의 순서 번호는 첫 번호부터 커밋마다 하나씩 커진다")
void anAggregatesNumbersGrowByOnePerCommittedWriteFromItsFirst() {
// given
AggregateIdentity aggregate = aggregate();
List<Long> numbers = new ArrayList<>();
@@ -34,23 +40,110 @@ public abstract class OutboxAggregateSequenceContract {
}
// then
assertThat(numbers).containsExactly(1L, 2L, 3L);
long first = numbers.get(0);
assertThat(List.of(first >= 1, numbers))
.containsExactly(true, List.of(first, first + 1, first + 2));
}
@Test
@DisplayName("aggregate마다 순서 번호를 따로 센다")
void eachAggregateCountsOnItsOwn() {
@DisplayName("다른 aggregate의 쓰기는 이 aggregate의 첫 번호를 바꾸지 않는다")
void anotherAggregatesWritesDoNotMoveThisAggregatesFirstNumber() {
// given
AggregateIdentity first = aggregate();
AggregateIdentity second = aggregate();
transactions().inWrite(() -> sequences().nextSequence(first));
long firstsFirst = transactions().inWrite(() -> sequences().nextSequence(first));
transactions().inWrite(() -> sequences().nextSequence(first));
// when
long secondsFirst = transactions().inWrite(() -> sequences().nextSequence(second));
// then
assertThat(secondsFirst).isEqualTo(1L);
assertThat(secondsFirst).isEqualTo(firstsFirst);
}
/**
* The first two writes of an aggregate overlap: both find no counter. A store that creates the
* counter with a plain insert fails the second one on the primary key (review RR-03-01), which
* rejects a valid business write that no caller retries.
*/
@Test
@DisplayName("카운터가 없는 aggregate에 두 쓰기가 겹쳐도 둘 다 성공하고 커밋 순서대로 연속 번호를 받는다")
void twoOverlappingFirstWritesBothSucceedWithConsecutiveNumbers() {
// given
AggregateIdentity aggregate = aggregate();
// when
List<Long> numbers =
OverlappingWrites.run(
work -> transactions().inWrite(work),
() -> sequences().nextSequence(aggregate),
() -> sequences().nextSequence(aggregate));
// then
assertThat(numbers.get(1)).isEqualTo(numbers.get(0) + 1);
}
/**
* Outside the caller's write transaction the number would commit apart from the event it numbers
* (review 2026-11-03 RR-01-06).
*/
@Test
@DisplayName("쓰기 트랜잭션 밖에서는 순서 번호를 주지 않는다")
void aNumberIsRefusedOutsideTheCallersWriteTransaction() {
// given
AggregateIdentity aggregate = aggregate();
// when
Throwable thrown = catchThrowable(() -> sequences().nextSequence(aggregate));
// then
assertThat(thrown)
.isInstanceOf(IllegalStateException.class)
.hasMessageContaining("requires an active caller transaction");
}
/**
* The number is taken under the counter's lock and goes back with a rollback, so the next commit
* reuses it rather than leaving a gap (review 2026-11-03 RR-01-06). Relative to the first number,
* so a store that seeds a new counter above 1 is held to the same case.
*/
@Test
@DisplayName("롤백된 쓰기가 받은 순서 번호는 다음 쓰기가 다시 받는다")
void aNumberTakenByARolledBackWriteIsHandedOutAgain() {
// given
AggregateIdentity aggregate = aggregate();
long first = transactions().inWrite(() -> sequences().nextSequence(aggregate));
long rolledBack = numberTakenByARolledBackWrite(aggregate);
// when
long next = transactions().inWrite(() -> sequences().nextSequence(aggregate));
// then
assertThat(List.of(rolledBack, next)).containsExactly(first + 1, first + 1);
}
private long numberTakenByARolledBackWrite(AggregateIdentity aggregate) {
long[] taken = new long[1];
try {
transactions()
.inWrite(
() -> {
taken[0] = sequences().nextSequence(aggregate);
throw new RollBack();
});
} catch (RollBack expected) {
// the write rolled back, as this case needs
}
return taken[0];
}
/** Thrown inside a write so that its transaction rolls back. */
private static final class RollBack extends RuntimeException {
private static final long serialVersionUID = 1L;
RollBack() {
super("roll the write back");
}
}
private static AggregateIdentity aggregate() {
@@ -7,6 +7,7 @@ import dev.caskeleton.application.outbox.OutboxBackoffPolicy;
import dev.caskeleton.application.outbox.OutboxCompletion;
import dev.caskeleton.application.outbox.OutboxEventStatus;
import dev.caskeleton.application.outbox.OutboxLease;
import dev.caskeleton.application.outbox.OutboxLongRetries;
import dev.caskeleton.application.outbox.OutboxMessagePublishPort;
import dev.caskeleton.application.outbox.OutboxRelayFailureReport;
import dev.caskeleton.application.outbox.OutboxRelayFailureReportPort;
@@ -54,6 +55,13 @@ public abstract class OutboxLeaseFencingContract {
/** Reads the row's persisted status, bypassing anything the store caches. */
protected abstract OutboxEventStatus statusOf(String eventId);
/**
* Reads the row's persisted {@code last_failure_code}, bypassing anything the store caches.
*
* @return the code, or {@code null} when no failed completion wrote one
*/
protected abstract String lastFailureCodeOf(String eventId);
@Test
void lateFailureFromASupersededRelayIsStaleAndThePublishedRowStays() {
// given
@@ -149,7 +157,8 @@ public abstract class OutboxLeaseFencingContract {
transactions().inWrite(() -> store().markPublished(lease));
// when
OutboxCompletion second = transactions().inWrite(() -> store().markDead(lease));
OutboxCompletion second =
transactions().inWrite(() -> store().markDead(lease, "REJECTED_BEFORE_SEND"));
// then
assertThat(Map.entry(second, statusOf(eventId)))
@@ -201,7 +210,9 @@ public abstract class OutboxLeaseFencingContract {
Instant retryAt = CLAIMED_AT.plusSeconds(30);
// when
OutboxCompletion deferred = transactions().inWrite(() -> store().markDeferred(first, retryAt));
OutboxCompletion deferred =
transactions()
.inWrite(() -> store().markDeferred(first, retryAt, "KAFKA_TRANSPORT_CLOSED"));
// then
OutboxLease second = claim("relay-a", retryAt);
@@ -214,6 +225,95 @@ public abstract class OutboxLeaseFencingContract {
.containsExactly(2, 1, 1);
}
@Test
@DisplayName("미룬 시도는 publisher가 붙인 원인 코드를 행에 남긴다")
void aDeferredClaimLeavesThePublishersFailureCodeOnTheRow() {
// given
String eventId = appendEvent("deferred-code");
OutboxLease lease = claim("relay-a", CLAIMED_AT);
// when
transactions()
.inWrite(
() ->
store()
.markDeferred(
lease, CLAIMED_AT.plusSeconds(30), "KAFKA_AUTHENTICATIONEXCEPTION"));
// then
assertThat(List.of(statusOf(eventId), lastFailureCodeOf(eventId)))
.containsExactly(OutboxEventStatus.FAILED, "KAFKA_AUTHENTICATIONEXCEPTION");
}
@Test
@DisplayName("DEAD로 옮긴 시도는 그 원인 코드를 행에 남긴다")
void aDeadLetteredClaimLeavesItsFailureCodeOnTheRow() {
// given
String eventId = appendEvent("dead-code");
OutboxLease lease = claim("relay-a", CLAIMED_AT);
// when
transactions().inWrite(() -> store().markDead(lease, "KAFKA_RECORDTOOLARGEEXCEPTION"));
// then
assertThat(List.of(statusOf(eventId), lastFailureCodeOf(eventId)))
.containsExactly(OutboxEventStatus.DEAD, "KAFKA_RECORDTOOLARGEEXCEPTION");
}
@Test
@DisplayName("넘겨받힌 claim의 실패는 행의 원인 코드를 바꾸지 않는다")
void aSupersededLeasesFailureDoesNotOverwriteTheRowsFailureCode() {
// given
String eventId = appendEvent("stale-code");
OutboxLease expired = claim("relay-a", CLAIMED_AT);
OutboxLease current = claim("relay-b", AFTER_EXPIRY);
transactions()
.inWrite(() -> store().markDeferred(current, AFTER_EXPIRY.plusSeconds(30), "CURRENT_CODE"));
// when
OutboxCompletion late =
transactions()
.inWrite(() -> store().markFailed(expired, AFTER_EXPIRY.plusSeconds(30), "LATE_CODE"));
// then
assertThat(List.of(late, lastFailureCodeOf(eventId)))
.containsExactly(OutboxCompletion.STALE, "CURRENT_CODE");
}
@Test
@DisplayName("미룬 claim이 기준 수 이상 쌓인 FAILED 행만 오래 재시도 중인 행으로 센다")
void onlyFailedRowsWithEnoughDeferredClaimsCountAsLongRetrying() {
// given: one row deferred twice (due again at +60s), one deferred once (claimed at +59s, when
// it is the only row due), measured an hour after both occurred
String twice = appendEvent("long-twice");
deferTwice(twice);
appendEvent("long-once");
OutboxLease once = claim("relay-a", CLAIMED_AT.plusSeconds(59));
transactions().inWrite(() -> store().markDeferred(once, CLAIMED_AT.plusSeconds(89), "ONCE"));
Instant anHourLater = CLAIMED_AT.minusSeconds(1).plusSeconds(3600);
// when
OutboxLongRetries longRetries = store().longRetries(2, anHourLater);
// then
assertThat(longRetries).isEqualTo(new OutboxLongRetries(1, 3600));
}
/** Claims and defers the only claimable row twice; it ends FAILED with two deferred claims. */
private void deferTwice(String eventId) {
Instant at = CLAIMED_AT;
for (int i = 0; i < 2; i++) {
OutboxLease lease = claim("relay-a", at);
if (!lease.eventId().equals(eventId)) {
throw new IllegalStateException(
"expected to claim " + eventId + ", got " + lease.eventId());
}
Instant retryAt = at.plusSeconds(30);
transactions().inWrite(() -> store().markDeferred(lease, retryAt, "TWICE"));
at = retryAt;
}
}
private OutboxLease claim(String owner, Instant now) {
return transactions()
.inWrite(() -> store().claimBatch(owner, 1, now, IN_FLIGHT_TIMEOUT))
@@ -302,13 +402,15 @@ public abstract class OutboxLeaseFencingContract {
}
@Override
public OutboxCompletion markFailed(OutboxLease lease, Instant nextAttemptAt) {
return count(delegate.markFailed(lease, nextAttemptAt));
public OutboxCompletion markFailed(
OutboxLease lease, Instant nextAttemptAt, String failureCode) {
return count(delegate.markFailed(lease, nextAttemptAt, failureCode));
}
@Override
public OutboxCompletion markDeferred(OutboxLease lease, Instant nextAttemptAt) {
return count(delegate.markDeferred(lease, nextAttemptAt));
public OutboxCompletion markDeferred(
OutboxLease lease, Instant nextAttemptAt, String failureCode) {
return count(delegate.markDeferred(lease, nextAttemptAt, failureCode));
}
@Override
@@ -317,8 +419,8 @@ public abstract class OutboxLeaseFencingContract {
}
@Override
public OutboxCompletion markDead(OutboxLease lease) {
return count(delegate.markDead(lease));
public OutboxCompletion markDead(OutboxLease lease, String failureCode) {
return count(delegate.markDead(lease, failureCode));
}
private OutboxCompletion count(OutboxCompletion completion) {
@@ -337,5 +439,10 @@ public abstract class OutboxLeaseFencingContract {
public Map<String, Long> oldestUnpublishedAgeSecondsByEventType(Instant now) {
return delegate.oldestUnpublishedAgeSecondsByEventType(now);
}
@Override
public OutboxLongRetries longRetries(int minDeferredClaims, Instant now) {
return delegate.longRetries(minDeferredClaims, now);
}
}
}
@@ -6,6 +6,7 @@ import static org.assertj.core.api.Assertions.catchThrowable;
import dev.caskeleton.application.messaging.event.testkit.BrokerAnswer;
import dev.caskeleton.application.outbox.ClaimedOutboxEvent;
import dev.caskeleton.application.outbox.OutboxMessagePublishPort;
import dev.caskeleton.application.outbox.OutboxPublishAttempt;
import dev.caskeleton.application.outbox.OutboxPublishOutcome;
import java.time.Instant;
import java.util.List;
@@ -40,7 +41,7 @@ public abstract class OutboxMessagePublishContract {
OutboxMessagePublishPort port = publisherOverABrokerThat(BrokerAnswer.CONFIRMS);
// when
OutboxPublishOutcome outcome = port.publishForOutcome(claimedRow());
OutboxPublishOutcome outcome = port.publishForOutcome(claimedRow()).outcome();
// then
assertThat(outcome).isEqualTo(OutboxPublishOutcome.CONFIRMED);
@@ -54,7 +55,7 @@ public abstract class OutboxMessagePublishContract {
OutboxMessagePublishPort port = publisherOverABrokerThat(BrokerAnswer.NEVER_CONFIRMS);
// when
OutboxPublishOutcome outcome = port.publishForOutcome(claimedRow());
OutboxPublishOutcome outcome = port.publishForOutcome(claimedRow()).outcome();
// then
assertThat(outcome).isEqualTo(OutboxPublishOutcome.AMBIGUOUS);
@@ -67,12 +68,25 @@ public abstract class OutboxMessagePublishContract {
OutboxMessagePublishPort port = publisherOverABrokerThat(BrokerAnswer.REFUSES_AFTER_RECEIVING);
// when
OutboxPublishOutcome outcome = port.publishForOutcome(claimedRow());
OutboxPublishOutcome outcome = port.publishForOutcome(claimedRow()).outcome();
// then
assertThat(outcome).isEqualTo(OutboxPublishOutcome.REJECTED_AFTER_BROKER);
}
@Test
@DisplayName("broker의 거부는 그 거부에 붙은 원인 코드를 함께 알린다")
void aBrokerRefusalCarriesItsFailureCode() {
// given
OutboxMessagePublishPort port = publisherOverABrokerThat(BrokerAnswer.REFUSES_FOR_NOW);
// when
OutboxPublishAttempt attempt = port.publishForOutcome(claimedRow());
// then
assertThat(attempt.failureCode()).isPresent();
}
@Test
@DisplayName("예외로 알리는 발행은 broker가 확인했을 때만 정상 반환한다")
void theThrowingPublishReturnsWhenTheBrokerConfirmed() {
@@ -0,0 +1,99 @@
package dev.caskeleton.application.transaction.testkit;
import java.time.Duration;
import java.util.List;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.Future;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
import java.util.function.Function;
import java.util.function.Supplier;
/**
* Two writes of the same key whose transactions overlap, in an order that does not depend on luck.
*
* <p>The first write runs and then holds its transaction open. The second starts while the first is
* still uncommitted — the moment a find-then-insert reads "absent" twice — and the first commits
* only once the second has either finished or had time to block on the first's row. A store that
* has no transactions simply runs the two one after the other, which is the answer it must give
* anyway.
*
* <p>Public, and here beside the transaction port's own fake, because every store contract with an
* insert-or-find has the same race to show: the outbox order counter's first number, and the
* notification suppression, preference, deduplication, request and admin operation stores. It lived
* in application-notification until the outbox contract needed it too; one copy, not two that
* drift.
*/
public final class OverlappingWrites {
private static final Duration SECOND_WRITE_HEAD_START = Duration.ofMillis(500);
private static final Duration LIMIT = Duration.ofSeconds(30);
private OverlappingWrites() {}
/**
* Runs both writes and returns their results, first then second.
*
* @param inTransaction runs one unit of work in one committed transaction of the store
* @param first the write whose transaction is held open
* @param second the write that starts while the first is uncommitted
* @return both results; a write that failed fails this call with its cause
*/
public static <T> List<T> run(
Function<Supplier<T>, T> inTransaction, Supplier<T> first, Supplier<T> second) {
CountDownLatch firstWrote = new CountDownLatch(1);
CountDownLatch releaseFirst = new CountDownLatch(1);
ExecutorService threads = Executors.newFixedThreadPool(2);
try {
Future<T> firstResult =
threads.submit(
() ->
inTransaction.apply(
() -> {
T written = first.get();
firstWrote.countDown();
await(releaseFirst);
return written;
}));
if (!firstWrote.await(LIMIT.toMillis(), TimeUnit.MILLISECONDS)) {
throw new IllegalStateException("the first write never finished its statement");
}
Future<T> secondResult = threads.submit(() -> inTransaction.apply(second));
try {
secondResult.get(SECOND_WRITE_HEAD_START.toMillis(), TimeUnit.MILLISECONDS);
} catch (TimeoutException blockedOnTheFirst) {
// Expected on a database: the second write waits for the first's uncommitted row.
} catch (ExecutionException failed) {
// Reported below, after the first transaction has been allowed to finish.
}
releaseFirst.countDown();
return List.of(
firstResult.get(LIMIT.toMillis(), TimeUnit.MILLISECONDS),
secondResult.get(LIMIT.toMillis(), TimeUnit.MILLISECONDS));
} catch (ExecutionException failed) {
throw new AssertionError("an overlapping write failed", failed.getCause());
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
throw new AssertionError("interrupted while racing two writes", interrupted);
} catch (TimeoutException stuck) {
throw new AssertionError("an overlapping write did not finish", stuck);
} finally {
releaseFirst.countDown();
threads.shutdownNow();
}
}
private static void await(CountDownLatch latch) {
try {
if (!latch.await(LIMIT.toMillis(), TimeUnit.MILLISECONDS)) {
throw new IllegalStateException("the first write was never released");
}
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
throw new IllegalStateException(interrupted);
}
}
}