This commit is contained in:
@@ -3,8 +3,9 @@
|
||||
이 정책을 강제하는 것은
|
||||
[`scripts/ci/trivy-scan.sh`](../scripts/ci/trivy-scan.sh)(pull request workflow의 `done` job, main·nightly
|
||||
workflow의 `vulnerabilities` job, release workflow의 이미지 job이 부른다),
|
||||
[`../.trivyignore.yaml`](../.trivyignore.yaml), CODEOWNERS,
|
||||
[`../renovate.json`](../renovate.json)이다.
|
||||
[`../.trivyignore.yaml`](../.trivyignore.yaml), CODEOWNERS다. [`../renovate.json`](../renovate.json)은 갱신 PR을 만드는
|
||||
설정일 뿐 강제 수단이 아니다. 이 repo를 보는 Renovate 실행기가 지금 Gitea에 없어서, 그 설정은 누가 Renovate를 이 repo에
|
||||
붙일 때부터 쓰인다.
|
||||
|
||||
## 실행 위치와 플랫폼 경계
|
||||
|
||||
@@ -92,7 +93,9 @@ mirror가 살아 있고 최신인지는 운영이 챙길 의존이다. 낡은 mi
|
||||
|
||||
## 의존성 갱신 정책
|
||||
|
||||
Renovate가 저장소에 커밋된 보안 갱신 봇 설정이다. 보안 갱신은 갱신 종류와 상관없이 자동 병합하지 않는다
|
||||
Renovate가 저장소에 커밋된 보안 갱신 봇 설정이다. 실행기가 붙어 있지 않은 동안 갱신은 trivy 실패를 본 관리자가
|
||||
손으로 한다. GitHub vulnerability alert(`vulnerabilityAlerts`)는 GitHub 호스트에서만 있고, 그 밖에서는
|
||||
`osvVulnerabilityAlerts`가 근거다. 보안 갱신은 갱신 종류와 상관없이 자동 병합하지 않는다
|
||||
(`renovate.json`의 `automerge: false`). Renovate는 strict lockfile을 다시 만들지 않는다. 관리자가
|
||||
`./gradlew resolveAndLockAll --write-locks`로 잠금을 다시 만들고, 잠금 diff를 검토해 함께
|
||||
커밋한다. 의존성 선언과 모든 `gradle.lockfile`은 같이 움직이고, `verifyDependencyLocks`는 계속 릴리스를
|
||||
|
||||
+1
-1
@@ -33,7 +33,7 @@
|
||||
| `registries/` | 레지스트리: env 키, 오류 코드, 메트릭, HTTP 헤더, 로그(MDC) 키, 비밀 분류, use case capability, 객체 저장소 준비도. 테스트가 코드와 대조한다 |
|
||||
| `web/` | HTTP wire 계약(`web/http-contract.md`), PATCH·스트리밍 계약, 선택형 web 기능(`web-advanced`), web 장애 대응 |
|
||||
| `architecture/` | 공개 API 표면 스냅숏(`*-api-surface.txt`). API surface 검사가 대조한다 |
|
||||
| `security/` | 기본 공개 경로 스냅숏. `verifyPublicPathSnapshot`이 대조한다 |
|
||||
| `security/` | 공개 경로 스냅숏(`verifyPublicPathSnapshot`이 대조한다)과 요청률 제한을 어디서 거는지(`rate-limiting.md`) |
|
||||
| `observability/` | 구조화 로그 필드 사전 |
|
||||
|
||||
### 영역 운영 문서
|
||||
|
||||
+10
-7
@@ -20,18 +20,21 @@ Checkstyle은 **포매터가 표현할 수 없는 것만** — 네이밍과 몇
|
||||
(`config/checkstyle/checkstyle.xml`). 줄 길이·들여쓰기·import 순서 모듈이 여기에 없는 것은 누락이
|
||||
아니라 포매터와 싸우지 않기 위한 선택이다. Error Prone은 컴파일 시점 버그 패턴을 담당한다.
|
||||
|
||||
무엇이 어느 단계에서 도는지의 정본은 `docs/work/reference/gates.md` 1절과 루트 `build.gradle`의 단계 태스크다. 아래 표는
|
||||
태스크 하나하나가 하는 일이다.
|
||||
|
||||
| 게이트 | 하는 일 |
|
||||
| --- | --- |
|
||||
| `architectureCheck` | Clean Architecture 의존 방향, domain-core·shared-contract·application-* 순수성, Git에 실리지 않는 source package, ArchUnit을 검사 |
|
||||
| `qualityCheck` | 모든 leaf의 SpotBugs + FindSecBugs를 실행 |
|
||||
| `configContractCheck` | `:app-bootstrap:verifyEnvKeys`로 환경 설정 계약을 검사 |
|
||||
| `qualificationCheck` | 전체 기동(system) 레인과 보조 source set Checkstyle을 실행 |
|
||||
| `qualificationCheck` | 전체 기동(system) 레인(`systemTestCheck`), 보조 source set Checkstyle, 시험 품질 검사(`testQualityCheck`)를 실행 |
|
||||
| `integrationCheck` | 선언된 strict integration lane을 실행. 대부분 container runtime이 필요. 입력이 필요한 lane(Redis topology: `-Predis.topology.mode`, AWS: 보호 자격 증명 env)은 입력이 없으면 빠지고 집계가 그 이유를 출력 |
|
||||
| `performanceCheck` | 선언된 strict performance lane(부하·종료·pool·자원 상한)을 실행. 실서버·container가 필요. 상한은 매번 단언하고 끄는 속성이 없다(`-Pperformance.assertions.enabled`가 `true`가 아니면 실패, skip된 테스트가 있어도 실패). `main.yml` `performance` job이 nightly에 다른 무거운 job 뒤에서 같은 명령으로 돌림 |
|
||||
| `verifyStrictLaneStages` | `--dry-run` 전용. `explicitOnly`가 아닌 strict lane이 `strictLaneStages`에 선언한 단계(`prCheck`·`mainCheck`·`integrationCheck`·`performanceCheck`·`releaseCheck`) 중 하나의 계획에 있는지, 단계마다 선언한 workflow job이 `./gradlew <단계>`를 정해진 한 줄로 조건 없이(또는 선언한 조건으로) 돌리는지 검사. 형식은 `build-logic/AGENTS.md` 「단계 job의 모양」. PR 단계가 돌림 |
|
||||
| `prCheck` | PR 단계: `ci` + `verifyDependencyLocks` + compose 렌더링(`verifyComposeProfiles`) + 저장소 배치(`verifyRepositoryLayout`) + 작업 지침 분량·이력 ID(`verifyWorkDocs`) + 문서 검사(`documentCheck`) |
|
||||
| `ci` | 모든 leaf `check`(API surface 검사 포함, 소유자 결정 20) + `architectureCheck` + `qualityCheck` |
|
||||
| `mainCheck` | main 단계: `configContractCheck` + `qualificationCheck` + `verifyPublicPathSnapshot` + 전송·메시징 qualification 레인 + 각 leaf의 `mainCheck`(문서 대조 레인 `*DocumentContractTest`, objectstorage MinIO 레인) |
|
||||
| `mainCheck` | main 단계: `configContractCheck` + `qualificationCheck` + `verifyPublicPathSnapshot` + 전송·메시징 qualification(`conditionalTransportQualification`, `verifyMessagingContracts`) + graphql 전송 경계 lane(`graphqlStableTest`) + 생성 명령 왕복(`verifyFeatureScaffold`) + 각 leaf의 `mainCheck`(문서 대조 레인 `*DocumentContractTest`, objectstorage MinIO 레인) |
|
||||
| `releaseCheck` | tag 전용 검사: `verifyReleaseProvenance` + `verifyPublicPathSnapshot`(`ci`를 다시 돌리지 않음) |
|
||||
|
||||
따라서 로컬에서 한 모듈만 수정했다면 `./gradlew :domain-core:check`처럼 focused task를
|
||||
@@ -48,10 +51,10 @@ Checkstyle은 **포매터가 표현할 수 없는 것만** — 네이밍과 몇
|
||||
### 로컬 첫 실행
|
||||
|
||||
`scripts/bootstrap-local.sh`(저장소 루트)은 compile → Docker 확인 → DB 기동 대기 →
|
||||
app 기동(Flyway 포함) → health smoke를 순서대로 실행한다(예전 `./gradlew bootstrap`, 리뷰
|
||||
BUILD-O3-5로 build-logic 플러그인에서 스크립트로 옮김).
|
||||
DB와 app lifecycle은 저장소 루트의 개발 compose 파일 `compose.yaml`(`db`는 `jpa` profile)이 소유하며, app startup Flyway가
|
||||
끝나 public health endpoint가 준비되어야 다음 단계로 넘어간다. `.env.example`은 커밋된
|
||||
app 기동 → health smoke를 순서대로 실행한다(예전 `./gradlew bootstrap`, build-logic 플러그인에서 스크립트로 옮김).
|
||||
DB와 app lifecycle은 저장소 루트의 개발 compose 파일 `compose.yaml`(`db`는 `jpa` profile)이 소유하며, public health
|
||||
endpoint가 준비되어야 다음 단계로 넘어간다. 기본 조립은 web뿐이라 datasource를 열지 않고 Flyway도 돌지 않는다.
|
||||
persistence-jpa 줄을 켠 서비스는 그 대기 안에서 startup Flyway가 끝난다. `.env.example`은 커밋된
|
||||
env 계약이고 `.env`는 로컬 실행 입력이다. `verifyEnvKeys`는 example/registry/shipped YAML을
|
||||
함께 검사한다.
|
||||
|
||||
@@ -270,7 +273,7 @@ Kafka 없이 기동한다. 나머지 기능은 `src/bootstrap/app/build.gradle`
|
||||
| WebSocket (STOMP push) | `runtimeOnly project(':adapter:inbound:websocket')` | 없음(기본값으로 동작). origin은 `APP_WEBSOCKET_ALLOWED_ORIGINS` | `APP_WEBSOCKET_ENABLED` |
|
||||
| gRPC 서버 | `runtimeOnly project(':adapter:inbound:grpc')` | `APP_GRPC_SERVER_ALLOW_INSECURE_LOCAL=true` (지금 받는 listener가 loopback plaintext뿐) | `app.grpc.server.enabled` |
|
||||
| 파일 서버 (JPA를 함께 가져옴) | `runtimeOnly project(':composition:fileserver-platform')` | `APP_FILESERVER_PLATFORM_STORAGE_ROOT`, `APP_FILESERVER_PLATFORM_OBSERVABILITY_FINGERPRINT_KEY`, 그리고 `FileAccessPolicyPort` bean 또는 `APP_FILESERVER_PLATFORM_SECURITY_ACCESS_POLICY=role-based` | `APP_FILESERVER_PLATFORM_ENABLED` |
|
||||
| 알림 (SMTP/SES, JPA 줄도 필요) | `runtimeOnly project(':composition:notification-platform')` | 키 8종과 각 `_ID`(`APP_NOTIFICATION_PLATFORM_*_KEY`, `*_KEY_ID`), 쓰는 provider 설정(`APP_NOTIFICATION_PLATFORM_SMTP_*` 또는 `_SES_*`) | `APP_NOTIFICATION_PLATFORM_ENABLED` |
|
||||
| 알림 (SMTP/SES, JPA 줄도 필요) | `runtimeOnly project(':composition:notification-platform')` | 키와 각 `_ID`(`APP_NOTIFICATION_PLATFORM_*_KEY`, `*_KEY_ID`, 목록은 registry), 쓰는 provider 설정(`APP_NOTIFICATION_PLATFORM_SMTP_*` 또는 `_SES_*`) | `APP_NOTIFICATION_PLATFORM_ENABLED` |
|
||||
|
||||
전체 목록과 타입·기본값은 `docs/registries/env-keys.yaml`, 각 모듈이 제공하는 것은 그 모듈 README의
|
||||
"제공하는 것 · 추가할 한 줄 · env 키" 절에 있다. 기능 사이의 의존(알림·파일 서버 → JPA, outbox relay
|
||||
|
||||
@@ -30,10 +30,10 @@ lanes and CI; it is not a deployment artifact.
|
||||
| Relational persistence (JPA/PostgreSQL) | `ca-skeleton.persistence-jpa.enabled` / `APP_PERSISTENCE_JPA_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:persistence-jpa')`) | yes | Not in the default composition. The one line brings everything — its own `AutoConfiguration.imports` (`PersistenceJpaAutoConfiguration`, `PersistenceJpaRuntimeConfig`, `JpaStartupAutoConfiguration`), its environment handling (`JpaActivationEnvironmentPostProcessor`, `spring.factories`: readiness `db` while on; with `false` it also excludes Boot's JDBC, Hibernate, Spring Data JPA and Flyway auto-configuration, so no DataSource is bound), the startup guards (Flyway strategy, datasource/OSIV/DDL/pool/TLS/vendor checks, exit codes unchanged) and its settings (`config/module-defaults/persistence-jpa.yml`). `persistence-jpa:PersistenceJpaCapabilityAssemblyTest` proves the module assembles on its own; the `postgresql*IntegrationTest` readiness lanes, run by `main.yml` → `main` (`:integrationCheck`), qualify it against PostgreSQL. `bootRunH2` adds the module to its own classpath only. |
|
||||
| Document persistence (MongoDB) | `ca-skeleton.persistence-mongo.enabled` / `APP_PERSISTENCE_MONGO_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:persistence-mongo')`) | yes | On when present; `false` also excludes Boot's Mongo auto-configuration (`MongoCapabilityActivationTest`). The connection-source rule (`SPRING_MONGODB_URI` or the selected profile's `uri-secret`) is checked by the module's own `MongoDefaultsEnvironmentPostProcessor`. Six container lanes (`mongoReplicaSetTest`, `mongoFailoverTest`, …), run by `main.yml` → `main` (`:integrationCheck`) |
|
||||
| Messaging (Kafka) | `app.messaging.enabled` / `APP_MESSAGING_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:messaging-kafka')`, which brings the application bridge and the messaging library `dev.cakit.messaging` (messaging-library repo, catalog `messagingLibrary`) with its Kafka transport) | Kafka only | On when present (`KafkaCapabilityActivationTest`). The application's own publish and consume paths run against a live Kafka in `messagingKafkaRelayIntegrationTest` and `messagingInboxRedeliveryIntegrationTest`. The library's broker certification (`verifyMessagingCertificationEvidence`) runs in the messaging-library repo's main stage since 2026-11-08. Kafka is the only registered broker; the RabbitMQ broker keys were removed (no transport). |
|
||||
| Redis capabilities (cache / rate-limit / lease / idempotency) | `app.redis.enabled` / `APP_REDIS_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:cache-redis')`, which brings `redis-runtime`) | yes | `cache-redis:redisContainerContractTest` (Testcontainers Redis, `integrationCheck`); `cache-redis:redisTopologyTest`, run by `redis-sdk-topology.yml`. Not in the default composition. On when present; `false` contributes no Redis bean — no settings, client, connection, thread or health contributor. The module owns its readiness contribution (`RedisReadinessGroupPostProcessor`, `spring.factories`) and its settings (`config/module-defaults/cache-redis.yml`: `app.redis.enabled`, `app.rate-limit.*`, the Redis `ca-skeleton.capabilities.*`). No `app-bootstrap` main source names a Redis type. |
|
||||
| Redis capabilities (cache / rate-limit / lease / idempotency) | `app.redis.enabled` / `APP_REDIS_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:cache-redis')`, which brings `redis-runtime`) | yes | `cache-redis:redisContainerContractTest` (Testcontainers Redis, `integrationCheck`); `cache-redis:redisTopologyTest`, run by `main.yml` job `redis-topology` (`scripts/ci/redis-topology.sh`). Not in the default composition. On when present; `false` contributes no Redis bean — no settings, client, connection, thread or health contributor. The module owns its readiness contribution (`RedisReadinessGroupPostProcessor`, `spring.factories`) and its settings (`config/module-defaults/cache-redis.yml`: `app.redis.enabled`, `app.rate-limit.*`, the Redis `ca-skeleton.capabilities.*`). No `app-bootstrap` main source names a Redis type. |
|
||||
| Request idempotency | `APP_IDEMPOTENCY_PROVIDER` (`disabled` \| `redis` \| `postgresql`; a selector, not an on/off key) | yes | yes | Redis and PostgreSQL | One generation: the application `IdempotencyExecutor`, built once by `composition:idempotency` (`IdempotencyAutoConfiguration`) over the one store the selected provider contributes (`cache-redis` or `persistence-jpa`); startup is refused unless exactly one store exists. `app-bootstrap`이 그 모듈을 `runtimeOnly` 한 줄로 받고, 다른 조립은 없다. Redis is covered by the row above. PostgreSQL has `persistence-jpa:postgresqlIdempotencyIntegrationTest`, run by `main.yml` → `main` (`:integrationCheck`). The `postgresql` provider refuses a non-PostgreSQL data source, so `bootRunH2` uses `disabled` or `redis`. Each store comes with its module: `postgresql` needs the persistence-jpa line, `redis` the cache-redis one. |
|
||||
| Transactional outbox relay | `ca-skeleton.outbox.enabled` / `APP_OUTBOX_ENABLED`, `false` (+ `APP_OUTBOX_RELAY_ENABLED`, `false`; persistence-jpa settings) | yes | yes (with the persistence-jpa line; the scheduler also needs the messaging-kafka line) | yes | The store and its settings are persistence-jpa's; the relay (`OutboxConfig`) is application composition in `app-bootstrap` because a driven adapter must not build or call a use case. It turns on only when an `OutboxStorePort` bean exists, and the scheduler only when an `OutboxMessagePublishPort` does (the messaging bridge), each ordered after its contributor by `afterName` — so an environment with no publisher keeps its PENDING rows. The bridge registers no stand-in publisher: a present-and-enabled bridge with a blank broker and no canonical transport is refused at startup. `postgresqlLegacyOutboxConcurrentRelayIntegrationTest` qualifies claim/fencing against PostgreSQL. |
|
||||
| Notification platform | `ca-skeleton.notification.platform.enabled` / `APP_NOTIFICATION_PLATFORM_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':composition:notification-platform')`, plus the persistence-jpa line) | claim-scoped | Not in the default composition. The one line brings the use-case assembly, `adapter:outbound:notification`, the HTTP surface `adapter:inbound:web-notification` and its own settings (`config/module-defaults/notification.yml`), each registered through the module's own `AutoConfiguration.imports`; `adapter:inbound:web` no longer depends on `application-notification`. `verifyNotificationEvidence` refuses a grade in `docs/notification/support-matrix.md` that no proven claim backs; run by `notification-platform.yml`. There is no real-SMTP lane, and the matrix says so rather than implying one. |
|
||||
| Transactional outbox relay | `ca-skeleton.outbox.enabled` / `APP_OUTBOX_ENABLED`, `false` (+ `APP_OUTBOX_RELAY_ENABLED`, `false`; persistence-jpa settings) | yes | yes (with the persistence-jpa line; the scheduler also needs the messaging-kafka line) | yes | The store and its settings are persistence-jpa's; the relay (`OutboxRelayAutoConfiguration`) is the composition module `:composition:outbox-relay` because a driven adapter must not build or call a use case. It turns on only when an `OutboxStorePort` bean exists, and the scheduler only when an `OutboxMessagePublishPort` does (the messaging bridge), each ordered after its contributor by `afterName` — so an environment with no publisher keeps its PENDING rows. The bridge registers no stand-in publisher: a present-and-enabled bridge with a blank broker and no canonical transport is refused at startup. `persistence-jpa:postgresqlOutboxConcurrentRelayIntegrationTest` qualifies claim/fencing against PostgreSQL. |
|
||||
| Notification platform | `ca-skeleton.notification.platform.enabled` / `APP_NOTIFICATION_PLATFORM_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':composition:notification-platform')`, plus the persistence-jpa line) | claim-scoped | Not in the default composition. The one line brings the use-case assembly, `adapter:outbound:notification`, the HTTP surface `adapter:inbound:web-notification` and its own settings (`config/module-defaults/notification.yml`), each registered through the module's own `AutoConfiguration.imports`; `adapter:inbound:web` no longer depends on `application-notification`. `NotificationEvidenceVerifierTest` refuses a grade in `docs/notification/support-matrix.md` that no proven claim backs; it runs in the leaf's main-stage lane `notificationDocumentContractTest`, run by `main.yml` → `main` (`:mainCheck`). There is no real-SMTP lane, and the matrix says so rather than implying one. |
|
||||
| File server platform | `app.fileserver-platform.enabled` / `APP_FILESERVER_PLATFORM_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':composition:fileserver-platform')`, plus the persistence-jpa line) | yes | On when present; module-owned `config/module-defaults/fileserver.yml` also carries the servlet multipart ceiling. `app-bootstrap:integrationTest` → `FileserverCompositionIntegrationTest` (required by the strict lane), run by `main.yml` → `main` (`:integrationCheck`) |
|
||||
| Outbound HTTP client | `app.httpclient.enabled` / `APP_HTTPCLIENT_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:httpclient')`) | yes | On when present (`HttpClientPlatformActivationTest`). `httpclient:httpClientFailureInjectionTest` against a faulted upstream, run by `main.yml` → `main` (`:integrationCheck`) |
|
||||
| GraphQL transport | `backend.graphql.enabled` / `APP_GRAPHQL_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:inbound:graphql')`) | leaf-level | On when present; `false` also excludes Spring GraphQL's own auto-configuration, so no `/graphql` (`GraphQlCapabilityActivationTest`). `graphqlTransportQualificationTest` runs the HTTP boundary. The deployment-mode/runtime-profile rule is the module's own `GraphQlPlatformStartupValidator`. The default jar does not ship GraphQL, so a compose lane that exercises it runs the qualification jar. |
|
||||
@@ -71,6 +71,8 @@ web 경로의 `W/`는 `src/adapter/inbound/web/src/main/java/dev/caskeleton/adap
|
||||
|
||||
복구가 필요하면 표의 커밋에서 경로를 꺼낸다(`git show <커밋>:<경로>`).
|
||||
|
||||
표의 경로는 지운 때의 배치다. 2026-11 재배치(Gradle 루트를 저장소 루트로) 전에 지운 행은 `src/app-bootstrap/`·`src/adapters/` 같은 옛 경로를 적고, 그 경로는 지금 트리에 없다. 지금 위치로 고치지 않는다. 그 커밋에서 꺼낼 때 쓰는 경로가 그것이기 때문이다. 옛 배치와 새 배치의 대응은 `docs/upgrade/2026-11-relayout.md`다.
|
||||
|
||||
리뷰 후속 작업(2026-09-25~28, `docs/history/plans/2026-09-25-review-followup.md`)에서 지운 것은 마지막으로 존재한 커밋이 `6d27356e`인 행으로 표 끝에 이어 붙였다.
|
||||
|
||||
| 대상 | 경로 | 마지막으로 존재한 커밋 | 이유 |
|
||||
@@ -526,3 +528,4 @@ web 경로의 `W/`는 `src/adapter/inbound/web/src/main/java/dev/caskeleton/adap
|
||||
| `SecretSourceValidator`의 `RELATIONAL_PERSISTENCE_PROPERTY`·`isRelationalPersistenceOn()`(모듈 스위치 해석) | `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/runtime/SecretSourceValidator.java` | `0ebb77b5` | P22-new-1: persistence-jpa가 기여 |
|
||||
| 설정 키 `app.notification.platform.smtp.max-concurrency`(이름 변경 → `dispatch-concurrency`, env `APP_NOTIFICATION_PLATFORM_SMTP_DISPATCH_CONCURRENCY` 그대로) | `NotificationSmtpSettings.java`, `notification.yml` | `0ebb77b5` | P20-new-1 |
|
||||
| Redis ACL `+@pubsub`·`&prod:*`(application 계정 2개) | `infra/redis-sdk/acl/*.acl` | `0ebb77b5` | P22-new-2 |
|
||||
| 시험 `ComposeMergeCharacterizationTest` | `src/bootstrap/app/src/integrationTest/java/dev/caskeleton/bootstrap/compose/ComposeMergeCharacterizationTest.java` | `ca1fbfde`(지운 커밋 `23139722`의 부모) | 어느 lane도 고르지 않아 한 번도 돌지 않았다(`integrationTest` lane은 `requires`로 적은 클래스만 고른다). 보던 것(기본·dev 조합 렌더링, 계약 스크립트)은 PR 단계 `verifyComposeProfiles`가 모든 lane으로 본다(2026-11-12 리뷰) |
|
||||
|
||||
@@ -16,6 +16,9 @@ body size limit
|
||||
→ 2xx
|
||||
```
|
||||
|
||||
응답은 본문 없는 status다: 받으면(중복도) 204, 서명·형식 거절은 400, 본문 한도 초과는 413, 검증을 돌리지 못하면
|
||||
503과 `Retry-After`. provider는 4xx면 멈추고 5xx면 다시 보낸다. 인증 전 경로라 거절 이유를 싣지 않는다.
|
||||
|
||||
projection보다 ledger 추가를 먼저 하기 때문에 빠른 2xx가 정직하다. provider에게는 이벤트가 기록됐다고 알리고,
|
||||
projector 결함은 이벤트 유실이 아니라 replay 문제가 된다.
|
||||
|
||||
|
||||
@@ -42,8 +42,9 @@ verifyMessagingTargetBindingPreflight
|
||||
1. 각 시나리오를 실제로 실행하는 Test 태스크.
|
||||
2. 그 실행 결과(JUnit XML)에서 payload-free manifest를 만드는 producer.
|
||||
3. `src/adapter/outbound/messaging/release/evidence/build-evidence-manifest-v1.schema.json`으로 그 manifest 바이트를
|
||||
검증하는 단계(build-tools `VerifyMessagingEvidenceTask`가 쓰고 바로 검증한다).
|
||||
검증하는 단계. manifest를 쓰는 태스크가 쓰자마자 검증한다.
|
||||
4. 위 셋이 모두 생긴 다음에 `verifyMessaging<Scenario>R2` 태스크 등록.
|
||||
|
||||
build-tools `MessagingQualificationPlugin`의 `verifyMessagingContracts`가 그 네 단계를 모두 갖춘
|
||||
예시다.
|
||||
> 이력: 네 단계를 모두 갖춘 예시였던 build-tools `MessagingQualificationPlugin`과 `VerifyMessagingEvidenceTask`는
|
||||
> 2026-09-25 capability 포장(`6d27356e`)에서 지웠다. 루트 `verifyMessagingContracts`는 남아 있고, 지금은
|
||||
> application·shared 계약 lane 둘을 묶기만 한다(루트 `build.gradle`).
|
||||
|
||||
@@ -141,15 +141,14 @@ fixture는 **지원 코드**다. TEST/INTEGRATION/SYSTEM/ARCHITECTURE/PERFORMANC
|
||||
|
||||
### repository
|
||||
|
||||
- `integrationCheck`: production leaf들의 INTEGRATION lanes.
|
||||
- `systemTestCheck`: production leaf들의 SYSTEM lanes.
|
||||
- `architectureCheck`: repository architecture rules + ARCHITECTURE lanes.
|
||||
- `qualificationCheck`: SYSTEM composition + auxiliary-source style gate.
|
||||
- `ci`: leaf checks + architecture/quality/config contract + qualification.
|
||||
- `releaseCheck`: `ci` + release-only provenance/archive/public-path checks.
|
||||
category별 묶음 태스크: `integrationCheck`(모든 leaf의 INTEGRATION lane), `performanceCheck`(PERFORMANCE lane),
|
||||
`systemTestCheck`(SYSTEM lane. app-bootstrap은 `check`가 이미 돌려 뺀다), `architectureCheck`(저장소 아키텍처 규칙과
|
||||
ARCHITECTURE lane). 이것들을 어느 단계(`prCheck`·`mainCheck`·`releaseCheck` 등)가 부르는지와 단계마다 무엇이 더 붙는지의 정본은
|
||||
`docs/work/reference/gates.md` 1절과 루트 `build.gradle`의 단계 태스크다. 여기에 복사하지 않는다.
|
||||
|
||||
`integrationCheck`는 현재 `ci`에 암묵적으로 포함되지 않는다.
|
||||
여러 integration lane이 container runtime을 요구하므로 별도 workflow/main/nightly에서 실행할 수 있다.
|
||||
- `integrationCheck`는 `ci`에 들지 않는다. container runtime이 드는 lane이 많아 main 단계(`main.yml` `main` job)가
|
||||
따로 부른다.
|
||||
- `systemTestCheck`는 `qualificationCheck`를 거쳐 main 단계에서 돈다.
|
||||
|
||||
PERFORMANCE는 기본 로컬 `check`에 붙이지 않는다. 명시적 benchmark/performance task나
|
||||
scheduled workflow가 실행한다.
|
||||
|
||||
@@ -70,6 +70,10 @@ status는 코드 표(`HttpStatusErrorCodes`)에 있는 것만 그대로 나간
|
||||
4xx·5xx status로 나가는 본문은 `success:true`로 감싸지 않는다. 실패 Envelope가 아닌 본문을 오류 status로
|
||||
돌려주는 핸들러는 그 본문이 그대로 나간다.
|
||||
|
||||
Envelope가 아닌 응답은 두 곳뿐이다. fileserver의 프로토콜 예외(`docs/fileserver/http-contract.md` 「Envelope 규칙의
|
||||
프로토콜 예외」)와 알림 provider callback이다. callback은 provider가 status만 읽는 webhook 응답이라 본문 없이
|
||||
204·400·413·503만 답한다(`src/adapter/inbound/web-notification/AGENTS.md`).
|
||||
|
||||
### 왜 이렇게 나가는가
|
||||
|
||||
`Envelope`·`BulkEnvelope`·`ApiError`·`ResponseMeta`는 `shared-contract`에 있고, 이 leaf는 Java
|
||||
|
||||
@@ -7,12 +7,14 @@
|
||||
API 설명의 가치는 전부 그것을 소비하는 쪽에 있다. client generator가 다 이해하지 못하는 버전의 문서는 실패하지
|
||||
않는다. 컴파일되는데 틀린 client를 만든다. 문서가 아예 없는 것보다 나쁘다.
|
||||
|
||||
그래서 3.1.2가 릴리스 산출물로 남고, 3.2는 그 옆에서 만든다.
|
||||
그래서 3.2는 3.1 문서를 바꾸지 않고 그 옆에서 만든다. 이 템플릿 자체는 OpenAPI 문서를 릴리스 산출물로 내지
|
||||
않는다(만들던 샘플을 2026-09-25에 지웠다). 아래는 3.1 문서를 내는 서비스가 3.2를 함께 만들 때의 규칙이다.
|
||||
|
||||
## 불변식
|
||||
|
||||
**3.2를 만드는 것이 3.1 snapshot을 바꾸면 안 된다.** 둘은 같은 모델에서 나온다. 그래서 3.2로 가는 길에 모델을
|
||||
바꾸는 기여자는 실제로 내보내는 산출물을 바꾼다. 조용히, 그리고 3.2를 만들 때만.
|
||||
**3.2를 만드는 것이 그 서비스의 3.1 문서를 바꾸면 안 된다.** 둘은 같은 모델에서 나온다. 그래서 3.2로 가는 길에
|
||||
모델을 바꾸는 기여자는 실제로 내보내는 산출물을 바꾼다. 조용히, 그리고 3.2를 만들 때만. 서비스는 자기 3.1 문서를
|
||||
snapshot으로 두고 3.2를 만들 때 그것이 그대로인지 본다.
|
||||
|
||||
이 저장소에는 그것을 검사하는 것이 더는 없다. snapshot을 hash하고 어떤 parser, linter, generator, client 컴파일이
|
||||
3.2 출력을 읽었는지 기록하던 승격 보고서 `OpenApi32CompatibilityReport`와 `OpenApiToolchainMatrix`는 2026-09-25에
|
||||
@@ -23,5 +25,5 @@ API 설명의 가치는 전부 그것을 소비하는 쪽에 있다. client gene
|
||||
|
||||
## 돌리기
|
||||
|
||||
이 저장소의 어떤 workflow도 3.2를 만들지 않는다. `OpenApiVersionLane.STABLE_3_1`이 릴리스 산출물이고,
|
||||
`WebOpenApi32GeneratorTest`가 generator를 다룬다.
|
||||
이 저장소의 어떤 workflow도 OpenAPI 문서를 만들지 않는다. `OpenApiVersionLane.STABLE_3_1`은 서비스가 내보낼 안정
|
||||
lane의 이름이고, `WebOpenApi32GeneratorTest`가 3.2 generator를 다룬다.
|
||||
|
||||
@@ -144,9 +144,10 @@ worker는 바뀐 행 수로 그것을 안다.
|
||||
## 8. 예산 강제: edge가 막는 것과 애플리케이션이 막는 것
|
||||
|
||||
> **2026-09-25에 지움.** servlet 예산 filter(`WebMvcBudgetFilter`)와 그 problem 대응은 2세대 플랫폼과 함께 지웠다.
|
||||
> 내보내는 애플리케이션은 더는 아래 애플리케이션 칸을 강제하지 않는다. `budget` 목록(`WebRequestBudget`,
|
||||
> `WebBudgetCatalog`)은 `adapter:inbound:web-advanced`에 라이브러리 코드로 남고, 쓰이지 않던 meter(`WebBudgetMeter`와
|
||||
> 그 결과/위반 타입)는 지웠다. edge 칸은 여전히 맞다.
|
||||
> 내보내는 애플리케이션이 직접 강제하는 칸은 요청 본문 한도뿐이다. JSON 본문은 web 한도(`app.web.mvc.max-json-body-size`,
|
||||
> 기본 1 MiB, web `JsonBodyLimitFilter`, 넘으면 413 `PAYLOAD_TOO_LARGE` Envelope), multipart는 Spring 기본 한도다. 나머지 칸의 이름(`maxUriBytes` 등)은
|
||||
> `budget` 목록(`WebRequestBudget`, `WebBudgetCatalog`)의 값이고, 그 목록은 `adapter:inbound:web-advanced`에 라이브러리
|
||||
> 코드로만 남았다. 쓰이지 않던 meter(`WebBudgetMeter`와 그 결과/위반 타입)는 지웠다. edge 칸은 여전히 맞다.
|
||||
|
||||
설계(Task 49)는 edge proxy의 한도와 애플리케이션 자체 한도의 차이를 장애 중에 발견하지 말고 적어 두라고 요구한다.
|
||||
같은 차원에 한도는 늘 둘 있고, 둘은 결코 같지 않으며, 어느 쪽이 걸리는지가 호출자가 보는 것을 정한다.
|
||||
@@ -155,11 +156,11 @@ worker는 바뀐 행 수로 그것을 안다.
|
||||
| --- | --- | --- | --- |
|
||||
| 요청 줄 / URI | `large_client_header_buffers`(기본 8k) | `maxUriBytes` | edge가 먼저 — nginx가 자기 HTML로 414 |
|
||||
| 요청 헤더 | `large_client_header_buffers` | `maxHeaderBytes` | edge가 먼저 — nginx 400, problem document 없음 |
|
||||
| 요청 본문 | `client_max_body_size`(기본 1m) | `maxBodyBytes`(플랫폼 상한 8 MiB) | 더 작은 쪽. nginx는 HTML로 413 |
|
||||
| query parameter 수 | 강제하지 않음 | `maxQueryParameters` | 늘 애플리케이션 |
|
||||
| JSON 깊이 / 배열 크기 | 강제하지 않음 | `maxJsonDepth`, `maxArrayElements` | 늘 애플리케이션 |
|
||||
| 실행 시간 | `proxy_read_timeout`(기본 60s) | `maxExecutionTime`(상한 2분) | 플랫폼 쪽이 더 크면 edge가 먼저 |
|
||||
| 응답 크기 | 강제하지 않음 | `maxResponseBytes`(상한 32 MiB) | 늘 애플리케이션 |
|
||||
| 요청 본문 | `client_max_body_size`(기본 1m) | JSON 본문: `app.web.mvc.max-json-body-size`(기본 1 MiB, 강제함). multipart 본문: Spring 기본 한도(`spring.servlet.multipart.*`, 넘으면 Envelope 413). 그 밖의 raw 본문: 전역 한도 없음, endpoint가 둔다 | 더 작은 쪽. nginx는 HTML로 413, 애플리케이션은 Envelope로 413 |
|
||||
| query parameter 수 | 강제하지 않음 | `maxQueryParameters` | 아무도 막지 않는다(애플리케이션 칸은 목록 값뿐) |
|
||||
| JSON 깊이 / 배열 크기 | 강제하지 않음 | `maxJsonDepth`, `maxArrayElements` | 깊이는 Jackson 기본 `StreamReadConstraints`만 걸린다. 배열 크기는 아무도 막지 않는다 |
|
||||
| 실행 시간 | `proxy_read_timeout`(기본 60s) | `maxExecutionTime`(상한 2분) | edge. 애플리케이션 칸은 목록 값뿐이다 |
|
||||
| 응답 크기 | 강제하지 않음 | `maxResponseBytes`(상한 32 MiB) | 아무도 막지 않는다(애플리케이션 칸은 목록 값뿐) |
|
||||
|
||||
둘 다 직관과 반대라서 적어 둘 만한 결과가 둘 있다.
|
||||
|
||||
@@ -167,8 +168,8 @@ worker는 바뀐 행 수로 그것을 안다.
|
||||
HTML 오류 쪽을 답하므로, `error.code`로 분기하는 client는 파싱할 수 없는 본문을 받는다. client에게 중요한 차원이면
|
||||
edge 한도를 애플리케이션보다 *높게* 두어 애플리케이션이 거부하게 한다.
|
||||
|
||||
**edge 한도가 애플리케이션보다 높아도 쓸데없지 않다.** 애플리케이션의 meter가 세기 전에 문제가 될 만큼 큰 본문과
|
||||
프로세스 사이에 서 있는 것은 그것뿐이다. 둘 다 있어야 하고, 정할 것은 순서뿐이다.
|
||||
**edge 한도가 애플리케이션보다 높아도 쓸데없지 않다.** 애플리케이션이 막지 않는 차원(위 표의 「아무도 막지 않는다」)에서
|
||||
큰 요청과 프로세스 사이에 서 있는 것은 그것뿐이다. 둘 다 있어야 하고, 정할 것은 순서뿐이다.
|
||||
|
||||
## 9. Nginx lane (2026-09-25에 지움)
|
||||
|
||||
|
||||
+5
-3
@@ -6,15 +6,17 @@
|
||||
"This repository uses strict per-leaf Gradle lockfiles; Renovate does not regenerate those locks here.",
|
||||
"A maintainer must run `./gradlew resolveAndLockAll --write-locks`, review the lock diff,",
|
||||
"and commit the refreshed lockfiles before a dependency PR can pass `verifyDependencyLocks`.",
|
||||
"Transitive vulnerabilities are NOT covered by either bot (direct deps only) — pin them with a Gradle",
|
||||
"dependency constraint / resolutionStrategy.force (§4) and regenerate locks (supply-chain D8)."
|
||||
"Transitive vulnerabilities are NOT covered by Renovate (direct deps only) — pin them with a Gradle",
|
||||
"dependency constraint / resolutionStrategy.force (§4) and regenerate locks (supply-chain D8).",
|
||||
"This file takes effect only where a Renovate instance is pointed at the repository; none is wired",
|
||||
"for the Gitea host today. The enforced gate is scripts/ci/trivy-scan.sh in the pipelines."
|
||||
],
|
||||
"extends": [
|
||||
"config:recommended",
|
||||
"security:only-security-updates"
|
||||
],
|
||||
"vulnerabilityAlerts": {
|
||||
"description": "Stable GitHub vulnerability alerts → immediate security PR, ignoring schedule.",
|
||||
"description": "GitHub-hosted only: Renovate reads GitHub's Dependabot alerts, which a Gitea host does not have. osvVulnerabilityAlerts below is the source elsewhere.",
|
||||
"enabled": true,
|
||||
"labels": [
|
||||
"security",
|
||||
|
||||
@@ -10,8 +10,9 @@
|
||||
# This was the build-logic `ca.developer-bootstrap` plugin (`./gradlew bootstrap`). Starting
|
||||
# containers and probing an HTTP endpoint is not a build rule, so it is a script now (review
|
||||
# 2026-09-24 BUILD-O3-5). The four stages and their order are unchanged: the next stage starts only
|
||||
# when the previous one succeeded, and the app stage waits for startup Flyway through the compose
|
||||
# healthcheck before the smoke probe runs.
|
||||
# when the previous one succeeded, and the app stage waits for the compose healthcheck before the
|
||||
# smoke probe runs. The default composition is web only: it opens no datasource and runs no
|
||||
# Flyway. A service that adds the persistence-jpa line gets startup Flyway inside the same wait.
|
||||
#
|
||||
# Until 2026-11-07 it merged docker-compose.yml with docker-compose.local.yml and asked for a `db`
|
||||
# service neither file had defined since the database moved to a third file, so the documented
|
||||
@@ -40,7 +41,7 @@ fi
|
||||
echo "bootstrap 2/4: starting the PostgreSQL dependency and waiting for readiness"
|
||||
"${compose[@]}" up -d --wait db
|
||||
|
||||
echo "bootstrap 3/4: building and starting the app; startup Flyway finishes before health is ready"
|
||||
echo "bootstrap 3/4: building and starting the app and waiting for its health"
|
||||
"${compose[@]}" up -d --build --wait app
|
||||
|
||||
echo "bootstrap 4/4: requiring HTTP 200 and status=UP from ${health_endpoint}"
|
||||
|
||||
@@ -107,7 +107,9 @@ required-class 검사가 이 테스트가 조용히 사라지는 것을 막는
|
||||
모듈을 자동 커버 — per-module 규칙 추가 불필요).
|
||||
- 프로덕션 feature 쿼리/뮤테이션을 스켈레톤에 두는 것 — health 표면만 (web 의
|
||||
`HealthcheckController` 와 동일 원칙). feature 스키마/컨트롤러/매퍼는 그 기능을 가진 서비스가 소유한다.
|
||||
- 모듈별 `yml` — 설정은 프레임워크 `spring.graphql.*` 로 composition-root `application.yml` 에 산다.
|
||||
- `config/graphql.yml` 밖의 설정 파일 — 이 leaf의 설정 기본값은 그 파일 하나다. 의존성에 support가 없어 공용
|
||||
`ModuleDefaultsEnvironmentPostProcessor` 대신 `GraphQlActivationEnvironmentPostProcessor`가 읽는다(manual 10 기준 7 뒤 예외).
|
||||
전송 설정 `spring.graphql.*`은 composition-root `application.yml`에 둔다.
|
||||
|
||||
## 오류 대응 (`Category → ErrorType`)
|
||||
|
||||
|
||||
@@ -123,7 +123,8 @@ gRPC 와 달리 spring-graphql / graphql-java 는 Spring Boot BOM 이 관리한
|
||||
## 설정 — 프레임워크 `spring.graphql.*` + 플랫폼 `app.graphql.*`
|
||||
|
||||
전송 계층 설정(path, graphiql, introspection, schema location)은 프레임워크 `spring.graphql.*`
|
||||
가 소유한다. composition-root `application.yml` 에서 설정하며 모듈별 `yml` 은 없다.
|
||||
가 소유한다. composition-root `application.yml` 에서 설정한다. 이 leaf의 `app.graphql.*` 기본값과 env 연결은
|
||||
모듈의 `config/graphql.yml` 하나에 있고, `GraphQlActivationEnvironmentPostProcessor`가 가장 낮은 우선순위로 읽는다.
|
||||
|
||||
플랫폼 정책은 `spring.graphql.*` 로 표현할 수 없다 — cost/page 한계, preparsed
|
||||
캐시 경계, 관측 label 로 허용할 operation 이름은 전부 이 leaf 의 결정이다. 그래서
|
||||
@@ -148,9 +149,9 @@ app:
|
||||
observed-operation-names: [] # 비우면 모든 operation 이름이 `other` 로 접힌다
|
||||
```
|
||||
|
||||
이 모듈의 `config/graphql.yml`이 위 wired 설정을 `APP_GRAPHQL_*`로 노출한다. `APP_GRAPHQL_ENABLED`와
|
||||
`APP_GRAPHQL_DEPLOYMENT_MODE` 외에도 execution profile, console, page/complexity, preparsed-cache
|
||||
한계와 관측 operation allowlist가 같은 property tree로 들어간다.
|
||||
이 모듈의 `config/graphql.yml`이 위 설정을 `APP_GRAPHQL_*`로 노출한다. `APP_GRAPHQL_ENABLED`와
|
||||
`APP_GRAPHQL_DEPLOYMENT_MODE` 외에도 console(`APP_GRAPHQL_GRAPHIQL_ENABLED`, `APP_GRAPHQL_INTROSPECTION_ENABLED`),
|
||||
page/complexity, preparsed-cache 한계, N+1 경고 임계와 관측 operation allowlist가 같은 property tree로 들어간다.
|
||||
|
||||
production mode는 env만으로 완성되지 않는다. 애플리케이션 좌표를 스켈레톤이 알 수 없으므로
|
||||
**명시적인 `GraphQlAuthorizationPolicy` bean이 반드시 필요**하며, 이것은 의도된 fail-closed
|
||||
|
||||
@@ -0,0 +1,31 @@
|
||||
# adapter:inbound:web-fileserver — 파일 서버의 HTTP 표면
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-inbound-web-fileserver`
|
||||
- Gradle 경로: `:adapter:inbound:web-fileserver`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:web-fileserver:test --console=plain`
|
||||
- registry 정본: `gradle/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.adapter.inbound.web.fileserver`. 무엇을 주는지와 조립은 [README.md](README.md)에 있다.
|
||||
|
||||
## 책임
|
||||
|
||||
- 업로드(`controller`, tus `tus`, IETF draft-12 `draft12`)·다운로드·파일 삭제와 복사·이동(`lifecycle`)·관리(`admin`) HTTP endpoint와 그 요청 해석(`mapper`).
|
||||
- 다운로드의 Range·조건부 요청 해석과 응답 계획(`http`의 `HttpDownloadPlanner`, `HttpRangeResolver`).
|
||||
- 실패를 Envelope로 바꾸는 `problem`(`FileserverExceptionHandler`, `FileserverProblemHeaders`), 전송 worker pool(`config.BlockingTransferExecutor`), nginx `X-Accel-Redirect`(`nginx`).
|
||||
- CORS 노출 헤더 기여(`config.FileserverHttpSurfaceConfiguration`).
|
||||
|
||||
## 규칙
|
||||
|
||||
- 전송은 업로드 이름을 지어 넣지 않는다. 받은 이름이 없으면 빈 이름을 넘기고 `application-fileserver`의 `OriginalFilenamePolicy`가 정한다.
|
||||
- `Retry-After`는 본문 `retryable`과 같은 규칙으로 붙인다: code가 재시도를 허락하고 그 발생도 재시도 가능할 때만.
|
||||
- batch 업로드는 공용 bulk envelope(web AGENTS B8)다. 부분 실패는 `success: false` + `BATCH_PARTIAL_FAILURE`다.
|
||||
- 새 응답 헤더를 쓰면 `FileserverHttpSurfaceConfiguration`의 CORS 노출 목록에 같은 변경에서 더한다.
|
||||
- `adapter:inbound:web`의 inbound 규칙이 그대로 적용된다: repository 접근 없음, 업무 규칙 없음.
|
||||
|
||||
## 테스트
|
||||
|
||||
```bash
|
||||
./gradlew :adapter:inbound:web-fileserver:test --console=plain
|
||||
```
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -0,0 +1,32 @@
|
||||
# adapter:inbound:web-fileserver
|
||||
|
||||
파일 서버의 HTTP 표면을 담는 leaf다. 업로드·다운로드 protocol을 유스케이스 호출로 바꾼다.
|
||||
|
||||
## 책임과 소유하지 않는 것
|
||||
|
||||
- 업로드(`controller`, tus `tus`, IETF draft-12 `draft12`)·다운로드·파일 삭제와 복사·이동(`lifecycle`)·관리(`admin`) HTTP endpoint와 그 요청 해석(`mapper`).
|
||||
- 다운로드의 Range·조건부 요청 해석과 응답 계획(`http`의 `HttpDownloadPlanner`, `HttpRangeResolver`).
|
||||
- 실패를 Envelope로 바꾸는 `problem`(`FileserverExceptionHandler`, `FileserverProblemHeaders`), 전송 worker pool(`config.BlockingTransferExecutor`), nginx `X-Accel-Redirect`(`nginx`).
|
||||
- CORS 노출 헤더 기여(`config.FileserverHttpSurfaceConfiguration`).
|
||||
- 소유하지 않는 것: 할당량·표시 이름 같은 정책(`application-fileserver`), 바이트 저장(`adapter:outbound:fileserver`), 공용 Envelope 처리(`adapter:inbound:web`).
|
||||
|
||||
## 공개 표면
|
||||
|
||||
HTTP endpoint(`docs/fileserver/http-contract.md` 「공개 endpoint」·「관리 endpoint」), 오류 code 표(같은 문서 「오류 코드」). 설정 prefix는 없다(`app.fileserver-platform.*`는 `adapter:outbound:fileserver`의 것).
|
||||
|
||||
## 조립
|
||||
|
||||
직접 더하지 않는다. `runtimeOnly project(':composition:fileserver-platform')` 한 줄이 이 leaf를 함께 싣고, 조립 모듈이 이 leaf의 설정 class를 import한다. 끄는 키는 `APP_FILESERVER_PLATFORM_ENABLED`다.
|
||||
|
||||
## 테스트 명령
|
||||
|
||||
```bash
|
||||
./gradlew :adapter:inbound:web-fileserver:test --console=plain
|
||||
```
|
||||
|
||||
## 더 읽을 곳
|
||||
|
||||
- [AGENTS.md](AGENTS.md)(이 leaf의 규칙)
|
||||
- `docs/fileserver/http-contract.md`(HTTP 계약 정본)
|
||||
- `src/adapter/inbound/web/AGENTS.md`(요청 경계, bulk envelope)
|
||||
- `src/bootstrap/fileserver-platform/README.md`(조립)
|
||||
@@ -0,0 +1,31 @@
|
||||
# adapter:inbound:web-notification — 알림 플랫폼의 HTTP 표면
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-inbound-web-notification`
|
||||
- Gradle 경로: `:adapter:inbound:web-notification`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:inbound:web-notification:test --console=plain`
|
||||
- registry 정본: `gradle/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.adapter.inbound.web.notification`. 무엇을 주는지와 조립은 [README.md](README.md)에 있다.
|
||||
|
||||
## 책임
|
||||
|
||||
- 알림 제출(`NotificationSubmissionController`)과 template 게시(`NotificationTemplateController`) HTTP endpoint.
|
||||
- provider callback 수신(`NotificationCallbackMvcController`)과 그 경로만 덮는 보안 chain(`CallbackMvcSecurityConfiguration`).
|
||||
- 요청 DTO를 `application-notification`의 command로 바꾼다. 업무 판정은 하지 않는다.
|
||||
|
||||
## 규칙
|
||||
|
||||
- controller는 변환만 한다. 모르는 channel·slot·locale은 그 필드를 짚는 `400 VALIDATION_FAILED`로 거절하고, 발송 판정은 유스케이스에 넘긴다.
|
||||
- callback 경로는 presentation prefix를 받지 않는 절대 경로다. provider에 한 번 등록한 URL이 prefix 변경으로 움직이면 안 된다(`NotificationRoutePrefixTest`).
|
||||
- callback chain은 인증 없이 연다. 서명 검증은 이 leaf의 `ProviderCallbackIngress`에 맡긴다. 구현은 `composition:notification-platform`의 `ProviderCallbackIngressBridge`이고, `adapter:outbound:notification`의 provider adapter(`ProviderCallbackAdapterRegistry`, SES는 `SnsSignatureVerifier`)로 검증한 뒤 검증된 event만 유스케이스에 넘긴다. 유스케이스는 서명을 보지 않는다.
|
||||
- 그 `permitAll`은 공개 경로 스냅숏(`docs/security/public-paths-snapshot.txt`)에 들어 있다. callback 경로를 바꾸면 스냅숏도 바뀐다.
|
||||
- callback 응답은 Envelope 규칙의 예외다. 본문 없이 204(받음, 중복도 같다)·400(서명·형식 거절)·413(본문 한도)·503(검증을 못 돌림, `Retry-After`)만 답한다. 인증 전 경로라 거절 이유를 싣지 않고, provider는 status만 본다(4xx면 멈추고 5xx면 다시 보낸다). 본문을 더하거나 status를 바꾸면 provider의 재전송 동작이 바뀐다(`NotificationCallbackMvcController` Javadoc).
|
||||
- `adapter:inbound:web`의 inbound 규칙이 그대로 적용된다: repository 접근 없음, DTO를 application으로 넘기지 않음.
|
||||
|
||||
## 테스트
|
||||
|
||||
```bash
|
||||
./gradlew :adapter:inbound:web-notification:test --console=plain
|
||||
```
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -0,0 +1,31 @@
|
||||
# adapter:inbound:web-notification
|
||||
|
||||
알림 플랫폼의 HTTP 표면을 담는 leaf다. 요청을 유스케이스 command로 바꾼다. 제출·template 게시는 Envelope로 답하고, provider callback은 본문 없이 status만 답한다.
|
||||
|
||||
## 책임과 소유하지 않는 것
|
||||
|
||||
- 알림 제출(`NotificationSubmissionController`)과 template 게시(`NotificationTemplateController`) HTTP endpoint.
|
||||
- provider callback 수신(`NotificationCallbackMvcController`)과 그 경로만 덮는 보안 chain(`CallbackMvcSecurityConfiguration`).
|
||||
- 요청 DTO를 `application-notification`의 command로 바꾼다. 업무 판정은 하지 않는다.
|
||||
- 소유하지 않는 것: 발송 판정(`application-notification`), callback 서명 검증과 provider 호출(`adapter:outbound:notification`, `composition:notification-platform`이 `ProviderCallbackIngress`로 이어 준다), 공용 오류 처리(`adapter:inbound:web`).
|
||||
|
||||
## 공개 표면
|
||||
|
||||
HTTP endpoint 셋(경로는 `docs/notification/`과 각 controller 주석), 권한 `notification:submit`·`notification-template:publish`. 설정 prefix는 없다.
|
||||
|
||||
## 조립
|
||||
|
||||
직접 더하지 않는다. `runtimeOnly project(':composition:notification-platform')` 한 줄이 이 leaf를 함께 싣고, 이 leaf의 `NotificationWebAutoConfiguration`이 켜진다. 끄는 키는 `APP_NOTIFICATION_PLATFORM_ENABLED`다.
|
||||
|
||||
## 테스트 명령
|
||||
|
||||
```bash
|
||||
./gradlew :adapter:inbound:web-notification:test --console=plain
|
||||
```
|
||||
|
||||
## 더 읽을 곳
|
||||
|
||||
- [AGENTS.md](AGENTS.md)(이 leaf의 규칙)
|
||||
- `src/adapter/inbound/web/AGENTS.md`(요청 경계 B1~B8, 직렬화 S1~S4)
|
||||
- `docs/notification/`(callback 대조, provider runbook)
|
||||
- `src/bootstrap/notification-platform/README.md`(조립)
|
||||
@@ -329,9 +329,8 @@ rate-limit 어댑터가 있다고 SDK 명령 정책이 강제된다고 짐작하
|
||||
`redisContainerContractTest`는 cache-region, lease, 멱등성 store 포트 계약(메모리 fake가 통과하는 것. 멱등성 계약의
|
||||
시간 있는 경우는 여기서 서버 자신의 시계로 돌고, `test`에서는 명령 fake의 시계로 돈다 — 후자는 program 자체가 아니라
|
||||
fixture가 가진 program 사본을 증명한다)과 살아 있는 semantic 포트 시험을, standalone topology의 ACL 파일 아래에서 스스로
|
||||
띄운 Redis에 대고 돌린다. `integrationCheck`(`main.yml`의 `integration` job)에 있고 거기에만 있다:
|
||||
`mainCheck`에도 적었을 때는 main push마다 두 번 돌았다. image는 `gradle/container-images.properties`의
|
||||
`redis`다.
|
||||
띄운 Redis에 대고 돌린다. `integrationCheck`에 있고 거기에만 있다. `main.yml`의 `main` job이
|
||||
`./gradlew :integrationCheck :mainCheck`로 둘을 함께 돌린다. image는 `gradle/container-images.properties`의 `redis`다.
|
||||
|
||||
살아 있는 Redis·topology 검증은 빠른 단위 시험과 따로다. 특정 Redis topology나 ACL 배치에 대한 릴리스 주장에는 그에
|
||||
맞는 살아 있는 검증 lane이 필요하다. 메모리 gateway는 결정적인 계약 시험을 위한 것이지, 외부 Redis 배포가 같은
|
||||
|
||||
@@ -71,12 +71,10 @@ redisTopologyLane {
|
||||
// the same defect (05-02, 05-03). The image is gradle/container-images.properties' `redis`,
|
||||
// and the ACL file is the one the development stack and the redis-sdk topologies share
|
||||
// (compose/redis/acl), so the accounts and their rights are the standalone
|
||||
// topology's. Integration category, so integrationCheck runs it — main.yml's `integration` job, on
|
||||
// every push to main and nightly. It is deliberately not in this leaf's mainCheck as well: `main` and
|
||||
// `integration` are two jobs of the same workflow run, so a
|
||||
// lane in both started a second Redis container and ran every live contract twice per push without
|
||||
// covering anything the first run did not (found while fixing review 2026-11-03). Sentinel, cluster
|
||||
// and TLS remain the topology lane's.
|
||||
// topology's. Integration category, so integrationCheck runs it — main.yml's `main` job runs
|
||||
// `./gradlew :integrationCheck :mainCheck` on every push to main and nightly. It is not in this leaf's
|
||||
// mainCheck as well: one stage is where a lane is owned, and verifyStrictLaneStages names that stage.
|
||||
// Sentinel, cluster and TLS remain the topology lane's.
|
||||
def redisAclDirectory = rootProject.projectDir.toPath().resolve('compose/redis/acl').toFile()
|
||||
strictTestLanes {
|
||||
lane('redisContainerContractTest') {
|
||||
|
||||
@@ -230,12 +230,10 @@ strictTestLanes {
|
||||
// the deadline and evidence contracts against real TCP faults — a slow drip, a cut stream, a refused
|
||||
// connect — and review 2026-11-01 05-06/05-16 put it in the main stage because it was reachable only
|
||||
// through integrationCheck, which then ran on no main-branch build. That premise no longer holds:
|
||||
// main.yml's `integration` job runs integrationCheck (an integration lane, so this one) on every push
|
||||
// to main and nightly, in the same workflow run as the `main` job. In both
|
||||
// stages, every main push started a second Toxiproxy and httpbin and ran every fault twice without
|
||||
// covering anything the first run did not (review 2026-11-03 README §8, closed in round 9; the
|
||||
// cache-redis container lane left mainCheck for the same reason). verifyStrictLaneStages still fails
|
||||
// if no executed stage reaches it. It stays out of `check` for the reason above.
|
||||
// main.yml's `main` job runs `./gradlew :integrationCheck :mainCheck` (an integration lane, so this
|
||||
// one) on every push to main and nightly. One stage owns the lane, so it is in integrationCheck only
|
||||
// (the cache-redis container lane likewise). verifyStrictLaneStages still fails if no executed stage
|
||||
// reaches it. It stays out of `check` for the reason above.
|
||||
tasks.named('mainCheck') {
|
||||
dependsOn 'spring70CompatibilityTest'
|
||||
}
|
||||
|
||||
@@ -44,7 +44,7 @@ transfer와 multipart는 코드가 없다: 조립되지 않은 구현을 지웠
|
||||
이 줄을 지우면 port 구현, provider, 설정 바인딩이 모두 함께 빠진다.
|
||||
- 켜기와 끄기: 모듈이 있으면 켜진다. `app.object-storage.enabled=false`로만 끄고, 그때 모듈은 아무
|
||||
bean도 두지 않는다.
|
||||
- env 키: 전용 `APP_*` 키는 없다. provider·destination이 map 구조라 배포의 `application-*.yml`에
|
||||
- env 키: `APP_OBJECTSTORAGE_ENABLED`(끄기) 하나뿐이다. provider·destination은 map 구조라 배포의 `application-*.yml`에
|
||||
`app.object-storage.{default-destination, providers.<id>.*, destinations.<id>.*}`를 적는다(아래
|
||||
「켜기와 라우팅」). 빠지면 기동 시 binding compile이 실패한다.
|
||||
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
# adapter:outbound:redis-runtime — Redis 연결과 명령 실행의 공용 runtime
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `adapter-outbound-redis-runtime`
|
||||
- Gradle 경로: `:adapter:outbound:redis-runtime`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :adapter:outbound:redis-runtime:test --console=plain`
|
||||
- registry 정본: `gradle/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.adapter.outbound.cache.redis.runtime`. 무엇을 주는지와 조립은 [README.md](README.md)에 있다.
|
||||
|
||||
## 책임
|
||||
|
||||
- Redis 연결(standalone·sentinel·cluster·TLS)과 그 수명(`connection`의 `RedisRuntimeClient`, lane·account), 의미 단위 명령(`command.SemanticRedisCommands`), key 규칙(`key`), 설정(`config`의 `app.redis.*`, `RedisRuntimeSettings`)과 health.
|
||||
- `cache-redis`와 `redis-sdk`가 같은 연결 하나를 쓰게 하는 바닥이다. 업무 포트를 구현하지 않는다.
|
||||
- testFixtures: 메모리 명령(`InMemorySemanticRedisCommands`), stub client, 실 topology endpoint(`RedisTopologyEndpoint`). 두 위 leaf의 시험이 쓴다.
|
||||
|
||||
## 규칙
|
||||
|
||||
- 어떤 프로젝트 leaf에도 의존하지 않는다(registry 허용 의존이 비어 있다). application 포트를 모른다.
|
||||
- 설정 트리는 `app.redis.*`다(manual 10 기준 4의 Redis 예외: setter + `validate()`). 새 트리를 만들지 않는다.
|
||||
- 연결은 `RedisRuntimeClient` 하나를 함께 쓴다. 위 leaf가 Lettuce 연결을 따로 열지 않는다.
|
||||
- 실 topology 검증은 `ca.redis-topology-lane`의 topology lane이다. 좌표를 받아야 도는 lane이라 명시적으로만 돈다.
|
||||
|
||||
## 테스트
|
||||
|
||||
```bash
|
||||
./gradlew :adapter:outbound:redis-runtime:test --console=plain
|
||||
```
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -0,0 +1,34 @@
|
||||
# adapter:outbound:redis-runtime
|
||||
|
||||
Redis 연결과 명령 실행의 공용 runtime을 담는 leaf다. 업무 포트는 `cache-redis`가 구현하고, `redis-sdk`는 서비스 코드가 직접 부르는 SDK 표면을 준다(bean도 포트 구현도 없다).
|
||||
|
||||
## 책임과 소유하지 않는 것
|
||||
|
||||
- Redis 연결(standalone·sentinel·cluster·TLS)과 그 수명(`connection`의 `RedisRuntimeClient`, lane·account), 의미 단위 명령(`command.SemanticRedisCommands`), key 규칙(`key`), 설정(`config`의 `app.redis.*`, `RedisRuntimeSettings`)과 health.
|
||||
- `cache-redis`와 `redis-sdk`가 같은 연결 하나를 쓰게 하는 바닥이다. 업무 포트를 구현하지 않는다.
|
||||
- testFixtures: 메모리 명령(`InMemorySemanticRedisCommands`), stub client, 실 topology endpoint(`RedisTopologyEndpoint`). 두 위 leaf의 시험이 쓴다.
|
||||
- 소유하지 않는 것: cache·rate-limit·lease·멱등성 포트 구현(`adapter:outbound:cache-redis`), Redis SDK 표면(`adapter:outbound:redis-sdk`).
|
||||
|
||||
## 공개 표면
|
||||
|
||||
`connection.RedisRuntimeClient`, `command.SemanticRedisCommands`, key 타입, 설정 `app.redis.*`(env `APP_REDIS_*`, `docs/registries/env-keys.yaml`). 기본값은 `RedisRuntimeSettings`의 Java 기본값이고, `app.redis.enabled`만 cache-redis의 `config/module-defaults/cache-redis.yml`이 정한다. 이 leaf의 `config/module-defaults/redis-runtime.yml`은 health 상태 순서만 싣는다.
|
||||
|
||||
## 조립
|
||||
|
||||
직접 더하지 않는다. 이 leaf를 싣는 길은 둘이다.
|
||||
|
||||
- `runtimeOnly project(':adapter:outbound:cache-redis')`: cache-redis의 기본값(`app.redis.enabled: ${APP_REDIS_ENABLED:true}`)이 함께 와서 `RedisRuntimeAutoConfiguration`이 켜진다. 끄는 키는 `APP_REDIS_ENABLED`다.
|
||||
- `implementation project(':adapter:outbound:redis-sdk')`: SDK가 이 leaf를 `api`로 싣는다. 이 길에는 cache-redis 기본값이 없고 `RedisRuntimeAutoConfiguration`은 `app.redis.enabled=true`일 때만 켜지므로, `APP_REDIS_ENABLED=true`를 직접 준다(`src/adapter/outbound/redis-sdk/README.md` 「env 키」).
|
||||
|
||||
## 테스트 명령
|
||||
|
||||
```bash
|
||||
./gradlew :adapter:outbound:redis-runtime:test --console=plain
|
||||
```
|
||||
|
||||
## 더 읽을 곳
|
||||
|
||||
- [AGENTS.md](AGENTS.md)(이 leaf의 규칙)
|
||||
- `src/adapter/outbound/cache-redis/AGENTS.md`(Redis 설정 트리의 이유, capability)
|
||||
- `docs/redis/`(명령 정책, 운영, 지원 표)
|
||||
- `src/adapter/outbound/redis-sdk/compose/README.md`(topology lane 좌표)
|
||||
@@ -0,0 +1,29 @@
|
||||
# application-fileserver — 파일 서버의 유스케이스와 정책
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `application-fileserver`
|
||||
- Gradle 경로: `:application-fileserver`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :application-fileserver:test --console=plain`
|
||||
- registry 정본: `gradle/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.application.fileserver`. 무엇을 주는지와 조립은 [README.md](README.md)에 있다.
|
||||
|
||||
## 책임
|
||||
|
||||
- 업로드(단일·raw·batch·이어 쓰기)·다운로드·복사·이동·삭제·정리의 유스케이스와 그 정책(할당량, 전송 허가, 표시 이름).
|
||||
- 들어오는 포트(`port.in`), 나가는 포트, 오류 어휘 `api.error.FileserverErrorCode`(HTTP 표는 `docs/fileserver/http-contract.md` 「오류 코드」).
|
||||
- testFixtures `testkit`: 저장·대기열 포트의 공유 계약(`*PortContract`)과 in-memory 구현, 내용 gateway·정책의 fake. 모든 포트에 계약이 있지는 않다(다운로드·zero-copy·사용량·지표 포트는 없다).
|
||||
|
||||
## 규칙
|
||||
|
||||
- framework 의존이 없다(`ca.java-library`). 허용 의존은 registry의 `application-core`·`shared-contract`뿐이다.
|
||||
- 업로드 이름의 표시 규칙은 `api.security.OriginalFilenamePolicy` 한 곳이다. 이름 없는 업로드의 이름도 여기서 정한다. 전송이 기본 이름을 지어 넣지 않는다.
|
||||
- 전송 허가(`quota.TransferAdmissionController`)는 호출자 자신의 동시 전송 초과를 `TRANSFER_ADMISSION_REJECTED`(429), instance 전체 포화를 `SERVER_BUSY`(503)로 가른다.
|
||||
- `FileserverErrorCode`에 code를 더하면 `docs/fileserver/http-contract.md` 「오류 코드」 표에 같은 변경에서 행을 더한다.
|
||||
|
||||
## 테스트
|
||||
|
||||
```bash
|
||||
./gradlew :application-fileserver:test --console=plain
|
||||
```
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -0,0 +1,31 @@
|
||||
# application-fileserver
|
||||
|
||||
파일 서버의 유스케이스와 정책을 담는 leaf다. HTTP·저장소·조립은 각각 다른 leaf가 한다.
|
||||
|
||||
## 책임과 소유하지 않는 것
|
||||
|
||||
- 업로드(단일·raw·batch·이어 쓰기)·다운로드·복사·이동·삭제·정리의 유스케이스와 그 정책(할당량, 전송 허가, 표시 이름).
|
||||
- 들어오는 포트(`port.in`), 나가는 포트, 오류 어휘 `api.error.FileserverErrorCode`(HTTP 표는 `docs/fileserver/http-contract.md` 「오류 코드」).
|
||||
- testFixtures `testkit`: 저장·대기열 포트의 공유 계약(`*PortContract`)과 in-memory 구현, 내용 gateway·정책의 fake. 모든 포트에 계약이 있지는 않다(다운로드·zero-copy·사용량·지표 포트는 없다).
|
||||
- 소유하지 않는 것: HTTP 모양(`adapter:inbound:web-fileserver`), 바이트 저장(`adapter:outbound:fileserver`), metadata 저장(`adapter:outbound:persistence-fileserver`), 조립(`composition:fileserver-platform`).
|
||||
|
||||
## 공개 표면
|
||||
|
||||
들어오는 포트 `port.in`(예: `CreateUploadUseCase`, `AppendUploadUseCase`, `DescribeFileUseCase`, `ForceDeleteFileUseCase`), 오류 `api.error`, 정책 `api.security`·`quota`. 설정 prefix는 없다(설정은 `adapter:outbound:fileserver`의 `app.fileserver-platform.*`).
|
||||
|
||||
## 조립
|
||||
|
||||
직접 더하지 않는다. `runtimeOnly project(':composition:fileserver-platform')` 한 줄이 유스케이스와 HTTP 표면을 함께 싣는다. 끄는 키는 `APP_FILESERVER_PLATFORM_ENABLED`다.
|
||||
|
||||
## 테스트 명령
|
||||
|
||||
```bash
|
||||
./gradlew :application-fileserver:test --console=plain
|
||||
```
|
||||
|
||||
## 더 읽을 곳
|
||||
|
||||
- [AGENTS.md](AGENTS.md)(이 leaf의 규칙)
|
||||
- `docs/fileserver/`(HTTP 계약, 설정, 운영, 보안)
|
||||
- `src/adapter/outbound/fileserver/README.md`(저장소 adapter)
|
||||
- `src/bootstrap/fileserver-platform/README.md`(조립)
|
||||
@@ -0,0 +1,29 @@
|
||||
# application-notification — 알림 플랫폼의 유스케이스와 포트
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `application-notification`
|
||||
- Gradle 경로: `:application-notification`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :application-notification:test --console=plain`
|
||||
- registry 정본: `gradle/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.application.notification`. 무엇을 주는지와 조립은 [README.md](README.md)에 있다.
|
||||
|
||||
## 책임
|
||||
|
||||
- 알림 플랫폼의 업무 흐름: 제출·예약·취소·조회, template 게시, provider callback 수집, 발송 판정과 재시도 정책.
|
||||
- 들어오는 포트(`platform.port.in`의 `*UseCase`·`*Command`·`*Query`), 나가는 포트(쓰는 흐름의 패키지에 있다: `platform.dispatch`·`platform.callback`·`platform.policy`·`platform.observation`·`platform.admin`·`platform.inbox`·`platform.template`·`platform.provider`·`platform.security`), 오류 어휘(`platform.api.error`). `port.out` 패키지는 따로 없다. 나가는 포트 이름은 대개 `*Port`지만 아닌 것도 있다: `provider.NotificationProviderAdapter`·`BatchNotificationProviderAdapter`·`AttachmentResolver`, `security.SecretMaterialProvider`·`ContactPointProtector`, `template.TemplateRegistry`, `callback.ProviderEventLedger`. 새 포트를 만들기 전에 이 이름들도 찾는다.
|
||||
- testFixtures(흐름 패키지의 `testkit`): 저장 포트의 in-memory fake와 공유 계약(`*Contract`), provider adapter 계약(`ProviderAdapterContract`). 모든 포트에 있지는 않다. adapter의 시험이 같은 계약을 상속한다.
|
||||
|
||||
## 규칙
|
||||
|
||||
- framework 의존이 없다(`ca.java-library`). Spring·JPA·HTTP 타입을 쓰지 않는다. 허용 의존은 registry의 `application-core`·`shared-contract`뿐이다.
|
||||
- 전송 DTO(HTTP 요청·응답 record)를 여기에 두지 않는다. 전송 모양은 `adapter:inbound:web-notification`의 것이다.
|
||||
- 발송 판정(마케팅 억제, category 필수)은 여기서 한다. 전송이나 설정에서 기본값을 골라 넣지 않는다.
|
||||
- 공개 타입이 늘면 `docs/notification/api-surface-snapshot.txt`가 바뀐다(`adapter:outbound:notification`의 `verifyNotificationApiSurface`가 이 leaf까지 본다).
|
||||
|
||||
## 테스트
|
||||
|
||||
```bash
|
||||
./gradlew :application-notification:test --console=plain
|
||||
```
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -0,0 +1,31 @@
|
||||
# application-notification
|
||||
|
||||
알림 플랫폼의 유스케이스와 포트를 담는 leaf다. 알림을 제출하는 HTTP·발송 provider·저장은 각각 다른 leaf가 한다.
|
||||
|
||||
## 책임과 소유하지 않는 것
|
||||
|
||||
- 알림 플랫폼의 업무 흐름: 제출·예약·취소·조회, template 게시, provider callback 수집, 발송 판정과 재시도 정책.
|
||||
- 들어오는 포트(`platform.port.in`의 `*UseCase`·`*Command`·`*Query`), 나가는 포트(쓰는 흐름의 패키지에 있다: `platform.dispatch`·`platform.callback`·`platform.policy`·`platform.observation`·`platform.admin`·`platform.inbox`·`platform.template`·`platform.provider`·`platform.security`), 오류 어휘(`platform.api.error`). `port.out` 패키지는 따로 없다. 나가는 포트 이름은 대개 `*Port`지만 아닌 것도 있다: `provider.NotificationProviderAdapter`·`BatchNotificationProviderAdapter`·`AttachmentResolver`, `security.SecretMaterialProvider`·`ContactPointProtector`, `template.TemplateRegistry`, `callback.ProviderEventLedger`. 새 포트를 만들기 전에 이 이름들도 찾는다.
|
||||
- testFixtures(흐름 패키지의 `testkit`): 저장 포트의 in-memory fake와 공유 계약(`*Contract`), provider adapter 계약(`ProviderAdapterContract`). 모든 포트에 있지는 않다. adapter의 시험이 같은 계약을 상속한다.
|
||||
- 소유하지 않는 것: HTTP 모양(`adapter:inbound:web-notification`), provider 호출·설정(`adapter:outbound:notification`), 저장(`adapter:outbound:persistence-notification`), 조립(`composition:notification-platform`).
|
||||
|
||||
## 공개 표면
|
||||
|
||||
들어오는 포트 `platform.port.in`(예: `SubmitNotificationUseCase`, `PublishNotificationTemplateUseCase`, `IngestProviderCallbackUseCase`), 흐름 패키지의 나가는 포트(`*Port`와 위의 이름들), 오류 `platform.api.error`. 설정 prefix는 없다(설정은 `adapter:outbound:notification`의 `app.notification.platform.*`).
|
||||
|
||||
## 조립
|
||||
|
||||
직접 더하지 않는다. `runtimeOnly project(':composition:notification-platform')` 한 줄이 유스케이스를 조립하고 이 leaf를 함께 싣는다. 끄는 키는 `APP_NOTIFICATION_PLATFORM_ENABLED`다.
|
||||
|
||||
## 테스트 명령
|
||||
|
||||
```bash
|
||||
./gradlew :application-notification:test --console=plain
|
||||
```
|
||||
|
||||
## 더 읽을 곳
|
||||
|
||||
- [AGENTS.md](AGENTS.md)(이 leaf의 규칙)
|
||||
- `src/adapter/outbound/notification/README.md`(플랫폼 전체, 설정)
|
||||
- `docs/notification/`(지원 표, 운영, callback 대조)
|
||||
- `src/bootstrap/notification-platform/README.md`(조립)
|
||||
@@ -0,0 +1,27 @@
|
||||
# application-objectstorage — 객체 저장소 포트
|
||||
|
||||
## 등록 정보
|
||||
|
||||
- 모듈 ID: `application-objectstorage`
|
||||
- Gradle 경로: `:application-objectstorage`
|
||||
- 이 모듈만 시험(Gradle 경로에서 나온 명령): `./gradlew :application-objectstorage:test --console=plain`
|
||||
- registry 정본: `gradle/modules.json`.
|
||||
|
||||
패키지 루트: `dev.caskeleton.application.objectstorage`. 무엇을 주는지와 조립은 [README.md](README.md)에 있다.
|
||||
|
||||
## 책임
|
||||
|
||||
- 객체 저장소를 쓰는 쪽이 보는 포트와 그 값 타입: 전송(`ObjectTransferPort`), 검사, 게시(staged·managed), 회수, 결과 확인.
|
||||
- `model`·`request`·`identity`·`content`의 값 타입. 구현은 `adapter:outbound:objectstorage` 하나다.
|
||||
|
||||
## 규칙
|
||||
|
||||
- framework·AWS SDK 의존이 없다(`ca.java-library`). 허용 의존은 registry의 `application-core`·`shared-contract`뿐이다.
|
||||
- S3·MinIO 개념(bucket 정책, presign 구현)은 adapter의 것이다. 포트는 저장소에 상관없는 말로 쓴다.
|
||||
- 이 leaf에는 포트 계약 시험이 아직 없다. adapter testFixtures의 `ObjectStorageProviderContract`는 adapter 안의 provider SPI를 시험하고, 이 leaf의 포트는 시험하지 않는다. 값 타입(`model`·`request`·`identity`·`content`)을 바꾸면 그 provider 계약을 같은 변경에서 고친다.
|
||||
|
||||
## 테스트
|
||||
|
||||
```bash
|
||||
./gradlew :application-objectstorage:test --console=plain
|
||||
```
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -0,0 +1,30 @@
|
||||
# application-objectstorage
|
||||
|
||||
객체 저장소 포트와 그 값 타입을 담는 leaf다. 구현은 `adapter:outbound:objectstorage` 하나다.
|
||||
|
||||
## 책임과 소유하지 않는 것
|
||||
|
||||
- 객체 저장소를 쓰는 쪽이 보는 포트와 그 값 타입: 전송(`ObjectTransferPort`), 검사, 게시(staged·managed), 회수, 결과 확인.
|
||||
- `model`·`request`·`identity`·`content`의 값 타입. 구현은 `adapter:outbound:objectstorage` 하나다.
|
||||
- 소유하지 않는 것: S3·MinIO 호출과 설정(`adapter:outbound:objectstorage`), 파일 서버의 업로드 흐름(`application-fileserver`).
|
||||
|
||||
## 공개 표면
|
||||
|
||||
`port`의 포트(`ObjectTransferPort`, `ObjectInspectionPort`, `StagedObjectPublicationPort`, `ManagedObjectPublicationPort`, `ObjectRetirementPort` 등)와 값 타입. 설정 prefix는 없다(`app.object-storage.*`는 adapter의 것).
|
||||
|
||||
## 조립
|
||||
|
||||
직접 더하지 않는다. `runtimeOnly project(':adapter:outbound:objectstorage')` 한 줄이 이 leaf를 함께 싣는다. 끄는 키는 `APP_OBJECTSTORAGE_ENABLED`다.
|
||||
|
||||
## 테스트 명령
|
||||
|
||||
```bash
|
||||
./gradlew :application-objectstorage:test --console=plain
|
||||
```
|
||||
|
||||
## 더 읽을 곳
|
||||
|
||||
- [AGENTS.md](AGENTS.md)(이 leaf의 규칙)
|
||||
- `src/adapter/outbound/objectstorage/README.md`(adapter, 설정, MinIO lane)
|
||||
- `docs/objectstorage/env-fields.yaml`(env 칸)
|
||||
- `docs/storage-capability-boundary.md`(파일 서버와의 경계)
|
||||
@@ -15,13 +15,18 @@ tracing 이음매, domain-context 전파)은 [README.md](README.md)에 있다.
|
||||
남는다.
|
||||
|
||||
## 책임 (Responsibility)
|
||||
- 응답 envelope(`response/Envelope`, `response/ApiError`, `response/BulkEnvelope`, `response/BulkItemResult`).
|
||||
- 오류 코드 계약(`error/ApiErrorCode` 인터페이스, `error/OperationalError` enum,
|
||||
- 응답 envelope(`response/Envelope`, `response/ApiError`, `response/BulkEnvelope`, `response/BulkItemResult`)와 그 meta
|
||||
(`response/ResponseMeta`, 목록의 `response/PageMeta`).
|
||||
- 오류 코드 계약(`error/ApiErrorCode` 인터페이스, `error/Category`, `error/OperationalError` enum,
|
||||
`error/ApiErrorCarrier`)과 클라이언트에 보여 줄 문구 표 하나(`error/ClientErrorMessages`.
|
||||
한국어이고 `Category`마다 문구 하나이며 모든 전송 계층이 쓴다).
|
||||
- 전송이 같은 규칙으로 읽는 공용 carrier 예외(`error/DependencyFailureException`,
|
||||
`error/PersistenceFailureException`, `error/AdapterDisabledException`)와 서버 실패 로그 한 줄의 모양
|
||||
(`error/ServerFailureLog`. 모든 전송이 같은 레벨·키로 남긴다).
|
||||
- 계층을 가로지르는 mapper 표지 예외(`error/MappingException`).
|
||||
- 요청 값 계약(`request/Patch`).
|
||||
- tracing 계약 타입(`tracing/TraceParent`, `tracing/SpanErrorRecorder`) — W3C `traceparent` 값 타입과
|
||||
- tracing 계약 타입(`tracing/TraceParent`, `tracing/SpanErrorRecorder`, `tracing/ActiveTrace`) — W3C `traceparent` 값 타입,
|
||||
지금 trace를 읽는 이음매와
|
||||
span 오류 기록 이음매(feature-distributed-tracing-contract. OTel tracer 런타임은 fork가 켜는
|
||||
이음매라서 이 타입들은 Java 표준 라이브러리만 쓴다).
|
||||
- 모든 leaf가 복사해 쓰던 표준 라이브러리 도우미(2026-09-25 리뷰 후속으로 여기로 옮겼다):
|
||||
|
||||
Reference in New Issue
Block a user