문제: 성숙도 리뷰 수정을 다시 읽은 재리뷰(Critical 0, 회귀 0)가 Important 27건·Minor 41건을 찾았다. 수정이 새로 만든 결함이 많았다. @SystemInvoked가 권한 규칙의 탈출구가 됐고, 데모 계정 거부가 정확히 prod일 때만 걸렸고, outbox 순서 번호가 업그레이드 때 뒤로 갔고, GraphQL union 아래 복잡도가 0이었고, 서블릿 오류 응답이 success:true로 나갔고, 호출자 deadline이 breaker를 열었다. 원래 리뷰 색인이 06 영역 발견 5건(06-10~14)을 빠뜨려 그동안 처리되지 않았다. 방법: 영역별 7묶음이 test-driven-development 절차로 실패 테스트를 먼저 쓰고 고쳤다. 결정은 재리뷰 README 4절에 적었다: 순서 번호는 V21이 기록한 전역 floor부터, 데모 계정은 local·test·demo 허용 목록, @SystemInvoked bean은 기동 실패, complete 단계 실패는 IDEMPOTENCY_COMPLETION_UNKNOWN(결과 불명), 캐시 조건부 쓰기는 별도 SCRIPT lane, strict lane 정책은 build cache 입력, 끝나지 않는 재시도 행은 원인 코드·지표·PARKED 절차. 레지스트리가 선언만 하고 아무 코드도 내보내지 않던 redis.capability.* 지표 6개는 빼고 runbook을 실제 지표(redis.lane.*) 기준으로 고쳤다. 위험·한계: V21을 V22 없이 직접 고쳤다(어느 배포에도 아직 없음). 이 브랜치의 V21을 적용한 개발 DB는 다시 만들어야 한다. 서블릿 오류 디스패치를 보안 체인이 허용한다. 발행·저장소 포트 시그니처가 바뀌어 파생 서비스 코드가 깨진다. prod에서 fixture-로 시작하는 설정값은 기동을 막는다. httpclient failure-injection lane의 main 단계 중복 실행은 이전 결정대로 남겼다. 실제 CI runner 실행은 확인하지 못했다. 검증: ci, mainCheck, :integrationCheck, -p optional-platforms ci integrationCheck performanceCheck, :performanceCheck, :releaseCheck (-PgitRevision), verify-compose-profile-contracts(18 lane) 통과. 첫 실행의 실패 2건(FindSecBugs 1, sample 동시 생성 테스트의 v4 event id)은 고친 뒤 ci·integrationCheck·mainCheck를 다시 돌려 통과했다. Refs: docs/reviews/2026-11-03-rereview/README.md 3·4·6·7절 BREAKING CHANGE: outbox 발행 포트와 저장소 포트 시그니처, 순서 번호 첫 값(V21 floor 다음), 샘플 데모 계정 프로필 허용 목록, 새 오류 코드 IDEMPOTENCY_COMPLETION_UNKNOWN, prod의 fixture- 값 거부, 기동 rule은 static·의존 없음이어야 한다.
212 lines
15 KiB
Markdown
212 lines
15 KiB
Markdown
# Configuration reference
|
|
|
|
The notification delivery platform binds under `app.notification.platform`. The tree lives in
|
|
`src/composition/notification-platform/src/main/resources/config/module-defaults/notification.yml`,
|
|
which the support leaf's `ModuleDefaultsEnvironmentPostProcessor` loads at the lowest precedence,
|
|
so an application without the module carries none of it. The module is in no default composition: a
|
|
service selects it with `runtimeOnly project(':composition:notification-platform')` (plus the
|
|
persistence-jpa line) in `app-bootstrap/build.gradle`, and it is on when present. Every value carries
|
|
an inline default, so a deployment that switches the platform off supplies nothing.
|
|
|
|
Until 2026-08-15 this page named properties the binding did not have — `max-retry-concurrency`,
|
|
`scheduler-poll-interval`, `callback-worker-concurrency` — and omitted three it did. There was no
|
|
tree in `application.yml` at all, so the only way to configure the platform was to guess environment
|
|
variable names from Boot's relaxed binding. `NotificationEnvironmentRegistryTest`
|
|
(`:composition:notification-platform:test`) now fails when the shipped YAML and
|
|
`docs/registries/env-keys.yaml` disagree.
|
|
|
|
## Master switch
|
|
|
|
| Property | Environment variable | Default | Meaning |
|
|
|---|---|---|---|
|
|
| `enabled` | `APP_NOTIFICATION_PLATFORM_ENABLED` | `true` | On while the module is present. `false` binds nothing at all: no runtime, no schema check, no scheduler thread, no secret required |
|
|
| `mode` | `APP_NOTIFICATION_PLATFORM_MODE` | `SERVING` | `SERVING` refuses to start without a working provider; `INGEST_ONLY` stores requests and does not dispatch: it builds no provider runtime but records each enabled profile's route, so a request accepted now is delivered later on that route by a `SERVING` deployment (handoff) |
|
|
|
|
## Dispatch
|
|
|
|
| Property | Environment variable | Default | Bound |
|
|
|---|---|---|---|
|
|
| `dispatch.claim-batch-size` | `APP_NOTIFICATION_PLATFORM_CLAIM_BATCH_SIZE` | `50` | 1..1000 |
|
|
| `dispatch.lease-duration` | `APP_NOTIFICATION_PLATFORM_LEASE_DURATION` | `2m` | positive, finite |
|
|
| `dispatch.poll-interval` | `APP_NOTIFICATION_PLATFORM_POLL_INTERVAL` | `1s` | positive, finite |
|
|
| `dispatch.max-global-concurrency` | `APP_NOTIFICATION_PLATFORM_MAX_CONCURRENCY` | `64` | positive |
|
|
| `dispatch.max-additional-attempts` | `APP_NOTIFICATION_PLATFORM_MAX_ADDITIONAL_ATTEMPTS` | `4` | non-negative |
|
|
| `dispatch.max-queue-age` | `APP_NOTIFICATION_PLATFORM_MAX_QUEUE_AGE` | `24h` | positive |
|
|
| `dispatch.allow-ambiguous-fallback` | `APP_NOTIFICATION_PLATFORM_ALLOW_AMBIGUOUS_FALLBACK` | `false` | boolean |
|
|
|
|
Every value is bounded. "Unlimited" is not an accepted configuration.
|
|
|
|
The lease must outlast a provider call plus its timeout. Below that, a delivery a live worker is
|
|
still waiting on gets claimed by a second worker, and the recipient receives the notification twice.
|
|
|
|
## Callbacks
|
|
|
|
| Property | Environment variable | Default | Bound |
|
|
|---|---|---|---|
|
|
| `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` | positive; SNS messages whose `Timestamp` is further than this from receipt, either way, are rejected. The default is SNS's longest HTTP/S retry period (3,600 s), so a bounce or complaint SNS redelivers after an outage is still accepted; a replay inside the window is a duplicate in the provider event ledger, not a second event (review 05-20) |
|
|
| `callbacks.trusted-proxies` | `APP_NOTIFICATION_PLATFORM_CALLBACK_TRUSTED_PROXIES` | *(empty)* | CSV of peer addresses |
|
|
|
|
콜백 응답: 기록(중복 포함) `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이 전부 서명 실패가 된다.
|
|
`trusted-proxies`가 비어 있으면 forwarded 헤더를 **믿지 않고** 컨테이너가 관측한 값을 쓴다. 무조건 믿으면
|
|
아무 호출자나 자기 서명이 검증될 URL을 고를 수 있어 서명 자체가 무의미해진다. 로드밸런서 뒤에 있는 배포는
|
|
그 peer를 명시한다.
|
|
|
|
65251 is not a round number by accident: it is the ciphertext column's 65536 bytes minus the largest
|
|
envelope the protector writes — a version byte, a key-id length byte, a key id of up to 255 bytes, the
|
|
AES-GCM nonce and tag. A larger configured value is refused when the settings bind, so the capability
|
|
does not start; before that check existed it passed every layer above the database and failed the
|
|
`CHECK` constraint after the callback had already been acknowledged to the provider. The shipped
|
|
default was 65508 (nonce and tag only) for a while after the envelope gained its key id, and every
|
|
deployment that turned the platform on failed to start until it was corrected (review 2026-11-01
|
|
r3-i, found by booting the compose lanes).
|
|
|
|
## Provider profiles
|
|
|
|
Profiles are a map under `providers`, keyed by profile id. Arbitrary deployment-chosen ids can be
|
|
supplied as YAML or through Spring relaxed binding (`APP_NOTIFICATION_PLATFORM_PROVIDERS_<ID>_<FIELD>`).
|
|
The shipped reference profiles `smtp` and `ses` additionally expose explicit `APP_NOTIFICATION_PLATFORM_SMTP_*`
|
|
and `APP_NOTIFICATION_PLATFORM_SES_*` aliases so operators do not have to invent binding names.
|
|
|
|
| Field | Meaning |
|
|
|---|---|
|
|
| `type` | `SES`, `SMTP` — a closed enum, so an unknown value fails binding rather than assembling into nothing |
|
|
| `enabled` | A disabled profile is bound and validated but contributes no runtime |
|
|
| `primary-for-channel` | Exactly one primary per channel |
|
|
| `environment` | Required when enabled |
|
|
| `credential-profile` | Provider credential key id resolved through `SecretMaterialProvider`; never inline secret material |
|
|
| `timeout` | Positive and finite |
|
|
| `max-concurrency` | Positive |
|
|
| `rate-per-second` | Positive |
|
|
|
|
A profile pins provider type, environment, credential profile, timeouts, concurrency and rate limit.
|
|
Sender identity and credential profile are separate concerns.
|
|
|
|
### SES profile fields
|
|
|
|
An enabled SES profile adds a typed `ses` block:
|
|
|
|
| Field | Meaning |
|
|
|---|---|
|
|
| `ses.endpoint` | SES API base URI, used as the AWS SDK client's endpoint override |
|
|
| `ses.region` | AWS region the SDK signs for |
|
|
| `ses.sender-identity` | verified SES From identity |
|
|
| `ses.access-key-id` | AWS access key id; identifier only, not secret material |
|
|
| `ses.configuration-set` | optional SES configuration-set name |
|
|
| `ses.allowed-topic-arns` | SNS topic ARNs whose SES events this profile accepts (`APP_NOTIFICATION_PLATFORM_SES_ALLOWED_TOPIC_ARNS`, comma-separated). Required when `callbacks.enabled=true`: binding fails without it, because a valid SNS signature only proves AWS sent the message and anyone can own a topic |
|
|
| `credential-profile` | key id for the secret access-key material; generation 1 is activated at assembly |
|
|
|
|
The shipped reference profile is `providers.ses` and is disabled by default. It is controlled by
|
|
`APP_NOTIFICATION_PLATFORM_SES_*`; its secret material comes from
|
|
`APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY`, whose active key id must match
|
|
`APP_NOTIFICATION_PLATFORM_SES_CREDENTIAL_KEY_ID`.
|
|
|
|
`type` lists only the families the shipped composition can assemble. Current shipped
|
|
reachability is:
|
|
|
|
| Provider type | Contract/adapter code | Shipped dispatch assembler | Shipped callback assembler | What happens when enabled for dispatch |
|
|
|---|---|---|---|---|
|
|
| `SMTP` | yes | **yes** | no | assembles when Spring Mail relay settings are complete |
|
|
| `SES` | yes | **yes** | **yes** | assembles an EMAIL runtime from the typed `ses` block; SNS callback verification remains available in `INGEST_ONLY` |
|
|
|
|
APNs, FCM, Twilio, Web Push and Webhook adapters used to ship as protocol code with no assembler, so
|
|
enabling one failed startup. They were removed; the `docs/capability-status.md` "제거된 코드" table
|
|
names the last commit that had them. Adding a family back means adding its adapter, a
|
|
`ProviderRuntimeAssembler`, its `ProviderType` constant and the settings/secret inputs it actually
|
|
needs, together.
|
|
|
|
## SMTP relay
|
|
|
|
The one provider profile the template ships, off. A deployment that wants the common case sets
|
|
`APP_NOTIFICATION_PLATFORM_SMTP_ENABLED=true` and the relay address; one that wants a different
|
|
profile id or a second family declares it in its own YAML instead.
|
|
|
|
The profile and the relay are separate tables below because they answer different questions. The
|
|
profile says *which* provider serves EMAIL and under what limits; the relay says *what the transport
|
|
is*. Host, port and credentials are not here at all — they stay `spring.mail.*`, because Spring
|
|
already owns them and a second spelling would be a second thing to keep in step.
|
|
|
|
| Property | Environment variable | Default | Bound |
|
|
|---|---|---|---|
|
|
| `providers.smtp.enabled` | `APP_NOTIFICATION_PLATFORM_SMTP_ENABLED` | `false` | boolean |
|
|
| `providers.smtp.primary-for-channel` | `APP_NOTIFICATION_PLATFORM_SMTP_PRIMARY` | `true` | boolean; exactly one primary per channel |
|
|
| `providers.smtp.environment` | `APP_NOTIFICATION_PLATFORM_SMTP_ENVIRONMENT` | `local` | required when enabled |
|
|
| `providers.smtp.credential-profile` | `APP_NOTIFICATION_PLATFORM_SMTP_CREDENTIAL_PROFILE` | `default` | resolved through `SecretMaterialProvider`, never inline material |
|
|
| `providers.smtp.timeout` | `APP_NOTIFICATION_PLATFORM_SMTP_TIMEOUT` | `10s` | positive, finite |
|
|
| `providers.smtp.max-concurrency` | `APP_NOTIFICATION_PLATFORM_SMTP_MAX_CONCURRENCY` | `4` | positive |
|
|
| `providers.smtp.rate-per-second` | `APP_NOTIFICATION_PLATFORM_SMTP_RATE_PER_SECOND` | `10` | positive |
|
|
|
|
| Property | Environment variable | Default | Bound |
|
|
|---|---|---|---|
|
|
| `smtp.sender-identity` | `APP_NOTIFICATION_PLATFORM_SMTP_SENDER_IDENTITY` | `no-reply@example.invalid` | address |
|
|
| `smtp.dispatch-concurrency` | `APP_NOTIFICATION_PLATFORM_SMTP_DISPATCH_CONCURRENCY` | `4` | positive |
|
|
|
|
SMTP transport configuration has one owner: Spring Mail. The actual `JavaMailSenderImpl` must use required STARTTLS (`mail.smtp.starttls.enable=true` plus `mail.smtp.starttls.required=true`) or implicit TLS (`mail.smtp.ssl.enable=true`). It must also have positive `mail.smtp.connectiontimeout`, `mail.smtp.timeout`, and `mail.smtp.writetimeout` values. SMTP assembly fails before serving traffic when those properties are absent or invalid.
|
|
|
|
The native environment contract is `SPRING_MAIL_HOST`, `SPRING_MAIL_PORT`, optional
|
|
`SPRING_MAIL_USERNAME` / secret `SPRING_MAIL_PASSWORD`, plus the
|
|
`SPRING_MAIL_PROPERTIES_MAIL_SMTP_*` TLS and timeout keys listed in `.env.example`. These names stay
|
|
Spring-native because Spring Boot itself owns and consumes `spring.mail.*`; the notification module
|
|
does not create a second alias for the same relay.
|
|
|
|
The default sender is an RFC 2606 reserved domain that resolves nowhere, so a deployment that forgot
|
|
to set one produces a traceable bounce instead of mail apparently sent from an address it does not
|
|
own.
|
|
|
|
## Startup failures
|
|
|
|
Startup fails rather than degrading when:
|
|
|
|
- a payload or queue setting is unbounded
|
|
- a timeout is negative
|
|
- a TTL-required profile has no expiry source
|
|
- a callback signing secret is missing
|
|
- a production profile enables trust-all
|
|
- an SES profile is missing its `ses` block, or callbacks are on and `ses.allowed-topic-arns` is empty
|
|
- two provider profiles share an id
|
|
- a route points only at disabled providers
|
|
- `mode` is `SERVING` and no provider profile is enabled
|
|
- the notification schema stream is not applied and promoted
|
|
|
|
## Secrets
|
|
|
|
All key material arrives through `SecretMaterialProvider`. Nothing is read from source, from a
|
|
committed file, or from a plaintext log. Contact point encryption and lookup HMAC keys must be
|
|
distinct, and the encryption key must be exactly 256 bits.
|
|
|
|
Seven purposes, seven keys. Each is base64 of at least 32 bytes and each must differ from every
|
|
other; the platform decodes them at startup and refuses to boot if one is blank, short or shared. A
|
|
blank value used to be skipped, which meant the platform started without the key and found out on
|
|
the first contact point — in production, on a recipient's notification.
|
|
|
|
Every default below is **unset**, deliberately. Supply the values out of band, per environment. Do
|
|
not write one into this table, into `application.yml`, into an `.env` file that is tracked, or into
|
|
any example: a value that appears in the repository is a value that has been disclosed.
|
|
|
|
| Purpose | Key material | Active key id |
|
|
|---|---|---|
|
|
| Contact point encryption | `APP_NOTIFICATION_PLATFORM_CONTACT_ENCRYPTION_KEY` | `APP_NOTIFICATION_PLATFORM_CONTACT_ENCRYPTION_KEY_ID` |
|
|
| Contact point lookup HMAC | `APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY` | `APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY_ID` |
|
|
| Callback signing | `APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY` | `APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY_ID` |
|
|
| Callback fingerprint HMAC | `APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY` | `APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY_ID` |
|
|
| Provider credential encryption | `APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY` | `APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY_ID` |
|
|
| Provider request lookup HMAC | `APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY` | `APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY_ID` |
|
|
| Payload encryption | `APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY` | `APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY_ID` |
|
|
|
|
A key id is not secret — an id identifies key material without revealing it — but it is required,
|
|
and it has no default on purpose. A constant id makes a rotation indistinguishable from the key it
|
|
replaced, so nothing could decrypt what was written before it. Change the id in the same deployment
|
|
that changes the material, and keep the superseded key readable under its old id until the data it
|
|
wrote has been re-encrypted. The rotation sequence is in
|
|
[at-rest-threat-model.md](at-rest-threat-model.md).
|
|
|
|
## Readiness
|
|
|
|
The platform contributes a `notifications` actuator endpoint and a health indicator. It reports DOWN
|
|
when a provider's credentials were rejected, when a configured provider has no channel route, and
|
|
when the measured backlog, stuck-lease count, projection lag or reconciliation lag passes the
|
|
thresholds in `NotificationServingThresholds`. See [operations.md](operations.md).
|