refactor: 부가 기능을 capability 모듈로 포장하고 기본 조립을 web-only로 전환

설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md

- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
  (compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
  messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
  outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
  Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
  qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용

삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-25 12:49:07 +09:00
co-authored by Claude Opus 5.5
parent 208077fddf
commit 6d27356e2b
2822 changed files with 27992 additions and 166879 deletions
@@ -0,0 +1,50 @@
# composition:fileserver-platform — 파일 서버 capability
- Module ID: `composition-fileserver-platform`
- Gradle path: `:composition:fileserver-platform`
- Package: `dev.caskeleton.composition.fileserver`
- 테스트: `./gradlew :composition:fileserver-platform:test --console=plain`
## 제공하는 것
이 모듈 하나를 붙이면 HTTP 파일 서버 전체가 들어온다.
```
composition:fileserver-platform
├─ FileserverPlatformAutoConfiguration HTTP surface·startup 정책·cleanup worker 조립
├─ FileserverAdminManagementContextConfiguration 관리 포트의 admin endpoint
├─ config/module-defaults/fileserver.yml (설정 기본값, support 로더가 읽음)
├─ adapter:outbound:fileserver 저장소·검증·업로드·다운로드 (FileserverCapabilityAutoConfiguration)
├─ adapter:outbound:persistence-fileserver 메타데이터·quota·recovery 테이블
└─ adapter:inbound:web-fileserver 업로드/다운로드/lifecycle route
```
- 켜기와 끄기: 모듈이 있으면 켜진다. `APP_FILESERVER_PLATFORM_ENABLED=false`로만 끈다. 끄면 detail
설정도 바인딩되지 않는다.
- 설정: `config/module-defaults/fileserver.yml`을 support의 `ModuleDefaultsEnvironmentPostProcessor`가 읽는다. 우선순위가 가장 낮아서 `application*.yml`, 환경
변수, 시스템 속성이 항상 이긴다. servlet multipart 상한(`spring.servlet.multipart.*`)도 같은
placeholder로 이 파일이 준다. app-bootstrap은 이 파일을 모른다.
- 저장소: 메타데이터 테이블은 JPA(`adapter:outbound:persistence-jpa`)가 있어야 한다.
## 추가할 한 줄
```groovy
// app-bootstrap/build.gradle
runtimeOnly project(':composition:fileserver-platform') // 파일 서버
```
이 줄을 지우면 route, 저장소, 메타데이터, 설정 기본값이 모두 함께 빠진다. 기본 조립에는 없다.
## 필요한 env 키
전체 목록과 타입·기본값은 `docs/registries/env-keys.yaml`의 `APP_FILESERVER_PLATFORM_*` 행이
SSOT다. 설명은 `docs/fileserver/configuration.md`.
| 언제 | 키 |
| --- | --- |
| 항상 | `APP_FILESERVER_PLATFORM_STORAGE_ROOT` (절대 경로, 전용 volume) |
| 항상 (metrics 기본 on) | `APP_FILESERVER_PLATFORM_OBSERVABILITY_FINGERPRINT_KEY` (secret), 또는 `APP_FILESERVER_PLATFORM_OBSERVABILITY_METRICS_ENABLED=false` |
| 다중 인스턴스 | `APP_FILESERVER_PLATFORM_INSTANCE_ID` (인스턴스마다 다르게) |
| 접근 정책 | 기본 `required`는 `FileAccessPolicy` bean이 있어야 한다. 아니면 `APP_FILESERVER_PLATFORM_SECURITY_ACCESS_POLICY=role-based` |
나머지(업로드·다운로드 상한, quota, cleanup, tus, nginx 위임)는 기본값으로 동작한다.
@@ -13,8 +13,8 @@ plugins {
// is why every application shipped Fileserver whether or not it wanted it.
//
// This module is not a composition root. It composes one capability; it does not run. What decides
// whether an application ships Fileserver is one project dependency in `app-bootstrap/build.gradle`,
// and its absence is enforced there by `dependencyPolicy`.
// whether an application ships Fileserver is one commented `runtimeOnly` line in
// `app-bootstrap/build.gradle`.
//
// It is deliberately thin: cross-adapter wiring only. A configuration that knows one leaf belongs to
// that leaf — the fileserver platform's own settings, storage gateway, verification and security
@@ -58,7 +58,6 @@ io.micrometer:micrometer-commons:1.16.7=compileClasspath,runtimeClasspath,testCo
io.micrometer:micrometer-core:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.micrometer:micrometer-jakarta9:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.micrometer:micrometer-observation:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.projectreactor:reactor-core:3.8.7=runtimeClasspath,testRuntimeClasspath
io.swagger.core.v3:swagger-annotations-jakarta:2.2.38=runtimeClasspath,testRuntimeClasspath
io.swagger.core.v3:swagger-core-jakarta:2.2.38=runtimeClasspath,testRuntimeClasspath
io.swagger.core.v3:swagger-models-jakarta:2.2.38=runtimeClasspath,testRuntimeClasspath
@@ -142,7 +141,6 @@ org.ow2.asm:asm-util:9.10.1=spotbugs
org.ow2.asm:asm:9.10.1=spotbugs
org.ow2.asm:asm:9.7.1=testCompileClasspath,testRuntimeClasspath
org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor
org.reactivestreams:reactive-streams:1.0.4=runtimeClasspath,testRuntimeClasspath
org.reflections:reflections:0.10.2=checkstyle
org.skyscreamer:jsonassert:1.5.3=testCompileClasspath,testRuntimeClasspath
org.slf4j:jul-to-slf4j:2.0.18=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
@@ -218,7 +216,6 @@ org.springframework:spring-orm:7.0.9=runtimeClasspath,testRuntimeClasspath
org.springframework:spring-test:7.0.9=testCompileClasspath,testRuntimeClasspath
org.springframework:spring-tx:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-web:7.0.9=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-webflux:7.0.9=runtimeClasspath,testRuntimeClasspath
org.springframework:spring-webmvc:7.0.9=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
org.xmlunit:xmlunit-core:2.10.4=testCompileClasspath,testRuntimeClasspath
@@ -1,5 +1,6 @@
package dev.caskeleton.composition.fileserver;
import dev.caskeleton.adapter.inbound.web.fileserver.config.FileserverHttpSurfaceConfiguration;
import dev.caskeleton.adapter.outbound.fileserver.platform.autoconfigure.FileserverPlatformSettings;
import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
@@ -23,7 +24,8 @@ import org.springframework.context.annotation.Import;
@ConditionalOnProperty(
prefix = FileserverPlatformSettings.PREFIX,
name = "enabled",
havingValue = "true")
havingValue = "true",
matchIfMissing = true)
@Import({
FileserverCorePolicyConfiguration.class,
FileserverWebAssemblyConfiguration.class,
@@ -39,6 +41,9 @@ import org.springframework.context.annotation.Import;
// they were left.
FileserverLocalStorageCoreConfiguration.class,
FileserverUploadServiceConfiguration.class,
FileserverCleanupConfiguration.class
FileserverCleanupConfiguration.class,
// The HTTP surface itself. Its controllers used to be found by the composition root's component
// scan of `dev.caskeleton.adapter`; the capability now brings them, so selecting it is enough.
FileserverHttpSurfaceConfiguration.class
})
public class FileserverPlatformAutoConfiguration {}
@@ -1,7 +1,6 @@
package dev.caskeleton.composition.fileserver;
import dev.caskeleton.adapter.inbound.web.fileserver.draft12.Draft12Properties;
import dev.caskeleton.adapter.inbound.web.fileserver.tus.TusChecksumVerifier;
import dev.caskeleton.adapter.inbound.web.fileserver.tus.TusProperties;
import dev.caskeleton.adapter.inbound.web.fileserver.tus.TusRequestParser;
import dev.caskeleton.adapter.outbound.fileserver.platform.autoconfigure.FileserverPlatformSettings;
@@ -15,7 +14,7 @@ import org.springframework.context.annotation.Configuration;
class FileserverProtocolConfiguration {
/**
* tus support objects, contributed only when both this switch and the master switch are on.
* tus support objects, contributed only when both this switch and the capability switch are on.
*
* <p>The nesting is the fix: previously the protocol's own flag was the only condition, so
* enabling tus in a deployment with the Fileserver off produced a controller with no service
@@ -45,16 +44,6 @@ class FileserverProtocolConfiguration {
return new TusRequestParser(tusProperties);
}
@Bean
@ConditionalOnMissingBean
@ConditionalOnProperty(
prefix = FileserverPlatformSettings.PREFIX + ".tus",
name = "enabled",
havingValue = "true")
TusChecksumVerifier fileserverTusChecksumVerifier() {
return new TusChecksumVerifier();
}
/**
* Settings for the experimental draft, which previously had no production binding at all.
*
@@ -30,7 +30,6 @@ import dev.caskeleton.application.fileserver.upload.UploadContentGateway;
import dev.caskeleton.application.fileserver.upload.UploadIdentifierFactory;
import dev.caskeleton.application.fileserver.upload.UploadPolicy;
import dev.caskeleton.application.fileserver.upload.UploadStorageGateway;
import dev.caskeleton.application.transaction.PolicyTransactionPort;
import dev.caskeleton.application.transaction.TransactionPort;
import java.time.Clock;
import org.springframework.beans.factory.ObjectProvider;
@@ -84,7 +83,7 @@ class FileserverUploadServiceConfiguration {
UploadIdentifierFactory identifierFactory,
UploadPolicy uploadPolicy,
ObjectProvider<FileserverMetricsPort> metrics,
PolicyTransactionPort transactions,
TransactionPort transactions,
Clock clock) {
return new DefaultUploadApplicationService(
metadataStore,
@@ -114,7 +113,7 @@ class FileserverUploadServiceConfiguration {
CleanupQueue cleanupQueue,
RecoveryQueue recoveryQueue,
LocalBlockingContentStore store,
PolicyTransactionPort transactions,
TransactionPort transactions,
Clock clock) {
return new DefaultFinalizeUploadService(
metadataStore,
@@ -0,0 +1,101 @@
# Fileserver capability 설정 기본값.
#
# adapter:outbound:support 의 ModuleDefaultsEnvironmentPostProcessor 가 읽는다. 우선순위는 가장 낮아서
# application*.yml, 환경 변수, 시스템 속성이 항상 이긴다. 이 모듈을 빌드에서 빼면 이 파일도 함께
# 빠진다.
spring:
servlet:
multipart:
# app.fileserver-platform.upload.* 와 같은 placeholder 를 쓴다. 두 상한이 따로 있으면 servlet
# container 가 Fileserver 정책이 허용한 업로드를 Fileserver 코드(에러 매핑 포함)가 돌기 전에
# 거절한다. 이 모듈이 없으면 Spring 기본값이 적용된다.
max-file-size: ${APP_FILESERVER_PLATFORM_UPLOAD_MAX_FILE_SIZE:100MB}
max-request-size: ${APP_FILESERVER_PLATFORM_UPLOAD_MAX_REQUEST_SIZE:110MB}
app:
# HTTP Fileserver platform: upload/download/lifecycle routes over HTTP.
#
# While enabled=false none of the detail below is bound: FileserverPlatformAutoConfiguration
# binds the block itself, and it is not processed until the capability switch is true. Unknown keys
# under this prefix are refused rather than ignored.
fileserver-platform:
# true | false — 모듈이 있으면 켜진다. false 로만 끈다.
enabled: ${APP_FILESERVER_PLATFORM_ENABLED:true}
# Writer-lease owner. Must be unique per instance in a multi-instance deployment; the startup
# gate treats the default as single-instance.
instance-id: ${APP_FILESERVER_PLATFORM_INSTANCE_ID:local-node}
default-namespace: ${APP_FILESERVER_PLATFORM_DEFAULT_NAMESPACE:default}
storage:
# Absolute, on its own volume, and never under a web or configuration root. A relative path
# resolves against the process working directory, which differs between a container and a
# test, so it is refused.
root: ${APP_FILESERVER_PLATFORM_STORAGE_ROOT:/var/lib/backend/files}
publish-mode: ${APP_FILESERVER_PLATFORM_STORAGE_PUBLISH_MODE:atomic-move-preferred}
buffer-size: ${APP_FILESERVER_PLATFORM_STORAGE_BUFFER_SIZE:128KB}
forbidden-root-ancestors: ${APP_FILESERVER_PLATFORM_STORAGE_FORBIDDEN_ROOT_ANCESTORS:/app,/etc,/usr/share/nginx/html}
upload:
# Shared with spring.servlet.multipart above through the same placeholder. Two independent
# limits would let the servlet container reject an upload the Fileserver policy allows,
# before any Fileserver code — including its error mapping — ever runs.
max-file-size: ${APP_FILESERVER_PLATFORM_UPLOAD_MAX_FILE_SIZE:100MB}
max-request-size: ${APP_FILESERVER_PLATFORM_UPLOAD_MAX_REQUEST_SIZE:110MB}
initial-reservation: ${APP_FILESERVER_PLATFORM_UPLOAD_INITIAL_RESERVATION:8MB}
max-parts: ${APP_FILESERVER_PLATFORM_UPLOAD_MAX_PARTS:16}
ttl: ${APP_FILESERVER_PLATFORM_UPLOAD_TTL:1h}
reservation-ttl: ${APP_FILESERVER_PLATFORM_UPLOAD_RESERVATION_TTL:24h}
lease-duration: ${APP_FILESERVER_PLATFORM_UPLOAD_LEASE_DURATION:30s}
require-content-length: ${APP_FILESERVER_PLATFORM_UPLOAD_REQUIRE_CONTENT_LENGTH:false}
download:
cache-control: ${APP_FILESERVER_PLATFORM_DOWNLOAD_CACHE_CONTROL:private, no-store}
inline-allowed: ${APP_FILESERVER_PLATFORM_DOWNLOAD_INLINE_ALLOWED:false}
max-ranges: ${APP_FILESERVER_PLATFORM_DOWNLOAD_MAX_RANGES:1}
# Applies to the single-range profile too, so the ceiling is not inert by default.
max-range-bytes: ${APP_FILESERVER_PLATFORM_DOWNLOAD_MAX_RANGE_BYTES:100MB}
zero-copy-enabled: ${APP_FILESERVER_PLATFORM_DOWNLOAD_ZERO_COPY_ENABLED:true}
zero-copy-minimum-bytes: ${APP_FILESERVER_PLATFORM_DOWNLOAD_ZERO_COPY_MINIMUM_BYTES:16MB}
transfer:
core-size: ${APP_FILESERVER_PLATFORM_TRANSFER_CORE_SIZE:8}
max-size: ${APP_FILESERVER_PLATFORM_TRANSFER_MAX_SIZE:32}
queue-capacity: ${APP_FILESERVER_PLATFORM_TRANSFER_QUEUE_CAPACITY:64}
await-seconds: ${APP_FILESERVER_PLATFORM_TRANSFER_AWAIT_SECONDS:300}
security:
# required | role-based | unenforced. `required` has no built-in policy and fails startup
# unless the deployment supplies a FileAccessPolicy bean; `unenforced` is refused under a
# production profile.
access-policy: ${APP_FILESERVER_PLATFORM_SECURITY_ACCESS_POLICY:required}
read-roles: ${APP_FILESERVER_PLATFORM_SECURITY_READ_ROLES:ROLE_FILE_READ}
write-roles: ${APP_FILESERVER_PLATFORM_SECURITY_WRITE_ROLES:ROLE_FILE_WRITE}
admin-roles: ${APP_FILESERVER_PLATFORM_SECURITY_ADMIN_ROLES:ROLE_FILE_ADMIN}
verification:
timeout: ${APP_FILESERVER_PLATFORM_VERIFICATION_TIMEOUT:5s}
require-media-type-verdict: ${APP_FILESERVER_PLATFORM_VERIFICATION_REQUIRE_MEDIA_TYPE_VERDICT:false}
inline-safe-profile: ${APP_FILESERVER_PLATFORM_VERIFICATION_INLINE_SAFE_PROFILE:false}
quota:
instance-upload-permits: ${APP_FILESERVER_PLATFORM_QUOTA_INSTANCE_UPLOAD_PERMITS:16}
scope-upload-permits: ${APP_FILESERVER_PLATFORM_QUOTA_SCOPE_UPLOAD_PERMITS:4}
direct-download-permits: ${APP_FILESERVER_PLATFORM_QUOTA_DIRECT_DOWNLOAD_PERMITS:64}
soft-high-water: ${APP_FILESERVER_PLATFORM_QUOTA_SOFT_HIGH_WATER:0.70}
hard-high-water: ${APP_FILESERVER_PLATFORM_QUOTA_HARD_HIGH_WATER:0.85}
admin:
enabled: ${APP_FILESERVER_PLATFORM_ADMIN_ENABLED:false}
orphan-minimum-age: ${APP_FILESERVER_PLATFORM_ADMIN_ORPHAN_MINIMUM_AGE:1h}
cleanup:
enabled: ${APP_FILESERVER_PLATFORM_CLEANUP_ENABLED:false}
interval: ${APP_FILESERVER_PLATFORM_CLEANUP_INTERVAL:60s}
max-items: ${APP_FILESERVER_PLATFORM_CLEANUP_MAX_ITEMS:100}
max-bytes: ${APP_FILESERVER_PLATFORM_CLEANUP_MAX_BYTES:1GB}
retry-backoff: ${APP_FILESERVER_PLATFORM_CLEANUP_RETRY_BACKOFF:5m}
tus:
enabled: ${APP_FILESERVER_PLATFORM_TUS_ENABLED:false}
httpbis-draft12:
# Unratified protocol; the contract can change without notice.
enabled: ${APP_FILESERVER_PLATFORM_HTTPBIS_DRAFT12_ENABLED:false}
nginx:
enabled: ${APP_FILESERVER_PLATFORM_NGINX_ENABLED:false}
internal-prefix: ${APP_FILESERVER_PLATFORM_NGINX_INTERNAL_PREFIX:/__files/}
object-suffix: ${APP_FILESERVER_PLATFORM_NGINX_OBJECT_SUFFIX:.bin}
minimum-size: ${APP_FILESERVER_PLATFORM_NGINX_MINIMUM_SIZE:16MB}
observability:
metrics-enabled: ${APP_FILESERVER_PLATFORM_OBSERVABILITY_METRICS_ENABLED:true}
# Secret. Keyed HMAC over file identifiers; an unkeyed digest of an enumerable id is
# reversible, so startup fails while metrics are on and this is blank.
fingerprint-key: ${APP_FILESERVER_PLATFORM_OBSERVABILITY_FINGERPRINT_KEY:}
@@ -11,9 +11,7 @@ import dev.caskeleton.application.fileserver.cleanup.QuotaReclaimGateway;
import dev.caskeleton.application.fileserver.recovery.RecoveryQueue;
import dev.caskeleton.application.fileserver.recovery.StagingUploadLocator;
import dev.caskeleton.application.fileserver.upload.QuotaCommitGateway;
import dev.caskeleton.application.transaction.PolicyTransactionPort;
import dev.caskeleton.application.transaction.TransactionRequest;
import dev.caskeleton.application.transaction.TransactionResult;
import dev.caskeleton.application.transaction.TransactionPort;
import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.file.Files;
@@ -52,8 +50,8 @@ public abstract class FileserverAssemblyFixture {
* — what this proves is that the wiring supplies one at all.
*/
@Bean
PolicyTransactionPort transactions() {
return new PolicyTransactionPort() {
TransactionPort transactions() {
return new TransactionPort() {
@Override
public <T> T inWrite(java.util.function.Supplier<T> action) {
return action.get();
@@ -73,12 +71,6 @@ public abstract class FileserverAssemblyFixture {
public <T> T inNew(java.util.function.Supplier<T> action) {
return action.get();
}
@Override
public <T> TransactionResult<T> inTransaction(
TransactionRequest request, java.util.function.Supplier<T> action) {
return new TransactionResult.Committed<>(action.get(), request.operationId());
}
};
}
@@ -0,0 +1,48 @@
package dev.caskeleton.composition.fileserver;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.outbound.support.startup.ModuleDefaultsEnvironmentPostProcessor;
import java.util.Map;
import org.junit.jupiter.api.Test;
import org.springframework.boot.SpringApplication;
import org.springframework.core.env.MapPropertySource;
import org.springframework.core.env.StandardEnvironment;
/**
* The module ships its settings under config/module-defaults, and a deployment's value beats them.
*/
class FileserverModuleDefaultsTest {
@Test
void theShippedDefaultsTurnThePlatformOnAndShareTheUploadCeilingWithTheServlet() {
StandardEnvironment environment = processed(Map.of());
assertThat(environment.getProperty("app.fileserver-platform.enabled")).isEqualTo("true");
assertThat(environment.getProperty("spring.servlet.multipart.max-file-size"))
.isEqualTo(environment.getProperty("app.fileserver-platform.upload.max-file-size"))
.isEqualTo("100MB");
}
@Test
void theEnvironmentVariableTurnsItOffAndMovesBothCeilingsTogether() {
StandardEnvironment environment =
processed(
Map.of(
"APP_FILESERVER_PLATFORM_ENABLED", "false",
"APP_FILESERVER_PLATFORM_UPLOAD_MAX_FILE_SIZE", "5MB"));
assertThat(environment.getProperty("app.fileserver-platform.enabled")).isEqualTo("false");
assertThat(environment.getProperty("spring.servlet.multipart.max-file-size")).isEqualTo("5MB");
assertThat(environment.getProperty("app.fileserver-platform.upload.max-file-size"))
.isEqualTo("5MB");
}
private static StandardEnvironment processed(Map<String, Object> deployment) {
StandardEnvironment environment = new StandardEnvironment();
environment.getPropertySources().addFirst(new MapPropertySource("deployment", deployment));
new ModuleDefaultsEnvironmentPostProcessor()
.postProcessEnvironment(environment, new SpringApplication());
return environment;
}
}
@@ -40,6 +40,7 @@ class FileserverPlatformAutoConfigurationTest {
void disabledCapabilityIgnoresDetailAndSubFeatureSettings() {
runner
.withPropertyValues(
"app.fileserver-platform.enabled=false",
"app.fileserver-platform.upload.ttl=not-a-duration",
"app.fileserver-platform.storage.buffer-size=not-a-size",
"app.fileserver-platform.storage.root=relative/path",
@@ -120,7 +121,7 @@ class FileserverPlatformAutoConfigurationTest {
* the startup log mentions it.
*/
@Test
void aMasterSwitchThatIsNotABooleanDoesNotSilentlyEnableTheCapability() {
void anEnabledValueThatIsNotABooleanDoesNotSilentlyEnableTheCapability() {
runner
.withPropertyValues("app.fileserver-platform.enabled=yes")
.run(
@@ -156,7 +157,6 @@ class FileserverPlatformAutoConfigurationTest {
@Test
void enabledDefaultsAssembleTheExpectedRuntime() {
enabled()
.withPropertyValues("app.fileserver.enabled=false", "app.file-export.enabled=false")
.run(
context -> {
assertThat(context).hasNotFailed();
@@ -185,11 +185,6 @@ class FileserverPlatformAutoConfigurationTest {
assertThat(properties.maxSize()).isEqualTo(32);
assertThat(properties.queueCapacity()).isEqualTo(64);
});
assertThat(context.getEnvironment().getProperty("app.fileserver.enabled"))
.isEqualTo("false");
assertThat(context.getEnvironment().getProperty("app.file-export.enabled"))
.isEqualTo("false");
});
}
@@ -46,7 +46,7 @@ class FileserverPlatformEnvRoundTripTest {
FileserverPlatformSettings bound = bindStrictly(environmentVariables);
assertThat(bound.enabled()).isFalse();
assertThat(bound.enabled()).isTrue();
assertThat(bound.storage().root().isAbsolute()).isTrue();
assertThat(bound.upload().maxRequestSize().toBytes())
.isGreaterThanOrEqualTo(bound.upload().maxFileSize().toBytes());
@@ -54,13 +54,17 @@ class FileserverPlatformEnvRoundTripTest {
assertThat(bound.storage().forbiddenRootAncestors()).isNotEmpty();
}
/** The shipped defaults must be the conservative ones, in the file operators actually copy. */
/**
* The shipped defaults must be the conservative ones, in the file operators actually copy. The
* master switch is on — the capability is present only where a service selected it — and every
* optional surface inside it stays off.
*/
@Test
void theShippedEnvironmentKeepsEveryOptionalSurfaceOff() {
Map<String, Object> environmentVariables = declaredPlatformEnvironment();
assertThat(environmentVariables)
.containsEntry("APP_FILESERVER_PLATFORM_ENABLED", "false")
.containsEntry("APP_FILESERVER_PLATFORM_ENABLED", "true")
.containsEntry("APP_FILESERVER_PLATFORM_ADMIN_ENABLED", "false")
.containsEntry("APP_FILESERVER_PLATFORM_CLEANUP_ENABLED", "false")
.containsEntry("APP_FILESERVER_PLATFORM_TUS_ENABLED", "false")
@@ -0,0 +1,62 @@
# composition:notification-platform — 알림 capability
- Module ID: `composition-notification-platform`
- Gradle path: `:composition:notification-platform`
- Package: `dev.caskeleton.composition.notification`
- 테스트: `./gradlew :composition:notification-platform:test --console=plain`
## 제공하는 것
이 모듈 하나를 붙이면 알림 기능 전체가 들어온다.
```
composition:notification-platform
├─ NotificationApplicationCompositionAutoConfiguration (use case 조립, `enabled` 조건)
│ ├─ NotificationSubmissionConfiguration 접수·예약·취소·조회·템플릿 발행 use case
│ ├─ NotificationDeliveryConfiguration 발송·재조정·lease 회수·ledger 투영·운영자 plane
│ └─ NotificationCallbackConfiguration provider 콜백 수집 + ProviderCallbackIngressBridge
├─ config/module-defaults/notification.yml (설정 기본값, support 로더가 읽음)
├─ adapter:outbound:notification provider(SMTP·SES), 저장 외 런타임, NotificationPlatformAutoConfiguration
└─ adapter:inbound:web-notification POST /notifications, POST /notification-templates,
POST /internal/notification/callbacks/{provider}/{profile}
```
- 조립 순서: 이 모듈의 root는 `NotificationPlatformAutoConfiguration`(outbound leaf) 뒤에 온다
(`afterName`).
- 설정: `config/module-defaults/notification.yml`을 support의 `ModuleDefaultsEnvironmentPostProcessor`가 읽는다. 우선순위는 가장 낮다. 그래서
`application*.yml`, 환경 변수, 시스템 속성이 항상 이긴다. app-bootstrap은 이 파일을 모른다.
- 저장소: 요청·발송·ledger 테이블은 `adapter:outbound:persistence-jpa`에 있다. 그래서
persistence-jpa 줄도 함께 넣어야 하고, `APP_PERSISTENCE_JPA_ENABLED=false`로 끄면 안 된다.
## 추가할 한 줄
```groovy
// app-bootstrap/build.gradle
runtimeOnly project(':adapter:outbound:persistence-jpa') // 알림 저장소
runtimeOnly project(':composition:notification-platform') // 알림
```
기본 조립에는 없다(`app-bootstrap/build.gradle`에 주석 처리된 줄로 있다). 이 줄을 지우면 use case
조립, provider 어댑터, HTTP 엔드포인트, 설정 기본값이 모두 함께 빠진다.
## 켜기와 끄기
모듈이 있으면 켜진다. `ca-skeleton.notification.platform.enabled`(`APP_NOTIFICATION_PLATFORM_ENABLED`,
기본 `true`)를 `false`로 줄 때만 꺼지고, 그때는 아무것도 바인딩하지 않는다. 켜진 상태에서는 아래
"항상" 키가 없으면 기동이 거부된다.
## 필요한 env 키
전체 목록과 타입·기본값은 `docs/registries/env-keys.yaml`의 `APP_NOTIFICATION_*`,
`SPRING_MAIL_*` 행이 SSOT다. 켤 때 실제로 넣어야 하는 것:
| 언제 | 키 |
| --- | --- |
| 항상 | persistence-jpa 줄과 그 연결 env(`APP_DATASOURCE_URL`, `APP_DATASOURCE_USERNAME`, `APP_DATASOURCE_PASSWORD`) |
| 항상 (키 8종과 각 키 id, 32바이트 이상 base64, 서로 달라야 함) | `APP_NOTIFICATION_PLATFORM_{CONTACT_ENCRYPTION,CONTACT_LOOKUP_HMAC,CALLBACK_SIGNING,PROVIDER_CREDENTIAL,PAYLOAD_ENCRYPTION,VAPID_SIGNING,PROVIDER_REQUEST_LOOKUP_HMAC,CALLBACK_FINGERPRINT_HMAC}_KEY`, 같은 이름 + `_ID` |
| SMTP provider | `APP_NOTIFICATION_PLATFORM_SMTP_ENABLED=true`, `APP_NOTIFICATION_PLATFORM_SMTP_SENDER_IDENTITY`, `SPRING_MAIL_HOST`, `SPRING_MAIL_PORT`, `SPRING_MAIL_USERNAME`, `SPRING_MAIL_PASSWORD` |
| SES provider | `APP_NOTIFICATION_PLATFORM_SES_ENABLED=true`, `APP_NOTIFICATION_PLATFORM_SES_SENDER_IDENTITY`, `APP_NOTIFICATION_PLATFORM_SES_ACCESS_KEY_ID`, `APP_NOTIFICATION_PLATFORM_SES_CREDENTIAL_KEY_ID`, `APP_NOTIFICATION_PLATFORM_SES_REGION` |
| provider 콜백 | `APP_NOTIFICATION_PLATFORM_CALLBACKS_ENABLED=true`, SES는 `APP_NOTIFICATION_PLATFORM_SES_ALLOWED_TOPIC_ARNS`, 프록시 뒤라면 `APP_NOTIFICATION_PLATFORM_CALLBACK_TRUSTED_PROXIES` |
나머지(발송 배치 크기, lease, 준비 상태 임계값 등)는 기본값으로 동작한다. 설명은
`docs/notification/configuration-reference.md`.
@@ -0,0 +1,35 @@
plugins {
id 'ca.spring-library'
id 'ca.spring-config'
}
// The Notification capability, selected by one project dependency.
//
// It holds what used to be app-bootstrap's notification assembly: the application use cases that
// open their own transactions, the bridge from the inbound callback endpoint to the outbound
// provider verification, and the capability's shipped settings (config/module-defaults/notification.yml). It depends
// on the outbound adapter and on the HTTP surface, so an application that adds this module gets the
// whole capability and an application that removes it keeps nothing of it.
//
// Not a composition root: it composes one capability and does not run. Same shape as
// :composition:fileserver-platform.
dependencies {
implementation project(':application-core')
implementation project(':application-notification')
implementation project(':adapter:outbound:notification')
implementation project(':adapter:inbound:web-notification')
implementation 'org.springframework.boot:spring-boot-autoconfigure'
implementation 'org.springframework:spring-context'
testImplementation 'org.springframework.boot:spring-boot-starter-test'
// NotificationModuleDefaultsTest reads the shipped file through the loader that serves it at
// runtime (reached there through adapter:outbound:notification). Test scope only.
testImplementation project(':adapter:outbound:support')
}
// NotificationEnvironmentRegistryTest compares the shipped settings with the environment registry.
tasks.named('test') {
inputs.file(new File(rootProject.projectDir.parentFile, 'docs/registries/env-keys.yaml'))
.withPathSensitivity(PathSensitivity.RELATIVE)
}
@@ -0,0 +1,201 @@
# This is a Gradle generated file for dependency locking.
# Manual edits can break the build and are not advised.
# This file is expected to be part of source control.
biz.aQute.bnd:biz.aQute.bnd.annotation:7.1.0=testCompileClasspath
ch.qos.logback:logback-classic:1.5.38=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
ch.qos.logback:logback-core:1.5.38=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
com.ethlo.time:itu:1.14.0=runtimeClasspath,testRuntimeClasspath
com.fasterxml.jackson.core:jackson-annotations:2.21=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
com.fasterxml.jackson.core:jackson-core:2.21.5=runtimeClasspath,testRuntimeClasspath
com.fasterxml.jackson.core:jackson-databind:2.21.5=runtimeClasspath,testRuntimeClasspath
com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.21.5=runtimeClasspath,testRuntimeClasspath
com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.21.5=runtimeClasspath,testRuntimeClasspath
com.fasterxml.jackson:jackson-bom:2.21.5=runtimeClasspath,testRuntimeClasspath
com.fasterxml:classmate:1.7.3=runtimeClasspath,testRuntimeClasspath
com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor
com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor
com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs
com.github.spotbugs:spotbugs:4.10.2=spotbugs
com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs
com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor
com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor
com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor
com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs
com.google.code.gson:gson:2.13.2=spotbugs
com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_annotations:2.38.0=testCompileClasspath
com.google.errorprone:error_prone_annotations:2.41.0=spotbugs
com.google.errorprone:error_prone_annotations:2.47.0=checkstyle
com.google.errorprone:error_prone_annotations:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor
com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.guava:guava:33.5.0-jre=annotationProcessor,testAnnotationProcessor
com.google.guava:guava:33.6.0-jre=checkstyle
com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor
com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins
com.jayway.jsonpath:json-path:2.10.0=testCompileClasspath,testRuntimeClasspath
com.networknt:json-schema-validator:3.0.2=runtimeClasspath,testRuntimeClasspath
com.nimbusds:nimbus-jose-jwt:10.4=runtimeClasspath,testRuntimeClasspath
com.puppycrawl.tools:checkstyle:13.5.0=checkstyle
com.vaadin.external.google:android-json:0.0.20131108.vaadin1=testCompileClasspath,testRuntimeClasspath
commons-beanutils:commons-beanutils:1.11.0=checkstyle
commons-collections:commons-collections:3.2.2=checkstyle
commons-io:commons-io:2.21.0=spotbugs
commons-logging:commons-logging:1.3.6=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
info.picocli:picocli:4.7.7=checkstyle
io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor
io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor
io.micrometer:micrometer-commons:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.micrometer:micrometer-core:1.16.7=runtimeClasspath,testRuntimeClasspath
io.micrometer:micrometer-observation:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
io.swagger.core.v3:swagger-annotations-jakarta:2.2.38=runtimeClasspath,testRuntimeClasspath
io.swagger.core.v3:swagger-core-jakarta:2.2.38=runtimeClasspath,testRuntimeClasspath
io.swagger.core.v3:swagger-models-jakarta:2.2.38=runtimeClasspath,testRuntimeClasspath
jakarta.activation:jakarta.activation-api:2.1.4=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
jakarta.annotation:jakarta.annotation-api:3.0.0=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
jakarta.mail:jakarta.mail-api:2.1.5=runtimeClasspath,testRuntimeClasspath
jakarta.validation:jakarta.validation-api:3.1.1=runtimeClasspath,testRuntimeClasspath
jakarta.xml.bind:jakarta.xml.bind-api:4.0.5=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor
jaxen:jaxen:2.0.6=spotbugs
net.bytebuddy:byte-buddy-agent:1.17.8=testCompileClasspath,testRuntimeClasspath
net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath
net.minidev:accessors-smart:2.6.0=testCompileClasspath,testRuntimeClasspath
net.minidev:json-smart:2.6.0=testCompileClasspath,testRuntimeClasspath
net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs
ognl:ognl:3.3.4=runtimeClasspath,testRuntimeClasspath
org.antlr:antlr4-runtime:4.13.2=checkstyle
org.apache.bcel:bcel:6.12.0=spotbugs
org.apache.commons:commons-lang3:3.20.0=checkstyle,runtimeClasspath,spotbugs,testRuntimeClasspath
org.apache.commons:commons-text:1.15.0=spotbugs
org.apache.commons:commons-text:1.3=checkstyle
org.apache.httpcomponents:httpclient:4.5.13=checkstyle
org.apache.httpcomponents:httpcore:4.4.16=checkstyle
org.apache.logging.log4j:log4j-api:2.25.5=runtimeClasspath,spotbugs,testCompileClasspath,testRuntimeClasspath
org.apache.logging.log4j:log4j-core:2.25.5=spotbugs
org.apache.logging.log4j:log4j-to-slf4j:2.25.5=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.apache.maven.doxia:doxia-core:1.12.0=checkstyle
org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle
org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle
org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle
org.apache.tomcat.embed:tomcat-embed-core:11.0.24=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.apache.tomcat.embed:tomcat-embed-el:11.0.24=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.apache.tomcat.embed:tomcat-embed-websocket:11.0.24=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.apache.xbean:xbean-reflect:3.7=checkstyle
org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath
org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath
org.attoparser:attoparser:2.0.7.RELEASE=runtimeClasspath,testRuntimeClasspath
org.awaitility:awaitility:4.3.0=testCompileClasspath,testRuntimeClasspath
org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle
org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle
org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle
org.codehaus.plexus:plexus-utils:3.3.0=checkstyle
org.dom4j:dom4j:2.2.0=spotbugs
org.eclipse.angus:angus-activation:2.0.3=runtimeClasspath,testRuntimeClasspath
org.eclipse.angus:angus-mail:2.0.5=runtimeClasspath,testRuntimeClasspath
org.hamcrest:hamcrest:3.0=testCompileClasspath,testRuntimeClasspath
org.hdrhistogram:HdrHistogram:2.2.2=runtimeClasspath,testRuntimeClasspath
org.hibernate.validator:hibernate-validator:9.0.1.Final=runtimeClasspath,testRuntimeClasspath
org.javassist:javassist:3.28.0-GA=checkstyle
org.javassist:javassist:3.29.0-GA=runtimeClasspath,testRuntimeClasspath
org.jboss.logging:jboss-logging:3.6.3.Final=runtimeClasspath,testRuntimeClasspath
org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,compileClasspath,runtimeClasspath,testAnnotationProcessor,testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath
org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath
org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath
org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit:junit-bom:6.1.0=spotbugs
org.latencyutils:LatencyUtils:2.0.3=runtimeClasspath,testRuntimeClasspath
org.mockito:mockito-core:5.20.0=mockitoAgent,testCompileClasspath,testRuntimeClasspath
org.mockito:mockito-junit-jupiter:5.20.0=testCompileClasspath,testRuntimeClasspath
org.objenesis:objenesis:3.3=testRuntimeClasspath
org.openapitools:jackson-databind-nullable:0.2.6=runtimeClasspath,testRuntimeClasspath
org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath
org.osgi:org.osgi.annotation.bundle:2.0.0=testCompileClasspath
org.osgi:org.osgi.annotation.versioning:1.1.2=testCompileClasspath
org.osgi:org.osgi.resource:1.0.0=testCompileClasspath
org.osgi:org.osgi.service.serviceloader:1.0.0=testCompileClasspath
org.ow2.asm:asm-analysis:9.10.1=spotbugs
org.ow2.asm:asm-commons:9.10.1=spotbugs
org.ow2.asm:asm-tree:9.10.1=spotbugs
org.ow2.asm:asm-util:9.10.1=spotbugs
org.ow2.asm:asm:9.10.1=spotbugs
org.ow2.asm:asm:9.7.1=testCompileClasspath,testRuntimeClasspath
org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor
org.reflections:reflections:0.10.2=checkstyle
org.skyscreamer:jsonassert:1.5.3=testCompileClasspath,testRuntimeClasspath
org.slf4j:jul-to-slf4j:2.0.18=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.slf4j:slf4j-api:2.0.18=runtimeClasspath,spotbugs,spotbugsSlf4j,testCompileClasspath,testRuntimeClasspath
org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.18=checkstyle
org.springdoc:springdoc-openapi-starter-common:3.0.0=runtimeClasspath,testRuntimeClasspath
org.springdoc:springdoc-openapi-starter-webmvc-api:3.0.0=runtimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-actuator-autoconfigure:4.0.8=runtimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-actuator:4.0.8=runtimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-autoconfigure:4.0.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-configuration-processor:4.0.8=annotationProcessor
org.springframework.boot:spring-boot-health:4.0.8=runtimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-http-converter:4.0.8=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-jackson:4.0.8=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-mail:4.0.8=runtimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-resttestclient:4.0.8=testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-security-oauth2-resource-server:4.0.8=runtimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-security:4.0.8=runtimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-servlet:4.0.8=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-jackson-test:4.0.8=testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-jackson:4.0.8=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-json:4.0.8=runtimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-logging:4.0.8=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-mail:4.0.8=runtimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-oauth2-resource-server:4.0.8=runtimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-security:4.0.8=runtimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-test:4.0.8=testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-tomcat-runtime:4.0.8=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-tomcat:4.0.8=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-validation:4.0.8=runtimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-web:4.0.8=runtimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-webmvc-test:4.0.8=testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter-webmvc:4.0.8=testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-starter:4.0.8=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-test-autoconfigure:4.0.8=testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-test:4.0.8=testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-tomcat:4.0.8=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-validation:4.0.8=runtimeClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-web-server:4.0.8=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-webmvc-test:4.0.8=testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot-webmvc:4.0.8=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.boot:spring-boot:4.0.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework.security:spring-security-config:7.0.7=runtimeClasspath,testRuntimeClasspath
org.springframework.security:spring-security-core:7.0.7=runtimeClasspath,testRuntimeClasspath
org.springframework.security:spring-security-crypto:7.0.7=runtimeClasspath,testRuntimeClasspath
org.springframework.security:spring-security-oauth2-core:7.0.7=runtimeClasspath,testRuntimeClasspath
org.springframework.security:spring-security-oauth2-jose:7.0.7=runtimeClasspath,testRuntimeClasspath
org.springframework.security:spring-security-oauth2-resource-server:7.0.7=runtimeClasspath,testRuntimeClasspath
org.springframework.security:spring-security-web:7.0.7=runtimeClasspath,testRuntimeClasspath
org.springframework.session:spring-session-core:4.0.5=runtimeClasspath,testRuntimeClasspath
org.springframework:spring-aop:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-beans:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-context-support:7.0.9=runtimeClasspath,testRuntimeClasspath
org.springframework:spring-context:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-core:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-expression:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-test:7.0.9=testCompileClasspath,testRuntimeClasspath
org.springframework:spring-web:7.0.9=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.springframework:spring-webmvc:7.0.9=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
org.thymeleaf:thymeleaf:3.1.5.RELEASE=runtimeClasspath,testRuntimeClasspath
org.unbescape:unbescape:1.1.6.RELEASE=runtimeClasspath,testRuntimeClasspath
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
org.xmlunit:xmlunit-core:2.10.4=testCompileClasspath,testRuntimeClasspath
org.yaml:snakeyaml:2.5=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
tools.jackson.core:jackson-core:3.1.5=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
tools.jackson.core:jackson-databind:3.1.5=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
tools.jackson:jackson-bom:3.1.5=runtimeClasspath,testCompileClasspath,testRuntimeClasspath
empty=
@@ -0,0 +1,27 @@
package dev.caskeleton.composition.notification;
import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Import;
/**
* Application-owned Notification orchestration and transaction-bound use-case assembly.
*
* <p>The root holds the capability switch and imports one configuration per concern. It orders
* itself after the outbound leaf's root, whose stores, providers and policies every use case here
* consumes.
*/
@AutoConfiguration(
afterName =
"dev.caskeleton.adapter.outbound.notification.platform.autoconfigure.NotificationPlatformAutoConfiguration")
@ConditionalOnProperty(
prefix = "ca-skeleton.notification.platform",
name = "enabled",
havingValue = "true",
matchIfMissing = true)
@Import({
NotificationSubmissionConfiguration.class,
NotificationDeliveryConfiguration.class,
NotificationCallbackConfiguration.class
})
public class NotificationApplicationCompositionAutoConfiguration {}
@@ -0,0 +1,46 @@
package dev.caskeleton.composition.notification;
import dev.caskeleton.adapter.inbound.web.notification.platform.callback.ProviderCallbackIngress;
import dev.caskeleton.adapter.outbound.notification.platform.callback.ProviderCallbackAdapterRegistry;
import dev.caskeleton.application.notification.platform.callback.CallbackPayloadProtectionPort;
import dev.caskeleton.application.notification.platform.callback.IngestProviderCallbackApplicationUseCase;
import dev.caskeleton.application.notification.platform.callback.ProviderEventLedger;
import dev.caskeleton.application.notification.platform.observation.NotificationMetricsPort;
import dev.caskeleton.application.notification.platform.observation.NotificationSecurityAuditPort;
import dev.caskeleton.application.notification.platform.port.in.IngestProviderCallbackUseCase;
import dev.caskeleton.application.transaction.TransactionPort;
import java.time.Clock;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
/** Provider callbacks: semantic ingestion, and the bridge from raw HTTP to it. */
@Configuration(proxyBeanMethods = false)
class NotificationCallbackConfiguration {
/** Semantic callback ingestion after provider verification has completed. */
@Bean
IngestProviderCallbackApplicationUseCase providerCallbackIngestionService(
ProviderEventLedger ledger,
TransactionPort transactions,
CallbackPayloadProtectionPort payloadProtection,
NotificationMetricsPort metrics,
Clock clock) {
return new IngestProviderCallbackApplicationUseCase(
ledger, transactions, payloadProtection, metrics, clock);
}
/**
* The adapter-to-adapter callback bridge.
*
* <p>Raw HTTP remains in the inbound adapter, provider signature verification remains in the
* outbound provider integration, and only the verified semantic callback crosses the application
* port.
*/
@Bean
ProviderCallbackIngress providerCallbackIngress(
ProviderCallbackAdapterRegistry adapters,
IngestProviderCallbackUseCase ingestion,
NotificationSecurityAuditPort securityAudit) {
return new ProviderCallbackIngressBridge(adapters, ingestion, securityAudit);
}
}
@@ -0,0 +1,181 @@
package dev.caskeleton.composition.notification;
import dev.caskeleton.adapter.outbound.notification.platform.dispatch.NotificationDispatchProperties;
import dev.caskeleton.application.notification.platform.admin.AdminAuthorizationGuard;
import dev.caskeleton.application.notification.platform.admin.AdminOperationStorePort;
import dev.caskeleton.application.notification.platform.admin.DuplicateRiskGuard;
import dev.caskeleton.application.notification.platform.admin.NotificationAdminApplicationService;
import dev.caskeleton.application.notification.platform.admin.NotificationAdminService;
import dev.caskeleton.application.notification.platform.admin.ProviderRuntimeControlPort;
import dev.caskeleton.application.notification.platform.callback.DeliveryAttemptResolverPort;
import dev.caskeleton.application.notification.platform.callback.DeliveryProjectionStorePort;
import dev.caskeleton.application.notification.platform.callback.NotificationSideEffectPort;
import dev.caskeleton.application.notification.platform.callback.ProviderEventLedger;
import dev.caskeleton.application.notification.platform.callback.ProviderEventProjectionService;
import dev.caskeleton.application.notification.platform.callback.ProviderEventProjectorRegistry;
import dev.caskeleton.application.notification.platform.dispatch.DeliveryAttemptFactory;
import dev.caskeleton.application.notification.platform.dispatch.DeliveryAttemptStorePort;
import dev.caskeleton.application.notification.platform.dispatch.DispatchOutcomeRecorder;
import dev.caskeleton.application.notification.platform.dispatch.DispatchPipeline;
import dev.caskeleton.application.notification.platform.dispatch.LeaseRecoveryService;
import dev.caskeleton.application.notification.platform.dispatch.MessageDigestPort;
import dev.caskeleton.application.notification.platform.dispatch.NotificationDispatchService;
import dev.caskeleton.application.notification.platform.dispatch.NotificationIdGeneratorPort;
import dev.caskeleton.application.notification.platform.dispatch.NotificationRequestStorePort;
import dev.caskeleton.application.notification.platform.dispatch.ProviderDispatchGatewayPort;
import dev.caskeleton.application.notification.platform.dispatch.RecipientDeliveryStorePort;
import dev.caskeleton.application.notification.platform.dispatch.RecipientLeaseStorePort;
import dev.caskeleton.application.notification.platform.dispatch.ReconciliationGatewayPort;
import dev.caskeleton.application.notification.platform.dispatch.ReconciliationService;
import dev.caskeleton.application.notification.platform.dispatch.SyntheticEventFingerprint;
import dev.caskeleton.application.notification.platform.dispatch.TemplateRendererRegistry;
import dev.caskeleton.application.notification.platform.observation.NotificationAuditPort;
import dev.caskeleton.application.notification.platform.observation.NotificationMetricsPort;
import dev.caskeleton.application.notification.platform.policy.NotificationRetryPolicy;
import dev.caskeleton.application.notification.platform.policy.RoutingDecisionEngine;
import dev.caskeleton.application.notification.platform.policy.SuppressionStorePort;
import dev.caskeleton.application.transaction.TransactionPort;
import java.time.Clock;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
/**
* Doing the work and correcting it: dispatch, reconciliation, lease recovery, ledger projection and
* the operator plane that redrives and suppresses deliveries.
*
* <p>Here rather than in the notification adapter because each of these opens its own transactions
* around each write, and the adapter must not decide where a unit of work begins (NTF-020).
*/
@Configuration(proxyBeanMethods = false)
class NotificationDeliveryConfiguration {
/** Dispatch orchestration. */
@Bean
NotificationDispatchService notificationDispatchService(
NotificationRequestStorePort requests,
RecipientDeliveryStorePort recipients,
DeliveryAttemptStorePort attempts,
DispatchPipeline pipeline,
RoutingDecisionEngine routing,
NotificationRetryPolicy retryPolicy,
DeliveryAttemptFactory attemptFactory,
DispatchOutcomeRecorder recorder,
ProviderDispatchGatewayPort gateway,
TemplateRendererRegistry renderers,
RecipientLeaseStorePort leases,
TransactionPort transactions,
Clock clock,
NotificationDispatchProperties properties) {
return new NotificationDispatchService(
requests,
recipients,
attempts,
pipeline,
routing,
retryPolicy,
attemptFactory,
recorder,
gateway,
renderers,
leases,
transactions,
clock,
properties.maxAdditionalAttempts(),
properties.estimatedDispatchDuration());
}
/** Provider status correction. */
@Bean
ReconciliationService reconciliationService(
DeliveryAttemptStorePort attempts,
RecipientDeliveryStorePort recipients,
ReconciliationGatewayPort gateway,
ProviderEventLedger ledger,
ProviderEventProjectionService projection,
NotificationAuditPort audit,
NotificationMetricsPort metrics,
SyntheticEventFingerprint syntheticEventFingerprints,
TransactionPort transactions,
Clock clock) {
return new ReconciliationService(
attempts,
recipients,
gateway,
ledger,
projection,
audit,
metrics,
syntheticEventFingerprints,
transactions,
clock);
}
/** Recovers deliveries a dead worker left in flight; the adapter's background worker runs it. */
@Bean
@ConditionalOnMissingBean
LeaseRecoveryService notificationLeaseRecoveryService(
RecipientLeaseStorePort leases,
DeliveryAttemptStorePort attempts,
RecipientDeliveryStorePort deliveries,
ReconciliationService reconciliation,
TransactionPort transactions,
Clock clock,
NotificationDispatchProperties properties) {
return new LeaseRecoveryService(
leases,
attempts,
deliveries,
reconciliation::reconcile,
transactions,
clock,
properties.leaseDuration(),
properties.claimBatchSize());
}
/** Ledger projection. */
@Bean
ProviderEventProjectionService providerEventProjectionService(
ProviderEventLedger ledger,
ProviderEventProjectorRegistry projectors,
DeliveryAttemptResolverPort resolver,
DeliveryProjectionStorePort projections,
NotificationSideEffectPort sideEffects,
TransactionPort transactions,
NotificationMetricsPort metrics) {
return new ProviderEventProjectionService(
ledger, projectors, resolver, projections, sideEffects, transactions, metrics);
}
/** The N4 operator plane. */
@Bean
NotificationAdminService notificationAdminService(
AdminAuthorizationGuard authorization,
DuplicateRiskGuard duplicateRiskGuard,
DeliveryAttemptStorePort attempts,
RecipientDeliveryStorePort recipients,
ReconciliationService reconciliation,
SuppressionStorePort suppressions,
ProviderRuntimeControlPort runtimes,
AdminOperationStorePort operations,
NotificationAuditPort audit,
TransactionPort transactions,
NotificationIdGeneratorPort ids,
MessageDigestPort digests,
Clock clock) {
return new NotificationAdminApplicationService(
authorization,
duplicateRiskGuard,
attempts,
recipients,
reconciliation,
suppressions,
runtimes,
operations,
audit,
transactions,
ids,
digests,
clock);
}
}
@@ -0,0 +1,130 @@
package dev.caskeleton.composition.notification;
import dev.caskeleton.application.notification.platform.dispatch.AcceptNotificationApplicationUseCase;
import dev.caskeleton.application.notification.platform.dispatch.CancelNotificationApplicationUseCase;
import dev.caskeleton.application.notification.platform.dispatch.CanonicalNotificationPlanWriter;
import dev.caskeleton.application.notification.platform.dispatch.ContactPointStorePort;
import dev.caskeleton.application.notification.platform.dispatch.DeliveryAttemptStorePort;
import dev.caskeleton.application.notification.platform.dispatch.GetNotificationApplicationUseCase;
import dev.caskeleton.application.notification.platform.dispatch.MessageDigestPort;
import dev.caskeleton.application.notification.platform.dispatch.NotificationIdGeneratorPort;
import dev.caskeleton.application.notification.platform.dispatch.NotificationRequestStorePort;
import dev.caskeleton.application.notification.platform.dispatch.NotificationSubmissionService;
import dev.caskeleton.application.notification.platform.dispatch.PublishNotificationTemplateApplicationUseCase;
import dev.caskeleton.application.notification.platform.dispatch.RecipientDeliveryStorePort;
import dev.caskeleton.application.notification.platform.dispatch.RequestFingerprint;
import dev.caskeleton.application.notification.platform.dispatch.ScheduleNotificationApplicationUseCase;
import dev.caskeleton.application.notification.platform.dispatch.SubmitNotificationApplicationUseCase;
import dev.caskeleton.application.notification.platform.dispatch.TenantContextPort;
import dev.caskeleton.application.notification.platform.observation.NotificationMetricsPort;
import dev.caskeleton.application.notification.platform.policy.DeduplicationService;
import dev.caskeleton.application.notification.platform.port.in.AcceptNotificationUseCase;
import dev.caskeleton.application.notification.platform.port.in.CancelNotificationUseCase;
import dev.caskeleton.application.notification.platform.port.in.GetNotificationUseCase;
import dev.caskeleton.application.notification.platform.port.in.PublishNotificationTemplateUseCase;
import dev.caskeleton.application.notification.platform.port.in.ScheduleNotificationUseCase;
import dev.caskeleton.application.notification.platform.port.in.SubmitNotificationUseCase;
import dev.caskeleton.application.notification.platform.security.ContactPointProtector;
import dev.caskeleton.application.notification.platform.template.TemplateRegistry;
import dev.caskeleton.application.transaction.TransactionPort;
import java.time.Clock;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
/**
* Accepting work: the submission service and the inbound use cases callers reach it through.
*
* <p>The inbound use cases are separate beans rather than one orchestrator, because a caller
* depending on the whole orchestrator depends on operations it does not use.
*/
@Configuration(proxyBeanMethods = false)
class NotificationSubmissionConfiguration {
/** N2 orchestration. */
@Bean
NotificationSubmissionService notificationSubmissionService(
NotificationRequestStorePort requests,
RecipientDeliveryStorePort recipients,
DeliveryAttemptStorePort attempts,
TemplateRegistry templates,
RequestFingerprint fingerprints,
CanonicalNotificationPlanWriter writer,
TransactionPort transactions,
TenantContextPort tenants,
DeduplicationService deduplication,
NotificationMetricsPort metrics,
Clock clock) {
return new NotificationSubmissionService(
requests,
recipients,
attempts,
templates,
fingerprints,
writer,
transactions,
tenants,
deduplication,
metrics,
clock);
}
/**
* The transport-facing entry point: accept by address (NTF-INT-008).
*
* <p>Separate from {@code submitNotificationUseCase}, which it delegates to. That one takes a
* plan whose recipients reference contact points already in the directory; this one takes an
* address, registers or reuses the contact point, and builds the plan. Without it the platform is
* reachable only by a caller that already holds contact point ids — and the platform ships no way
* to obtain one, so it was reachable by nobody.
*/
@Bean
AcceptNotificationUseCase acceptNotificationUseCase(
SubmitNotificationUseCase submit,
ContactPointStorePort contactPoints,
ContactPointProtector protector,
TenantContextPort tenants,
NotificationIdGeneratorPort ids,
RequestFingerprint fingerprints,
TransactionPort transactions,
Clock clock) {
return new AcceptNotificationApplicationUseCase(
submit, contactPoints, protector, tenants, ids, fingerprints, transactions, clock);
}
/**
* Publishing a template version.
*
* <p>A submission pins a template id and version and the platform refuses one it cannot resolve,
* so a deployment with no published template can accept nothing. {@code TemplateRegistry.publish}
* existed throughout and was called by no application code and no transport.
*/
@Bean
PublishNotificationTemplateUseCase publishNotificationTemplateUseCase(
TemplateRegistry templates, MessageDigestPort digests, TransactionPort transactions) {
return new PublishNotificationTemplateApplicationUseCase(templates, digests, transactions);
}
@Bean
SubmitNotificationUseCase submitNotificationUseCase(
NotificationSubmissionService service, TransactionPort transactions) {
return new SubmitNotificationApplicationUseCase(service, transactions);
}
@Bean
ScheduleNotificationUseCase scheduleNotificationUseCase(
NotificationSubmissionService service, TransactionPort transactions) {
return new ScheduleNotificationApplicationUseCase(service, transactions);
}
@Bean
CancelNotificationUseCase cancelNotificationUseCase(
NotificationSubmissionService service, TransactionPort transactions) {
return new CancelNotificationApplicationUseCase(service, transactions);
}
@Bean
GetNotificationUseCase getNotificationUseCase(
NotificationSubmissionService service, TransactionPort transactions) {
return new GetNotificationApplicationUseCase(service, transactions);
}
}
@@ -0,0 +1,95 @@
package dev.caskeleton.composition.notification;
import dev.caskeleton.adapter.inbound.web.notification.platform.callback.ProviderCallbackHttpRequest;
import dev.caskeleton.adapter.inbound.web.notification.platform.callback.ProviderCallbackIngress;
import dev.caskeleton.adapter.outbound.notification.platform.callback.CallbackLimits;
import dev.caskeleton.adapter.outbound.notification.platform.callback.CallbackVerificationResult;
import dev.caskeleton.adapter.outbound.notification.platform.callback.ProviderCallbackAdapter;
import dev.caskeleton.adapter.outbound.notification.platform.callback.ProviderCallbackAdapterRegistry;
import dev.caskeleton.adapter.outbound.notification.platform.callback.ProviderCallbackVerificationRequest;
import dev.caskeleton.application.notification.platform.api.CallbackIngestionResult;
import dev.caskeleton.application.notification.platform.api.error.CallbackValidationException;
import dev.caskeleton.application.notification.platform.api.error.FailureCategory;
import dev.caskeleton.application.notification.platform.api.error.NotificationFailureCode;
import dev.caskeleton.application.notification.platform.api.error.NotificationFailureDescriptor;
import dev.caskeleton.application.notification.platform.observation.NotificationSecurityAuditPort;
import dev.caskeleton.application.notification.platform.port.in.IngestProviderCallbackCommand;
import dev.caskeleton.application.notification.platform.port.in.IngestProviderCallbackUseCase;
import java.util.Objects;
/**
* Composition-only bridge from raw inbound HTTP to provider verification and semantic ingestion.
*
* <p>This class is intentionally in the capability's composition module. The inbound web adapter
* must not depend on the outbound notification adapter, and the outbound adapter must not depend on
* the web transport. This module is the one place allowed to know both and connect them.
*/
final class ProviderCallbackIngressBridge implements ProviderCallbackIngress {
private final ProviderCallbackAdapterRegistry adapters;
private final IngestProviderCallbackUseCase ingestion;
private final NotificationSecurityAuditPort securityAudit;
ProviderCallbackIngressBridge(
ProviderCallbackAdapterRegistry adapters,
IngestProviderCallbackUseCase ingestion,
NotificationSecurityAuditPort securityAudit) {
this.adapters = Objects.requireNonNull(adapters, "adapters");
this.ingestion = Objects.requireNonNull(ingestion, "ingestion");
this.securityAudit = Objects.requireNonNull(securityAudit, "securityAudit");
}
@Override
public CallbackIngestionResult ingest(ProviderCallbackHttpRequest request) {
Objects.requireNonNull(request, "request");
CallbackLimits limits = adapters.limitsFor(request.providerProfileId());
if (request.bodyLength() > limits.maxBodyBytes()) {
securityAudit.callbackRejectedByLimit(request.providerProfileId(), "BODY_TOO_LARGE");
throw rejected(NotificationFailureCode.CALLBACK_PAYLOAD_REJECTED);
}
if (!limits.acceptsContentType(request.contentType().orElse(null))) {
securityAudit.callbackRejectedByLimit(request.providerProfileId(), "CONTENT_TYPE_REJECTED");
throw rejected(NotificationFailureCode.CALLBACK_PAYLOAD_REJECTED);
}
ProviderCallbackAdapter adapter = adapters.require(request.providerProfileId());
if (!adapter.providerId().equals(request.providerId())) {
securityAudit.callbackRejectedByLimit(
request.providerProfileId(), "PROVIDER_PROFILE_MISMATCH");
throw rejected(NotificationFailureCode.CALLBACK_PAYLOAD_REJECTED);
}
ProviderCallbackVerificationRequest verificationRequest =
new ProviderCallbackVerificationRequest(
request.providerId(),
request.providerProfileId(),
request.externalUrl(),
request.httpMethod(),
request.contentType(),
request.headers(),
request.body(),
request.receivedAt());
CallbackVerificationResult verification = adapter.verify(verificationRequest);
if (!verification.valid()) {
securityAudit.callbackSignatureRejected(
request.providerProfileId(), verification.reasonCode());
throw rejected(NotificationFailureCode.CALLBACK_SIGNATURE_INVALID);
}
var verified = verification.verifiedCallback().orElseThrow();
return ingestion.handle(
new IngestProviderCallbackCommand(
request.providerId(),
request.providerProfileId(),
adapter.normalize(verified),
request.body()));
}
private static CallbackValidationException rejected(String code) {
return new CallbackValidationException(
NotificationFailureDescriptor.preDispatch(
code, FailureCategory.CALLBACK_VALIDATION_FAILURE));
}
}
@@ -0,0 +1 @@
dev.caskeleton.composition.notification.NotificationApplicationCompositionAutoConfiguration
@@ -0,0 +1,182 @@
# 알림 전송 플랫폼과 R0 레거시 제공자 선택. 두 트리가 한 파일에 있는 것은 의도다 — 운영자가 '알림'을 찾을 때 한 곳만 보면 된다.
#
# composition:notification-platform 모듈이 싣고, 이 모듈의 의존성으로 함께 오는 support 의 로더가 읽는다
# (adapter:outbound:support 의 ModuleDefaultsEnvironmentPostProcessor). app-bootstrap 의 application.yml 은 이 파일을 모른다 —
# 모듈 한 줄을 빼면 이 설정도 함께 사라진다. 이 파일의 값은 우선순위가 가장 낮다(application.yml,
# application-{profile}.yml, 환경 변수보다 낮음). 배포별 오버라이드는 그대로 우선한다.
#
# The platform is on while this module is present, like every capability: selecting the module is
# the decision to run it. On needs the notification schema (the persistence-jpa module), the eight
# keys under secrets, and — in SERVING mode — at least one assembled provider profile; see
# docs/notification/configuration-reference.md. Off (APP_NOTIFICATION_PLATFORM_ENABLED=false) means
# no provider runtime, schema activation check, scheduler thread, notification secret or Spring Boot
# mail auto-configuration is required.
ca-skeleton:
notification:
platform:
# The capability switch. False binds nothing at all.
enabled: ${APP_NOTIFICATION_PLATFORM_ENABLED:true}
# SERVING | INGEST_ONLY. SERVING refuses to start without a working provider; INGEST_ONLY
# stores requests and does not dispatch, which is the shape a migration or a drain wants.
mode: ${APP_NOTIFICATION_PLATFORM_MODE:SERVING}
dispatch:
claim-batch-size: ${APP_NOTIFICATION_PLATFORM_CLAIM_BATCH_SIZE:50}
# The lease must outlast a provider call plus its timeout, or a live worker's delivery is
# claimed by a second one while the first is still waiting on the provider.
lease-duration: ${APP_NOTIFICATION_PLATFORM_LEASE_DURATION:2m}
poll-interval: ${APP_NOTIFICATION_PLATFORM_POLL_INTERVAL:1s}
max-global-concurrency: ${APP_NOTIFICATION_PLATFORM_MAX_CONCURRENCY:64}
max-additional-attempts: ${APP_NOTIFICATION_PLATFORM_MAX_ADDITIONAL_ATTEMPTS:4}
estimated-dispatch-duration: ${APP_NOTIFICATION_PLATFORM_ESTIMATED_DISPATCH_DURATION:2s}
max-queue-age: ${APP_NOTIFICATION_PLATFORM_MAX_QUEUE_AGE:24h}
# Must fit within the deployment's pod termination grace; workers use this exact bound.
shutdown-grace: ${APP_NOTIFICATION_PLATFORM_SHUTDOWN_GRACE:20s}
# An ambiguous attempt means the request reached the provider and the outcome could not be
# read. Falling back would risk sending the same notification twice, so it is off.
allow-ambiguous-fallback: ${APP_NOTIFICATION_PLATFORM_ALLOW_AMBIGUOUS_FALLBACK:false}
# Readiness is deployment-specific: throughput and operational SLOs determine what backlog
# is acceptable. These defaults preserve the original behavior but are no longer hard-coded.
serving-thresholds:
max-backlog-depth: ${APP_NOTIFICATION_PLATFORM_MAX_BACKLOG_DEPTH:100000}
max-oldest-due-age: ${APP_NOTIFICATION_PLATFORM_MAX_OLDEST_DUE_AGE:10m}
max-stuck-leases: ${APP_NOTIFICATION_PLATFORM_MAX_STUCK_LEASES:50}
max-pending-projections: ${APP_NOTIFICATION_PLATFORM_MAX_PENDING_PROJECTIONS:50000}
max-failed-projections: ${APP_NOTIFICATION_PLATFORM_MAX_FAILED_PROJECTIONS:1000}
max-oldest-pending-projection-age: ${APP_NOTIFICATION_PLATFORM_MAX_OLDEST_PENDING_PROJECTION_AGE:15m}
max-oldest-reconciliation-age: ${APP_NOTIFICATION_PLATFORM_MAX_OLDEST_RECONCILIATION_AGE:30m}
callbacks:
enabled: ${APP_NOTIFICATION_PLATFORM_CALLBACKS_ENABLED:false}
# Ceiling is 65508 = the ciphertext column minus the AES-GCM nonce and tag. A larger value
# is refused at binding rather than at the database, after the callback was acknowledged.
max-body-bytes: ${APP_NOTIFICATION_PLATFORM_CALLBACK_MAX_BODY_BYTES:65508}
replay-skew: ${APP_NOTIFICATION_PLATFORM_CALLBACK_REPLAY_SKEW:5m}
# Peers whose Forwarded/X-Forwarded-* headers may be believed when reconstructing the URL a
# provider signed. Empty by default, and that is the safe default rather than the convenient
# one: with no entry the resolver uses what the container observed, so no caller can choose
# the URL its own signature is checked against. A deployment behind a load balancer lists its
# proxies here.
trusted-proxies: ${APP_NOTIFICATION_PLATFORM_CALLBACK_TRUSTED_PROXIES:}
# Provider profiles, keyed by profile id. None by default: an empty map with mode=SERVING is
# refused at startup, which is the intended outcome for "enabled but not configured".
#
# A profile looks like this — copy it under a profile id of your own and supply the secrets
# through the credential profile, never inline:
#
# providers:
# ses-primary:
# type: SES # APNS | FCM | SES | SMTP | TWILIO | WEB_PUSH | WEBHOOK
# enabled: true
# primary-for-channel: true # exactly one primary per channel
# environment: PRODUCTION
# credential-profile: ses-prod # resolved through SecretMaterialProvider
# timeout: 10s
# max-concurrency: 16
# rate-per-second: 50
# One shipped profile, disabled, because a map cannot be written by an environment variable.
#
# `ca-skeleton` contains a hyphen and an environment variable cannot express one — Spring maps
# `_` to `.`, never to `-` — so every setting in this tree reaches a deployment through an
# APP_ placeholder named here. A provider map with caller-chosen keys has no placeholder to be
# named by, which is why the tree shipped as `providers: {}` and no deployment could add one.
#
# So the template ships the reference family as one profile, off. A deployment that wants a
# different id or a second family declares it in its own YAML; a deployment that wants the
# common case sets APP_NOTIFICATION_PLATFORM_SMTP_ENABLED=true and the relay address below.
#
# Disabled profiles are skipped by assembly before their type is resolved, so this costs a
# deployment that does not want it exactly nothing.
providers:
smtp:
type: SMTP
enabled: ${APP_NOTIFICATION_PLATFORM_SMTP_ENABLED:false}
# Exactly one primary per channel; a second primary for EMAIL fails assembly by name.
primary-for-channel: ${APP_NOTIFICATION_PLATFORM_SMTP_PRIMARY:true}
environment: ${APP_NOTIFICATION_PLATFORM_SMTP_ENVIRONMENT:local}
credential-profile: ${APP_NOTIFICATION_PLATFORM_SMTP_CREDENTIAL_PROFILE:default}
timeout: ${APP_NOTIFICATION_PLATFORM_SMTP_TIMEOUT:10s}
max-concurrency: ${APP_NOTIFICATION_PLATFORM_SMTP_MAX_CONCURRENCY:4}
rate-per-second: ${APP_NOTIFICATION_PLATFORM_SMTP_RATE_PER_SECOND:10}
ses:
type: SES
enabled: ${APP_NOTIFICATION_PLATFORM_SES_ENABLED:false}
primary-for-channel: ${APP_NOTIFICATION_PLATFORM_SES_PRIMARY:false}
environment: ${APP_NOTIFICATION_PLATFORM_SES_ENVIRONMENT:PRODUCTION}
# This is the SecretMaterialProvider key id backing credential generation 1.
credential-profile: ${APP_NOTIFICATION_PLATFORM_SES_CREDENTIAL_KEY_ID:}
timeout: ${APP_NOTIFICATION_PLATFORM_SES_TIMEOUT:10s}
max-concurrency: ${APP_NOTIFICATION_PLATFORM_SES_MAX_CONCURRENCY:8}
rate-per-second: ${APP_NOTIFICATION_PLATFORM_SES_RATE_PER_SECOND:20}
ses:
endpoint: ${APP_NOTIFICATION_PLATFORM_SES_ENDPOINT:https://email.us-east-1.amazonaws.com}
region: ${APP_NOTIFICATION_PLATFORM_SES_REGION:us-east-1}
sender-identity: ${APP_NOTIFICATION_PLATFORM_SES_SENDER_IDENTITY:}
access-key-id: ${APP_NOTIFICATION_PLATFORM_SES_ACCESS_KEY_ID:}
configuration-set: ${APP_NOTIFICATION_PLATFORM_SES_CONFIGURATION_SET:}
# Comma-separated SNS topic ARNs whose SES events this profile accepts. Required once
# callbacks are enabled: a valid SNS signature only proves AWS sent the message, and
# anyone can own a topic.
allowed-topic-arns: ${APP_NOTIFICATION_PLATFORM_SES_ALLOWED_TOPIC_ARNS:}
# Relay address, credentials, TLS and socket timeouts are owned by spring.mail.* and
# validated against the actual JavaMailSender when SMTP is assembled. Keeping a second copy
# here would let validation describe a transport that is not the one sending mail.
smtp:
# example.invalid is reserved by RFC 2606 and resolves nowhere, so a deployment that forgot
# to set one gets a traceable bounce rather than mail apparently from an address it does not
# own.
sender-identity: ${APP_NOTIFICATION_PLATFORM_SMTP_SENDER_IDENTITY:no-reply@example.invalid}
max-concurrency: ${APP_NOTIFICATION_PLATFORM_SMTP_DISPATCH_CONCURRENCY:4}
# ---- Key material -------------------------------------------------------
# Eight purposes, eight keys, each base64 of at least 32 bytes and each distinct 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, so the platform started without the key and found
# out on the first contact point — in production, on a user's notification.
#
# These were bound by nothing until now. The subtree was missing from this file entirely while
# the settings record and its validator existed, so `enabled: true` was an unconditional boot
# failure in every environment and the only way to discover the eight names was to read the
# record. That is the gap this block closes; the empty defaults keep a deployment with the
# platform off from having to supply anything.
#
# Never write a value here. Supply them out of band, per environment.
secrets:
contact-encryption-key: ${APP_NOTIFICATION_PLATFORM_CONTACT_ENCRYPTION_KEY:}
contact-lookup-hmac-key: ${APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY:}
callback-signing-key: ${APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY:}
provider-credential-key: ${APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY:}
payload-encryption-key: ${APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY:}
vapid-signing-key: ${APP_NOTIFICATION_PLATFORM_VAPID_SIGNING_KEY:}
provider-request-lookup-hmac-key: ${APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY:}
callback-fingerprint-hmac-key: ${APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY:}
# The id written into every envelope this key produces, one per purpose, keyed by the
# purpose's own name. Not secret — an id identifies key material without revealing it — but
# required all the same, and with 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.
active-key-ids:
CONTACT_ENCRYPTION: ${APP_NOTIFICATION_PLATFORM_CONTACT_ENCRYPTION_KEY_ID:}
CONTACT_LOOKUP_HMAC: ${APP_NOTIFICATION_PLATFORM_CONTACT_LOOKUP_HMAC_KEY_ID:}
CALLBACK_SIGNING: ${APP_NOTIFICATION_PLATFORM_CALLBACK_SIGNING_KEY_ID:}
PROVIDER_CREDENTIAL: ${APP_NOTIFICATION_PLATFORM_PROVIDER_CREDENTIAL_KEY_ID:}
PAYLOAD_ENCRYPTION: ${APP_NOTIFICATION_PLATFORM_PAYLOAD_ENCRYPTION_KEY_ID:}
VAPID_SIGNING: ${APP_NOTIFICATION_PLATFORM_VAPID_SIGNING_KEY_ID:}
PROVIDER_REQUEST_LOOKUP_HMAC: ${APP_NOTIFICATION_PLATFORM_PROVIDER_REQUEST_LOOKUP_HMAC_KEY_ID:}
CALLBACK_FINGERPRINT_HMAC: ${APP_NOTIFICATION_PLATFORM_CALLBACK_FINGERPRINT_HMAC_KEY_ID:}
# Superseded material, kept readable, grouped by the purpose it served and then by the id
# it was active under — historical-keys.PAYLOAD_ENCRYPTION.payload-2026-01. The purpose is
# not recoverable from an id, and every consumer that resolves a key by id refuses one
# carrying the wrong purpose, so a retired key filed under the wrong heading resolves and
# is then rejected. Unset until a first rotation; a deployment that has never rotated needs
# none. See docs/notification/at-rest-threat-model.md for the rotation sequence.
historical-keys: {}
app:
notification:
# R0 compatibility provider gates. These booleans are the properties the provider
# configurations actually consume; the removed provider-id selectors were never read.
# This is the R0 legacy seam. The delivery platform is the separate
# ca-skeleton.notification.platform tree below.
slack-webhook:
enabled: ${APP_NOTIFICATION_SLACK_WEBHOOK_ENABLED:false}
google-email:
enabled: ${APP_NOTIFICATION_GOOGLE_EMAIL_ENABLED:false}
@@ -0,0 +1,38 @@
package dev.caskeleton.composition.notification;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.inbound.web.notification.platform.callback.ProviderCallbackIngress;
import dev.caskeleton.application.notification.platform.dispatch.NotificationSubmissionService;
import java.util.List;
import org.junit.jupiter.api.Test;
import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.AutoConfigurations;
import org.springframework.boot.context.annotation.ImportCandidates;
import org.springframework.boot.test.context.runner.ApplicationContextRunner;
class NotificationApplicationCompositionAutoConfigurationTest {
@Test
void bootDiscoversTheRootFromThisModule() {
List<String> candidates =
ImportCandidates.load(AutoConfiguration.class, getClass().getClassLoader()).getCandidates();
assertThat(candidates)
.contains(NotificationApplicationCompositionAutoConfiguration.class.getName());
}
@Test
void theRootAssemblesNothingWhileThePlatformIsOff() {
new ApplicationContextRunner()
.withConfiguration(
AutoConfigurations.of(NotificationApplicationCompositionAutoConfiguration.class))
.withPropertyValues("ca-skeleton.notification.platform.enabled=false")
.run(
context ->
assertThat(context)
.hasNotFailed()
.doesNotHaveBean(NotificationSubmissionService.class)
.doesNotHaveBean(ProviderCallbackIngress.class));
}
}
@@ -0,0 +1,71 @@
package dev.caskeleton.composition.notification;
import static org.assertj.core.api.Assertions.assertThat;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Set;
import java.util.TreeSet;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.stream.Stream;
import org.junit.jupiter.api.Test;
/**
* docs/registries/env-keys.yaml registers exactly the notification keys this module's shipped
* settings bind: a registered key nothing reads is a knob that does nothing, and a bound key the
* registry lacks is a deployment input nobody documented. The build declares the registry as an
* input of {@code test}; the shipped settings are already on the test classpath.
*/
class NotificationEnvironmentRegistryTest {
private static final Path MODULE_DEFAULTS = Path.of("src/main/resources/config/module-defaults");
private static final Path REGISTRY = Path.of("../../../docs/registries/env-keys.yaml");
private static final Pattern PLACEHOLDER =
Pattern.compile("\\$\\{(APP_NOTIFICATION_[A-Z0-9_]+)(:[^}]*)?}");
private static final Pattern REGISTERED =
Pattern.compile("^\\s*- name:\\s*((?:APP_NOTIFICATION|SPRING_MAIL)_[A-Z0-9_]+)\\s*$");
/** Spring's own mail keys, required whenever the SMTP provider can be switched on. */
private static final Set<String> SMTP_EXTERNAL_VARIABLES =
Set.of(
"SPRING_MAIL_HOST",
"SPRING_MAIL_PORT",
"SPRING_MAIL_USERNAME",
"SPRING_MAIL_PASSWORD",
"SPRING_MAIL_PROPERTIES_MAIL_SMTP_STARTTLS_ENABLE",
"SPRING_MAIL_PROPERTIES_MAIL_SMTP_STARTTLS_REQUIRED",
"SPRING_MAIL_PROPERTIES_MAIL_SMTP_CONNECTIONTIMEOUT",
"SPRING_MAIL_PROPERTIES_MAIL_SMTP_TIMEOUT",
"SPRING_MAIL_PROPERTIES_MAIL_SMTP_WRITETIMEOUT");
@Test
void registeredNotificationKeysAreExactlyTheBoundOnes() throws IOException {
// given
Set<String> bound = new TreeSet<>();
try (Stream<Path> files = Files.list(MODULE_DEFAULTS)) {
for (Path settings : files.filter(file -> file.toString().endsWith(".yml")).toList()) {
Matcher matcher = PLACEHOLDER.matcher(Files.readString(settings));
while (matcher.find()) {
bound.add(matcher.group(1));
}
}
}
if (bound.contains("APP_NOTIFICATION_PLATFORM_SMTP_ENABLED")) {
bound.addAll(SMTP_EXTERNAL_VARIABLES);
}
// when
Set<String> registered = new TreeSet<>();
for (String line : Files.readAllLines(REGISTRY)) {
Matcher matcher = REGISTERED.matcher(line);
if (matcher.matches()) {
registered.add(matcher.group(1));
}
}
// then
assertThat(registered).isNotEmpty().containsExactlyInAnyOrderElementsOf(bound);
}
}
@@ -0,0 +1,62 @@
package dev.caskeleton.composition.notification;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.outbound.support.startup.ModuleDefaultsEnvironmentPostProcessor;
import java.util.Map;
import org.junit.jupiter.api.Test;
import org.springframework.boot.SpringApplication;
import org.springframework.core.env.MapPropertySource;
import org.springframework.core.env.StandardEnvironment;
/**
* The module ships its settings under config/module-defaults, and a deployment's value beats them.
*/
class NotificationModuleDefaultsTest {
@Test
void theShippedDefaultsTurnThePlatformOnWhileTheModuleIsPresent() {
StandardEnvironment environment = processed(Map.of());
assertThat(environment.getProperty("ca-skeleton.notification.platform.enabled"))
.isEqualTo("true");
assertThat(environment.getProperty("ca-skeleton.notification.platform.mode"))
.isEqualTo("SERVING");
}
@Test
void theEnvironmentVariableReachesTheHyphenatedTreeThroughTheShippedPlaceholder() {
StandardEnvironment environment =
processed(Map.of("APP_NOTIFICATION_PLATFORM_ENABLED", "false"));
assertThat(environment.getProperty("ca-skeleton.notification.platform.enabled"))
.isEqualTo("false");
}
@Test
void aDeploymentValueOutranksTheShippedDefault() {
StandardEnvironment environment =
processed(Map.of("ca-skeleton.notification.platform.mode", "INGEST_ONLY"));
assertThat(environment.getProperty("ca-skeleton.notification.platform.mode"))
.isEqualTo("INGEST_ONLY");
}
@Test
void bothNotificationTreesShipInTheOneFile() {
StandardEnvironment environment = processed(Map.of());
assertThat(environment.getProperty("ca-skeleton.notification.platform.dispatch.lease-duration"))
.isEqualTo("2m");
assertThat(environment.getProperty("app.notification.slack-webhook.enabled"))
.isEqualTo("false");
}
private static StandardEnvironment processed(Map<String, Object> deployment) {
StandardEnvironment environment = new StandardEnvironment();
environment.getPropertySources().addFirst(new MapPropertySource("deployment", deployment));
new ModuleDefaultsEnvironmentPostProcessor()
.postProcessEnvironment(environment, new SpringApplication());
return environment;
}
}
@@ -0,0 +1,281 @@
package dev.caskeleton.composition.notification;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.adapter.inbound.web.notification.platform.callback.ProviderCallbackHttpRequest;
import dev.caskeleton.adapter.outbound.notification.platform.callback.CallbackLimits;
import dev.caskeleton.adapter.outbound.notification.platform.callback.CallbackVerificationResult;
import dev.caskeleton.adapter.outbound.notification.platform.callback.MapProviderCallbackAdapterRegistry;
import dev.caskeleton.adapter.outbound.notification.platform.callback.ProviderCallbackAdapter;
import dev.caskeleton.adapter.outbound.notification.platform.callback.ProviderCallbackAdapterRegistry;
import dev.caskeleton.adapter.outbound.notification.platform.callback.ProviderCallbackVerificationRequest;
import dev.caskeleton.adapter.outbound.notification.platform.callback.VerifiedCallback;
import dev.caskeleton.adapter.outbound.notification.platform.provider.ses.SesCallbackAdapter;
import dev.caskeleton.adapter.outbound.notification.platform.provider.ses.SesEventNormalizer;
import dev.caskeleton.adapter.outbound.notification.platform.provider.ses.SnsSignatureVerifier;
import dev.caskeleton.adapter.outbound.notification.platform.template.NotificationJsonMapper;
import dev.caskeleton.application.notification.platform.api.CallbackIngestionResult;
import dev.caskeleton.application.notification.platform.api.NormalizedEventType;
import dev.caskeleton.application.notification.platform.api.NormalizedProviderEvent;
import dev.caskeleton.application.notification.platform.api.ProviderId;
import dev.caskeleton.application.notification.platform.api.ProviderProfileId;
import dev.caskeleton.application.notification.platform.api.error.CallbackValidationException;
import dev.caskeleton.application.notification.platform.observation.NotificationSecurityAuditPort;
import dev.caskeleton.application.notification.platform.port.in.IngestProviderCallbackCommand;
import dev.caskeleton.application.notification.platform.port.in.IngestProviderCallbackUseCase;
import java.nio.charset.StandardCharsets;
import java.security.KeyPairGenerator;
import java.security.Signature;
import java.time.Duration;
import java.time.Instant;
import java.util.Base64;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.Set;
import org.junit.jupiter.api.Test;
class ProviderCallbackIngressBridgeTest {
private static final ProviderId TWILIO = new ProviderId("twilio");
private static final ProviderProfileId PROFILE = new ProviderProfileId("twilio-primary");
private static final Instant RECEIVED_AT = Instant.parse("2026-09-19T00:00:00Z");
@Test
void providerMismatchIsRejectedBeforeSignatureVerification() {
RecordingAdapter adapter = new RecordingAdapter(new ProviderId("ses"), true);
RecordingAudit audit = new RecordingAudit();
RecordingIngestion ingestion = new RecordingIngestion();
ProviderCallbackIngressBridge bridge = bridge(adapter, ingestion, audit, 1024);
assertThatThrownBy(() -> bridge.ingest(request("application/json", "{}")))
.isInstanceOf(CallbackValidationException.class);
assertThat(adapter.verifications).isZero();
assertThat(audit.limitReasons).containsExactly("PROVIDER_PROFILE_MISMATCH");
assertThat(ingestion.callbacks).isEmpty();
}
@Test
void invalidSignatureIsAuditedAndNeverReachesApplication() {
RecordingAdapter adapter = new RecordingAdapter(TWILIO, false);
RecordingAudit audit = new RecordingAudit();
RecordingIngestion ingestion = new RecordingIngestion();
ProviderCallbackIngressBridge bridge = bridge(adapter, ingestion, audit, 1024);
assertThatThrownBy(() -> bridge.ingest(request("application/json", "{}")))
.isInstanceOf(CallbackValidationException.class);
assertThat(adapter.verifications).isEqualTo(1);
assertThat(audit.signatureReasons).containsExactly("SIGNATURE_MISMATCH");
assertThat(ingestion.callbacks).isEmpty();
}
@Test
void validCallbackCrossesTheApplicationBoundaryAsVerifiedSemanticData() {
RecordingAdapter adapter = new RecordingAdapter(TWILIO, true);
RecordingAudit audit = new RecordingAudit();
RecordingIngestion ingestion = new RecordingIngestion();
ProviderCallbackIngressBridge bridge = bridge(adapter, ingestion, audit, 1024);
byte[] raw = "MessageStatus=delivered".getBytes(StandardCharsets.UTF_8);
CallbackIngestionResult result =
bridge.ingest(
new ProviderCallbackHttpRequest(
TWILIO,
PROFILE,
"https://callback.example/internal/notification/callbacks/twilio/twilio-primary",
"POST",
Optional.of("application/x-www-form-urlencoded"),
Map.of("x-twilio-signature", List.of("signed")),
raw,
RECEIVED_AT));
assertThat(result).isEqualTo(new CallbackIngestionResult(1, 0));
assertThat(ingestion.callbacks).hasSize(1);
IngestProviderCallbackCommand callback = ingestion.callbacks.getFirst();
assertThat(callback.providerId()).isEqualTo(TWILIO);
assertThat(callback.providerProfileId()).isEqualTo(PROFILE);
assertThat(callback.events()).hasSize(1);
assertThat(callback.rawPayload()).isEqualTo(raw);
assertThat(audit.limitReasons).isEmpty();
assertThat(audit.signatureReasons).isEmpty();
}
@Test
void validSesCallbackCrossesTheShippedBridgeThroughTheRealVerifier() throws Exception {
var keyPair = KeyPairGenerator.getInstance("RSA").generateKeyPair();
SnsSignatureVerifier verifier = new SnsSignatureVerifier(certificateUrl -> keyPair.getPublic());
SesCallbackAdapter adapter =
new SesCallbackAdapter(
verifier,
new SesEventNormalizer(),
Set.of("arn:aws:sns:us-east-1:123456789012:notifications"),
Duration.ofMinutes(5));
ProviderProfileId profile = new ProviderProfileId("ses-events");
ProviderId provider = new ProviderId("ses");
Map<String, String> envelope = new LinkedHashMap<>();
envelope.put("Type", "Notification");
envelope.put("MessageId", "sns-message-1");
envelope.put("TopicArn", "arn:aws:sns:us-east-1:123456789012:notifications");
envelope.put("Timestamp", RECEIVED_AT.toString());
envelope.put(
"Message",
"{\"eventType\":\"Delivery\",\"mail\":{\"messageId\":\"ses-request-1\"},"
+ "\"delivery\":{\"timestamp\":\""
+ RECEIVED_AT
+ "\"}}");
envelope.put(
"SigningCertURL", "https://sns.us-east-1.amazonaws.com/SimpleNotificationService-test.pem");
envelope.put("SignatureVersion", "2");
Signature signer = Signature.getInstance("SHA256withRSA");
signer.initSign(keyPair.getPrivate());
signer.update(SnsSignatureVerifier.canonicalString(envelope).getBytes(StandardCharsets.UTF_8));
envelope.put("Signature", Base64.getEncoder().encodeToString(signer.sign()));
byte[] raw = NotificationJsonMapper.mapper().writeValueAsBytes(envelope);
ProviderCallbackAdapterRegistry registry =
new MapProviderCallbackAdapterRegistry(
Map.of(profile, adapter), new CallbackLimits(4_096, Set.of("application/json")));
RecordingAudit audit = new RecordingAudit();
RecordingIngestion ingestion = new RecordingIngestion();
ProviderCallbackIngressBridge bridge =
new ProviderCallbackIngressBridge(registry, ingestion, audit);
CallbackIngestionResult result =
bridge.ingest(
new ProviderCallbackHttpRequest(
provider,
profile,
"https://callback.example/internal/notification/callbacks/ses/ses-events",
"POST",
Optional.of("application/json"),
Map.of(),
raw,
RECEIVED_AT));
assertThat(result).isEqualTo(new CallbackIngestionResult(1, 0));
assertThat(ingestion.callbacks).hasSize(1);
assertThat(ingestion.callbacks.getFirst().providerId()).isEqualTo(provider);
assertThat(ingestion.callbacks.getFirst().events())
.extracting(NormalizedProviderEvent::type)
.containsExactly(NormalizedEventType.DELIVERY_CONFIRMED);
assertThat(audit.signatureReasons).isEmpty();
assertThat(audit.limitReasons).isEmpty();
}
@Test
void rawHttpLimitsAreEnforcedBeforeTheProviderAdapterRuns() {
RecordingAdapter adapter = new RecordingAdapter(TWILIO, true);
RecordingAudit audit = new RecordingAudit();
RecordingIngestion ingestion = new RecordingIngestion();
ProviderCallbackIngressBridge bridge = bridge(adapter, ingestion, audit, 4);
assertThatThrownBy(() -> bridge.ingest(request("application/json", "12345")))
.isInstanceOf(CallbackValidationException.class);
assertThat(adapter.verifications).isZero();
assertThat(audit.limitReasons).containsExactly("BODY_TOO_LARGE");
}
private static ProviderCallbackIngressBridge bridge(
RecordingAdapter adapter,
RecordingIngestion ingestion,
RecordingAudit audit,
long maxBodyBytes) {
ProviderCallbackAdapterRegistry registry =
new ProviderCallbackAdapterRegistry() {
@Override
public ProviderCallbackAdapter require(ProviderProfileId profileId) {
return adapter;
}
@Override
public CallbackLimits limitsFor(ProviderProfileId profileId) {
return new CallbackLimits(
maxBodyBytes, Set.of("application/json", "application/x-www-form-urlencoded"));
}
};
return new ProviderCallbackIngressBridge(registry, ingestion, audit);
}
private static ProviderCallbackHttpRequest request(String contentType, String body) {
return new ProviderCallbackHttpRequest(
TWILIO,
PROFILE,
"https://callback.example/internal/notification/callbacks/twilio/twilio-primary",
"POST",
Optional.of(contentType),
Map.of(),
body.getBytes(StandardCharsets.UTF_8),
RECEIVED_AT);
}
private static final class RecordingAdapter implements ProviderCallbackAdapter {
private final ProviderId providerId;
private final boolean valid;
private int verifications;
private RecordingAdapter(ProviderId providerId, boolean valid) {
this.providerId = providerId;
this.valid = valid;
}
@Override
public ProviderId providerId() {
return providerId;
}
@Override
public CallbackVerificationResult verify(ProviderCallbackVerificationRequest request) {
verifications++;
return valid
? CallbackVerificationResult.valid(new VerifiedCallback(request, Map.of()))
: CallbackVerificationResult.invalid("SIGNATURE_MISMATCH");
}
@Override
public List<NormalizedProviderEvent> normalize(VerifiedCallback callback) {
return List.of(
new NormalizedProviderEvent(
NormalizedEventType.DELIVERY_CONFIRMED,
"delivered",
Optional.of("event-1"),
Optional.of("request-1"),
Optional.of(RECEIVED_AT),
Map.of()));
}
}
private static final class RecordingIngestion implements IngestProviderCallbackUseCase {
private final List<IngestProviderCallbackCommand> callbacks = new java.util.ArrayList<>();
@Override
public CallbackIngestionResult handle(IngestProviderCallbackCommand command) {
callbacks.add(command);
return new CallbackIngestionResult(1, 0);
}
}
private static final class RecordingAudit implements NotificationSecurityAuditPort {
private final List<String> signatureReasons = new java.util.ArrayList<>();
private final List<String> limitReasons = new java.util.ArrayList<>();
@Override
public void callbackSignatureRejected(ProviderProfileId profileId, String reasonCode) {
signatureReasons.add(reasonCode);
}
@Override
public void callbackRejectedByLimit(ProviderProfileId profileId, String reasonCode) {
limitReasons.add(reasonCode);
}
}
}