- 결정 16: `ca-skeleton.*`·`backend.graphql` 등 → `app.*`(APP_* env 키 이름 유지), selector 키 상수 하나(`CapabilitySelectors`), 바인딩만 되던 `streaming-idle` 삭제 - `StrictSettingsBinder`가 env 오타까지 거부 — 모든 capability(graphql·websocket·mongo는 edge 제약으로 파일만 strict), httpclient 리플렉션 `HttpClientEnvironmentKeys` 삭제 - persistence-jpa가 `APP_DATASOURCE_PASSWORD` secret 요구를 기여(bootstrap이 JPA 스위치를 읽지 않음), Redis ACL fixture에서 pub/sub 권한 제거 - 결함 수정: SMTP 설정 env 이름 충돌(P20-new-1), `bindExcept`가 system env까지 filter(P20-new-2), graphql 빈 deployment-mode 메시지(P20-new-6) - 통합: P30과 충돌 11건(P30의 명시적 bean 구조 유지), P30 코드의 옛 키를 app.*로, persistence-jpa 포맷 - 현황표: 소유자 결정 36(persistence-jpa 설정은 플랫폼 키만 app.persistence-jpa.*로, 공유 기능 트리 예외), 재개 문서에 일시 정지 상태 Wave 3 종료 검증: check · ci verifyDependencyLocks --warning-mode=fail(714 task) · mainCheck · architectureCheck verifyPublicPathSnapshot :app-bootstrap:verifyEnvKeys configContractCheck · :app-bootstrap:integrationTest :sample-portfolio:integrationTest :sample-portfolio:systemTest · integrationCheck · -p build-logic test · -p optional-platforms ci · :app-bootstrap:qualificationBootJar releaseCheck 통과 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
205 lines
13 KiB
Markdown
205 lines
13 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 |
|
|
|
|
## 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` | `65508` | 1..65508 |
|
|
| `callbacks.replay-skew` | `APP_NOTIFICATION_PLATFORM_CALLBACK_REPLAY_SKEW` | `5m` | positive; SNS messages whose `Timestamp` is further than this from receipt, either way, are rejected |
|
|
| `callbacks.trusted-proxies` | `APP_NOTIFICATION_PLATFORM_CALLBACK_TRUSTED_PROXIES` | *(empty)* | CSV of peer addresses |
|
|
|
|
여러 provider가 요청 URL에 서명하므로, 그 URL을 잘못 재구성하면 정상 webhook이 전부 서명 실패가 된다.
|
|
`trusted-proxies`가 비어 있으면 forwarded 헤더를 **믿지 않고** 컨테이너가 관측한 값을 쓴다. 무조건 믿으면
|
|
아무 호출자나 자기 서명이 검증될 URL을 고를 수 있어 서명 자체가 무의미해진다. 로드밸런서 뒤에 있는 배포는
|
|
그 peer를 명시한다.
|
|
|
|
65508 is not a round number by accident: it is the ciphertext column's 65536 bytes minus the AES-GCM
|
|
nonce and tag. A larger configured value would pass every check above the database and fail the
|
|
`CHECK` constraint after the callback had already been acknowledged to the provider.
|
|
|
|
## 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).
|