Files
clean-architecture-backend-…/docs/notification/configuration-reference.md
DongHyeonka 6a792b8144 refactor(layout)!: 옮긴 경로를 부르는 곳을 모두 새 배치에 맞춘다
문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.

고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
  :composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
  이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
  boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
  project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
  gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
  config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
  (getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
  훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
  rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
  src/를 붙인다. notification API surface의 application-notification 소스
  루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
  건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
  폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
  registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
  써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
  env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
  verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
  check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
  operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
  다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
  capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
  docs/upgrade/2026-11-relayout.md를 더한다.

위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.

검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.

BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
2026-11-11 22:15:42 +09:00

15 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 양수, 유한
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를 본다.