Files
clean-architecture-backend-…/docs/notification/callback-reconciliation.md
T
DongHyeonka 4ca61cd9bc
pr / done (pull_request) Canceled after 0s
docs: 알림·파일·객체 저장소·Redis leaf 안내의 범위를 코드대로 좁히고 callback 예외를 적는다
문제(구조 리뷰):
- application-notification 안내가 나가는 포트를 `*Port`로만 적어 provider·security
  패키지와 이름이 다른 포트 일곱(NotificationProviderAdapter, TemplateRegistry 등)을
  빠뜨렸다. provider를 더하는 세션이 같은 계약을 두 번 만들 수 있다.
- notification·fileserver testFixtures를 모든 포트에 있는 것처럼 적었다.
- application-objectstorage 안내가 adapter의 provider SPI 계약을 이 leaf 포트의
  계약처럼 적었다. 이 leaf에는 포트 계약 시험이 없다.
- redis-runtime 안내가 redis-sdk를 포트 구현 leaf로 적었고, redis-sdk로 싣는 길에서는
  APP_REDIS_ENABLED를 직접 줘야 한다는 것을 적지 않았다.
- provider callback은 본문 없이 status만 답하는데, Envelope가 아닌 응답이 fileserver
  프로토콜 예외뿐인 것처럼 적혀 있었다. objectstorage README는 registry에 있는
  APP_OBJECTSTORAGE_ENABLED를 「전용 키 없음」이라 했다.

고친 것: 위 문장을 코드대로 고치고, callback 응답(204·400·413·503, 본문 없음)을 HTTP
계약 §1·callback 문서·leaf 안내에 예외로 적었다. callback 동작은 그대로 둔다(인증 전
경로라 거절 이유를 싣지 않고, provider는 status로 재전송을 정한다).

검증: check-docs.py·check-work-docs.py rc=0. 이 문서들을 읽는 시험은 존재 확인뿐이다
(NotificationReleaseGateTest).

Refs: RR9-04-42
2026-11-13 05:35:51 +09:00

2.5 KiB

콜백과 맞추기(reconciliation)

받는 순서

body size limit
  → content type
  → profile lookup
  → signature verification
  → append to the ledger
  → duplicate detection
  → normalization
  → attempt resolution
  → projection
  → side effects
  → 2xx

응답은 본문 없는 status다: 받으면(중복도) 204, 서명·형식 거절은 400, 본문 한도 초과는 413, 검증을 돌리지 못하면 503과 Retry-After. provider는 4xx면 멈추고 5xx면 다시 보낸다. 인증 전 경로라 거절 이유를 싣지 않는다.

projection보다 ledger 추가를 먼저 하기 때문에 빠른 2xx가 정직하다. provider에게는 이벤트가 기록됐다고 알리고, projector 결함은 이벤트 유실이 아니라 replay 문제가 된다.

서명이 거부된 콜백은 provider event ledger가 아니라 보안 감사에 기록한다. ledger에 쓰면 엔드포인트에 닿는 누구나 전달 이력을 잡음으로 채울 수 있다.

중복과 순서

중복 억제는 provider가 event id를 주면 (providerProfileId, providerEventId)를 쓰고, 주지 않으면 profile, request id, event 종류, 발생 시각, payload digest로 만든 결정적 fingerprint를 쓴다. 중복은 확인 응답하고 projection은 정확히 한 번 한다.

순서가 뒤바뀐 콜백은 보통이다. 순서는 도착 시각이 아니라 이벤트의 뜻으로 정한다.

모르는 칸

콜백 parser는 모르는 JSON 칸을 받아들인다. 정규화는 attempt를 가리키는 데 필요한 칸이 없을 때만 payload를 거부한다. provider는 칸을 더한다. 그것 때문에 받기가 멈추면 안 된다.

맞추기

맞추기 대상:

  • lease가 지나도 DISPATCHING에 멈춘 attempt
  • 모호한 제출
  • 콜백 SLA가 지난, 수락된 attempt
  • 짝이 없는 provider 이벤트

확인된 조회 결과는 source = RECONCILIATION으로 같은 ledger에 추가하고 같은 projector가 projection한다. 그래서 projection replay가 계속 가능하다. projection을 직접 쓰는 특별한 두 번째 길은 없다.

provider에 상태 조회 기능이 없으면 플랫폼은 Unsupported를 기록하고 attempt를 모호한 채로 둔다. 최종 상태를 짐작하지 않는다.

내보내는 family인 SES와 SMTP는 맞추기가 없다. 그 assembler는 ReconciliationCapability를 보태지 않으므로, 둘의 맞추기 작업은 모두 Unsupported로 끝난다. AssembledProvider의 그 자리는 도입하는 쪽이 자기 상태 조회와 함께 조립하는 provider family를 위한 것이다.