Files
clean-architecture-backend-…/docs/messaging/configuration-reference.md
T
DongHyeonka bbe944bd3c 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

257 lines
13 KiB
Markdown

# 설정 레퍼런스
> **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
```yaml
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
```yaml
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)이다.
## 보안
```yaml
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 비밀번호를
가리킨다.
```text
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
```yaml
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를 가르는 밑줄은 둘 안에 있는 밑줄과 구별되지 않으므로,
되돌려 쪼개려면 추측해야 한다. 여기서의 추측은 정상 배포를 거절하는 쪽으로 틀리며, 그것은 배포
매니페스트에 손으로 적어야 하는 변수에서 오타 하나를 놓치는 것보다 나쁘다.