설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md
- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
(compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용
삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(b5114b9b)과 함께 기록.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
11 KiB
설정 레퍼런스
Prefix. Every property below binds under
app.messaging, which is the prefix the deployed runtime and theAPP_MESSAGING_*environment variables already use. Earlier revisions of this page documented a baremessagingprefix and the starter boundbackend.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 — seeMessagingPrefixMigrationValidator.
이 페이지는 실행된다. 아래 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 이름으로 추론하지 않는다. 기존 legacy OutboxEvent/realtime 경로는 별도 cutover가
끝날 때까지 app.messaging.broker 경로를 유지한다.
Outbox canonical transport-only cutover
APP_OUTBOX_CANONICAL_TRANSPORT_ENABLED / ca-skeleton.outbox.canonical-transport-enabled은
기존 outbox_event writer/claim/status authority를 유지한 채 canonical row의 transport만 platform
publish path로 보내는 compatibility gate다. 기본값은 false이며 두 번째 relay를 만들지 않는다.
true일 때는 OutboxAppendPort가 ValidatedIntegrationEvent의 exact envelope bytes와 canonical
metadata를 기존 outbox row에 저장하고, claim된 canonical row는 IntegrationEventPublishPort로 간다.
legacy row는 계속 MessageBroker를 사용한다. 따라서 mixed-row compatibility 기간에는 relay가 켜져
있다면 app.messaging.broker도 계속 필요하며, canonical path를 위해 IntegrationEventPublishPort도
추가로 필요하다. legacy backlog가 0이라는 별도 증거 없이 broker 요구를 제거하지 않는다.
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이기 때문이며, 실 배포는 셋 다 참이다.
보안
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: []
키는 app.messaging.brokers에 선언된 브로커 이름과 같아야 한다. tls-enabled와 production은
브로커 쪽에만 있고 여기에 중복되지 않는다 — 하나의 브로커가 두 곳에서 기술되면 두 값이 어긋나는
날이 오고, 어느 쪽이 이기는지는 아무도 모른다.
credential-id는 이름일 뿐이고 자격 증명 자체가 아니다. 실제 재료는 CredentialProvider가
연결 시점에 해석하므로, 설정 덤프나 힙 덤프에서 나오는 것은 이름뿐이다. producer와 consumer는
서로 다른 credential-id를 써야 하며, 같으면 부팅에 실패한다.
Kafka producer는 이 항목을 실제 클라이언트 설정(security.protocol, sasl.mechanism,
sasl.jaas.config, ssl.enabled.protocols=TLSv1.3,TLSv1.2, hostname 검증)으로 옮긴다. 평문으로
조용히 넘어가지 않도록 다음 경우 부팅에 실패한다: 브로커가 tls-enabled나
authentication-enabled를 켰는데 app.messaging.security.<broker>가 없을 때, security 항목은
있는데 CredentialProvider bean이 없을 때, 같은 브로커에 맞는 항목이 둘 이상일 때.
한계: truststore/keystore 설정 키가 없어 TLS는 JVM 기본 truststore를 쓰고, MUTUAL_TLS는 클라이언트
인증서를 제출할 수 없다(미지원).
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를 가르는 밑줄은 둘 안에 있는 밑줄과 구별되지 않으므로,
되돌려 쪼개려면 추측해야 한다. 여기서의 추측은 정상 배포를 거절하는 쪽으로 틀리며, 그것은 배포
매니페스트에 손으로 적어야 하는 변수에서 오타 하나를 놓치는 것보다 나쁘다.