# adapter:outbound:support — 설계 결정 참조 아웃바운드 기술 어댑터(`:adapter:outbound:messaging`, `:adapter:outbound:cache-redis`, `:adapter:outbound:notification`, `:adapter:outbound:httpclient`)가 공유하는 베이스 모듈. 패키지 루트: `dev.caskeleton.adapter.outbound.support`. 허용/금지 의존 정책은 `build.gradle` 의 `allowedProjectDependencies['adapter:outbound:support']` 항목이 SSOT 다(이 모듈은 아직 별도 AGENTS.md 를 두지 않았다). 이 문서는 코드 주석에서 덜어낸 **설계 결정의 근거**를 모아둔 참조용 기록이다 — 코드를 읽다 "왜 이렇게 했나"가 궁금할 때 본다. ## 왜 별도 모듈인가 옛 `adapter-outbound` 모듈을 기술별(`messaging`/`cache-redis`/`notification`/`httpclient`)로 쪼개면서, 네 모듈이 공통으로 필요로 하는 조각 — correlation 조회, fail-open 의존성 로깅, 공유 `@Configuration` 등록 지점 — 을 이 모듈로 뽑아냈다. 네 기술 모듈 모두 `implementation project(':adapter:outbound:support')` 로 이 모듈에 의존한다. ## FailOpenDependencyLogger — WARN, ERROR 아님 실패를 ERROR 가 아니라 WARN 으로 로깅한다: cache/messaging/notification 선택형 어댑터는 fail-open 이라 의존성 실패가 나도 use case 는 성공한 것이다 — 관측은 하되 escalate 하지 않는다. 이는 호출자에게 직접 노출되는 hard failure 를 ERROR 로 올리는 `httpclient` 모듈의 `OutboundHttpDependencyLogger` 와 명확히 구분된다. 메서드 시그니처가 본문·수신자·페이로드를 받지 않아 PII 가 로그에 닿지 않는다. ## OutboundCorrelation — `"unknown"` 센티넬 MDC 에 correlation id 가 없으면 `null` 이 아니라 `"unknown"` 문자열을 반환해 로그 라인에 필드가 비지 않게 한다. MDC 키는 SSOT(`mdc-keys.yaml`)를 따른다. ## OutboundSupportConfig — 공유 auto-configuration seam `FailOpenDependencyLogger` 빈을 `@ConditionalOnMissingBean` 으로 무조건 등록하는 단일 `@AutoConfiguration` 이다(`META-INF/spring/...AutoConfiguration.imports`에 등록 — 합성 루트의 component scan 없이 이 모듈이 있으면 등록된다). 네 기술 모듈이 각자 로거 빈을 중복 등록하지 않고 이 모듈에만 의존하면 와이어링되며, 포크는 같은 타입의 빈을 직접 등록해 오버라이드할 수 있다. 이 모듈 자체는 어떤 `@ConditionalOnProperty` 게이팅도 갖지 않는다 — 게이팅은 각 기술 모듈이 자신의 연동 client 단위로 소유한다. ## messaging — 템플릿의 integration event encoder `JsonIntegrationEventEncoder`가 `IntegrationEventEncoderPort`의 템플릿 구현이다(소유자 결정 7: outbox append는 canonical 하나, encoder는 템플릿이 준다). `IntegrationEventEncoderAutoConfiguration`이 context의 모든 `IntegrationEventContractContribution` bean으로 닫힌 catalog를 만들고, 서비스가 자기 encoder bean을 두면 물러난다. - 형식: `shared-contract`의 envelope v1(`contracts/messaging/envelope/v1.schema.json`) 안에 payload record를 `CanonicalJson`으로 한 번 렌더링해 넣는다. 한 값에는 렌더링이 하나다: component 선언 순서, 공백 없음, RFC 8259 필수 escape만, 숫자는 plain decimal. 그래서 envelope hash가 event를 대표한다. - 받는 component 타입은 닫혀 있다: String, 정수형, BigDecimal, Boolean, enum, Instant, LocalDate, UUID, Optional, List, public record. `double`/`float`는 거부한다(한 값에 철자가 여럿이라서). `null`도 거부한다 — 없을 수 있는 값은 Optional로 선언한다. - 시작할 때 확인하는 것: payload 타입이 `IntegrationPayload`를 구현한 record인지, 선언한 component 순서가 record의 것인지, 선언한 schema hash가 classpath schema 파일 bytes의 SHA-256인지. schema를 고치고 hash를 안 고치면 기동이 실패한다. - 확인하지 않는 것: payload를 JSON Schema로 검증하지 않는다(NetworkNT를 production에 다시 싣지 않았다). 매 event마다 검증하려는 서비스는 자기 encoder bean을 둔다. - partition key는 tenant·logical destination·aggregate type·aggregate id의 domain-separated SHA-256이라 한 aggregate의 event는 한 partition으로 간다. 여기 있는 이유: use case가 append 전에 encode하므로 outbox를 쓰는 모든 조립에 있어야 한다. messaging 모듈은 발행 쪽에만 있고(sample은 messaging이 없다), persistence는 직렬화를 소유하지 않는다. support는 outbound 어댑터가 있는 모든 조립에 있다. ## startup — 시작 실패 계약과 모듈 기본 설정 (app-bootstrap에서 이동) capability 모듈이 합성 루트에 의존하지 않고 같은 방식으로 실패하고, 자기 설정을 가져오게 하려고 `support.startup` 패키지로 옮겼다. 로거 이름(`dev.caskeleton.bootstrap.runtime.startup`, `dev.caskeleton.bootstrap.runtime`)과 로그 필드는 그대로 둬서 운영 필터가 바뀌지 않는다. logstash encoder·Logback은 `compileOnly`다: 애플리케이션의 로깅 스택(app-bootstrap이 둘 다 싣는다)이 제공하고, 시작 실패를 던지는 모듈(persistence-jpa, cache-redis)은 encoder를 직접 선언한다. - `StartupOrder` — 모든 `EnvironmentPostProcessor`의 순서표. 모듈 기본 설정(`MODULE_DEFAULTS`)이 config data 바로 뒤, 그다음 Redis·DB readiness 기여, 맨 끝에 검증기들이다. - `ReadinessGroup` — readiness 그룹에 contributor를 붙이는 유일한 방법. - `RuntimeWarnings` — 경고 두 종류(meter 기록 실패, 설정 대체)의 구조화 필드. - `ModuleDefaultsEnvironmentPostProcessor` — 모듈이 `config/module-defaults/<모듈>.yml`에 둔 기본 설정을 가장 낮은 우선순위로 읽는다. 모듈을 고르면 설정이 따라오고 지우면 같이 사라진다. 이 모듈의 `spring.factories`에 등록돼 있다. 규칙: 의존성 closure(`modules.json`)에 support가 있는 모듈은 전부 이 로더를 쓴다(yml만 두면 되고 코드 의존은 필요 없다). support에 닿지 않는 모듈 (persistence-mongo, graphql)만 자기 activation EPP가 `config/<이름>.yml`을 읽는다. ### 시작 실패 타입(StartupErrorCode / StartupPhase / StartupFailures / *Exception) - **`StartupErrorCode` — 네 가지 시작 실패 원인을 (레지스트리 error code, 표준 프로세스 exit 코드, `StartupPhase`)로 묶는다.** exit 78(env 누락/오류)과 70(마이그레이션 실패)은 sysexits 표준 (`EX_CONFIG`, `EX_SOFTWARE`)과 정렬돼 외부적으로 방어 가능하다. 반면 exit 71(프로파일 불일치)과 72(필수 어댑터 비활성)는 ca-tmpl 내부 규약이다 — sysexits 의 `EX_OSERR`/`EX_OSFILE`이 이 의미와 맞지 않아, 외부 표준이 아니라 내부 룩업 테이블 값으로 정했다. exit 코드는 carrying 예외가 `ExitCodeGenerator`를 구현하기 때문에만 JVM 종료 상태가 된다. - **`StartupPhase` — 실패 원인을 운영자가 로그에서 구분할 수 있게 하는 `startup.phase` 필드다.** 시작 실패는 요청이 아직 없으므로 HTTP 에러 응답에 절대 실리지 않는다. 따라서 구조화 로그의 `startup.phase`가 `kubectl logs`/`describe`에서 네 가지 원인을 가려내는 유일한 계약이다. wire 이름은 dash-case(`env-validation | migration | adapter-enablement | profile-check`)이며, MDC 키가 아니라 Logstash structured argument 로 방출되므로 snake_case MDC 키 레지스트리 규칙은 적용되지 않는다. - **`StartupFailures` — 시작 실패를 던지는 단일 출처로, 예외 생성 *전에* 구조화 로그를 먼저 방출한다.** "throw 직전 각 validator 가 직접 logger 를 호출"하는 패턴을 중앙화해, 어떤 시작 가드도 원인/구분자 없는 실패를 던지지 못하게 한다. 로그는 `startup.phase` / `error.code` / `error.category` 세 필드를 Logstash structured argument 로 싣고, cause 가 있으면 `error.root_cause.class` / `error.root_cause.message` 요약 필드만 추가한다. 원본 cause 는 반환되는 `StartupFailureException`에 보존하지만 SLF4J throwable 인자로 넘기지 않는다. 따라서 canonical startup-failure 로그는 운영자가 분류할 수 있는 요약만 남기고 프레임워크/드라이버 stacktrace 를 출력하지 않는다. - **`StartupFailureException` — 시작 실패의 유일한 타입이다. 원인은 싣고 있는 `StartupErrorCode`가 말하고(`errorCode()`), `ExitCodeGenerator`로 그 코드의 exit 코드를 JVM 종료 상태로 만든다.** 코드마다 subclass(생성자로 코드만 넘기던 4개)를 두던 구조는 없앴다(S6-#13). 생성은 `StartupFailures` 팩토리만 한다 — 생성자는 package-private 이고, 팩토리가 구조화 로그를 함께 남긴다. context refresh 가 실패하면 `SpringApplication`의 `SpringBootExceptionHandler` (부팅 스레드의 uncaught-exception handler 로 설치됨)가 실패 예외에서 `getExitCode()`를 읽어 `System.exit(code)`를 호출한다 — `main()` 수정이 필요 없다. `IllegalStateException`을 상속하는 이유는 과거 `StartupSafetyValidator`가 `IllegalStateException`을 던졌기 때문으로, 타입드 예외로 업그레이드한 뒤에도 소스/동작 호환을 유지하기 위함이다. - **`StartupFailureExceptionReporter` / `StartupFailureSpringBootLogFilter` — Spring Boot 의 중복 startup stacktrace 를 억제한다.** reporter 는 failure cause chain 에 `StartupFailureException`이 있을 때만 `true`를 반환해 Boot 의 generic `Application run failed` 출력을 "이미 보고됨"으로 처리한다. 이후 Boot 가 반쯤 초기화된 context 를 닫다가 `Unable to close ApplicationContext`를 다시 남길 수 있으므로, canonical startup-failure 로그가 이미 찍힌 프로세스에서는 해당 `org.springframework.boot.SpringApplication` 중복 메시지만 logback turbo filter 가 차단한다. 일반 startup failure 가 아닌 예외와 다른 logger/message 는 기존 Spring Boot 로그 경로를 유지한다. - **`REQUIRED_ADAPTER_DISABLED`(`StartupFailures.requiredAdapterDisabled`)는 런타임-라이프사이클의 `ADAPTER_DISABLED`와 의도적으로 구분된다.** 이쪽은 *시작* 검증(필수 어댑터/조정 빈이 꺼져 있음)이고, 후자는 비활성 옵션 어댑터에 대한 *런타임* 호출이다.