main / main-check (push) Successful in 8m35s
옮겨 온 문서는 템플릿 안의 family를 전제로 쓰였다. 루트 지침은
하네스 뼈대의 빈 양식이고, 모듈 지침·제품 문서는 템플릿 경로
(src/platforms/messaging, src/config/…, cd src)와 템플릿 소비자
(app-bootstrap, adapter:*, composition:*)를 이 repo 안의 것처럼 부른다.
- AGENTS.md(38줄)·CLAUDE.md: 꼭 지킬 것 일곱(api 모듈 순수성, 템플릿
타입·경로 금지, 배포 버전·적용된 migration 불변, 인증 manifest 손으로
고치지 않기 등), 지도, 맡은 일, 검증 진입점.
- README.md: 받는 법(exclusiveContent dev.cakit), migration 위치, 지원 표
(Boot 4.0.9, kafka-clients 4.1.2, apache/kafka:4.1.0, PostgreSQL 16,
Java 21), 구조, 문서 지도, 서명 공개 키(지문 …A1C936D7F791F8AB,
grpc-library와 같은 키), 이력(템플릿 2959eff0에서 filter-repo).
- CHANGELOG.md: 1.0.0 절과 템플릿 안 코드에서 옮기는 법(패키지,
Kafka 설정 키, Gradle 좌표, 바뀌지 않는 것).
- docs/README.md, docs/work/{README,gates,release}.md,
docs/problem-statement.md: grpc-library와 같은 모양으로, 메시징의
인증 증거 게이트·migration 규칙·템플릿과 같이 고치는 경로를 넣었다.
docs/vision.md는 소유자가 쓸 자리라 비워 둔다.
- messaging/AGENTS.md, docs/messaging/*, starter README: registry 경로를
이 repo 기준으로, 템플릿 쪽 경로·타입은 「백엔드 템플릿의」로 밝혔다.
시험이 읽는 문장(지원 표의 broker·버전, 설정 참조의 YAML)은 바꾸지
않았다.
검증: scripts/verify.sh docs rc=0(vision.md 자리 알림만). desktop
mainCheck는 이 커밋 직전 트리에서 rc=0이었다. 문서가 시험에 읽히는
부분은 다음 desktop 실행으로 다시 본다.
Refs: design-docs repo-structure/05-library-repos.md 14.2절
257 lines
13 KiB
Markdown
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`.
|
|
이 라이브러리의 `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를 가르는 밑줄은 둘 안에 있는 밑줄과 구별되지 않으므로,
|
|
되돌려 쪼개려면 추측해야 한다. 여기서의 추측은 정상 배포를 거절하는 쪽으로 틀리며, 그것은 배포
|
|
매니페스트에 손으로 적어야 하는 변수에서 오타 하나를 놓치는 것보다 나쁘다.
|