Files
clean-architecture-backend-…/src/composition/outbox-relay/README.md
T
DongHyeonka 1885bf8da7 fix!: 2차 재리뷰가 찾은 결함 29건을 고친다
문제: 재리뷰 수정 커밋(bbe944bd)만 다시 본 2차 재리뷰가 Important 7건,
Minor 22건을 찾았다. 결과 불명 503 뒤 같은 키를 다시 보내면 Redis
store가 lease 지난 실행을 넘겨받아 작업을 다시 돌렸다. replay TTL이
lease보다 짧으면 lease 도중 key가 사라져 같은 키가 두 번 실행됐다.
@SystemInvoked 규칙이 매뉴얼 09장의 이벤트 소비 경로까지 막았다. V22가
outbox_event에 가장 강한 잠금을 lock_timeout 없이 걸었다. prod의
fixture- 거부가 HOSTNAME 같은 비밀 아닌 값까지 막았다. 데모 허용 목록의
test·demo 프로필로 sample이 뜨지 않았다. 기동 rule bean의 @Value 필드가
조용히 null이 됐다.

방법: 영역별 4묶음이 test-driven-development 절차로 실패 테스트를
먼저 쓰고 고쳤다. 결정은 재리뷰 README 9.1절이다.
- 두 멱등성 store가 같은 계약을 따른다. lease가 지난 실행 기록은 다시
  돌리지 않고 포기로 표시해 500 RECOVERY_REQUIRED로 답한다. 기록 수명은
  lease + replay TTL이고, replay-ttl < processing-lease면 기동이 실패한다.
- 사용자 transport만 @SystemInvoked use case에 닿지 못한다. 메시지
  handler·scheduler는 새 표시 @SystemCaller(reason)를 달고 use case를
  생성자에서 new로 만든다. 매뉴얼 경로를 테스트로 고정했다.
- 아직 어디에도 적용되지 않은 마이그레이션(V20·V22·알림 V11~V13·sample
  V8_1·grpc V002·V003)에 lock_timeout 5s를 넣고, 텍스트 검사기와 실 PG
  lane을 더했다. 이미 배포된 24개는 동결 목록으로 둔다.
- fixture- 검사는 비밀로 분류된 값만 본다. sample은 local·test·demo에서
  object storage를 끈다. 기동 rule bean에 주입 멤버가 있으면 모든
  프로필에서 기동이 실패한다. 리뷰어가 제안한 "static @Bean 선언 강제"는
  문제없는 등록을 막고 @Value 필드는 통과시켜서 버렸다.
- 이 수정 전에 move된 파일의 쿼터 차이를 찾는 쿼리와 재계산 SQL을
  docs/fileserver/operations.md에 적었다.

위험·한계: lease 뒤 늦게 끝난 첫 시도의 결과는 기록되지 않는다(그 요청도
500). @SystemCaller가 없는 메시지 handler, 주입 멤버가 있는 기동 rule,
working-directory 없이 ./gradlew를 부르는 workflow 명령은 파생 서비스에서
새로 실패하거나 세지지 않는다(업그레이드 안내 B-14~16·B-36·B-39).
spotbugsTestFixtures는 게이트 밖이고 기준 커밋에서도 실패하며, 새 검사기의
정규식 경고 8건이 더해졌다. 실제 CI runner 실행은 확인하지 못했다(Gitea
repo의 Actions가 꺼져 있다).

검증: ci, 두 빌드의 verifyStrictLaneStages --dry-run, mainCheck,
:integrationCheck, -p optional-platforms ci integrationCheck
performanceCheck, :performanceCheck, :releaseCheck(-PgitRevision),
verify-compose-profile-contracts(18 lane) 첫 실행 통과. 쿼터 재계산
SQL은 실 PostgreSQL 16에서 차이 2행 → 0행을 확인했다.

Refs: docs/reviews/2026-11-03-rereview/README.md 9·9.1·10절
BREAKING CHANGE: replay-ttl < processing-lease 설정은 기동 실패, ledger
release가 claim token을 받는다, HttpBodyReadException(IOException 하위)이
본문 실패를 싣는다, 기동 rule·비밀 목록 bean의 주입 멤버 금지,
verifyStrictLaneStages가 workflow 명령의 working-directory로 빌드를 정한다.
2026-11-04 01:47:50 +09:00

17 KiB
Raw Blame History

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가 있고 켜져 있는데 canonical IntegrationEventPublishPort가 없으면(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(lane outboxRelayDocumentContractTest, 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 작업까지 바뀐다).
  • 한 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로 가져온다.