# 설정 레퍼런스

> **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`.


## 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: 6
        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: true
      topology-auto-create: false
```

## 기본값

| 설정 | 기본값 | 근거 |
|---|---:|---|
| 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 폭발 방지 |

## Broker profile

### Kafka

```yaml
app:
  messaging:
  brokers:
    kafka-primary:
      type: kafka
      stable: true
      production: true
      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     # 항상 금지
      tls-enabled: true             # production 필수
      authentication-enabled: true  # production 필수
```

### RabbitMQ

```yaml
app:
  messaging:
  brokers:
    rabbit-primary:
      type: rabbitmq
      stable: true
      production: true
      addresses: [rabbit-1:5671]
      publisher-confirms: true      # stable에서 필수
      publisher-returns: true       # stable에서 필수
      mandatory: true               # stable에서 필수
      confirm-timeout: 5s
      auto-ack: false               # 항상 금지
      prefetch: 16
      quorum-queues: true           # durable work queue 필수
      tls-enabled: true
      authentication-enabled: true
```

## 보안

```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
      access:
        publishable: [order-events]
        consumable: []
        administrable: []
```

## Experimental / Optional

기본값은 전부 `false`다.

```yaml
app:
  messaging:
  experimental:
    kafka-share: false
    pulsar: false
    nats: false
  bridge:
    spring-cloud-stream: false
```

## Backpressure

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

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