Files
clean-architecture-backend-…/src/composition/outbox-relay/README.md
T
DongHyeonka 34565130e0 fix!: 성숙도 리뷰의 High·P1 결함 19건을 고친다
문제: 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 필드를 보내지 않는다.
2026-11-03 19:52:06 +09:00

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가 있고 켜져 있는데 canonical IntegrationEventPublishPort가 없으면(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 자체 relay MessagingOutboxRelayLifecycle와 같은 값)에 서고, 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 결정까지 다시 열어야 해서 이번 범위보다 크다).

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로 가져온다.