Merge branch 'claude/d2c-ops-docs-1-c22c9f' — runbook·알림·JPA·관측·호환·storage 문서 번역
충돌: scripts/check-docs-exceptions.txt. 두 쪽 모두 줄을 지우기만 했다(앞 병합까지 92줄, D2c 67줄, 겹침 0). 기준의 줄 중 두 쪽이 모두 남긴 줄만 남겼다(128 → 61줄).
This commit is contained in:
@@ -1,77 +1,53 @@
|
||||
# Notification payload at rest — threat model and decision (NTF-INT-007)
|
||||
# 저장된 알림 payload — 위협 모델과 결정 (NTF-INT-007)
|
||||
|
||||
Wave 2 Task D6 offers two branches and requires that one be chosen and implemented fully:
|
||||
결론: 템플릿 변수(payload)는 저장소 경계에서 암호화한다(branch (a)). 변수를 「민감하지 않은 값」으로 제한하는 길
|
||||
(branch (b))은 쓸 수 없다. 변수가 곧 메시지의 내용이기 때문이다.
|
||||
|
||||
- **(a) encryption** — a codec/port, ciphertext envelope, key id, rotation and history, row migration,
|
||||
and a decryption-failure contract;
|
||||
- **(b) restriction** — this document plus a static restriction proving the variable types cannot
|
||||
carry sensitive values.
|
||||
Wave 2 Task D6은 두 길을 주고, 하나를 골라 끝까지 구현하라고 요구했다.
|
||||
|
||||
The plan recommends (b) **"if and only if the variable types can genuinely be restricted to
|
||||
non-sensitive values"**. They cannot. This document records why, what that leaves, and when the
|
||||
remaining branch lands.
|
||||
- **(a) 암호화** — codec·port, 암호문 envelope, key id, 교체와 이력, 행 마이그레이션, 복호화 실패 계약.
|
||||
- **(b) 제한** — 이 문서, 그리고 변수 타입이 민감한 값을 담을 수 없음을 보이는 정적 제한.
|
||||
|
||||
## What is stored, and where
|
||||
계획은 **「변수 타입을 정말로 민감하지 않은 값으로 제한할 수 있을 때만」** (b)를 권했다. 제한할 수 없다. 이 문서는
|
||||
그 이유와, 그래서 고른 (a)가 지금 어떻게 들어가 있는지를 적는다.
|
||||
|
||||
`CanonicalNotificationPlanWriter.request(...)` puts `encoded.variablesPayload()` into
|
||||
`NotificationRequestRecord` verbatim. `JpaNotificationRequestStore` writes that record to
|
||||
`notification_request.variables_payload` with no transformation. There is no encryption anywhere on
|
||||
this path.
|
||||
## 지금 상태
|
||||
|
||||
## Why the restriction branch is unavailable
|
||||
- `NotificationPayloadProtection`이 애플리케이션이 가진 port이고, `AesGcmNotificationPayloadProtection`이 AES-GCM
|
||||
구현이다.
|
||||
- `NotificationRecordMapper`가 그것을 **필수** 생성자 인자로 받아 적용한다. 그래서 payload를 평문으로 둔 채 알림
|
||||
저장소를 조립할 수 없다.
|
||||
- 쓰기 경로는 조립에서 닿는다. `NotificationJpaPersistenceFacade`는 persistence-notification leaf의
|
||||
`AutoConfiguration.imports`가 올린다.
|
||||
- 평문 행이 이미 있는 배포는 마이그레이션에서 멈춘다. `V10__variables_payload_envelope_guard.sql`은 행을 다시
|
||||
암호화하지 않고, 보호되지 않은 행이 있으면 실패한다.
|
||||
- `NotificationPayloadAtRestContractTest`가 이 문서가 기대는 사실을 모두 단언한다. 하나라도 거짓이 되면 그 테스트가
|
||||
실패하므로, 결정이 저절로 낡지 않는다.
|
||||
- 알림은 Stable이 아니다(`docs/notification/support-matrix.md`).
|
||||
|
||||
Template variables are a closed algebra — `NotificationVariable` permits `TextValue`, `NumberValue`,
|
||||
`BooleanValue`, `NullValue`, `ListValue`, `ObjectValue` — which is a real improvement over the
|
||||
`Map<String, Object>` it replaced. But `TextValue` holds an arbitrary UTF-8 string of up to 8 KiB,
|
||||
and that is not an oversight to be tightened: **the variables are the recipient-specific content of
|
||||
the message**. A password-reset code, an order total, a delivery address, a patient's appointment
|
||||
time — those are what a notification is for.
|
||||
## 무엇이 어디에 저장되나
|
||||
|
||||
A restriction to "non-sensitive values" would therefore be one of two things, and both are worse
|
||||
than the problem:
|
||||
`CanonicalNotificationPlanWriter.request(...)`는 `encoded.variablesPayload()`를 그대로 `NotificationRequestRecord`에
|
||||
넣는다. 애플리케이션은 그것을 렌더링해야 하므로 여기서는 평문이 맞다. 「저장된(at rest)」은 행 안을 뜻하므로
|
||||
envelope는 여기가 아니라 저장소 경계에서 씌운다. `notification_request.variables_payload`에는 base64 AES-GCM
|
||||
envelope가 들어간다.
|
||||
|
||||
- **unenforceable** — a comment saying callers should not put sensitive data in a field designed to
|
||||
carry the message's content, which is a policy no type checks and no reviewer can see violated;
|
||||
- **enforced and useless** — a type that refuses free text, which does not restrict the capability so
|
||||
much as delete it.
|
||||
## 제한 가지를 쓸 수 없는 이유
|
||||
|
||||
The precondition on the plan's recommendation is false. Branch (b) is not available.
|
||||
템플릿 변수는 닫힌 대수다. `NotificationVariable`은 `TextValue`, `NumberValue`, `BooleanValue`, `NullValue`,
|
||||
`ListValue`, `ObjectValue`만 허용한다. 이것이 대신한 `Map<String, Object>`보다 확실히 낫다. 그러나 `TextValue`는 8 KiB까지의
|
||||
아무 UTF-8 문자열을 담고, 그것은 조여야 할 실수가 아니다. **변수는 메시지의 수신자별 내용이다.** 비밀번호 재설정
|
||||
코드, 주문 합계, 배송 주소, 환자의 예약 시각, 알림은 그것을 보내려고 있다.
|
||||
|
||||
> **Status: branch (a) implemented at the storage boundary.** `NotificationPayloadProtection` is the
|
||||
> application-owned port, `AesGcmNotificationPayloadProtection` the AES-GCM implementation, and
|
||||
> `NotificationRecordMapper` applies it — as a **required** constructor argument, so a composition
|
||||
> cannot assemble the notification stores while leaving the payload in plaintext. What remains before
|
||||
> the facade can be imported is the row migration for any deployment that already has plaintext rows,
|
||||
> and the `local-notification-*` lanes. The analysis below is kept as written, because it is what the
|
||||
> decision rests on.
|
||||
그래서 「민감하지 않은 값」으로의 제한은 둘 중 하나가 되고, 둘 다 문제보다 나쁘다.
|
||||
|
||||
## Decision: branch (a), landing with the persistence wiring
|
||||
- **강제할 수 없음** — 메시지 내용을 담으려고 만든 칸에 민감한 데이터를 넣지 말라는 주석. 어떤 타입도 확인하지
|
||||
않고, 어떤 리뷰어도 위반을 볼 수 없는 정책이다.
|
||||
- **강제하지만 쓸모없음** — 자유 텍스트를 거부하는 타입. capability를 제한한다기보다 지운다.
|
||||
|
||||
Encryption is therefore the required branch. Its scope is unchanged from the plan: a codec behind an
|
||||
application port, a ciphertext envelope carrying its key id, key rotation with history so an old row
|
||||
stays readable, a migration for existing rows, and an explicit contract for what a decryption failure
|
||||
does to a request.
|
||||
계획의 권고에 붙은 전제가 거짓이다. (b)는 쓸 수 없다.
|
||||
|
||||
**It lands in the change unit that makes the write path reachable, and not before.** The reason is a
|
||||
fact the spec did not have: `NotificationJpaPersistenceFacade`, which assembles
|
||||
`JpaNotificationRequestStore`, is imported by nothing. The composition root's component scan excludes
|
||||
the persistence package by design, and no configuration imports the facade — so the notification
|
||||
capability has **no JPA persistence at all**, and no deployment currently writes this payload
|
||||
anywhere. The defect is real in the code and latent in the runtime.
|
||||
|
||||
Designing key rotation and a row migration for rows that no deployment produces would be building the
|
||||
migration before the table. Worse, it would settle the envelope's shape before the store that has to
|
||||
read it is wired, which is the order that produces an envelope the store cannot use.
|
||||
|
||||
**One correction, learned by trying it.** This section said the envelope "lands with the wiring".
|
||||
Wiring the facade first — to register the SMTP assembler — made
|
||||
`NotificationPayloadAtRestContractTest` fail on the case asserting the write path is reachable from
|
||||
no composition, which is exactly what that case is for. The wave forbids connecting wiring over a
|
||||
known security finding on a runtime path, so the wiring was reverted and the envelope built first.
|
||||
The honest ordering is **envelope before or with the wiring, never after**, and the contract test now
|
||||
enforces it by failing on the wiring alone.
|
||||
|
||||
### The envelope, and why it has a key id
|
||||
## envelope와 key id를 두는 이유
|
||||
|
||||
```
|
||||
byte version always 1
|
||||
@@ -81,36 +57,50 @@ byte[12] nonce
|
||||
byte[] ciphertext + GCM tag
|
||||
```
|
||||
|
||||
The key id is the reason there is a format at all. This repository's callback protection stores nonce
|
||||
and ciphertext and nothing else, so the day the active key changes, every row written under the
|
||||
previous one becomes unreadable and nothing in the row can say which key it needed — that is not a
|
||||
rotation story with a gap in it, it is the absence of one. `SecretMaterialProvider` already exposes
|
||||
`keyById`, so reading the id back and asking for that specific key makes rotation a change of default
|
||||
rather than a data migration. The version byte costs one byte and is what allows the format to change
|
||||
at all.
|
||||
형식을 두는 이유는 key id다. 이 저장소의 콜백 보호는 한때 nonce와 암호문만 저장했다. 그러면 활성 키가 바뀌는 날
|
||||
앞 키로 쓴 행은 모두 읽을 수 없게 되고, 행 안의 어떤 것도 어느 키가 필요했는지 말하지 못한다. 틈 있는 교체가 아니라
|
||||
교체가 없는 것이다. `SecretMaterialProvider`가 이미 `keyById`를 드러내므로, id를 다시 읽어 바로 그 키를 달라고 하면
|
||||
교체는 데이터 마이그레이션이 아니라 기본값 변경이 된다. version 바이트는 1바이트이고, 형식을 바꿀 수 있게 해 준다.
|
||||
|
||||
The header is passed as **AAD**, not merely prefixed: without that, the key id is attacker-editable
|
||||
and an envelope could be redirected at a key of the attacker's choosing.
|
||||
header는 앞에 붙이기만 하는 것이 아니라 **AAD**로 넘긴다. 그러지 않으면 공격자가 key id를 고쳐 envelope를 자기가
|
||||
고른 키로 돌릴 수 있다.
|
||||
|
||||
A failed decryption throws `NotificationPayloadUnreadableException` rather than returning empty. A
|
||||
caller handed an empty payload renders every variable as nothing and sends "Hello , your code is " to
|
||||
a real person — the failure delivered instead of reported. All three causes (unknown key, wrong key,
|
||||
modified ciphertext) collapse into one message, because telling them apart tells an attacker which of
|
||||
the three they achieved.
|
||||
복호화에 실패하면 빈 값을 돌려주지 않고 `NotificationPayloadUnreadableException`을 던진다. 빈 payload를 받은
|
||||
호출자는 모든 변수를 빈 값으로 렌더링해 실제 사람에게 "Hello , your code is "를 보낸다. 실패를 보고하는 대신 실패를
|
||||
배달하는 것이다. 세 원인(모르는 키, 틀린 키, 고쳐진 암호문)은 한 메시지로 합친다. 셋을 구별해 주면 공격자에게 셋 중
|
||||
무엇을 해냈는지 알려 주기 때문이다.
|
||||
|
||||
## What must not be done instead
|
||||
## 키 교체 순서
|
||||
|
||||
**Requiring `PAYLOAD_ENCRYPTION` in `INGEST_ONLY` is not a fix.** That secret is consumed by exactly
|
||||
one thing — `AesGcmCallbackPayloadProtection`, which protects raw callback bodies — and by nothing on
|
||||
the accept path. Demanding it would make a deployment supply a key that protects nothing while the
|
||||
payload it appears to be about stays in plaintext. The repository already has one defect of that
|
||||
exact shape: `app.graphql.cursor.key-ids` (key removed 2026-09-25), which production refuses to start without and which no
|
||||
code signs a cursor with (GQL-INT-003). Adding a second would make the pattern a habit.
|
||||
설정 키는 `app.notification.platform.secrets` 아래에 있다(`notification.yml`).
|
||||
|
||||
## Consequence
|
||||
1. 새 키 값과 새 key id를 같은 배포에서 바꾼다(예: `APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY`와
|
||||
`APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY_ID`). 고정된 id는 교체를 앞 키와 구별할 수 없게 한다.
|
||||
2. 같은 배포에서 밀려난 키 값을 `historical-keys.<목적>.<옛 id>` 아래에 둔다(예:
|
||||
`historical-keys.PAYLOAD_ENCRYPTION.payload-2026-01`). 목적은 id에서 알아낼 수 없고, id로 키를 푸는 쪽은 목적이 다른
|
||||
키를 거부한다. 그러니 다른 목적 아래 둔 옛 키는 풀리기는 해도 거부된다.
|
||||
3. 옛 키로 쓴 행이 남아 있는 동안 옛 키를 그대로 둔다. `SettingsSecretMaterialProvider.keyById`는 모르는 id를 현재
|
||||
키로 대신하지 않고 거부한다. 대신하면 이력의 모든 행이 읽을 때 인증 tag 실패가 된다.
|
||||
|
||||
Notification is **not promoted to Stable**, per the index's scope boundaries, until branch (a) is
|
||||
complete. The three notification Compose lanes stay non-blocking. `NotificationPayloadAtRestContractTest`
|
||||
holds every fact this decision rests on, so the decision expires automatically if any of them stops
|
||||
being true — in particular, the assertion that no encryption sits on the accept path fails the moment
|
||||
somebody adds one, which is the change this document is waiting for.
|
||||
## 결정의 이력
|
||||
|
||||
> 이력: 결정 당시(Wave 2) `NotificationJpaPersistenceFacade`는 아무도 import하지 않았다. 조립 루트의 component scan은
|
||||
> 설계상 persistence 패키지를 빼고, 어떤 설정도 facade를 import하지 않아서, 알림 capability에는 JPA 영속성이 아예 없었다.
|
||||
> 결함은 코드에는 있고 런타임에는 숨어 있었다. 그래서 처음에는 「envelope는 그 wiring과 함께 들어간다」고 정했다.
|
||||
> 아무 배포도 만들지 않는 행을 위해 키 교체와 행 마이그레이션을 설계하는 것은 테이블보다 마이그레이션을 먼저 짓는
|
||||
> 일이었다.
|
||||
>
|
||||
> 해 보고 배운 정정이 하나 있다. SMTP assembler를 등록하려고 facade를 먼저 wiring하자,
|
||||
> `NotificationPayloadAtRestContractTest`의 「쓰기 경로가 어느 조립에서도 닿지 않는다」 단언이 실패했다. 그 단언은 바로
|
||||
> 그것을 잡으려고 있었다. Wave는 런타임 경로에 알려진 보안 발견을 둔 채 wiring을 잇는 것을 막았으므로 wiring을 되돌리고
|
||||
> envelope를 먼저 지었다. 맞는 순서는 **envelope를 wiring 전이나 함께, 뒤에는 절대 아니다**이다.
|
||||
>
|
||||
> 결정 당시 `PAYLOAD_ENCRYPTION` secret을 쓰는 곳은 원본 콜백 본문을 보호하는 `AesGcmCallbackPayloadProtection` 하나뿐이었고
|
||||
> 받기 경로에는 없었다. 그래서 `INGEST_ONLY`에서 그것을 요구하는 것은 고침이 아니었다. 아무것도 보호하지 않는 키를
|
||||
> 배포에 요구하고, 그것이 다룬다고 보이는 payload는 평문으로 남는다. 저장소에는 이미 그런 꼴의 결함이 하나 있었다.
|
||||
> `app.graphql.cursor.key-ids`(2026-09-25에 키를 지움)는 운영이 그것 없이는 뜨지 않으면서, 어떤 코드도 그것으로 cursor에
|
||||
> 서명하지 않았다(GQL-INT-003). 지금은 `AesGcmNotificationPayloadProtection` 하나가 같은 envelope로 받은 payload와 보관하는
|
||||
> 콜백을 모두 덮고, `NotificationSecretRequirements`가 이 목적을 모든 설정에서 요구한다.
|
||||
>
|
||||
> 결정 당시 결론은 이랬다. 알림은 색인의 범위 경계에 따라 (a)가 끝날 때까지 Stable로 올리지 않는다. 알림 Compose
|
||||
> lane 셋은 막지 않는 lane으로 둔다.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Callbacks and reconciliation
|
||||
# 콜백과 맞추기(reconciliation)
|
||||
|
||||
## Ingestion order
|
||||
## 받는 순서
|
||||
|
||||
```text
|
||||
body size limit
|
||||
@@ -16,41 +16,40 @@ body size limit
|
||||
→ 2xx
|
||||
```
|
||||
|
||||
Appending before projecting is what makes a fast 2xx honest. The provider is told the event is
|
||||
recorded, and a projector defect becomes a replay problem rather than a lost event.
|
||||
projection보다 ledger 추가를 먼저 하기 때문에 빠른 2xx가 정직하다. provider에게는 이벤트가 기록됐다고 알리고,
|
||||
projector 결함은 이벤트 유실이 아니라 replay 문제가 된다.
|
||||
|
||||
A rejected signature is recorded in the security audit, never in the provider event ledger. Writing
|
||||
it to the ledger would let anyone who can reach the endpoint fill a delivery history with noise.
|
||||
서명이 거부된 콜백은 provider event ledger가 아니라 보안 감사에 기록한다. ledger에 쓰면 엔드포인트에 닿는 누구나
|
||||
전달 이력을 잡음으로 채울 수 있다.
|
||||
|
||||
## Duplicates and ordering
|
||||
## 중복과 순서
|
||||
|
||||
Duplicate suppression uses `(providerProfileId, providerEventId)` where the provider supplies an
|
||||
event id, and a deterministic fingerprint over profile, request id, event type, occurrence time and
|
||||
payload digest where it does not. A duplicate is acknowledged and projected exactly once.
|
||||
중복 억제는 provider가 event id를 주면 `(providerProfileId, providerEventId)`를 쓰고, 주지 않으면 profile, request id,
|
||||
event 종류, 발생 시각, payload digest로 만든 결정적 fingerprint를 쓴다. 중복은 확인 응답하고 projection은 정확히 한 번
|
||||
한다.
|
||||
|
||||
Out-of-order callbacks are normal. Ordering is resolved by event semantics, not by arrival time.
|
||||
순서가 뒤바뀐 콜백은 보통이다. 순서는 도착 시각이 아니라 이벤트의 뜻으로 정한다.
|
||||
|
||||
## Unknown fields
|
||||
## 모르는 칸
|
||||
|
||||
Callback parsers tolerate unknown JSON fields. Normalization only rejects a payload when a field
|
||||
required to identify the attempt is missing. Providers add fields; that must not stop ingestion.
|
||||
콜백 parser는 모르는 JSON 칸을 받아들인다. 정규화는 attempt를 가리키는 데 필요한 칸이 없을 때만 payload를 거부한다.
|
||||
provider는 칸을 더한다. 그것 때문에 받기가 멈추면 안 된다.
|
||||
|
||||
## Reconciliation
|
||||
## 맞추기
|
||||
|
||||
Reconciliation targets:
|
||||
맞추기 대상:
|
||||
|
||||
- attempts stuck in `DISPATCHING` past their lease
|
||||
- ambiguous submissions
|
||||
- accepted attempts whose callback SLA has expired
|
||||
- unmatched provider events
|
||||
- lease가 지나도 `DISPATCHING`에 멈춘 attempt
|
||||
- 모호한 제출
|
||||
- 콜백 SLA가 지난, 수락된 attempt
|
||||
- 짝이 없는 provider 이벤트
|
||||
|
||||
A confirmed query result is appended to the same ledger with `source = RECONCILIATION` and projected
|
||||
by the same projector, so projection replay stays possible: there is no privileged second path that
|
||||
writes projections directly.
|
||||
확인된 조회 결과는 `source = RECONCILIATION`으로 같은 ledger에 추가하고 같은 projector가 projection한다. 그래서
|
||||
projection replay가 계속 가능하다. projection을 직접 쓰는 특별한 두 번째 길은 없다.
|
||||
|
||||
Where a provider has no status-query capability, the platform records `Unsupported` and leaves the
|
||||
attempt ambiguous. It does not infer a final status.
|
||||
provider에 상태 조회 기능이 없으면 플랫폼은 `Unsupported`를 기록하고 attempt를 모호한 채로 둔다. 최종 상태를 짐작하지
|
||||
않는다.
|
||||
|
||||
The shipped families, SES and SMTP, have no reconciliation: their assemblers contribute no
|
||||
`ReconciliationCapability`, so every reconciliation job for them ends `Unsupported`. The slot on
|
||||
`AssembledProvider` is for a provider family an adopter assembles with a status query of its own.
|
||||
내보내는 family인 SES와 SMTP는 맞추기가 없다. 그 assembler는 `ReconciliationCapability`를 보태지 않으므로, 둘의 맞추기
|
||||
작업은 모두 `Unsupported`로 끝난다. `AssembledProvider`의 그 자리는 도입하는 쪽이 자기 상태 조회와 함께 조립하는 provider
|
||||
family를 위한 것이다.
|
||||
|
||||
@@ -1,211 +1,202 @@
|
||||
# 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.
|
||||
알림 전달 플랫폼은 `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 줄)를
|
||||
더해 고르고, 모듈이 있으면 켜진다. 값마다 기본값이 붙어 있으므로 플랫폼을 끄는 배포는 아무것도 주지 않아도 된다.
|
||||
|
||||
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.
|
||||
> 이력: 2026-08-15까지 이 문서는 바인딩에 없는 속성(`max-retry-concurrency`, `scheduler-poll-interval`,
|
||||
> `callback-worker-concurrency`)을 적었고, 있는 속성 셋을 빠뜨렸다. `application.yml`에 트리가 아예 없어서, 플랫폼을
|
||||
> 설정하려면 Boot의 relaxed binding으로 환경 변수 이름을 짐작해야 했다.
|
||||
|
||||
## Master switch
|
||||
지금은 내보내는 YAML과 `docs/registries/env-keys.yaml`이 다르면 `NotificationEnvironmentRegistryTest`
|
||||
(`:composition:notification-platform:test`)가 실패한다.
|
||||
|
||||
| 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) |
|
||||
| `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
|
||||
## 발송
|
||||
|
||||
| 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.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 |
|
||||
|
||||
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.
|
||||
lease는 provider 호출과 그 시간 상한보다 길어야 한다. 그보다 짧으면, 살아 있는 worker가 아직 기다리는 전달을 두 번째
|
||||
worker가 claim하고, 수신자는 알림을 두 번 받는다.
|
||||
|
||||
## 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 |
|
||||
| `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다.
|
||||
콜백 응답: 기록(중복 포함) `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를 명시한다.
|
||||
여러 provider가 요청 URL에 서명하므로, 그 URL을 잘못 재구성하면 정상 webhook이 전부 서명 실패가 된다. provider가
|
||||
서명한 URL은 컨테이너가 보고한 값으로 다시 만든다. 콜백 전용 proxy 목록은 없다. 로드밸런서 뒤에 있는 배포는
|
||||
`APP_SERVER_FORWARD_HEADERS_STRATEGY=native`로 두고 그 proxy를 `server.tomcat.remoteip.internal-proxies`에 적는다.
|
||||
forwarded 헤더를 무조건 믿으면 아무 호출자나 자기 서명이 검증될 URL을 고를 수 있어 서명 자체가 무의미해진다.
|
||||
|
||||
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).
|
||||
65251은 우연히 고른 수가 아니다. 암호문 칸의 65536바이트에서 protector가 쓰는 가장 큰 envelope를 뺀 값이다. version
|
||||
바이트, key id 길이 바이트, 255바이트까지의 key id, AES-GCM nonce와 tag다. 이보다 큰 값은 설정을 묶을 때 거부되므로
|
||||
capability가 뜨지 않는다. 그 검사가 생기기 전에는 DB 위의 모든 층을 통과한 뒤, 콜백을 provider에 이미 확인 응답한 다음
|
||||
`CHECK` 제약에서 실패했다.
|
||||
|
||||
## Provider profiles
|
||||
> 이력: envelope에 key id가 붙은 뒤에도 한동안 내보낸 기본값이 65508(nonce와 tag만 뺀 값)이었고, 플랫폼을 켠 배포는 그
|
||||
> 값을 고칠 때까지 모두 뜨지 못했다(review 2026-11-01 r3-i, compose lane을 띄워서 찾음).
|
||||
|
||||
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.
|
||||
## provider profile
|
||||
|
||||
| Field | Meaning |
|
||||
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` — 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 |
|
||||
| `type` | `SES`, `SMTP`. 닫힌 enum이라 모르는 값은 아무것도 조립하지 않고 넘어가는 대신 바인딩에서 실패한다 |
|
||||
| `enabled` | 꺼진 profile도 묶이고 검증되지만 런타임에 아무것도 보태지 않는다 |
|
||||
| `primary-for-channel` | 채널마다 primary는 정확히 하나 |
|
||||
| `environment` | 켜면 필요하다 |
|
||||
| `credential-profile` | `SecretMaterialProvider`로 푸는 provider 자격 증명 key id. secret 값을 직접 적지 않는다 |
|
||||
| `timeout` | 양수, 유한 |
|
||||
| `max-concurrency` | 양수 |
|
||||
| `rate-per-second` | 양수 |
|
||||
|
||||
A profile pins provider type, environment, credential profile, timeouts, concurrency and rate limit.
|
||||
Sender identity and credential profile are separate concerns.
|
||||
profile 하나가 provider 종류, 환경, 자격 증명 profile, 시간 상한, 동시성, 속도 제한을 고정한다. 보내는 쪽 신원과 자격
|
||||
증명 profile은 서로 다른 문제다.
|
||||
|
||||
### SES profile fields
|
||||
### SES profile 칸
|
||||
|
||||
An enabled SES profile adds a typed `ses` block:
|
||||
켜진 SES profile에는 타입이 있는 `ses` 블록이 더해진다.
|
||||
|
||||
| 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 |
|
||||
| `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이 활성화된다 |
|
||||
|
||||
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`.
|
||||
내보내는 참조 profile은 `providers.ses`이고 기본으로 꺼져 있다. `APP_NOTIFICATION_PLATFORM_SES_*`로 다룬다. secret 값은
|
||||
`APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY`에서 오고, 그 활성 key id는
|
||||
`APP_NOTIFICATION_PLATFORM_SES_CREDENTIAL_KEY_ID`와 같아야 한다.
|
||||
|
||||
`type` lists only the families the shipped composition can assemble. Current shipped
|
||||
reachability is:
|
||||
`type`에는 내보내는 조립이 만들 수 있는 family만 있다. 지금 내보내는 것으로 닿는 범위는 다음과 같다.
|
||||
|
||||
| Provider type | Contract/adapter code | Shipped dispatch assembler | Shipped callback assembler | What happens when enabled for dispatch |
|
||||
| provider 종류 | 계약·어댑터 코드 | 내보내는 발송 assembler | 내보내는 콜백 assembler | 발송용으로 켜면 |
|
||||
|---|---|---|---|---|
|
||||
| `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` |
|
||||
| `SMTP` | 있음 | **있음** | 없음 | Spring Mail relay 설정이 다 있으면 조립한다 |
|
||||
| `SES` | 있음 | **있음** | **있음** | 타입 있는 `ses` 블록으로 EMAIL 런타임을 조립한다. SNS 콜백 검증은 `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.
|
||||
APNs, FCM, Twilio, Web Push, Webhook 어댑터는 assembler 없이 프로토콜 코드로만 들어 있어서 켜면 기동이 실패했다. 그래서
|
||||
지웠다. 마지막으로 그것을 가진 커밋은 `docs/capability-status.md` 「제거된 코드」 표가 적는다. family를 다시 더하려면
|
||||
그 어댑터, `ProviderRuntimeAssembler`, `ProviderType` 상수, 실제로 필요한 설정·secret 입력을 함께 더한다.
|
||||
|
||||
## 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.
|
||||
템플릿이 내보내는 provider profile 하나이고, 꺼져 있다. 흔한 경우를 원하는 배포는
|
||||
`APP_NOTIFICATION_PLATFORM_SMTP_ENABLED=true`와 relay 주소를 준다. 다른 profile id나 두 번째 family를 원하는 배포는
|
||||
대신 자기 YAML에 선언한다.
|
||||
|
||||
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.
|
||||
profile과 relay는 다른 질문에 답하므로 아래 두 표로 나눈다. profile은 *어느* provider가 EMAIL을 어떤 한도로 맡는지를
|
||||
말하고, relay는 *전송이 무엇인지*를 말한다. host, port, 자격 증명은 여기에 아예 없다. `spring.mail.*`에 그대로 둔다.
|
||||
Spring이 이미 그것을 가지고 있고, 두 번째 표기는 맞춰 둘 것을 하나 더 만든다.
|
||||
|
||||
| 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 |
|
||||
| `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` | 양수 |
|
||||
|
||||
| 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.sender-identity` | `APP_NOTIFICATION_PLATFORM_SMTP_SENDER_IDENTITY` | `no-reply@example.invalid` | 주소 |
|
||||
| `smtp.dispatch-concurrency` | `APP_NOTIFICATION_PLATFORM_SMTP_DISPATCH_CONCURRENCY` | `4` | 양수 |
|
||||
|
||||
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.
|
||||
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 조립이 트래픽을 받기 전에 실패한다.
|
||||
|
||||
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.
|
||||
환경 변수 계약은 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에 두 번째 별칭을
|
||||
만들지 않는다.
|
||||
|
||||
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.
|
||||
기본 보내는 주소는 어디로도 풀리지 않는 RFC 2606 예약 도메인이다. 그래서 보내는 주소 설정을 잊은 배포는, 자기가
|
||||
가지지 않은 주소로 메일을 보낸 것처럼 보이는 대신 추적할 수 있는 bounce를 낸다.
|
||||
|
||||
## 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
|
||||
- payload나 큐 설정에 상한이 없다
|
||||
- 시간 상한이 음수다
|
||||
- TTL이 필요한 profile에 만료 출처가 없다
|
||||
- 콜백 서명 secret이 없다
|
||||
- 운영 profile이 trust-all을 켠다
|
||||
- SES profile에 `ses` 블록이 없거나, 콜백이 켜졌는데 `ses.allowed-topic-arns`가 비어 있다
|
||||
- 두 provider profile의 id가 같다
|
||||
- route가 꺼진 provider만 가리킨다
|
||||
- `mode`가 `SERVING`인데 켜진 provider profile이 없다
|
||||
- 알림 스키마 stream이 적용·승격되지 않았다
|
||||
|
||||
## Secrets
|
||||
## secret
|
||||
|
||||
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.
|
||||
키 값은 모두 `SecretMaterialProvider`로 들어온다. 소스, 커밋한 파일, 평문 로그에서는 아무것도 읽지 않는다. 연락처
|
||||
암호화 키와 조회 HMAC 키는 서로 달라야 하고, 암호화 키는 정확히 256비트여야 한다.
|
||||
|
||||
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.
|
||||
목적 일곱, 키 일곱이다. 각각 32바이트 이상의 base64이고 다른 모든 키와 달라야 한다. 플랫폼은 기동할 때 키를 풀어
|
||||
보고, 하나라도 비었거나 짧거나 겹치면 뜨기를 거부한다. 전에는 빈 값을 건너뛰었고, 그래서 플랫폼이 키 없이 뜬 뒤 첫
|
||||
연락처에서야, 운영에서는 수신자의 알림에서야 그것을 알았다.
|
||||
|
||||
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.
|
||||
아래 기본값은 모두 일부러 **비어 있다**. 값은 환경마다 따로 준다. 이 표, `application.yml`, 추적되는 `.env` 파일, 어느
|
||||
예시에도 값을 쓰지 않는다. 저장소에 나타난 값은 이미 드러난 값이다.
|
||||
|
||||
| Purpose | Key material | Active key id |
|
||||
| 목적 | 키 값 | 활성 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` |
|
||||
| 연락처 암호화 | `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` |
|
||||
|
||||
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).
|
||||
key id는 secret이 아니다. id는 키 값을 드러내지 않고 그것을 가리킨다. 그래도 필요하고, 일부러 기본값이 없다. 고정된
|
||||
id는 교체를 바뀌기 전 키와 구별할 수 없게 만들어서, 그 전에 쓴 것을 아무것도 풀지 못하게 한다. 키 값을 바꾸는 배포에서
|
||||
id도 함께 바꾸고, 밀려난 키는 그 키로 쓴 데이터를 다시 암호화할 때까지 옛 id로 읽을 수 있게 둔다. 교체 순서는
|
||||
[at-rest-threat-model.md](at-rest-threat-model.md)에 있다.
|
||||
|
||||
## Readiness
|
||||
## 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).
|
||||
플랫폼은 `notifications` actuator 엔드포인트와 health indicator를 보탠다. provider 자격 증명이 거부됐을 때, 설정된
|
||||
provider에 채널 route가 없을 때, 그리고 잰 backlog, 멈춘 lease 수, projection 지연, 맞추기(reconciliation) 지연이
|
||||
`NotificationServingThresholds`의 임계값을 넘을 때 DOWN을 보고한다. [operations.md](operations.md)를 본다.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Delivery evidence model
|
||||
# 전달 증거 모델
|
||||
|
||||
## The shape
|
||||
## 모양
|
||||
|
||||
```text
|
||||
NotificationRequest
|
||||
@@ -12,39 +12,37 @@ NotificationRequest
|
||||
+ EngagementFacts + SuppressionFacts
|
||||
```
|
||||
|
||||
Four identities, four lifecycles. A logical request is not a recipient job, a recipient job is not a
|
||||
provider attempt, and a provider attempt is not the event stream that describes it.
|
||||
신원 넷, 수명 주기 넷이다. 논리 요청은 수신자 작업이 아니고, 수신자 작업은 provider attempt가 아니고, provider attempt는
|
||||
그것을 설명하는 이벤트 흐름이 아니다.
|
||||
|
||||
## Why not one status enum
|
||||
## 상태 enum 하나가 아닌 이유
|
||||
|
||||
A single linear status would have to answer "what happened?" with one value, and the real answers do
|
||||
not fit on one line:
|
||||
일직선 상태 하나는 「무슨 일이 있었나」에 값 하나로 답해야 하는데, 실제 답은 한 줄에 들어가지 않는다.
|
||||
|
||||
- An email can be `DELIVERED` and then generate a complaint. Both facts are true and both matter:
|
||||
one for reporting, the other for suppression.
|
||||
- Twilio does not guarantee callback ordering, so `sent` routinely arrives after `delivered`. Under
|
||||
an ordinal rule the later, weaker event silently overwrites the stronger one.
|
||||
- APNs may accept a notification and then store, replace or discard it.
|
||||
- 이메일은 `DELIVERED`가 된 뒤 complaint를 낼 수 있다. 두 사실이 다 참이고 다 중요하다. 하나는 보고에, 다른 하나는
|
||||
억제에 쓴다.
|
||||
- Twilio는 콜백 순서를 보장하지 않아서 `sent`가 `delivered` 뒤에 오는 일이 흔하다. 순번 규칙에서는 뒤에 온 약한
|
||||
이벤트가 강한 이벤트를 조용히 덮어쓴다.
|
||||
- APNs는 알림을 수락한 뒤 저장하거나, 바꾸거나, 버릴 수 있다.
|
||||
|
||||
So the ledger stores events and a channel projector merges them through an explicit transition table.
|
||||
`StandardDeliveryProjector` holds the shared rules; provider projectors add only their own event
|
||||
vocabulary.
|
||||
그래서 ledger는 이벤트를 저장하고, channel projector가 명시한 전이 표로 그것을 합친다. 공통 규칙은
|
||||
`StandardDeliveryProjector`가 가지고, provider projector는 자기 이벤트 어휘만 더한다.
|
||||
|
||||
## Merge rules
|
||||
## 합치는 규칙
|
||||
|
||||
| Transition | Result |
|
||||
| 전이 | 결과 |
|
||||
|---|---|
|
||||
| `sent` → `delivered` | applied |
|
||||
| `delivered` → `sent` | ignored, event still stored |
|
||||
| `delivered` → `complaint` | complaint fact added, delivery preserved |
|
||||
| `complaint` → `delivered` | delivery applied, complaint preserved |
|
||||
| `accepted` → `bounced` | applied |
|
||||
| `read` → `displayed` | ignored |
|
||||
| hard bounce → `delivered` | ignored, hard bounce is terminal |
|
||||
| `sent` → `delivered` | 적용 |
|
||||
| `delivered` → `sent` | 무시, 이벤트는 저장 |
|
||||
| `delivered` → `complaint` | complaint 사실을 더하고 전달은 유지 |
|
||||
| `complaint` → `delivered` | 전달을 적용하고 complaint는 유지 |
|
||||
| `accepted` → `bounced` | 적용 |
|
||||
| `read` → `displayed` | 무시 |
|
||||
| hard bounce → `delivered` | 무시, hard bounce는 끝 상태 |
|
||||
|
||||
Engagement (`opened`, `clicked`) is stored beside the delivery outcome and never changes it.
|
||||
참여(`opened`, `clicked`)는 전달 결과 옆에 저장하고 그것을 바꾸지 않는다.
|
||||
|
||||
## Ambiguity
|
||||
## 모호함
|
||||
|
||||
```text
|
||||
platform ──── send ────▶ provider
|
||||
@@ -53,10 +51,9 @@ platform ──── send ────▶ provider
|
||||
✗ connection reset
|
||||
```
|
||||
|
||||
The platform may hold no provider request id while the notification really was sent. The attempt
|
||||
records `requestStarted`, `requestBodyCommitted`, `providerResponseReceived` and an
|
||||
`EvidenceCertainty` for each, so a later decision can tell "we know nothing was sent" apart from "we
|
||||
could not read the answer".
|
||||
알림이 실제로 보내졌는데 플랫폼은 provider request id를 하나도 가지지 못할 수 있다. attempt는 `requestStarted`,
|
||||
`requestBodyCommitted`, `providerResponseReceived`와 그 각각의 `EvidenceCertainty`를 기록한다. 그래서 나중의 판단이
|
||||
「아무것도 보내지 않았음을 안다」와 「답을 읽지 못했다」를 가릴 수 있다.
|
||||
|
||||
`ProviderSubmissionResult` enforces this: an ambiguous result may not claim `PROVIDER_ACCEPTED`, and
|
||||
no submission result of any kind may carry a delivery outcome.
|
||||
`ProviderSubmissionResult`가 이것을 강제한다. 모호한 결과는 `PROVIDER_ACCEPTED`를 주장할 수 없고, 어떤 제출 결과도
|
||||
전달 결과를 실을 수 없다.
|
||||
|
||||
@@ -1,45 +1,38 @@
|
||||
# Migration guide
|
||||
# 이행 안내
|
||||
|
||||
## From the R0 routing seam
|
||||
## R0 routing seam에서
|
||||
|
||||
The pre-existing `dev.caskeleton.adapter.outbound.notification` router (`RoutingNotifier`,
|
||||
`FailOpenNotificationProvider`, the Google email and Slack webhook seams) stays untouched. The
|
||||
delivery platform lives beside it under `…notification.platform` and does not modify or delete any
|
||||
R0 class.
|
||||
이미 있던 `dev.caskeleton.adapter.outbound.notification` router(`RoutingNotifier`, `FailOpenNotificationProvider`, Google
|
||||
email과 Slack webhook seam)는 건드리지 않는다. 전달 플랫폼은 그 옆 `…notification.platform` 아래에 있고, R0 클래스를
|
||||
고치거나 지우지 않는다.
|
||||
|
||||
Migration order per capability:
|
||||
capability마다 이행 순서:
|
||||
|
||||
1. Register the contact points behind `ContactPointStorePort` so the platform owns protected values.
|
||||
2. Publish the template version, and pin the template id, version and locale at every call site.
|
||||
3. Move the call site from the router to the N1 typed facade for the channel.
|
||||
4. Verify evidence in the snapshot rather than in the caller's return value: `submit()` is durable
|
||||
acceptance and nothing more.
|
||||
5. Remove the R0 route only after the platform route has produced provider evidence in the target
|
||||
environment.
|
||||
1. 플랫폼이 보호된 값을 가지도록 연락처를 `ContactPointStorePort` 뒤에 등록한다.
|
||||
2. 템플릿 버전을 게시하고, 모든 호출 지점에서 템플릿 id, 버전, locale을 고정한다.
|
||||
3. 호출 지점을 router에서 그 채널의 N1 typed facade로 옮긴다.
|
||||
4. 증거는 호출자의 반환값이 아니라 snapshot에서 확인한다. `submit()`은 durable 수락일 뿐이다.
|
||||
5. 대상 환경에서 플랫폼 route가 provider 증거를 낸 뒤에만 R0 route를 지운다.
|
||||
|
||||
## Return-value semantics change
|
||||
## 반환값의 뜻이 바뀐다
|
||||
|
||||
The R0 seam returned a send-shaped result. `NotificationReceipt` returns `notificationId`, a request
|
||||
status and an acceptance time. Callers that treated the old return value as proof of delivery must be
|
||||
changed; there is no compatibility shim, because a shim would have to invent the delivery claim this
|
||||
platform exists to avoid.
|
||||
R0 seam은 보낸 결과 모양을 돌려줬다. `NotificationReceipt`는 `notificationId`, 요청 상태, 수락 시각을 돌려준다. 옛
|
||||
반환값을 전달 증거로 다룬 호출자는 고쳐야 한다. 호환 shim은 없다. shim은 이 플랫폼이 피하려고 있는 전달 주장을 지어내야
|
||||
하기 때문이다.
|
||||
|
||||
## FCM target migration
|
||||
## FCM 대상 이행
|
||||
|
||||
Registration tokens keep working through `LegacyFcmRegistrationToken`. New registrations should use
|
||||
`FcmInstallationId`. The two are distinct types, so a migration is a compile-time task rather than a
|
||||
runtime guess.
|
||||
registration token은 `LegacyFcmRegistrationToken`으로 계속 쓸 수 있다. 새 등록은 `FcmInstallationId`를 쓴다. 둘은 서로
|
||||
다른 타입이라 이행은 런타임 짐작이 아니라 컴파일 시점의 일이다.
|
||||
|
||||
## R1의 처분 (NOTIF-ADR-005)
|
||||
|
||||
이 문서는 R0 router → platform 이행만 설명해 왔고, `dev.caskeleton.application.notification` 직속의
|
||||
R1 public type 100개를 어떻게 할 것인지 다루지 않았다. 그래서 새 consumer가 어느 API를 써야 하는지
|
||||
문서 어디에도 답이 없었다.
|
||||
이 문서는 R0 router → platform 이행만 설명해 왔고, `dev.caskeleton.application.notification` 직속의 R1 public type
|
||||
100개를 어떻게 할 것인지 다루지 않았다. 그래서 새 consumer가 어느 API를 써야 하는지 문서 어디에도 답이 없었다.
|
||||
|
||||
- **canonical은 `..notification.platform..`이다.** NOTIF-ADR-005가 근거와 함께 정한다.
|
||||
- **application R1 public type은 2026-09-25에 삭제했다.** production consumer가 0건이었다. 남은 것은
|
||||
단순 알림 포트 `NotificationPort`·`Notification`·`NotificationChannel`뿐이다.
|
||||
- R1을 따라 만들어졌지만 composition root에서 한 번도 조립되지 않았던 outbound adapter의
|
||||
`catalog/`, `provider/`, `template/` 실험 구현도 제거했다. 실제 runtime은
|
||||
`dev.caskeleton.adapter.outbound.notification.platform..`만 사용한다.
|
||||
- **application R1 public type은 2026-09-25에 삭제했다.** production consumer가 0건이었다. 남은 것은 단순 알림 포트
|
||||
`NotificationPort`·`Notification`·`NotificationChannel`뿐이다.
|
||||
- R1을 따라 만들어졌지만 composition root에서 한 번도 조립되지 않았던 outbound adapter의 `catalog/`, `provider/`,
|
||||
`template/` 실험 구현도 제거했다. 실제 runtime은 `dev.caskeleton.adapter.outbound.notification.platform..`만 사용한다.
|
||||
- 삭제 목록과 마지막 커밋은 `docs/capability-status.md`의 「제거된 코드」 표에 있다.
|
||||
|
||||
@@ -1,39 +1,37 @@
|
||||
# Notification Delivery Platform — module mapping
|
||||
# 알림 전달 플랫폼 — 모듈 대응표
|
||||
|
||||
> Source design: `docs/design/2026-08-10-notification-platform-design.md`
|
||||
> 출처 설계서: `docs/design/2026-08-10-notification-platform-design.md`
|
||||
>
|
||||
> Source plan: `docs/history/plans/2026-08-10-notification-platform-implementation-plan.md`
|
||||
> 출처 계획서: `docs/history/plans/2026-08-10-notification-platform-implementation-plan.md`
|
||||
|
||||
## Why a mapping exists
|
||||
## 대응표가 있는 이유
|
||||
|
||||
The plan was written against a hypothetical repository (`modules/notification/**`, root package
|
||||
`io.backend.skeleton.notification`, 31 Gradle projects). This repository is a fail-closed
|
||||
19-leaf Clean Architecture template: `src/settings.gradle` rejects any registry that does not
|
||||
contain exactly the 19 modules in `src/config/architecture/modules.json`, and
|
||||
`verifyCleanArchitectureDependencies` rejects any project edge outside `allowed_dependencies`.
|
||||
계획은 가상의 저장소(`modules/notification/**`, root 패키지 `io.backend.skeleton.notification`, Gradle 프로젝트 31개)를
|
||||
두고 쓰였다. 이 저장소는 fail-closed Clean Architecture 템플릿이다. `src/settings.gradle`은 registry
|
||||
(`src/config/architecture/modules.json`)를 읽고 검증한 뒤 등록된 프로젝트만 들이고, `verifyCleanArchitectureDependencies`는
|
||||
`allowed_dependencies` 밖의 프로젝트 edge를 거부한다.
|
||||
|
||||
Creating 31 new Gradle projects would violate HARD-STOP #5 of `AGENTS.md`. The package README
|
||||
anticipates this and instructs the implementer to map dependency catalog and package/file paths onto
|
||||
the host repository's rules while preserving the public contracts and reliability semantics.
|
||||
Gradle 프로젝트 31개를 새로 만들면 `AGENTS.md`의 HARD-STOP #5를 어긴다. 패키지 README도 이것을 내다보고, 공개 계약과
|
||||
신뢰성 의미를 지키면서 의존성 카탈로그와 패키지·파일 경로를 받는 저장소의 규칙에 맞추라고 구현자에게 지시한다.
|
||||
|
||||
Every logical module of the plan is therefore implemented as a **package** inside the registered leaf
|
||||
that owns its responsibility. No public contract, evidence rule, or reliability semantic is dropped.
|
||||
그래서 계획의 논리 모듈마다 그 책임을 가진 등록 leaf 안의 **패키지**로 구현했다. 공개 계약, 증거 규칙, 신뢰성 의미는
|
||||
하나도 빠지지 않았다.
|
||||
|
||||
## Logical module → registered leaf
|
||||
## 논리 모듈 → 등록 leaf
|
||||
|
||||
| Plan module | Registered leaf | Package |
|
||||
| 계획 모듈 | 등록 leaf | 패키지 |
|
||||
|---|---|---|
|
||||
| `notification-core-api` | `application-core` | `dev.caskeleton.application.notification.platform.api` |
|
||||
| `notification-content-api` | `application-core` | `…platform.api.content` |
|
||||
| `notification-contact-api` | `application-core` | `…platform.contact` |
|
||||
| `notification-template-api` | `application-core` | `…platform.template` |
|
||||
| `notification-policy` | `application-core` | `…platform.policy` |
|
||||
| `notification-provider-spi` | `application-core` | `…platform.provider` |
|
||||
| `notification-callback-api` | `application-core` | `…platform.callback` |
|
||||
| `notification-inbox-api` | `application-core` | `…platform.inbox` |
|
||||
| `notification-admin-api` | `application-core` | `…platform.admin` |
|
||||
| `notification-security` (ports) | `application-core` | `…platform.security` |
|
||||
| `notification-observability` (ports) | `application-core` | `…platform.observation` |
|
||||
| `notification-core-api` | `application-notification` | `dev.caskeleton.application.notification.platform.api` |
|
||||
| `notification-content-api` | `application-notification` | `…platform.api.content` |
|
||||
| `notification-contact-api` | `application-notification` | `…platform.contact` |
|
||||
| `notification-template-api` | `application-notification` | `…platform.template` |
|
||||
| `notification-policy` | `application-notification` | `…platform.policy` |
|
||||
| `notification-provider-spi` | `application-notification` | `…platform.provider` |
|
||||
| `notification-callback-api` | `application-notification` | `…platform.callback` |
|
||||
| `notification-inbox-api` | `application-notification` | `…platform.inbox` |
|
||||
| `notification-admin-api` | `application-notification` | `…platform.admin` |
|
||||
| `notification-security` (ports) | `application-notification` | `…platform.security` |
|
||||
| `notification-observability` (ports) | `application-notification` | `…platform.observation` |
|
||||
| `notification-dispatch-runtime` | `adapter:outbound:notification` | `dev.caskeleton.adapter.outbound.notification.platform.dispatch` |
|
||||
| `notification-security` (AES-GCM/HMAC impl) | `adapter:outbound:notification` | `…platform.security` |
|
||||
| `notification-template-thymeleaf` (reference renderer) | `adapter:outbound:notification` | `…platform.template` |
|
||||
@@ -42,20 +40,20 @@ that owns its responsibility. No public contract, evidence rule, or reliability
|
||||
| `notification-observability` (Micrometer impl) | `adapter:outbound:notification` | `…platform.observation` |
|
||||
| `notification-admin-runtime` | `adapter:outbound:notification` | `…platform.admin` |
|
||||
| `notification-spring-boot-starter` | `adapter:outbound:notification` | `…platform.autoconfigure` |
|
||||
| `notification-persistence-jpa` | `adapter:outbound:persistence-notification` | `dev.caskeleton.adapter.outbound.persistence.notification.platform` (store adapters), `….platform.entity` (JPA rows), `….platform.repository` (Spring Data interfaces and SQL text) |
|
||||
| `notification-inbox-jpa` | `adapter:outbound:persistence-notification` | `…persistence.notification.platform` (`JpaNotificationInbox`, `InboxCommitEventPublisher`, `InboxOutboxRecordFactory`); row and repository in `….platform.entity` / `….platform.repository` |
|
||||
| `notification-persistence-jpa` | `adapter:outbound:persistence-notification` | `dev.caskeleton.adapter.outbound.persistence.notification.platform`(저장소 어댑터), `….platform.entity`(JPA 행), `….platform.repository`(Spring Data interface와 SQL 문) |
|
||||
| `notification-inbox-jpa` | `adapter:outbound:persistence-notification` | `…persistence.notification.platform`(`JpaNotificationInbox`, `InboxCommitEventPublisher`, `InboxOutboxRecordFactory`). 행과 repository는 `….platform.entity` / `….platform.repository` |
|
||||
| `notification-callback-mvc` | `adapter:inbound:web-notification` | `dev.caskeleton.adapter.inbound.web.notification.platform.callback` |
|
||||
| `notification-submission-mvc` | `adapter:inbound:web-notification` | `dev.caskeleton.adapter.inbound.web.notification.platform.submission` |
|
||||
| application composition (use cases, callback bridge, `config/module-defaults/notification.yml`) | `composition:notification-platform` | `dev.caskeleton.composition.notification` |
|
||||
| `notification-testkit` | test source sets of the owning leaves | `…platform.testkit` |
|
||||
| 애플리케이션 조립(use case, 콜백 bridge, `config/module-defaults/notification.yml`) | `composition:notification-platform` | `dev.caskeleton.composition.notification` |
|
||||
| `notification-testkit` | 소유 leaf의 test source set | `…platform.testkit` |
|
||||
|
||||
## Dependency-direction consequences
|
||||
## 의존 방향의 결과
|
||||
|
||||
The plan's module DAG (`*-api` → `provider-spi`/`policy` → runtime/adapters → starter) is preserved
|
||||
by the leaf DAG that the registry already enforces:
|
||||
계획의 모듈 DAG(`*-api` → `provider-spi`/`policy` → runtime/adapters → starter)는 registry가 이미 강제하는 leaf DAG로
|
||||
지켜진다.
|
||||
|
||||
```text
|
||||
application-core (all *-api, provider SPI, policy, callback contracts)
|
||||
application-notification (all *-api, provider SPI, policy, callback contracts; → application-core)
|
||||
↑ ↑ ↑
|
||||
adapter:outbound:notification adapter:outbound:persistence-notification adapter:inbound:web-notification
|
||||
↑ ↑ (runtimeOnly, with persistence-jpa) ↑ (→ adapter:inbound:web)
|
||||
@@ -64,50 +62,40 @@ adapter:outbound:notification adapter:outbound:persistence-notification ad
|
||||
app-bootstrap (one line)
|
||||
```
|
||||
|
||||
Two plan edges cannot be expressed as project edges in this repository, and are replaced by ports:
|
||||
계획의 edge 둘은 이 저장소에서 프로젝트 edge로 표현할 수 없어서 port로 바꿨다.
|
||||
|
||||
1. `notification-email-ses` → `httpclient platform`. (The Twilio, FCM, APNs, Web Push and
|
||||
Webhook adapters that shared this edge were removed: none had an assembler.)
|
||||
`adapter-outbound-notification` is not allowed to depend on `adapter-outbound-httpclient`, and
|
||||
SES no longer needs it: the SES adapter sends through the AWS SDK v2 `sesv2` client (owner
|
||||
decision 17), which signs requests itself. The adapter-local JDK HTTP gateway and SigV4 signer
|
||||
were deleted with that change. The client is built per profile with SDK retries off, no default
|
||||
credential chain (each request carries its profile's credential) and the profile's endpoint,
|
||||
which still passes the notification routability guard.
|
||||
2. `notification-inbox-jpa` → `optional messaging outbox integration`.
|
||||
`adapter-outbound-persistence-notification` may not depend on `adapter-outbound-messaging`; the inbox
|
||||
publishes through the existing persistence outbox tables plus the
|
||||
`NotificationInboxSignalPort` application port, and `app-bootstrap` binds the relay.
|
||||
1. `notification-email-ses` → `httpclient platform`. (이 edge를 함께 쓰던 Twilio, FCM, APNs, Web Push, Webhook 어댑터는
|
||||
assembler가 없어서 지웠다.) `adapter-outbound-notification`은 `adapter-outbound-httpclient`에 의존할 수 없고, SES는
|
||||
이제 그것이 필요 없다. SES 어댑터는 스스로 요청에 서명하는 AWS SDK v2 `sesv2` 클라이언트로 보낸다(소유자 결정 17).
|
||||
어댑터 안의 JDK HTTP gateway와 SigV4 signer는 그 변경과 함께 지웠다. 클라이언트는 profile마다 SDK 재시도를 끄고,
|
||||
기본 credential chain 없이(요청마다 자기 profile의 자격 증명을 싣는다), profile의 endpoint로 만든다. 그 endpoint는
|
||||
여전히 알림 routability guard를 통과한다.
|
||||
2. `notification-inbox-jpa` → `optional messaging outbox integration`. `adapter-outbound-persistence-notification`은
|
||||
`adapter-outbound-messaging`에 의존할 수 없다. inbox는 이미 있는 persistence outbox 테이블과 애플리케이션 port
|
||||
`NotificationInboxSignalPort`로 내보내고, outbox relay는 `composition:outbox-relay`가 조립한다.
|
||||
|
||||
## Commit policy
|
||||
## 커밋 정책
|
||||
|
||||
`AGENTS.md` pins commit policy to `human-only`. Step 5 (`git add` / `git commit`) of every plan task
|
||||
is therefore intentionally **not** executed by the agent; the working tree carries the change and the
|
||||
human owner commits.
|
||||
`AGENTS.md`는 커밋 정책을 `human-only`로 고정한다. 그래서 계획의 모든 task에 있는 Step 5(`git add` / `git commit`)는
|
||||
에이전트가 일부러 **하지 않았다**. 작업 트리가 변경을 싣고, 사람 소유자가 커밋한다.
|
||||
|
||||
## Runtime reachability after the R1 adapter cleanup
|
||||
## R1 어댑터 정리 뒤 런타임 도달 범위
|
||||
|
||||
The application R1 contract covered by NOTIF-ADR-005 is a separate question from the abandoned
|
||||
outbound implementation that had been built around it. The latter is gone: the notification leaf no
|
||||
longer contains top-level `catalog/`, `provider/`, or `template/` R1 adapter packages. They had no
|
||||
production composition consumer and were proved only by their own fakes.
|
||||
NOTIF-ADR-005가 다루는 애플리케이션 R1 계약은, 그것을 둘러싸고 만들었다가 버린 outbound 구현과는 다른 문제다. 뒤의 것은
|
||||
없어졌다. 알림 leaf에는 최상위 `catalog/`, `provider/`, `template/` R1 어댑터 패키지가 더는 없다. 그것들은 운영 조립의
|
||||
consumer가 없었고 자기 fake로만 증명됐다.
|
||||
|
||||
The useful rendering invariant from that experiment was not discarded. R2
|
||||
`platform.template.TemplateSlotPolicy` now validates the final HTML against the reviewed tag and
|
||||
attribute subset in addition to escaping substituted values. Active script markup, event-handler
|
||||
attributes and non-HTTPS HTML links are refused.
|
||||
그 실험의 쓸모 있던 렌더링 불변식은 버리지 않았다. R2 `platform.template.TemplateSlotPolicy`가 이제 치환한 값을
|
||||
escape하는 것에 더해, 최종 HTML을 검토한 태그·속성 부분집합과 대조한다. 실행되는 script markup, event handler 속성,
|
||||
HTTPS가 아닌 HTML 링크는 거부한다.
|
||||
|
||||
R2 provider protocol packages remain because they implement the canonical platform SPI and have
|
||||
contract tests. Their presence does **not** make them shipped dispatch runtimes. Current composition
|
||||
reachability is SMTP and SES for dispatch, with SES also available for callback ingestion; the remaining
|
||||
provider packages are extension assets until a composition contributes a `ProviderRuntimeAssembler`
|
||||
with the settings and secret sources that family requires. See `support-matrix.md` for the explicit table.
|
||||
R2 provider 프로토콜 패키지는 canonical 플랫폼 SPI를 구현하고 계약 테스트가 있어서 남아 있다. 남은 것은 `ses`와
|
||||
`smtp`이고, 둘 다 내보내는 조립이 발송에 쓴다(SES는 콜백 받기에도 쓴다). 다른 family는 조립이 그 family에 필요한 설정·secret
|
||||
출처와 함께 `ProviderRuntimeAssembler`를 보탤 때 생긴다. 표는 `support-matrix.md`에 있다.
|
||||
|
||||
## R1 public types (NOTIF-ADR-005)
|
||||
## R1 public type (NOTIF-ADR-005)
|
||||
|
||||
NOTIF-ADR-005 made `..notification.platform..` canonical. The R1 types directly under
|
||||
`dev.caskeleton.application.notification` had no production consumer and were removed on
|
||||
2026-09-25, together with the ArchUnit rule that kept the two namespaces apart. What remains there
|
||||
is the simple notification port the adapter core implements — `NotificationPort`, `Notification`,
|
||||
`NotificationChannel`. The removed types and their last commit are listed in
|
||||
`docs/capability-status.md` under "제거된 코드".
|
||||
NOTIF-ADR-005가 `..notification.platform..`을 canonical로 정했다. `dev.caskeleton.application.notification` 바로 아래의
|
||||
R1 타입은 운영 consumer가 없어서, 두 namespace를 떼어 놓던 ArchUnit 규칙과 함께 2026-09-25에 지웠다. 거기 남은 것은
|
||||
어댑터 core가 구현하는 단순 알림 port `NotificationPort`, `Notification`, `NotificationChannel`이다. 지운 타입과 마지막
|
||||
커밋은 `docs/capability-status.md` 「제거된 코드」에 있다.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Operations
|
||||
# 운영
|
||||
|
||||
## Runtime shape
|
||||
## 런타임 모양
|
||||
|
||||
```text
|
||||
durable queue (PostgreSQL, FOR UPDATE SKIP LOCKED)
|
||||
@@ -12,35 +12,31 @@ durable queue (PostgreSQL, FOR UPDATE SKIP LOCKED)
|
||||
→ provider adapter
|
||||
```
|
||||
|
||||
Provider calls run outside every database transaction. The attempt row is committed first, so after a
|
||||
crash the row is either absent (nothing was sent) or present in `DISPATCHING` (reconciliation has
|
||||
something to ask about).
|
||||
provider 호출은 모든 DB 트랜잭션 밖에서 돈다. attempt 행을 먼저 커밋하므로, 장애 뒤 그 행은 없거나(아무것도 보내지
|
||||
않음) `DISPATCHING`으로 있다(맞추기가 물어볼 것이 있음).
|
||||
|
||||
## Guards that exist for specific incidents
|
||||
## 특정 장애를 막으려고 있는 장치
|
||||
|
||||
| Guard | The incident it prevents |
|
||||
| 장치 | 막는 장애 |
|
||||
|---|---|
|
||||
| Credential failure opens the provider route | One expired key multiplied by a queue becomes a self-inflicted outage |
|
||||
| Retry budget per provider profile | A provider outage turning every queued notification into its own retry loop |
|
||||
| Ambiguous attempts block automatic fallback | A push whose response was lost arriving alongside the "just in case" SMS |
|
||||
| Permits released during backoff | A slow provider pinning the whole concurrency budget on work that is only waiting |
|
||||
| Fail-fast intake on capacity | An unbounded in-memory queue absorbing a burst it cannot survive |
|
||||
| 자격 증명 실패가 provider route를 연다 | 만료된 키 하나가 큐만큼 곱해져 스스로 만든 장애가 된다 |
|
||||
| provider profile마다 재시도 예산 | provider 장애가 큐의 모든 알림을 저마다의 재시도 반복으로 만든다 |
|
||||
| 모호한 attempt는 자동 전환을 막는다 | 응답을 잃은 push와 「혹시 몰라」 보낸 SMS가 함께 도착한다 |
|
||||
| 백오프 동안 허가를 돌려준다 | 느린 provider가 기다리기만 하는 일로 동시성 예산 전체를 붙잡는다 |
|
||||
| 용량이 차면 받기를 바로 거부한다 | 상한 없는 메모리 큐가 버틸 수 없는 폭주를 받아들인다 |
|
||||
|
||||
## Scheduling
|
||||
## 일정
|
||||
|
||||
`scheduleAt` activates the job, `notBefore` is the earliest permitted provider submission, and
|
||||
`expiresAt` blocks new attempts, retries and fallbacks. Suppression and expiry are re-checked
|
||||
immediately before dispatch, because a scheduled notification can sit in the queue for hours and the
|
||||
user may have opted out in the meantime.
|
||||
`scheduleAt`은 작업을 활성화하고, `notBefore`는 provider 제출을 허용하는 가장 이른 시각이고, `expiresAt`은 새 attempt,
|
||||
재시도, 전환을 막는다. 억제와 만료는 발송 직전에 다시 확인한다. 예약된 알림은 큐에서 몇 시간을 기다릴 수 있고, 그동안
|
||||
사용자가 수신을 거부했을 수 있다.
|
||||
|
||||
## Redrive
|
||||
## 다시 보내기(redrive)
|
||||
|
||||
A redrive preserves `NotificationId` and `RecipientDeliveryId`, creates a new `DeliveryAttemptId`, and
|
||||
reuses the pinned template version and rendered digest. Sending different content is a new
|
||||
notification, not a redrive. Redriving an ambiguous attempt requires explicit duplicate-risk approval,
|
||||
because the platform genuinely cannot tell whether the first submission reached the user.
|
||||
redrive는 `NotificationId`와 `RecipientDeliveryId`를 유지하고, 새 `DeliveryAttemptId`를 만들고, 고정된 템플릿 버전과
|
||||
렌더링 digest를 다시 쓴다. 다른 내용을 보내는 것은 redrive가 아니라 새 알림이다. 모호한 attempt를 redrive하려면 중복
|
||||
위험 승인을 명시해야 한다. 첫 제출이 사용자에게 닿았는지 플랫폼이 정말로 알 수 없기 때문이다.
|
||||
|
||||
## Actuator surface
|
||||
## actuator 표면
|
||||
|
||||
Provider runtime states and generations, queue depth and age, callback and reconciliation health.
|
||||
Never addresses, never credentials.
|
||||
provider 런타임 상태와 세대, 큐 깊이와 나이, 콜백과 맞추기 상태. 주소와 자격 증명은 절대 싣지 않는다.
|
||||
|
||||
@@ -1,34 +1,34 @@
|
||||
# Provider runbooks
|
||||
# provider runbook
|
||||
|
||||
## SMTP
|
||||
|
||||
| Symptom | Classification | Action |
|
||||
| 증상 | 분류 | 조치 |
|
||||
|---|---|---|
|
||||
| Final `2xx` after `DATA` | `CONFIRMED_ACCEPTED` / `PROVIDER_ACCEPTED` | None; this is acceptance, not inbox delivery |
|
||||
| `4yz` | `TRANSIENT_PROVIDER` | Retry under budget and deadline |
|
||||
| `5yz` | `PERMANENT_PROVIDER` or `INVALID_RECIPIENT` | Stop, or invalidate the contact point |
|
||||
| Connection lost after `DATA` | `AMBIGUOUS_SUBMISSION` | Reconcile or escalate; do not resend automatically |
|
||||
| `DATA` 뒤 최종 `2xx` | `CONFIRMED_ACCEPTED` / `PROVIDER_ACCEPTED` | 없음. 받은편지함 도착이 아니라 수락이다 |
|
||||
| `4yz` | `TRANSIENT_PROVIDER` | 예산과 마감 안에서 다시 시도한다 |
|
||||
| `5yz` | `PERMANENT_PROVIDER` 또는 `INVALID_RECIPIENT` | 멈추거나, 연락처를 무효로 한다 |
|
||||
| `DATA` 뒤 연결 끊김 | `AMBIGUOUS_SUBMISSION` | 맞추거나 넘긴다. 자동으로 다시 보내지 않는다 |
|
||||
|
||||
Connection, read, write and pool-acquire timeouts are all finite. There is no unbounded timeout.
|
||||
연결, 읽기, 쓰기, 풀 획득 시간 상한은 모두 유한하다. 상한 없는 시간 상한은 없다.
|
||||
|
||||
## Amazon SES
|
||||
|
||||
`MessageId` is acceptance evidence. SES itself documents that it can accept a request and then not
|
||||
send, so `MessageId` is never mapped to `DELIVERED`.
|
||||
`MessageId`는 수락 증거다. SES 자신이 요청을 수락한 뒤 보내지 않을 수 있다고 문서에 적으므로, `MessageId`는 절대
|
||||
`DELIVERED`로 매핑하지 않는다.
|
||||
|
||||
| Event | Normalized |
|
||||
| 이벤트 | 정규화 |
|
||||
|---|---|
|
||||
| `Send` | reinforces `PROVIDER_ACCEPTED` |
|
||||
| `Send` | `PROVIDER_ACCEPTED`를 보강한다 |
|
||||
| `Delivery` | `DELIVERY_CONFIRMED` / `NETWORK_OR_CARRIER_ACCEPTED` |
|
||||
| `DeliveryDelay` | delay fact |
|
||||
| `Bounce` (permanent) | `BOUNCED_HARD` plus hard-bounce suppression |
|
||||
| `Bounce` (transient) | `BOUNCED_SOFT`; retry policy input, not a suppression reason |
|
||||
| `Complaint` | complaint fact plus suppression |
|
||||
| `DeliveryDelay` | 지연 사실 |
|
||||
| `Bounce` (permanent) | `BOUNCED_HARD`와 hard bounce 억제 |
|
||||
| `Bounce` (transient) | `BOUNCED_SOFT`. 억제 사유가 아니라 재시도 정책의 입력이다 |
|
||||
| `Complaint` | complaint 사실과 억제 |
|
||||
| `Reject` | `PROVIDER_REJECTED` |
|
||||
| `RenderingFailure` | `TEMPLATE_FAILURE` |
|
||||
|
||||
## Removed provider families
|
||||
## 지운 provider family
|
||||
|
||||
Twilio, FCM, APNs, Web Push and Webhook adapters were removed because nothing assembled them; their
|
||||
runbooks went with them. The last commit that had both is named in `docs/capability-status.md`
|
||||
(제거된 코드). A deployment that adds one of these providers back writes its runbook here with it.
|
||||
Twilio, FCM, APNs, Web Push, Webhook 어댑터는 아무것도 조립하지 않아서 지웠고, 그 runbook도 함께 지웠다. 둘을 모두
|
||||
가진 마지막 커밋은 `docs/capability-status.md`(제거된 코드)에 있다. 이 provider 중 하나를 다시 더하는 배포는 그 runbook을
|
||||
여기에 함께 쓴다.
|
||||
|
||||
@@ -1,54 +1,44 @@
|
||||
# Security and privacy
|
||||
# 보안과 개인정보
|
||||
|
||||
## Protected values
|
||||
## 보호하는 값
|
||||
|
||||
Email addresses, phone numbers, FCM installation ids and legacy tokens, APNs device tokens, Web Push
|
||||
endpoints and keys, VAPID private keys, provider credentials, callback signing secrets, template
|
||||
variables, rendered bodies, attachment references and unsubscribe tokens.
|
||||
이메일 주소, 전화번호, FCM installation id와 legacy token, APNs device token, Web Push endpoint와 키, VAPID private key,
|
||||
provider 자격 증명, 콜백 서명 secret, 템플릿 변수, 렌더링한 본문, 첨부 참조, 수신 거부 token.
|
||||
|
||||
## At rest
|
||||
## 저장할 때
|
||||
|
||||
Contact points are encrypted with AES-256-GCM. Equality lookup uses a separate HMAC-SHA-256
|
||||
fingerprint.
|
||||
연락처는 AES-256-GCM으로 암호화한다. 같은지 찾는 조회는 따로 둔 HMAC-SHA-256 fingerprint를 쓴다.
|
||||
|
||||
Two keys, not one, because the requirements are opposite: the ciphertext must be non-deterministic so
|
||||
two records of the same address are not visibly identical, while equality lookup must be
|
||||
deterministic. The fingerprint is keyed rather than a plain digest because phone numbers and email
|
||||
addresses come from a small, enumerable space — an unkeyed hash of a phone number is recoverable in
|
||||
seconds.
|
||||
요구가 반대라서 키가 하나가 아니라 둘이다. 암호문은 결정적이지 않아야 같은 주소의 두 기록이 겉으로 같아 보이지 않고,
|
||||
같은지 찾는 조회는 결정적이어야 한다. fingerprint를 그냥 digest가 아니라 키가 있는 것으로 두는 이유는 전화번호와 이메일
|
||||
주소가 작고 셀 수 있는 공간에서 오기 때문이다. 키 없는 전화번호 hash는 몇 초면 되살린다.
|
||||
|
||||
The contact point kind is bound into the GCM associated data, so a ciphertext cannot be moved between
|
||||
contact kinds without failing the authentication tag.
|
||||
연락처 종류를 GCM associated data에 묶으므로, 암호문을 다른 연락처 종류로 옮기면 인증 tag가 실패한다.
|
||||
|
||||
An unknown key id is refused rather than silently falling back to the current key: a silent fallback
|
||||
would turn every historical row into a tag failure at read time.
|
||||
모르는 key id는 현재 키로 조용히 대신하지 않고 거부한다. 조용히 대신하면 이력의 모든 행이 읽을 때 tag 실패가 된다.
|
||||
|
||||
## Never logged, never a metric tag
|
||||
## 로그에도 메트릭 태그에도 넣지 않는 것
|
||||
|
||||
Addresses, tokens, Web Push endpoints and keys, message bodies, template variables, provider
|
||||
credentials, unsubscribe tokens, attachment URLs, raw callback payloads and raw provider request ids.
|
||||
주소, token, Web Push endpoint와 키, 메시지 본문, 템플릿 변수, provider 자격 증명, 수신 거부 token, 첨부 URL, 원본 콜백
|
||||
payload, 원본 provider request id.
|
||||
|
||||
`CardinalityGuard` enforces this for metrics rather than convention: it validates every metric tag
|
||||
against a closed allowlist.
|
||||
메트릭은 관례가 아니라 `CardinalityGuard`가 강제한다. 모든 메트릭 태그를 닫힌 허용 목록과 대조한다.
|
||||
|
||||
An allowlist rather than a denylist, because the failure mode of a denylist is that the one field
|
||||
nobody thought of is the one that leaks.
|
||||
거부 목록이 아니라 허용 목록인 이유가 있다. 거부 목록이 실패하는 꼴은, 아무도 생각하지 못한 그 칸 하나가 새는 것이다.
|
||||
|
||||
Every contact point value type overrides `toString()` to print `[redacted]`. That covers the case a
|
||||
central redactor cannot: a value interpolated into a log line by accident.
|
||||
모든 연락처 값 타입은 `toString()`을 고쳐 `[redacted]`를 찍는다. 그것은 중앙 redactor가 막지 못하는 경우, 실수로 로그
|
||||
줄에 끼워 넣은 값을 막는다.
|
||||
|
||||
## Web Push endpoints
|
||||
## Web Push endpoint
|
||||
|
||||
RFC 8030 defines the push URI as a capability URL — knowing it is sufficient to push to the
|
||||
subscriber. It is handled as a secret, not as a URL.
|
||||
RFC 8030은 push URI를 capability URL로 정의한다. 그것을 알면 구독자에게 push할 수 있다. 그래서 URL이 아니라 secret으로
|
||||
다룬다.
|
||||
|
||||
## Callbacks
|
||||
## 콜백
|
||||
|
||||
TLS, provider signature verification over the exact received bytes and external URL, replay defence
|
||||
where a timestamp or nonce is available, body-size and content-type limits, profile binding, rate
|
||||
limiting, idempotent ingestion and a security audit trail for rejections.
|
||||
TLS, 받은 그대로의 바이트와 외부 URL에 대한 provider 서명 검증, timestamp나 nonce가 있으면 replay 방어, 본문 크기와
|
||||
content type 한도, profile 묶기, 속도 제한, 멱등한 받기, 거부를 남기는 보안 감사 기록.
|
||||
|
||||
## Tenant isolation
|
||||
## 테넌트 격리
|
||||
|
||||
Every store port carries the tenant boundary in its signature. Administrative operations require an
|
||||
explicit tenant or a global authority.
|
||||
모든 저장소 port는 시그니처에 테넌트 경계를 싣는다. 관리 작업에는 명시한 테넌트나 전역 권한이 필요하다.
|
||||
|
||||
@@ -1,109 +1,102 @@
|
||||
# Notification support matrix
|
||||
# 알림 지원 매트릭스
|
||||
|
||||
What each channel can actually prove, and what the platform refuses to claim.
|
||||
채널마다 실제로 증명할 수 있는 것과, 플랫폼이 주장하기를 거부하는 것이다.
|
||||
|
||||
The grade column is not an opinion. `docs/notification/evidence-manifest.json` declares which claims
|
||||
each grade requires and which executable artifact proves each claim, and
|
||||
`NotificationEvidenceVerifierTest` (in `:adapter:outbound:notification:test`) refuses a grade whose
|
||||
claims are not all backed by a file that exists. Raising a grade means adding the artifact first.
|
||||
등급 칸은 의견이 아니다. `docs/notification/evidence-manifest.json`이 등급마다 필요한 claim과 claim마다 그것을 증명하는
|
||||
실행 산출물을 선언하고, `NotificationEvidenceVerifierTest`(`:adapter:outbound:notification:test`)가 claim이 모두 실제
|
||||
파일로 뒷받침되지 않은 등급을 거부한다. 등급을 올리려면 산출물을 먼저 더한다.
|
||||
|
||||
Five channels read `Stable` until 2026-08-15. Nothing in the pipeline had ever sent a request to a
|
||||
provider — the sandbox job's whole body was two `echo` statements behind `continue-on-error` — and
|
||||
no test killed a worker mid-dispatch. The protocols are implemented and their contracts are proven
|
||||
against real PostgreSQL; the wire and the crash are not. That is what the grade now says.
|
||||
2026-08-15까지 다섯 채널이 `Stable`이었다. 파이프라인의 어떤 것도 provider에 요청을 보낸 적이 없었고(sandbox job의 본문
|
||||
전체가 `continue-on-error` 뒤의 `echo` 두 줄이었다), 발송 도중 worker를 죽인 테스트도 없었다. 프로토콜은 구현돼 있고 그
|
||||
계약은 실제 PostgreSQL에서 증명됐지만, 실제 전송과 장애 중단은 증명되지 않았다. 지금 등급이 말하는 것이 그것이다.
|
||||
|
||||
## Channels
|
||||
## 채널
|
||||
|
||||
| Channel | Reference implementation | Grade | Strongest evidence the platform records by default |
|
||||
| 채널 | 참조 구현 | 등급 | 플랫폼이 기본으로 기록하는 가장 강한 증거 |
|
||||
|---|---|---|---|
|
||||
| Email | SMTP, Amazon SES API | Contract implemented / runtime unqualified | Provider acceptance; recipient mail-server delivery, bounce and complaint when the provider publishes events |
|
||||
| SMS | none shipped — adapter removed; the channel type stays in the application API (see `docs/capability-status.md` 제거된 코드) | Extension | Whatever the added provider adapter can prove |
|
||||
| Mobile push (FCM, APNs) | none shipped — adapter removed; the channel type stays in the application API (see `docs/capability-status.md` 제거된 코드) | Extension | Whatever the added provider adapter can prove |
|
||||
| Web Push | none shipped — adapter removed; the channel type stays in the application API (see `docs/capability-status.md` 제거된 코드) | Extension | Whatever the added provider adapter can prove |
|
||||
| In-app inbox | Own database | Optional stable | `PERSISTED`, `SEEN`, `READ` |
|
||||
| Webhook | none shipped — adapter removed; the channel type stays in the application API (see `docs/capability-status.md` 제거된 코드) | Extension | Whatever the receiving HTTP contract states |
|
||||
| Email | SMTP, Amazon SES API | Contract implemented / runtime unqualified | provider 수락. provider가 이벤트를 내면 수신 메일 서버 전달, bounce, complaint |
|
||||
| SMS | 내보내지 않음 — 어댑터를 지웠고 채널 종류는 애플리케이션 API에 남아 있다(`docs/capability-status.md` 제거된 코드) | Extension | 더한 provider 어댑터가 증명할 수 있는 것 |
|
||||
| 모바일 push(FCM, APNs) | 내보내지 않음 — 어댑터를 지웠고 채널 종류는 애플리케이션 API에 남아 있다(`docs/capability-status.md` 제거된 코드) | Extension | 더한 provider 어댑터가 증명할 수 있는 것 |
|
||||
| Web Push | 내보내지 않음 — 어댑터를 지웠고 채널 종류는 애플리케이션 API에 남아 있다(`docs/capability-status.md` 제거된 코드) | Extension | 더한 provider 어댑터가 증명할 수 있는 것 |
|
||||
| 앱 안 inbox | 자체 DB | Optional stable | `PERSISTED`, `SEEN`, `READ` |
|
||||
| Webhook | 내보내지 않음 — 어댑터를 지웠고 채널 종류는 애플리케이션 API에 남아 있다(`docs/capability-status.md` 제거된 코드) | Extension | 받는 HTTP 계약이 말하는 것 |
|
||||
|
||||
## Shipped provider assembly reachability
|
||||
## 내보내는 provider 조립이 닿는 범위
|
||||
|
||||
The grade above describes protocol/reliability evidence. It does **not** mean every reference
|
||||
implementation is selectable in the default composition. Dispatch reachability is a separate axis:
|
||||
위 등급은 프로토콜·신뢰성 증거를 말한다. 모든 참조 구현을 기본 조립에서 고를 수 있다는 뜻이 **아니다**. 발송이 닿는지는
|
||||
따로 보는 축이다.
|
||||
|
||||
| Provider family | Dispatch assembler in shipped composition | Callback assembler | Current use |
|
||||
| provider family | 내보내는 조립의 발송 assembler | 콜백 assembler | 지금 쓰임 |
|
||||
|---|---|---|---|
|
||||
| SMTP | **yes** | no | EMAIL dispatch reference family |
|
||||
| SES | **yes** | **yes** | EMAIL dispatch + SNS callback ingestion; disabled reference profile ships in `config/module-defaults/notification.yml` (`composition:notification-platform`) |
|
||||
| SMTP | **있음** | 없음 | EMAIL 발송 참조 family |
|
||||
| SES | **있음** | **있음** | EMAIL 발송 + SNS 콜백 수집. 꺼진 참조 profile이 `config/module-defaults/notification.yml`(`composition:notification-platform`)에 들어 있다 |
|
||||
|
||||
APNs, FCM, Twilio, Web Push and Webhook adapters shipped as protocol code with no assembler and
|
||||
were removed; `ProviderType` now lists only SES and SMTP, so such a profile fails binding as an
|
||||
unknown type. An enabled dispatch profile with no assembler fails startup by profile/family; it never silently
|
||||
assembles into an empty runtime. SMTP additionally names `spring.mail.host` when its shipped
|
||||
assembler is absent because the relay was not configured.
|
||||
APNs, FCM, Twilio, Web Push, Webhook 어댑터는 assembler 없이 프로토콜 코드로만 들어 있다가 지워졌다. 이제
|
||||
`ProviderType`에는 SES와 SMTP만 있으므로 그런 profile은 모르는 종류로 바인딩에서 실패한다. assembler가 없는 켜진 발송
|
||||
profile은 profile·family 이름을 대며 기동에 실패한다. 빈 런타임으로 조용히 조립되는 일은 없다. SMTP는 relay가 설정되지
|
||||
않아 내보내는 assembler가 없으면 `spring.mail.host`도 이름 댄다.
|
||||
|
||||
## What each grade requires
|
||||
## 등급마다 필요한 것
|
||||
|
||||
| Grade | Requires |
|
||||
| 등급 | 필요한 claim |
|
||||
|---|---|
|
||||
| Stable | durable, multi-worker-safe, callback-supported, recoverable, provider-wire-qualified |
|
||||
| Contract implemented / runtime unqualified | durable, multi-worker-safe, callback-supported |
|
||||
| Optional stable | durable |
|
||||
| Extension | nothing; the receiving contract owns its own guarantees |
|
||||
| Experimental | nothing; the grade is the warning |
|
||||
| Extension | 없음. 받는 쪽 계약이 자기 보장을 가진다 |
|
||||
| Experimental | 없음. 등급 자체가 경고다 |
|
||||
|
||||
`recoverable` is backed by two tests. `WorkerCrashRecoveryContractTest` walks the four phases a
|
||||
dispatch passes through — claimed, attempt written, request started, body committed — and pins the
|
||||
rows a dead worker leaves at each: a passed lease, and from the attempt insert on an unfinished
|
||||
attempt carrying that phase's evidence. It writes those rows itself, so it checks recovery's input,
|
||||
not recovery. `PostgreSqlNotificationBackgroundPassIntegrationTest` runs lease recovery and
|
||||
reconciliation over rows the dispatcher's own factory wrote and asserts the outcome: requeued before
|
||||
any attempt, reconciled after one (review 05-01, RR-03-07).
|
||||
`recoverable`은 테스트 둘이 뒷받침한다. `WorkerCrashRecoveryContractTest`는 발송이 지나는 네 단계(claim됨, attempt 기록됨,
|
||||
요청 시작됨, 본문 커밋됨)를 따라가며 단계마다 죽은 worker가 남기는 행을 고정한다. 지난 lease, 그리고 attempt insert부터는
|
||||
그 단계의 증거를 가진 끝나지 않은 attempt다. 그 행을 테스트가 직접 쓰므로, 복구가 아니라 복구의 입력을 확인한다.
|
||||
`PostgreSqlNotificationBackgroundPassIntegrationTest`는 dispatcher 자신의 factory가 쓴 행에 lease 복구와 맞추기를 돌리고
|
||||
결과를 단언한다. attempt 전이면 다시 큐에 넣고, attempt 뒤면 맞춘다(review 05-01, RR-03-07).
|
||||
|
||||
The remaining unmet claim, and what would meet it:
|
||||
남은 미충족 claim과 그것을 채울 것:
|
||||
|
||||
- **provider-wire-qualified** — a real provider sandbox call producing an immutable, uploaded
|
||||
artifact with a correlation id. No request has ever left the process in CI.
|
||||
- **provider-wire-qualified** — 실제 provider sandbox 호출로 correlation id가 있는 불변 산출물을 만들어 올린다. CI에서
|
||||
프로세스 밖으로 요청이 나간 적이 한 번도 없다.
|
||||
|
||||
## Evidence levels
|
||||
## 증거 수준
|
||||
|
||||
`NONE` → `PLATFORM_QUEUED` → `PROVIDER_ACCEPTED` → `NETWORK_OR_CARRIER_ACCEPTED` →
|
||||
`DEVICE_DELIVERED` → `USER_AGENT_DISPLAYED` → `USER_READ`
|
||||
|
||||
| Provider signal | Highest evidence it may produce |
|
||||
| provider 신호 | 그 신호가 낼 수 있는 가장 높은 증거 |
|
||||
|---|---|
|
||||
| Internal queue commit | `PLATFORM_QUEUED` |
|
||||
| 내부 큐 커밋 | `PLATFORM_QUEUED` |
|
||||
| SES `MessageId` | `PROVIDER_ACCEPTED` |
|
||||
| SES `Delivery` | `NETWORK_OR_CARRIER_ACCEPTED` |
|
||||
| In-app row commit | `PROVIDER_ACCEPTED` |
|
||||
| In-app `seen` endpoint | `USER_AGENT_DISPLAYED` |
|
||||
| In-app `read` endpoint, authenticated app receipt | `USER_READ` |
|
||||
| 앱 안 행 커밋 | `PROVIDER_ACCEPTED` |
|
||||
| 앱 안 `seen` 엔드포인트 | `USER_AGENT_DISPLAYED` |
|
||||
| 앱 안 `read` 엔드포인트, 인증된 앱 수신 확인 | `USER_READ` |
|
||||
|
||||
Promotions the platform will not make, in code or in configuration:
|
||||
플랫폼이 코드에서도 설정에서도 하지 않는 승격:
|
||||
|
||||
- A push or SMS acceptance, from any provider adapter a deployment adds, is not `DEVICE_DELIVERED`.
|
||||
- A provider 2xx is not `DELIVERED`.
|
||||
- An SES `MessageId` is not `DELIVERED`.
|
||||
- An SMTP `250` is not inbox delivery.
|
||||
- 배포가 더한 어느 provider 어댑터에서 온 것이든 push·SMS 수락은 `DEVICE_DELIVERED`가 아니다.
|
||||
- provider의 2xx는 `DELIVERED`가 아니다.
|
||||
- SES `MessageId`는 `DELIVERED`가 아니다.
|
||||
- SMTP `250`은 받은편지함 도착이 아니다.
|
||||
|
||||
## Submission outcomes
|
||||
## 제출 결과
|
||||
|
||||
`NOT_SUBMITTED`, `CONFIRMED_ACCEPTED`, `CONFIRMED_REJECTED`, `AMBIGUOUS`.
|
||||
|
||||
`AMBIGUOUS` is a first-class stored state, not an error path. It means the request body was committed
|
||||
to the provider and the outcome could not be read. While an ambiguous attempt exists on a recipient
|
||||
delivery, automatic retry and automatic cross-channel fallback are both blocked.
|
||||
`AMBIGUOUS`는 오류 경로가 아니라 정식으로 저장되는 상태다. 요청 본문을 provider에 넘겼지만 결과를 읽지 못했다는 뜻이다.
|
||||
수신자 전달에 모호한 attempt가 있는 동안에는 자동 재시도와 자동 채널 전환이 모두 막힌다.
|
||||
|
||||
## Not supported
|
||||
## 지원하지 않는 것
|
||||
|
||||
The platform will not claim any of the following, because no channel above can support them:
|
||||
위의 어떤 채널도 뒷받침할 수 없으므로 플랫폼은 다음 중 어떤 것도 주장하지 않는다.
|
||||
|
||||
- guaranteed delivery
|
||||
- guaranteed read
|
||||
- exactly-once human notification
|
||||
- unconditional multi-provider failover after an unread response
|
||||
- provider SDK types in the public API
|
||||
- audience selection, campaign segmentation or jurisdiction rulings
|
||||
- 전달 보장(guaranteed delivery)
|
||||
- 읽음 보장(guaranteed read)
|
||||
- 사람에게 가는 알림의 정확히 한 번(exactly-once) 전달
|
||||
- 읽지 못한 응답 뒤의 조건 없는 다중 provider failover
|
||||
- 공개 API의 provider SDK 타입
|
||||
- 대상 선정, 캠페인 세분화, 관할 판정
|
||||
|
||||
## Target model
|
||||
## 대상 모델
|
||||
|
||||
`FCM_FID` is the primary mobile push target. `FCM_REGISTRATION_TOKEN_LEGACY` and
|
||||
`APNS_DEVICE_TOKEN` are separate types with separate lifecycles; they are never flattened into one
|
||||
string field.
|
||||
`FCM_FID`가 모바일 push의 기본 대상이다. `FCM_REGISTRATION_TOKEN_LEGACY`와 `APNS_DEVICE_TOKEN`은 수명 주기가 다른 별도
|
||||
종류다. 하나의 문자열 칸으로 합치지 않는다.
|
||||
|
||||
Reference in New Issue
Block a user