review-followup Wave 3 라운드 3(P28·P29): fileserver use case·file:* 권한, 보안 파일 primitive 공용화, jvm-test-suite
- 결정 32: fileserver transport 연산 21개를 `port.in` use case로, 쓰기·읽기에 `file:*` 권한(소유자·tenant 정책은 유지), inbound 서비스 이름 `*UseCase`, port 구현 이름 `<Tech><Port>` 규칙(S2-#13b, 24개) - 디렉터리 descriptor 파일 primitive를 `adapter:outbound:support`로(S4-lead-2 일부 — fileserver는 번역만), persistence-fileserver를 scan·클래스별 조건 대신 명시적 `@Bean` 설정으로(S2-#8a 일부), `FileVerifier`를 adapter로 - 호출자 0인 `poster.image-attached` 이벤트 삭제, SES SDK client를 레지스트리 종료 때 close, fileserver migration V1–V5 고정 - P29: auxiliary 레인 → Gradle `jvm-test-suite`(BUILD-O3-5, build-logic 16,768 → 5,851줄), redis-sdk가 runtime을 api로(P22-new-3) - 통합: JPA API surface 기준선 재승인(이름 규칙 변경), migration lane에 V19 반영, messaging 통합 테스트가 jar 안 migration 목록 조회(ORCH-new-5) - P28·P29 에이전트가 세션 재시작으로 중단 — 커밋된 것만 합치고 결과 파일은 오케스트레이터가 확정, S6-#10a는 P30으로 검증: ./gradlew ci verifyDependencyLocks --warning-mode=fail(714 task) · mainCheck architectureCheck verifyPublicPathSnapshot :app-bootstrap:verifyEnvKeys configContractCheck · :app-bootstrap:integrationTest :sample-portfolio:integrationTest :sample-portfolio:systemTest integrationCheck · -p build-logic test · -p optional-platforms ci · releaseCheck qualificationBootJar 통과 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
09e2dd63d6
commit
0579935746
@@ -12,7 +12,7 @@ A create that fails after the record exists must end in `FAILED`, but the table
|
||||
The record therefore walks `CREATED → UPLOADING → FAILED`, which is also the honest reading: the
|
||||
upload had been admitted before it failed.
|
||||
|
||||
Pinned by `UploadApplicationServiceTest` (application-core).
|
||||
Pinned by `ResumableUploadUseCasesTest` (application-fileserver).
|
||||
|
||||
### 2. `ContentKey`'s alphabet admits a leading separator
|
||||
|
||||
@@ -28,7 +28,7 @@ Deleting a file that is mid-verification has no legal transition. The lifecycle
|
||||
with `409 FILE_NOT_READY` rather than inventing an edge, which matches the allowed-state list the
|
||||
JPA `markDeleting` statement already enforced.
|
||||
|
||||
Pinned by `FileLifecycleServiceTest`.
|
||||
Pinned by `FileLifecycleUseCasesTest`.
|
||||
|
||||
### 4. `If-Match` is specified as an ETag but the lifecycle was designed around the row version
|
||||
|
||||
@@ -36,7 +36,7 @@ The HTTP contract sends an entity tag; the metadata store guards on a numeric ve
|
||||
takes `Optional<String> expectedEtag` and compares against the record's strong validator, so the
|
||||
precondition a client sends is the precondition that is checked.
|
||||
|
||||
Pinned by `FileLifecycleServiceTest`.
|
||||
Pinned by `FileLifecycleUseCasesTest`.
|
||||
|
||||
### 5. The filename policy left `:` intact
|
||||
|
||||
@@ -174,40 +174,44 @@ an extension point for a backend this template does not ship:
|
||||
`ContentStoreCapabilities` reports what the running store actually supports, so no unimplemented SPI
|
||||
is advertised as available.
|
||||
|
||||
## Known deviation from the repository's application-layer contract
|
||||
## The repository's application-layer contract
|
||||
|
||||
### 5. Fileserver application services are not `CommandUseCase` / `QueryUseCase`
|
||||
### 5. Fileserver operations are use cases (resolved, owner decision 32)
|
||||
|
||||
`src/application-core/CLAUDE.md` requires every inbound port implementation to extend
|
||||
`CommandUseCase` or `QueryUseCase` and to carry `@UseCaseCapability`, which declares its transaction
|
||||
mode, idempotency and repository access. The Fileserver instead exposes multi-method services —
|
||||
`UploadApplicationService`, `DownloadApplicationService`, `FileLifecycleService`,
|
||||
`FileserverAdminService` and their `Default*` implementations.
|
||||
Every operation the transport reaches is a `CommandUseCase` or `QueryUseCase` behind a one-method
|
||||
port in `application.fileserver.port.in` — create, append, status, cancel, finalize and the
|
||||
single-request upload; describe, prepare, open and transfer for downloads; delete, copy and move;
|
||||
and the eight management-plane operations. Each implementation (`*ApplicationUseCase`) declares its
|
||||
`@UseCaseCapability`, so the ArchUnit rules that check transaction mode, repository access and
|
||||
outbound calls now see the Fileserver like every other feature.
|
||||
|
||||
This is a real deviation, not an oversight, and it is unenforced: the ArchUnit rules
|
||||
`inbound_port_implementations_end_with_use_case` and
|
||||
`inbound_port_implementations_declare_capability` only match types that implement `UseCase`, so a
|
||||
service that never does is silently exempt. The capability contract that every other feature in
|
||||
this repository declares is therefore absent here.
|
||||
Two authorities guard a write, and both stay:
|
||||
|
||||
Two things follow from it. The transaction mode of each operation is expressed only by which
|
||||
`TransactionPort` method the body happens to call, rather than declared and checked. And the
|
||||
application layer holds transport policy it would not hold if each operation were a use case with
|
||||
its own command: HTTP status codes on `FileserverErrorCode`, `Range` and conditional-request
|
||||
parsing in `api.transfer`, and `Content-Disposition` construction.
|
||||
| Check | Where | Decides |
|
||||
| --- | --- | --- |
|
||||
| `@RequiresPermission("file:…")` | the use case's proxy, enforced by the web adapter's method security | whether the caller's roles grant the operation at all |
|
||||
| `FileAccessPolicyPort` | inside the use case, before any side effect | the tier (read/write/admin), and that the caller owns the file in its tenant |
|
||||
|
||||
The status mapping in particular is a deliberate trade rather than an accident. It lives in
|
||||
`application-core` so the servlet transport, the reactive transport and the Nginx delegation path
|
||||
cannot answer the same failure with three different statuses. Moving it to the transport layer
|
||||
resolves the layering complaint and reintroduces exactly that drift, which is why this is an
|
||||
architecture decision rather than a cleanup.
|
||||
The permissions are `file:read` (describe, download, upload status), `file:upload` (create,
|
||||
append, finalize, cancel, the single-request upload), `file:delete`, `file:copy`, `file:move` and
|
||||
`file:admin` (every management-plane operation). `security.yml` grants them to `ROLE_FILE_READ`,
|
||||
`ROLE_FILE_WRITE` and `ROLE_FILE_ADMIN` — the fileserver's own default tier roles — so a caller
|
||||
holding a tier holds its permissions. A deployment that renames the tier roles, or supplies its own
|
||||
`FileAccessPolicyPort` under other role names, maps those names in
|
||||
`ca-skeleton.authz.role-permissions` too; `security.access-policy: unenforced` relaxes only the
|
||||
tier and ownership check, never the permission gate.
|
||||
|
||||
**Status: open, deliberately unresolved in this change set.** Closing it means roughly thirty
|
||||
command/query use cases, a decision about where the shared status vocabulary lives, and a change to
|
||||
the ArchUnit rules so a service that bypasses the contract fails the build instead of being exempt
|
||||
from it. That belongs in its own ADR with its own review, and doing it inside a correctness patch
|
||||
would mix a large mechanical refactor into changes that need to be readable.
|
||||
The resumable transfers run on the transfer pool, and method security reads the security context
|
||||
of the calling thread, so `BlockingTransferExecutor` carries the request's context onto the worker
|
||||
(`BlockingTransferExecutorSecurityContextTest`). Without it an authenticated append was refused as
|
||||
anonymous.
|
||||
|
||||
Nothing here is pinned by a test, because the deviation is the absence of a constraint. The next
|
||||
step is the ADR, not another test.
|
||||
What is not a use case is what no transport calls: `CleanupService` and
|
||||
`FileReconciliationService` are driven by background workers with no caller identity, and a
|
||||
mutating use case must declare a permission a scheduler could not hold.
|
||||
`FileserverUseCaseContractDeviationTest` freezes that list.
|
||||
|
||||
The HTTP status vocabulary on `FileserverErrorCode` stays in the application layer, for the reason
|
||||
this section used to give: the servlet transport and the Nginx delegation path must not answer the
|
||||
same failure with different statuses.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user