- 결정 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>
12 KiB
Fileserver — deviations from the design
The design specification and the implementation plan are frozen documents. Where implementation found them under-specified or self-contradicting, the resolution is recorded here rather than by editing the specification, and every entry names the test that pins the decision.
Resolved inconsistencies in the state machine and contracts
1. CREATED → FAILED has no edge in the transition table
A create that fails after the record exists must end in FAILED, but the table has no direct edge.
The record therefore walks CREATED → UPLOADING → FAILED, which is also the honest reading: the
upload had been admitted before it failed.
Pinned by ResumableUploadUseCasesTest (application-fileserver).
2. ContentKey's alphabet admits a leading separator
The design's key pattern [a-z0-9/_-]{16,200} matches /etc/passwd/.... Rejecting an absolute path
at the value type would change a design-fixed contract, so the stricter shape check lives in
PhysicalPathResolver, per §12.2 rule 1 — the only place that turns an identifier into a path.
Pinned by PhysicalPathResolverTest.
3. VERIFYING → DELETING has no edge
Deleting a file that is mid-verification has no legal transition. The lifecycle service refuses it
with 409 FILE_NOT_READY rather than inventing an edge, which matches the allowed-state list the
JPA markDeleting statement already enforced.
Pinned by FileLifecycleUseCasesTest.
4. If-Match is specified as an ETag but the lifecycle was designed around the row version
The HTTP contract sends an entity tag; the metadata store guards on a numeric version. The service
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 FileLifecycleUseCasesTest.
5. The filename policy left : intact
C:\Windows\system.ini sanitized to C:Windowssystem.ini — a drive-qualified name surviving into
display text and headers. : joined the structural strip set.
Pinned by FileserverHardeningContractTest and AmbiguousFilesystemOperationDetectorTest.
Additions the design implies but does not specify
6. fs_recovery_item
§10.2 lists five core tables and none of them can hold the recovery queue, yet §29.3 requires one:
reconciliation reports files whose bytes and metadata disagree, and holding that list in memory
would lose exactly the cases a restart interrupted. Added in
V2__fileserver_recovery_and_staging_cleanup.sql with one open item per file, so repeated sweeps
update a worklist rather than accumulating a log.
Pinned by PostgreSqlFileserverReclamationIntegrationTest.
7. fs_cleanup_item.upload_id
A staging object is addressed by upload, not by file. Without this column a queued staging cleanup could name only already-published content, so a cancelled or expired upload left bytes nothing could find. Added in the same migration, with a check constraint that an item names exactly one target.
Pinned by PostgreSqlFileserverReclamationIntegrationTest.
8. ContentReferenceLedgerPort and StagingUploadLocatorPort
The orphan scan must ask whether a record still claims a physical object, and reconciliation must
map a file back to the upload that last staged it. Neither question is answerable through the
design's FileMetadataPort or UploadSessionPort as written. Rather than widen those
design-fixed interfaces, both are narrow single-method ports.
Pinned by PostgreSqlFileserverReclamationIntegrationTest and LocalOrphanScanAdapterTest.
Interpretations
9. Quota settlement is FIFO within a scope
Nothing links a reservation row to the upload that took it, and the design deliberately reclaims
stragglers by TTL and the STALE_QUOTA_RESERVATION cleanup type rather than threading a reservation
id through the upload session. QuotaCommitPort therefore settles the oldest live reservation in
the file's namespace.
Which row closes does not change any quota decision: enforcement sums reserved and committed bytes per scope and never reads an individual row. Concurrent uploads of different sizes can leave the reserved total transiently high or low, and it converges as each settles. Durable usage with no live reservation behind it — an upload that outlived its TTL — is still recorded, because a ledger that silently under-counts is worse than one that is briefly imprecise.
Pinned by PostgreSqlFileserverReclamationIntegrationTest.
10. Zero copy is a channel transfer, not a file handoff
Task 22 asks for zero copy on local files; §19 forbids a Path leaving the storage adapter, and §5
of the plan forbids adding Path to the content store. WebFlux's zero-copy API takes a Path, so
that route is closed.
The servlet path takes the other one: ZeroCopyDownloadPort receives a WritableByteChannel from
the transport and the storage adapter performs FileChannel.transferTo into it. That is a genuine
kernel-level transfer with no filesystem concept leaving storage. The reactive path continues to
stream with bounded demand.
Zero copy is an optimization with no observable difference: when storage declines, the response is streamed and is byte-identical.
Pinned by LocalStorageGatewayContractTest and ZeroCopyEligibilityTest.
11. The Fileserver JPA stores are gated on the capability switch
The metadata store, session store, quota service, queues, ledger, and staging locator carry
@ConditionalOnProperty(app.fileserver-platform.enabled) even though the rest of
adapter:outbound:persistence-jpa is unconditional.
Without the gate, every composition root that includes the persistence module built these beans —
including sample-portfolio, which has no Fileserver — and each of them needs collaborators only
the Fileserver configuration provides. That is the same rule the design states for the transport
surface, applied to persistence: no surface appears merely because the dependency is present.
FileStateMachine is bound alongside them, in FileserverStorageConfiguration. It had no
production binding at all before, which made the metadata store unconstructible in any
component-scanned context.
Pinned by SampleApplicationContextTest (the capability off) and
FileserverRuntimeAssemblyTest (the capability on).
12. Transaction boundaries are owned by the application services, and are deliberately narrow
The design does not say where a transaction begins. The repository does:
adapter:outbound:persistence-jpa forbids a repository adapter from owning a @Transactional
boundary, and application-core owns them through TransactionPort. The Fileserver follows that
rule — every Jpa* store here declares no @Transactional of its own.
What is specific to this capability is how narrow the boundaries are. A boundary covers a contiguous run of metadata writes and stops before every storage call, because a filesystem operation inside a database transaction would hold a connection for the length of a byte transfer. The upload path therefore has three boundaries, not one: acquire the lease, transfer the bytes, commit the offset.
Where several stores must agree, they share one boundary:
| Unit | Why it is one boundary |
|---|---|
| reserve quota + insert record + create session | a reservation that outlived a failed insert holds capacity for a file that never existed |
| READY transition + quota commit | a finished file whose reservation was never converted holds capacity until the reservation expires |
markDeleting + enqueue cleanup |
a file that stopped being reachable with nothing queued to reclaim it is never collected |
| content delete settlement: reclaim + retire record + close queue item | half of it leaves the item to be retried against content that no longer exists |
What this cannot make atomic is the storage/metadata seam itself — no database boundary could. That seam is exactly what the ambiguous-completion path and the reconciler exist for, and the one hand-written compensation that remains (staging creation failing after the records committed) is there for the same reason.
Pinned by FileserverRoundTripContractTest against real PostgreSQL; the application tests use
DirectTransactions, which runs a boundary inline and counts it.
Not implemented
AsyncContentStore, CapacityAwareContentStore, CopyCapableContentStore, DelegatedDownloadStore
Four optional content-store SPIs are declared in application-core with no implementation. Each is
an extension point for a backend this template does not ship:
AsyncContentStore— for a backend whose native client is non-blocking. The local platform is blocking, and the reactive transport bridges to it on a dedicated I/O scheduler.CapacityAwareContentStore— capacity is reported throughStorageHealthPortandStorageUsagePort, which the local platform implements.CopyCapableContentStore— server-side copy is delivered byCopyContentPort; the local platform has no cheaper primitive than a streamed copy.DelegatedDownloadStore— delegation is delivered at the transport boundary by the nginxX-Accel-Redirectstrategy, which needs no store participation.
ContentStoreCapabilities reports what the running store actually supports, so no unimplemented SPI
is advertised as available.
The repository's application-layer contract
5. Fileserver operations are use cases (resolved, owner decision 32)
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.
Two authorities guard a write, and both stay:
| 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 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.
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.
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.