Files
clean-architecture-backend-…/docs/notification/configuration-reference.md
T
DongHyeonka 5a860e1e6b docs(notification): 알림 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: `docs/notification`의 살아 있는 문서 10개가 영어였다. 번역하며 대조하니
설정 참조와 위협 모델이 지금 코드와 다른 말을 했다.

고친 것:
- 10개를 번역했다(ADR은 다른 세션 몫이라 두었다). 코드·설정 키·환경 변수·표 구조는
  그대로다.
- 코드에 맞춘 주장:
  - configuration-reference: 바인딩에 없는 `callbacks.trusted-proxies`
    (`APP_NOTIFICATION_PLATFORM_CALLBACK_TRUSTED_PROXIES`)를 지우고 실제 방법
    (`APP_SERVER_FORWARD_HEADERS_STRATEGY=native`, `server.tomcat.remoteip.internal-proxies`)을
    적었다. 근거는 `notification.yml` 주석과 env-keys registry다.
  - at-rest-threat-model: 「facade를 아무도 import하지 않아 JPA 영속성이 없다」는 낡았다.
    지금은 persistence-notification의 `AutoConfiguration.imports`가 facade를 올리고,
    `NotificationPayloadAtRestContractTest`가 그것을 단언한다. 지금 상태를 앞에 쓰고
    결정 당시 분석은 `> 이력` 블록으로 옮겼다. 설정 참조와 YAML이 「교체 순서는 이
    문서에 있다」고 하는데 없어서, `historical-keys`와 `SettingsSecretMaterialProvider`
    대로 짧은 교체 순서를 더했다.
  - module-mapping: plan API 모듈의 leaf `application-core` → `application-notification`,
    「19 leaf」 → registry, relay 조립 `app-bootstrap` → `composition:outbox-relay`, 남은
    provider 패키지는 `ses`·`smtp`뿐.
- `support-matrix.md`: 등급 칸 제목을 `등급`으로, 거부 절을 「## 지원하지 않는 것」으로
  옮겼다. 등급 값(manifest의 키)은 그대로다.
- 테스트: `NotificationEvidenceVerifier`가 `Grade` 대신 `등급` 칸을 읽는다(영어 칸만
  있으면 「등급을 매기는 표가 없다」로 닫힌 채 실패한다). `NotificationReleaseGateTest`는
  거부 절 제목과 전달 보장·읽음 보장·정확히 한 번을 단언하고, 앞 절에는 한국어와 영어
  표현이 모두 없어야 한다. `DEVICE_DELIVERED`·`DELIVERED` 승격 거부 문장도 한국어로 본다.
- 예외 목록에서 알림 language 줄 10개를 지웠다.

버린 대안: 등급 칸 제목을 `Grade`로 두기. 검증기가 읽는 키라서 바꾸지 않아도 됐지만,
한국어 문서에 영어 칸 하나가 남고 그 이유를 문서에 따로 적어야 한다. 검증기의 상수
하나를 바꾸는 쪽이 작다.

위험·한계: 위협 모델은 결정 기록 성격이 섞인 살아 있는 문서다. 결정 당시 글은
`> 이력` 블록에 뜻을 그대로 옮겼다.

검증: 최종 트리 기준(첫 커밋 본문 참고).

검증(desktop, 최종 트리 8295db89):
- `:adapter:outbound:notification:check` rc=0(375개 건너뜀 1 실패 0. `NotificationReleaseGateTest` 3,
  `NotificationEvidenceVerifierTest` 7, `NotificationModeSsotTest` 3, `NotificationPayloadAtRestContractTest` 5),
  `:mainCheck` rc=0(`notificationDocumentContractTest`의 저장소 문서 대조 통과), `testQualityCheck` rc=0.
- RED: 기준 커밋의 옛 문서에 대면 `NotificationReleaseGateTest` 2개와 저장소 문서 대조가 실패한다
  ("support-matrix.md has no table that assigns a grade (a '등급' column …)").
2026-11-07 17:56:34 +09:00

15 KiB

설정 참조

알림 전달 플랫폼은 app.notification.platform 아래에 묶인다. 설정 트리는 src/composition/notification-platform/src/main/resources/config/module-defaults/notification.yml에 있고, support leaf의 ModuleDefaultsEnvironmentPostProcessor가 가장 낮은 우선순위로 읽는다. 그래서 이 모듈이 없는 애플리케이션에는 이 설정이 하나도 없다. 이 모듈은 어느 기본 조립에도 없다. 서비스가 app-bootstrap/build.gradle에 runtimeOnly project(':composition:notification-platform')(와 persistence-jpa 줄)를 더해 고르고, 모듈이 있으면 켜진다. 값마다 기본값이 붙어 있으므로 플랫폼을 끄는 배포는 아무것도 주지 않아도 된다.

이력: 2026-08-15까지 이 문서는 바인딩에 없는 속성(max-retry-concurrency, scheduler-poll-interval, callback-worker-concurrency)을 적었고, 있는 속성 셋을 빠뜨렸다. application.yml에 트리가 아예 없어서, 플랫폼을 설정하려면 Boot의 relaxed binding으로 환경 변수 이름을 짐작해야 했다.

지금은 내보내는 YAML과 docs/registries/env-keys.yaml이 다르면 NotificationEnvironmentRegistryTest (:composition:notification-platform:test)가 실패한다.

주 스위치

속성 환경 변수 기본값 뜻
enabled APP_NOTIFICATION_PLATFORM_ENABLED true 모듈이 있으면 켜진다. false면 아무것도 묶지 않는다. 런타임도, 스키마 검사도, scheduler 스레드도, 필요한 secret도 없다
mode APP_NOTIFICATION_PLATFORM_MODE SERVING SERVING은 동작하는 provider가 없으면 뜨기를 거부한다. INGEST_ONLY는 요청을 저장만 하고 보내지 않는다. provider 런타임을 만들지 않지만 켜진 profile마다 route를 기록하므로, 지금 받은 요청은 나중에 SERVING 배포가 그 route로 보낸다(handoff)

발송

속성 환경 변수 기본값 범위
dispatch.claim-batch-size APP_NOTIFICATION_PLATFORM_CLAIM_BATCH_SIZE 50 1..1000
dispatch.lease-duration APP_NOTIFICATION_PLATFORM_LEASE_DURATION 2m 양수, 유한
dispatch.poll-interval APP_NOTIFICATION_PLATFORM_POLL_INTERVAL 1s 양수, 유한
dispatch.max-global-concurrency APP_NOTIFICATION_PLATFORM_MAX_CONCURRENCY 64 양수
dispatch.max-additional-attempts APP_NOTIFICATION_PLATFORM_MAX_ADDITIONAL_ATTEMPTS 4 0 이상
dispatch.max-queue-age APP_NOTIFICATION_PLATFORM_MAX_QUEUE_AGE 24h 양수
dispatch.allow-ambiguous-fallback APP_NOTIFICATION_PLATFORM_ALLOW_AMBIGUOUS_FALLBACK false boolean

모든 값에 상한이 있다. 「무제한」은 받는 설정이 아니다.

lease는 provider 호출과 그 시간 상한보다 길어야 한다. 그보다 짧으면, 살아 있는 worker가 아직 기다리는 전달을 두 번째 worker가 claim하고, 수신자는 알림을 두 번 받는다.

콜백

속성 환경 변수 기본값 범위
callbacks.enabled APP_NOTIFICATION_PLATFORM_CALLBACKS_ENABLED false boolean
callbacks.max-body-bytes APP_NOTIFICATION_PLATFORM_CALLBACK_MAX_BODY_BYTES 65251 1..65251
callbacks.replay-skew APP_NOTIFICATION_PLATFORM_CALLBACK_REPLAY_SKEW 1h 양수. Timestamp가 받은 시각에서 이보다 멀리(앞이든 뒤든) 떨어진 SNS 메시지는 거절한다. 기본값은 SNS의 HTTP/S 재시도 기간 중 가장 긴 값(3,600 s)이라, 장애 뒤에 SNS가 다시 보내는 bounce·complaint도 받는다. 창 안의 replay는 provider event ledger에서 중복이지 두 번째 이벤트가 아니다(review 05-20)

콜백 응답: 기록(중복 포함) 204, 거절 400(서명·topic·시각·형식), 본문 초과 413. SNS 서명 인증서를 가져오지 못하면(5xx·408·429·네트워크 실패) 거절하지 않고 503+Retry-After로 답한다. SNS는 4xx를 처리 완료로 보고 재전송을 멈추지만 5xx는 다시 보낸다(review 05-20). 인증서 URL이 그 밖의 4xx(403·404 등)로 답하면 SNS가 발급하지 않은 인증서를 가리킨 위조 콜백이므로 서명 검증 실패로 400 거절하고 보안 감사(callbackSignatureRejected)에 남긴다(review 2026-11-03 RR-07-03). 호스트 검사를 통과한 URL이라 답하는 쪽은 SNS다.

여러 provider가 요청 URL에 서명하므로, 그 URL을 잘못 재구성하면 정상 webhook이 전부 서명 실패가 된다. provider가 서명한 URL은 컨테이너가 보고한 값으로 다시 만든다. 콜백 전용 proxy 목록은 없다. 로드밸런서 뒤에 있는 배포는 APP_SERVER_FORWARD_HEADERS_STRATEGY=native로 두고 그 proxy를 server.tomcat.remoteip.internal-proxies에 적는다. forwarded 헤더를 무조건 믿으면 아무 호출자나 자기 서명이 검증될 URL을 고를 수 있어 서명 자체가 무의미해진다.

65251은 우연히 고른 수가 아니다. 암호문 칸의 65536바이트에서 protector가 쓰는 가장 큰 envelope를 뺀 값이다. version 바이트, key id 길이 바이트, 255바이트까지의 key id, AES-GCM nonce와 tag다. 이보다 큰 값은 설정을 묶을 때 거부되므로 capability가 뜨지 않는다. 그 검사가 생기기 전에는 DB 위의 모든 층을 통과한 뒤, 콜백을 provider에 이미 확인 응답한 다음 CHECK 제약에서 실패했다.

이력: envelope에 key id가 붙은 뒤에도 한동안 내보낸 기본값이 65508(nonce와 tag만 뺀 값)이었고, 플랫폼을 켠 배포는 그 값을 고칠 때까지 모두 뜨지 못했다(review 2026-11-01 r3-i, compose lane을 띄워서 찾음).

provider profile

profile은 providers 아래의 map이고, 키는 profile id다. 배포가 정한 아무 id나 YAML이나 Spring relaxed binding (APP_NOTIFICATION_PLATFORM_PROVIDERS_<ID>_<FIELD>)으로 줄 수 있다. 내보내는 참조 profile smtp와 ses는 그 밖에 APP_NOTIFICATION_PLATFORM_SMTP_*와 APP_NOTIFICATION_PLATFORM_SES_* 별칭도 드러내므로, 운영자가 바인딩 이름을 지어낼 필요가 없다.

칸 뜻
type SES, SMTP. 닫힌 enum이라 모르는 값은 아무것도 조립하지 않고 넘어가는 대신 바인딩에서 실패한다
enabled 꺼진 profile도 묶이고 검증되지만 런타임에 아무것도 보태지 않는다
primary-for-channel 채널마다 primary는 정확히 하나
environment 켜면 필요하다
credential-profile SecretMaterialProvider로 푸는 provider 자격 증명 key id. secret 값을 직접 적지 않는다
timeout 양수, 유한
max-concurrency 양수
rate-per-second 양수

profile 하나가 provider 종류, 환경, 자격 증명 profile, 시간 상한, 동시성, 속도 제한을 고정한다. 보내는 쪽 신원과 자격 증명 profile은 서로 다른 문제다.

SES profile 칸

켜진 SES profile에는 타입이 있는 ses 블록이 더해진다.

칸 뜻
ses.endpoint SES API 기본 URI. AWS SDK 클라이언트의 endpoint override로 쓴다
ses.region SDK가 서명하는 AWS region
ses.sender-identity 검증된 SES From 신원
ses.access-key-id AWS access key id. 식별자일 뿐 secret 값이 아니다
ses.configuration-set 선택. SES configuration-set 이름
ses.allowed-topic-arns 이 profile이 SES 이벤트를 받는 SNS topic ARN(APP_NOTIFICATION_PLATFORM_SES_ALLOWED_TOPIC_ARNS, 쉼표로 구분). callbacks.enabled=true면 필요하다. 없으면 바인딩이 실패한다. 유효한 SNS 서명은 AWS가 메시지를 보냈다는 것만 증명하고, topic은 누구나 가질 수 있기 때문이다
credential-profile secret access key 값의 key id. 조립할 때 세대 1이 활성화된다

내보내는 참조 profile은 providers.ses이고 기본으로 꺼져 있다. APP_NOTIFICATION_PLATFORM_SES_*로 다룬다. secret 값은 APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY에서 오고, 그 활성 key id는 APP_NOTIFICATION_PLATFORM_SES_CREDENTIAL_KEY_ID와 같아야 한다.

type에는 내보내는 조립이 만들 수 있는 family만 있다. 지금 내보내는 것으로 닿는 범위는 다음과 같다.

provider 종류 계약·어댑터 코드 내보내는 발송 assembler 내보내는 콜백 assembler 발송용으로 켜면
SMTP 있음 있음 없음 Spring Mail relay 설정이 다 있으면 조립한다
SES 있음 있음 있음 타입 있는 ses 블록으로 EMAIL 런타임을 조립한다. SNS 콜백 검증은 INGEST_ONLY에서도 쓸 수 있다

APNs, FCM, Twilio, Web Push, Webhook 어댑터는 assembler 없이 프로토콜 코드로만 들어 있어서 켜면 기동이 실패했다. 그래서 지웠다. 마지막으로 그것을 가진 커밋은 docs/capability-status.md 「제거된 코드」 표가 적는다. family를 다시 더하려면 그 어댑터, ProviderRuntimeAssembler, ProviderType 상수, 실제로 필요한 설정·secret 입력을 함께 더한다.

SMTP relay

템플릿이 내보내는 provider profile 하나이고, 꺼져 있다. 흔한 경우를 원하는 배포는 APP_NOTIFICATION_PLATFORM_SMTP_ENABLED=true와 relay 주소를 준다. 다른 profile id나 두 번째 family를 원하는 배포는 대신 자기 YAML에 선언한다.

profile과 relay는 다른 질문에 답하므로 아래 두 표로 나눈다. profile은 어느 provider가 EMAIL을 어떤 한도로 맡는지를 말하고, relay는 전송이 무엇인지를 말한다. host, port, 자격 증명은 여기에 아예 없다. spring.mail.*에 그대로 둔다. Spring이 이미 그것을 가지고 있고, 두 번째 표기는 맞춰 둘 것을 하나 더 만든다.

속성 환경 변수 기본값 범위
providers.smtp.enabled APP_NOTIFICATION_PLATFORM_SMTP_ENABLED false boolean
providers.smtp.primary-for-channel APP_NOTIFICATION_PLATFORM_SMTP_PRIMARY true boolean. 채널마다 primary는 정확히 하나
providers.smtp.environment APP_NOTIFICATION_PLATFORM_SMTP_ENVIRONMENT local 켜면 필요하다
providers.smtp.credential-profile APP_NOTIFICATION_PLATFORM_SMTP_CREDENTIAL_PROFILE default SecretMaterialProvider로 푼다. 값을 직접 적지 않는다
providers.smtp.timeout APP_NOTIFICATION_PLATFORM_SMTP_TIMEOUT 10s 양수, 유한
providers.smtp.max-concurrency APP_NOTIFICATION_PLATFORM_SMTP_MAX_CONCURRENCY 4 양수
providers.smtp.rate-per-second APP_NOTIFICATION_PLATFORM_SMTP_RATE_PER_SECOND 10 양수
속성 환경 변수 기본값 범위
smtp.sender-identity APP_NOTIFICATION_PLATFORM_SMTP_SENDER_IDENTITY no-reply@example.invalid 주소
smtp.dispatch-concurrency APP_NOTIFICATION_PLATFORM_SMTP_DISPATCH_CONCURRENCY 4 양수

SMTP 전송 설정의 소유자는 Spring Mail 하나다. 실제 JavaMailSenderImpl은 필수 STARTTLS (mail.smtp.starttls.enable=true와 mail.smtp.starttls.required=true)나 암묵적 TLS(mail.smtp.ssl.enable=true)를 써야 한다. mail.smtp.connectiontimeout, mail.smtp.timeout, mail.smtp.writetimeout도 양수여야 한다. 이 속성이 없거나 틀리면 SMTP 조립이 트래픽을 받기 전에 실패한다.

환경 변수 계약은 Spring 그대로다. SPRING_MAIL_HOST, SPRING_MAIL_PORT, 선택인 SPRING_MAIL_USERNAME과 secret SPRING_MAIL_PASSWORD, 그리고 .env.example에 있는 SPRING_MAIL_PROPERTIES_MAIL_SMTP_* TLS·시간 상한 키다. Spring Boot 자신이 spring.mail.*를 가지고 읽으므로 이름을 Spring 그대로 둔다. 알림 모듈은 같은 relay에 두 번째 별칭을 만들지 않는다.

기본 보내는 주소는 어디로도 풀리지 않는 RFC 2606 예약 도메인이다. 그래서 보내는 주소 설정을 잊은 배포는, 자기가 가지지 않은 주소로 메일을 보낸 것처럼 보이는 대신 추적할 수 있는 bounce를 낸다.

기동 실패

다음이면 기능을 줄여 뜨지 않고 기동이 실패한다.

  • payload나 큐 설정에 상한이 없다
  • 시간 상한이 음수다
  • TTL이 필요한 profile에 만료 출처가 없다
  • 콜백 서명 secret이 없다
  • 운영 profile이 trust-all을 켠다
  • SES profile에 ses 블록이 없거나, 콜백이 켜졌는데 ses.allowed-topic-arns가 비어 있다
  • 두 provider profile의 id가 같다
  • route가 꺼진 provider만 가리킨다
  • mode가 SERVING인데 켜진 provider profile이 없다
  • 알림 스키마 stream이 적용·승격되지 않았다

secret

키 값은 모두 SecretMaterialProvider로 들어온다. 소스, 커밋한 파일, 평문 로그에서는 아무것도 읽지 않는다. 연락처 암호화 키와 조회 HMAC 키는 서로 달라야 하고, 암호화 키는 정확히 256비트여야 한다.

목적 일곱, 키 일곱이다. 각각 32바이트 이상의 base64이고 다른 모든 키와 달라야 한다. 플랫폼은 기동할 때 키를 풀어 보고, 하나라도 비었거나 짧거나 겹치면 뜨기를 거부한다. 전에는 빈 값을 건너뛰었고, 그래서 플랫폼이 키 없이 뜬 뒤 첫 연락처에서야, 운영에서는 수신자의 알림에서야 그것을 알았다.

아래 기본값은 모두 일부러 비어 있다. 값은 환경마다 따로 준다. 이 표, application.yml, 추적되는 .env 파일, 어느 예시에도 값을 쓰지 않는다. 저장소에 나타난 값은 이미 드러난 값이다.

목적 키 값 활성 key id
연락처 암호화 APP_NOTIFICATION_PLATFORM_CONTACT_ENCRYPTION_KEY APP_NOTIFICATION_PLATFORM_CONTACT_ENCRYPTION_KEY_ID
연락처 조회 HMAC APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY_ID
콜백 서명 APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY_ID
콜백 fingerprint HMAC APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY_ID
provider 자격 증명 암호화 APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY_ID
provider 요청 조회 HMAC APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY_ID
payload 암호화 APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY_ID

key id는 secret이 아니다. id는 키 값을 드러내지 않고 그것을 가리킨다. 그래도 필요하고, 일부러 기본값이 없다. 고정된 id는 교체를 바뀌기 전 키와 구별할 수 없게 만들어서, 그 전에 쓴 것을 아무것도 풀지 못하게 한다. 키 값을 바꾸는 배포에서 id도 함께 바꾸고, 밀려난 키는 그 키로 쓴 데이터를 다시 암호화할 때까지 옛 id로 읽을 수 있게 둔다. 교체 순서는 at-rest-threat-model.md에 있다.

readiness

플랫폼은 notifications actuator 엔드포인트와 health indicator를 보탠다. provider 자격 증명이 거부됐을 때, 설정된 provider에 채널 route가 없을 때, 그리고 잰 backlog, 멈춘 lease 수, projection 지연, 맞추기(reconciliation) 지연이 NotificationServingThresholds의 임계값을 넘을 때 DOWN을 보고한다. operations.md를 본다.