문제: qualityCheck는 spotbugsMain만 돈다. main 밖 source set(test, testFixtures, integrationTest, systemTest 등)의 SpotBugs 태스크 111개는 어느 게이트에도 없었고, 돌려 보니 53개가 실패했다(발견 300건). 그중 동시성 테스트 7건은 CountDownLatch.await의 시간 초과를 무시하고 다음 단계로 가서 순서를 확인하지 않은 채 통과했다. 2개는 분석 classpath에 없는 클래스 때문에 분석이 불완전했다. 방법: - leaf마다 testQualityCheck를 두고 main 빌드는 mainCheck, optional 빌드는 ci에 넣었다. PR 게이트에 넣지 않은 것은 테스트 코드가 배포되지 않고 전체 실행이 ci만큼 걸려서다. - 테스트용 제외 목록 config/spotbugs/exclude-test.xml. 패턴 전체 제외는 이유가 모든 테스트 클래스에 성립하는 것만(보안 범주, 내부 상태 노출, 생성자 예외, 반환값 null 역참조, 아키텍처 위반 fixture). 나머지 30건은 클래스·메서드로 좁히고 이유를 달았다. - 24건은 코드로 고쳤다: await 결과 단언, 공유 변수 원자성, 닫지 않은 Statement, SQLException을 삼키던 upsert 테스트, 만료 없는 키에서 NPE가 나던 Redis fake. 쓰는 곳이 없던 web-fileserver 테스트 helper 2개는 지웠다. - 모든 SpotBugs 태스크가 그 source set의 runtime classpath로 분석하고 분석이 불완전하면 실패한다. SpotBugs 플러그인이 나중에 생긴 source set의 태스크를 등록하면서 classpath를 덮어써서 설정을 평가 뒤에 등록한다. 그 자리에 의존성을 더하는 우회는 버렸다. 위험·한계: 파생 서비스는 자기 테스트 코드의 SpotBugs 발견이 mainCheck를 막는다(업그레이드 안내 B-40). mainCheck가 그만큼 길어진다(main 빌드 테스트 태스크 100개). 검증: ci, 두 빌드 verifyStrictLaneStages --dry-run, mainCheck(testQualityCheck 100개 포함, 3분 10초 → 8분 33초), :integrationCheck, -p optional-platforms ci(testQualityCheck 포함) integrationCheck performanceCheck, :performanceCheck, :releaseCheck(-PgitRevision), verify-compose-profile- contracts(18 lane) 첫 실행 통과. 고친 컨테이너 테스트는 클래스별로 따로 실행해 통과. Refs: docs/reviews/2026-11-03-rereview/README.md 14절 BREAKING CHANGE: mainCheck(optional 빌드는 ci)가 테스트 source set의 SpotBugs·FindSecBugs 발견에 실패한다. 고치거나 config/spotbugs/ exclude-test.xml에 이유를 단 좁은 Match를 더한다.
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 로 구동,
│ 발행이 이어지는 동안 한 tick 안에서 바로 다시 claim(최대 50회차),
│ 종료 때 platform보다 먼저 멈추고 남은 claim을 놓음(SmartLifecycle)
├─ OutboxMetrics outbox.pending.size / outbox.publisher.lag / outbox.retry.long.*
│ (자기 스레드에서 poll 주기마다 갱신) / published.total(relay 회차 결과)
└─ OutboxRelayOffWarning 발행 포트가 있는데 relay가 꺼져 있으면 기동 시 WARN 한 줄
여러 인스턴스가 함께 relay를 돌려도 조정자는 없다. claim SQL의 FOR UPDATE SKIP LOCKED가 인스턴스마다
겹치지 않는 행을 주고, lease token이 늦은 완료를 막는다(PostgreSqlOutboxClaimRepository, V17). 리더를
뽑지 않는다.
- 조립 순서:
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 를 독립 컨텍스트 빈으로 등록하지 않는다. relay는 스케줄러만 부르는
@SystemInvoked유스케이스라 권한 선언이 없다. 빈으로 올리면 전송 계층이 권한 검사 없이 닿을 수 있으므로, 빈으로 등록된@SystemInvoked유스케이스는composition:service-runtime의PermissionEnforcementGuard가 기동을 실패시킨다. 스케줄러 스레드에는Authentication이 없으므로 권한 게이트를 달아도 매 틱 거부될 뿐이다. 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토큰 빈은 지웠다(리뷰 2026-11-01 06-13). 로직 없는 marker였고, Javadoc은 "있기만 하면 멀티 인스턴스 조정 요구를 채운다"고 했지만 그 빈을 요구하는 검사도, 리더 선출도 없었다 (claim은 행 단위다). 버린 대안: 이름을 실제 동작(OutboxClaimStrategy)으로 바꾸기 — 여전히 아무도 읽지 않는 marker다. 동작 설명은 위 트리 아래 문단과PostgreSqlOutboxClaimRepository에 있다.- relay 조립은 배치가 lease 안에 다 나가는지 확인한다(06-12). 한 회차는 batch 전체를 lease 하나로
잡고 차례로 발행한다.
batch-size× 발행 포트의longestAttempt()(bridge: platform 발행 기한의 두 배, 기본 10초)가in-flight-timeout이상이면 기동을 거부한다. lease가 먼저 끝나면 다른 인스턴스가 같은 행을 다시 보내기 때문이다(fencing은 상태 덮어쓰기만 막는다). 기본값은 20 × 10초 = 200초 < 5분이다. 포트가 최악 시간을 모르면(Optional.empty()) 검사하지 않는다. 버린 대안: relay가 회차 중 남은 lease를 보고 남은 행을 놓기 — 설정 실수를 운영 중 중복 대신 기동 실패로 드러내는 쪽을 골랐다. outboxMetrics빈은MeterRegistry가 없을 때 no-op 이다. Actuator 가 클래스패스에 없는 환경에서도 와이어링이 깨지지 않도록ObjectProvider로 레지스트리를 선택적으로 주입한다.
OutboxMetrics
MeterRegistry가 없으면 모든 메트릭 연산이 no-op 이다. Actuator 가 없는 환경에서도 릴레이가 정상 동작해야 하므로, 생성자에서ObjectProvider로 레지스트리를 조회해 없으면 게이지도 만들지 않고 기록도 건너뛴다.- 카운터 outcome은 relay 회차 결과(
OutboxRelayResult.Outcome) 다섯 값이다: PUBLISHED, FAILED, DEAD, STALE, RELEASED. IN_FLIGHT는 행 상태이지 회차 결과가 아니라 세지 않는다.docs/registries/metrics.yaml의 허용 값과 enum이 같은지OutboxStatusRegistryContractTest가 비교한다(재리뷰 2026-11-03 RR-05-06). - 오래 재시도 중인 행을 따로 센다(RR-05-03). 응답 없음·지금만 거부는 시도 예산을 쓰지 않아 끝이 없다.
outbox.retry.long.size는 미룬 claim이LONG_RETRY_DEFERRED_CLAIMS(10)번 이상인 FAILED 행 수,outbox.retry.long.age는 그중 가장 오래된 행의 나이다. 10번은 backoff 상한 5분 기준으로 적어도 약 35분 동안 실패했다는 뜻이라 broker 재시작·credential 교체는 넘긴다. publish-failed runbook §4.1의 조회가 같은 기준을 쓴다. runbook SQL에는 숫자가 그대로 적혀 있어서(운영자가 psql에 붙여 넣는다) 상수만 바꾸면 경보가 센 행과 조회가 보여 주는 행이 갈라진다.OutboxLongRetryRunbookContractTest(laneoutboxRelayDocumentContractTest,mainCheck)가 runbook 블록의 숫자와 상수를 비교한다(재리뷰 2차 RR-02-14). - MultiGauge 갱신 시
overwrite=true로 등록한다. 매 스케줄러 틱마다 store 를 다시 조회해 게이지를 갱신하는데, 이전 틱에 있었지만 지금은 사라진 event type 같은 오래된 time-series 태그를 덮어써 제거하기 위함이다.
OutboxRelayScheduler
- 합성 루트가 직접 등록하고 컴포넌트 스캔하지 않는다. 이 스케줄러가 구동하는 릴레이 use case 가
(위 OutboxRelayAutoConfiguration 사유로) 일부러 빈이 아니기 때문에, 그 use case 를 조립하는
OutboxRelayAutoConfiguration가 스케줄러 등록까지 같이 소유한다. - 릴레이 사이클에서 발생하는 예상치 못한 예외를 잡아 ERROR 로 로깅만 하고 삼킨다(그 tick의 남은 회차도 건너뛴다). 스케줄러 스레드가 죽으면 릴레이가 조용히 멈추므로, 다음 틱을 위해 스레드를 살려둔다. 단, 개별 발행 실패 (FAILED/DEAD 전이)는 relay가 persisted transition 성공 뒤 typed reporter로 canonical ERROR를 요청하고 결과에 반영하므로 이 catch 블록까지 오지 않는다 — 여기서 삼키는 것은 어디까지나 "예상치 못한" 예외다.
- 스케줄링은
OutboxRelayAutoConfiguration가 직접 켜고(@EnableScheduling) fixed-delay 를 쓴다. 예전에는 JDBC idempotency 설정만 스케줄링을 켰기 때문에 다른 provider 를 고르면 릴레이가 조립만 되고 돌지 않았다. fixed-delay 는 릴레이 실행 시간과 무관하게 사이클이 겹치지 않도록(non-overlapping) 보장한다. - 종료 때는 platform보다 먼저 멈추고, 진행 중 발행 하나만 끝낸 뒤 남은 claim을 놓는다(SmartLifecycle,
phase
Integer.MAX_VALUE). relay 회차는 messaging platform을 거쳐 발행한다. platform은 자기 종료 phase(MessagingShutdownLifecycle.PHASE=Integer.MAX_VALUE - 1024)에서 발행 admission을 닫고, 그 뒤 발행은SHUTTING_DOWN으로 거부된다.@Scheduled만으로는 이 순서에 들어가지 못한다(Spring은ContextClosedEvent에서 다음 tick만 취소하고 실행 중 회차는 그대로 둔다). 그래서 스케줄러가 SmartLifecycle로 platform 위 phase에 선다.stop은 새 회차를 막고 실행 중 회차에 멈춤을 알린다 (PublishPendingOutboxEventsCommand.stopRequested). 회차는 지금 하는 발행 하나를 끝내고, claim했지만 손대지 않은 row를OutboxStorePort.releaseLease로 놓는다: PENDING, 곧바로 claim 가능, 시도 횟수에서 그 claim을 뺀다. 결과는RELEASED로 센다. 그래서 종료 대기는 발행 하나(최대 약 10초)로 묶이고spring.lifecycle.timeout-per-shutdown-phase(기본 30초) 안에 끝난다. 놓은 row는 다른 인스턴스가 다음 poll에서, 아니면 재시작한 이 인스턴스가 가져간다. 프로세스가 강제 종료되면 IN_FLIGHT row는 lease 만료(in-flight-timeout) 뒤 다시 claim된다.OutboxRelayShutdownOrderTest가 platform 상수 (MessagingShutdownLifecycle.PHASE, test compile-only 참조)로 순서를, 남은 claim 해제를 고정한다.- 고른 방법: 멈춤 요청 즉시 남은 claim 해제. 버린 대안: 종료 한도까지 계속 발행하다 한도 직전에
해제 — 한도 값과 발행 하나의 최악 시간을 이 leaf가 알아야 하고, 그 추정이 틀리면 admission이 닫힌
뒤 발행해 retry 지연(30초 이상)과 FAILED 경고를 남긴다. scheduler executor phase 올리기(전역 설정이라
다른
@Scheduled작업까지 바뀐다).
- 고른 방법: 멈춤 요청 즉시 남은 claim 해제. 버린 대안: 종료 한도까지 계속 발행하다 한도 직전에
해제 — 한도 값과 발행 하나의 최악 시간을 이 leaf가 알아야 하고, 그 추정이 틀리면 admission이 닫힌
뒤 발행해 retry 지연(30초 이상)과 FAILED 경고를 남긴다. scheduler executor phase 올리기(전역 설정이라
다른
- 한 tick이 claim 한 번이 아니다(06-04). claim gate는 aggregate마다 가장 앞 row 하나만 내보낸다.
예전에는 tick당 claim 한 번이라 한 aggregate가 poll 주기(기본 5초)마다 한 건씩만 나갔다(이벤트 100건 ≈
8분). 지금은 회차가 무언가를 발행하면 같은 tick 안에서 바로 다시 claim하고, 아무것도 발행하지 못하거나
claim이 비면 tick을 끝낸다. 한 tick의 상한은
MAX_CYCLES_PER_TICK= 50회차다.- 처리량 상한(계산, 실측 아님): 한 aggregate는 poll 주기가 아니라 발행 왕복 시간에 묶인다(정상 broker에서 회차당 claim·완료 DB 왕복 + Kafka ack). 인스턴스 하나는 tick당 최대 50 × batch 20 = 1,000행을 보내고 다음 tick까지 5초 쉰다. 넘는 처리량이 필요하면 batch-size(06-12: lease보다 길면 기동이 거부된다)나 인스턴스 수로 늘린다.
- 버린 대안: poll 주기만 줄이기 — 빈 tick마다 claim·지표 질의가 는다.
- 지표 게이지는 relay와 따로, 자기 스레드에서 갱신한다(06-05, RR-05-05).
outbox.pending.size·outbox.publisher.lag·outbox.retry.long.*는OutboxMetrics가 poll 주기마다 갱신한다(relay가 꺼져 있어도, 회차가 매번 예외로 끝나도). 예전에는 relay 회차 안에서만 갱신되어, relay가 꺼진 배포(기본값)나 매 회차 실패하는 장애에서 게이지가 멈췄다. 그다음에는@Scheduled로 떼었지만 Spring의 fixed-delay 작업은 모두 스레드 하나(virtual thread면SimpleAsyncTaskScheduler의 fixedDelayExecutor, 아니면 pool 1)에서 줄을 서서, relay tick이 50회차를 도는 동안(느린 broker면 몇 분) 게이지가 기다렸다 — 적체를 봐야 할 바로 그때다. 지금은OutboxMetrics가SmartLifecycle로 자기 단일 daemon 스레드(outbox-gauges)를 시작하고 멈춘다. 버린 대안: tick 상한을 회차 수 대신 시간으로 — 게이지가 여전히 relay 뒤에 줄을 선다. Micrometer 지연 조회 gauge — scrape마다 DB 질의가 나가고, event type별 series를 덮어쓸 수 없다. 카운터outbox.publisher.published.total은 회차 결과로 relay가 기록한다. 발행 포트가 있는데 relay가 꺼져 있으면OutboxRelayOffWarning이 기동 시 WARN 한 줄을 남긴다(별도 worker 배포가 relay를 돌리는 구성도 있으므로 기동 실패로 만들지 않았다).
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로 가져온다.