docs: 알림·파일·객체 저장소·Redis leaf 안내의 범위를 코드대로 좁히고 callback 예외를 적는다
pr / done (pull_request) Canceled after 0s
pr / done (pull_request) Canceled after 0s
문제(구조 리뷰): - 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
This commit is contained in:
@@ -16,6 +16,9 @@ body size limit
|
||||
→ 2xx
|
||||
```
|
||||
|
||||
응답은 본문 없는 status다: 받으면(중복도) 204, 서명·형식 거절은 400, 본문 한도 초과는 413, 검증을 돌리지 못하면
|
||||
503과 `Retry-After`. provider는 4xx면 멈추고 5xx면 다시 보낸다. 인증 전 경로라 거절 이유를 싣지 않는다.
|
||||
|
||||
projection보다 ledger 추가를 먼저 하기 때문에 빠른 2xx가 정직하다. provider에게는 이벤트가 기록됐다고 알리고,
|
||||
projector 결함은 이벤트 유실이 아니라 replay 문제가 된다.
|
||||
|
||||
|
||||
@@ -70,6 +70,10 @@ status는 코드 표(`HttpStatusErrorCodes`)에 있는 것만 그대로 나간
|
||||
4xx·5xx status로 나가는 본문은 `success:true`로 감싸지 않는다. 실패 Envelope가 아닌 본문을 오류 status로
|
||||
돌려주는 핸들러는 그 본문이 그대로 나간다.
|
||||
|
||||
Envelope가 아닌 응답은 두 곳뿐이다. fileserver의 프로토콜 예외(`docs/fileserver/http-contract.md` 「Envelope 규칙의
|
||||
프로토콜 예외」)와 알림 provider callback이다. callback은 provider가 status만 읽는 webhook 응답이라 본문 없이
|
||||
204·400·413·503만 답한다(`src/adapter/inbound/web-notification/AGENTS.md`).
|
||||
|
||||
### 왜 이렇게 나가는가
|
||||
|
||||
`Envelope`·`BulkEnvelope`·`ApiError`·`ResponseMeta`는 `shared-contract`에 있고, 이 leaf는 Java
|
||||
|
||||
@@ -21,6 +21,7 @@
|
||||
- callback 경로는 presentation prefix를 받지 않는 절대 경로다. provider에 한 번 등록한 URL이 prefix 변경으로 움직이면 안 된다(`NotificationRoutePrefixTest`).
|
||||
- callback chain은 인증 없이 연다. 서명 검증은 이 leaf의 `ProviderCallbackIngress`에 맡긴다. 구현은 `composition:notification-platform`의 `ProviderCallbackIngressBridge`이고, `adapter:outbound:notification`의 provider adapter(`ProviderCallbackAdapterRegistry`, SES는 `SnsSignatureVerifier`)로 검증한 뒤 검증된 event만 유스케이스에 넘긴다. 유스케이스는 서명을 보지 않는다.
|
||||
- 그 `permitAll`은 공개 경로 스냅숏(`docs/security/public-paths-snapshot.txt`)에 들어 있다. callback 경로를 바꾸면 스냅숏도 바뀐다.
|
||||
- callback 응답은 Envelope 규칙의 예외다. 본문 없이 204(받음, 중복도 같다)·400(서명·형식 거절)·413(본문 한도)·503(검증을 못 돌림, `Retry-After`)만 답한다. 인증 전 경로라 거절 이유를 싣지 않고, provider는 status만 본다(4xx면 멈추고 5xx면 다시 보낸다). 본문을 더하거나 status를 바꾸면 provider의 재전송 동작이 바뀐다(`NotificationCallbackMvcController` Javadoc).
|
||||
- `adapter:inbound:web`의 inbound 규칙이 그대로 적용된다: repository 접근 없음, DTO를 application으로 넘기지 않음.
|
||||
|
||||
## 테스트
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# adapter:inbound:web-notification
|
||||
|
||||
알림 플랫폼의 HTTP 표면을 담는 leaf다. 요청을 유스케이스 command로 바꾸고 응답을 Envelope로 돌려준다.
|
||||
알림 플랫폼의 HTTP 표면을 담는 leaf다. 요청을 유스케이스 command로 바꾼다. 제출·template 게시는 Envelope로 답하고, provider callback은 본문 없이 status만 답한다.
|
||||
|
||||
## 책임과 소유하지 않는 것
|
||||
|
||||
|
||||
@@ -44,7 +44,7 @@ transfer와 multipart는 코드가 없다: 조립되지 않은 구현을 지웠
|
||||
이 줄을 지우면 port 구현, provider, 설정 바인딩이 모두 함께 빠진다.
|
||||
- 켜기와 끄기: 모듈이 있으면 켜진다. `app.object-storage.enabled=false`로만 끄고, 그때 모듈은 아무
|
||||
bean도 두지 않는다.
|
||||
- env 키: 전용 `APP_*` 키는 없다. provider·destination이 map 구조라 배포의 `application-*.yml`에
|
||||
- env 키: `APP_OBJECTSTORAGE_ENABLED`(끄기) 하나뿐이다. provider·destination은 map 구조라 배포의 `application-*.yml`에
|
||||
`app.object-storage.{default-destination, providers.<id>.*, destinations.<id>.*}`를 적는다(아래
|
||||
「켜기와 라우팅」). 빠지면 기동 시 binding compile이 실패한다.
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# adapter:outbound:redis-runtime
|
||||
|
||||
Redis 연결과 명령 실행의 공용 runtime을 담는 leaf다. 업무 포트는 위 leaf(`cache-redis`, `redis-sdk`)가 구현한다.
|
||||
Redis 연결과 명령 실행의 공용 runtime을 담는 leaf다. 업무 포트는 `cache-redis`가 구현하고, `redis-sdk`는 서비스 코드가 직접 부르는 SDK 표면을 준다(bean도 포트 구현도 없다).
|
||||
|
||||
## 책임과 소유하지 않는 것
|
||||
|
||||
@@ -15,7 +15,10 @@ Redis 연결과 명령 실행의 공용 runtime을 담는 leaf다. 업무 포트
|
||||
|
||||
## 조립
|
||||
|
||||
직접 더하지 않는다. `runtimeOnly project(':adapter:outbound:cache-redis')`가 이 leaf를 함께 싣고, 이 leaf의 `RedisRuntimeAutoConfiguration`이 켜진다. 끄는 키는 `APP_REDIS_ENABLED`다.
|
||||
직접 더하지 않는다. 이 leaf를 싣는 길은 둘이다.
|
||||
|
||||
- `runtimeOnly project(':adapter:outbound:cache-redis')`: cache-redis의 기본값(`app.redis.enabled: ${APP_REDIS_ENABLED:true}`)이 함께 와서 `RedisRuntimeAutoConfiguration`이 켜진다. 끄는 키는 `APP_REDIS_ENABLED`다.
|
||||
- `implementation project(':adapter:outbound:redis-sdk')`: SDK가 이 leaf를 `api`로 싣는다. 이 길에는 cache-redis 기본값이 없고 `RedisRuntimeAutoConfiguration`은 `app.redis.enabled=true`일 때만 켜지므로, `APP_REDIS_ENABLED=true`를 직접 준다(`src/adapter/outbound/redis-sdk/README.md` 「env 키」).
|
||||
|
||||
## 테스트 명령
|
||||
|
||||
|
||||
@@ -13,7 +13,7 @@
|
||||
|
||||
- 업로드(단일·raw·batch·이어 쓰기)·다운로드·복사·이동·삭제·정리의 유스케이스와 그 정책(할당량, 전송 허가, 표시 이름).
|
||||
- 들어오는 포트(`port.in`), 나가는 포트, 오류 어휘 `api.error.FileserverErrorCode`(HTTP 표는 `docs/fileserver/http-contract.md` 「오류 코드」).
|
||||
- testFixtures `testkit`: 포트마다 fake와 공유 계약.
|
||||
- testFixtures `testkit`: 저장·대기열 포트의 공유 계약(`*PortContract`)과 in-memory 구현, 내용 gateway·정책의 fake. 모든 포트에 계약이 있지는 않다(다운로드·zero-copy·사용량·지표 포트는 없다).
|
||||
|
||||
## 규칙
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
|
||||
- 업로드(단일·raw·batch·이어 쓰기)·다운로드·복사·이동·삭제·정리의 유스케이스와 그 정책(할당량, 전송 허가, 표시 이름).
|
||||
- 들어오는 포트(`port.in`), 나가는 포트, 오류 어휘 `api.error.FileserverErrorCode`(HTTP 표는 `docs/fileserver/http-contract.md` 「오류 코드」).
|
||||
- testFixtures `testkit`: 포트마다 fake와 공유 계약.
|
||||
- testFixtures `testkit`: 저장·대기열 포트의 공유 계약(`*PortContract`)과 in-memory 구현, 내용 gateway·정책의 fake. 모든 포트에 계약이 있지는 않다(다운로드·zero-copy·사용량·지표 포트는 없다).
|
||||
- 소유하지 않는 것: HTTP 모양(`adapter:inbound:web-fileserver`), 바이트 저장(`adapter:outbound:fileserver`), metadata 저장(`adapter:outbound:persistence-fileserver`), 조립(`composition:fileserver-platform`).
|
||||
|
||||
## 공개 표면
|
||||
|
||||
@@ -12,8 +12,8 @@
|
||||
## 책임
|
||||
|
||||
- 알림 플랫폼의 업무 흐름: 제출·예약·취소·조회, template 게시, provider callback 수집, 발송 판정과 재시도 정책.
|
||||
- 들어오는 포트(`platform.port.in`의 `*UseCase`·`*Command`·`*Query`), 나가는 포트(`*Port`, 쓰는 흐름의 패키지에 있다: `platform.dispatch`·`platform.callback`·`platform.policy`·`platform.observation`·`platform.admin`·`platform.inbox`·`platform.template`), 오류 어휘(`platform.api.error`). `port.out` 패키지는 따로 없다.
|
||||
- testFixtures: 흐름 패키지마다 `testkit`에 저장 포트의 in-memory fake와 공유 계약(`*Contract`), provider adapter 계약(`ProviderAdapterContract`). adapter의 시험이 같은 계약을 상속한다.
|
||||
- 들어오는 포트(`platform.port.in`의 `*UseCase`·`*Command`·`*Query`), 나가는 포트(쓰는 흐름의 패키지에 있다: `platform.dispatch`·`platform.callback`·`platform.policy`·`platform.observation`·`platform.admin`·`platform.inbox`·`platform.template`·`platform.provider`·`platform.security`), 오류 어휘(`platform.api.error`). `port.out` 패키지는 따로 없다. 나가는 포트 이름은 대개 `*Port`지만 아닌 것도 있다: `provider.NotificationProviderAdapter`·`BatchNotificationProviderAdapter`·`AttachmentResolver`, `security.SecretMaterialProvider`·`ContactPointProtector`, `template.TemplateRegistry`, `callback.ProviderEventLedger`. 새 포트를 만들기 전에 이 이름들도 찾는다.
|
||||
- testFixtures(흐름 패키지의 `testkit`): 저장 포트의 in-memory fake와 공유 계약(`*Contract`), provider adapter 계약(`ProviderAdapterContract`). 모든 포트에 있지는 않다. adapter의 시험이 같은 계약을 상속한다.
|
||||
|
||||
## 규칙
|
||||
|
||||
|
||||
@@ -5,13 +5,13 @@
|
||||
## 책임과 소유하지 않는 것
|
||||
|
||||
- 알림 플랫폼의 업무 흐름: 제출·예약·취소·조회, template 게시, provider callback 수집, 발송 판정과 재시도 정책.
|
||||
- 들어오는 포트(`platform.port.in`의 `*UseCase`·`*Command`·`*Query`), 나가는 포트(`*Port`, 쓰는 흐름의 패키지에 있다: `platform.dispatch`·`platform.callback`·`platform.policy`·`platform.observation`·`platform.admin`·`platform.inbox`·`platform.template`), 오류 어휘(`platform.api.error`). `port.out` 패키지는 따로 없다.
|
||||
- testFixtures: 흐름 패키지마다 `testkit`에 저장 포트의 in-memory fake와 공유 계약(`*Contract`), provider adapter 계약(`ProviderAdapterContract`). adapter의 시험이 같은 계약을 상속한다.
|
||||
- 들어오는 포트(`platform.port.in`의 `*UseCase`·`*Command`·`*Query`), 나가는 포트(쓰는 흐름의 패키지에 있다: `platform.dispatch`·`platform.callback`·`platform.policy`·`platform.observation`·`platform.admin`·`platform.inbox`·`platform.template`·`platform.provider`·`platform.security`), 오류 어휘(`platform.api.error`). `port.out` 패키지는 따로 없다. 나가는 포트 이름은 대개 `*Port`지만 아닌 것도 있다: `provider.NotificationProviderAdapter`·`BatchNotificationProviderAdapter`·`AttachmentResolver`, `security.SecretMaterialProvider`·`ContactPointProtector`, `template.TemplateRegistry`, `callback.ProviderEventLedger`. 새 포트를 만들기 전에 이 이름들도 찾는다.
|
||||
- testFixtures(흐름 패키지의 `testkit`): 저장 포트의 in-memory fake와 공유 계약(`*Contract`), provider adapter 계약(`ProviderAdapterContract`). 모든 포트에 있지는 않다. adapter의 시험이 같은 계약을 상속한다.
|
||||
- 소유하지 않는 것: HTTP 모양(`adapter:inbound:web-notification`), provider 호출·설정(`adapter:outbound:notification`), 저장(`adapter:outbound:persistence-notification`), 조립(`composition:notification-platform`).
|
||||
|
||||
## 공개 표면
|
||||
|
||||
들어오는 포트 `platform.port.in`(예: `SubmitNotificationUseCase`, `PublishNotificationTemplateUseCase`, `IngestProviderCallbackUseCase`), 흐름 패키지의 나가는 포트(`*Port`), 오류 `platform.api.error`. 설정 prefix는 없다(설정은 `adapter:outbound:notification`의 `app.notification.platform.*`).
|
||||
들어오는 포트 `platform.port.in`(예: `SubmitNotificationUseCase`, `PublishNotificationTemplateUseCase`, `IngestProviderCallbackUseCase`), 흐름 패키지의 나가는 포트(`*Port`와 위의 이름들), 오류 `platform.api.error`. 설정 prefix는 없다(설정은 `adapter:outbound:notification`의 `app.notification.platform.*`).
|
||||
|
||||
## 조립
|
||||
|
||||
|
||||
@@ -18,7 +18,7 @@
|
||||
|
||||
- framework·AWS SDK 의존이 없다(`ca.java-library`). 허용 의존은 registry의 `application-core`·`shared-contract`뿐이다.
|
||||
- S3·MinIO 개념(bucket 정책, presign 구현)은 adapter의 것이다. 포트는 저장소에 상관없는 말로 쓴다.
|
||||
- 포트를 바꾸면 adapter의 계약 시험(`adapter:outbound:objectstorage` testFixtures)을 같은 변경에서 고친다.
|
||||
- 이 leaf에는 포트 계약 시험이 아직 없다. adapter testFixtures의 `ObjectStorageProviderContract`는 adapter 안의 provider SPI를 시험하고, 이 leaf의 포트는 시험하지 않는다. 값 타입(`model`·`request`·`identity`·`content`)을 바꾸면 그 provider 계약을 같은 변경에서 고친다.
|
||||
|
||||
## 테스트
|
||||
|
||||
|
||||
Reference in New Issue
Block a user