문제: src/sample-portfolio(311파일)와 src/Dockerfile.sample이 빌드 8곳,
registry, PR job, spotbugs 제외, 매뉴얼·leaf 문서 수십 곳에 얽혀 있다.
매뉴얼과 생성 명령이 예시를 맡게 된 뒤로 샘플은 유지 비용만 남았고,
문서 일부는 이미 없는 태스크(sampleOffTest)와 ArchUnit 규칙을 가리킨다.
고른 방법: 소유자 결정(2026-11-07)대로 샘플을 폴더째 지우고 역할은
옮기지 않는다. 샘플을 가리키던 것도 같은 변경에서 지운다.
- 빌드: registry 행, 루트 build.gradle의 샘플 태스크·의존·단계
(sampleWebContractCheck, :sample-portfolio:*, strict lane 단계),
app-bootstrap architectureTestRuntimeOnly, spotbugs 제외 3곳
- CI: ci-quality-gates.yml의 sample-portfolio job과 release-gate 칸
- 테스트: SampleRuntimeDefaultsContractTest, Dockerfile.sample 비교 테스트,
ArchUnit 규칙의 죽은 sample 패키지 제외. build-logic 테스트와
application-core 테스트의 가짜 이름은 example-app으로 바꾼다
- 문서: 매뉴얼 예시를 실제 코드(durable operation, identifier,
ErrorCodeRegistryMappingTest)로 바꾸고, 템플릿에 예가 없는 기법
(유일 제약 → 같은 409)은 규칙과 확인 방법만 적는다. 결정 색인의
샘플 전용 행은 "샘플과 함께 사라짐"으로 표시한다
버린 대안: 설계서 권장안(OpenAPI 스냅숏·웹 계약을 옮긴 뒤 삭제)은
소유자가 고르지 않았다.
위험·한계:
- 샘플 안에만 있던 검사(OpenAPI 스냅숏, Date 헤더, 가상 스레드 MDC
전파, 요청당 SQL 수 단언)가 함께 사라진다. 소유자가 남기라 하면
총괄이 따로 맡긴다.
- APP_CACHE_REDIS_ENABLED는 샘플이 읽지 않는 키라(설계서 가정과 다름)
지우지 않고 src/README.md 문장만 고쳤다. 제거 기한 2026-11-30은 그대로.
- docs/capability-status.md 「제거된 코드」 표와 docs/work/evidence.md의
샘플 경로는 이력이라 두었다.
검증(desktop, 트리 0525e14e, ~/t1-layout-logs/):
- ./gradlew :ci --warning-mode=fail rc=0 (502 executed, 83 from cache)
- :verifyStrictLaneStages --dry-run rc=0
- :app-bootstrap:documentContractTest rc=0
- -p build-logic check rc=0
- :verifyDependencyLocks rc=0
- python3 scripts/check-work-docs.py, 상대 링크 검사 rc=0
Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.2
BREAKING CHANGE: src/sample-portfolio, src/Dockerfile.sample, 샘플 태스크와 job이 없어진다. 샘플을 고쳐 쓰던 파생 서비스는 병합 때 수정 대 삭제 충돌이 난다. docs/upgrade/2026-11-maturity-review.md B-49.
659 lines
52 KiB
Markdown
659 lines
52 KiB
Markdown
# application-core — 설계 결정 참조
|
||
|
||
애플리케이션 유스케이스 계층. 패키지 루트: `dev.caskeleton.application`.
|
||
|
||
허용/금지 의존, 유스케이스 형태, 트랜잭션 모드, 명명 규칙 같은 **모듈 규칙**은
|
||
[CLAUDE.md](CLAUDE.md) 가 SSOT 다. 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를
|
||
모아둔 참조용 기록이다 — 코드를 읽다 "왜 이렇게 했나"가 궁금할 때 본다. 아래 설명은 별도
|
||
추적 ID를 몰라도 읽히도록 결정의 배경과 트레이드오프를 문장으로 풀어 둔다.
|
||
|
||
이 계층을 관통하는 큰 원칙 하나: **application-core 는 프레임워크-free 다.** Spring/JPA/HTTP
|
||
타입뿐 아니라 SLF4J/JUL/Logback/Log4j/Micrometer도 직접 들이지 않고, 필요한 인프라 능력
|
||
(트랜잭션·락·인가·알림·운영 진단 등)은 전부 구체적인 목적의 `*Port` 인터페이스로 추상화한다.
|
||
구현은 adapter 모듈에 있고 컴파일 타임엔 보이지 않는다. Gradle
|
||
`verifyApplicationCoreDependencyPurity`와 ArchUnit
|
||
`APPLICATION_HAS_NO_DIAGNOSTIC_FRAMEWORK`가 이 계약을 자동 검증한다.
|
||
|
||
Cache도 같은 원칙을 따른다. `cache` 패키지에는 cache-redis가 구현하는 `CacheRegionPort`와 그
|
||
값 타입만 있다. Redis key, codec, Micrometer 렌더링은 adapter가 소유한다.
|
||
|
||
---
|
||
|
||
## 메시징 semantic contract R1
|
||
|
||
`messaging.contract`와 `messaging.event`는 feature가 integration event를 동적 JSON이나 provider
|
||
타입으로 넘기지 않게 만드는 application 경계다.
|
||
|
||
- `IntegrationPayload` 구현은 feature가 소유한 불변 typed record다.
|
||
- `IntegrationEventContractContribution`은 contract ID와 payload version을 분리하고, exact final
|
||
record type token, 실제 record component 순서, repository-local schema resource/hash와
|
||
provider-neutral `ContractDescriptor`만 기여한다. assignable-type 탐색, `Class.forName`, Java
|
||
class-name routing, `Map`, raw JSON string/tree는 이 SPI에 들어오지 않는다.
|
||
- `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를
|
||
classpath 파일과 대조). 결과는 logical destination, exact US-ASCII
|
||
partition key, exact encoded envelope bytes, schema/envelope hash와 catalog/binding revision을
|
||
defensive copy로 보존한다.
|
||
- `ContractDescriptor`는 owner module, logical destination, serializer ID, ordering requirement,
|
||
payload/envelope byte limit, sensitivity classification, same-event requeue horizon만 표현한다.
|
||
physical topic, Kafka cluster/security topology는 deployment binding의 책임이다.
|
||
|
||
이 절의 타입은 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 도입 — 이 템플릿
|
||
범위에 비해 운영 비용이 크다.
|
||
|
||
---
|
||
|
||
## 유스케이스 계약 (usecase / command / query / capability)
|
||
|
||
### UseCase / CommandUseCase / QueryUseCase
|
||
|
||
- inbound port(헥사고날의 primary port)다. 모든 구체 유스케이스는 쓰기면 `CommandUseCase`,
|
||
읽기면 `QueryUseCase` 를 extends 해서 **연산의 종류를 타입에 박아 둔다.** 이렇게 해야
|
||
capability·트랜잭션 모드 같은 계약을 컴파일/ArchUnit 단계에서 강제할 수 있다. 클래스 이름은
|
||
반드시 `UseCase` 로 끝난다(ArchUnit 강제).
|
||
- 제네릭 입출력 타입(`<I, O>`)에는 web 요청 DTO·JPA 엔티티·외부 클라이언트 응답 타입이 올 수
|
||
없다. 입력은 `Command`/`Query`, 출력은 도메인 객체·도메인 프로젝션·`Void` 만 허용. 이 자리에
|
||
transport 타입이 들어오면 application 계층 경계가 깨진다.
|
||
|
||
### Command / Query (마커)
|
||
|
||
- 둘 다 마커 인터페이스. `Command` = 쓰기 의도, `Query` = 읽기 의도.
|
||
- 반드시 불변 타입(가능하면 `record`)이고 도메인 타입·원시 값 객체로만 구성한다. web DTO,
|
||
JPA 엔티티, 외부 응답 타입은 필드에 넣을 수 없다 — 이게 들어오면 transport 관심사가
|
||
application 계층으로 새는 것.
|
||
|
||
### UseCaseCapability (모든 유스케이스 필수 애너테이션)
|
||
|
||
- 모든 구체 `*UseCase` 클래스에 필수. 유스케이스의 **트랜잭션 모양·멱등성·리포지토리 접근·외부
|
||
호출 여부를 본문을 읽지 않고도** 알 수 있게 만든다. ArchUnit 이 모든 구체 inbound port 에 이
|
||
애너테이션이 일관되게 붙어 있는지 검사한다.
|
||
- 일관성 규칙(ArchUnit 으로 강제):
|
||
- `QueryUseCase` 구현은 `transactionMode = READ_ONLY` + `repositoryAccess = READ_REPOSITORY` 여야 한다.
|
||
- `transactionMode = REQUIRES_NEW` 는 outbox / audit / compensation 흐름 전용이다.
|
||
- 외부 `*Port`(outbound adapter 에 바인딩된 포트)를 호출하려면 `externalOutboundAllowed = true`
|
||
가 필요하다. 없으면 outbound 어댑터 호출 금지.
|
||
- `repositoryAccess` 가 `WRITE_REPOSITORY` 가 아닌 유스케이스는 리포지토리 포트의 쓰기
|
||
메서드(save/delete/update/insert)를 호출할 수 없다 — `read_only_use_cases_do_not_call_repository_write_methods`
|
||
규칙이 막는다. 단 정적 분석은 **직접 호출만** 잡으므로, helper/mapper 를 거친 쓰기는 리뷰가 본다.
|
||
- `bulkWrite = true` 는 `WRITE_REPOSITORY` 를 함께 요구한다(대량 쓰기도 결국 쓰기).
|
||
`bulk_write_capability_requires_write_repository_access` 가 강제.
|
||
- 이 애너테이션은 `docs/registries/capabilities.yaml` 의 7개 capability 를 코드로 구현한 것이며,
|
||
**코드가 SSOT** 다. 추가 플래그의 의미:
|
||
- `sensitiveRead` — PII/자격증명/비밀을 읽는 유스케이스 선언. 필드 단위 마커(엔티티 FQN +
|
||
필드명 테이블)와 자동 강제는 이 영역의 책임이고 아직 미구현이라,
|
||
지금은 리뷰 기반의 선언적 계약이다. 이 마커를 **도메인/JPA 엔티티 애너테이션으로 표현하면 안
|
||
된다**(프레임워크 의존이 도메인에 새는 것을 막기 위함).
|
||
- `bulkWrite` — 단일 트랜잭션에서 100행/배치를 초과하는 쓰기(registry 임계치 = 100). 임계치
|
||
미만이면 평범한 `WRITE_REPOSITORY` 선언으로 충분하다.
|
||
- `crossTenantAdmin` — 테넌트 경계를 넘는 admin 연산. cross-tenant 접근 정책 자체는
|
||
이 영역의 책임(여기선 어휘만 제공). single-tenant 유스케이스에 붙이면
|
||
리뷰 reject.
|
||
|
||
---
|
||
|
||
## 트랜잭션 경계 (transaction)
|
||
|
||
### TransactionPort
|
||
|
||
- **존재 이유**: application 유스케이스가 `org.springframework.transaction.annotation.Transactional`
|
||
을 import 하지 않고도 트랜잭션 의도를 선언하게 하기 위한 추상화다. 구현(보통
|
||
`SpringTransaction`)은 persistence adapter 가 Spring `PlatformTransactionManager` 로 제공한다.
|
||
application/domain 을 프레임워크-free 로 유지하는 핵심 장치.
|
||
- 네 가지 경계:
|
||
- `inWrite` — REQUIRED + read-write, `READ_COMMITTED`. command 유스케이스 기본.
|
||
- `inRootWrite` — 물리 root 전용 REQUIRED + read-write, `READ_COMMITTED`. 실제 ambient
|
||
transaction 이 하나라도 있으면 action 실행 전에
|
||
`NestedRootTransactionRejectedException` 으로 거부한다. 성공 값은 commit 이 끝난 뒤에만
|
||
호출자에게 반환되며, commit 실패는 그대로 전파된다.
|
||
- `inRead` — REQUIRED + read-only, `READ_COMMITTED`. query 유스케이스 기본.
|
||
- `inNew` — REQUIRES_NEW + read-write. UseCaseCapability 에 `REQUIRES_NEW` 를 명시한
|
||
유스케이스(outbox/audit/compensation)에서만 허용.
|
||
- **root-only 사용 조건**: `inRootWrite` 는 join 가능한 일반 command 경계의 대체물이 아니다.
|
||
외부 효과를 commit 이후에만 시작해야 하는 orchestration처럼 물리 root를 증명해야 하는 경우에만
|
||
쓴다. 기존 transaction 안에서 `REQUIRES_NEW` 로 몰래 분리하지 않고 fail-fast하므로, 호출자는
|
||
transaction 없는 진입점에서 이 경계를 시작해야 한다.
|
||
- **콜백 시그니처(D11)**: 네 메서드 모두 `Supplier`/`Runnable` 을 받아 checked exception 을 던질
|
||
수 없다. Spring `TransactionCallback<T>` 제약과 동일하다. 그래서 호출자는 도메인 checked
|
||
exception 을 `RuntimeException` 하위로 감싸야 한다(`DomainException extends RuntimeException`).
|
||
`IOException` → `UncheckedIOException`, `SQLException` 은 Spring `DataAccessException` 계층이
|
||
자동 변환한다. 콜백 안에서 던진 `RuntimeException` 은 롤백 + 호출자 전파.
|
||
- **`inNew` 풀 사이징 비용(D12)**: REQUIRES_NEW 는 바깥 트랜잭션의 커넥션을 잡아둔 채 **새 물리
|
||
JDBC 커넥션을 추가로** 잡는다. 즉 미완료 `inNew` 호출 하나당 풀에서 커넥션 하나를 더 쓴다.
|
||
|
||
```
|
||
hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1
|
||
```
|
||
|
||
여기서 `max_inNew_depth` 는 스레드당 미완료 `inNew` 중첩의 최대 깊이다.
|
||
**금지**: 많은 레코드를 도는 루프 안에서 `inNew` 호출(예: per-row outbox dispatch). 풀 고갈 +
|
||
데드락 위험. 레코드를 한 번의 `inNew` 안에서 배치 처리하거나, 루프를 트랜잭션 경계 밖으로 빼라.
|
||
- **금지 목록**: `NESTED`/`NEVER` propagation, `READ_UNCOMMITTED` isolation, application 패키지에서
|
||
`@Transactional` 직접 사용, `inRootWrite` 의 ambient transaction 진입, `inNew` 의 per-record
|
||
루프 호출.
|
||
|
||
### TransactionMode
|
||
|
||
- `WRITE` / `READ_ONLY` / `REQUIRES_NEW`. TransactionPort API 와 UseCaseCapability 양쪽에서 쓰여,
|
||
유스케이스의 트랜잭션 계약을 본문 없이 드러낸다.
|
||
- `READ_ONLY` 일 때 persistence adapter 는 `readOnly = true` 를 켜서 드라이버 읽기 최적화
|
||
(Hibernate flush-mode MANUAL 등)를 적용하는 것이 좋다.
|
||
|
||
### Isolation
|
||
|
||
- `READ_COMMITTED` 가 고정 기본값이고, **모든 트랜잭션 템플릿에 명시적으로** 설정한다. vendor
|
||
기본값에 위임하지 않는 이유: 엔진마다 기본 isolation 이 다르다(PostgreSQL = READ COMMITTED,
|
||
MySQL InnoDB = REPEATABLE READ). 위임하면 같은 코드가 DB 에 따라 다른 isolation 으로 도는
|
||
silent 위험이 생긴다.
|
||
- `REPEATABLE_READ` / `SERIALIZABLE` 은 쓰기 무거운/읽기 일관성 유스케이스를 위한 명시적
|
||
opt-in. `READ_UNCOMMITTED` 는 금지라 enum 에 아예 선언하지 않았다.
|
||
- 단, 더 엄격한 레벨을 TransactionPort 호출 경로로 라우팅하는 per-use-case 선택 메커니즘은
|
||
관련 추상화 설계와의 공동 변경이라 아직 `planned` 다.
|
||
그전까지 이 상수들은 **어휘만** 선언하고, 실제 호출 경로는 `READ_COMMITTED` 로 고정된다.
|
||
|
||
---
|
||
|
||
## 인가 (security)
|
||
|
||
인증("누구냐")은 web/security adapter 책임이고, 이 패키지는 인가("이걸 해도 되냐")만 소유한다.
|
||
|
||
### AuthorizationPort
|
||
|
||
- 제품 인가 enforcement point(PEP). 인증된 호출자가 권한이 필요한 연산을 수행해도 되는지
|
||
결정한다. 인증된 principal 의 raw role 을 입력으로 받는다(인증 자체는 베이스라인 소유).
|
||
- **왜 포트인가, `@PreAuthorize` 가 아니라**: Spring method-security 애너테이션은 빈을
|
||
`org.springframework.security` 타입에 묶는다. application/domain 은 프레임워크-free 여야 하므로
|
||
(TransactionPort 선례), enforcement *결정* 은 평범한 Java 포트로 표현하고 Spring 의존
|
||
enforcement *메커니즘*(커스텀 `AuthorizationManager`)은 web adapter 에 둔다.
|
||
- **fail-closed**: 호출자가 필요한 권한을 가진 경우에만 정상 반환한다. 그 외(미지 role, role 없음,
|
||
매핑 누락)는 전부 `AuthorizationDeniedException`.
|
||
|
||
### RequiresPermission (애너테이션)
|
||
|
||
- 인증된 호출자가 가드된 유스케이스를 호출하려면 가져야 하는 `Permission` 을 선언한다. 값은
|
||
`resource:action` 토큰(예: `"worklog:close"`). `@UseCaseCapability` 패턴을 그대로 따라, 유스케이스가
|
||
요구하는 권한을 본문 없이 보이게 한다.
|
||
- **순수 선언 — Spring-free**: Spring Security 타입을 일절 담지 않는다. 실제 enforcement 는 web
|
||
adapter 의 `RequiresPermissionAuthorizationManager` 가 RUNTIME retention 으로 이 애너테이션을
|
||
읽어 `AuthorizationPort` 에 위임한다. enforcement 가 Spring AOP 프록시를 거치므로
|
||
self-invocation 이나 비-Spring 빈 호출은 우회된다 — 모든 mutating 진입점을 가드하는 책임은
|
||
아키텍처 강제 규칙 몫이다.
|
||
- **적용 대상**: skeleton 기본은 mutating/민감 유스케이스(`repositoryAccess = WRITE_REPOSITORY`)에
|
||
필수, public read 는 항상 면제(D4). 타입/메서드 어디에도 붙일 수 있다.
|
||
|
||
### AuthorizationPrincipal
|
||
|
||
- `AuthorizationPort` 가 소비하는 프레임워크-free 호출자 뷰 — IdP subject + 호출자의 raw role
|
||
이름. web adapter 는 Spring 인지 principal(`AuthenticatedPrincipal`, Keycloak 스타일 raw role)을
|
||
노출하지만 application 계층은 그 타입을 import 할 수 없으므로, enforcement point 가 이 추상으로
|
||
내려 매핑한다.
|
||
- **role 은 raw, Spring authority 가 아니다**: role set 은 IdP 가 발급한 그대로의 문자열
|
||
(`"admin"`, `"user"`)이며 `ROLE_*` GrantedAuthority 형태가 아니다. role→permission 해석이 raw
|
||
이름을 키로 쓰므로(D3), 둘을 섞으면 권한 0개로 해석돼 fail-closed denial 이 된다.
|
||
|
||
### AuthorizationDeniedException
|
||
|
||
- 인증된 호출자가 필요한 `Permission` 을 못 가졌을 때 `AuthorizationPort` 가 던진다.
|
||
- **프레임워크-free, application 소유**: application 계층은 Spring Security 에 의존할 수 없어
|
||
Spring `AccessDeniedException` 을 던질 수 없다. web adapter 의 method-security enforcement
|
||
point 가 경계에서 이 예외를 잡아 Spring authorization 실패로 번역하고, error pipeline 이
|
||
`AUTHZ_INSUFFICIENT_PERMISSION` 403 으로 매핑한다(코드 SSOT 는 베이스라인 소유).
|
||
- **fail-closed**: denial 은 필요한 권한과 호출자 subject 만 담고, 호출자의 *유효 권한 집합* 은
|
||
절대 담지 않는다(인가 표면을 클라이언트에 노출하지 않기 위함).
|
||
|
||
---
|
||
|
||
## 멱등성 (idempotency)
|
||
|
||
application 계층이 claim·replay·복구 **정책** 을 소유하고, 저장은 `IdempotencyStorePort` 로
|
||
위임한다. 패키지는 `dev.caskeleton.application.idempotency` 하나다. 예전 V1(`IdempotencyScope`,
|
||
`tryBegin/complete/discard`)은 삭제됐고, owner-safe 계약이 유일한 세대다.
|
||
|
||
### IdempotencyExecutor
|
||
|
||
- application 유스케이스 경계에서 멱등 실행을 조율한다. 입력은 `IdempotencyScopeDigest`,
|
||
`RequestFingerprint`, caller 가 응답 유실 뒤에도 보관하는 `IdempotencyClaimAttempt`
|
||
(`newAttempt(operationId)` 로 만든다), `IdempotentAction`, `IdempotentResponseCodec` 이다.
|
||
- 흐름: **claim → markExecutionStarted → action 실행 → complete(또는 markFailed)**.
|
||
- `COMPLETED` record 는 저장된 응답을 codec 으로 재생한다.
|
||
- 같은 scope 에 다른 fingerprint → `IdempotencyRequestMismatchException` → 422.
|
||
- 다른 owner 가 진행 중 → 기다리지 않고 바로 `IdempotencyInFlightException` → 409.
|
||
- store 응답이 유실(`INDETERMINATE`)되면 `inspect` 로 실제 상태를 읽어 이어가거나 멈춘다.
|
||
- 모든 상태 전이는 owner 핸들(owner token + attempt + operation ID + state revision)을
|
||
compare-and-set 으로 검증한다. 전이가 성공하면 revision 이 올라간 새 핸들을 다음 호출에 쓴다.
|
||
- action 결과는 `IdempotentAction.Outcome` 으로 분류한다. `RetryableNoEffect` 만 재시도 가능한
|
||
실패로 기록하고, `EffectUnknown` 이나 그냥 던진 예외는 "효과 불명"(`ABANDONED`)으로 남긴다.
|
||
한 번 실행됐을지 모르는 작업을 재시도로 두 번 돌리지 않기 위해서다.
|
||
- processing lease 와 replay TTL 은 따로 간다. 넘겨받을 수 있는 것은 만료된 `CLAIMED` 와 재시도 가능한
|
||
실패뿐이고, 다음 claim 이 누구든 넘겨받는다 — 같은 attempt 를 다시 보낸 caller 도 새 attempt 번호로
|
||
넘겨받는다(라운드6 RR6-02-01: 전에는 같은 attempt 가 이 기록을 재생받아 시작을 다시 거절당했다). 넘겨받기 전
|
||
핸들은 같은 attempt 가 들고 있어도 낡은 핸들이라 시작이 확인되지 않는다. 이미 적용된 전이(start·renew·
|
||
complete·markFailed·release)를 "이미 처리됨"으로 확인받는 것은 그 전이를 적용한 핸들뿐이다. 넘겨받은 뒤에
|
||
일어난 complete·markFailed 를 넘겨받기 전 핸들로 다시 보내면 `NOT_OWNER` 다(2026-11-06 소유자 결정). renew 를
|
||
적용한 핸들로 start 해도 `NOT_OWNER` 다 — 기록은 그 핸들보다 revision 이 하나 높지만 거기로 옮긴 것은 start 가
|
||
아니라 renew 다. markFailed 를 적용한 핸들이 다른 disposition 으로 다시 보내면 `OPERATION_CONFLICT`(기록된 실패는
|
||
그대로), retention 만 다르면 "이미 처리됨"이다. retention 은 complete 의 replay TTL 처럼 비교하지 않는다(2026-11-07
|
||
소유자 결정). 한 attempt 를
|
||
두 호출이 동시에 쓰는 것은 가려내지 못하므로 재시도는 앞 호출이 돌아온 뒤에 한다.
|
||
만료된 `EXECUTING` 은 다른 caller 에게 `RECOVERY_REQUIRED` 로 답하되 기록은 그대로 둔다. 주인이 늦게
|
||
보고한 결과·실패는 기록된다 — 먼저 온 보고 하나만 남고 뒤의 보고는 거절된다(2026-11-04 소유자 결정,
|
||
재리뷰 RR5-01-03). lease 가 이미 끝났으면 주인도 시작(`markExecutionStarted`)과 `renew` 를 할 수 없고
|
||
`LEASE_EXPIRED` 를 받는다. 이 값은 `NOT_OWNER`(기록이 남에게 넘어감)와 다르다: 시작 전이면 아무것도
|
||
돌지 않았고 다음 claim 이 넘겨받으며, executor 는 503 `IDEMPOTENCY_UNAVAILABLE`(실행 전 거부)로 답한다.
|
||
실행 중이면 주인은 여전히 `complete`·`markFailed` 할 수 있다(RR5-01-02).
|
||
- 생성은 app-bootstrap `IdempotencyProviderSelectionConfig` 가 한 번 한다(`IdempotencySettings`:
|
||
processing lease 30s, replay TTL 24h(최대 72h), failure retention 24h(replay TTL 이상), codec id `json-v2`,
|
||
policy revision 2). 유스케이스나 서비스 설정이 직접 만들지 않는다.
|
||
- 이 계약은 요청 재생(replay) 근거를 남길 뿐이다. store 와 비즈니스 DB 사이의 exactly-once 를
|
||
보장하지 않는다.
|
||
|
||
### IdempotencyStorePort
|
||
|
||
- provider 중립 owner-safe 상태 기계 포트. 메서드: `newClaimAttempt`, `claim`,
|
||
`markExecutionStarted`, `renew`, `complete`, `markFailed`, `releaseBeforeExecution`, `inspect`.
|
||
- 상태: `CLAIMED` / `EXECUTING` / `COMPLETED` / `FAILED_RETRYABLE` / `ABANDONED`(`IdempotencyState`).
|
||
- 구현은 provider 하나만 붙는다: `redis`(`adapter:outbound:cache-redis`
|
||
`RedisIdempotencyStoreAdapter`) 또는 `postgresql`(`adapter:outbound:persistence-jpa`
|
||
`PostgreSqlIdempotencyStore`). `app.capabilities.idempotency.provider` 로 고르고
|
||
기본값은 `disabled` 다. store 가 정확히 하나가 아니면 기동을 거부한다.
|
||
- **in-memory 프로덕션 구현 금지**. 테스트용 `InMemoryIdempotencyStore` 는 testFixtures 에만 있다.
|
||
|
||
### IdempotencyScopeDigest
|
||
|
||
- 멱등 요청의 정체성. principal·클라이언트 key·operation code 를 **caller 가 먼저 versioned
|
||
HMAC-SHA-256 으로 digest** 한 값이다(`digest`, `keyDigestVersion`, `operationCode`).
|
||
- raw 클라이언트 key 와 principal 은 executor·store·로그·메트릭 어디에도 닿지 않는다. 예외
|
||
메시지의 진단 문자열도 이 digest 로만 만든다.
|
||
- digest 를 만드는 쪽(키 링, 버전 교체)은 adapter 나 유스케이스 소유다.
|
||
|
||
### RequestFingerprint
|
||
|
||
- 요청 body 의 SHA-256 지문(D8). 같은 scope 인데 body 가 다르면(지문이 다르면) 클라이언트
|
||
버그로 보고 executor 가 422 로 거부한다. null/빈 body 는 zero-length payload 지문으로 취급해
|
||
빈 replay 의 일관성을 지킨다.
|
||
- **SHA-256 선택(표준이 강제한 값 아님 — 스켈레톤 기본 선택)**: MD5/SHA-1 대비 충돌 저항성 때문에
|
||
SHA-256 을 골랐다 — 인용 가능한 표준이 강제한 것도, 측정된 성능 근거가 있는 것도 아니다. body
|
||
**정규화**(JSON 키 순서·공백·인코딩)는 의도적으로 적용하지 않는다 — 전송된 raw 바이트를 그대로
|
||
해시한다. 정규 동등성이 필요한 caller 는 `ofSha256` 호출 전에 직접 정규화해야 한다. 안 하면 키
|
||
순서만 바뀐 의미상 동일 replay 가 false mismatch 가 된다(부하와 실제 요청 형태로 검증 필요).
|
||
- `NoSuchAlgorithmException` catch 는 도달 불가다(SHA-256 은 모든 JDK 에 필수). 그래서
|
||
`IllegalStateException` 으로 감싼다.
|
||
|
||
### 멱등성 값/계약 타입 (StoredResponse · Codec · Action)
|
||
|
||
- `StoredResponse` — 완료된 응답의 불투명 직렬화 표현으로, 중복 caller 에게 그대로 재생된다(§B).
|
||
어디에 어떻게 저장되는지는 provider 관심사다. PostgreSQL store 는 8 KiB 이하 응답만 행에
|
||
inline 으로 저장하고, 넘으면 거부한다(별도 object store 경로는 없다).
|
||
- `IdempotentResponseCodec` — 유스케이스 결과를 `StoredResponse` payload 로 직렬화/역직렬화.
|
||
application 은 wire-format 중립이다 — 구체 JSON 인코딩은 `R` 의 응답 모양을 아는 adapter 가
|
||
소유하고(예: web-advanced `JsonIdempotentResponseCodec`), executor 는 그 문자열을 store 로
|
||
왕복시키기만 한다.
|
||
- `IdempotentAction` — 실행할 작업. 결과를 `Outcome.Success` / `RetryableNoEffect` /
|
||
`EffectUnknown` 으로 돌려준다.
|
||
- complete/fail/release 재호출은 operation ID 와 result digest 가 같을 때만 이전 결과로 재생한다.
|
||
|
||
### 멱등성 예외 (공통 패턴)
|
||
|
||
- `IdempotencyRequestMismatchException`(422 `IDEMPOTENT_REQUEST_MISMATCH`),
|
||
`IdempotencyInFlightException`(409 `IDEMPOTENT_IN_FLIGHT`),
|
||
`IdempotencyUnavailableException`(실행 전 거부: store 에 닿지 못함, 또는 claim 의 lease 가 시작 전에 끝남),
|
||
`IdempotencyRecoveryRequiredException`(첫 시도가 효과를 냈는지 증명하지 못함).
|
||
- 모두 **프레임워크-free, application 소유**(`AuthorizationDeniedException` 선례). web adapter 가
|
||
경계에서 HTTP 코드로 매핑한다. 진단 메시지는 scope digest 만 **로그용으로** 담고, 클라이언트에는
|
||
핸들러가 고정 client-safe 메시지로 대체한다(fingerprint 자체는 노출 안 함).
|
||
- retryable: mismatch 는 `false`(body 를 고쳐야 한다). in-flight 는 `true`: 결과 불명. 같은
|
||
`Idempotency-Key`로 `Retry-After` 뒤 재전송. 새 키 금지(`docs/web/http-contract.md` §2). recovery-required 는 재생도 재실행도 안전하지 않다 — 비즈니스
|
||
데이터로만 판단할 수 있다.
|
||
|
||
---
|
||
|
||
## 트랜잭셔널 아웃박스 릴레이 (outbox)
|
||
|
||
핵심 패턴: 비즈니스 쓰기와 같은 트랜잭션에 이벤트를 append → 별도 relay 가 짧은 트랜잭션으로
|
||
claim → 트랜잭션 밖에서 발행 → at-least-once 보장.
|
||
|
||
### OutboxAppendPort
|
||
|
||
- 트랜잭셔널 아웃박스에 새 이벤트를 append 하는 outbound 포트.
|
||
- **dual-write 금지(D2)**: 반드시 이벤트를 만든 비즈니스 연산과 **같은 DB 트랜잭션 안에서**
|
||
호출해야 한다(그 트랜잭션은 caller 가 `TransactionPort.inWrite` 로 연다). 트랜잭션 밖에서, 또는
|
||
비즈니스 연산과 다른 트랜잭션에서 호출하면 dual-write 금지 위반이다 — 비즈니스는 커밋됐는데
|
||
outbox append 가 안 되거나(또는 그 반대) 이벤트가 silent 손실/허위 방출된다. 따라서 구현은
|
||
내부에서 새 트랜잭션을 열면 안 되고, 바깥 트랜잭션에 참여해야 한다.
|
||
|
||
### OutboxStorePort
|
||
|
||
- relay 측에서 outbox store 에 접근하는 포트. 모든 mutating 연산
|
||
(`claimBatch`/`markPublished`/`markFailed`/`markDeferred`/`releaseLease`/`markDead`)은 relay 유스케이스가 소유한
|
||
`TransactionPort.inWrite` 경계 안에서 호출하며, 구현은 자체 트랜잭션을 열지 않는다.
|
||
- **claim 의미(I4 / I6)** — `claimBatch` 가 적격 행을 atomic 하게 `IN_FLIGHT` 로 전이시킨다:
|
||
- 적격 행: `PENDING`, `next_attempt_at <= now` 인 `FAILED`, `next_attempt_at <= now` 인
|
||
`IN_FLIGHT`(고아 in-flight — I6 timeout 재사용).
|
||
- **FIFO 게이트(I4)**: 같은 `aggregate_id` 의 더 이른 `occurred_at` 행이 아직 `PUBLISHED` 가
|
||
아니면 그 aggregate 의 뒤 행들은 skip 한다. `DEAD` 행도 그 aggregate 큐를 막는다(strict
|
||
FIFO — 해제하려면 runbook 개입 필요).
|
||
- claim 후: `status = IN_FLIGHT`, `attempt_count += 1`,
|
||
`next_attempt_at = now + inFlightTimeout`, `lease_owner = owner`, `lease_token += 1`.
|
||
claim 결과는 행마다 `OutboxLease(event, owner, token)`이다.
|
||
- 순서: adapter 는 claim 쿼리에 `ORDER BY occurred_at ASC` 를 쓰는 게 좋고, relay 도 받은
|
||
배치를 방어적으로 재정렬한다.
|
||
- **in-flight timeout 재사용(I6)**: `next_attempt_at` 컬럼을 in-flight 고아 timeout 으로
|
||
재사용한다. relay 인스턴스가 죽어 `IN_FLIGHT` 로 남은 행이 `next_attempt_at` 을 지나면 다음
|
||
폴링에서 다시 claim 가능해진다. 별도 `claimed_at` 컬럼 없이 at-least-once 전달을 보장하는 트릭.
|
||
- **lease fencing**: in-flight timeout 뒤 다른 relay 가 행을 다시 claim 할 수 있으므로 완료
|
||
(`markPublished`/`markFailed`/`markDead`)는 lease 를 받아, 행이 아직 `IN_FLIGHT` 이고 owner·token
|
||
이 같을 때만 적용된다. 결과는 `OutboxCompletion.APPLIED`/`STALE` 이고 `STALE` 이면 아무것도 쓰지
|
||
않는다. 그래서 timeout 을 넘겨 멈췄던 relay 가 행을 넘겨받은 relay 의 결과를 덮지 못한다.
|
||
relay 는 `STALE` 을 `Outcome.STALE` 로 남기고 `reportStaleCompletion` 으로 알린 뒤 넘어간다.
|
||
owner 는 relay 인스턴스마다 한 번 만든 UUID 다. fake 는 testFixtures `InMemoryOutboxStore`,
|
||
계약은 `OutboxLeaseFencingContract`(fake 와 PostgreSQL adapter 가 같은 계약을 통과).
|
||
- `countByStatus` / `oldestUnpublishedAgeSecondsByEventType` 는 메트릭 게이지
|
||
(`outbox.pending.size`, `outbox.publisher.lag`)의 데이터 소스다. 트랜잭션 밖 read-only
|
||
(metric-scrape 경로)로 호출된다.
|
||
|
||
### OutboxMessagePublishPort
|
||
|
||
- claim 된 outbox 이벤트를 메시지 브로커에 발행하는 outbound 포트.
|
||
- **fail-closed 계약(I8)**: 발행 실패는 반드시 `RuntimeException` 으로 표면화해야 한다. 구현은
|
||
예외를 삼키거나 실패 시 log-and-return 하면 안 된다. 일반적인 fail-open 메시징 publisher(잡고
|
||
로그 후 정상 반환)와의 **의도적·문서화된 차이** 다 — relay 의 Failure condition 이 발행 실패를
|
||
예외로 관측해야 FAILED/DEAD 전이 + typed failure report를 구동할 수 있기 때문. 삼킨 실패
|
||
(예외 없음·전이 없음·report 없음)가
|
||
금지 조건이다 — 행이 영원히 `IN_FLIGHT` 로 남고, aggregate FIFO 큐가 조용히 막히며, 메트릭엔
|
||
이상이 안 보인다.
|
||
- **호출 위치**: relay 유스케이스가 **트랜잭션 밖에서** 호출한다. 짧은 `inWrite` 로 배치 claim →
|
||
트랜잭션 해제 → 발행 → 결과별로 다시 짧은 `inWrite` 로 상태 갱신. 브로커 호출이 진행되는 동안
|
||
트랜잭션 보유 시간을 최소화한다.
|
||
|
||
### PublishPendingOutboxEventsUseCase (릴레이 본체)
|
||
|
||
- pending outbox 이벤트를 claim 해 브로커에 발행하는 relay 유스케이스.
|
||
- **알고리즘(claim short, publish outside tx)**:
|
||
1. 짧은 write 트랜잭션 안에서 배치를 claim 한다.
|
||
2. `occurred_at` 오름차순으로 방어적 정렬(claim 쿼리도 정렬하지만, adapter 가 안 해도 relay 가
|
||
FIFO 를 강제한다).
|
||
3. 각 이벤트를 **트랜잭션 밖에서** 발행하고 결과로 상태 머신을 구동한다:
|
||
- 발행 성공(`CONFIRMED`) → `inWrite { markPublished }` → `PUBLISHED`.
|
||
- 확정 거부(`REJECTED_BEFORE_SEND`·`REJECTED_AFTER_BROKER`) → 시도 예산과 무관하게 바로 `markDead`.
|
||
- 일시적 실패(`AMBIGUOUS`·`REJECTED_RETRYABLE`, 즉 `OutboxPublishOutcome.retryable()`) →
|
||
시도 예산을 쓰지 않고 항상 `markDeferred(nextAttemptAt, failureCode)`(FAILED 전이 + 미룬 시도로 기록). broker 정지·종료 중·permit 부족·
|
||
credential 교체는 모든 행을 같은 방식으로 실패시키고 저절로 끝나므로, 예산을 쓰게 하면 몇 분
|
||
장애가 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를 영원히 막지 않게 하는 장치다.
|
||
`budgetedAttemptCount() = attemptCount - deferredAttemptCount`: 미룬(일시적 실패) claim은 빼고,
|
||
결과를 남기지 못하고 죽은 claim(lease 만료)은 센다. 그래서 장애를 오래 기다린 행도 그 뒤 예산을
|
||
온전히 받는다(예전 한계: `attemptCount`가 일시 실패 claim까지 세어 첫 발행 예외에서 바로 DEAD).
|
||
재시도 지연은 계속 전체 `attemptCount`로 늘어나 긴 장애에서도 최대 5분 간격을 유지한다.
|
||
- 멈춤 요청(`PublishPendingOutboxEventsCommand.stopRequested`, 종료 중인 scheduler가 건다): 지금
|
||
발행을 끝낸 뒤 남은 claim은 발행하지 않고 `releaseLease(now)`로 놓는다 → `PENDING`, 시도 수에서
|
||
그 claim을 빼고 바로 claim 가능. 결과는 `RELEASED`.
|
||
- 전이를 먼저 성공시킨 뒤 해당 typed failure report를 보낸다.
|
||
- `nextAttemptAt` 의 기준 시각은 **그 행이 실패한 시각**(`clock.instant()`)이다. 회차 시작
|
||
시각을 쓰면 broker가 멈춘 동안 publish 하나가 deadline(약 5초)을 다 쓰므로 배치 뒤쪽 행은
|
||
표시되는 순간 이미 재시도 시각이 지나 있어 지연이 사라진다.
|
||
- **발행 실패는 절대 삼키지 않는다**: relay 는 각 발행 예외를 잡아 FAILED/DEAD 상태 머신을
|
||
구동하고, 성공한 전이만 `OutboxRelayFailureReportPort`로 보고한 뒤 rethrow 하지 않는다
|
||
(스케줄러 루프가 다음 이벤트로 계속 가야 하므로). 상태 전이가 실패하면 예외가 전파되고 report는
|
||
없다. reporter가 `RuntimeException`을 던져도 persisted outcome을 바꾸거나 다음 이벤트를 막지
|
||
못한다.
|
||
- **안전한 allowlist report**: `OutboxRelayFailureReport`는
|
||
`code/eventId/eventType/aggregateId/correlationId/attemptCount/nextAttemptAt/cause`만 가진다.
|
||
payload, envelope bytes, whole `ClaimedOutboxEvent`, severity/template, arbitrary map은 타입 수준에서
|
||
전달할 수 없다. retry factory는 `OUTBOX_PUBLISH_FAILED`와 필수 `nextAttemptAt`, dead factory는
|
||
`OUTBOX_DEAD_LETTER`와 null retry time을 고정한다.
|
||
- **상태 갱신 실패는 시끄럽게 전파한다**: 발행 성공 후의 `markPublished` 실패는 store/인프라
|
||
에러지 발행 실패가 아니다. 따라서 FAILED/DEAD 머신을 구동하면 안 된다(이미 전달된 이벤트를
|
||
dead-letter 하는 꼴). 대신 스케줄러 catch 블록으로 전파되고, 행은 `IN_FLIGHT` 로 남아 고아
|
||
visibility-timeout 재claim 경로로 복구된다 → 재발행 → consumer dedupe 가 중복을
|
||
흡수(at-least-once). 배치 중간의 상태 갱신 실패가 그 tick 의 남은 배치를 중단시키는 것은
|
||
허용된다 — DB 가 실패 중이면 뒤따르는 갱신도 실패할 테고, 다음 tick 이 모든 `IN_FLIGHT` 고아를
|
||
재시도하기 때문.
|
||
- **수동 와이어링(@Service 아님, context 빈 아님)**: outbox-relay composition이 직접 생성한다
|
||
(`batchSize`·`inFlightTimeout` 같은 설정값이 필요해서 자동 등록이 안 된다). `UseCaseCapability`
|
||
는 빈 등록 방식과 무관하게 필수다(ArchUnit 강제). 그리고 **Spring 빈으로 등록하면 안 된다**:
|
||
relay를 부르는 것은 스케줄러뿐이고, 스케줄러 스레드에는 `Authentication`이 없다. 빈으로
|
||
노출하면 전송 계층이 권한 검사 없이 닿을 수 있다.
|
||
- **권한 선언 없음 — `@SystemInvoked`**: relay는 엔드유저가 아니라 시스템이 부르는 유스케이스라
|
||
`@RequiresPermission`을 달지 않고 `@SystemInvoked(reason = ...)`로 그 사실을 적는다. 예전의
|
||
`@RequiresPermission("outbox:relay")`는 D4 규칙을 통과시키려고 붙인 장식이었다(빈이 아니라 한
|
||
번도 검사되지 않았고, 빈이었다면 매 tick 거부됐다). ArchUnit D4는 `@SystemInvoked`를 권한 선언
|
||
대신 받고, `SYSTEM_INVOKED_USE_CASES_DECLARE_NO_PERMISSION`이 둘을 함께 다는 것을 막는다.
|
||
면제의 전제(사용자 요청이 닿지 않는다)도 코드가 지킨다: `@SystemInvoked` 빈은
|
||
`PermissionEnforcementGuard`가 기동을 실패시키고, `@SystemCaller`가 아닌 inbound adapter가 그 클래스에
|
||
의존하면 `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`가 빌드를 실패시킨다(review 2026-11-03
|
||
RR-01-02, RR-01-12). 메시지 소비자는 `@SystemCaller` handler가 use case를 직접 만든다(매뉴얼 09장
|
||
「소비」 4단계). 시스템 호출자 세 가지(조립 모듈의 스케줄러, `@SystemCaller` 메시지 handler,
|
||
`@SystemCaller` 예약 작업)와 각각 두는 곳은 매뉴얼 07장 「시스템이 부르는 쓰기」가 정본이다.
|
||
|
||
### OutboxBackoffPolicy
|
||
|
||
- relay 재시도 스케줄링 정책(I10). 이름과 달리 "full jitter" 가 아니다 — full jitter 는 0 을 고를
|
||
수 있고, relay 재시도가 실패한 그 순간에 다시 due 가 되면 안 된다.
|
||
- 공식: `base = 30s`, `maxDelay = 5m`, `maxAttempts = 3`, `delay = ceiling(attemptCount) + U[0, base]`,
|
||
`nextAttemptAt = failedAt + delay`. `ceiling` 은 shared-contract `Backoff` 의
|
||
`base × 2^(attemptCount-1)` 이고 `maxDelay`(5분)에서 멈춘다. `attemptCount` 는 방금 실패한
|
||
시도의 1-based 번호다. 예산 안(1·2회차)의 값은 30s·60s 그대로라 registry·runbook 숫자가 유지된다.
|
||
- `maxAttempts` 는 발행 예외(분류되지 않은 실패)에만 적용된다. 일시적 결과(`retryable()`)는 예산 없이
|
||
`maxDelay` 간격까지 늘어나며 계속 재시도된다. 그래서 broker가 돌아오면 늦어도 약 5분 30초 안에
|
||
적체가 저절로 빠진다.
|
||
- 버린 대안: `MAX_ATTEMPTS` 만 늘리기(장애 길이에 비례해 계속 키워야 하고 진짜 poison 행이 늦게
|
||
격리된다), 예산을 설정 키로 외부화(I10 — registry·runbook과 어긋난다; 일시적 실패가 예산을 쓰지
|
||
않으므로 장애 길이에 맞춰 예산을 조정할 이유도 사라졌다), 일시적 실패 시 `attempt_count` 되돌리기
|
||
(지수 간격을 키울 근거가 사라진다 — 그래서 별도 열 `deferred_attempt_count`(V20)로 센다).
|
||
- 더하는 spread 는 한 base 짜리 full jitter(`Backoff#fullJitter`, `[0, base]` 균등)이며 주입된
|
||
`RandomGenerator` 로 뽑는다. 0 을 반환하는 generator 를 주면 테스트가 결정적이 된다(I10).
|
||
- **상수는 고정이다(I10)**: `BASE_DELAY`·`MAX_ATTEMPTS`·jitter 범위는 설정 프로퍼티가 아니다.
|
||
외부화하면 registry alert 임계치(`error-codes.yaml` 의 `retry_after_seconds=30`)와
|
||
`outbox-publish-failed` runbook 이 실제 런타임 값과 어긋난다. 이 상수는 registry·runbook
|
||
업데이트와 **함께만** 바꾼다.
|
||
- 지수 계산의 overflow 는 `Backoff` 가 포화 연산으로 막는다.
|
||
|
||
### outbox 값/상태 타입 (Status · ClaimedOutboxEvent · RelayResult · Command)
|
||
|
||
- `OutboxEventStatus` — 행 상태 머신(D5). `PENDING → IN_FLIGHT → {PUBLISHED | FAILED | DEAD}`,
|
||
`FAILED → IN_FLIGHT`(재claim), `IN_FLIGHT 고아 → IN_FLIGHT`(I6). `DEAD` 는 FIFO 형제를 막는다 —
|
||
같은 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 다.
|
||
- `ClaimedOutboxEvent` — `claimBatch` 가 반환하는 claim-result 읽기 모델. append 된 validated event
|
||
(저장된 exact envelope bytes 에서 복원) + 현재 `status` + `attemptCount`. relay 가 `attemptCount` 로
|
||
다음 실패 시 dead-letter 여부를 결정한다. 옛 `OutboxEvent`/`NewOutboxEvent`/`LegacyOutboxAppendPort`
|
||
(free-text payload 모델)는 삭제됐다.
|
||
- `OutboxRelayResult` — relay 한 사이클의 결과. `claimedCount` + per-event outcome 목록. 내부
|
||
`Outcome` enum 이 `OutboxEventStatus` 를 재사용하지 않고 5값(PUBLISHED/FAILED/DEAD/STALE/RELEASED —
|
||
STALE 은 lease 를 잃어 결과를 쓰지 못한 경우, RELEASED 는 멈추는 relay 가 쓰지 않은 claim 을 놓은 경우)을
|
||
따로 두는 이유: relay 관점은 "이번 실행에서 무슨 일이 있었나" 이지 "행의 현재 영속 상태" 가
|
||
아니다(후자는 store 가 `OutboxEventStatus` 로 추적). 이 5값이 `outbox.publisher.published.total` 의
|
||
`outcome` label 이다(`docs/registries/metrics.yaml`, 계약 테스트가 비교).
|
||
- `PublishPendingOutboxEventsCommand` — relay 커맨드 마커. 스케줄러 구동이라 caller 파라미터가
|
||
없고, 모든 운영 파라미터는 생성 시점에 주입된다(IdempotencyExecutor 선례). 호출마다 새 인스턴스를
|
||
만들 필요가 없게 `INSTANCE` 싱글톤을 제공한다.
|
||
- `OutboxRelayFailureReportPort` / `OutboxRelayFailureReport` — confirmed FAILED/DEAD 상태를
|
||
adapter에 전달하는 framework-free outbound contract. 구조화 ERROR 필드와 runbook 렌더링은
|
||
messaging adapter가 소유한다.
|
||
|
||
### outbox V2 (삭제됨)
|
||
|
||
`outbox.v2`(immutable storage + polling delivery 포트·유스케이스)는 어떤 composition 도 조립하지
|
||
않은 세대라 2026-09-25 에 삭제했다(`docs/capability-status.md` "제거된 코드"). 그 설계에서 가져온
|
||
owner/token CAS 는 위 `OutboxStorePort` 의 lease fencing 이다.
|
||
|
||
---
|
||
|
||
## 분산 락 (lock)
|
||
|
||
application 계층은 락 획득/해제 계약만 알고, 실제 구현은 adapter 가 소유한다.
|
||
|
||
### DistributedLockPort
|
||
|
||
- 분산 락 획득 outbound 포트.
|
||
- **왜 이 포트가 있나(D2)**: 유스케이스는 락 클라이언트·Spring `LockRegistry`·advisory-lock SQL
|
||
을 직접 import 하면 안 된다. 이 포트가 application-core 안에서 협조적 상호배제를 위해 허용된
|
||
유일한 의존이다. adapter 구현(`JdbcLockRegistry` 멀티 인스턴스, `DefaultLockRegistry` 단일
|
||
인스턴스)은 `adapter-persistence` 에 있고 컴파일 타임엔 application 계층에 안 보인다.
|
||
- **try-lock + 유한 waitTime + 필수 leaseTtl(D5)**: `tryAcquire` 는 try-lock 이다 — 최대
|
||
`waitTime` 만 블로킹하고 held 핸들을 반환하거나 `LockAcquisitionTimeoutException` 을 던진다.
|
||
무한 블로킹은 금지(항상 유한 `waitTime` 공급). `leaseTtl` 은 JVM 이 `close()` 전에 죽어도
|
||
adapter 가 락을 유지하는 최대 시간으로, 죽은 보유자가 시스템을 무한 데드락 시키는 것을
|
||
막는다. `JdbcLockRegistry` 는 registry 기본 TTL 과 호출별 lock TTL 을 강제하고, in-process
|
||
`DefaultLockRegistry` 는 advisory(강제 없음)다.
|
||
- **트랜잭션 커밋 순서 불변식(D4)**: 반환된 핸들은 보호 작업의 DB 트랜잭션이 **커밋된 후에만**
|
||
해제해야 한다. 트랜잭션 안(커밋 전)에서 해제하면 lost-update 경합이 생긴다 — 두 번째 스레드가
|
||
락을 얻어, 첫 트랜잭션의 쓰기가 DB 에 보이기 전에 자신의 read-modify-write 를 시작한다.
|
||
- 올바른 패턴: `tryAcquire` → `try { txPort.inWrite(...) } finally { lock.close() }`(커밋 후 해제).
|
||
- 금지된 역순: `inWrite` 콜백 안에서 `lock.close()`(커밋 전 해제 → 다른 스레드가 stale 상태를 본다).
|
||
- **효율 락이지 정합성 락이 아니다(D6)**: 이 락은 경합·불필요한 재시도를 줄이는 *효율* 장치다.
|
||
정합성(중복·충돌 쓰기 방지)은 여전히 DB 제약(유니크 인덱스·낙관적 동시성)이 강제한다. 이 락
|
||
하나만 정합성 가드로 의존하면 안 된다.
|
||
- **lease 만료 시 해제(SI-LOCK-C5)**: TTL 기반 provider(`JdbcLockRegistry`)에서 보유자가
|
||
`close()` 하기 전에 lease 가 만료되면, 락 행은 이미 다른 인스턴스가 회수했을 수 있다. metered
|
||
`distributedLockProvider` 가 이를 로그 + 카운트 이벤트(`lock.lease.expired`)로 표면화하고
|
||
`close()` 는 정상 반환한다 — 만료가 caller 의 `finally` 를 터뜨리거나 보호 작업 자신의 예외를
|
||
가리지 않게 하기 위함.
|
||
- `leaseTtl` 이 provider 설정 TTL 을 초과하면 `IllegalArgumentException`. shipped 와이어링은 provider
|
||
설정과 같은 `LockSettings.leaseTtl()` 로 바인딩하므로 런타임엔 안 터지고, mis-wired caller/test 를
|
||
잡는 가드다.
|
||
|
||
### DistributedLock (핸들)
|
||
|
||
- 획득한 분산 락 핸들(`AutoCloseable`). `close()` 가 해제이고 `finally` 에서 한 번 호출하기에
|
||
안전하며, 구현은 idempotent 해야 한다(여러 번 close 해도 throw 금지).
|
||
- D4 커밋 순서 불변식은 `DistributedLockPort` 와 동일하다 — 커밋 후에만 `close`.
|
||
- `close()` 가 `AutoCloseable` 의 `throws Exception` 을 제거하도록 override 한 이유: 구현이 해제
|
||
시 checked exception 을 던지지 못하게 해서, caller 가 checked-exception 의식 없이 `finally` 에
|
||
둘 수 있게 하기 위함.
|
||
|
||
### LockAcquisitionTimeoutException
|
||
|
||
- `waitTime` 안에 락을 얻지 못하면 `tryAcquire` 가 던진다(D5).
|
||
- `OperationalError.LOCK_ACQUISITION_TIMEOUT`(CONFLICT, 409, retryable=true)을 운반한다. 락
|
||
경합은 일시적이다 — 현재 보유자가 임계 구역을 떠나거나 lease TTL 이 만료되면 재시도가
|
||
획득한다(D6 효율 락).
|
||
- `ApiErrorCarrier` 를 구현한다. 그래서 전송이 따로 처리기를 두지 않아도 web 은 409 +
|
||
`Retry-After: 1`(레지스트리 값), GraphQL·gRPC 는 같은 코드로 답하고, 4xx 라 서버 로그를 남기지 않는다. 전에는
|
||
carrier 가 아니어서 모든 전송이 500 `INTERNAL_ERROR`(재시도 불가)와 "unhandled" ERROR 로 답했다(재리뷰
|
||
RR7-01-04). `getMessage()`(key·waitTime 포함)는 클라이언트에 보내지 않고, 로그에도 남지 않는다. 4xx carrier 라
|
||
어느 전송도 남기지 않고, 락 adapter 도 timeout 을 남기지 않는다. 어느 락이 막혔는지 기록이 필요하면 호출자가
|
||
`key()` 를 직접 남긴다(엔티티 id 는 빼고). 운영 절차는 `docs/runbooks/lock-acquisition-timeout.md`
|
||
(`lock.acquisition` metric, `INT_LOCK` 보유자 조회)다(재리뷰 RR8-01-02).
|
||
|
||
---
|
||
|
||
## 알림 타입은 이 leaf에 없다 (application-notification)
|
||
|
||
`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에 삭제했다.
|
||
|
||
---
|
||
|
||
## 로그 가명화 포트 (observability)
|
||
|
||
### CorrelationIdPort
|
||
|
||
- 현재 application invocation의 correlation id를 `Optional<String>`으로 읽는 framework-free
|
||
경계다. application use case는 MDC나 SLF4J를 직접 알지 않는다.
|
||
- inbound web adapter가 sanitized `correlation_id` MDC 슬롯을 구현 세부로 읽는다.
|
||
- 값이 없거나 blank이면 event publisher는 생성한 event id를 correlation id로 재사용해 기존
|
||
self-correlation 동작을 유지한다.
|
||
|
||
### UserPrincipalPseudonymizerPort
|
||
|
||
- raw 보안 principal id 를, 값이 로그/MDC 에 쓰이기 전에 안정적 가명 토큰으로 바꾸는 outbound
|
||
포트.
|
||
- **null/blank 의미**: `rawPrincipal` 이 null/blank 면 null 을 반환한다. 가명화할 게 없으니, 이
|
||
경우 caller 는 `user_principal` MDC 키에 아무 값도 넣으면 안 된다.
|
||
- **안정 토큰 계약**: non-blank 입력에 대해 (1) 같은 입력 + 같은 salt 는 같은 salt epoch 안에서
|
||
항상 같은 출력을 낸다(안정), (2) raw principal 의 trivial 복원이 불가능하다(일방향 derivation
|
||
이지 인코딩·가역 변환이 아니다), (3) `user_principal` MDC 와 로그 라인에 안전하다.
|
||
- **알고리즘 SSOT**: 구체 알고리즘(90일 회전 salt 로 keyed 한 HMAC-SHA-256)은
|
||
이 영역의 책임다. 이 포트는
|
||
"보안 principal 을 가명 형태로 기록한다" 는 계약만 소유한다. 구현은 `adapter-identifier` 에
|
||
있고 `app-bootstrap` 이 와이어링한다.
|
||
- **계층**: 순수 Java 인터페이스다. 구현은 application-core/domain-core 에서 참조하면 안 된다.
|
||
consumer(`adapter-web` 의 `RequestLoggingFilter`)가 이 포트를 주입받아
|
||
`AuthenticatedPrincipal.idpUserId()` 를 가명화한 뒤 `MDC.put("user_principal", ...)` 한다.
|
||
|
||
### OutboxAggregateSequencePort (2026-11-01 리뷰 06-07)
|
||
|
||
- aggregate의 다음 순서 번호(`AggregateOrder.sequence`)를 append와 같은 caller 쓰기 트랜잭션에서 준다.
|
||
claim gate와 소비자가 이 번호로 "어느 변경이 나중인가"를 판단하므로 번호는 커밋 순서를 따라야 한다.
|
||
벽시계(예전 샘플의 epoch 마이크로초)는 인스턴스 사이 시계 차이·NTP 되돌림·같은 마이크로초 두 건에서
|
||
커밋 순서와 달라진다.
|
||
- 계약(`OutboxAggregateSequenceContract`, fake `InMemoryOutboxAggregateSequences`와 JPA 구현이 공유):
|
||
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가 없는
|
||
aggregate를 위한 것이다.
|
||
|
||
---
|
||
|
||
## 비밀 값 해석 (secret)
|
||
|
||
- `SecretSourcePort`와 `SecretReference`(`secret://<source>/<name>` 한 가지 표기)를 둔다. 예전에는
|
||
`CallBudget`과 함께 `outbound` 패키지에 묶여 있었다. 세 타입은 서로 관계가 없고 `outbound`는
|
||
내용이 아니라 방향을 말하는 이름이라, 2026-11-01 리뷰 01-10에서 내용별로 흩었다.
|
||
- `CallBudget`은 쓰는 곳이 object storage 계약(요청 record와 content 콜백 context)뿐이라
|
||
`application-objectstorage`의 `objectstorage.content`로, 항상 함께 다니는 `CancellationView` 옆에
|
||
옮겼다. 다른 전송(HTTP client·gRPC·GraphQL)은 각자의 deadline 타입을 쓴다.
|
||
- 포트 계약 `secret.testkit.SecretSourceContract`, fake `InMemorySecretSource`(testFixtures).
|