문제: 2026-11-01 성숙도 리뷰에서 High 21건·P1 25건이 나왔다. 결과를 모르는 일을 "확실함"으로 기록했다(발송 중 죽은 알림 재발송, 커밋 중 끊긴 쓰기를 재시도 가능으로 응답, 재시도 가능한 거부를 DEAD로). 중복을 DB가 아니라 코드 순서로 막았다(정산 job, 포스터 제목). 짝 프론트와 wire 계약이 달랐고(처리 중 409, Envelope null), JWT audience 검증이 기본으로 꺼져 있었고, 트레이스가 나가지 않았고, CI가 strict lane 14개를 한 번도 돌리지 않았다. 방법: 발견마다 실패하는 테스트를 먼저 쓰고 고쳤다. 주요 선택: - 알림 attempt는 처음부터 "시작 여부 모름"으로 쓴다(호출 직전 갱신은 쓰기가 하나 늘어 버림). - 정산 job claim은 lease·fence를 갱신하는 UPDATE 한 문장(처리 전체를 트랜잭션으로 감싸는 안은 외부 호출 동안 잠금을 잡아 버림). - 커밋 단계 연결 끊김은 DB_COMPLETION_UNKNOWN(재시도 불가). - 처리 중 409는 retryable=true + Retry-After: 2, Envelope null 필드는 web Jackson mixin으로 생략(shared-contract는 stdlib only). - 트레이싱은 자체 Tracer를 지우고 Boot 4 tracing·OTLP로. - strict lane을 단계에 연결하고 verifyStrictLaneStages가 고아를 막는다. 발견별 RED·GREEN·버린 대안은 리뷰 README 13절 표에 있다. 위험·한계: JWT 모드는 APP_SECURITY_JWT_AUDIENCE가 없으면 기동하지 않는다. 짝 프론트는 409 retryable과 Envelope 키 규칙을 맞춰야 한다. 이 커밋 시점에는 MinIO 공식 이미지가 사라져 MinIO 2 lane이 실패한다 (다음 커밋에서 대체 이미지로 해결). 검증: ci 통과. mainCheck·integrationCheck는 MinIO 2 lane만 실패(이미지 pull 거부). -p optional-platforms ci integrationCheck, performanceCheck, releaseCheck(-PgitRevision) 통과. Refs: docs/reviews/2026-11-01-maturity-review/README.md 2·13절 BREAKING CHANGE: JWT 모드에서 APP_SECURITY_JWT_AUDIENCE가 필수가 되고 role은 audience client와 realm 것만 읽는다. IDEMPOTENT_IN_FLIGHT가 retryable=true, Retry-After: 2로 바뀌고 Envelope는 null 필드를 보내지 않는다.
12 KiB
12 KiB
composition:outbox-relay — transactional outbox relay 조립
- Module ID:
composition-outbox-relay - Gradle path:
:composition:outbox-relay - Package:
dev.caskeleton.composition.outbox - 테스트:
./gradlew :composition:outbox-relay:test --console=plain
제공하는 것
outbox에 쌓인 event를 broker로 내보내는 relay를 조립한다. use case는 이 모듈을 부르지 않는다 —
use case는 OutboxAppendPort로 append만 하고, relay가 나머지를 한다.
composition:outbox-relay
└─ OutboxRelayAutoConfiguration app.outbox.enabled=true + OutboxStorePort 가 있을 때만
├─ OutboxSettings app.outbox.* strict 바인딩(오타는 기동 실패)
├─ OutboxRelayScheduler relay-enabled=true + OutboxMessagePublishPort 가 있을 때만,
│ PublishPendingOutboxEventsUseCase 를 fixed-delay 로 구동,
│ 종료 때 platform보다 먼저 멈춤(SmartLifecycle)
├─ OutboxMetrics outbox.pending.size / outbox.publisher.lag / published.total
└─ OutboxLeaderElectionToken SKIP LOCKED 가 리더 선출이라는 표시(로직 없음)
- 조립 순서:
PersistenceJpaAutoConfiguration(store)과MessagingBridgeRootAutoConfiguration(발행 포트) 뒤에 온다(afterName, 문자열이라 컴파일 의존이 없다). 둘 다 포트라서 이 모듈은 어떤 모듈 타입도 이름으로 부르지 않는다. - 발행 포트가 없으면 스케줄러를 만들지 않는다. messaging을 고르지 않은 배포는 PENDING row를 그대로 둔다(대역 publisher로 DEAD까지 소진하지 않는다).
- persistence-jpa 안이 아니라 여기 있는 이유: driven adapter는 use case를 만들거나 부르지 않는다
(ArchUnit
PERSISTENCE_DOES_NOT_DEPEND_ON_APPLICATION_SERVICES). - 설정 기본값:
app.outbox.*의 기본값은 store를 가진 persistence-jpa가config/module-defaults/persistence-jpa.yml로 싣는다(store와 reaper도enabled,reaper-interval,published-retention을 읽는다). 키의 선언과 검증은 이 모듈의OutboxSettings하나다.
추가할 한 줄
// app-bootstrap/build.gradle
runtimeOnly project(':composition:outbox-relay') // outbox relay
기본 조립에 있다. store(persistence-jpa + APP_OUTBOX_ENABLED=true)가 없으면 아무것도 만들지 않으므로
안전하다. 이 줄을 지우면 relay, metrics가 함께 빠진다(append한 row는 발행되지 않고 남는다).
필요한 env 키
전체 목록과 타입은 docs/registries/env-keys.yaml의 APP_OUTBOX_* 행이 SSOT다.
| 언제 | 키 |
|---|---|
| 항상 | persistence-jpa 줄과 그 연결 env, APP_OUTBOX_ENABLED=true |
| relay를 돌릴 때 | APP_OUTBOX_RELAY_ENABLED=true, 그리고 발행 capability(adapter:outbound:messaging-kafka 줄과 APP_MESSAGING_PRODUCER_ID, APP_MESSAGING_KAFKA_BROKERS) |
poll 주기·batch 크기·in-flight timeout·보존 기간은 env 키 없이 app.outbox.* 기본값으로
동작한다.
설계 결정 참조 (app-bootstrap에서 옮김)
이 모듈의 코드는 2026-09-28에 app-bootstrap autoconfigure/outbox에서 옮겨 왔다(소유자 결정 3). 아래 근거는 그때의 기록이다. OutboxSettings는 이제 strict 바인딩이고 enabled도 선언한다.
OutboxRelayAutoConfiguration
- 릴레이 use case 를
@Service가 아니라 이 모듈에서 수동 조립한다.PublishPendingOutboxEventsUseCase는batchSize와inFlightTimeout같은 설정값을 생성자로 받아야 하는데,application-core는 설정(OutboxSettings)을 직접 읽으면 안 된다. 그래서 설정을 볼 수 있는 조립 모듈(OutboxRelayAutoConfiguration)이 값을 꺼내 use case 를 손으로 만들어 넘긴다. use case 클래스의@UseCaseCapability애너테이션은 와이어링 방식과 무관하게 유지된다(ArchUnit 이 강제). - 이 모듈은 failure reporter를 구현하지 않고 주입만 한다. messaging bridge의
MessagingConfig가 정확히 하나의OutboxRelayFailureReportPort구현을 만들고,OutboxRelayAutoConfiguration은 이를 relay 생성자에 전달한다. - 릴레이 use case 를 독립 컨텍스트 빈으로 등록하지 않는다. 만약 빈으로 올리면
adapter-web의MethodSecurityConfig메서드 보안 pointcut(@RequiresPermission)이 이 타입을 CGLIB 프록시로 감싼다. 그런데 use case 가final클래스라 프록시 생성 자체가 실패하고, 설령 된다 해도 스케줄러 스레드에는Authentication이 없어 매 릴레이 틱이 fail-closed 로 거부된다. 그래서 빈으로 올리지 않고,outbox:relay권한 확인은 스케줄러 컨텍스트에서 관례로 둔다. outboxRelayScheduler빈은app.outbox.relay-enabled=true일 때만 만든다(기본 false). 키가 없으면 꺼진 것으로 본다. 모듈 기본값(persistence-jpa.yml의${APP_OUTBOX_RELAY_ENABLED:false}),@ConditionalOnProperty,OutboxSettings의 null 기본값이 모두 false로 같다.- store와 publisher가 있을 때만 켜진다. 설정 전체는
OutboxStorePort빈(persistence-jpa를 고르고 outbox를 켰을 때만 존재)을, 스케줄러는 추가로OutboxMessagePublishPort빈(messaging bridge가 제공)을 조건으로 건다. 두 auto-configuration 뒤에 오도록afterName으로 순서를 명시한다. 발행할 곳이 없으면 스케줄러가 없으므로 PENDING 행이 그대로 남는다 — 예전에는DisabledMessagingSentinelAutoConfiguration의 대역 publisher가 모든 claim을 실패시켜 DEAD로 소진했고, 그걸 막으려고OutboxRelayBrokerRequirementValidator가 있었다. 둘 다 삭제했다. messaging bridge의MessagingConfig도 outbox 대역 publisher를 만들지 않는다. bridge가 있고 켜져 있는데 canonicalIntegrationEventPublishPort가 없으면(producer id 없음) 기동을 거부한다. - 왜 persistence-jpa가 아니라 여기인가. 릴레이는 use case를 조립해 타이머로 구동하는 합성
코드다. driven adapter인 persistence-jpa가 use case를 만들거나 호출하면
PERSISTENCE_DOES_NOT_DEPEND_ON_APPLICATION_SERVICES규칙 위반이다. 모듈 타입은 하나도 이름으로 부르지 않고 포트만 쓰므로, persistence-jpa 한 줄을 지우면 릴레이도 함께 꺼진다. outboxLeaderElection토큰 빈은 outbox capability 안에서 조건 없이 등록한다. SKIP LOCKED 는 멀티 인스턴스 전역 스위치와 무관하게 outbox relay 자체의 리더십/claim 메커니즘이라, outbox가 켜진 상태에서 별도 하위 토글로 끌 수 있게 만들지 않는다. 이 토큰은 outbox 조립의 자기 설명용 marker이지APP_MULTI_INSTANCE_ENABLED의 전역 필수 빈이 아니다.outboxMetrics빈은MeterRegistry가 없을 때 no-op 이다. Actuator 가 클래스패스에 없는 환경에서도 와이어링이 깨지지 않도록ObjectProvider로 레지스트리를 선택적으로 주입한다.
OutboxLeaderElectionToken
- 로직이 전혀 없는 마커(documentation artifact) 빈이다. 이 타입은 동작을 갖지 않고, Spring 컨텍스트에 존재한다는 사실만으로 멀티 인스턴스 조정 빈 요구사항을 충족시킨다.
- 리더 선출을 외부 코디네이터 없이 PostgreSQL
FOR UPDATE SKIP LOCKED로 구현한다는 것을 표현한다. claim 쿼리에 SKIP LOCKED 를 걸면 각 릴레이 인스턴스가 서로 겹치지 않는(disjoint) 행 집합을 가져가므로, 별도 코디네이터 없이도 "각 인스턴스가 자기 파티션의 리더" 형태로 리더 선출 의미가 성립한다.
OutboxMetrics
MeterRegistry가 없으면 모든 메트릭 연산이 no-op 이다. Actuator 가 없는 환경에서도 릴레이가 정상 동작해야 하므로, 생성자에서ObjectProvider로 레지스트리를 조회해 없으면 게이지도 만들지 않고 기록도 건너뛴다.- 카운터는 PUBLISHED/FAILED/DEAD 만 집계하고 IN_FLIGHT 는 제외한다. IN_FLIGHT 는 릴레이 사이클의 종료 결과(terminal outcome)가 아니라 처리 중을 나타내는 일시적 상태라 카운터 outcome 으로 의미가 없다.
- MultiGauge 갱신 시
overwrite=true로 등록한다. 매 스케줄러 틱마다 store 를 다시 조회해 게이지를 갱신하는데, 이전 틱에 있었지만 지금은 사라진 event type 같은 오래된 time-series 태그를 덮어써 제거하기 위함이다.
OutboxRelayScheduler
- 합성 루트가 직접 등록하고 컴포넌트 스캔하지 않는다. 이 스케줄러가 구동하는 릴레이 use case 가
(위 OutboxRelayAutoConfiguration 사유로) 일부러 빈이 아니기 때문에, 그 use case 를 조립하는
OutboxRelayAutoConfiguration가 스케줄러 등록까지 같이 소유한다. - 릴레이 사이클에서 발생하는 예상치 못한 예외를 잡아 ERROR 로 로깅만 하고 삼킨다. 스케줄러 스레드가 죽으면 릴레이가 조용히 멈추므로, 다음 틱을 위해 스레드를 살려둔다. 단, 개별 발행 실패 (FAILED/DEAD 전이)는 relay가 persisted transition 성공 뒤 typed reporter로 canonical ERROR를 요청하고 결과에 반영하므로 이 catch 블록까지 오지 않는다 — 여기서 삼키는 것은 어디까지나 "예상치 못한" 예외다.
- 스케줄링은
OutboxRelayAutoConfiguration가 직접 켜고(@EnableScheduling) fixed-delay 를 쓴다. 예전에는 JDBC idempotency 설정만 스케줄링을 켰기 때문에 다른 provider 를 고르면 릴레이가 조립만 되고 돌지 않았다. fixed-delay 는 릴레이 실행 시간과 무관하게 사이클이 겹치지 않도록(non-overlapping) 보장한다. - 종료 때는 platform보다 먼저 멈추고 진행 중 회차를 끝낸다(SmartLifecycle, phase
Integer.MAX_VALUE). relay 회차는 messaging platform을 거쳐 발행한다. platform은 자기 종료 phase(MessagingShutdownLifecycle,Integer.MAX_VALUE - 1024)에서 발행 admission을 닫고, 그 뒤 발행은SHUTTING_DOWN으로 거부된다.@Scheduled만으로는 이 순서에 들어가지 못한다(Spring은ContextClosedEvent에서 다음 tick만 취소하고 실행 중 회차는 그대로 둔다). 그래서 스케줄러가 SmartLifecycle로 platform 위 phase(platform 자체 relayMessagingOutboxRelayLifecycle와 같은 값)에 서고,stop에서 새 회차를 막고 실행 중 회차가 결과를 기록할 때까지 종료를 붙잡는다. 기다리는 한도는 Spring의spring.lifecycle.timeout-per-shutdown-phase다. 한도를 넘긴 회차의 남은 row는 거부되지만 재시도 대상(FAILED)이고, 프로세스가 강제 종료되면 IN_FLIGHT row는 lease 만료(in-flight-timeout) 뒤 다시 claim된다. 이 leaf는 messaging 타입을 이름으로 부를 수 없어 phase를 값으로 맞췄고,OutboxRelayShutdownOrderTest가 같은 phase의 대역으로 순서를 고정한다.- 버린 대안: scheduler executor phase 올리기(전역 설정이라 다른
@Scheduled작업까지 바뀐다), relay 루프를 전용 스레드로 직접 소유하기(@Scheduled·fixed-delay 정책과@EnableScheduling결정까지 다시 열어야 해서 이번 범위보다 크다).
- 버린 대안: scheduler executor phase 올리기(전역 설정이라 다른
OutboxSettings
- 튜닝 값(poll 주기·batch·timeout·보존)은 코드 리터럴 기본값을 쓰고 env placeholder 를 두지 않는다. 신규 env key 를
추가하지 않는다는 결정에 따라, 값이 없으면 컴팩트 생성자에서 직접 기본값(예:
PT5S,20,PT5M,PT10M,P7D)을 채운다. reaper-interval과published-retention은adapter-persistence의OutboxReaper도 property 문자열로 읽는다. 두 모듈이 같은 키를 공유하지만, 이 settings record 가 일곱 값 전체를 선언 하는 단일 지점(single place) 역할을 한다. strict 바인딩이라 prefix 아래 모르는 키는 기동 실패다. 기본값 yml(app.outbox.*)은 store를 가진 persistence-jpa 모듈이config/module-defaults/persistence-jpa.yml로 가져온다.