Files
messaging-library/docs/messaging/configuration-reference.md
T
DongHyeonka a32b67a2ce fix!: 재리뷰가 찾은 결함과 색인에서 빠졌던 발견 5건을 고친다
문제: 성숙도 리뷰 수정을 다시 읽은 재리뷰(Critical 0, 회귀 0)가
Important 27건·Minor 41건을 찾았다. 수정이 새로 만든 결함이 많았다.
@SystemInvoked가 권한 규칙의 탈출구가 됐고, 데모 계정 거부가 정확히
prod일 때만 걸렸고, outbox 순서 번호가 업그레이드 때 뒤로 갔고,
GraphQL union 아래 복잡도가 0이었고, 서블릿 오류 응답이 success:true로
나갔고, 호출자 deadline이 breaker를 열었다. 원래 리뷰 색인이 06 영역
발견 5건(06-10~14)을 빠뜨려 그동안 처리되지 않았다.

방법: 영역별 7묶음이 test-driven-development 절차로 실패 테스트를
먼저 쓰고 고쳤다. 결정은 재리뷰 README 4절에 적었다: 순서 번호는 V21이
기록한 전역 floor부터, 데모 계정은 local·test·demo 허용 목록,
@SystemInvoked bean은 기동 실패, complete 단계 실패는
IDEMPOTENCY_COMPLETION_UNKNOWN(결과 불명), 캐시 조건부 쓰기는 별도
SCRIPT lane, strict lane 정책은 build cache 입력, 끝나지 않는 재시도
행은 원인 코드·지표·PARKED 절차. 레지스트리가 선언만 하고 아무 코드도
내보내지 않던 redis.capability.* 지표 6개는 빼고 runbook을 실제
지표(redis.lane.*) 기준으로 고쳤다.

위험·한계: V21을 V22 없이 직접 고쳤다(어느 배포에도 아직 없음). 이
브랜치의 V21을 적용한 개발 DB는 다시 만들어야 한다. 서블릿 오류
디스패치를 보안 체인이 허용한다. 발행·저장소 포트 시그니처가 바뀌어
파생 서비스 코드가 깨진다. prod에서 fixture-로 시작하는 설정값은
기동을 막는다. httpclient failure-injection lane의 main 단계 중복
실행은 이전 결정대로 남겼다. 실제 CI runner 실행은 확인하지 못했다.

검증: ci, mainCheck, :integrationCheck, -p optional-platforms ci
integrationCheck performanceCheck, :performanceCheck, :releaseCheck
(-PgitRevision), verify-compose-profile-contracts(18 lane) 통과.
첫 실행의 실패 2건(FindSecBugs 1, sample 동시 생성 테스트의 v4 event
id)은 고친 뒤 ci·integrationCheck·mainCheck를 다시 돌려 통과했다.

Refs: docs/reviews/2026-11-03-rereview/README.md 3·4·6·7절
BREAKING CHANGE: outbox 발행 포트와 저장소 포트 시그니처, 순서 번호
첫 값(V21 floor 다음), 샘플 데모 계정 프로필 허용 목록, 새 오류 코드
IDEMPOTENCY_COMPLETION_UNKNOWN, prod의 fixture- 값 거부, 기동 rule은
static·의존 없음이어야 한다.
2026-11-03 23:29:35 +09:00

13 KiB

설정 레퍼런스

Prefix. Every property below binds under app.messaging, which is the prefix the deployed runtime and the APP_MESSAGING_* environment variables already use. Earlier revisions of this page documented a bare messaging prefix and the starter bound backend.messaging; neither bound what this page describes, so a deployment configured from it changed nothing. A key under either of the old prefixes now fails startup with a message naming the key — see MessagingPrefixMigrationValidator.

이 페이지는 실행된다. 아래 YAML 블록은 MessagingConfigurationBindingTest가 이 파일에서 직접 읽어 컨텍스트에 올린다. 문서가 설명하는 모양이 곧 바인딩되는 모양이라는 뜻이고, 문서를 고치면서 코드를 고치지 않으면 테스트가 깨진다. 이전 판은 destination·broker·security 세 섹션을 설명했지만 어떤 binder도 그것을 읽지 않았다 — 문서대로 설정한 배포는 아무것도 바뀌지 않았고 아무 말도 듣지 못했다 (MSG-008).

Application publish bridge identity

Application의 canonical integration event를 platform publish pipeline으로 보낼 때는 app.messaging.producer-id를 명시한다. 같은 값의 환경변수 이름은 APP_MESSAGING_PRODUCER_ID다. 이 값은 host/pod 이름이 아니라 배포와 무관하게 유지되는 논리적 producing-service identity다.

값이 없으면 IntegrationEventPublishPort bridge 자체를 만들지 않는다. spring.application.name이나 현재 process 이름으로 추론하지 않는다. 모든 발행(outbox relay 포함)이 이 bridge를 지나므로 messaging 모듈이 켜진 상태에서 값이 없으면 기동이 거부된다.

Outbox

application의 발행 경로는 하나다(2026-09-28): outbox_event 표와 composition:outbox-relay. vendored platform의 messaging_outbox(outbox-inbox.md)는 이 경로에 쓰이지 않는다 — 두 모델의 상태 대응은 outbox-inbox.md 머리의 표에 있다. use case가 IntegrationEventEncoderPort로 만든 ValidatedIntegrationEvent를 OutboxAppendPort로 append하고, relay는 claim한 row의 exact envelope bytes를 IntegrationEventPublishPort로 보낸다. 예전의 app.outbox.canonical-transport-enabled gate와 legacy MessageBroker → KafkaSender 경로는 삭제됐다. 발행할 contract의 logical destination마다 아래 destination profile을 선언한다(템플릿의 durable operation event는 durable-operations).

Destination profile

app:
  messaging:
    destinations:
      order-events:
        broker: kafka-primary
        kind: EVENT_STREAM          # ASYNC_COMMAND | DOMAIN_EVENT | INTEGRATION_EVENT
                                    # | WORK_QUEUE | PUBLISH_SUBSCRIBE | EVENT_STREAM | REQUEST_REPLY
        tier: M1                    # M1 | M2 | M3
        physical:
          topic: order.events.v1
        schema:
          codec: application/json
          compatibility: BACKWARD_TRANSITIVE
          message-types: [order.created]
        guarantees:
          delivery: AT_LEAST_ONCE   # AT_MOST_ONCE | AT_LEAST_ONCE
          ordering: KEY             # NONE | DESTINATION | PARTITION | KEY
          external-side-effect: INBOX_TRANSACTIONAL
        producer:
          confirmation: REPLICATION_OR_PERSISTENCE_ACK
          timeout: 5s
          mandatory-routing: true
          idempotent: true
        consumer:
          group: order-projection
          concurrency: 1            # DESTINATION 순서를 요구하면 1이어야 한다
          max-in-flight-per-ordering-unit: 1
          prefetch: 16
          handler-timeout: 30s
          manual-settlement: false
        retry:
          mode: PAUSE_PARTITION     # NONE | INLINE | BLOCKING | PAUSE_PARTITION
                                    # | RETRY_DESTINATION | BROKER_DELAYED
          max-attempts: 3
          initial-delay: 200ms
          max-delay: 2s
          multiplier: 2.0
          jitter: true
          ordering-impact: PRESERVE # PRESERVE | ALLOW_REORDER
        dlq:
          destination: order-events-dlq
          max-redrive-count: 1
        payload:
          max-bytes: 1048576
          claim-check-threshold-bytes: 1048576
        key-resolver-configured: true
        production: false
        topology-auto-create: false
      order-events-dlq:
        broker: kafka-primary
        kind: WORK_QUEUE
        guarantees:
          delivery: AT_MOST_ONCE    # terminal DLQ: another DLQ is not required
        physical:
          topic: order.events.v1.dlt
        schema:
          message-types: [order.created]

dlq.destination이 가리키는 destination도 선언되어야 한다. 선언되지 않은 이름은 부팅 실패이며, 메시지가 갈 곳 없는 DLQ 설정이 조용히 통과하지 않는다. retry.destination과 dlq.destination이 섞여 만드는 순환(A의 retry가 B로, B의 dlq가 A로)도 하나의 그래프로 검사되어 경로와 함께 거절된다.

기본값

설정 기본값 근거
logical payload 최대 1,048,576 bytes portability. 초과는 Claim Check
global hard 최대 8,388,608 bytes 어떤 destination도 넘을 수 없는 상한
header 총 크기 32,768 bytes
header 개수 64
header key 128 bytes metric tag 안전
header value 4,096 bytes
publish timeout 5s
handler timeout 30s
graceful shutdown drain 30s
일반 destination retry 0회 자동 retry는 opt-in
DLQ redrive batch 100 한 번의 작업이 source를 덮치지 않게
Outbox relay batch 100
Outbox lease 30s
Outbox polling 500ms
metric dimension 상한 200 cardinality 폭발 방지

schema.codec은 application/json, schema.compatibility는 BACKWARD_TRANSITIVE,

현재 강제 범위: schema.compatibility 값은 현재 정책 선언이며 runtime/CI에서 schema registry를 조회해 호환성을 차단하지 않는다. Avro 비교기는 독립 utility/test로만 존재한다. 따라서 이 값을 설정했다고 breaking schema가 자동 거부된다고 해석하면 안 된다. 실제 registry gate가 wiring되기 전까지 호환성은 adopter의 schema CI가 소유한다.

guarantees.delivery는 AT_LEAST_ONCE, retry.mode는 NONE이 기본값이다. 자동 retry가 기본으로 꺼져 있는 이유는 순서를 흐트러뜨리거나 비멱등 side effect를 두 번 실행하는 retry가 눈에 보이는 실패보다 나쁘기 때문이다.

Broker profile

브로커는 app.messaging.brokers 아래에 한 번만 기술한다. type은 kafka만 받는다 — transport가 있는 계열이 Kafka 하나뿐이다. RabbitMQ 키(addresses, prefetch, quorum-queues 등)와 type: rabbitmq는 2026-09-25에 설정 모델에서 삭제됐다. 연결할 transport 없이 바인딩만 되던 키라, 지금은 무시되지 않고 키 이름을 담아 부팅 실패로 거절된다.

Kafka

app:
  messaging:
    brokers:
      kafka-primary:
        type: kafka
        stable: true
        production: false
        bootstrap-servers: [broker-1:9093, broker-2:9093]
        enable-idempotence: true    # stable에서 필수
        acks: all                   # stable에서 필수
        max-in-flight-requests-per-connection: 5   # 최대 5
        delivery-timeout: 30s
        enable-auto-commit: false   # 항상 금지
        consumer-group: order-projection
        tls-enabled: false          # production이면 필수
        authentication-enabled: false  # production이면 필수

production: true인 Kafka 브로커는 tls-enabled와 authentication-enabled가 모두 참이어야 하고, 그렇지 않으면 KafkaProfileValidator가 부팅을 거절한다. app.messaging.broker로 고를 수 있는 값은 kafka뿐이다. 위 예시가 production: false인 것은 이 페이지가 그대로 실행되는 fixture이기 때문이며, 실 배포는 셋 다 참이다.

Kafka producer는 이 항목 하나로 만든다. bootstrap-servers, acks, enable-idempotence, max-in-flight-requests-per-connection, delivery-timeout이 그대로 client 설정이 된다. spring.kafka.bootstrap-servers는 읽지 않는다. type이 kafka인 항목이 정확히 하나가 아니면 기동에 실패한다. send()가 metadata를 기다리며 호출 스레드를 막는 시간(max.block.ms)은 기본 publish timeout(5s)이다.

보안

app:
  messaging:
    security:
      kafka-primary:
        producer: { type: SASL_SCRAM, credential-id: kafka-producer }
        consumer: { type: SASL_SCRAM, credential-id: kafka-consumer }
        # admin은 application runtime에 설정하지 않는다
        hostname-verification: true
        # 사설 CA로 서명된 TLS 브로커면(tls-enabled: true일 때만):
        # trust-store: { location: /etc/kafka/ca.p12, type: PKCS12, password-credential-id: kafka-truststore }
        access:
          publishable: [order-events]
          consumable: []
          administrable: []

키는 app.messaging.brokers에 선언된 브로커 이름과 같아야 한다. tls-enabled와 production은 브로커 쪽에만 있고 여기에 중복되지 않는다 — 하나의 브로커가 두 곳에서 기술되면 두 값이 어긋나는 날이 오고, 어느 쪽이 이기는지는 아무도 모른다.

credential-id는 이름일 뿐이고 자격 증명 자체가 아니다. 실제 재료는 CredentialProvider가 연결 시점에 해석하므로, 설정 덤프나 힙 덤프에서 나오는 것은 이름뿐이다. producer와 consumer는 서로 다른 credential-id를 써야 하며, 같으면 부팅에 실패한다.

SASL_SCRAM·USERNAME_PASSWORD의 사용자 이름은 CredentialProvider.username(credentialId)가 준다. credential id를 사용자 이름으로 보내지 않는다. 비밀번호와 사용자 이름은 JAAS 문자열에 들어가지 않고, 연결이 인증할 때마다 provider에서 읽힌다. 그래서 provider가 만료 시각을 주는 credential은 재기동 없이 rotation된다(security.md).

MUTUAL_TLS는 클라이언트 인증서를 key store로 제출한다. credential-id는 key store 비밀번호를 가리킨다.

producer:
  type: MUTUAL_TLS
  credential-id: kafka-producer-tls      # key store 비밀번호
  key-store: { location: /etc/kafka/producer.p12, type: PKCS12 }

trust-store를 생략하면 JVM 기본 trust store를 쓴다. 사설 CA 브로커는 trust-store.location (PKCS12·JKS·PEM)과, 잠긴 store면 password-credential-id를 준다.

Kafka producer는 이 항목을 실제 클라이언트 설정(security.protocol, sasl.mechanism, sasl.jaas.config, sasl.client.callback.handler.class, ssl.truststore.*, ssl.keystore.*, ssl.enabled.protocols=TLSv1.3,TLSv1.2, hostname 검증)으로 옮긴다. 평문으로 조용히 넘어가지 않도록 다음 경우 부팅에 실패한다: 브로커가 tls-enabled나 authentication-enabled를 켰는데 app.messaging.security.<broker>가 없을 때, security 항목은 있는데 CredentialProvider bean이 없을 때, 같은 브로커에 맞는 항목이 둘 이상일 때, provider가 SASL 사용자 이름을 주지 않을 때, MUTUAL_TLS인데 key-store가 없거나 tls-enabled가 꺼져 있을 때, trust-store를 줬는데 tls-enabled가 꺼져 있을 때, store 파일을 열 수 없을 때.

access.publishable은 강제된다. security 항목이 있는 브로커의 destination은 이 목록에 있어야 publish된다. 목록 밖 publish는 REJECTED(PUBLISH_FORBIDDEN)이고, 빈 목록이면 아무것도 publish되지 않는다.

Backpressure

app:
  messaging:
    backpressure:
      global-limit: 512
      per-destination-limit: 64    # global-limit 이하여야 한다

per-destination-limit > global-limit이면 global limit이 limit이 아니게 되므로 부팅에 실패한다.

바인딩되지 않는 키

섹션은 바인딩되는데 그 안의 키 하나가 오타인 경우는 접두사 오타와 달리 조용하다 — 섹션은 붙고, 플랫폼은 뜨고, 바꾸러 온 그 설정만 적용되지 않는다. MessagingConfigurationKeyValidator가 app.messaging.destinations|brokers|security 아래의 모든 키를 settings 레코드에서 파생한 목록과 대조하고, 없는 키는 그 키 이름을 담아 부팅을 거절한다.

허용 키 목록은 이 문서가 아니라 레코드에서 나온다. 문서에 목록을 적으면 필드가 추가된 날 그 목록이 틀리고, 오타를 잡으라고 만든 검사가 정상 필드를 거절하게 된다.

환경변수(APP_MESSAGING_...)는 이 검사의 대상이 아니다. APP_MESSAGING_DESTINATIONS_ORDER_EVENTS_ CONSUMER_PREFETCH에서 entry 이름과 leaf를 가르는 밑줄은 둘 안에 있는 밑줄과 구별되지 않으므로, 되돌려 쪼개려면 추측해야 한다. 여기서의 추측은 정상 배포를 거절하는 쪽으로 틀리며, 그것은 배포 매니페스트에 손으로 적어야 하는 변수에서 오타 하나를 놓치는 것보다 나쁘다.