diff --git a/docs/notification/callback-reconciliation.md b/docs/notification/callback-reconciliation.md index 7e2d833a..9a3af5ed 100644 --- a/docs/notification/callback-reconciliation.md +++ b/docs/notification/callback-reconciliation.md @@ -16,6 +16,9 @@ body size limit → 2xx ``` +응답은 본문 없는 status다: 받으면(중복도) 204, 서명·형식 거절은 400, 본문 한도 초과는 413, 검증을 돌리지 못하면 +503과 `Retry-After`. provider는 4xx면 멈추고 5xx면 다시 보낸다. 인증 전 경로라 거절 이유를 싣지 않는다. + projection보다 ledger 추가를 먼저 하기 때문에 빠른 2xx가 정직하다. provider에게는 이벤트가 기록됐다고 알리고, projector 결함은 이벤트 유실이 아니라 replay 문제가 된다. diff --git a/docs/web/http-contract.md b/docs/web/http-contract.md index 1f66a154..78d154f6 100644 --- a/docs/web/http-contract.md +++ b/docs/web/http-contract.md @@ -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 diff --git a/src/adapter/inbound/web-notification/AGENTS.md b/src/adapter/inbound/web-notification/AGENTS.md index a9d030b5..41fac979 100644 --- a/src/adapter/inbound/web-notification/AGENTS.md +++ b/src/adapter/inbound/web-notification/AGENTS.md @@ -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으로 넘기지 않음. ## 테스트 diff --git a/src/adapter/inbound/web-notification/README.md b/src/adapter/inbound/web-notification/README.md index 83516d8b..55fc45f5 100644 --- a/src/adapter/inbound/web-notification/README.md +++ b/src/adapter/inbound/web-notification/README.md @@ -1,6 +1,6 @@ # adapter:inbound:web-notification -알림 플랫폼의 HTTP 표면을 담는 leaf다. 요청을 유스케이스 command로 바꾸고 응답을 Envelope로 돌려준다. +알림 플랫폼의 HTTP 표면을 담는 leaf다. 요청을 유스케이스 command로 바꾼다. 제출·template 게시는 Envelope로 답하고, provider callback은 본문 없이 status만 답한다. ## 책임과 소유하지 않는 것 diff --git a/src/adapter/outbound/objectstorage/README.md b/src/adapter/outbound/objectstorage/README.md index 6d57c05a..c8b38502 100644 --- a/src/adapter/outbound/objectstorage/README.md +++ b/src/adapter/outbound/objectstorage/README.md @@ -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..*, destinations..*}`를 적는다(아래 「켜기와 라우팅」). 빠지면 기동 시 binding compile이 실패한다. diff --git a/src/adapter/outbound/redis-runtime/README.md b/src/adapter/outbound/redis-runtime/README.md index 06723fea..99d74e16 100644 --- a/src/adapter/outbound/redis-runtime/README.md +++ b/src/adapter/outbound/redis-runtime/README.md @@ -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 키」). ## 테스트 명령 diff --git a/src/application/fileserver/AGENTS.md b/src/application/fileserver/AGENTS.md index 2f1f7427..8c39a929 100644 --- a/src/application/fileserver/AGENTS.md +++ b/src/application/fileserver/AGENTS.md @@ -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·사용량·지표 포트는 없다). ## 규칙 diff --git a/src/application/fileserver/README.md b/src/application/fileserver/README.md index c2a59f31..4f2f1f9c 100644 --- a/src/application/fileserver/README.md +++ b/src/application/fileserver/README.md @@ -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`). ## 공개 표면 diff --git a/src/application/notification/AGENTS.md b/src/application/notification/AGENTS.md index e230f2de..9c163f4d 100644 --- a/src/application/notification/AGENTS.md +++ b/src/application/notification/AGENTS.md @@ -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의 시험이 같은 계약을 상속한다. ## 규칙 diff --git a/src/application/notification/README.md b/src/application/notification/README.md index fa031656..682a0357 100644 --- a/src/application/notification/README.md +++ b/src/application/notification/README.md @@ -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.*`). ## 조립 diff --git a/src/application/objectstorage/AGENTS.md b/src/application/objectstorage/AGENTS.md index da3cdece..1543a289 100644 --- a/src/application/objectstorage/AGENTS.md +++ b/src/application/objectstorage/AGENTS.md @@ -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 계약을 같은 변경에서 고친다. ## 테스트