Files
clean-architecture-backend-…/docs/notification/configuration-reference.md
T
DongHyeonka 2d274a6842
pr / done (pull_request) Canceled after 0s
refactor(application)!: 시스템 쓰기와 운영자 연산을 유스케이스 계약 안으로 옮긴다
시스템이 부르는 쓰기가 유스케이스 계약 밖에 있다. fileserver 정리·맞추기,
알림 claim·발송·lease 회복·맞추기·provider event replay는 capability도
트랜잭션 선언도 없는 서비스를 worker가 바로 부르고, 그 worker와 조립은
outbound adapter 안에 있다. 알림 운영자 연산 넷은 permission 없이 서비스
하나에 모여 있고 재시도 시각은 상수다. web stream bridge는 outbound가
구현한 replay 포트를 바로 읽는다. fileserver 관리 HTTP 기본값은
controller가 정한다.

고른 방법: 시스템 쓰기는 @SystemInvoked 유스케이스로 나누고 composition
worker 설정이 new로 만든다(bean 아님). 알림 worker와 fileserver 정리 조립은
composition으로 옮기고, 맞추기의 재시도·포기 시점은 유스케이스가 정한다.
운영자 연산은 platform.admin의 유스케이스 클래스 넷과 notification-admin:*
permission이다(port.in 인터페이스는 port.in과 admin의 cycle을 만들어 두지
않는다). replay 읽기는 조회 유스케이스 둘을 거치고 포트는
LiveEventReplayQueryPort로 이름을 바꾼다. 아키텍처 규칙 둘: 사용자 전송은
저장·id 포트를 쥐지 못하고, inbound는 application 서비스·coordinator를
interface로도 쥐지 못한다. 재시도 시각은 설정, 관리 기본값은 command
팩터리다. 재시도 시각의 규칙은 policy의 값 RetryTiming 하나가 갖고 설정은
그 값을 만든다. retry·routing 값들은 서버가 만드는 값이라 잘못된 값을
IllegalStateException으로 거절한다(manual 06). 모듈 기본값이 role notification-admin에 운영자 permission
넷을 준다(fileserver의 ROLE_FILE_ADMIN과 같다). 버린 대안: 서비스에
@UseCaseCapability만 달기(사용자와 시스템이 같은 진입점을 나눠 써서 권한
규칙이 막지 못한다), 운영자 서비스 삭제, 설정에서 policy를 만들어 버리며
검증하기(규칙이 바뀐 policy bean과 상관없이 남는다).

위험·한계: 공개 타입·생성자·bean 이름·아키텍처 규칙이 바뀐다. 파생
서비스가 할 일은 docs/upgrade/2026-11-round9-application.md 1~3·5·6행이다.
claim·fence 커밋 위에 쌓았다.

검증: PR 본문의 desktop 결과.

Refs: RR9-05-06, RR9-05-07, RR9-05-08, RR9-05-10, RR9-05-19
BREAKING CHANGE: NotificationAdminService·NotificationAdminApplicationService가 없어지고 운영자 연산은 platform.admin의 RedriveDeliveryUseCase 등이다(permission notification-admin:*). 알림 worker가 composition:notification-platform으로 옮기고 ReconciliationJobWorker·ProviderEventReplayWorker는 유스케이스가 됐다. MessagingReplayBridge 생성자가 조회 유스케이스를 받고 LiveEventReplayPort는 LiveEventReplayQueryPort다. 사용자 전송이 저장·id 포트나 application 서비스 interface를 쥐면 architectureTest가 실패한다. 운영자 요청 record 이름이 *Request로 바뀌고 DefaultNotificationRetryPolicy 생성자가 RetryTiming을 받는다. RetryBackoff·RetryBudget·RetryContext·RetryDecision.RetryAfter·RouteCandidate·RoutingContext·RoutingDecision·EligibilityResult가 잘못된 값에 IllegalStateException을 던진다.
2026-11-13 16:37:03 +09:00

17 KiB

설정 참조

알림 전달 플랫폼은 app.notification.platform 아래에 묶인다. 설정 트리는 src/bootstrap/notification-platform/src/main/resources/config/module-defaults/notification.yml에 있고, support leaf의 ModuleDefaultsEnvironmentPostProcessor가 가장 낮은 우선순위로 읽는다. 그래서 이 모듈이 없는 애플리케이션에는 이 설정이 하나도 없다. 이 모듈은 어느 기본 조립에도 없다. 서비스가 src/bootstrap/app/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 양수, 유한. poll-interval과 켜진 provider profile의 timeout보다 길어야 기동한다
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 호출 한 번이 delivery를 쥐는 시간보다 길어야 한다. 그보다 짧으면 아직 기다리는 호출이 멈춘 lease로 보인다. lease가 끝난 뒤 lease만큼 더 지나도 호출이 끝나지 않았으면, lease 복구가 그 delivery를 버려진 것으로 보고 맞추기로 넘긴다. 기본 제공 provider(SES·SMTP)는 결과 조회가 없어 운영자 확인(RECONCILIATION_REQUIRED)으로 넘어간다. 그 뒤에 끝난 호출도 자기 결과를 기록한다(owner와 fence가 그대로다). 두 번째 worker가 다시 보내지는 않는다. claim은 DISPATCHING인 delivery를 가져가지 않는다.

재시도 시각

속성 환경 변수 기본값 범위
retry.backoff-base 없음 1s 양수. 첫 재시도의 상한이자 가장 짧은 대기
retry.backoff-max 없음 5m backoff-base 이상. provider의 Retry-After도 이 값을 넘지 못한다
retry.reconcile-delay 없음 1m 0 이상. 결과를 모르는 제출 뒤 provider에 처음 물어보기까지

대기는 backoff-base와 지수로 늘어난 상한 사이의 full jitter다. 세 값에는 env 자리표시자가 없다. 배포의 설정 파일(application-{profile}.yml)에서 바꾼다. 값은 provider의 호출 한도에 맞춰 정한다. 템플릿이 정할 일이 아니어서 상수가 아니라 설정이다(2026-11-13).

콜백

속성 환경 변수 기본값 범위
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를 본다.