docs: 옮기거나 지운 타입·샘플·플랫폼을 가리키던 안내를 지금 이름으로 고친다

문제: 모듈 README·AGENTS·매뉴얼·Javadoc이 옮기거나 이름을 바꾼 타입,
지운 샘플, 다른 repo로 옮긴 플랫폼을 그대로 가리켰다.
- 옮기거나 바꾼 타입: OutboxConfig(지금 :composition:outbox-relay의
  OutboxRelayAutoConfiguration), IdempotencyProviderSelectionConfig(지금
  :composition:idempotency의 IdempotencyAutoConfiguration),
  TracingProperties·GraphQlPlatformProperties(지금 *Settings), SecretSource
  (지금 application-core SecretSourcePort), JsonNullableModule(지금
  JsonNullableJackson3Module), PeriodTest·OutboxEventIdFactory(샘플과 함께
  지움).
- 지운 샘플: SampleDemoProfilesStartupSystemTest, 「sample 테스트」,
  IdempotencyAutoConfiguration·ManagementSecurityConfig Javadoc의 샘플.
- 옮긴 플랫폼: graphql AGENTS·README가 messaging 플랫폼과 「두 패턴 공존」을
  적었지만 그 플랫폼은 2026-11-08 messaging-library로 옮겼다. gRPC 문서는
  grpc-library로 옮긴 플랫폼을 「vendored」·「벤더 starter」로 불렀다.
- leaf CLAUDE.md를 가리키던 곳(지금 AGENTS.md), 복사한 숫자(httpclient
  java 파일 수, graphql systemTest 수), manual 06의 registry 머리말 옛 영어 인용.

고른 방법: 문장이 가리키는 대상만 지금 이름으로 바꾼다. 동작 설명은 그대로
둔다. 숫자는 지운다(레지스트리·빌드가 정한다).

검증:
- 노트북: check-docs.py rc=0. check-work-docs.py는 main의 operate.md 151줄
  때문에만 rc=1.
- desktop(--no-build-cache, 트리 310eb524): 이 문서들을 읽는 시험
  (:app-bootstrap:documentContractTest, repositoryContractTest —
  DeveloperExperienceContractTest 포함, MongoNamespaceContractTest,
  AwsQualificationClaimHonestyTest)과 Javadoc을 고친 두 leaf의
  compileJava·spotlessCheck. 134건 실패 0, skip 1.
This commit is contained in:
DongHyeonka
2026-11-13 03:23:03 +09:00
parent a7e38c1049
commit f2d2267e2e
17 changed files with 40 additions and 46 deletions
+1 -1
View File
@@ -410,7 +410,7 @@ app:
### 분산 추적
- **`OTEL_EXPORTER_OTLP_ENDPOINT`** — OTLP exporter endpoint. 빈 값 = exporter off(스켈레톤에서 OTel
SEAM 미활성). 값이 있으면 유효한 URL 이어야 하며 기동 시 `TracingProperties` 가 검증한다.
SEAM 미활성). 값이 있으면 유효한 URL 이어야 하며 기동 시 `TracingSettings` 가 검증한다.
- **`APP_TRACING_ENABLED`** — `false` 면 tracing seam 은 꺼지지만, `meta.traceId` 는
`WebMvcRequestIdFilter` 가 W3C `traceparent` 로 여전히 생성한다(D4 disabled-fallback 보장).
- **`APP_TRACING_SAMPLE_RATE`** — per-profile 기본값을 덮어쓰는 샘플 비율. [0.0, 1.0] float.
+2 -2
View File
@@ -55,8 +55,8 @@ gRPC/GraphQL/WebSocket: 같은 ApiErrorCarrier를 자기 status 모양으로
- 템플릿 운영 코드: `OperationalError` + `docs/registries/error-codes.yaml`을 같은 변경에서 고친다.
`ErrorCodeRegistryMappingTest`(app-bootstrap)가 status 일치를 검사한다.
- 서비스 기능 코드: 그 registry에 넣지 않는다(registry 머리말 "Product/fork ApiErrorCode enums own local
registries"). 서비스 자기 registry를 만들고 같은 모양의 대조 테스트를 둔다. 모양은 위
- 서비스 기능 코드: 그 registry에 넣지 않는다(registry 머리말 「제품·fork의 ApiErrorCode enum은 자기 레지스트리·계약을
가진다」). 서비스 자기 registry를 만들고 같은 모양의 대조 테스트를 둔다. 모양은 위
`ErrorCodeRegistryMappingTest`(`src/bootstrap/app/src/test/java/dev/caskeleton/bootstrap/contract/ErrorCodeRegistryMappingTest.java`)다.
## 지금 이해하면 되는 것
+1 -1
View File
@@ -289,7 +289,7 @@ source set에서 태그 `jpa-contract`로 `jpaPlatformContractTest` lane이 돌
케이스 3건이 실패함을 확인했다.
- `OutboxAggregateSequenceContract`는 포트 Javadoc의 세 약속 중 둘을 보지 않았다(RR-01-06). "쓰기
트랜잭션 밖 거부"와 "롤백된 번호는 다시 준다"를 넣었다. fake는 `DirectTransactionPort`를 받으면 같은
규칙으로 동작한다(인자 없이 만들면 예전처럼 트랜잭션을 보지 않는다 — sample 테스트가 쓰는 방식).
규칙으로 동작한다(인자 없이 만들면 예전처럼 트랜잭션을 보지 않는다).
`CacheRegionContract`에는 2^53 위 revision 한 자리 차이 경우를 넣었다. fake가 revision을 double로
비교하게 바꾼 변이가 이제 실패한다(전에는 통과).
+1 -1
View File
@@ -2,7 +2,7 @@
> **범위:** 내보내는 조립은 WebSocket 런타임을 조립하지 않는다. 이 runbook은 `PlatformWebSocketHandler`를 스스로 등록한
> 서비스에 적용한다(`src/adapter/inbound/websocket/README.md` 「라이브러리 API」). STOMP channel의 규칙은 leaf
> `CLAUDE.md`에 있다.
> `AGENTS.md`에 있다.
무엇을 보았는지로 나눴다. 장애 중에 손에 있는 것이 그것이기 때문이다.
+2 -2
View File
@@ -17,7 +17,7 @@
- **모양**: 계약·runbook·매뉴얼·README·Javadoc·실패 메시지가 현재 동작과 다르다.
- **막는 기준**: 동작을 바꾸는 변경은 그 동작을 설명하는 모든 문서를 같은 변경에서 고친다. 대상: `docs/web/http-contract.md`, `docs/registries/`, runbook, 매뉴얼, leaf README·`CLAUDE.md`, Javadoc, 업그레이드 안내. 고친 뒤 옛 표현을 grep으로 찾아 남은 곳을 없앤다.
- **볼 것**: diff가 바꾼 동작의 키워드(오류 코드, 설정 키, 상태 이름)로 `docs/`, `src/**/README.md`, `src/**/CLAUDE.md`를 grep.
- **볼 것**: diff가 바꾼 동작의 키워드(오류 코드, 설정 키, 상태 이름)로 `docs/`, `src/**/README.md`, `src/**/AGENTS.md`를 grep.
- **장치**: 일부만 있다. runbook 숫자와 상수를 비교하는 document-contract lane, runbook SQL을 실 PostgreSQL에서 그대로 실행하는 lane. 나머지는 리뷰가 본다. 이 repo는 문서 전체를 파싱하는 검사를 일부러 두지 않는다(`docs/testing/TESTING_STRATEGY.md` 8절).
### A3. 선언과 실행이 떨어져 있다
@@ -65,7 +65,7 @@
- **모양**: 프로필·환경 이름 하나가 다르면 위험한 기능이 열린다. 허용한 값으로는 실제로 동작하지 않는다.
- **막는 기준**: 위험한 기능(데모 계정, 비밀 검사 면제 등)은 거부 목록이 아니라 허용 목록으로 연다. 허용 목록의 값마다 실제로 그 값으로 동작해야 한다.
- **볼 것**: 프로필·환경 이름 문자열 비교, 허용 값마다 실제로 기동하는 테스트가 있는지.
- **장치**: `SampleDemoProfilesStartupSystemTest`(허용 프로필마다 기동).
- **장치**: 기동 때 profile 값을 검사하는 `RuntimeEnvironmentProfileValidator`와 그 시험. 허용 프로필마다 실제로 기동해 보던 시험은 샘플과 함께 지웠다(2026-11-07).
### A10. 글로만 있는 규칙
+8 -14
View File
@@ -16,21 +16,15 @@ Package root: `dev.caskeleton.adapter.inbound.graphql`.
## 플랫폼 모듈 = sub-package (Gradle 모듈 아님)
GraphQL 플랫폼 설계서는 Stable 16개 + Advanced 12개 "모듈"을 말하지만, 이 구현은 그 28개를 이
leaf 안의 **bounded sub-package** 로 매핑한다(선례: httpclient leaf 가 366개 java 파일을 같은
leaf 안의 **bounded sub-package** 로 매핑한다(선례: httpclient leaf 가 여러 기능 package를 같은
방식으로 담는다). GraphQL 표면은 하나의 인바운드 전송 경계이고, 그 내부 분할을 leaf 정체성
SSOT(`gradle/modules.json`)까지 밀어올리지 않는다는 선택이다.
**이는 레지스트리가 닫혀 있어서가 아니다.** `modules.json` 은 확장 가능하며, 실제로 자매
플랫폼인 messaging 은 **정반대 선택**을 해서 자기 leaf 들을 레지스트리에 개별 등록했다. 개수는
`modules.json` 이 소유하며 여기서 되풀이하지 않는다 — 산문에 적힌 숫자는 leaf 가 하나 추가되는 순간
낡는다. 즉 이 레포에는 두 패턴이 공존한다:
| | 방식 | 경계 강제 |
| --- | --- | --- |
| messaging | 레지스트리에 leaf 등록 | Gradle 의존 게이트 |
| graphql | 단일 leaf 내 sub-package | 아래 ArchUnit 테스트 (전송 경계만) |
어느 쪽으로 통일할지는 **미결 아키텍처 결정**이다.
**이는 레지스트리가 닫혀 있어서가 아니다.** `modules.json` 은 확장 가능하다. 자매 플랫폼 messaging 은
한때 **정반대 선택**을 해서 자기 leaf 들을 레지스트리에 개별 등록했다. 그 플랫폼은 2026-11-08 별도 repo
`messaging-library`로 옮겨 버전으로 받는다(`docs/work/reference/related-repos.md`). 그래서 이 repo 안에는 비교할 다른
패턴이 없다. GraphQL 내부를 leaf로 나누는 일은 레지스트리에 leaf를 더하는 변경이고, 경계 강제는 지금
아래 ArchUnit 테스트(전송 경계만)다.
sub-package 사이의 경계(Stable↔Advanced 방향, 모듈 레코드)를 값으로 선언하던 `moduleboundary/`
모델과 부팅 때마다 컨트롤러를 리플렉션으로 검사하던 `architecture/` 는 2026-09-25 에 삭제했다
@@ -101,7 +95,7 @@ required-class 검사가 이 테스트가 조용히 사라지는 것을 막는
고정한다(`spring-boot-starter-web`·`spring-webmvc`·`spring-webflux`·`tomcat-embed-*` 전부
`testCompileClasspath,testRuntimeClasspath` 만). 템플릿은 servlet 단일 스택이라 실행
프로파일(`execution-profile`)·reactive 런타임 감지·blocking bridge 는 2026-09-25 에 삭제했다.
- `annotationProcessor` 로 `spring-boot-configuration-processor` — `GraphQlPlatformProperties` 가
- `annotationProcessor` 로 `spring-boot-configuration-processor` — `GraphQlPlatformSettings` 가
`@ConfigurationProperties` 이므로 `ca.spring-config` convention plugin이 주는 패리티
게이트가 이 선언을 요구한다.
@@ -157,7 +151,7 @@ health 스키마만 소유한다.
```bash
./gradlew :adapter:inbound:graphql:graphqlStableTest --console=plain # GraphQlTransportBoundaryArchitectureTest만, skip 금지
./gradlew :adapter:inbound:graphql:systemTest --console=plain # 23 tests (실제 HTTP 서버)
./gradlew :adapter:inbound:graphql:systemTest --console=plain # 실제 HTTP 서버
```
`graphqlStableTest` 는 `GraphQlTransportBoundaryArchitectureTest` 가 실행되지 않거나 skip 되면
+6 -7
View File
@@ -127,7 +127,7 @@ gRPC 와 달리 spring-graphql / graphql-java 는 Spring Boot BOM 이 관리한
플랫폼 정책은 `spring.graphql.*` 로 표현할 수 없다 — cost/page 한계, preparsed
캐시 경계, 관측 label 로 허용할 operation 이름은 전부 이 leaf 의 결정이다. 그래서
`GraphQlPlatformProperties` 가 **`app.graphql`** prefix 로 `@ConfigurationProperties` 를
`GraphQlPlatformSettings` 가 **`app.graphql`** prefix 로 `@ConfigurationProperties` 를
바인딩한다(`spring.graphql.platform.*` 이 아니다 — 그 prefix 는 존재한 적이 없다).
```yaml
@@ -180,16 +180,15 @@ composition root 는 이 leaf 를 채택할 때 인증/인가 및 CORS 정책을
(`gradle/modules.json`)에 추가하는 것은 레지스트리·
`settings.gradle` fail-closed 검증·의존 게이트를 동시에 건드리는 변경이다. GraphQL 표면은 하나의
인바운드 전송 경계이므로 그 **내부** 분할을 레포 전역 SSOT 까지 밀어올리지 않기로 하고,
**모듈 = bounded sub-package** 로 매핑했다(선례: httpclient leaf 가 366개 java 파일을 같은 방식으로
**모듈 = bounded sub-package** 로 매핑했다(선례: httpclient leaf 가 여러 기능 package를 같은 방식으로
담는다).
**정직하게 기록해 둘 반례:** 이후 main 에 통합된 자매 플랫폼 messaging 은 정반대로
**자기 leaf 를 레지스트리에 하나씩 등록**했다(지금의 leaf 목록과 수는 레지스트리가 정한다). 즉 레지스트리는 닫혀 있지 않았고,
"확장하면 게이트가 깨진다"는 전제는 과했다. 두 플랫폼이 서로 다른 패턴을 쓰고 있으므로
**어느 쪽으로 통일할지는 미결 아키텍처 결정**이다.
**정직하게 기록해 둘 반례:** 자매 플랫폼 messaging 은 정반대로 **자기 leaf 를 레지스트리에 하나씩
등록**했다. 즉 레지스트리는 닫혀 있지 않았고, "확장하면 게이트가 깨진다"는 전제는 과했다. 그 플랫폼은
2026-11-08 별도 repo `messaging-library`로 옮겼으므로 지금 이 repo에서 두 패턴이 공존하지는 않는다.
sub-package 경계를 값으로 선언하던 `moduleboundary/` 모델(소스 텍스트 스캐너 포함)은
2026-09-25 에 삭제했다. 두 플랫폼 중 어느 패턴으로 통일할지 정할 때 다시 설계한다.
2026-09-25 에 삭제했다. GraphQL 내부를 leaf로 나누기로 정할 때 다시 설계한다.
## 전송 경계 규칙은 빌드 때 ArchUnit 으로 검사한다
+2 -2
View File
@@ -42,8 +42,8 @@ Package root: `dev.caskeleton.adapter.inbound.grpc`.
타입드 `@ConfigurationProperties` 만 두고, 값은 composition-root `application.yml` 에 산다
(모듈별 `yml` 없음). prefix가 `app.grpc`가 아니라 `.server`까지인 이유: 바인딩이
`ignoreUnknownFields = false`라서, 부모 prefix를 쓰면 벤더 starter의 `app.grpc.platform.*`
키가 들어오는 순간 기동이 실패한다(`GrpcSafeActivationTest`).
`ignoreUnknownFields = false`라서, 부모 prefix를 쓰면 `grpc-library` starter를 함께 받은 서비스의
`app.grpc.platform.*` 키가 들어오는 순간 기동이 실패한다(`GrpcSafeActivationTest`).
| key | default | 의미 |
|---|---|---|
+1 -1
View File
@@ -59,7 +59,7 @@
io.grpc 기본값은 메시지 4 MiB, 연결당 동시 호출 무제한, 호출마다 스레드를 늘리는 cached
executor, 서버 deadline 없음, 연결 수명 무제한이다. 어댑터 서버는 이 값을 모두 명시한다.
| 키 (`app.grpc.server.*`) | 기본값 | 같은 값의 출처 (vendored 플랫폼) |
| 키 (`app.grpc.server.*`) | 기본값 | 같은 값의 출처 (`grpc-library` 플랫폼) |
|---|---|---|
| `max-inbound-message-bytes` | 1048576 (1 MiB) | `GrpcTransportLimits.DEFAULT_MAX_MESSAGE_BYTES` |
| `max-inbound-metadata-bytes` | 8192 (8 KiB) | `GrpcTransportLimits.DEFAULT_MAX_METADATA_BYTES` |
+1 -1
View File
@@ -136,7 +136,7 @@ B2)가 이미 inbound 쪽을 덮고, 아래 규칙이 outbound 쪽을 덮는다.
|---|---|---|---|---|
| 문법·모양 | `adapter:inbound:web` 요청 DTO(`@Valid` / `jakarta.validation`) | 요청 모양, 타입, 필수 필드 | `VALIDATION` | ArchUnit 규칙 `VALIDATION_CONSTRAINTS_STAY_AT_WEB_BOUNDARY` |
| 유스케이스 정책 | `application-core` | 인가, aggregate를 가로지르는 정책, 상태 전제 조건 | `AUTHZ` / `CONFLICT` | `BusinessRuleValidationContractTest` |
| 도메인 불변식 | `domain-core` 모델·값 객체 **생성자** | 업무 불변식(예: end ≥ start) | `CONFLICT` / `VALIDATION` | 도메인 단위 시험(예: `PeriodTest`) — 생성자가 유일하고 바뀌지 않는 생성 경로다 |
| 도메인 불변식 | `domain-core` 모델·값 객체 **생성자** | 업무 불변식(예: end ≥ start) | `CONFLICT` / `VALIDATION` | 도메인 단위 시험(생성 명령이 만드는 aggregate의 시험) — 생성자가 유일하고 바뀌지 않는 생성 경로다 |
| 영속 무결성 | `adapter:outbound:persistence-jpa`(번역기는 `feature-persistence-failure-baseline`의 것) | unique / FK / check / serialization | `DATA_INTEGRITY` / `CONFLICT` | `BusinessRuleValidationContractTest` + 누출 시험 |
- **C1 — 검증 애너테이션은 web 경계에 머문다.** `jakarta.validation`(`@NotNull`, `@Valid`, …)은
+1 -1
View File
@@ -469,7 +469,7 @@ commit-aware response wrapper 계약을 구현한다. 또한 이 모듈은 HTML
(/api 없이) 계속 접근 가능하게 유지.
### JacksonNullableConfig
- `JsonNullableModule` 을 Spring 관리 `ObjectMapper` 에 등록. 없으면 PATCH 요청 DTO 의 `JsonNullable<T>`(B2)를
- `JacksonNullableConfig`가 `JsonNullable` 처리기 모듈(`JsonNullableJackson3Module`)을 Spring 관리 `ObjectMapper` 에 등록. 없으면 PATCH 요청 DTO 의 `JsonNullable<T>`(B2)를
Jackson 이 역직렬화하지 못해 absent / explicit-null 구분이 조용히 붕괴된다.
- 스켈레톤 전역 web 관심사(공유 `Patch<T>` 타입과 짝)라 기능 모듈이 아니라 adapter-web 에 위치.
@@ -40,7 +40,7 @@ bean과 함께 Boot의 JDBC·Hibernate·Spring Data JPA·Flyway 자동 설정도
`ModuleDefaultsEnvironmentPostProcessor`가 가장 낮은 우선순위로 읽으므로 애플리케이션 설정과
환경변수가 언제나 이긴다.
outbox **relay**(스케줄러)는 이 모듈이 아니라 합성 루트의 `OutboxConfig`가 조립한다. use case를
outbox **relay**(스케줄러)는 이 모듈이 아니라 조립 모듈 `:composition:outbox-relay`의 `OutboxRelayAutoConfiguration`이 조립한다. use case를
만들고 구동하는 일은 driven adapter의 몫이 아니기 때문이다. 그 설정은 이 모듈이 주는
`OutboxStorePort`와 messaging이 주는 `OutboxMessagePublishPort`가 모두 있을 때만 켜진다.
@@ -217,7 +217,7 @@ Spring Boot 메인 클래스는 `dev.caskeleton.bootstrap` 에 있어서, `@Auto
`app.capabilities.idempotency.provider=postgresql` 일 때만 켜진다
(`autoconfigure/PostgreSqlIdempotencyStoreConfig`). 이 leaf 는 `IdempotencyStorePort` 구현
(`PostgreSqlIdempotencyStore`) 하나만 내놓고, executor 는 app-bootstrap
`IdempotencyProviderSelectionConfig` 가 만든다. V1 JDBC store 와 `jdbc` provider 값은 없다.
조립 모듈 `:composition:idempotency`의 `IdempotencyAutoConfiguration`이 만든다. V1 JDBC store 와 `jdbc` provider 값은 없다.
- **스키마**: 기본 테이블은 primary Flyway(`db/migration/postgresql/V1__idempotency_record.sql`)가,
owner-safe 컬럼은 `db/migration/jpa/idempotency` stream 이 소유한다. 기동 시
+1 -1
View File
@@ -77,7 +77,7 @@ architectureTest)가 강제한다. 나머지는 리뷰 규칙이고, 리뷰가
| 애플리케이션이 가진 기술 저장소(outbox, 멱등성, operation 행) | `<Thing>StorePort` | application 패키지 | `*WritePort`(옛 onboarding fixture, 지움) |
| aggregate가 아니라 projection을 돌려주는 읽기 모델 | `<Thing>QueryPort` | application 패키지. projection만 돌려준다(ArchUnit) | — |
| 그 밖의 outbound 포트 | `<Capability>Port` | application 패키지 | — |
| 서버가 정하는 id 생성 | `<Aggregate>IdFactory extends IdFactory<<Aggregate>Id>` | domain 패키지. id record는 `implements ResourceId<Self>` | `OutboxEventIdFactory`(샘플. event id는 resource id가 아니다) |
| 서버가 정하는 id 생성 | `<Aggregate>IdFactory extends IdFactory<<Aggregate>Id>` | domain 패키지. id record는 `implements ResourceId<Self>` | `DurableOperationIdFactory`(durable operation id는 aggregate의 resource id가 아니라 `IdFactory`를 따르지 않는다) |
| 설정 바인딩 | `*Settings`(운영) 또는 `*Policy`(인가·도메인 정책), ArchUnit이 강제 | 그것을 바인딩하는 leaf | — |
| Throwable | `*Exception`, ArchUnit이 강제 | — | — |
| 포트의 계약 시험 키트 | 포트 소유자의 testFixtures에 둔 추상 `<Port>Contract`. fake의 시험과 각 어댑터의 시험이 상속한다 | testFixtures | 값 타입 시험의 이름이 한때 `*ContractTest`였다. 지금은 `*ValueTypesTest`다 |
+1 -1
View File
@@ -284,7 +284,7 @@ application 계층이 claim·replay·복구 **정책** 을 소유하고, 저장
`LEASE_EXPIRED` 를 받는다. 이 값은 `NOT_OWNER`(기록이 남에게 넘어감)와 다르다: 시작 전이면 아무것도
돌지 않았고 다음 claim 이 넘겨받으며, executor 는 503 `IDEMPOTENCY_UNAVAILABLE`(실행 전 거부)로 답한다.
실행 중이면 주인은 여전히 `complete`·`markFailed` 할 수 있다(RR5-01-02).
- 생성은 app-bootstrap `IdempotencyProviderSelectionConfig` 가 한 번 한다(`IdempotencySettings`:
- 생성은 조립 모듈 `:composition:idempotency`의 `IdempotencyAutoConfiguration`이 한 번 한다(`IdempotencySettings`:
processing lease 30s, replay TTL 24h(최대 72h), failure retention 24h(replay TTL 이상), codec id `json-v2`,
policy revision 2). 유스케이스나 서비스 설정이 직접 만들지 않는다.
- 이 계약은 요청 재생(replay) 근거를 남길 뿐이다. store 와 비즈니스 DB 사이의 exactly-once 를
+8 -7
View File
@@ -85,11 +85,12 @@ README의 "startup" 절에 있다.
시크릿을 어디서 읽을지(env / Vault / 클라우드 시크릿 매니저)를 인터페이스 뒤로 숨기고, 위험한
런타임 설정값은 기동 시점에 막는다.
### SecretSource
- **시크릿 해석을 인터페이스 한 겹 뒤로 숨긴 backend seam 이다.** 시크릿이 필요한 코드는 이
인터페이스에만 의존하고, 실제 백엔드(env / Vault / AWS Secrets Manager / GCP Secret Manager)는
### SecretSourcePort
- **시크릿 해석을 인터페이스 한 겹 뒤로 숨긴 backend seam 이다.** 포트는 application-core
`dev.caskeleton.application.secret`에 있다. 시크릿이 필요한 코드는 이 인터페이스에만 의존하고,
실제 백엔드(env / Vault / AWS Secrets Manager / GCP Secret Manager)는
`SecretSourceFactory`가 설정값으로 고른다. 설정과 구현 선택을 한 factory에 모으는 패턴이다.
백엔드를 추가하는 비용이 "새 `SecretSource` 구현 1개 + `SecretSourceStrategy` enum 값 1개 +
백엔드를 추가하는 비용이 "새 `SecretSourcePort` 구현 1개 + `SecretSourceStrategy` enum 값 1개 +
factory case 1개"로 고정되고, 소비자(`SecretSourceValidator`, 향후 어댑터)는 전혀 손대지 않는다.
- **빈 문자열은 "없음"으로 취급한다.** `resolve`가 blank 값을 `Optional.empty()`로 돌려주지 않으면,
"값은 존재하지만 비어 있는" 시크릿이 존재 검사(presence check)를 통과해 버려 prod 부팅을 막을 수
@@ -98,7 +99,7 @@ README의 "startup" 절에 있다.
### SecretSourceStrategy
- **enum 값 하나가 곧 백엔드 하나라는 확장 규약을 못 박는다.** `app.secret-source.strategy`로
바인딩되며 `ENVIRONMENT`만 기본 제공한다. 미래 백엔드(VAULT, AWS_SECRETS_MANAGER,
GCP_SECRET_MANAGER)는 주석으로만 남겨 두어, 추가 절차가 "enum 값 + `SecretSource` 구현 + factory
GCP_SECRET_MANAGER)는 주석으로만 남겨 두어, 추가 절차가 "enum 값 + `SecretSourcePort` 구현 + factory
case"임을 코드에서 바로 읽히게 했다(rate-limit algorithm enum 패턴과 동일).
### SecretSourceSettings
@@ -108,7 +109,7 @@ README의 "startup" 절에 있다.
### SecretSourceConfig
- **시크릿 백엔드와 그 시작 가드를 composition root 에서만 와이어링한다.** `SecretSourceFactory`로
선택된 `SecretSource`(기본 `ENVIRONMENT`)와, 그것을 통해 필수 시크릿을 검증하는
선택된 `SecretSourcePort` 구현(기본 `ENVIRONMENT`)과, 그것을 통해 필수 시크릿을 검증하는
`SecretSourceValidator`를 빈으로 노출한다. 검증기를 Spring 스테레오타입 없는 일반 클래스로 둔
이유는 단위 테스트 가능성을 지키기 위함이고, 이 config 가 유일한 production 와이어링이다.
- **`RuntimeSafetyConfig`와 일부러 분리했다.** 시크릿 계약은 secrets-config-source-contract 가
@@ -117,7 +118,7 @@ README의 "startup" 절에 있다.
### SecretSourceFactory
- **유일한 확장 지점을 `switch` 하나로 모았다.** 새 백엔드는 `SecretSourceStrategy` 값 +
`SecretSource` 구현 + 이 `switch`의 case 추가로 끝나고 소비자는 바뀌지 않는다.
`SecretSourcePort` 구현 + 이 `switch`의 case 추가로 끝나고 소비자는 바뀌지 않는다.
factory 한곳에 "확장 비용이 어디에 있는가"를 보이게 했다.
### EnvironmentSecretSource
@@ -21,7 +21,7 @@ import org.springframework.core.env.Environment;
* replay TTL, retention, codec id, policy revision — is the same whichever store holds the records,
* so it lives in one {@link IdempotencySettings} record and the executor is built here from it.
* Every composition root that serves idempotent requests takes this module rather than a copy of
* it: the application and the sample build the same executor from the same checks.
* it, so every one builds the same executor from the same checks.
*
* <p>A selected provider must yield exactly one store. None means the provider's module is not on
* the runtime classpath or its switch is off; two means something else registered one (a scan-found
@@ -32,7 +32,7 @@ import org.springframework.security.web.authentication.HttpStatusEntryPoint;
*
* <p>A composition root that deliberately wants another actuator posture declares its own bean
* named {@code actuatorSecurityFilterChain}; this one then steps aside instead of putting two
* chains with the same matcher in front of the same requests. The standalone sample does that.
* chains with the same matcher in front of the same requests.
*/
@AutoConfiguration(
before = {