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:
donghyeon-ka
2026-09-29 14:54:06 +09:00
co-authored by Claude Opus 5.5
parent 09e2dd63d6
commit 0579935746
275 changed files with 5838 additions and 3312 deletions
@@ -0,0 +1,74 @@
package dev.caskeleton.application.fileserver.admin;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.observability.SafeFileFingerprint;
import java.time.Clock;
import java.util.Objects;
/**
* The audit trail and page cap every operator action shares.
*
* <p>Public because the use cases that write it are assembled outside this package; nothing but the
* admin use cases constructs one.
*/
public final class AdminAudit {
private static final int MAXIMUM_ADMIN_PAGE = 1000;
private final AdminAuditPort auditPort;
private final SafeFileFingerprint fingerprint;
private final Clock clock;
public AdminAudit(AdminAuditPort auditPort, SafeFileFingerprint fingerprint, Clock clock) {
this.auditPort = Objects.requireNonNull(auditPort, "auditPort");
this.fingerprint = Objects.requireNonNull(fingerprint, "fingerprint");
this.clock = Objects.requireNonNull(clock, "clock");
}
/**
* Caps every admin query.
*
* <p>An unbounded admin listing is a self-inflicted outage: it walks production storage or the
* whole metadata table on an operator's keystroke.
*/
static int boundedLimit(int requested) {
return Math.max(1, Math.min(requested, MAXIMUM_ADMIN_PAGE));
}
void record(
String operation,
String reasonCode,
RequestContext context,
boolean succeeded,
String subjectId) {
auditPort.record(
new AdminAuditRecord(
operation,
reasonCode,
actorFingerprint(context),
context.traceId(),
succeeded,
subjectFingerprint(subjectId),
clock.instant()));
}
/**
* Stable pseudonym for the acting operator.
*
* <p>An audit trail needs to correlate actions by the same actor without becoming a second
* directory of who works here, so the principal is reduced to a fingerprint.
*
* <p>A keyed HMAC, not {@code hashCode()}. A 32-bit unkeyed hash over an enumerable identifier
* space is reversible with a laptop and collides often enough that two operators can share a
* pseudonym — which is worse than no pseudonym, because the trail then reads as if one person did
* both things.
*/
private String actorFingerprint(RequestContext context) {
return fingerprint.of(context.subject().principalId());
}
/** The same reduction for the object of the action; a raw file id is a disclosure too. */
private String subjectFingerprint(String subjectId) {
return subjectId.isBlank() ? subjectId : fingerprint.of(subjectId);
}
}
@@ -0,0 +1,54 @@
package dev.caskeleton.application.fileserver.admin;
import dev.caskeleton.application.capability.Idempotency;
import dev.caskeleton.application.capability.RepositoryAccess;
import dev.caskeleton.application.capability.UseCaseCapability;
import dev.caskeleton.application.fileserver.api.security.FileAccessPolicyPort;
import dev.caskeleton.application.fileserver.api.security.FileOperation;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.cleanup.CleanupBatchResult;
import dev.caskeleton.application.fileserver.cleanup.CleanupService;
import dev.caskeleton.application.fileserver.port.in.CleanupUploadsCommand;
import dev.caskeleton.application.fileserver.port.in.CleanupUploadsUseCase;
import dev.caskeleton.application.security.RequiresPermission;
import dev.caskeleton.application.transaction.TransactionMode;
import java.util.Objects;
import java.util.Optional;
/**
* Runs one cleanup batch on an operator's request.
*
* <p>{@code RepositoryAccess.NONE}: the batch is {@link CleanupService}'s, which opens a boundary
* per claimed item. One around the whole batch would hold a connection across every deletion.
*/
@RequiresPermission("file:admin")
@UseCaseCapability(
transactionMode = TransactionMode.WRITE,
idempotency = Idempotency.NOT_IDEMPOTENT,
repositoryAccess = RepositoryAccess.NONE,
crossTenantAdmin = true)
// Not final: @RequiresPermission is applied through a CGLIB proxy
// (RequiresPermissionProxyabilityTest).
public class CleanupUploadsApplicationUseCase implements CleanupUploadsUseCase {
private final CleanupService cleanupService;
private final FileAccessPolicyPort accessPolicy;
private final AdminAudit audit;
public CleanupUploadsApplicationUseCase(
CleanupService cleanupService, FileAccessPolicyPort accessPolicy, AdminAudit audit) {
this.cleanupService = Objects.requireNonNull(cleanupService, "cleanupService");
this.accessPolicy = Objects.requireNonNull(accessPolicy, "accessPolicy");
this.audit = Objects.requireNonNull(audit, "audit");
}
@Override
public CleanupBatchResult handle(CleanupUploadsCommand command) {
RequestContext context = command.context();
accessPolicy.authorize(FileOperation.ADMIN_FORCE_DELETE, context.subject(), Optional.empty());
CleanupBatchResult result =
cleanupService.runBatch(AdminAudit.boundedLimit(command.maxItems()), command.maxBytes());
audit.record("uploads:cleanup", "OPERATOR_CLEANUP", context, true, "batch");
return result;
}
}
@@ -1,272 +0,0 @@
package dev.caskeleton.application.fileserver.admin;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.FileState;
import dev.caskeleton.application.fileserver.api.error.FileNotFoundException;
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
import dev.caskeleton.application.fileserver.api.error.FileserverException;
import dev.caskeleton.application.fileserver.api.error.FileserverFailureContext;
import dev.caskeleton.application.fileserver.api.metadata.FileMetadataPort;
import dev.caskeleton.application.fileserver.api.metadata.FileRecord;
import dev.caskeleton.application.fileserver.api.metadata.FileRecordMutation;
import dev.caskeleton.application.fileserver.api.metadata.UploadSession;
import dev.caskeleton.application.fileserver.api.metadata.UploadSessionPort;
import dev.caskeleton.application.fileserver.api.security.FileAccessPolicyPort;
import dev.caskeleton.application.fileserver.api.security.FileOperation;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.cleanup.CleanupBatchResult;
import dev.caskeleton.application.fileserver.cleanup.CleanupQueuePort;
import dev.caskeleton.application.fileserver.cleanup.CleanupRequest;
import dev.caskeleton.application.fileserver.cleanup.CleanupService;
import dev.caskeleton.application.fileserver.cleanup.FileRetirement;
import dev.caskeleton.application.fileserver.observability.SafeFileFingerprint;
import dev.caskeleton.application.fileserver.recovery.StagingUploadLocatorPort;
import dev.caskeleton.application.fileserver.upload.FileView;
import dev.caskeleton.application.transaction.TransactionPort;
import java.time.Clock;
import java.util.ArrayList;
import java.util.List;
import java.util.Optional;
/**
* The management plane, with its own authority and its own audit trail.
*
* <p>Two rules shape everything here. A reconcile is a dry run unless the caller explicitly opted
* out <em>and</em> echoed the fingerprints it was shown, so a stale scan can never turn into a mass
* delete. And every mutating action is audited whether it succeeded or not, because a refused
* force-delete is exactly the event a reviewer needs to see.
*/
public final class DefaultFileserverAdminService implements FileserverAdminService {
private static final int MAXIMUM_ADMIN_PAGE = 1000;
private final StorageHealthPort healthPort;
private final OrphanScanPort orphanScanPort;
private final FileMetadataPort metadataStore;
private final UploadSessionPort sessionStore;
private final StagingUploadLocatorPort stagingLocator;
private final CleanupQueuePort cleanupQueue;
private final FileRetirement retirement;
private final CleanupService cleanupService;
private final FileAccessPolicyPort accessPolicy;
private final AdminAuditPort auditPort;
private final SafeFileFingerprint fingerprint;
private final TransactionPort transactions;
private final Clock clock;
public DefaultFileserverAdminService(
StorageHealthPort healthPort,
OrphanScanPort orphanScanPort,
FileMetadataPort metadataStore,
UploadSessionPort sessionStore,
StagingUploadLocatorPort stagingLocator,
CleanupQueuePort cleanupQueue,
CleanupService cleanupService,
FileAccessPolicyPort accessPolicy,
AdminAuditPort auditPort,
SafeFileFingerprint fingerprint,
TransactionPort transactions,
Clock clock) {
this.healthPort = healthPort;
this.orphanScanPort = orphanScanPort;
this.metadataStore = metadataStore;
this.sessionStore = sessionStore;
this.stagingLocator = stagingLocator;
this.cleanupQueue = cleanupQueue;
this.cleanupService = cleanupService;
this.accessPolicy = accessPolicy;
this.auditPort = auditPort;
this.fingerprint = fingerprint;
this.transactions = transactions;
this.clock = clock;
this.retirement = new FileRetirement(metadataStore, cleanupQueue);
}
@Override
public StorageHealthReport storageHealth(RequestContext context) {
authorizeRead(context);
return healthPort.health();
}
@Override
public RuntimeCapabilityReport capabilities(RequestContext context) {
authorizeRead(context);
return healthPort.capabilities();
}
@Override
public List<OrphanObject> orphans(int limit, RequestContext context) {
authorizeRead(context);
return orphanScanPort.scan(boundedLimit(limit));
}
@Override
public OrphanReconcileReport reconcileOrphans(
OrphanReconcileCommand command, RequestContext context) {
accessPolicy.authorize(FileOperation.ADMIN_FORCE_DELETE, context.subject(), Optional.empty());
List<OrphanObject> candidates = orphanScanPort.scan(boundedLimit(command.limit()));
if (command.dryRun()) {
audit("orphans:reconcile", command.reasonCode(), context, true, "dry-run");
return new OrphanReconcileReport(true, candidates, 0, 0, 0);
}
int deleted = 0;
int mismatched = 0;
long reclaimed = 0;
for (OrphanObject candidate : candidates) {
if (!command.expectedFingerprints().contains(candidate.fingerprint())) {
mismatched++;
continue;
}
if (reclaimed + candidate.sizeBytes() > command.maxBytes()) {
break;
}
if (orphanScanPort.deleteIfFingerprintMatches(
candidate.contentKey(), candidate.fingerprint())) {
// Retirement moved the object to quarantine; the durable record of that intent is queued
// immediately after. Without it a node that dies here leaves an object nobody is looking
// for, in an area nothing scans.
transactions.inWrite(
() -> cleanupQueue.enqueue(CleanupRequest.forOrphan(candidate.contentKey())));
deleted++;
reclaimed += candidate.sizeBytes();
} else {
mismatched++;
}
}
audit("orphans:reconcile", command.reasonCode(), context, true, "apply");
return new OrphanReconcileReport(false, candidates, deleted, mismatched, reclaimed);
}
@Override
public FileView reverify(FileId fileId, RequestContext context) {
accessPolicy.authorize(FileOperation.ADMIN_REVERIFY, context.subject(), Optional.empty());
FileRecord record = requireRecord(fileId);
if (record.state() != FileState.QUARANTINED) {
audit("files:reverify", "REVERIFY_REJECTED", context, false, fileId.canonicalText());
throw new FileserverException(
"only a quarantined file can be re-verified",
FileserverFailureContext.forFileState(
FileserverErrorCode.FILE_NOT_READY, fileId, record.state(), false));
}
FileRecord verifying =
transactions.inWrite(
() ->
metadataStore.transition(
record.fileId(),
record.version(),
FileState.QUARANTINED,
FileState.VERIFYING,
FileRecordMutation.none()));
audit("files:reverify", "OPERATOR_REVERIFY", context, true, fileId.canonicalText());
return FileView.of(verifying.toDescriptor());
}
@Override
public void forceDelete(ForceDeleteCommand command, RequestContext context) {
accessPolicy.authorize(FileOperation.ADMIN_FORCE_DELETE, context.subject(), Optional.empty());
FileRecord record = requireRecord(command.fileId());
// An operator force-delete must not be able to leave a file unreachable with nothing queued to
// reclaim its bytes, so retiring the record and queueing the content commit together — and an
// upload still in progress ends with it, exactly as a data-plane delete does.
transactions.inWrite(
() -> retirement.retireWithUnfinishedUpload(record, sessionStore, stagingLocator));
audit(
"files:force-delete",
command.reasonCode(),
context,
true,
command.fileId().canonicalText());
}
@Override
public List<IncompleteUploadView> incompleteUploads(int limit, RequestContext context) {
authorizeRead(context);
List<IncompleteUploadView> views = new ArrayList<>();
for (UploadSession session : sessionStore.findExpired(clock.instant(), boundedLimit(limit))) {
views.add(
new IncompleteUploadView(
session.uploadId(),
session.fileId(),
session.committedOffset(),
session.expiresAt(),
session.leaseOwner(),
session.leaseUntil()));
}
return List.copyOf(views);
}
@Override
public CleanupBatchResult cleanupUploads(int maxItems, long maxBytes, RequestContext context) {
accessPolicy.authorize(FileOperation.ADMIN_FORCE_DELETE, context.subject(), Optional.empty());
CleanupBatchResult result = cleanupService.runBatch(boundedLimit(maxItems), maxBytes);
audit("uploads:cleanup", "OPERATOR_CLEANUP", context, true, "batch");
return result;
}
/**
* Management-plane reads are an admin operation, not a metadata read: a data-plane reader must
* not learn storage health or list other callers' incomplete uploads.
*/
private void authorizeRead(RequestContext context) {
accessPolicy.authorize(FileOperation.ADMIN_READ, context.subject(), Optional.empty());
}
/**
* Caps every admin query.
*
* <p>An unbounded admin listing is a self-inflicted outage: it walks production storage or the
* whole metadata table on an operator's keystroke.
*/
private static int boundedLimit(int requested) {
return Math.max(1, Math.min(requested, MAXIMUM_ADMIN_PAGE));
}
private void audit(
String operation,
String reasonCode,
RequestContext context,
boolean succeeded,
String subjectId) {
auditPort.record(
new AdminAuditRecord(
operation,
reasonCode,
actorFingerprint(context),
context.traceId(),
succeeded,
subjectFingerprint(subjectId),
clock.instant()));
}
/**
* Stable pseudonym for the acting operator.
*
* <p>An audit trail needs to correlate actions by the same actor without becoming a second
* directory of who works here, so the principal is reduced to a fingerprint.
*
* <p>A keyed HMAC, not {@code hashCode()}. A 32-bit unkeyed hash over an enumerable identifier
* space is reversible with a laptop and collides often enough that two operators can share a
* pseudonym — which is worse than no pseudonym, because the trail then reads as if one person did
* both things.
*/
private String actorFingerprint(RequestContext context) {
return fingerprint.of(context.subject().principalId());
}
/** The same reduction for the object of the action; a raw file id is a disclosure too. */
private String subjectFingerprint(String subjectId) {
return subjectId.isBlank() ? subjectId : fingerprint.of(subjectId);
}
private FileRecord requireRecord(FileId fileId) {
return metadataStore
.find(fileId)
.orElseThrow(
() ->
new FileNotFoundException(
"file record does not exist",
FileserverFailureContext.forFile(
FileserverErrorCode.FILE_NOT_FOUND, fileId, false)));
}
}
@@ -1,34 +0,0 @@
package dev.caskeleton.application.fileserver.admin;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.cleanup.CleanupBatchResult;
import dev.caskeleton.application.fileserver.upload.FileView;
import java.util.List;
/**
* The management-plane surface.
*
* <p>Every method here is deliberately separate from the public application services: an operator
* action is authorized against a different authority, is always audited, and may see counters a
* tenant never should. Mixing them into the public services is how an admin capability ends up one
* missing check away from being publicly reachable.
*/
public interface FileserverAdminService {
StorageHealthReport storageHealth(RequestContext context);
RuntimeCapabilityReport capabilities(RequestContext context);
List<OrphanObject> orphans(int limit, RequestContext context);
OrphanReconcileReport reconcileOrphans(OrphanReconcileCommand command, RequestContext context);
FileView reverify(FileId fileId, RequestContext context);
void forceDelete(ForceDeleteCommand command, RequestContext context);
List<IncompleteUploadView> incompleteUploads(int limit, RequestContext context);
CleanupBatchResult cleanupUploads(int maxItems, long maxBytes, RequestContext context);
}
@@ -0,0 +1,81 @@
package dev.caskeleton.application.fileserver.admin;
import dev.caskeleton.application.capability.Idempotency;
import dev.caskeleton.application.capability.RepositoryAccess;
import dev.caskeleton.application.capability.UseCaseCapability;
import dev.caskeleton.application.fileserver.api.metadata.FileMetadataPort;
import dev.caskeleton.application.fileserver.api.metadata.FileRecord;
import dev.caskeleton.application.fileserver.api.metadata.FileRecords;
import dev.caskeleton.application.fileserver.api.metadata.UploadSessionPort;
import dev.caskeleton.application.fileserver.api.security.FileAccessPolicyPort;
import dev.caskeleton.application.fileserver.api.security.FileOperation;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.cleanup.CleanupQueuePort;
import dev.caskeleton.application.fileserver.cleanup.FileRetirement;
import dev.caskeleton.application.fileserver.port.in.ForceDeleteCommand;
import dev.caskeleton.application.fileserver.port.in.ForceDeleteFileUseCase;
import dev.caskeleton.application.fileserver.recovery.StagingUploadLocatorPort;
import dev.caskeleton.application.security.RequiresPermission;
import dev.caskeleton.application.transaction.TransactionMode;
import dev.caskeleton.application.transaction.TransactionPort;
import java.util.Objects;
import java.util.Optional;
/**
* Removes a file on an operator's authority, bypassing the data-plane preconditions.
*
* <p>An operator force-delete must not be able to leave a file unreachable with nothing queued to
* reclaim its bytes, so retiring the record and queueing the content commit together — and an
* upload still in progress ends with it, exactly as a data-plane delete does.
*/
@RequiresPermission("file:admin")
@UseCaseCapability(
transactionMode = TransactionMode.WRITE,
idempotency = Idempotency.IDEMPOTENT,
repositoryAccess = RepositoryAccess.WRITE_REPOSITORY,
crossTenantAdmin = true)
// Not final: @RequiresPermission is applied through a CGLIB proxy
// (RequiresPermissionProxyabilityTest).
public class ForceDeleteFileApplicationUseCase implements ForceDeleteFileUseCase {
private final FileMetadataPort metadataStore;
private final UploadSessionPort sessionStore;
private final StagingUploadLocatorPort stagingLocator;
private final FileRetirement retirement;
private final FileAccessPolicyPort accessPolicy;
private final AdminAudit audit;
private final TransactionPort transactions;
public ForceDeleteFileApplicationUseCase(
FileMetadataPort metadataStore,
UploadSessionPort sessionStore,
StagingUploadLocatorPort stagingLocator,
CleanupQueuePort cleanupQueue,
FileAccessPolicyPort accessPolicy,
AdminAudit audit,
TransactionPort transactions) {
this.metadataStore = Objects.requireNonNull(metadataStore, "metadataStore");
this.sessionStore = Objects.requireNonNull(sessionStore, "sessionStore");
this.stagingLocator = Objects.requireNonNull(stagingLocator, "stagingLocator");
this.retirement = new FileRetirement(metadataStore, cleanupQueue);
this.accessPolicy = Objects.requireNonNull(accessPolicy, "accessPolicy");
this.audit = Objects.requireNonNull(audit, "audit");
this.transactions = Objects.requireNonNull(transactions, "transactions");
}
@Override
public Void handle(ForceDeleteCommand command) {
RequestContext context = command.context();
accessPolicy.authorize(FileOperation.ADMIN_FORCE_DELETE, context.subject(), Optional.empty());
FileRecord record = FileRecords.require(metadataStore, command.fileId());
transactions.inWrite(
() -> retirement.retireWithUnfinishedUpload(record, sessionStore, stagingLocator));
audit.record(
"files:force-delete",
command.reasonCode(),
context,
true,
command.fileId().canonicalText());
return null;
}
}
@@ -0,0 +1,40 @@
package dev.caskeleton.application.fileserver.admin;
import dev.caskeleton.application.capability.Idempotency;
import dev.caskeleton.application.capability.RepositoryAccess;
import dev.caskeleton.application.capability.UseCaseCapability;
import dev.caskeleton.application.fileserver.api.security.FileAccessPolicyPort;
import dev.caskeleton.application.fileserver.api.security.FileOperation;
import dev.caskeleton.application.fileserver.port.in.GetRuntimeCapabilitiesQuery;
import dev.caskeleton.application.fileserver.port.in.GetRuntimeCapabilitiesUseCase;
import dev.caskeleton.application.security.RequiresPermission;
import dev.caskeleton.application.transaction.TransactionMode;
import java.util.Objects;
import java.util.Optional;
/** Reports what the running storage supports to an operator. */
@RequiresPermission("file:admin")
@UseCaseCapability(
transactionMode = TransactionMode.READ_ONLY,
idempotency = Idempotency.IDEMPOTENT,
repositoryAccess = RepositoryAccess.NONE,
externalOutboundAllowed = true)
// Not final: @RequiresPermission is applied through a CGLIB proxy
// (RequiresPermissionProxyabilityTest).
public class GetRuntimeCapabilitiesApplicationUseCase implements GetRuntimeCapabilitiesUseCase {
private final StorageHealthPort healthPort;
private final FileAccessPolicyPort accessPolicy;
public GetRuntimeCapabilitiesApplicationUseCase(
StorageHealthPort healthPort, FileAccessPolicyPort accessPolicy) {
this.healthPort = Objects.requireNonNull(healthPort, "healthPort");
this.accessPolicy = Objects.requireNonNull(accessPolicy, "accessPolicy");
}
@Override
public RuntimeCapabilityReport handle(GetRuntimeCapabilitiesQuery query) {
accessPolicy.authorize(FileOperation.ADMIN_READ, query.context().subject(), Optional.empty());
return healthPort.capabilities();
}
}
@@ -0,0 +1,45 @@
package dev.caskeleton.application.fileserver.admin;
import dev.caskeleton.application.capability.Idempotency;
import dev.caskeleton.application.capability.RepositoryAccess;
import dev.caskeleton.application.capability.UseCaseCapability;
import dev.caskeleton.application.fileserver.api.security.FileAccessPolicyPort;
import dev.caskeleton.application.fileserver.api.security.FileOperation;
import dev.caskeleton.application.fileserver.port.in.GetStorageHealthQuery;
import dev.caskeleton.application.fileserver.port.in.GetStorageHealthUseCase;
import dev.caskeleton.application.security.RequiresPermission;
import dev.caskeleton.application.transaction.TransactionMode;
import java.util.Objects;
import java.util.Optional;
/**
* Reports the storage's health to an operator.
*
* <p>A management-plane read is an admin operation, not a metadata read: a data-plane reader must
* not learn storage health.
*/
@RequiresPermission("file:admin")
@UseCaseCapability(
transactionMode = TransactionMode.READ_ONLY,
idempotency = Idempotency.IDEMPOTENT,
repositoryAccess = RepositoryAccess.NONE,
externalOutboundAllowed = true)
// Not final: @RequiresPermission is applied through a CGLIB proxy
// (RequiresPermissionProxyabilityTest).
public class GetStorageHealthApplicationUseCase implements GetStorageHealthUseCase {
private final StorageHealthPort healthPort;
private final FileAccessPolicyPort accessPolicy;
public GetStorageHealthApplicationUseCase(
StorageHealthPort healthPort, FileAccessPolicyPort accessPolicy) {
this.healthPort = Objects.requireNonNull(healthPort, "healthPort");
this.accessPolicy = Objects.requireNonNull(accessPolicy, "accessPolicy");
}
@Override
public StorageHealthReport handle(GetStorageHealthQuery query) {
accessPolicy.authorize(FileOperation.ADMIN_READ, query.context().subject(), Optional.empty());
return healthPort.health();
}
}
@@ -0,0 +1,72 @@
package dev.caskeleton.application.fileserver.admin;
import dev.caskeleton.application.capability.Idempotency;
import dev.caskeleton.application.capability.RepositoryAccess;
import dev.caskeleton.application.capability.UseCaseCapability;
import dev.caskeleton.application.fileserver.api.metadata.UploadSession;
import dev.caskeleton.application.fileserver.api.metadata.UploadSessionPort;
import dev.caskeleton.application.fileserver.api.security.FileAccessPolicyPort;
import dev.caskeleton.application.fileserver.api.security.FileOperation;
import dev.caskeleton.application.fileserver.port.in.ListIncompleteUploadsQuery;
import dev.caskeleton.application.fileserver.port.in.ListIncompleteUploadsUseCase;
import dev.caskeleton.application.security.RequiresPermission;
import dev.caskeleton.application.transaction.TransactionMode;
import dev.caskeleton.application.transaction.TransactionPort;
import java.time.Clock;
import java.util.ArrayList;
import java.util.List;
import java.util.Objects;
import java.util.Optional;
/**
* Lists uploads that expired before they finished.
*
* <p>An admin read: a data-plane reader must not list other callers' incomplete uploads.
*/
@RequiresPermission("file:admin")
@UseCaseCapability(
transactionMode = TransactionMode.READ_ONLY,
idempotency = Idempotency.IDEMPOTENT,
repositoryAccess = RepositoryAccess.READ_REPOSITORY,
crossTenantAdmin = true)
// Not final: @RequiresPermission is applied through a CGLIB proxy
// (RequiresPermissionProxyabilityTest).
public class ListIncompleteUploadsApplicationUseCase implements ListIncompleteUploadsUseCase {
private final UploadSessionPort sessionStore;
private final FileAccessPolicyPort accessPolicy;
private final TransactionPort transactions;
private final Clock clock;
public ListIncompleteUploadsApplicationUseCase(
UploadSessionPort sessionStore,
FileAccessPolicyPort accessPolicy,
TransactionPort transactions,
Clock clock) {
this.sessionStore = Objects.requireNonNull(sessionStore, "sessionStore");
this.accessPolicy = Objects.requireNonNull(accessPolicy, "accessPolicy");
this.transactions = Objects.requireNonNull(transactions, "transactions");
this.clock = Objects.requireNonNull(clock, "clock");
}
@Override
public List<IncompleteUploadView> handle(ListIncompleteUploadsQuery query) {
accessPolicy.authorize(FileOperation.ADMIN_READ, query.context().subject(), Optional.empty());
List<UploadSession> expired =
transactions.inRead(
() ->
sessionStore.findExpired(clock.instant(), AdminAudit.boundedLimit(query.limit())));
List<IncompleteUploadView> views = new ArrayList<>();
for (UploadSession session : expired) {
views.add(
new IncompleteUploadView(
session.uploadId(),
session.fileId(),
session.committedOffset(),
session.expiresAt(),
session.leaseOwner(),
session.leaseUntil()));
}
return List.copyOf(views);
}
}
@@ -0,0 +1,41 @@
package dev.caskeleton.application.fileserver.admin;
import dev.caskeleton.application.capability.Idempotency;
import dev.caskeleton.application.capability.RepositoryAccess;
import dev.caskeleton.application.capability.UseCaseCapability;
import dev.caskeleton.application.fileserver.api.security.FileAccessPolicyPort;
import dev.caskeleton.application.fileserver.api.security.FileOperation;
import dev.caskeleton.application.fileserver.port.in.ListOrphansQuery;
import dev.caskeleton.application.fileserver.port.in.ListOrphansUseCase;
import dev.caskeleton.application.security.RequiresPermission;
import dev.caskeleton.application.transaction.TransactionMode;
import java.util.List;
import java.util.Objects;
import java.util.Optional;
/** Lists physical objects no record refers to. */
@RequiresPermission("file:admin")
@UseCaseCapability(
transactionMode = TransactionMode.READ_ONLY,
idempotency = Idempotency.IDEMPOTENT,
repositoryAccess = RepositoryAccess.NONE,
externalOutboundAllowed = true)
// Not final: @RequiresPermission is applied through a CGLIB proxy
// (RequiresPermissionProxyabilityTest).
public class ListOrphansApplicationUseCase implements ListOrphansUseCase {
private final OrphanScanPort orphanScanPort;
private final FileAccessPolicyPort accessPolicy;
public ListOrphansApplicationUseCase(
OrphanScanPort orphanScanPort, FileAccessPolicyPort accessPolicy) {
this.orphanScanPort = Objects.requireNonNull(orphanScanPort, "orphanScanPort");
this.accessPolicy = Objects.requireNonNull(accessPolicy, "accessPolicy");
}
@Override
public List<OrphanObject> handle(ListOrphansQuery query) {
accessPolicy.authorize(FileOperation.ADMIN_READ, query.context().subject(), Optional.empty());
return orphanScanPort.scan(AdminAudit.boundedLimit(query.limit()));
}
}
@@ -0,0 +1,88 @@
package dev.caskeleton.application.fileserver.admin;
import dev.caskeleton.application.capability.Idempotency;
import dev.caskeleton.application.capability.RepositoryAccess;
import dev.caskeleton.application.capability.UseCaseCapability;
import dev.caskeleton.application.fileserver.api.security.FileAccessPolicyPort;
import dev.caskeleton.application.fileserver.api.security.FileOperation;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.cleanup.CleanupQueuePort;
import dev.caskeleton.application.fileserver.cleanup.CleanupRequest;
import dev.caskeleton.application.fileserver.port.in.OrphanReconcileCommand;
import dev.caskeleton.application.fileserver.port.in.ReconcileOrphansUseCase;
import dev.caskeleton.application.security.RequiresPermission;
import dev.caskeleton.application.transaction.TransactionMode;
import dev.caskeleton.application.transaction.TransactionPort;
import java.util.List;
import java.util.Objects;
import java.util.Optional;
/** Removes, or with a dry run only lists, the orphaned objects an operator names. */
@RequiresPermission("file:admin")
@UseCaseCapability(
transactionMode = TransactionMode.WRITE,
idempotency = Idempotency.NOT_IDEMPOTENT,
repositoryAccess = RepositoryAccess.WRITE_REPOSITORY,
externalOutboundAllowed = true,
crossTenantAdmin = true)
// Not final: @RequiresPermission is applied through a CGLIB proxy
// (RequiresPermissionProxyabilityTest).
public class ReconcileOrphansApplicationUseCase implements ReconcileOrphansUseCase {
private final OrphanScanPort orphanScanPort;
private final CleanupQueuePort cleanupQueue;
private final FileAccessPolicyPort accessPolicy;
private final AdminAudit audit;
private final TransactionPort transactions;
public ReconcileOrphansApplicationUseCase(
OrphanScanPort orphanScanPort,
CleanupQueuePort cleanupQueue,
FileAccessPolicyPort accessPolicy,
AdminAudit audit,
TransactionPort transactions) {
this.orphanScanPort = Objects.requireNonNull(orphanScanPort, "orphanScanPort");
this.cleanupQueue = Objects.requireNonNull(cleanupQueue, "cleanupQueue");
this.accessPolicy = Objects.requireNonNull(accessPolicy, "accessPolicy");
this.audit = Objects.requireNonNull(audit, "audit");
this.transactions = Objects.requireNonNull(transactions, "transactions");
}
@Override
public OrphanReconcileReport handle(OrphanReconcileCommand command) {
RequestContext context = command.context();
accessPolicy.authorize(FileOperation.ADMIN_FORCE_DELETE, context.subject(), Optional.empty());
List<OrphanObject> candidates = orphanScanPort.scan(AdminAudit.boundedLimit(command.limit()));
if (command.dryRun()) {
audit.record("orphans:reconcile", command.reasonCode(), context, true, "dry-run");
return new OrphanReconcileReport(true, candidates, 0, 0, 0);
}
int deleted = 0;
int mismatched = 0;
long reclaimed = 0;
for (OrphanObject candidate : candidates) {
if (!command.expectedFingerprints().contains(candidate.fingerprint())) {
mismatched++;
continue;
}
if (reclaimed + candidate.sizeBytes() > command.maxBytes()) {
break;
}
if (orphanScanPort.deleteIfFingerprintMatches(
candidate.contentKey(), candidate.fingerprint())) {
// Retirement moved the object to quarantine; the durable record of that intent is queued
// immediately after. Without it a node that dies here leaves an object nobody is looking
// for, in an area nothing scans.
transactions.inWrite(
() -> cleanupQueue.enqueue(CleanupRequest.forOrphan(candidate.contentKey())));
deleted++;
reclaimed += candidate.sizeBytes();
} else {
mismatched++;
}
}
audit.record("orphans:reconcile", command.reasonCode(), context, true, "apply");
return new OrphanReconcileReport(false, candidates, deleted, mismatched, reclaimed);
}
}
@@ -0,0 +1,79 @@
package dev.caskeleton.application.fileserver.admin;
import dev.caskeleton.application.capability.Idempotency;
import dev.caskeleton.application.capability.RepositoryAccess;
import dev.caskeleton.application.capability.UseCaseCapability;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.FileState;
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
import dev.caskeleton.application.fileserver.api.error.FileserverException;
import dev.caskeleton.application.fileserver.api.error.FileserverFailureContext;
import dev.caskeleton.application.fileserver.api.metadata.FileMetadataPort;
import dev.caskeleton.application.fileserver.api.metadata.FileRecord;
import dev.caskeleton.application.fileserver.api.metadata.FileRecordMutation;
import dev.caskeleton.application.fileserver.api.metadata.FileRecords;
import dev.caskeleton.application.fileserver.api.security.FileAccessPolicyPort;
import dev.caskeleton.application.fileserver.api.security.FileOperation;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.port.in.ReverifyFileCommand;
import dev.caskeleton.application.fileserver.port.in.ReverifyFileUseCase;
import dev.caskeleton.application.fileserver.upload.FileView;
import dev.caskeleton.application.security.RequiresPermission;
import dev.caskeleton.application.transaction.TransactionMode;
import dev.caskeleton.application.transaction.TransactionPort;
import java.util.Objects;
import java.util.Optional;
/** Sends a quarantined file back to verification. */
@RequiresPermission("file:admin")
@UseCaseCapability(
transactionMode = TransactionMode.WRITE,
idempotency = Idempotency.NOT_IDEMPOTENT,
repositoryAccess = RepositoryAccess.WRITE_REPOSITORY,
crossTenantAdmin = true)
// Not final: @RequiresPermission is applied through a CGLIB proxy
// (RequiresPermissionProxyabilityTest).
public class ReverifyFileApplicationUseCase implements ReverifyFileUseCase {
private final FileMetadataPort metadataStore;
private final FileAccessPolicyPort accessPolicy;
private final AdminAudit audit;
private final TransactionPort transactions;
public ReverifyFileApplicationUseCase(
FileMetadataPort metadataStore,
FileAccessPolicyPort accessPolicy,
AdminAudit audit,
TransactionPort transactions) {
this.metadataStore = Objects.requireNonNull(metadataStore, "metadataStore");
this.accessPolicy = Objects.requireNonNull(accessPolicy, "accessPolicy");
this.audit = Objects.requireNonNull(audit, "audit");
this.transactions = Objects.requireNonNull(transactions, "transactions");
}
@Override
public FileView handle(ReverifyFileCommand command) {
RequestContext context = command.context();
FileId fileId = command.fileId();
accessPolicy.authorize(FileOperation.ADMIN_REVERIFY, context.subject(), Optional.empty());
FileRecord record = FileRecords.require(metadataStore, fileId);
if (record.state() != FileState.QUARANTINED) {
audit.record("files:reverify", "REVERIFY_REJECTED", context, false, fileId.canonicalText());
throw new FileserverException(
"only a quarantined file can be re-verified",
FileserverFailureContext.forFileState(
FileserverErrorCode.FILE_NOT_READY, fileId, record.state(), false));
}
FileRecord verifying =
transactions.inWrite(
() ->
metadataStore.transition(
record.fileId(),
record.version(),
FileState.QUARANTINED,
FileState.VERIFYING,
FileRecordMutation.none()));
audit.record("files:reverify", "OPERATOR_REVERIFY", context, true, fileId.canonicalText());
return FileView.of(verifying.toDescriptor());
}
}
@@ -0,0 +1,53 @@
package dev.caskeleton.application.fileserver.api.metadata;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.error.FileNotFoundException;
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
import dev.caskeleton.application.fileserver.api.error.FileserverException;
import dev.caskeleton.application.fileserver.api.error.FileserverFailureContext;
/**
* The two record checks every file operation starts with.
*
* <p>Each operation used to carry its own copy of both, one per service; with one use case per
* operation that would have been a copy per use case, and a copy is where the refusal a client sees
* starts to differ between operations that should answer alike.
*/
public final class FileRecords {
private FileRecords() {}
/**
* The record of {@code fileId}, or the not-found refusal.
*
* @param metadata where records live
* @param fileId the file
* @return the record
* @throws FileNotFoundException when no record exists
*/
public static FileRecord require(FileMetadataPort metadata, FileId fileId) {
return metadata
.find(fileId)
.orElseThrow(
() ->
new FileNotFoundException(
"file record does not exist",
FileserverFailureContext.forFile(
FileserverErrorCode.FILE_NOT_FOUND, fileId, false)));
}
/**
* Refuses a record that is not in a publicly readable state.
*
* @param record the record
* @throws FileserverException {@code FILE_NOT_READY}, retryable, otherwise
*/
public static void requireReadable(FileRecord record) {
if (!record.state().isPubliclyReadable()) {
throw new FileserverException(
"file is not in a publicly readable state",
FileserverFailureContext.forFileState(
FileserverErrorCode.FILE_NOT_READY, record.fileId(), record.state(), true));
}
}
}
@@ -1,17 +0,0 @@
package dev.caskeleton.application.fileserver.api.security;
import java.util.concurrent.CompletionStage;
/**
* One step of the verification pipeline.
*
* <p>A verifier returns only a stable code and bounded safe metadata. It never logs a content
* sample, and a failure to reach an external scanner is {@link VerificationVerdict#RETRY}, never
* {@link VerificationVerdict#ACCEPT}.
*/
public interface FileVerifier {
String verifierId();
CompletionStage<VerificationResult> verify(VerificationRequest request);
}
@@ -1,149 +0,0 @@
package dev.caskeleton.application.fileserver.download;
import dev.caskeleton.application.fileserver.api.ByteRange;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.error.FileNotFoundException;
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
import dev.caskeleton.application.fileserver.api.error.FileserverException;
import dev.caskeleton.application.fileserver.api.error.FileserverFailureContext;
import dev.caskeleton.application.fileserver.api.metadata.FileMetadataPort;
import dev.caskeleton.application.fileserver.api.metadata.FileRecord;
import dev.caskeleton.application.fileserver.api.security.FileAccessPolicyPort;
import dev.caskeleton.application.fileserver.api.security.FileOperation;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.api.security.SanitizedFilename;
import dev.caskeleton.application.fileserver.api.transfer.FileRepresentation;
import dev.caskeleton.application.fileserver.observability.FileserverMetricsPort;
import dev.caskeleton.application.fileserver.observability.SizeBucket;
import dev.caskeleton.application.fileserver.upload.FileView;
import java.nio.channels.ReadableByteChannel;
import java.nio.channels.WritableByteChannel;
import java.util.Optional;
/**
* Authorizes download access and exposes immutable content facts.
*
* <p>HTTP conditional requests, range parsing, status selection and response headers deliberately
* do not live here. The application proves the file exists, is readable and authorized; an inbound
* transport may then derive its wire response before opening content.
*/
public final class DefaultDownloadApplicationService implements DownloadApplicationService {
private final FileMetadataPort metadataStore;
private final DownloadContentPort contentGateway;
private final FileAccessPolicyPort accessPolicy;
private final Optional<ZeroCopyDownloadPort> zeroCopyGateway;
private final FileserverMetricsPort metrics;
public DefaultDownloadApplicationService(
FileMetadataPort metadataStore,
DownloadContentPort contentGateway,
FileAccessPolicyPort accessPolicy) {
this(
metadataStore,
contentGateway,
accessPolicy,
Optional.empty(),
FileserverMetricsPort.noop());
}
public DefaultDownloadApplicationService(
FileMetadataPort metadataStore,
DownloadContentPort contentGateway,
FileAccessPolicyPort accessPolicy,
Optional<ZeroCopyDownloadPort> zeroCopyGateway,
FileserverMetricsPort metrics) {
this.metadataStore = metadataStore;
this.contentGateway = contentGateway;
this.accessPolicy = accessPolicy;
this.zeroCopyGateway = zeroCopyGateway;
this.metrics = metrics;
}
@Override
public FileView describeFile(FileId fileId, RequestContext context) {
FileRecord record = requireRecord(fileId);
accessPolicy.authorize(
FileOperation.READ_METADATA, context.subject(), Optional.of(record.toDescriptor()));
return FileView.of(record.toDescriptor());
}
@Override
public DownloadDescriptor describe(DownloadRequest request, RequestContext context) {
FileRecord record = requireRecord(request.fileId());
accessPolicy.authorize(
FileOperation.DOWNLOAD, context.subject(), Optional.of(record.toDescriptor()));
requireReadable(record);
FileRepresentation representation =
new FileRepresentation(
record.sha256().orElseThrow(DefaultDownloadApplicationService::readyWithoutValidator),
record
.publishedAt()
.orElseThrow(DefaultDownloadApplicationService::readyWithoutValidator),
record
.actualSize()
.orElseThrow(DefaultDownloadApplicationService::readyWithoutValidator),
record.verifiedMediaType().orElse("application/octet-stream"));
return new DownloadDescriptor(
record.fileId(),
representation,
record.contentKey().orElseThrow(DefaultDownloadApplicationService::readyWithoutKey),
new SanitizedFilename(record.originalName()));
}
@Override
public ReadableByteChannel openContent(DownloadDescriptor descriptor, ByteRange range) {
return contentGateway.openRead(descriptor.contentKey(), range);
}
@Override
public ZeroCopyTransferResult transferContent(
DownloadDescriptor descriptor, ByteRange range, WritableByteChannel sink) {
ZeroCopyTransferResult result =
zeroCopyGateway
.map(gateway -> gateway.transferTo(descriptor.contentKey(), range, sink))
.orElseGet(ZeroCopyTransferResult::notStarted);
String transferShape =
range.startInclusive() == 0 && range.length() == descriptor.representation().length()
? "full"
: "partial";
metrics.recordDownload(
"zero-copy",
transferShape,
result.outcome().name().toLowerCase(java.util.Locale.ROOT),
SizeBucket.of(range.length()),
java.time.Duration.ZERO,
result.transferredBytes());
return result;
}
private FileRecord requireRecord(FileId fileId) {
return metadataStore
.find(fileId)
.orElseThrow(
() ->
new FileNotFoundException(
"file record does not exist",
FileserverFailureContext.forFile(
FileserverErrorCode.FILE_NOT_FOUND, fileId, false)));
}
private static void requireReadable(FileRecord record) {
if (!record.state().isPubliclyReadable()) {
throw new FileserverException(
"file is not in a publicly readable state",
FileserverFailureContext.forFileState(
FileserverErrorCode.FILE_NOT_READY, record.fileId(), record.state(), true));
}
}
private static IllegalStateException readyWithoutKey() {
return new IllegalStateException("READY record has no content key");
}
private static IllegalStateException readyWithoutValidator() {
return new IllegalStateException("READY record has no size, digest, or publication instant");
}
}
@@ -0,0 +1,56 @@
package dev.caskeleton.application.fileserver.download;
import dev.caskeleton.application.capability.Idempotency;
import dev.caskeleton.application.capability.RepositoryAccess;
import dev.caskeleton.application.capability.UseCaseCapability;
import dev.caskeleton.application.fileserver.api.metadata.FileMetadataPort;
import dev.caskeleton.application.fileserver.api.metadata.FileRecord;
import dev.caskeleton.application.fileserver.api.metadata.FileRecords;
import dev.caskeleton.application.fileserver.api.security.FileAccessPolicyPort;
import dev.caskeleton.application.fileserver.api.security.FileOperation;
import dev.caskeleton.application.fileserver.port.in.DescribeFileQuery;
import dev.caskeleton.application.fileserver.port.in.DescribeFileUseCase;
import dev.caskeleton.application.fileserver.upload.FileView;
import dev.caskeleton.application.security.RequiresPermission;
import dev.caskeleton.application.transaction.TransactionMode;
import dev.caskeleton.application.transaction.TransactionPort;
import java.util.Objects;
import java.util.Optional;
/**
* Describes one file's metadata.
*
* <p>{@code file:read} is the role check; {@link FileAccessPolicyPort} still decides whether this
* caller owns this file.
*/
@RequiresPermission("file:read")
@UseCaseCapability(
transactionMode = TransactionMode.READ_ONLY,
idempotency = Idempotency.IDEMPOTENT,
repositoryAccess = RepositoryAccess.READ_REPOSITORY)
// Not final: @RequiresPermission is applied through a CGLIB proxy
// (RequiresPermissionProxyabilityTest).
public class DescribeFileApplicationUseCase implements DescribeFileUseCase {
private final FileMetadataPort metadataStore;
private final FileAccessPolicyPort accessPolicy;
private final TransactionPort transactions;
public DescribeFileApplicationUseCase(
FileMetadataPort metadataStore,
FileAccessPolicyPort accessPolicy,
TransactionPort transactions) {
this.metadataStore = Objects.requireNonNull(metadataStore, "metadataStore");
this.accessPolicy = Objects.requireNonNull(accessPolicy, "accessPolicy");
this.transactions = Objects.requireNonNull(transactions, "transactions");
}
@Override
public FileView handle(DescribeFileQuery query) {
FileRecord record =
transactions.inRead(() -> FileRecords.require(metadataStore, query.fileId()));
accessPolicy.authorize(
FileOperation.READ_METADATA, query.context().subject(), Optional.of(record.toDescriptor()));
return FileView.of(record.toDescriptor());
}
}
@@ -1,35 +0,0 @@
package dev.caskeleton.application.fileserver.download;
import dev.caskeleton.application.fileserver.api.ByteRange;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.upload.FileView;
import java.nio.channels.ReadableByteChannel;
import java.nio.channels.WritableByteChannel;
/**
* The download half of the public application surface.
*
* <p>{@link #describe} authorizes, requires READY, and evaluates validators and Range without
* touching content; only {@link #openContent} and {@link #transferContent} reach storage. A
* transport that answers {@code 304}, {@code 412}, or {@code 416} therefore never opens a byte.
*/
public interface DownloadApplicationService {
/** Public metadata for {@code GET /v1/files/{fileId}}. */
FileView describeFile(FileId fileId, RequestContext context);
DownloadDescriptor describe(DownloadRequest request, RequestContext context);
ReadableByteChannel openContent(DownloadDescriptor descriptor, ByteRange range);
/**
* Asks storage to write the region directly into {@code sink}.
*
* <p>Both this and {@link #openContent} start from an already-decided descriptor, so taking the
* fast path can never skip authorization or the READY gate. A {@code false} answer means the
* transport should stream instead; it is not an error and carries no response consequence.
*/
ZeroCopyTransferResult transferContent(
DownloadDescriptor descriptor, ByteRange range, WritableByteChannel sink);
}
@@ -1,16 +0,0 @@
package dev.caskeleton.application.fileserver.download;
import dev.caskeleton.application.fileserver.api.FileId;
import java.util.Objects;
/** Transport-neutral request to authorize and describe one readable file. */
public record DownloadRequest(FileId fileId) {
public DownloadRequest {
Objects.requireNonNull(fileId, "fileId");
}
public static DownloadRequest of(FileId fileId) {
return new DownloadRequest(fileId);
}
}
@@ -0,0 +1,41 @@
package dev.caskeleton.application.fileserver.download;
import dev.caskeleton.application.capability.Idempotency;
import dev.caskeleton.application.capability.RepositoryAccess;
import dev.caskeleton.application.capability.UseCaseCapability;
import dev.caskeleton.application.fileserver.port.in.OpenDownloadContentQuery;
import dev.caskeleton.application.fileserver.port.in.OpenDownloadContentUseCase;
import dev.caskeleton.application.fileserver.port.in.PrepareDownloadUseCase;
import dev.caskeleton.application.security.RequiresPermission;
import dev.caskeleton.application.transaction.TransactionMode;
import java.nio.channels.ReadableByteChannel;
import java.util.Objects;
/**
* Opens the published bytes a prepared download describes.
*
* <p>The descriptor is the authorization: only {@link PrepareDownloadUseCase} produces one, after
* the access policy allowed the read. The permission is checked again anyway, on the thread that
* streams, so a descriptor that outlived its caller's authority opens nothing.
*/
@RequiresPermission("file:read")
@UseCaseCapability(
transactionMode = TransactionMode.READ_ONLY,
idempotency = Idempotency.IDEMPOTENT,
repositoryAccess = RepositoryAccess.NONE,
externalOutboundAllowed = true)
// Not final: @RequiresPermission is applied through a CGLIB proxy
// (RequiresPermissionProxyabilityTest).
public class OpenDownloadContentApplicationUseCase implements OpenDownloadContentUseCase {
private final DownloadContentPort contentGateway;
public OpenDownloadContentApplicationUseCase(DownloadContentPort contentGateway) {
this.contentGateway = Objects.requireNonNull(contentGateway, "contentGateway");
}
@Override
public ReadableByteChannel handle(OpenDownloadContentQuery query) {
return contentGateway.openRead(query.descriptor().contentKey(), query.byteRange());
}
}
@@ -0,0 +1,82 @@
package dev.caskeleton.application.fileserver.download;
import dev.caskeleton.application.capability.Idempotency;
import dev.caskeleton.application.capability.RepositoryAccess;
import dev.caskeleton.application.capability.UseCaseCapability;
import dev.caskeleton.application.fileserver.api.metadata.FileMetadataPort;
import dev.caskeleton.application.fileserver.api.metadata.FileRecord;
import dev.caskeleton.application.fileserver.api.metadata.FileRecords;
import dev.caskeleton.application.fileserver.api.security.FileAccessPolicyPort;
import dev.caskeleton.application.fileserver.api.security.FileOperation;
import dev.caskeleton.application.fileserver.api.security.SanitizedFilename;
import dev.caskeleton.application.fileserver.api.transfer.FileRepresentation;
import dev.caskeleton.application.fileserver.port.in.PrepareDownloadQuery;
import dev.caskeleton.application.fileserver.port.in.PrepareDownloadUseCase;
import dev.caskeleton.application.security.RequiresPermission;
import dev.caskeleton.application.transaction.TransactionMode;
import dev.caskeleton.application.transaction.TransactionPort;
import java.util.Objects;
import java.util.Optional;
/**
* Authorizes a download and describes the representation it will serve.
*
* <p>{@code file:read} is the role check; {@link FileAccessPolicyPort} still decides whether this
* caller owns this file.
*/
@RequiresPermission("file:read")
@UseCaseCapability(
transactionMode = TransactionMode.READ_ONLY,
idempotency = Idempotency.IDEMPOTENT,
repositoryAccess = RepositoryAccess.READ_REPOSITORY)
// Not final: @RequiresPermission is applied through a CGLIB proxy
// (RequiresPermissionProxyabilityTest).
public class PrepareDownloadApplicationUseCase implements PrepareDownloadUseCase {
private final FileMetadataPort metadataStore;
private final FileAccessPolicyPort accessPolicy;
private final TransactionPort transactions;
public PrepareDownloadApplicationUseCase(
FileMetadataPort metadataStore,
FileAccessPolicyPort accessPolicy,
TransactionPort transactions) {
this.metadataStore = Objects.requireNonNull(metadataStore, "metadataStore");
this.accessPolicy = Objects.requireNonNull(accessPolicy, "accessPolicy");
this.transactions = Objects.requireNonNull(transactions, "transactions");
}
@Override
public DownloadDescriptor handle(PrepareDownloadQuery query) {
FileRecord record =
transactions.inRead(() -> FileRecords.require(metadataStore, query.fileId()));
accessPolicy.authorize(
FileOperation.DOWNLOAD, query.context().subject(), Optional.of(record.toDescriptor()));
FileRecords.requireReadable(record);
FileRepresentation representation =
new FileRepresentation(
record.sha256().orElseThrow(PrepareDownloadApplicationUseCase::readyWithoutValidator),
record
.publishedAt()
.orElseThrow(PrepareDownloadApplicationUseCase::readyWithoutValidator),
record
.actualSize()
.orElseThrow(PrepareDownloadApplicationUseCase::readyWithoutValidator),
record.verifiedMediaType().orElse("application/octet-stream"));
return new DownloadDescriptor(
record.fileId(),
representation,
record.contentKey().orElseThrow(PrepareDownloadApplicationUseCase::readyWithoutKey),
new SanitizedFilename(record.originalName()));
}
private static IllegalStateException readyWithoutKey() {
return new IllegalStateException("READY record has no content key");
}
private static IllegalStateException readyWithoutValidator() {
return new IllegalStateException("READY record has no size, digest, or publication instant");
}
}
@@ -0,0 +1,64 @@
package dev.caskeleton.application.fileserver.download;
import dev.caskeleton.application.capability.Idempotency;
import dev.caskeleton.application.capability.RepositoryAccess;
import dev.caskeleton.application.capability.UseCaseCapability;
import dev.caskeleton.application.fileserver.api.ByteRange;
import dev.caskeleton.application.fileserver.observability.FileserverMetricsPort;
import dev.caskeleton.application.fileserver.observability.SizeBucket;
import dev.caskeleton.application.fileserver.port.in.TransferDownloadContentQuery;
import dev.caskeleton.application.fileserver.port.in.TransferDownloadContentUseCase;
import dev.caskeleton.application.security.RequiresPermission;
import dev.caskeleton.application.transaction.TransactionMode;
import java.time.Duration;
import java.util.Locale;
import java.util.Objects;
import java.util.Optional;
/**
* Hands a prepared download to the storage for a kernel-level transfer, when it can.
*
* <p>A storage without zero copy answers {@link ZeroCopyTransferResult#notStarted()}, and the
* transport streams instead; the response is byte-identical either way.
*/
@RequiresPermission("file:read")
@UseCaseCapability(
transactionMode = TransactionMode.READ_ONLY,
idempotency = Idempotency.IDEMPOTENT,
repositoryAccess = RepositoryAccess.NONE,
externalOutboundAllowed = true)
// Not final: @RequiresPermission is applied through a CGLIB proxy
// (RequiresPermissionProxyabilityTest).
public class TransferDownloadContentApplicationUseCase implements TransferDownloadContentUseCase {
private final Optional<ZeroCopyDownloadPort> zeroCopyGateway;
private final FileserverMetricsPort metrics;
public TransferDownloadContentApplicationUseCase(
Optional<ZeroCopyDownloadPort> zeroCopyGateway, FileserverMetricsPort metrics) {
this.zeroCopyGateway = Objects.requireNonNull(zeroCopyGateway, "zeroCopyGateway");
this.metrics = Objects.requireNonNull(metrics, "metrics");
}
@Override
public ZeroCopyTransferResult handle(TransferDownloadContentQuery query) {
DownloadDescriptor descriptor = query.descriptor();
ByteRange range = query.byteRange();
ZeroCopyTransferResult result =
zeroCopyGateway
.map(gateway -> gateway.transferTo(descriptor.contentKey(), range, query.sink()))
.orElseGet(ZeroCopyTransferResult::notStarted);
String transferShape =
range.startInclusive() == 0 && range.length() == descriptor.representation().length()
? "full"
: "partial";
metrics.recordDownload(
"zero-copy",
transferShape,
result.outcome().name().toLowerCase(Locale.ROOT),
SizeBucket.of(range.length()),
Duration.ZERO,
result.transferredBytes());
return result;
}
}
@@ -0,0 +1,27 @@
package dev.caskeleton.application.fileserver.lifecycle;
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
import dev.caskeleton.application.fileserver.api.error.FileserverException;
import dev.caskeleton.application.fileserver.api.error.FileserverFailureContext;
import dev.caskeleton.application.fileserver.api.metadata.FileRecord;
import java.util.Optional;
/** The content-version precondition delete, copy and move all honour. */
final class ContentPreconditions {
private ContentPreconditions() {}
/** Enforces a transport-neutral content-version precondition over the immutable SHA-256. */
static void requireDigestMatches(FileRecord record, Optional<String> expectedSha256) {
if (expectedSha256.isEmpty()) {
return;
}
if (expectedSha256.orElseThrow().equals(record.sha256().orElse(null))) {
return;
}
throw new FileserverException(
"file validator does not match the caller's precondition",
FileserverFailureContext.forFileState(
FileserverErrorCode.PRECONDITION_FAILED, record.fileId(), record.state(), false));
}
}
@@ -0,0 +1,172 @@
package dev.caskeleton.application.fileserver.lifecycle;
import dev.caskeleton.application.capability.Idempotency;
import dev.caskeleton.application.capability.RepositoryAccess;
import dev.caskeleton.application.capability.UseCaseCapability;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.FileState;
import dev.caskeleton.application.fileserver.api.content.StoredContent;
import dev.caskeleton.application.fileserver.api.metadata.FileMetadataPort;
import dev.caskeleton.application.fileserver.api.metadata.FileRecord;
import dev.caskeleton.application.fileserver.api.metadata.FileRecordDraft;
import dev.caskeleton.application.fileserver.api.metadata.FileRecordMutation;
import dev.caskeleton.application.fileserver.api.metadata.FileRecords;
import dev.caskeleton.application.fileserver.api.security.FileAccessPolicyPort;
import dev.caskeleton.application.fileserver.api.security.FileOperation;
import dev.caskeleton.application.fileserver.api.security.OriginalFilenamePolicy;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.api.security.SanitizedFilename;
import dev.caskeleton.application.fileserver.port.in.CopyFileCommand;
import dev.caskeleton.application.fileserver.port.in.CopyFileUseCase;
import dev.caskeleton.application.fileserver.upload.FileView;
import dev.caskeleton.application.fileserver.upload.UploadIdentifierPort;
import dev.caskeleton.application.security.RequiresPermission;
import dev.caskeleton.application.transaction.TransactionMode;
import dev.caskeleton.application.transaction.TransactionPort;
import java.time.Clock;
import java.util.Objects;
import java.util.Optional;
/** Copies a readable file into a new file the caller owns. */
@RequiresPermission("file:copy")
@UseCaseCapability(
transactionMode = TransactionMode.WRITE,
idempotency = Idempotency.NOT_IDEMPOTENT,
repositoryAccess = RepositoryAccess.WRITE_REPOSITORY,
externalOutboundAllowed = true)
// Not final: @RequiresPermission is applied through a CGLIB proxy
// (RequiresPermissionProxyabilityTest).
public class CopyFileApplicationUseCase implements CopyFileUseCase {
private final FileMetadataPort metadataStore;
private final CopyContentPort copyGateway;
private final FileAccessPolicyPort accessPolicy;
private final OriginalFilenamePolicy filenamePolicy;
private final UploadIdentifierPort identifierFactory;
private final TransactionPort transactions;
private final Clock clock;
public CopyFileApplicationUseCase(
FileMetadataPort metadataStore,
CopyContentPort copyGateway,
FileAccessPolicyPort accessPolicy,
OriginalFilenamePolicy filenamePolicy,
UploadIdentifierPort identifierFactory,
TransactionPort transactions,
Clock clock) {
this.metadataStore = Objects.requireNonNull(metadataStore, "metadataStore");
this.copyGateway = Objects.requireNonNull(copyGateway, "copyGateway");
this.accessPolicy = Objects.requireNonNull(accessPolicy, "accessPolicy");
this.filenamePolicy = Objects.requireNonNull(filenamePolicy, "filenamePolicy");
this.identifierFactory = Objects.requireNonNull(identifierFactory, "identifierFactory");
this.transactions = Objects.requireNonNull(transactions, "transactions");
this.clock = Objects.requireNonNull(clock, "clock");
}
@Override
public FileView handle(CopyFileCommand command) {
RequestContext context = command.context();
FileRecord source = FileRecords.require(metadataStore, command.sourceFileId());
accessPolicy.authorize(
FileOperation.COPY, context.subject(), Optional.of(source.toDescriptor()));
ContentPreconditions.requireDigestMatches(source, command.expectedSha256());
FileRecords.requireReadable(source);
SanitizedFilename filename =
filenamePolicy.sanitize(command.targetFilename().orElse(source.originalName()));
FileId targetId = identifierFactory.newFileId();
FileRecord target =
transactions.inWrite(
() ->
metadataStore.insert(
new FileRecordDraft(
targetId,
command.targetNamespace(),
filename.value(),
source.verifiedMediaType().or(source::claimedMediaType),
source.actualSize(),
// The copy belongs to whoever made it, not to the source's owner.
context.subject().asOwner())));
StoredContent copied;
try {
copied =
copyGateway.copyCreateOnly(
source.contentKey().orElseThrow(CopyFileApplicationUseCase::readyWithoutKey),
command.targetNamespace());
} catch (RuntimeException failure) {
// The target may exist as a partial object; no rollback is promised, so it is queued for the
// cleanup worker instead of being left for an orphan scan to find much later.
failRecord(target, "COPY_FAILED");
throw failure;
}
return FileView.of(publish(target, copied).toDescriptor());
}
/** Walks the copied target to READY through the same edges an upload would take. */
private FileRecord publish(FileRecord target, StoredContent copied) {
// Four hops, one boundary. The intermediate states exist to satisfy the transition table, not
// to be observable; a copy that stalled on one of them would look like a stuck upload.
return transactions.inWrite(() -> publishSteps(target, copied));
}
private FileRecord publishSteps(FileRecord target, StoredContent copied) {
FileRecord uploading =
metadataStore.transition(
target.fileId(),
target.version(),
FileState.CREATED,
FileState.UPLOADING,
FileRecordMutation.none());
FileRecord uploaded =
metadataStore.transition(
uploading.fileId(),
uploading.version(),
FileState.UPLOADING,
FileState.UPLOADED,
FileRecordMutation.uploaded(copied.size(), copied.sha256()));
FileRecord verifying =
metadataStore.transition(
uploaded.fileId(),
uploaded.version(),
FileState.UPLOADED,
FileState.VERIFYING,
FileRecordMutation.none());
return metadataStore.transition(
verifying.fileId(),
verifying.version(),
FileState.VERIFYING,
FileState.READY,
FileRecordMutation.publishAt(
copied.contentKey(), copied.size(), copied.sha256(), clock.instant()));
}
/**
* Moves a freshly-created target to FAILED.
*
* <p>The transition table has no direct {@code CREATED -> FAILED} edge, so the record takes the
* one path it permits, through UPLOADING.
*/
private void failRecord(FileRecord record, String reasonCode) {
transactions.inWrite(
() -> {
FileRecord uploading =
metadataStore.transition(
record.fileId(),
record.version(),
FileState.CREATED,
FileState.UPLOADING,
FileRecordMutation.none());
metadataStore.transition(
uploading.fileId(),
uploading.version(),
FileState.UPLOADING,
FileState.FAILED,
FileRecordMutation.failure(reasonCode));
});
}
private static IllegalStateException readyWithoutKey() {
return new IllegalStateException("READY record has no content key");
}
}
@@ -1,270 +0,0 @@
package dev.caskeleton.application.fileserver.lifecycle;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.FileState;
import dev.caskeleton.application.fileserver.api.StorageNamespace;
import dev.caskeleton.application.fileserver.api.content.StoredContent;
import dev.caskeleton.application.fileserver.api.error.FileNotFoundException;
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
import dev.caskeleton.application.fileserver.api.error.FileserverException;
import dev.caskeleton.application.fileserver.api.error.FileserverFailureContext;
import dev.caskeleton.application.fileserver.api.metadata.FileMetadataPort;
import dev.caskeleton.application.fileserver.api.metadata.FileRecord;
import dev.caskeleton.application.fileserver.api.metadata.FileRecordDraft;
import dev.caskeleton.application.fileserver.api.metadata.FileRecordMutation;
import dev.caskeleton.application.fileserver.api.metadata.UploadSessionPort;
import dev.caskeleton.application.fileserver.api.security.FileAccessPolicyPort;
import dev.caskeleton.application.fileserver.api.security.FileOperation;
import dev.caskeleton.application.fileserver.api.security.OriginalFilenamePolicy;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.api.security.SanitizedFilename;
import dev.caskeleton.application.fileserver.cleanup.CleanupQueuePort;
import dev.caskeleton.application.fileserver.cleanup.FileRetirement;
import dev.caskeleton.application.fileserver.recovery.StagingUploadLocatorPort;
import dev.caskeleton.application.fileserver.upload.FileView;
import dev.caskeleton.application.fileserver.upload.UploadIdentifierPort;
import dev.caskeleton.application.transaction.TransactionPort;
import java.time.Clock;
import java.util.Optional;
/**
* Logical-first delete, copy, and move.
*
* <p>Delete transitions the record to DELETING <em>before</em> anything physical is scheduled, so a
* deleted file stops being downloadable the instant the metadata commits — even if the cleanup
* worker is hours behind. Copy is create-only and queues its partial target for cleanup rather than
* promising a rollback the filesystem cannot give. Move rewrites one metadata column and never
* touches the immutable object.
*/
public final class DefaultFileLifecycleService implements FileLifecycleService {
private final FileMetadataPort metadataStore;
private final CopyContentPort copyGateway;
private final FileAccessPolicyPort accessPolicy;
private final OriginalFilenamePolicy filenamePolicy;
private final UploadIdentifierPort identifierFactory;
private final TransactionPort transactions;
private final Clock clock;
private final FileRetirement retirement;
private final UploadSessionPort sessionStore;
private final StagingUploadLocatorPort stagingLocator;
public DefaultFileLifecycleService(
FileMetadataPort metadataStore,
CopyContentPort copyGateway,
FileAccessPolicyPort accessPolicy,
OriginalFilenamePolicy filenamePolicy,
CleanupQueuePort cleanupQueue,
UploadSessionPort sessionStore,
StagingUploadLocatorPort stagingLocator,
UploadIdentifierPort identifierFactory,
TransactionPort transactions,
Clock clock) {
this.metadataStore = metadataStore;
this.copyGateway = copyGateway;
this.accessPolicy = accessPolicy;
this.filenamePolicy = filenamePolicy;
this.identifierFactory = identifierFactory;
this.transactions = transactions;
this.clock = clock;
this.retirement = new FileRetirement(metadataStore, cleanupQueue);
this.sessionStore = sessionStore;
this.stagingLocator = stagingLocator;
}
@Override
public DeleteOutcome delete(
FileId fileId, Optional<String> expectedSha256, RequestContext context) {
FileRecord record = requireRecord(fileId);
accessPolicy.authorize(
FileOperation.DELETE, context.subject(), Optional.of(record.toDescriptor()));
requireDigestMatches(record, expectedSha256);
if (record.state() == FileState.DELETED) {
return new DeleteOutcome(fileId, false);
}
requireDeletable(record);
// One boundary for the whole decision: a record that reached DELETING without either its
// terminal transition or a queued reclamation would be unreachable and never collected.
return transactions.inWrite(
() ->
new DeleteOutcome(
fileId,
retirement.retireWithUnfinishedUpload(record, sessionStore, stagingLocator)));
}
@Override
public FileView copy(CopyFileCommand command, RequestContext context) {
FileRecord source = requireRecord(command.sourceFileId());
accessPolicy.authorize(
FileOperation.COPY, context.subject(), Optional.of(source.toDescriptor()));
requireDigestMatches(source, command.expectedSha256());
requireReadable(source);
SanitizedFilename filename =
filenamePolicy.sanitize(command.targetFilename().orElse(source.originalName()));
FileId targetId = identifierFactory.newFileId();
FileRecord target =
transactions.inWrite(
() ->
metadataStore.insert(
new FileRecordDraft(
targetId,
command.targetNamespace(),
filename.value(),
source.verifiedMediaType().or(source::claimedMediaType),
source.actualSize(),
// The copy belongs to whoever made it, not to the source's owner.
context.subject().asOwner())));
StoredContent copied;
try {
copied =
copyGateway.copyCreateOnly(
source.contentKey().orElseThrow(DefaultFileLifecycleService::readyWithoutKey),
command.targetNamespace());
} catch (RuntimeException failure) {
// The target may exist as a partial object; no rollback is promised, so it is queued for the
// cleanup worker instead of being left for an orphan scan to find much later.
failRecord(target, "COPY_FAILED");
throw failure;
}
return FileView.of(publish(target, copied).toDescriptor());
}
@Override
public FileView move(
FileId fileId,
StorageNamespace targetNamespace,
Optional<String> expectedSha256,
RequestContext context) {
FileRecord record = requireRecord(fileId);
accessPolicy.authorize(
FileOperation.MOVE, context.subject(), Optional.of(record.toDescriptor()));
requireDigestMatches(record, expectedSha256);
requireReadable(record);
return FileView.of(
transactions
.inWrite(() -> metadataStore.relocate(fileId, record.version(), targetNamespace))
.toDescriptor());
}
/** Walks the copied target to READY through the same edges an upload would take. */
private FileRecord publish(FileRecord target, StoredContent copied) {
// Four hops, one boundary. The intermediate states exist to satisfy the transition table, not
// to be observable; a copy that stalled on one of them would look like a stuck upload.
return transactions.inWrite(() -> publishSteps(target, copied));
}
private FileRecord publishSteps(FileRecord target, StoredContent copied) {
FileRecord uploading =
metadataStore.transition(
target.fileId(),
target.version(),
FileState.CREATED,
FileState.UPLOADING,
FileRecordMutation.none());
FileRecord uploaded =
metadataStore.transition(
uploading.fileId(),
uploading.version(),
FileState.UPLOADING,
FileState.UPLOADED,
FileRecordMutation.uploaded(copied.size(), copied.sha256()));
FileRecord verifying =
metadataStore.transition(
uploaded.fileId(),
uploaded.version(),
FileState.UPLOADED,
FileState.VERIFYING,
FileRecordMutation.none());
return metadataStore.transition(
verifying.fileId(),
verifying.version(),
FileState.VERIFYING,
FileState.READY,
FileRecordMutation.publishAt(
copied.contentKey(), copied.size(), copied.sha256(), clock.instant()));
}
/**
* Moves a freshly-created target to FAILED.
*
* <p>The transition table has no direct {@code CREATED -> FAILED} edge, so the record takes the
* one path it permits, through UPLOADING.
*/
private void failRecord(FileRecord record, String reasonCode) {
transactions.inWrite(
() -> {
FileRecord uploading =
metadataStore.transition(
record.fileId(),
record.version(),
FileState.CREATED,
FileState.UPLOADING,
FileRecordMutation.none());
metadataStore.transition(
uploading.fileId(),
uploading.version(),
FileState.UPLOADING,
FileState.FAILED,
FileRecordMutation.failure(reasonCode));
});
}
/** Enforces a transport-neutral content-version precondition over the immutable SHA-256. */
private static void requireDigestMatches(FileRecord record, Optional<String> expectedSha256) {
if (expectedSha256.isEmpty()) {
return;
}
if (expectedSha256.orElseThrow().equals(record.sha256().orElse(null))) {
return;
}
throw new FileserverException(
"file validator does not match the caller's precondition",
FileserverFailureContext.forFileState(
FileserverErrorCode.PRECONDITION_FAILED, record.fileId(), record.state(), false));
}
/**
* Refuses a delete from a state that has no DELETING edge.
*
* <p>CREATED and VERIFYING are transient states owned by the upload and verification pipelines.
* Forcing them into DELETING would either invent a transition the state machine does not have, or
* mislabel the file as verifier-rejected. The caller is told to retry once the state settles.
*/
private static void requireDeletable(FileRecord record) {
if (record.state() == FileState.CREATED || record.state() == FileState.VERIFYING) {
throw new FileserverException(
"file is in a transient state that cannot be deleted yet",
FileserverFailureContext.forFileState(
FileserverErrorCode.FILE_NOT_READY, record.fileId(), record.state(), true));
}
}
private static void requireReadable(FileRecord record) {
if (!record.state().isPubliclyReadable()) {
throw new FileserverException(
"file is not in a publicly readable state",
FileserverFailureContext.forFileState(
FileserverErrorCode.FILE_NOT_READY, record.fileId(), record.state(), true));
}
}
private FileRecord requireRecord(FileId fileId) {
return metadataStore
.find(fileId)
.orElseThrow(
() ->
new FileNotFoundException(
"file record does not exist",
FileserverFailureContext.forFile(
FileserverErrorCode.FILE_NOT_FOUND, fileId, false)));
}
private static IllegalStateException readyWithoutKey() {
return new IllegalStateException("READY record has no content key");
}
}
@@ -0,0 +1,102 @@
package dev.caskeleton.application.fileserver.lifecycle;
import dev.caskeleton.application.capability.Idempotency;
import dev.caskeleton.application.capability.RepositoryAccess;
import dev.caskeleton.application.capability.UseCaseCapability;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.FileState;
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
import dev.caskeleton.application.fileserver.api.error.FileserverException;
import dev.caskeleton.application.fileserver.api.error.FileserverFailureContext;
import dev.caskeleton.application.fileserver.api.metadata.FileMetadataPort;
import dev.caskeleton.application.fileserver.api.metadata.FileRecord;
import dev.caskeleton.application.fileserver.api.metadata.FileRecords;
import dev.caskeleton.application.fileserver.api.metadata.UploadSessionPort;
import dev.caskeleton.application.fileserver.api.security.FileAccessPolicyPort;
import dev.caskeleton.application.fileserver.api.security.FileOperation;
import dev.caskeleton.application.fileserver.cleanup.CleanupQueuePort;
import dev.caskeleton.application.fileserver.cleanup.FileRetirement;
import dev.caskeleton.application.fileserver.port.in.DeleteFileCommand;
import dev.caskeleton.application.fileserver.port.in.DeleteFileUseCase;
import dev.caskeleton.application.fileserver.recovery.StagingUploadLocatorPort;
import dev.caskeleton.application.security.RequiresPermission;
import dev.caskeleton.application.transaction.TransactionMode;
import dev.caskeleton.application.transaction.TransactionPort;
import java.util.Objects;
import java.util.Optional;
/**
* Deletes a file: it stops being reachable and its content is queued for reclamation.
*
* <p>{@code file:delete} is the role check; {@link FileAccessPolicyPort} still decides whether this
* caller owns this file, so the permission never reaches somebody else's.
*/
@RequiresPermission("file:delete")
@UseCaseCapability(
transactionMode = TransactionMode.WRITE,
idempotency = Idempotency.IDEMPOTENT,
repositoryAccess = RepositoryAccess.WRITE_REPOSITORY)
// Not final: @RequiresPermission is applied through a CGLIB proxy
// (RequiresPermissionProxyabilityTest).
public class DeleteFileApplicationUseCase implements DeleteFileUseCase {
private final FileMetadataPort metadataStore;
private final FileAccessPolicyPort accessPolicy;
private final FileRetirement retirement;
private final UploadSessionPort sessionStore;
private final StagingUploadLocatorPort stagingLocator;
private final TransactionPort transactions;
public DeleteFileApplicationUseCase(
FileMetadataPort metadataStore,
FileAccessPolicyPort accessPolicy,
CleanupQueuePort cleanupQueue,
UploadSessionPort sessionStore,
StagingUploadLocatorPort stagingLocator,
TransactionPort transactions) {
this.metadataStore = Objects.requireNonNull(metadataStore, "metadataStore");
this.accessPolicy = Objects.requireNonNull(accessPolicy, "accessPolicy");
this.retirement = new FileRetirement(metadataStore, cleanupQueue);
this.sessionStore = Objects.requireNonNull(sessionStore, "sessionStore");
this.stagingLocator = Objects.requireNonNull(stagingLocator, "stagingLocator");
this.transactions = Objects.requireNonNull(transactions, "transactions");
}
@Override
public DeleteOutcome handle(DeleteFileCommand command) {
FileId fileId = command.fileId();
FileRecord record = FileRecords.require(metadataStore, fileId);
accessPolicy.authorize(
FileOperation.DELETE, command.context().subject(), Optional.of(record.toDescriptor()));
ContentPreconditions.requireDigestMatches(record, command.expectedSha256());
if (record.state() == FileState.DELETED) {
return new DeleteOutcome(fileId, false);
}
requireDeletable(record);
// One boundary for the whole decision: a record that reached DELETING without either its
// terminal transition or a queued reclamation would be unreachable and never collected.
return transactions.inWrite(
() ->
new DeleteOutcome(
fileId,
retirement.retireWithUnfinishedUpload(record, sessionStore, stagingLocator)));
}
/**
* Refuses a delete from a state that has no DELETING edge.
*
* <p>CREATED and VERIFYING are transient states owned by the upload and verification pipelines.
* Forcing them into DELETING would either invent a transition the state machine does not have, or
* mislabel the file as verifier-rejected. The caller is told to retry once the state settles.
*/
private static void requireDeletable(FileRecord record) {
if (record.state() == FileState.CREATED || record.state() == FileState.VERIFYING) {
throw new FileserverException(
"file is in a transient state that cannot be deleted yet",
FileserverFailureContext.forFileState(
FileserverErrorCode.FILE_NOT_READY, record.fileId(), record.state(), true));
}
}
}
@@ -1,31 +0,0 @@
package dev.caskeleton.application.fileserver.lifecycle;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.StorageNamespace;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.upload.FileView;
import java.util.Optional;
/**
* Delete, copy, and move — the inbound port the transport reaches them through.
*
* <p>All three are logical-first: the metadata record decides reachability, and physical work is
* deferred to the cleanup worker. That ordering is what makes a delete take effect immediately even
* when the filesystem is slow or briefly unavailable.
*
* <p>An interface with one implementation, kept on purpose: an inbound adapter may depend only on a
* port, never on a concrete application service ({@code
* INBOUND_ADAPTERS_DEPEND_ON_PORTS_NOT_APPLICATION_SERVICES}).
*/
public interface FileLifecycleService {
DeleteOutcome delete(FileId fileId, Optional<String> expectedSha256, RequestContext context);
FileView copy(CopyFileCommand command, RequestContext context);
FileView move(
FileId fileId,
StorageNamespace targetNamespace,
Optional<String> expectedSha256,
RequestContext context);
}
@@ -0,0 +1,59 @@
package dev.caskeleton.application.fileserver.lifecycle;
import dev.caskeleton.application.capability.Idempotency;
import dev.caskeleton.application.capability.RepositoryAccess;
import dev.caskeleton.application.capability.UseCaseCapability;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.metadata.FileMetadataPort;
import dev.caskeleton.application.fileserver.api.metadata.FileRecord;
import dev.caskeleton.application.fileserver.api.metadata.FileRecords;
import dev.caskeleton.application.fileserver.api.security.FileAccessPolicyPort;
import dev.caskeleton.application.fileserver.api.security.FileOperation;
import dev.caskeleton.application.fileserver.port.in.MoveFileCommand;
import dev.caskeleton.application.fileserver.port.in.MoveFileUseCase;
import dev.caskeleton.application.fileserver.upload.FileView;
import dev.caskeleton.application.security.RequiresPermission;
import dev.caskeleton.application.transaction.TransactionMode;
import dev.caskeleton.application.transaction.TransactionPort;
import java.util.Objects;
import java.util.Optional;
/** Moves a readable file to another namespace. */
@RequiresPermission("file:move")
@UseCaseCapability(
transactionMode = TransactionMode.WRITE,
idempotency = Idempotency.IDEMPOTENT,
repositoryAccess = RepositoryAccess.WRITE_REPOSITORY)
// Not final: @RequiresPermission is applied through a CGLIB proxy
// (RequiresPermissionProxyabilityTest).
public class MoveFileApplicationUseCase implements MoveFileUseCase {
private final FileMetadataPort metadataStore;
private final FileAccessPolicyPort accessPolicy;
private final TransactionPort transactions;
public MoveFileApplicationUseCase(
FileMetadataPort metadataStore,
FileAccessPolicyPort accessPolicy,
TransactionPort transactions) {
this.metadataStore = Objects.requireNonNull(metadataStore, "metadataStore");
this.accessPolicy = Objects.requireNonNull(accessPolicy, "accessPolicy");
this.transactions = Objects.requireNonNull(transactions, "transactions");
}
@Override
public FileView handle(MoveFileCommand command) {
FileId fileId = command.fileId();
FileRecord record = FileRecords.require(metadataStore, fileId);
accessPolicy.authorize(
FileOperation.MOVE, command.context().subject(), Optional.of(record.toDescriptor()));
ContentPreconditions.requireDigestMatches(record, command.expectedSha256());
FileRecords.requireReadable(record);
return FileView.of(
transactions
.inWrite(
() -> metadataStore.relocate(fileId, record.version(), command.targetNamespace()))
.toDescriptor());
}
}
@@ -0,0 +1,35 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.command.Command;
import dev.caskeleton.application.fileserver.api.UploadId;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import java.nio.channels.ReadableByteChannel;
import java.util.Objects;
import java.util.Optional;
/**
* Append one chunk at the offset the client believes is committed.
*
* @param uploadId the open upload
* @param expectedOffset the offset the client believes is committed
* @param content the bytes to append; the caller owns and closes it
* @param contentLength the declared chunk length, or a negative value when unknown
* @param expectedChunkSha256 the client's digest of this chunk, if any
* @param context the caller
*/
public record AppendUploadCommand(
UploadId uploadId,
long expectedOffset,
ReadableByteChannel content,
long contentLength,
Optional<String> expectedChunkSha256,
RequestContext context)
implements Command {
public AppendUploadCommand {
Objects.requireNonNull(uploadId, "uploadId");
Objects.requireNonNull(content, "content");
Objects.requireNonNull(expectedChunkSha256, "expectedChunkSha256");
Objects.requireNonNull(context, "context");
}
}
@@ -0,0 +1,8 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.fileserver.upload.AppendUploadResult;
import dev.caskeleton.application.usecase.CommandUseCase;
/** Appends one chunk to an open upload under a writer lease. */
public interface AppendUploadUseCase
extends CommandUseCase<AppendUploadCommand, AppendUploadResult> {}
@@ -0,0 +1,20 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.command.Command;
import dev.caskeleton.application.fileserver.api.UploadId;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import java.util.Objects;
/**
* Cancel one upload.
*
* @param uploadId the upload
* @param context the caller
*/
public record CancelUploadCommand(UploadId uploadId, RequestContext context) implements Command {
public CancelUploadCommand {
Objects.requireNonNull(uploadId, "uploadId");
Objects.requireNonNull(context, "context");
}
}
@@ -0,0 +1,6 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.usecase.CommandUseCase;
/** Cancels an upload: the record stops being reachable and its bytes are queued for removal. */
public interface CancelUploadUseCase extends CommandUseCase<CancelUploadCommand, Void> {}
@@ -0,0 +1,20 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.command.Command;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import java.util.Objects;
/**
* Run one cleanup batch.
*
* @param maxItems the most queued items to process; capped by the use case
* @param maxBytes the byte budget of the batch
* @param context the operator
*/
public record CleanupUploadsCommand(int maxItems, long maxBytes, RequestContext context)
implements Command {
public CleanupUploadsCommand {
Objects.requireNonNull(context, "context");
}
}
@@ -0,0 +1,8 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.fileserver.cleanup.CleanupBatchResult;
import dev.caskeleton.application.usecase.CommandUseCase;
/** Runs one cleanup batch on an operator's request. */
public interface CleanupUploadsUseCase
extends CommandUseCase<CleanupUploadsCommand, CleanupBatchResult> {}
@@ -1,27 +1,34 @@
package dev.caskeleton.application.fileserver.lifecycle;
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.command.Command;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.StorageNamespace;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import java.util.Objects;
import java.util.Optional;
/**
* Intent to copy a READY file into a namespace.
* Copy one file.
*
* <p>{@code expectedSha256} is an optional immutable-content version asserted by the caller.
* Transport adapters translate their own validator syntax into this raw digest before invoking the
* use case.
* @param sourceFileId the file to copy
* @param targetNamespace where the copy goes
* @param targetFilename the copy's display name, if not the source's
* @param expectedSha256 the caller's content-version precondition, if any
* @param context the caller
*/
public record CopyFileCommand(
FileId sourceFileId,
StorageNamespace targetNamespace,
Optional<String> targetFilename,
Optional<String> expectedSha256) {
Optional<String> expectedSha256,
RequestContext context)
implements Command {
public CopyFileCommand {
Objects.requireNonNull(sourceFileId, "sourceFileId");
Objects.requireNonNull(targetNamespace, "targetNamespace");
Objects.requireNonNull(targetFilename, "targetFilename");
Objects.requireNonNull(expectedSha256, "expectedSha256");
Objects.requireNonNull(context, "context");
}
}
@@ -0,0 +1,7 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.fileserver.upload.FileView;
import dev.caskeleton.application.usecase.CommandUseCase;
/** Copies a readable file into a new file the caller owns. */
public interface CopyFileUseCase extends CommandUseCase<CopyFileCommand, FileView> {}
@@ -0,0 +1,21 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.command.Command;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.upload.CreateUploadRequest;
import java.util.Objects;
/**
* Open one upload for the caller.
*
* @param request what the client asked for
* @param context the caller
*/
public record CreateUploadCommand(CreateUploadRequest request, RequestContext context)
implements Command {
public CreateUploadCommand {
Objects.requireNonNull(request, "request");
Objects.requireNonNull(context, "context");
}
}
@@ -0,0 +1,8 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.fileserver.upload.UploadSessionView;
import dev.caskeleton.application.usecase.CommandUseCase;
/** Opens an upload: reserves quota, records the file and its session, and creates staging. */
public interface CreateUploadUseCase
extends CommandUseCase<CreateUploadCommand, UploadSessionView> {}
@@ -0,0 +1,24 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.command.Command;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import java.util.Objects;
import java.util.Optional;
/**
* Delete one file.
*
* @param fileId the file
* @param expectedSha256 the caller's content-version precondition, if any
* @param context the caller
*/
public record DeleteFileCommand(
FileId fileId, Optional<String> expectedSha256, RequestContext context) implements Command {
public DeleteFileCommand {
Objects.requireNonNull(fileId, "fileId");
Objects.requireNonNull(expectedSha256, "expectedSha256");
Objects.requireNonNull(context, "context");
}
}
@@ -0,0 +1,7 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.fileserver.lifecycle.DeleteOutcome;
import dev.caskeleton.application.usecase.CommandUseCase;
/** Deletes a file: it stops being reachable and its content is queued for reclamation. */
public interface DeleteFileUseCase extends CommandUseCase<DeleteFileCommand, DeleteOutcome> {}
@@ -0,0 +1,20 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.query.Query;
import java.util.Objects;
/**
* Read one file's metadata.
*
* @param fileId the file
* @param context the caller
*/
public record DescribeFileQuery(FileId fileId, RequestContext context) implements Query {
public DescribeFileQuery {
Objects.requireNonNull(fileId, "fileId");
Objects.requireNonNull(context, "context");
}
}
@@ -0,0 +1,7 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.fileserver.upload.FileView;
import dev.caskeleton.application.usecase.QueryUseCase;
/** Describes one file's metadata to a caller allowed to read it. */
public interface DescribeFileUseCase extends QueryUseCase<DescribeFileQuery, FileView> {}
@@ -0,0 +1,24 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.command.Command;
import dev.caskeleton.application.fileserver.api.UploadId;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.upload.FinalizeUploadRequest;
import java.util.Objects;
/**
* Finalize one upload.
*
* @param uploadId the fully received upload
* @param request the client's finalization assertions
* @param context the caller
*/
public record FinalizeUploadCommand(
UploadId uploadId, FinalizeUploadRequest request, RequestContext context) implements Command {
public FinalizeUploadCommand {
Objects.requireNonNull(uploadId, "uploadId");
Objects.requireNonNull(request, "request");
Objects.requireNonNull(context, "context");
}
}
@@ -0,0 +1,7 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.fileserver.upload.FileView;
import dev.caskeleton.application.usecase.CommandUseCase;
/** Verifies and publishes a fully received upload. */
public interface FinalizeUploadUseCase extends CommandUseCase<FinalizeUploadCommand, FileView> {}
@@ -1,6 +1,8 @@
package dev.caskeleton.application.fileserver.admin;
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.command.Command;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import java.util.Objects;
/**
@@ -9,14 +11,20 @@ import java.util.Objects;
* <p>The reason is mandatory and the caller must hold the second, force-delete-specific authority.
* A force delete that needed only the ordinary delete permission would make every operator able to
* destroy content the lifecycle rules exist to protect.
*
* @param fileId the file
* @param reasonCode why, for the audit trail
* @param context the operator
*/
public record ForceDeleteCommand(FileId fileId, String reasonCode) {
public record ForceDeleteCommand(FileId fileId, String reasonCode, RequestContext context)
implements Command {
private static final int MINIMUM_REASON_LENGTH = 8;
public ForceDeleteCommand {
Objects.requireNonNull(fileId, "fileId");
Objects.requireNonNull(reasonCode, "reasonCode");
Objects.requireNonNull(context, "context");
if (reasonCode.strip().length() < MINIMUM_REASON_LENGTH) {
throw new IllegalArgumentException("force delete requires an explicit reason");
}
@@ -0,0 +1,6 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.usecase.CommandUseCase;
/** Removes a file on an operator's authority, bypassing the data-plane preconditions. */
public interface ForceDeleteFileUseCase extends CommandUseCase<ForceDeleteCommand, Void> {}
@@ -0,0 +1,17 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.query.Query;
import java.util.Objects;
/**
* Read the runtime capabilities.
*
* @param context the operator
*/
public record GetRuntimeCapabilitiesQuery(RequestContext context) implements Query {
public GetRuntimeCapabilitiesQuery {
Objects.requireNonNull(context, "context");
}
}
@@ -0,0 +1,8 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.fileserver.admin.RuntimeCapabilityReport;
import dev.caskeleton.application.usecase.QueryUseCase;
/** Reports what the running storage supports to an operator. */
public interface GetRuntimeCapabilitiesUseCase
extends QueryUseCase<GetRuntimeCapabilitiesQuery, RuntimeCapabilityReport> {}
@@ -0,0 +1,17 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.query.Query;
import java.util.Objects;
/**
* Read storage health.
*
* @param context the operator
*/
public record GetStorageHealthQuery(RequestContext context) implements Query {
public GetStorageHealthQuery {
Objects.requireNonNull(context, "context");
}
}
@@ -0,0 +1,8 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.fileserver.admin.StorageHealthReport;
import dev.caskeleton.application.usecase.QueryUseCase;
/** Reports the storage's health to an operator. */
public interface GetStorageHealthUseCase
extends QueryUseCase<GetStorageHealthQuery, StorageHealthReport> {}
@@ -0,0 +1,20 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.fileserver.api.UploadId;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.query.Query;
import java.util.Objects;
/**
* Read where an open upload stands.
*
* @param uploadId the upload
* @param context the caller
*/
public record GetUploadStatusQuery(UploadId uploadId, RequestContext context) implements Query {
public GetUploadStatusQuery {
Objects.requireNonNull(uploadId, "uploadId");
Objects.requireNonNull(context, "context");
}
}
@@ -0,0 +1,8 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.fileserver.upload.UploadSessionView;
import dev.caskeleton.application.usecase.QueryUseCase;
/** Reports the committed offset of an open upload; an ended upload answers gone. */
public interface GetUploadStatusUseCase
extends QueryUseCase<GetUploadStatusQuery, UploadSessionView> {}
@@ -0,0 +1,18 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.query.Query;
import java.util.Objects;
/**
* List incomplete uploads.
*
* @param limit the page size; capped by the use case
* @param context the operator
*/
public record ListIncompleteUploadsQuery(int limit, RequestContext context) implements Query {
public ListIncompleteUploadsQuery {
Objects.requireNonNull(context, "context");
}
}
@@ -0,0 +1,9 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.fileserver.admin.IncompleteUploadView;
import dev.caskeleton.application.usecase.QueryUseCase;
import java.util.List;
/** Lists uploads that expired before they finished. */
public interface ListIncompleteUploadsUseCase
extends QueryUseCase<ListIncompleteUploadsQuery, List<IncompleteUploadView>> {}
@@ -0,0 +1,18 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.query.Query;
import java.util.Objects;
/**
* List orphaned objects.
*
* @param limit the page size; capped by the use case
* @param context the operator
*/
public record ListOrphansQuery(int limit, RequestContext context) implements Query {
public ListOrphansQuery {
Objects.requireNonNull(context, "context");
}
}
@@ -0,0 +1,8 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.fileserver.admin.OrphanObject;
import dev.caskeleton.application.usecase.QueryUseCase;
import java.util.List;
/** Lists physical objects no record refers to. */
public interface ListOrphansUseCase extends QueryUseCase<ListOrphansQuery, List<OrphanObject>> {}
@@ -0,0 +1,31 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.command.Command;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.StorageNamespace;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import java.util.Objects;
import java.util.Optional;
/**
* Move one file.
*
* @param fileId the file
* @param targetNamespace where it moves
* @param expectedSha256 the caller's content-version precondition, if any
* @param context the caller
*/
public record MoveFileCommand(
FileId fileId,
StorageNamespace targetNamespace,
Optional<String> expectedSha256,
RequestContext context)
implements Command {
public MoveFileCommand {
Objects.requireNonNull(fileId, "fileId");
Objects.requireNonNull(targetNamespace, "targetNamespace");
Objects.requireNonNull(expectedSha256, "expectedSha256");
Objects.requireNonNull(context, "context");
}
}
@@ -0,0 +1,7 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.fileserver.upload.FileView;
import dev.caskeleton.application.usecase.CommandUseCase;
/** Moves a readable file to another namespace. */
public interface MoveFileUseCase extends CommandUseCase<MoveFileCommand, FileView> {}
@@ -0,0 +1,21 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.fileserver.api.ByteRange;
import dev.caskeleton.application.fileserver.download.DownloadDescriptor;
import dev.caskeleton.application.query.Query;
import java.util.Objects;
/**
* Open a range of a prepared download.
*
* @param descriptor what an authorized prepare returned
* @param byteRange the bytes to read
*/
public record OpenDownloadContentQuery(DownloadDescriptor descriptor, ByteRange byteRange)
implements Query {
public OpenDownloadContentQuery {
Objects.requireNonNull(descriptor, "descriptor");
Objects.requireNonNull(byteRange, "byteRange");
}
}
@@ -0,0 +1,8 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.usecase.QueryUseCase;
import java.nio.channels.ReadableByteChannel;
/** Opens the published bytes a prepared download describes. */
public interface OpenDownloadContentUseCase
extends QueryUseCase<OpenDownloadContentQuery, ReadableByteChannel> {}
@@ -1,5 +1,7 @@
package dev.caskeleton.application.fileserver.admin;
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.command.Command;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import java.util.List;
import java.util.Objects;
@@ -9,17 +11,27 @@ import java.util.Objects;
* <p>{@code dryRun} defaults to true at every layer above this record. An apply additionally has to
* name the exact fingerprints it intends to remove and a byte budget, so a reconcile can never turn
* into an unbounded mass delete driven by a stale scan.
*
* @param dryRun list only, remove nothing
* @param limit the most candidates to consider
* @param maxBytes the byte budget of an apply
* @param expectedFingerprints the exact objects an apply may remove
* @param reasonCode why, for the audit trail
* @param context the operator
*/
public record OrphanReconcileCommand(
boolean dryRun,
int limit,
long maxBytes,
List<String> expectedFingerprints,
String reasonCode) {
String reasonCode,
RequestContext context)
implements Command {
public OrphanReconcileCommand {
Objects.requireNonNull(expectedFingerprints, "expectedFingerprints");
Objects.requireNonNull(reasonCode, "reasonCode");
Objects.requireNonNull(context, "context");
if (limit < 1 || maxBytes < 1) {
throw new IllegalArgumentException("limit and maxBytes must be positive");
}
@@ -34,7 +46,8 @@ public record OrphanReconcileCommand(
}
/** Bounded dry run, the default and the only shape a caller can reach without opting in. */
public static OrphanReconcileCommand dryRun(int limit) {
return new OrphanReconcileCommand(true, limit, Long.MAX_VALUE, List.of(), "ORPHAN_SCAN");
public static OrphanReconcileCommand dryRun(int limit, RequestContext context) {
return new OrphanReconcileCommand(
true, limit, Long.MAX_VALUE, List.of(), "ORPHAN_SCAN", context);
}
}
@@ -0,0 +1,20 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.query.Query;
import java.util.Objects;
/**
* Authorize and describe one readable file.
*
* @param fileId the file
* @param context the caller
*/
public record PrepareDownloadQuery(FileId fileId, RequestContext context) implements Query {
public PrepareDownloadQuery {
Objects.requireNonNull(fileId, "fileId");
Objects.requireNonNull(context, "context");
}
}
@@ -0,0 +1,8 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.fileserver.download.DownloadDescriptor;
import dev.caskeleton.application.usecase.QueryUseCase;
/** Authorizes a download and describes the readable representation it will serve. */
public interface PrepareDownloadUseCase
extends QueryUseCase<PrepareDownloadQuery, DownloadDescriptor> {}
@@ -0,0 +1,8 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.fileserver.admin.OrphanReconcileReport;
import dev.caskeleton.application.usecase.CommandUseCase;
/** Removes, or with a dry run only lists, the orphaned objects an operator names. */
public interface ReconcileOrphansUseCase
extends CommandUseCase<OrphanReconcileCommand, OrphanReconcileReport> {}
@@ -0,0 +1,20 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.command.Command;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import java.util.Objects;
/**
* Re-verify one quarantined file.
*
* @param fileId the quarantined file
* @param context the operator
*/
public record ReverifyFileCommand(FileId fileId, RequestContext context) implements Command {
public ReverifyFileCommand {
Objects.requireNonNull(fileId, "fileId");
Objects.requireNonNull(context, "context");
}
}
@@ -0,0 +1,7 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.fileserver.upload.FileView;
import dev.caskeleton.application.usecase.CommandUseCase;
/** Sends a quarantined file back to verification. */
public interface ReverifyFileUseCase extends CommandUseCase<ReverifyFileCommand, FileView> {}
@@ -0,0 +1,24 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.fileserver.api.ByteRange;
import dev.caskeleton.application.fileserver.download.DownloadDescriptor;
import dev.caskeleton.application.query.Query;
import java.nio.channels.WritableByteChannel;
import java.util.Objects;
/**
* Transfer a range of a prepared download straight into a sink.
*
* @param descriptor what an authorized prepare returned
* @param byteRange the bytes to send
* @param sink where the storage sends them
*/
public record TransferDownloadContentQuery(
DownloadDescriptor descriptor, ByteRange byteRange, WritableByteChannel sink) implements Query {
public TransferDownloadContentQuery {
Objects.requireNonNull(descriptor, "descriptor");
Objects.requireNonNull(byteRange, "byteRange");
Objects.requireNonNull(sink, "sink");
}
}
@@ -0,0 +1,8 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.fileserver.download.ZeroCopyTransferResult;
import dev.caskeleton.application.usecase.QueryUseCase;
/** Hands a prepared download to the storage for a kernel-level transfer, when it can. */
public interface TransferDownloadContentUseCase
extends QueryUseCase<TransferDownloadContentQuery, ZeroCopyTransferResult> {}
@@ -0,0 +1,33 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.command.Command;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.upload.CreateUploadRequest;
import dev.caskeleton.application.fileserver.upload.FinalizeUploadRequest;
import java.nio.channels.ReadableByteChannel;
import java.util.Objects;
/**
* Upload one whole file in a single request.
*
* @param request what the client asked for
* @param content the whole body; the caller owns and closes it
* @param contentLength the declared length, or a negative value when unknown
* @param finalizeRequest the client's finalization assertions
* @param context the caller
*/
public record UploadFileCommand(
CreateUploadRequest request,
ReadableByteChannel content,
long contentLength,
FinalizeUploadRequest finalizeRequest,
RequestContext context)
implements Command {
public UploadFileCommand {
Objects.requireNonNull(request, "request");
Objects.requireNonNull(content, "content");
Objects.requireNonNull(finalizeRequest, "finalizeRequest");
Objects.requireNonNull(context, "context");
}
}
@@ -0,0 +1,7 @@
package dev.caskeleton.application.fileserver.port.in;
import dev.caskeleton.application.fileserver.upload.FileView;
import dev.caskeleton.application.usecase.CommandUseCase;
/** Stores a whole file in one request: create, append and finalize as one operation. */
public interface UploadFileUseCase extends CommandUseCase<UploadFileCommand, FileView> {}
@@ -0,0 +1,170 @@
package dev.caskeleton.application.fileserver.upload;
import dev.caskeleton.application.capability.Idempotency;
import dev.caskeleton.application.capability.RepositoryAccess;
import dev.caskeleton.application.capability.UseCaseCapability;
import dev.caskeleton.application.fileserver.api.UploadId;
import dev.caskeleton.application.fileserver.api.content.AppendResult;
import dev.caskeleton.application.fileserver.api.content.UploadHandle;
import dev.caskeleton.application.fileserver.api.error.UploadOffsetMismatchException;
import dev.caskeleton.application.fileserver.api.metadata.FileMetadataPort;
import dev.caskeleton.application.fileserver.api.metadata.FileRecord;
import dev.caskeleton.application.fileserver.api.metadata.FileRecords;
import dev.caskeleton.application.fileserver.api.metadata.UploadSession;
import dev.caskeleton.application.fileserver.api.metadata.UploadSessionPort;
import dev.caskeleton.application.fileserver.api.metadata.WriterLease;
import dev.caskeleton.application.fileserver.api.security.FileAccessPolicyPort;
import dev.caskeleton.application.fileserver.api.security.FileOperation;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.concurrency.LeaseFence;
import dev.caskeleton.application.fileserver.concurrency.WriterLeaseCoordinator;
import dev.caskeleton.application.fileserver.observability.FileserverMetricsPort;
import dev.caskeleton.application.fileserver.observability.SizeBucket;
import dev.caskeleton.application.fileserver.port.in.AppendUploadCommand;
import dev.caskeleton.application.fileserver.port.in.AppendUploadUseCase;
import dev.caskeleton.application.fileserver.quota.TransferAdmissionController;
import dev.caskeleton.application.fileserver.quota.TransferPermit;
import dev.caskeleton.application.security.RequiresPermission;
import dev.caskeleton.application.transaction.TransactionMode;
import dev.caskeleton.application.transaction.TransactionPort;
import java.time.Clock;
import java.time.Duration;
import java.time.Instant;
import java.util.Objects;
import java.util.Optional;
/**
* Appends one chunk to an open upload under a writer lease.
*
* <p>Three separate boundaries, not one: the byte transfer between them must not run inside a
* transaction, so the lease, the offset commit, and the release each stand alone.
*/
@RequiresPermission("file:upload")
@UseCaseCapability(
transactionMode = TransactionMode.WRITE,
idempotency = Idempotency.NOT_IDEMPOTENT,
repositoryAccess = RepositoryAccess.WRITE_REPOSITORY,
externalOutboundAllowed = true)
// Not final: @RequiresPermission is applied through a CGLIB proxy
// (RequiresPermissionProxyabilityTest).
public class AppendUploadApplicationUseCase implements AppendUploadUseCase {
/** One bounded value, because the platform has exactly one storage provider. */
private static final String STORAGE_TYPE = "local";
private final FileMetadataPort metadataStore;
private final UploadSessionPort sessionStore;
private final WriterLeaseCoordinator leaseCoordinator;
private final UploadStoragePort storageGateway;
private final TransferAdmissionController admissionController;
private final FileAccessPolicyPort accessPolicy;
private final UploadPolicy uploadPolicy;
private final FileserverMetricsPort metrics;
private final TransactionPort transactions;
private final Clock clock;
public AppendUploadApplicationUseCase(
UploadStores stores,
UploadPolicies policies,
WriterLeaseCoordinator leaseCoordinator,
UploadStoragePort storageGateway,
TransferAdmissionController admissionController,
FileserverMetricsPort metrics,
TransactionPort transactions,
Clock clock) {
this.metadataStore = stores.metadata();
this.sessionStore = stores.sessions();
this.leaseCoordinator = Objects.requireNonNull(leaseCoordinator, "leaseCoordinator");
this.storageGateway = Objects.requireNonNull(storageGateway, "storageGateway");
this.admissionController = Objects.requireNonNull(admissionController, "admissionController");
this.accessPolicy = policies.access();
this.uploadPolicy = policies.upload();
this.metrics = Objects.requireNonNull(metrics, "metrics");
this.transactions = Objects.requireNonNull(transactions, "transactions");
this.clock = Objects.requireNonNull(clock, "clock");
}
@Override
public AppendUploadResult handle(AppendUploadCommand command) {
UploadId uploadId = command.uploadId();
long expectedOffset = command.expectedOffset();
RequestContext context = command.context();
UploadSession session = UploadSessions.requireActive(sessionStore, uploadId, clock.instant());
FileRecord record = FileRecords.require(metadataStore, session.fileId());
accessPolicy.authorize(
FileOperation.APPEND, context.subject(), Optional.of(record.toDescriptor()));
try (TransferPermit permit =
admissionController.acquireUpload(
UploadSessions.admissionScope(context), Math.max(command.contentLength(), 0))) {
WriterLease lease = leaseCoordinator.acquire(uploadId, context.instanceId());
// The fence is what carries the lease through the transfer. It renews on its own heartbeat
// and refuses the next write the moment renewal is denied, so a transfer that outlives its
// lease stops at a buffer boundary instead of discovering the takeover at commit time — by
// which point its bytes would already be interleaved with the new writer's.
LeaseFence fence = leaseCoordinator.fence(lease);
try {
UploadHandle handle =
storageGateway.reattachStaging(
uploadId,
record.namespace(),
UploadSessions.effectiveMaximum(uploadPolicy, record.expectedSize()));
requireOffsetsAgree(session, handle, expectedOffset);
Instant startedAt = clock.instant();
// The chunk checksum is checked by the store before it returns, so a mismatch never reaches
// the offset commit below.
AppendResult appended =
storageGateway.append(
handle,
expectedOffset,
command.content(),
command.contentLength(),
command.expectedChunkSha256(),
fence);
// The coordinator's own boundary joins this one; it is named here so the one write this
// operation commits after the transfer is visibly a write.
UploadSession committed =
transactions.inWrite(
() ->
leaseCoordinator.commitOffset(
fence.current(), expectedOffset, appended.committedOffset()));
// Recorded here rather than at the transport, because this is where the mode, the
// durable result and the byte count are all facts rather than inferences.
metrics.recordUpload(
session.mode(),
STORAGE_TYPE,
"committed",
SizeBucket.of(appended.appendedBytes()),
Duration.between(startedAt, clock.instant()),
appended.appendedBytes());
return new AppendUploadResult(
committed.committedOffset(), appended.appendedBytes(), appended.sha256());
} catch (UploadOffsetMismatchException mismatch) {
metrics.recordOffsetMismatch(session.mode(), "client");
throw mismatch;
} finally {
leaseCoordinator.release(fence.current());
}
}
}
/**
* Cross-checks the resumable offset against the bytes actually on disk.
*
* <p>A metadata offset that disagrees with the physical length means an earlier append is
* unaccounted for. Appending anyway would corrupt the object, so this is a hard conflict.
*/
private void requireOffsetsAgree(
UploadSession session, UploadHandle handle, long expectedOffset) {
long physicalLength = storageGateway.stagingLength(handle);
if (session.committedOffset() != physicalLength) {
throw UploadOffsetMismatchException.of(
session.uploadId(), session.committedOffset(), physicalLength);
}
if (expectedOffset != session.committedOffset()) {
throw UploadOffsetMismatchException.of(
session.uploadId(), expectedOffset, session.committedOffset());
}
}
}
@@ -0,0 +1,73 @@
package dev.caskeleton.application.fileserver.upload;
import dev.caskeleton.application.capability.Idempotency;
import dev.caskeleton.application.capability.RepositoryAccess;
import dev.caskeleton.application.capability.UseCaseCapability;
import dev.caskeleton.application.fileserver.api.metadata.FileMetadataPort;
import dev.caskeleton.application.fileserver.api.metadata.FileRecord;
import dev.caskeleton.application.fileserver.api.metadata.FileRecords;
import dev.caskeleton.application.fileserver.api.metadata.UploadSession;
import dev.caskeleton.application.fileserver.api.metadata.UploadSessionPort;
import dev.caskeleton.application.fileserver.api.security.FileAccessPolicyPort;
import dev.caskeleton.application.fileserver.api.security.FileOperation;
import dev.caskeleton.application.fileserver.cleanup.FileRetirement;
import dev.caskeleton.application.fileserver.port.in.CancelUploadCommand;
import dev.caskeleton.application.fileserver.port.in.CancelUploadUseCase;
import dev.caskeleton.application.security.RequiresPermission;
import dev.caskeleton.application.transaction.TransactionMode;
import dev.caskeleton.application.transaction.TransactionPort;
import java.util.Objects;
import java.util.Optional;
/**
* Cancels an upload: the record stops being reachable and its bytes are queued for removal.
*
* <p>{@code file:upload}, not {@code file:delete}: a caller that may start an upload may abandon
* its own, the same way {@code operation:submit} and {@code operation:cancel} go to one role.
*/
@RequiresPermission("file:upload")
@UseCaseCapability(
transactionMode = TransactionMode.WRITE,
idempotency = Idempotency.IDEMPOTENT,
repositoryAccess = RepositoryAccess.WRITE_REPOSITORY)
// Not final: @RequiresPermission is applied through a CGLIB proxy
// (RequiresPermissionProxyabilityTest).
public class CancelUploadApplicationUseCase implements CancelUploadUseCase {
private final FileMetadataPort metadataStore;
private final UploadSessionPort sessionStore;
private final FileAccessPolicyPort accessPolicy;
private final FileRetirement retirement;
private final TransactionPort transactions;
public CancelUploadApplicationUseCase(
UploadStores stores, FileAccessPolicyPort accessPolicy, TransactionPort transactions) {
this.metadataStore = stores.metadata();
this.sessionStore = stores.sessions();
this.accessPolicy = Objects.requireNonNull(accessPolicy, "accessPolicy");
this.retirement = new FileRetirement(stores.metadata(), stores.cleanupQueue());
this.transactions = Objects.requireNonNull(transactions, "transactions");
}
@Override
public Void handle(CancelUploadCommand command) {
UploadSession session = UploadSessions.require(sessionStore, command.uploadId());
FileRecord record = FileRecords.require(metadataStore, session.fileId());
accessPolicy.authorize(
FileOperation.DELETE, command.context().subject(), Optional.of(record.toDescriptor()));
transactions.inWrite(
() -> {
// Logical first: the record must stop being reachable before any physical work is
// scheduled. The staged bytes and, for an upload that was already published, the
// published object are queued in the same commit, so no cancel can leave a file
// unreachable with nothing queued to reclaim it.
retirement.retire(record, Optional.of(session.uploadId()));
// Terminal in the same transaction that queues the cleanup. Queuing alone left the
// session ACTIVE, so a writer could still take a lease on the very bytes the cleanup was
// about to delete and the two raced for the same object.
sessionStore.terminate(session.uploadId());
});
return null;
}
}
@@ -0,0 +1,204 @@
package dev.caskeleton.application.fileserver.upload;
import dev.caskeleton.application.capability.Idempotency;
import dev.caskeleton.application.capability.RepositoryAccess;
import dev.caskeleton.application.capability.UseCaseCapability;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.FileState;
import dev.caskeleton.application.fileserver.api.StorageNamespace;
import dev.caskeleton.application.fileserver.api.UploadId;
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
import dev.caskeleton.application.fileserver.api.error.FileserverException;
import dev.caskeleton.application.fileserver.api.error.FileserverFailureContext;
import dev.caskeleton.application.fileserver.api.metadata.FileMetadataPort;
import dev.caskeleton.application.fileserver.api.metadata.FileQuotaPort;
import dev.caskeleton.application.fileserver.api.metadata.FileRecord;
import dev.caskeleton.application.fileserver.api.metadata.FileRecordDraft;
import dev.caskeleton.application.fileserver.api.metadata.FileRecordMutation;
import dev.caskeleton.application.fileserver.api.metadata.QuotaReservation;
import dev.caskeleton.application.fileserver.api.metadata.QuotaScope;
import dev.caskeleton.application.fileserver.api.metadata.UploadSession;
import dev.caskeleton.application.fileserver.api.metadata.UploadSessionDraft;
import dev.caskeleton.application.fileserver.api.metadata.UploadSessionPort;
import dev.caskeleton.application.fileserver.api.security.FileAccessPolicyPort;
import dev.caskeleton.application.fileserver.api.security.FileOperation;
import dev.caskeleton.application.fileserver.api.security.OriginalFilenamePolicy;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.api.security.SanitizedFilename;
import dev.caskeleton.application.fileserver.port.in.CreateUploadCommand;
import dev.caskeleton.application.fileserver.port.in.CreateUploadUseCase;
import dev.caskeleton.application.fileserver.quota.TransferAdmissionController;
import dev.caskeleton.application.fileserver.quota.TransferPermit;
import dev.caskeleton.application.security.RequiresPermission;
import dev.caskeleton.application.transaction.TransactionMode;
import dev.caskeleton.application.transaction.TransactionPort;
import java.time.Clock;
import java.time.Instant;
import java.util.Objects;
import java.util.Optional;
import java.util.OptionalLong;
/**
* Opens an upload: quota, file record and session in one boundary, then staging.
*
* <p>Two authorities, both required. {@code file:upload} is the role check, enforced on the proxy
* before this runs; {@link FileAccessPolicyPort} is the tier and owner/tenant check, run first
* inside so a denial has no side effect.
*/
@RequiresPermission("file:upload")
@UseCaseCapability(
transactionMode = TransactionMode.WRITE,
idempotency = Idempotency.NOT_IDEMPOTENT,
repositoryAccess = RepositoryAccess.WRITE_REPOSITORY,
externalOutboundAllowed = true)
// Not final: @RequiresPermission is applied through a CGLIB proxy
// (RequiresPermissionProxyabilityTest).
public class CreateUploadApplicationUseCase implements CreateUploadUseCase {
private final FileMetadataPort metadataStore;
private final UploadSessionPort sessionStore;
private final UploadStoragePort storageGateway;
private final FileQuotaPort quotaService;
private final TransferAdmissionController admissionController;
private final FileAccessPolicyPort accessPolicy;
private final OriginalFilenamePolicy filenamePolicy;
private final UploadIdentifierPort identifierFactory;
private final UploadPolicy uploadPolicy;
private final TransactionPort transactions;
private final Clock clock;
public CreateUploadApplicationUseCase(
UploadStores stores,
UploadPolicies policies,
UploadStoragePort storageGateway,
FileQuotaPort quotaService,
TransferAdmissionController admissionController,
UploadIdentifierPort identifierFactory,
TransactionPort transactions,
Clock clock) {
this.metadataStore = stores.metadata();
this.sessionStore = stores.sessions();
this.storageGateway = Objects.requireNonNull(storageGateway, "storageGateway");
this.quotaService = Objects.requireNonNull(quotaService, "quotaService");
this.admissionController = Objects.requireNonNull(admissionController, "admissionController");
this.accessPolicy = policies.access();
this.filenamePolicy = policies.filenames();
this.identifierFactory = Objects.requireNonNull(identifierFactory, "identifierFactory");
this.uploadPolicy = policies.upload();
this.transactions = Objects.requireNonNull(transactions, "transactions");
this.clock = Objects.requireNonNull(clock, "clock");
}
@Override
public UploadSessionView handle(CreateUploadCommand command) {
CreateUploadRequest request = command.request();
RequestContext context = command.context();
accessPolicy.authorize(FileOperation.CREATE, context.subject(), Optional.empty());
requireLengthWithinPolicy(request.expectedLength());
SanitizedFilename displayName = filenamePolicy.sanitize(request.originalFilename());
StorageNamespace namespace = uploadPolicy.defaultNamespace();
Instant expiresAt = uploadPolicy.sessionExpiresAt(clock.instant());
QuotaScope scope = QuotaScope.ofNamespace(namespace.value());
long reservationBytes = request.expectedLength().orElse(uploadPolicy.initialReservationBytes());
try (TransferPermit permit =
admissionController.acquireUpload(
UploadSessions.admissionScope(context), reservationBytes)) {
FileId fileId = identifierFactory.newFileId();
UploadId uploadId = identifierFactory.newUploadId();
// One unit: a reservation that outlived a failed insert would hold capacity for a file that
// never existed, and a session without its record is unresolvable by any later step.
CreatedUpload created =
transactions.inWrite(
() -> {
QuotaReservation reservation =
quotaService.reserve(scope, reservationBytes, uploadPolicy.reservationTtl());
FileRecord record =
metadataStore.insert(
new FileRecordDraft(
fileId,
namespace,
displayName.value(),
request.claimedMediaType(),
request.expectedLength(),
context.subject().asOwner()));
UploadSession session =
sessionStore.create(
new UploadSessionDraft(
uploadId, fileId, request.mode(), request.expectedLength(), expiresAt));
return new CreatedUpload(reservation, record, session);
});
try {
storageGateway.createStaging(
uploadId,
namespace,
UploadSessions.effectiveMaximum(uploadPolicy, request.expectedLength()));
} catch (RuntimeException exception) {
// Staging sits outside the boundary above because it has to — it is a filesystem call — so
// it is the one failure here that still compensates by hand instead of rolling back.
try {
transactions.inNew(
() -> {
failRecord(created.record(), "UPLOAD_CREATE_FAILED");
quotaService.release(created.reservation());
});
} catch (RuntimeException compensationFailure) {
exception.addSuppressed(compensationFailure);
}
throw exception;
}
transactions.inWrite(
() -> {
metadataStore.transition(
created.record().fileId(),
created.record().version(),
FileState.CREATED,
FileState.UPLOADING,
FileRecordMutation.none());
});
return UploadSessions.toView(created.session());
}
}
/** The three records one create produces, so a single boundary can return them together. */
private record CreatedUpload(
QuotaReservation reservation, FileRecord record, UploadSession session) {}
private void requireLengthWithinPolicy(OptionalLong expectedLength) {
if (expectedLength.isPresent() && expectedLength.getAsLong() > uploadPolicy.maximumFileSize()) {
throw new FileserverException(
"declared upload length exceeds the configured maximum file size",
FileserverFailureContext.of(FileserverErrorCode.FILE_TOO_LARGE, false));
}
}
/**
* Moves a record to FAILED using only edges the state machine allows.
*
* <p>The design requires a failed create to end in FAILED, but the transition table has no direct
* {@code CREATED -> FAILED} edge. The record therefore takes the one path the table permits,
* through UPLOADING, which is also honest: the upload had been admitted before it failed.
*/
private void failRecord(FileRecord record, String reasonCode) {
FileRecord current = record;
if (current.state() == FileState.CREATED) {
current =
metadataStore.transition(
current.fileId(),
current.version(),
FileState.CREATED,
FileState.UPLOADING,
FileRecordMutation.none());
}
metadataStore.transition(
current.fileId(),
current.version(),
current.state(),
FileState.FAILED,
FileRecordMutation.failure(reasonCode));
}
}
@@ -1,60 +0,0 @@
package dev.caskeleton.application.fileserver.upload;
import dev.caskeleton.application.fileserver.api.UploadId;
import dev.caskeleton.application.fileserver.api.error.AmbiguousCompletionException;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import java.nio.channels.ReadableByteChannel;
/**
* Composes create, append, and finalize into the one-request upload.
*
* <p>The cancel-on-failure rule is the substance here. A transfer that fails outright leaves an
* orphan staging object and a reserved quota slice, so it is cancelled; an <em>ambiguous</em>
* completion is deliberately left alone, because its content may already be published and only
* reconciliation may decide its fate.
*/
public final class DefaultSingleShotUploadService implements SingleShotUploadService {
private final UploadApplicationService uploadService;
private final FinalizeUploadService finalizeService;
public DefaultSingleShotUploadService(
UploadApplicationService uploadService, FinalizeUploadService finalizeService) {
this.uploadService = uploadService;
this.finalizeService = finalizeService;
}
@Override
public FileView upload(
CreateUploadRequest request,
ReadableByteChannel content,
long contentLength,
FinalizeUploadRequest finalizeRequest,
RequestContext context) {
UploadSessionView created = uploadService.create(request, context);
try {
uploadService.append(created.uploadId(), 0, content, contentLength, context);
return finalizeService.finalizeUpload(created.uploadId(), finalizeRequest, context);
} catch (RuntimeException failure) {
if (!(failure instanceof AmbiguousCompletionException)) {
cancelQuietly(created.uploadId(), context, failure);
}
throw failure;
}
}
/**
* Best-effort cancel of the upload resource.
*
* <p>A cancel that itself fails must not replace the original failure: the caller would then be
* told about a cleanup problem instead of the reason their upload did not work. It is attached as
* a suppressed cause so nothing is silently lost either.
*/
private void cancelQuietly(UploadId uploadId, RequestContext context, RuntimeException failure) {
try {
uploadService.cancel(uploadId, context);
} catch (RuntimeException cleanupFailure) {
failure.addSuppressed(cleanupFailure);
}
}
}
@@ -1,387 +0,0 @@
package dev.caskeleton.application.fileserver.upload;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.FileState;
import dev.caskeleton.application.fileserver.api.StorageNamespace;
import dev.caskeleton.application.fileserver.api.UploadId;
import dev.caskeleton.application.fileserver.api.content.AppendResult;
import dev.caskeleton.application.fileserver.api.content.UploadHandle;
import dev.caskeleton.application.fileserver.api.error.FileNotFoundException;
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
import dev.caskeleton.application.fileserver.api.error.FileserverException;
import dev.caskeleton.application.fileserver.api.error.FileserverFailureContext;
import dev.caskeleton.application.fileserver.api.error.UploadOffsetMismatchException;
import dev.caskeleton.application.fileserver.api.metadata.FileMetadataPort;
import dev.caskeleton.application.fileserver.api.metadata.FileQuotaPort;
import dev.caskeleton.application.fileserver.api.metadata.FileRecord;
import dev.caskeleton.application.fileserver.api.metadata.FileRecordDraft;
import dev.caskeleton.application.fileserver.api.metadata.FileRecordMutation;
import dev.caskeleton.application.fileserver.api.metadata.QuotaReservation;
import dev.caskeleton.application.fileserver.api.metadata.QuotaScope;
import dev.caskeleton.application.fileserver.api.metadata.UploadSession;
import dev.caskeleton.application.fileserver.api.metadata.UploadSessionDraft;
import dev.caskeleton.application.fileserver.api.metadata.UploadSessionPort;
import dev.caskeleton.application.fileserver.api.metadata.WriterLease;
import dev.caskeleton.application.fileserver.api.security.FileAccessPolicyPort;
import dev.caskeleton.application.fileserver.api.security.FileOperation;
import dev.caskeleton.application.fileserver.api.security.OriginalFilenamePolicy;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.api.security.SanitizedFilename;
import dev.caskeleton.application.fileserver.cleanup.FileRetirement;
import dev.caskeleton.application.fileserver.concurrency.LeaseFence;
import dev.caskeleton.application.fileserver.concurrency.WriterLeaseCoordinator;
import dev.caskeleton.application.fileserver.observability.FileserverMetricsPort;
import dev.caskeleton.application.fileserver.observability.SizeBucket;
import dev.caskeleton.application.fileserver.quota.TransferAdmissionController;
import dev.caskeleton.application.fileserver.quota.TransferPermit;
import dev.caskeleton.application.transaction.TransactionPort;
import java.nio.channels.ReadableByteChannel;
import java.time.Clock;
import java.time.Duration;
import java.time.Instant;
import java.util.Optional;
import java.util.OptionalLong;
/**
* Orchestrates create, append, status, and cancel.
*
* <p>Two ordering rules carry most of the safety here. Authorization runs before admission, quota,
* and any storage call, so a denial has no side effect. On append, the metadata offset and the
* physical staging length must agree before a byte is written; when they disagree the upload goes
* to reconciliation rather than being silently repaired.
*
* <p>This service owns its transaction boundaries. They are deliberately narrow: 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. What that costs is atomicity across the storage/metadata seam, which no database
* boundary could have provided anyway — that seam is what the reconciler exists for.
*/
public final class DefaultUploadApplicationService implements UploadApplicationService {
private final FileMetadataPort metadataStore;
private final UploadSessionPort sessionStore;
private final WriterLeaseCoordinator leaseCoordinator;
private final UploadStoragePort storageGateway;
private final FileQuotaPort quotaService;
private final TransferAdmissionController admissionController;
private final FileAccessPolicyPort accessPolicy;
private final OriginalFilenamePolicy filenamePolicy;
private final FileRetirement retirement;
private final UploadIdentifierPort identifierFactory;
private final UploadPolicy uploadPolicy;
private final FileserverMetricsPort metrics;
private final TransactionPort transactions;
private final Clock clock;
public DefaultUploadApplicationService(
UploadStores stores,
UploadPolicies policies,
WriterLeaseCoordinator leaseCoordinator,
UploadStoragePort storageGateway,
FileQuotaPort quotaService,
TransferAdmissionController admissionController,
UploadIdentifierPort identifierFactory,
FileserverMetricsPort metrics,
TransactionPort transactions,
Clock clock) {
this.transactions = transactions;
this.metadataStore = stores.metadata();
this.sessionStore = stores.sessions();
this.leaseCoordinator = leaseCoordinator;
this.storageGateway = storageGateway;
this.quotaService = quotaService;
this.admissionController = admissionController;
this.accessPolicy = policies.access();
this.filenamePolicy = policies.filenames();
this.retirement = new FileRetirement(stores.metadata(), stores.cleanupQueue());
this.identifierFactory = identifierFactory;
this.uploadPolicy = policies.upload();
this.metrics = metrics;
this.clock = clock;
}
@Override
public UploadSessionView create(CreateUploadRequest request, RequestContext context) {
accessPolicy.authorize(FileOperation.CREATE, context.subject(), Optional.empty());
requireLengthWithinPolicy(request.expectedLength());
SanitizedFilename displayName = filenamePolicy.sanitize(request.originalFilename());
StorageNamespace namespace = uploadPolicy.defaultNamespace();
Instant expiresAt = uploadPolicy.sessionExpiresAt(clock.instant());
QuotaScope scope = QuotaScope.ofNamespace(namespace.value());
long reservationBytes = request.expectedLength().orElse(uploadPolicy.initialReservationBytes());
try (TransferPermit permit =
admissionController.acquireUpload(admissionScope(context), reservationBytes)) {
FileId fileId = identifierFactory.newFileId();
UploadId uploadId = identifierFactory.newUploadId();
// One unit: a reservation that outlived a failed insert would hold capacity for a file that
// never existed, and a session without its record is unresolvable by any later step.
CreatedUpload created =
transactions.inWrite(
() -> {
QuotaReservation reservation =
quotaService.reserve(scope, reservationBytes, uploadPolicy.reservationTtl());
FileRecord record =
metadataStore.insert(
new FileRecordDraft(
fileId,
namespace,
displayName.value(),
request.claimedMediaType(),
request.expectedLength(),
context.subject().asOwner()));
UploadSession session =
sessionStore.create(
new UploadSessionDraft(
uploadId, fileId, request.mode(), request.expectedLength(), expiresAt));
return new CreatedUpload(reservation, record, session);
});
try {
storageGateway.createStaging(
uploadId, namespace, effectiveMaximum(request.expectedLength()));
} catch (RuntimeException exception) {
// Staging sits outside the boundary above because it has to — it is a filesystem call — so
// it is the one failure here that still compensates by hand instead of rolling back.
try {
transactions.inNew(
() -> {
failRecord(created.record(), "UPLOAD_CREATE_FAILED");
quotaService.release(created.reservation());
});
} catch (RuntimeException compensationFailure) {
exception.addSuppressed(compensationFailure);
}
throw exception;
}
transactions.inWrite(
() -> {
metadataStore.transition(
created.record().fileId(),
created.record().version(),
FileState.CREATED,
FileState.UPLOADING,
FileRecordMutation.none());
});
return toView(created.session());
}
}
/** The three records one create produces, so a single boundary can return them together. */
private record CreatedUpload(
QuotaReservation reservation, FileRecord record, UploadSession session) {}
@Override
public AppendUploadResult append(
UploadId uploadId,
long expectedOffset,
ReadableByteChannel content,
long contentLength,
Optional<String> expectedChunkSha256,
RequestContext context) {
UploadSession session = requireActiveSession(uploadId);
FileRecord record = requireRecord(session.fileId());
accessPolicy.authorize(
FileOperation.APPEND, context.subject(), Optional.of(record.toDescriptor()));
try (TransferPermit permit =
admissionController.acquireUpload(admissionScope(context), Math.max(contentLength, 0))) {
// Three separate boundaries, not one: the byte transfer between them must not run inside a
// transaction, so the lease, the offset commit, and the release each stand alone.
WriterLease lease = leaseCoordinator.acquire(uploadId, context.instanceId());
// The fence is what carries the lease through the transfer. It renews on its own heartbeat
// and refuses the next write the moment renewal is denied, so a transfer that outlives its
// lease stops at a buffer boundary instead of discovering the takeover at commit time — by
// which point its bytes would already be interleaved with the new writer's.
LeaseFence fence = leaseCoordinator.fence(lease);
try {
UploadHandle handle =
storageGateway.reattachStaging(
uploadId, record.namespace(), effectiveMaximum(record.expectedSize()));
requireOffsetsAgree(session, handle, expectedOffset);
Instant startedAt = clock.instant();
// The chunk checksum is checked by the store before it returns, so a mismatch never reaches
// the offset commit below.
AppendResult appended =
storageGateway.append(
handle, expectedOffset, content, contentLength, expectedChunkSha256, fence);
UploadSession committed =
leaseCoordinator.commitOffset(
fence.current(), expectedOffset, appended.committedOffset());
// Recorded here rather than at the transport, because this is where the mode, the
// durable result and the byte count are all facts rather than inferences.
metrics.recordUpload(
session.mode(),
STORAGE_TYPE,
"committed",
SizeBucket.of(appended.appendedBytes()),
Duration.between(startedAt, clock.instant()),
appended.appendedBytes());
return new AppendUploadResult(
committed.committedOffset(), appended.appendedBytes(), appended.sha256());
} catch (UploadOffsetMismatchException mismatch) {
metrics.recordOffsetMismatch(session.mode(), "client");
throw mismatch;
} finally {
leaseCoordinator.release(fence.current());
}
}
}
@Override
public UploadSessionView status(UploadId uploadId, RequestContext context) {
// An ended upload answers gone, not with an offset a client would try to resume from.
UploadSession session = requireActiveSession(uploadId);
FileRecord record = requireRecord(session.fileId());
accessPolicy.authorize(
FileOperation.READ_METADATA, context.subject(), Optional.of(record.toDescriptor()));
return toView(session);
}
@Override
public void cancel(UploadId uploadId, RequestContext context) {
UploadSession session = requireSession(uploadId);
FileRecord record = requireRecord(session.fileId());
accessPolicy.authorize(
FileOperation.DELETE, context.subject(), Optional.of(record.toDescriptor()));
transactions.inWrite(
() -> {
// Logical first: the record must stop being reachable before any physical work is
// scheduled. The staged bytes and, for an upload that was already published, the
// published object are queued in the same commit, so no cancel can leave a file
// unreachable with nothing queued to reclaim it.
retirement.retire(record, Optional.of(session.uploadId()));
// Terminal in the same transaction that queues the cleanup. Queuing alone left the
// session ACTIVE, so a writer could still take a lease on the very bytes the cleanup was
// about to delete and the two raced for the same object.
sessionStore.terminate(session.uploadId());
});
}
/**
* Transfer concurrency is counted per caller.
*
* <p>Counting it per namespace put every caller of a deployment — which uploads into one default
* namespace — behind the same handful of permits, so one busy client refused everyone else.
*/
private static QuotaScope admissionScope(RequestContext context) {
return QuotaScope.ofPrincipal(context.subject().principalId());
}
/**
* Cross-checks the resumable offset against the bytes actually on disk.
*
* <p>A metadata offset that disagrees with the physical length means an earlier append is
* unaccounted for. Appending anyway would corrupt the object, so this is a hard conflict.
*/
/** One bounded value, because the platform has exactly one storage provider. */
private static final String STORAGE_TYPE = "local";
private void requireOffsetsAgree(
UploadSession session, UploadHandle handle, long expectedOffset) {
long physicalLength = storageGateway.stagingLength(handle);
if (session.committedOffset() != physicalLength) {
throw UploadOffsetMismatchException.of(
session.uploadId(), session.committedOffset(), physicalLength);
}
if (expectedOffset != session.committedOffset()) {
throw UploadOffsetMismatchException.of(
session.uploadId(), expectedOffset, session.committedOffset());
}
}
private void requireLengthWithinPolicy(OptionalLong expectedLength) {
if (expectedLength.isPresent() && expectedLength.getAsLong() > uploadPolicy.maximumFileSize()) {
throw new FileserverException(
"declared upload length exceeds the configured maximum file size",
FileserverFailureContext.of(FileserverErrorCode.FILE_TOO_LARGE, false));
}
}
private long effectiveMaximum(OptionalLong expectedLength) {
return expectedLength.isPresent()
? Math.min(uploadPolicy.maximumFileSize(), Math.max(expectedLength.getAsLong(), 1))
: uploadPolicy.maximumFileSize();
}
private UploadSession requireSession(UploadId uploadId) {
return sessionStore
.find(uploadId)
.orElseThrow(
() ->
new FileNotFoundException(
"upload resource does not exist",
FileserverFailureContext.forUpload(
FileserverErrorCode.FILE_NOT_FOUND, uploadId, false, false, false)));
}
private UploadSession requireActiveSession(UploadId uploadId) {
UploadSession session = requireSession(uploadId);
if (session.terminal()) {
// Cancelled, rejected or swept. Refusing it as a lease conflict told the client to retry an
// upload that can never accept another byte.
throw new FileserverException(
"upload resource is no longer open",
FileserverFailureContext.forUpload(
FileserverErrorCode.UPLOAD_EXPIRED, uploadId, false, false, false));
}
if (session.isExpiredAt(clock.instant())) {
throw new FileserverException(
"upload resource has expired",
FileserverFailureContext.forUpload(
FileserverErrorCode.UPLOAD_EXPIRED, uploadId, false, false, false));
}
return session;
}
private FileRecord requireRecord(FileId fileId) {
return metadataStore
.find(fileId)
.orElseThrow(
() ->
new FileNotFoundException(
"file record does not exist",
FileserverFailureContext.forFile(
FileserverErrorCode.FILE_NOT_FOUND, fileId, false)));
}
/**
* Moves a record to FAILED using only edges the state machine allows.
*
* <p>The design requires a failed create to end in FAILED, but the transition table has no direct
* {@code CREATED -> FAILED} edge. The record therefore takes the one path the table permits,
* through UPLOADING, which is also honest: the upload had been admitted before it failed.
*/
private void failRecord(FileRecord record, String reasonCode) {
FileRecord current = record;
if (current.state() == FileState.CREATED) {
current =
metadataStore.transition(
current.fileId(),
current.version(),
FileState.CREATED,
FileState.UPLOADING,
FileRecordMutation.none());
}
metadataStore.transition(
current.fileId(),
current.version(),
current.state(),
FileState.FAILED,
FileRecordMutation.failure(reasonCode));
}
private static UploadSessionView toView(UploadSession session) {
return new UploadSessionView(
session.uploadId(),
session.fileId(),
session.committedOffset(),
session.expectedLength(),
session.expiresAt());
}
}
@@ -1,5 +1,8 @@
package dev.caskeleton.application.fileserver.upload;
import dev.caskeleton.application.capability.Idempotency;
import dev.caskeleton.application.capability.RepositoryAccess;
import dev.caskeleton.application.capability.UseCaseCapability;
import dev.caskeleton.application.fileserver.api.ContentKey;
import dev.caskeleton.application.fileserver.api.FileState;
import dev.caskeleton.application.fileserver.api.UploadId;
@@ -27,7 +30,11 @@ import dev.caskeleton.application.fileserver.api.security.VerificationVerdict;
import dev.caskeleton.application.fileserver.cleanup.CleanupQueuePort;
import dev.caskeleton.application.fileserver.cleanup.CleanupRequest;
import dev.caskeleton.application.fileserver.cleanup.CleanupType;
import dev.caskeleton.application.fileserver.port.in.FinalizeUploadCommand;
import dev.caskeleton.application.fileserver.port.in.FinalizeUploadUseCase;
import dev.caskeleton.application.fileserver.recovery.RecoveryQueuePort;
import dev.caskeleton.application.security.RequiresPermission;
import dev.caskeleton.application.transaction.TransactionMode;
import dev.caskeleton.application.transaction.TransactionPort;
import java.time.Clock;
import java.time.Instant;
@@ -44,7 +51,15 @@ import java.util.OptionalLong;
* the physical publish, the caller gets an ambiguous completion and the file goes to the recovery
* queue — never a READY answer the store cannot back.
*/
public final class DefaultFinalizeUploadService implements FinalizeUploadService {
@RequiresPermission("file:upload")
@UseCaseCapability(
transactionMode = TransactionMode.WRITE,
idempotency = Idempotency.IDEMPOTENT,
repositoryAccess = RepositoryAccess.WRITE_REPOSITORY,
externalOutboundAllowed = true)
// Not final: @RequiresPermission is applied through a CGLIB proxy
// (RequiresPermissionProxyabilityTest).
public class FinalizeUploadApplicationUseCase implements FinalizeUploadUseCase {
private final FileMetadataPort metadataStore;
private final UploadSessionPort sessionStore;
@@ -58,7 +73,7 @@ public final class DefaultFinalizeUploadService implements FinalizeUploadService
private final TransactionPort transactions;
private final Clock clock;
public DefaultFinalizeUploadService(
public FinalizeUploadApplicationUseCase(
FileMetadataPort metadataStore,
UploadSessionPort sessionStore,
UploadContentPort contentGateway,
@@ -84,8 +99,8 @@ public final class DefaultFinalizeUploadService implements FinalizeUploadService
}
@Override
public FileView finalizeUpload(
UploadId uploadId, FinalizeUploadRequest request, RequestContext context) {
public FileView handle(FinalizeUploadCommand command) {
UploadId uploadId = command.uploadId();
UploadSession session =
sessionStore
.find(uploadId)
@@ -95,11 +110,10 @@ public final class DefaultFinalizeUploadService implements FinalizeUploadService
"upload resource does not exist",
FileserverFailureContext.forUpload(
FileserverErrorCode.FILE_NOT_FOUND, uploadId, false, false, false)));
return finalizeUpload(session, request, context);
return finalizeSession(session, command.request(), command.context());
}
@Override
public FileView finalizeUpload(
private FileView finalizeSession(
UploadSession session, FinalizeUploadRequest request, RequestContext context) {
FileRecord record = requireRecord(session);
// Before any digest, verification or publish: a denial must have no side effect.
@@ -1,25 +0,0 @@
package dev.caskeleton.application.fileserver.upload;
import dev.caskeleton.application.fileserver.api.UploadId;
import dev.caskeleton.application.fileserver.api.metadata.UploadSession;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
/**
* Completes an upload and decides whether it may become publicly readable.
*
* <p>READY is only ever reached after the physical object is published and re-verified, so a READY
* record always has readable content whose size and digest match.
*/
public interface FinalizeUploadService {
FileView finalizeUpload(
UploadSession session, FinalizeUploadRequest request, RequestContext context);
/**
* Transport-facing entry point that resolves the session itself.
*
* <p>A transport adapter only ever holds the opaque {@link UploadId}; letting it fetch an {@code
* UploadSession} would put a metadata port type in a controller signature.
*/
FileView finalizeUpload(UploadId uploadId, FinalizeUploadRequest request, RequestContext context);
}
@@ -0,0 +1,72 @@
package dev.caskeleton.application.fileserver.upload;
import dev.caskeleton.application.capability.Idempotency;
import dev.caskeleton.application.capability.RepositoryAccess;
import dev.caskeleton.application.capability.UseCaseCapability;
import dev.caskeleton.application.fileserver.api.metadata.FileMetadataPort;
import dev.caskeleton.application.fileserver.api.metadata.FileRecord;
import dev.caskeleton.application.fileserver.api.metadata.FileRecords;
import dev.caskeleton.application.fileserver.api.metadata.UploadSession;
import dev.caskeleton.application.fileserver.api.metadata.UploadSessionPort;
import dev.caskeleton.application.fileserver.api.security.FileAccessPolicyPort;
import dev.caskeleton.application.fileserver.api.security.FileOperation;
import dev.caskeleton.application.fileserver.port.in.GetUploadStatusQuery;
import dev.caskeleton.application.fileserver.port.in.GetUploadStatusUseCase;
import dev.caskeleton.application.security.RequiresPermission;
import dev.caskeleton.application.transaction.TransactionMode;
import dev.caskeleton.application.transaction.TransactionPort;
import java.time.Clock;
import java.util.Objects;
import java.util.Optional;
/**
* Reports where an open upload stands.
*
* <p>{@code file:read}, matching the metadata-read tier {@link FileAccessPolicyPort} checks inside
* along with ownership: resuming an upload means asking where one's own upload stands.
*/
@RequiresPermission("file:read")
@UseCaseCapability(
transactionMode = TransactionMode.READ_ONLY,
idempotency = Idempotency.IDEMPOTENT,
repositoryAccess = RepositoryAccess.READ_REPOSITORY)
// Not final: @RequiresPermission is applied through a CGLIB proxy
// (RequiresPermissionProxyabilityTest).
public class GetUploadStatusApplicationUseCase implements GetUploadStatusUseCase {
private final FileMetadataPort metadataStore;
private final UploadSessionPort sessionStore;
private final FileAccessPolicyPort accessPolicy;
private final TransactionPort transactions;
private final Clock clock;
public GetUploadStatusApplicationUseCase(
UploadStores stores,
FileAccessPolicyPort accessPolicy,
TransactionPort transactions,
Clock clock) {
this.metadataStore = stores.metadata();
this.sessionStore = stores.sessions();
this.accessPolicy = Objects.requireNonNull(accessPolicy, "accessPolicy");
this.transactions = Objects.requireNonNull(transactions, "transactions");
this.clock = Objects.requireNonNull(clock, "clock");
}
@Override
public UploadSessionView handle(GetUploadStatusQuery query) {
// The session and its record read together, so the owner the policy judges is the owner of the
// session being reported.
return transactions.inRead(
() -> {
// An ended upload answers gone, not with an offset a client would try to resume from.
UploadSession session =
UploadSessions.requireActive(sessionStore, query.uploadId(), clock.instant());
FileRecord record = FileRecords.require(metadataStore, session.fileId());
accessPolicy.authorize(
FileOperation.READ_METADATA,
query.context().subject(),
Optional.of(record.toDescriptor()));
return UploadSessions.toView(session);
});
}
}
@@ -1,27 +0,0 @@
package dev.caskeleton.application.fileserver.upload;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import java.nio.channels.ReadableByteChannel;
/**
* One-request upload: create, stream, finalize.
*
* <p>The sequence belongs here rather than in a transport because it decides lifecycle: which
* failures cancel the upload resource, and which leave it for reconciliation. A controller that
* assembled the same three calls itself would be making that decision per transport.
*/
public interface SingleShotUploadService {
/**
* Streams {@code content} into a new file and finalizes it.
*
* @param contentLength declared length, or a negative value when the request is chunked and the
* length is only known at end of stream
*/
FileView upload(
CreateUploadRequest request,
ReadableByteChannel content,
long contentLength,
FinalizeUploadRequest finalizeRequest,
RequestContext context);
}
@@ -1,46 +0,0 @@
package dev.caskeleton.application.fileserver.upload;
import dev.caskeleton.application.fileserver.api.UploadId;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import java.nio.channels.ReadableByteChannel;
import java.util.Optional;
/**
* The upload half of the public application surface.
*
* <p>Every method authorizes first, before any quota reservation or storage mutation, so a denied
* request leaves no record, no reservation, and no staging object behind.
*/
public interface UploadApplicationService {
UploadSessionView create(CreateUploadRequest request, RequestContext context);
/**
* Appends one request's bytes.
*
* @param expectedChunkSha256 hex SHA-256 the client asserted for this request's bytes only, never
* the whole upload; a mismatch is rejected before the offset commits and leaves no bytes
* behind
*/
AppendUploadResult append(
UploadId uploadId,
long expectedOffset,
ReadableByteChannel content,
long contentLength,
Optional<String> expectedChunkSha256,
RequestContext context);
/** Appends without a client checksum. */
default AppendUploadResult append(
UploadId uploadId,
long expectedOffset,
ReadableByteChannel content,
long contentLength,
RequestContext context) {
return append(uploadId, expectedOffset, content, contentLength, Optional.empty(), context);
}
UploadSessionView status(UploadId uploadId, RequestContext context);
void cancel(UploadId uploadId, RequestContext context);
}
@@ -0,0 +1,99 @@
package dev.caskeleton.application.fileserver.upload;
import dev.caskeleton.application.capability.Idempotency;
import dev.caskeleton.application.capability.RepositoryAccess;
import dev.caskeleton.application.capability.UseCaseCapability;
import dev.caskeleton.application.fileserver.api.UploadId;
import dev.caskeleton.application.fileserver.api.error.AmbiguousCompletionException;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.port.in.AppendUploadCommand;
import dev.caskeleton.application.fileserver.port.in.AppendUploadUseCase;
import dev.caskeleton.application.fileserver.port.in.CancelUploadCommand;
import dev.caskeleton.application.fileserver.port.in.CancelUploadUseCase;
import dev.caskeleton.application.fileserver.port.in.CreateUploadCommand;
import dev.caskeleton.application.fileserver.port.in.CreateUploadUseCase;
import dev.caskeleton.application.fileserver.port.in.FinalizeUploadCommand;
import dev.caskeleton.application.fileserver.port.in.FinalizeUploadUseCase;
import dev.caskeleton.application.fileserver.port.in.UploadFileCommand;
import dev.caskeleton.application.fileserver.port.in.UploadFileUseCase;
import dev.caskeleton.application.security.RequiresPermission;
import dev.caskeleton.application.transaction.TransactionMode;
import java.util.Objects;
import java.util.Optional;
/**
* Composes create, append, and finalize into the one-request upload.
*
* <p>The cancel-on-failure rule is the substance here. A transfer that fails outright leaves an
* orphan staging object and a reserved quota slice, so it is cancelled; an <em>ambiguous</em>
* completion is deliberately left alone, because its content may already be published and only
* reconciliation may decide its fate.
*
* <p>{@code RepositoryAccess.NONE}: this use case touches no store itself. Each step it composes is
* a use case that declares, and opens, its own boundaries — one transaction around the three would
* hold a connection for the length of the byte transfer. The permission is still declared: the
* composed steps check it again, but the operation a caller asks for is this one.
*/
@RequiresPermission("file:upload")
@UseCaseCapability(
transactionMode = TransactionMode.WRITE,
idempotency = Idempotency.NOT_IDEMPOTENT,
repositoryAccess = RepositoryAccess.NONE)
// Not final: @RequiresPermission is applied through a CGLIB proxy
// (RequiresPermissionProxyabilityTest).
public class UploadFileApplicationUseCase implements UploadFileUseCase {
private final CreateUploadUseCase create;
private final AppendUploadUseCase append;
private final FinalizeUploadUseCase finalizer;
private final CancelUploadUseCase cancel;
public UploadFileApplicationUseCase(
CreateUploadUseCase create,
AppendUploadUseCase append,
FinalizeUploadUseCase finalizer,
CancelUploadUseCase cancel) {
this.create = Objects.requireNonNull(create, "create");
this.append = Objects.requireNonNull(append, "append");
this.finalizer = Objects.requireNonNull(finalizer, "finalizer");
this.cancel = Objects.requireNonNull(cancel, "cancel");
}
@Override
public FileView handle(UploadFileCommand command) {
RequestContext context = command.context();
UploadSessionView created = create.handle(new CreateUploadCommand(command.request(), context));
try {
append.handle(
new AppendUploadCommand(
created.uploadId(),
0,
command.content(),
command.contentLength(),
Optional.empty(),
context));
return finalizer.handle(
new FinalizeUploadCommand(created.uploadId(), command.finalizeRequest(), context));
} catch (RuntimeException failure) {
if (!(failure instanceof AmbiguousCompletionException)) {
cancelQuietly(created.uploadId(), context, failure);
}
throw failure;
}
}
/**
* Best-effort cancel of the upload resource.
*
* <p>A cancel that itself fails must not replace the original failure: the caller would then be
* told about a cleanup problem instead of the reason their upload did not work. It is attached as
* a suppressed cause so nothing is silently lost either.
*/
private void cancelQuietly(UploadId uploadId, RequestContext context, RuntimeException failure) {
try {
cancel.handle(new CancelUploadCommand(uploadId, context));
} catch (RuntimeException cleanupFailure) {
failure.addSuppressed(cleanupFailure);
}
}
}
@@ -0,0 +1,79 @@
package dev.caskeleton.application.fileserver.upload;
import dev.caskeleton.application.fileserver.api.UploadId;
import dev.caskeleton.application.fileserver.api.error.FileNotFoundException;
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
import dev.caskeleton.application.fileserver.api.error.FileserverException;
import dev.caskeleton.application.fileserver.api.error.FileserverFailureContext;
import dev.caskeleton.application.fileserver.api.metadata.QuotaScope;
import dev.caskeleton.application.fileserver.api.metadata.UploadSession;
import dev.caskeleton.application.fileserver.api.metadata.UploadSessionPort;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import java.time.Instant;
import java.util.OptionalLong;
/**
* The session lookups and limits the upload use cases share.
*
* <p>They were private methods of one upload service. Split into one use case per operation, each
* would otherwise carry its own copy of the refusal a client sees for a missing or ended upload.
*/
final class UploadSessions {
private UploadSessions() {}
static UploadSession require(UploadSessionPort sessions, UploadId uploadId) {
return sessions
.find(uploadId)
.orElseThrow(
() ->
new FileNotFoundException(
"upload resource does not exist",
FileserverFailureContext.forUpload(
FileserverErrorCode.FILE_NOT_FOUND, uploadId, false, false, false)));
}
static UploadSession requireActive(UploadSessionPort sessions, UploadId uploadId, Instant now) {
UploadSession session = require(sessions, uploadId);
if (session.terminal()) {
// Cancelled, rejected or swept. Refusing it as a lease conflict told the client to retry an
// upload that can never accept another byte.
throw new FileserverException(
"upload resource is no longer open",
FileserverFailureContext.forUpload(
FileserverErrorCode.UPLOAD_EXPIRED, uploadId, false, false, false));
}
if (session.isExpiredAt(now)) {
throw new FileserverException(
"upload resource has expired",
FileserverFailureContext.forUpload(
FileserverErrorCode.UPLOAD_EXPIRED, uploadId, false, false, false));
}
return session;
}
/**
* Transfer concurrency is counted per caller.
*
* <p>Counting it per namespace put every caller of a deployment — which uploads into one default
* namespace — behind the same handful of permits, so one busy client refused everyone else.
*/
static QuotaScope admissionScope(RequestContext context) {
return QuotaScope.ofPrincipal(context.subject().principalId());
}
static long effectiveMaximum(UploadPolicy policy, OptionalLong expectedLength) {
return expectedLength.isPresent()
? Math.min(policy.maximumFileSize(), Math.max(expectedLength.getAsLong(), 1))
: policy.maximumFileSize();
}
static UploadSessionView toView(UploadSession session) {
return new UploadSessionView(
session.uploadId(),
session.fileId(),
session.committedOffset(),
session.expectedLength(),
session.expiresAt());
}
}
@@ -16,29 +16,29 @@ import dev.caskeleton.application.fileserver.api.security.FileOperation;
import dev.caskeleton.application.fileserver.api.transfer.UploadMode;
import dev.caskeleton.application.fileserver.cleanup.CleanupRequest;
import dev.caskeleton.application.fileserver.cleanup.CleanupType;
import dev.caskeleton.application.fileserver.cleanup.DefaultCleanupService;
import dev.caskeleton.application.fileserver.observability.FileserverMetricsPort;
import dev.caskeleton.application.fileserver.observability.SafeFileFingerprint;
import dev.caskeleton.application.fileserver.port.in.ForceDeleteCommand;
import dev.caskeleton.application.fileserver.port.in.GetRuntimeCapabilitiesQuery;
import dev.caskeleton.application.fileserver.port.in.GetStorageHealthQuery;
import dev.caskeleton.application.fileserver.port.in.OrphanReconcileCommand;
import dev.caskeleton.application.fileserver.port.in.ReverifyFileCommand;
import dev.caskeleton.application.fileserver.testkit.DirectTransactions;
import dev.caskeleton.application.fileserver.testkit.FakeAdminPorts;
import dev.caskeleton.application.fileserver.testkit.FakeCleanupContentGateway;
import dev.caskeleton.application.fileserver.testkit.FakeFileAccessPolicy;
import dev.caskeleton.application.fileserver.testkit.FileserverFixtures;
import dev.caskeleton.application.fileserver.testkit.InMemoryCleanupQueue;
import dev.caskeleton.application.fileserver.testkit.InMemoryFileMetadataStore;
import dev.caskeleton.application.fileserver.testkit.InMemoryUploadSessionStore;
import dev.caskeleton.application.fileserver.testkit.ReadyFileFixture;
import dev.caskeleton.application.fileserver.testkit.RecordingQuotaReclaimGateway;
import java.nio.charset.StandardCharsets;
import java.time.Clock;
import java.time.Duration;
import java.time.ZoneOffset;
import java.util.List;
import java.util.OptionalLong;
import java.util.UUID;
import org.junit.jupiter.api.Test;
class FileserverAdminServiceTest {
class FileserverAdminUseCasesTest {
private static final String DIGEST = "1".repeat(64);
private static final long SIZE = 10;
@@ -51,33 +51,33 @@ class FileserverAdminServiceTest {
private final FakeFileAccessPolicy accessPolicy = new FakeFileAccessPolicy();
private final Clock clock = Clock.fixed(FileserverFixtures.NOW, ZoneOffset.UTC);
private final FileserverAdminService admin =
new DefaultFileserverAdminService(
adminPorts,
adminPorts,
metadata,
sessions,
sessions,
queue,
new DefaultCleanupService(
queue,
new FakeCleanupContentGateway(),
metadata,
sessions,
new RecordingQuotaReclaimGateway(),
Duration.ofMinutes(5),
FileserverMetricsPort.noop(),
new DirectTransactions(),
clock),
accessPolicy,
private final AdminAudit audit =
new AdminAudit(
adminPorts,
new SafeFileFingerprint("test-fingerprint-key!".getBytes(StandardCharsets.UTF_8)),
new DirectTransactions(),
clock);
private final GetRuntimeCapabilitiesApplicationUseCase capabilities =
new GetRuntimeCapabilitiesApplicationUseCase(adminPorts, accessPolicy);
private final GetStorageHealthApplicationUseCase storageHealth =
new GetStorageHealthApplicationUseCase(adminPorts, accessPolicy);
private final ReconcileOrphansApplicationUseCase reconcile =
new ReconcileOrphansApplicationUseCase(
adminPorts, queue, accessPolicy, audit, new DirectTransactions());
private final ReverifyFileApplicationUseCase reverify =
new ReverifyFileApplicationUseCase(metadata, accessPolicy, audit, new DirectTransactions());
private final ForceDeleteFileApplicationUseCase forceDelete =
new ForceDeleteFileApplicationUseCase(
metadata, sessions, sessions, queue, accessPolicy, audit, new DirectTransactions());
@Test
void capabilitiesNeverDiscloseAPhysicalRoot() {
RuntimeCapabilityReport report = admin.capabilities(FileserverFixtures.context());
RuntimeCapabilityReport report =
capabilities.handle(new GetRuntimeCapabilitiesQuery(FileserverFixtures.context()));
assertThat(report.storageType()).isEqualTo("LOCAL");
assertThat(report.filesystemProfile()).isEqualTo("linux-ext4");
@@ -86,7 +86,8 @@ class FileserverAdminServiceTest {
@Test
void storageHealthReportsProportionsRatherThanPaths() {
StorageHealthReport health = admin.storageHealth(FileserverFixtures.context());
StorageHealthReport health =
storageHealth.handle(new GetStorageHealthQuery(FileserverFixtures.context()));
assertThat(health.usedFraction()).isEqualTo(0.6);
assertThat(health.toString()).doesNotContain("/var").doesNotContain("mount");
@@ -99,7 +100,9 @@ class FileserverAdminServiceTest {
accessPolicy.deny(FileOperation.ADMIN_READ);
// when
Throwable failure = catchThrowable(() -> admin.storageHealth(FileserverFixtures.context()));
Throwable failure =
catchThrowable(
() -> storageHealth.handle(new GetStorageHealthQuery(FileserverFixtures.context())));
// then
assertThat(failure)
@@ -112,7 +115,7 @@ class FileserverAdminServiceTest {
adminPorts.addOrphan(new OrphanObject(ORPHAN_KEY, 100, FileserverFixtures.NOW, "fp-1"));
OrphanReconcileReport report =
admin.reconcileOrphans(OrphanReconcileCommand.dryRun(100), FileserverFixtures.context());
reconcile.handle(OrphanReconcileCommand.dryRun(100, FileserverFixtures.context()));
assertThat(report.dryRun()).isTrue();
assertThat(report.candidates()).hasSize(1);
@@ -128,9 +131,14 @@ class FileserverAdminServiceTest {
ContentKey.of("aa/bb/orphan-object-0002"), 100, FileserverFixtures.NOW, "fp-2"));
OrphanReconcileReport report =
admin.reconcileOrphans(
new OrphanReconcileCommand(false, 100, 1L << 20, List.of("fp-1"), "OPERATOR_APPLY"),
FileserverFixtures.context());
reconcile.handle(
new OrphanReconcileCommand(
false,
100,
1L << 20,
List.of("fp-1"),
"OPERATOR_APPLY",
FileserverFixtures.context()));
assertThat(report.deleted()).isEqualTo(1);
assertThat(report.skippedFingerprintMismatch()).isEqualTo(1);
@@ -145,9 +153,14 @@ class FileserverAdminServiceTest {
ContentKey.of("aa/bb/orphan-object-0002"), 100, FileserverFixtures.NOW, "fp-2"));
OrphanReconcileReport report =
admin.reconcileOrphans(
new OrphanReconcileCommand(false, 100, 100, List.of("fp-1", "fp-2"), "OPERATOR_APPLY"),
FileserverFixtures.context());
reconcile.handle(
new OrphanReconcileCommand(
false,
100,
100,
List.of("fp-1", "fp-2"),
"OPERATOR_APPLY",
FileserverFixtures.context()));
assertThat(report.deleted()).isEqualTo(1);
assertThat(report.reclaimedBytes()).isEqualTo(100);
@@ -156,7 +169,9 @@ class FileserverAdminServiceTest {
@Test
void anApplyWithoutFingerprintsCannotEvenBeConstructed() {
assertThatThrownBy(
() -> new OrphanReconcileCommand(false, 100, 1024, List.of(), "OPERATOR_APPLY"))
() ->
new OrphanReconcileCommand(
false, 100, 1024, List.of(), "OPERATOR_APPLY", FileserverFixtures.context()))
.isInstanceOf(IllegalArgumentException.class);
}
@@ -164,7 +179,10 @@ class FileserverAdminServiceTest {
void reverifyOnlyAcceptsAQuarantinedFileAndAuditsTheRefusal() {
FileRecord ready = ReadyFileFixture.ready(metadata, SIZE, DIGEST);
assertThatThrownBy(() -> admin.reverify(ready.fileId(), FileserverFixtures.context()))
assertThatThrownBy(
() ->
reverify.handle(
new ReverifyFileCommand(ready.fileId(), FileserverFixtures.context())))
.isInstanceOf(FileserverException.class);
assertThat(adminPorts.auditTrail())
@@ -180,7 +198,7 @@ class FileserverAdminServiceTest {
void reverifyMovesAQuarantinedFileBackIntoVerification() {
FileRecord quarantined = quarantinedRecord();
admin.reverify(quarantined.fileId(), FileserverFixtures.context());
reverify.handle(new ReverifyFileCommand(quarantined.fileId(), FileserverFixtures.context()));
assertThat(metadata.find(quarantined.fileId()).orElseThrow().state())
.isEqualTo(FileState.VERIFYING);
@@ -193,9 +211,9 @@ class FileserverAdminServiceTest {
void forceDeleteRequiresTheSecondAuthorityAndIsAudited() {
FileRecord ready = ReadyFileFixture.ready(metadata, SIZE, DIGEST);
admin.forceDelete(
new ForceDeleteCommand(ready.fileId(), "LEGAL_TAKEDOWN_2026_08"),
FileserverFixtures.context());
forceDelete.handle(
new ForceDeleteCommand(
ready.fileId(), "LEGAL_TAKEDOWN_2026_08", FileserverFixtures.context()));
assertThat(accessPolicy.invocations()).containsExactly(FileOperation.ADMIN_FORCE_DELETE);
assertThat(metadata.find(ready.fileId()).orElseThrow().state()).isEqualTo(FileState.DELETING);
@@ -216,9 +234,9 @@ class FileserverAdminServiceTest {
FileRecord uploading = ReadyFileFixture.uploading(metadata, SIZE, DIGEST);
// when
admin.forceDelete(
new ForceDeleteCommand(uploading.fileId(), "LEGAL_TAKEDOWN_2026_08"),
FileserverFixtures.context());
forceDelete.handle(
new ForceDeleteCommand(
uploading.fileId(), "LEGAL_TAKEDOWN_2026_08", FileserverFixtures.context()));
// then
assertThat(metadata.find(uploading.fileId()).orElseThrow().state())
@@ -240,9 +258,9 @@ class FileserverAdminServiceTest {
FileserverFixtures.NOW.plusSeconds(3600)));
// when
admin.forceDelete(
new ForceDeleteCommand(uploading.fileId(), "LEGAL_TAKEDOWN_2026_08"),
FileserverFixtures.context());
forceDelete.handle(
new ForceDeleteCommand(
uploading.fileId(), "LEGAL_TAKEDOWN_2026_08", FileserverFixtures.context()));
// then
assertThat(
@@ -263,9 +281,9 @@ class FileserverAdminServiceTest {
assertThatThrownBy(
() ->
admin.forceDelete(
new ForceDeleteCommand(ready.fileId(), "LEGAL_TAKEDOWN_2026_08"),
FileserverFixtures.context()))
forceDelete.handle(
new ForceDeleteCommand(
ready.fileId(), "LEGAL_TAKEDOWN_2026_08", FileserverFixtures.context())))
.isInstanceOf(FileserverException.class);
assertThat(metadata.find(ready.fileId()).orElseThrow().state()).isEqualTo(FileState.READY);
@@ -275,7 +293,10 @@ class FileserverAdminServiceTest {
void aForceDeleteWithoutAReasonCannotBeConstructed() {
assertThatThrownBy(
() ->
new ForceDeleteCommand(FileId.parse("00000000-0000-0000-0000-000000000001"), " "))
new ForceDeleteCommand(
FileId.parse("00000000-0000-0000-0000-000000000001"),
" ",
FileserverFixtures.context()))
.isInstanceOf(IllegalArgumentException.class);
}
@@ -283,9 +304,9 @@ class FileserverAdminServiceTest {
void theAuditTrailCarriesAnActorFingerprintRatherThanAPrincipal() {
FileRecord ready = ReadyFileFixture.ready(metadata, SIZE, DIGEST);
admin.forceDelete(
new ForceDeleteCommand(ready.fileId(), "LEGAL_TAKEDOWN_2026_08"),
FileserverFixtures.context());
forceDelete.handle(
new ForceDeleteCommand(
ready.fileId(), "LEGAL_TAKEDOWN_2026_08", FileserverFixtures.context()));
assertThat(adminPorts.auditTrail())
.singleElement()
@@ -9,6 +9,10 @@ import dev.caskeleton.application.fileserver.api.error.FileNotFoundException;
import dev.caskeleton.application.fileserver.api.error.FileserverException;
import dev.caskeleton.application.fileserver.api.metadata.FileRecord;
import dev.caskeleton.application.fileserver.api.security.FileOperation;
import dev.caskeleton.application.fileserver.port.in.DescribeFileQuery;
import dev.caskeleton.application.fileserver.port.in.OpenDownloadContentQuery;
import dev.caskeleton.application.fileserver.port.in.PrepareDownloadQuery;
import dev.caskeleton.application.fileserver.testkit.DirectTransactions;
import dev.caskeleton.application.fileserver.testkit.FakeDownloadContentGateway;
import dev.caskeleton.application.fileserver.testkit.FakeFileAccessPolicy;
import dev.caskeleton.application.fileserver.testkit.FileserverFixtures;
@@ -19,7 +23,7 @@ import java.nio.channels.ReadableByteChannel;
import java.util.UUID;
import org.junit.jupiter.api.Test;
class DownloadApplicationServiceTest {
class DownloadUseCasesTest {
private static final String DIGEST = "b".repeat(64);
private static final long SIZE = 10;
@@ -28,15 +32,19 @@ class DownloadApplicationServiceTest {
private final FakeDownloadContentGateway content = new FakeDownloadContentGateway();
private final FakeFileAccessPolicy accessPolicy = new FakeFileAccessPolicy();
private final DownloadApplicationService service =
new DefaultDownloadApplicationService(metadata, content, accessPolicy);
private final PrepareDownloadApplicationUseCase prepare =
new PrepareDownloadApplicationUseCase(metadata, accessPolicy, new DirectTransactions());
private final DescribeFileApplicationUseCase describeFile =
new DescribeFileApplicationUseCase(metadata, accessPolicy, new DirectTransactions());
private final OpenDownloadContentApplicationUseCase open =
new OpenDownloadContentApplicationUseCase(content);
@Test
void readyFileExposesOnlyImmutableContentFacts() {
FileRecord ready = ReadyFileFixture.ready(metadata, SIZE, DIGEST);
DownloadDescriptor descriptor =
service.describe(DownloadRequest.of(ready.fileId()), FileserverFixtures.context());
prepare.handle(new PrepareDownloadQuery(ready.fileId(), FileserverFixtures.context()));
assertThat(descriptor.representation().length()).isEqualTo(SIZE);
assertThat(descriptor.representation().sha256()).isEqualTo(DIGEST);
@@ -51,8 +59,8 @@ class DownloadApplicationServiceTest {
assertThatThrownBy(
() ->
service.describe(
DownloadRequest.of(verifying.fileId()), FileserverFixtures.context()))
prepare.handle(
new PrepareDownloadQuery(verifying.fileId(), FileserverFixtures.context())))
.isInstanceOf(FileserverException.class);
assertThat(content.neverOpened()).isTrue();
@@ -64,8 +72,8 @@ class DownloadApplicationServiceTest {
assertThatThrownBy(
() ->
service.describe(
DownloadRequest.of(verifying.fileId()), FileserverFixtures.context()))
prepare.handle(
new PrepareDownloadQuery(verifying.fileId(), FileserverFixtures.context())))
.isInstanceOf(FileserverException.class);
assertThat(content.neverOpened()).isTrue();
@@ -75,8 +83,9 @@ class DownloadApplicationServiceTest {
void unknownFileIsNotFound() {
assertThatThrownBy(
() ->
service.describe(
DownloadRequest.of(FileId.of(UUID.randomUUID())), FileserverFixtures.context()))
prepare.handle(
new PrepareDownloadQuery(
FileId.of(UUID.randomUUID()), FileserverFixtures.context())))
.isInstanceOf(FileNotFoundException.class);
}
@@ -86,10 +95,11 @@ class DownloadApplicationServiceTest {
content.store(new byte[] {0, 1, 2, 3, 4, 5, 6, 7, 8, 9});
DownloadDescriptor descriptor =
service.describe(DownloadRequest.of(ready.fileId()), FileserverFixtures.context());
prepare.handle(new PrepareDownloadQuery(ready.fileId(), FileserverFixtures.context()));
ByteRange range = ByteRange.of(2, 4);
ByteBuffer buffer = ByteBuffer.allocate(8);
try (ReadableByteChannel channel = service.openContent(descriptor, range)) {
try (ReadableByteChannel channel =
open.handle(new OpenDownloadContentQuery(descriptor, range))) {
channel.read(buffer);
}
@@ -101,7 +111,10 @@ class DownloadApplicationServiceTest {
void metadataReadIsItsOwnAuthorizedOperation() {
FileRecord ready = ReadyFileFixture.ready(metadata, SIZE, DIGEST);
assertThat(service.describeFile(ready.fileId(), FileserverFixtures.context()).isDownloadable())
assertThat(
describeFile
.handle(new DescribeFileQuery(ready.fileId(), FileserverFixtures.context()))
.isDownloadable())
.isTrue();
assertThat(accessPolicy.invocations()).containsExactly(FileOperation.READ_METADATA);
}
@@ -14,6 +14,9 @@ import dev.caskeleton.application.fileserver.api.security.OriginalFilenamePolicy
import dev.caskeleton.application.fileserver.api.transfer.UploadMode;
import dev.caskeleton.application.fileserver.cleanup.CleanupRequest;
import dev.caskeleton.application.fileserver.cleanup.CleanupType;
import dev.caskeleton.application.fileserver.port.in.CopyFileCommand;
import dev.caskeleton.application.fileserver.port.in.DeleteFileCommand;
import dev.caskeleton.application.fileserver.port.in.MoveFileCommand;
import dev.caskeleton.application.fileserver.testkit.DirectTransactions;
import dev.caskeleton.application.fileserver.testkit.FakeCopyContentGateway;
import dev.caskeleton.application.fileserver.testkit.FakeFileAccessPolicy;
@@ -32,7 +35,7 @@ import java.util.OptionalLong;
import java.util.UUID;
import org.junit.jupiter.api.Test;
class FileLifecycleServiceTest {
class FileLifecycleUseCasesTest {
private static final String DIGEST = "f".repeat(64);
private static final long SIZE = 10;
@@ -43,25 +46,32 @@ class FileLifecycleServiceTest {
private final InMemoryCleanupQueue cleanup = new InMemoryCleanupQueue();
private final InMemoryUploadSessionStore sessions = new InMemoryUploadSessionStore();
private final FileLifecycleService service =
new DefaultFileLifecycleService(
private final DirectTransactions transactions = new DirectTransactions();
private final DeleteFileApplicationUseCase delete =
new DeleteFileApplicationUseCase(
metadata, accessPolicy, cleanup, sessions, sessions, transactions);
private final CopyFileApplicationUseCase copy =
new CopyFileApplicationUseCase(
metadata,
copyGateway,
accessPolicy,
OriginalFilenamePolicy.standard(),
cleanup,
sessions,
sessions,
new SequentialUploadIdentifierFactory(),
new DirectTransactions(),
transactions,
Clock.fixed(FileserverFixtures.NOW, ZoneOffset.UTC));
private final MoveFileApplicationUseCase move =
new MoveFileApplicationUseCase(metadata, accessPolicy, transactions);
@Test
void logicalDeleteBlocksDownloadBeforePhysicalDeleteCompletes() {
FileRecord ready = ReadyFileFixture.ready(metadata, SIZE, DIGEST);
DeleteOutcome outcome =
service.delete(ready.fileId(), Optional.empty(), FileserverFixtures.context());
delete.handle(
new DeleteFileCommand(ready.fileId(), Optional.empty(), FileserverFixtures.context()));
assertThat(outcome.physicalCleanupScheduled()).isTrue();
FileRecord current = metadata.find(ready.fileId()).orElseThrow();
@@ -77,7 +87,9 @@ class FileLifecycleServiceTest {
FileRecord uploading = ReadyFileFixture.uploading(metadata, SIZE, DIGEST);
DeleteOutcome outcome =
service.delete(uploading.fileId(), Optional.empty(), FileserverFixtures.context());
delete.handle(
new DeleteFileCommand(
uploading.fileId(), Optional.empty(), FileserverFixtures.context()));
assertThat(outcome.physicalCleanupScheduled()).isFalse();
assertThat(metadata.find(uploading.fileId()).orElseThrow().state())
@@ -99,7 +111,8 @@ class FileLifecycleServiceTest {
FileserverFixtures.NOW.plusSeconds(3600)));
// when
service.delete(uploading.fileId(), Optional.empty(), FileserverFixtures.context());
delete.handle(
new DeleteFileCommand(uploading.fileId(), Optional.empty(), FileserverFixtures.context()));
// then
assertThat(
@@ -119,7 +132,9 @@ class FileLifecycleServiceTest {
assertThatThrownBy(
() ->
service.delete(verifying.fileId(), Optional.empty(), FileserverFixtures.context()))
delete.handle(
new DeleteFileCommand(
verifying.fileId(), Optional.empty(), FileserverFixtures.context())))
.isInstanceOf(FileserverException.class);
assertThat(metadata.find(verifying.fileId()).orElseThrow().state())
@@ -132,8 +147,9 @@ class FileLifecycleServiceTest {
assertThatThrownBy(
() ->
service.delete(
ready.fileId(), Optional.of("\"stale\""), FileserverFixtures.context()))
delete.handle(
new DeleteFileCommand(
ready.fileId(), Optional.of("\"stale\""), FileserverFixtures.context())))
.isInstanceOf(FileserverException.class);
assertThat(metadata.find(ready.fileId()).orElseThrow().state()).isEqualTo(FileState.READY);
@@ -146,7 +162,10 @@ class FileLifecycleServiceTest {
accessPolicy.deny(FileOperation.DELETE);
assertThatThrownBy(
() -> service.delete(ready.fileId(), Optional.empty(), FileserverFixtures.context()))
() ->
delete.handle(
new DeleteFileCommand(
ready.fileId(), Optional.empty(), FileserverFixtures.context())))
.isInstanceOf(FileserverException.class);
assertThat(metadata.find(ready.fileId()).orElseThrow().state()).isEqualTo(FileState.READY);
@@ -158,13 +177,13 @@ class FileLifecycleServiceTest {
copyGateway.copiesContentOf(SIZE, DIGEST);
FileView copied =
service.copy(
copy.handle(
new CopyFileCommand(
source.fileId(),
StorageNamespace.of("tenant-b"),
Optional.of("copy.bin"),
Optional.empty()),
FileserverFixtures.context());
Optional.empty(),
FileserverFixtures.context()));
assertThat(copied.state()).isEqualTo(FileState.READY);
assertThat(copied.fileId()).isNotEqualTo(source.fileId());
@@ -180,13 +199,13 @@ class FileLifecycleServiceTest {
assertThatThrownBy(
() ->
service.copy(
copy.handle(
new CopyFileCommand(
source.fileId(),
StorageNamespace.of("tenant-b"),
Optional.empty(),
Optional.empty()),
FileserverFixtures.context()))
Optional.empty(),
FileserverFixtures.context())))
.isInstanceOf(FileserverException.class);
assertThat(metadata.find(source.fileId()).orElseThrow().state()).isEqualTo(FileState.READY);
@@ -198,13 +217,13 @@ class FileLifecycleServiceTest {
assertThatThrownBy(
() ->
service.copy(
copy.handle(
new CopyFileCommand(
verifying.fileId(),
StorageNamespace.of("tenant-b"),
Optional.empty(),
Optional.empty()),
FileserverFixtures.context()))
Optional.empty(),
FileserverFixtures.context())))
.isInstanceOf(FileserverException.class);
assertThat(copyGateway.copies()).isEmpty();
@@ -215,11 +234,12 @@ class FileLifecycleServiceTest {
FileRecord ready = ReadyFileFixture.ready(metadata, SIZE, DIGEST);
FileView moved =
service.move(
ready.fileId(),
StorageNamespace.of("tenant-b"),
Optional.of(DIGEST),
FileserverFixtures.context());
move.handle(
new MoveFileCommand(
ready.fileId(),
StorageNamespace.of("tenant-b"),
Optional.of(DIGEST),
FileserverFixtures.context()));
assertThat(moved.descriptor().namespace()).isEqualTo(StorageNamespace.of("tenant-b"));
assertThat(metadata.find(ready.fileId()).orElseThrow().contentKey())
@@ -230,12 +250,14 @@ class FileLifecycleServiceTest {
@Test
void everyLifecycleOperationConsultsItsOwnAccessOperation() {
FileRecord ready = ReadyFileFixture.ready(metadata, SIZE, DIGEST);
service.move(
ready.fileId(),
StorageNamespace.of("tenant-b"),
Optional.empty(),
FileserverFixtures.context());
service.delete(ready.fileId(), Optional.empty(), FileserverFixtures.context());
move.handle(
new MoveFileCommand(
ready.fileId(),
StorageNamespace.of("tenant-b"),
Optional.empty(),
FileserverFixtures.context()));
delete.handle(
new DeleteFileCommand(ready.fileId(), Optional.empty(), FileserverFixtures.context()));
assertThat(accessPolicy.invocations())
.containsExactly(FileOperation.MOVE, FileOperation.DELETE);
@@ -244,10 +266,13 @@ class FileLifecycleServiceTest {
@Test
void deletingAnAlreadyDeletedRecordIsIdempotent() {
FileRecord uploading = ReadyFileFixture.uploading(metadata, SIZE, DIGEST);
service.delete(uploading.fileId(), Optional.empty(), FileserverFixtures.context());
delete.handle(
new DeleteFileCommand(uploading.fileId(), Optional.empty(), FileserverFixtures.context()));
DeleteOutcome second =
service.delete(uploading.fileId(), Optional.empty(), FileserverFixtures.context());
delete.handle(
new DeleteFileCommand(
uploading.fileId(), Optional.empty(), FileserverFixtures.context()));
assertThat(second.physicalCleanupScheduled()).isFalse();
assertThat(metadata.find(uploading.fileId()).orElseThrow().state())
@@ -39,6 +39,17 @@ public final class InMemoryUploadSessionStore
this.now = instant;
}
/**
* Records a session in a state a test built directly, as if earlier appends had produced it.
*
* @param session the session
* @return the same session
*/
public UploadSession seed(UploadSession session) {
sessions.put(session.uploadId(), session);
return session;
}
@Override
public UploadSession create(UploadSessionDraft draft) {
UploadSession session =
@@ -1,142 +0,0 @@
package dev.caskeleton.application.fileserver.upload;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.UploadId;
import dev.caskeleton.application.fileserver.api.error.AmbiguousCompletionException;
import dev.caskeleton.application.fileserver.api.metadata.UploadSession;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.api.transfer.UploadMode;
import dev.caskeleton.application.fileserver.testkit.FileserverFixtures;
import java.io.ByteArrayInputStream;
import java.nio.channels.Channels;
import java.nio.channels.ReadableByteChannel;
import java.util.Optional;
import java.util.OptionalLong;
import java.util.UUID;
import org.junit.jupiter.api.Test;
class DefaultSingleShotUploadServiceTest {
private static final UploadId UPLOAD_ID =
UploadId.of(UUID.fromString("00000000-0000-7000-8000-000000000041"));
private static final FileId FILE_ID =
FileId.of(UUID.fromString("00000000-0000-7000-8000-000000000042"));
@Test
void appendFailureCancelsTheCreatedUploadBeforePropagating() {
RuntimeException failure = new IllegalStateException("append failed");
RecordingUploadService upload = new RecordingUploadService(failure);
DefaultSingleShotUploadService service =
new DefaultSingleShotUploadService(upload, new NeverFinalize());
assertThatThrownBy(() -> upload(service)).isSameAs(failure);
assertThat(upload.cancelCalls).isEqualTo(1);
}
@Test
void ambiguousFinalizeIsLeftForReconciliationInsteadOfBlindCancellation() {
RecordingUploadService upload = new RecordingUploadService(null);
AmbiguousCompletionException ambiguous =
AmbiguousCompletionException.forUpload("publish outcome unknown", UPLOAD_ID);
DefaultSingleShotUploadService service =
new DefaultSingleShotUploadService(upload, new AmbiguousFinalize(ambiguous));
assertThatThrownBy(() -> upload(service)).isSameAs(ambiguous);
assertThat(upload.cancelCalls).isZero();
}
private static void upload(DefaultSingleShotUploadService service) {
try (ReadableByteChannel content =
Channels.newChannel(new ByteArrayInputStream(new byte[] {1, 2, 3}))) {
service.upload(
new CreateUploadRequest(
"report.bin",
Optional.of("application/octet-stream"),
OptionalLong.of(3),
Optional.empty(),
UploadMode.SINGLE_SHOT),
content,
3,
FinalizeUploadRequest.synchronousWithoutDigest(),
FileserverFixtures.context());
} catch (java.io.IOException impossible) {
throw new IllegalStateException(impossible);
}
}
private static final class RecordingUploadService implements UploadApplicationService {
private final RuntimeException appendFailure;
private int cancelCalls;
RecordingUploadService(RuntimeException appendFailure) {
this.appendFailure = appendFailure;
}
@Override
public UploadSessionView create(CreateUploadRequest request, RequestContext context) {
return new UploadSessionView(
UPLOAD_ID, FILE_ID, 0, OptionalLong.of(3), FileserverFixtures.NOW.plusSeconds(3600));
}
@Override
public AppendUploadResult append(
UploadId uploadId,
long expectedOffset,
ReadableByteChannel content,
long contentLength,
Optional<String> expectedChunkSha256,
RequestContext context) {
if (appendFailure != null) {
throw appendFailure;
}
return new AppendUploadResult(3, 3, FileserverFixtures.DIGEST);
}
@Override
public UploadSessionView status(UploadId uploadId, RequestContext context) {
throw new UnsupportedOperationException();
}
@Override
public void cancel(UploadId uploadId, RequestContext context) {
cancelCalls++;
}
}
private static final class NeverFinalize implements FinalizeUploadService {
@Override
public FileView finalizeUpload(
UploadSession session, FinalizeUploadRequest request, RequestContext context) {
throw new AssertionError("finalize must not run after append failure");
}
@Override
public FileView finalizeUpload(
UploadId uploadId, FinalizeUploadRequest request, RequestContext context) {
throw new AssertionError("finalize must not run after append failure");
}
}
private static final class AmbiguousFinalize implements FinalizeUploadService {
private final AmbiguousCompletionException failure;
AmbiguousFinalize(AmbiguousCompletionException failure) {
this.failure = failure;
}
@Override
public FileView finalizeUpload(
UploadSession session, FinalizeUploadRequest request, RequestContext context) {
throw new UnsupportedOperationException();
}
@Override
public FileView finalizeUpload(
UploadId uploadId, FinalizeUploadRequest request, RequestContext context) {
throw failure;
}
}
}
@@ -16,6 +16,7 @@ import dev.caskeleton.application.fileserver.api.metadata.FileRecordMutation;
import dev.caskeleton.application.fileserver.api.metadata.UploadSession;
import dev.caskeleton.application.fileserver.api.security.FileOperation;
import dev.caskeleton.application.fileserver.api.security.VerificationResult;
import dev.caskeleton.application.fileserver.port.in.FinalizeUploadCommand;
import dev.caskeleton.application.fileserver.testkit.DirectTransactions;
import dev.caskeleton.application.fileserver.testkit.FakeFileAccessPolicy;
import dev.caskeleton.application.fileserver.testkit.FakeQuotaCommitGateway;
@@ -32,7 +33,7 @@ import java.util.UUID;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
class FinalizeUploadServiceTest {
class FinalizeUploadApplicationUseCaseTest {
private final InMemoryFileMetadataStore metadata = new InMemoryFileMetadataStore();
private final InMemoryUploadSessionStore sessions = new InMemoryUploadSessionStore();
@@ -44,12 +45,12 @@ class FinalizeUploadServiceTest {
private final DirectTransactions transactions = new DirectTransactions();
private VerificationResult verdict = VerificationResult.accept("ALL_CHECKS_PASSED");
private FinalizeUploadService service;
private FinalizeUploadApplicationUseCase service;
@BeforeEach
void createService() {
service =
new DefaultFinalizeUploadService(
new FinalizeUploadApplicationUseCase(
metadata,
sessions,
content,
@@ -68,10 +69,11 @@ class FinalizeUploadServiceTest {
UploadSession session = uploadedSession(10);
FileView result =
service.finalizeUpload(
session,
new FinalizeUploadRequest(Optional.of(FileserverFixtures.DIGEST), false),
FileserverFixtures.context());
service.handle(
new FinalizeUploadCommand(
session.uploadId(),
new FinalizeUploadRequest(Optional.of(FileserverFixtures.DIGEST), false),
FileserverFixtures.context()));
assertThat(result.state()).isEqualTo(FileState.READY);
FileRecord stored = metadata.find(result.fileId()).orElseThrow();
@@ -89,10 +91,11 @@ class FinalizeUploadServiceTest {
assertThatThrownBy(
() ->
service.finalizeUpload(
session,
new FinalizeUploadRequest(Optional.of("0".repeat(64)), false),
FileserverFixtures.context()))
service.handle(
new FinalizeUploadCommand(
session.uploadId(),
new FinalizeUploadRequest(Optional.of("0".repeat(64)), false),
FileserverFixtures.context())))
.isInstanceOf(FileserverException.class);
assertThat(metadata.find(session.fileId()).orElseThrow().state()).isEqualTo(FileState.REJECTED);
@@ -104,8 +107,11 @@ class FinalizeUploadServiceTest {
void quotaIsCommittedOnlyAfterTheReadyTransition() {
UploadSession session = uploadedSession(10);
service.finalizeUpload(
session, FinalizeUploadRequest.synchronousWithoutDigest(), FileserverFixtures.context());
service.handle(
new FinalizeUploadCommand(
session.uploadId(),
FinalizeUploadRequest.synchronousWithoutDigest(),
FileserverFixtures.context()));
assertThat(quota.committedBytes()).isEqualTo(10);
assertThat(content.leaseReleases()).isEqualTo(1);
@@ -117,10 +123,11 @@ class FinalizeUploadServiceTest {
UploadSession session = uploadedSession(10);
FileView result =
service.finalizeUpload(
session,
FinalizeUploadRequest.synchronousWithoutDigest(),
FileserverFixtures.context());
service.handle(
new FinalizeUploadCommand(
session.uploadId(),
FinalizeUploadRequest.synchronousWithoutDigest(),
FileserverFixtures.context()));
assertThat(result.state()).isEqualTo(FileState.REJECTED);
assertThat(result.isDownloadable()).isFalse();
@@ -136,10 +143,11 @@ class FinalizeUploadServiceTest {
assertThatThrownBy(
() ->
service.finalizeUpload(
session,
FinalizeUploadRequest.synchronousWithoutDigest(),
FileserverFixtures.context()))
service.handle(
new FinalizeUploadCommand(
session.uploadId(),
FinalizeUploadRequest.synchronousWithoutDigest(),
FileserverFixtures.context())))
.isInstanceOf(FileserverException.class);
assertThat(metadata.find(session.fileId()).orElseThrow().state()).isEqualTo(FileState.REJECTED);
@@ -151,10 +159,11 @@ class FinalizeUploadServiceTest {
UploadSession session = uploadedSession(10);
FileView result =
service.finalizeUpload(
session,
FinalizeUploadRequest.synchronousWithoutDigest(),
FileserverFixtures.context());
service.handle(
new FinalizeUploadCommand(
session.uploadId(),
FinalizeUploadRequest.synchronousWithoutDigest(),
FileserverFixtures.context()));
assertThat(result.state()).isEqualTo(FileState.QUARANTINED);
assertThat(result.isDownloadable()).isFalse();
@@ -169,8 +178,11 @@ class FinalizeUploadServiceTest {
UploadSession session = uploadedSession(10);
// when
service.finalizeUpload(
session, FinalizeUploadRequest.synchronousWithoutDigest(), FileserverFixtures.context());
service.handle(
new FinalizeUploadCommand(
session.uploadId(),
FinalizeUploadRequest.synchronousWithoutDigest(),
FileserverFixtures.context()));
// then
assertThat(cleanup.queued()).isEmpty();
@@ -186,10 +198,11 @@ class FinalizeUploadServiceTest {
Throwable failure =
catchThrowable(
() ->
service.finalizeUpload(
session,
FinalizeUploadRequest.synchronousWithoutDigest(),
FileserverFixtures.context()));
service.handle(
new FinalizeUploadCommand(
session.uploadId(),
FinalizeUploadRequest.synchronousWithoutDigest(),
FileserverFixtures.context())));
// then
assertThat(failure)
@@ -208,10 +221,11 @@ class FinalizeUploadServiceTest {
Throwable failure =
catchThrowable(
() ->
service.finalizeUpload(
session,
FinalizeUploadRequest.synchronousWithoutDigest(),
FileserverFixtures.context()));
service.handle(
new FinalizeUploadCommand(
session.uploadId(),
FinalizeUploadRequest.synchronousWithoutDigest(),
FileserverFixtures.context())));
// then
assertThat(metadata.find(session.fileId()).orElseThrow().contentKey())
@@ -232,10 +246,11 @@ class FinalizeUploadServiceTest {
Throwable failure =
catchThrowable(
() ->
service.finalizeUpload(
session,
FinalizeUploadRequest.synchronousWithoutDigest(),
FileserverFixtures.context()));
service.handle(
new FinalizeUploadCommand(
session.uploadId(),
FinalizeUploadRequest.synchronousWithoutDigest(),
FileserverFixtures.context())));
// then
assertThat(recovery.reasons())
@@ -249,10 +264,11 @@ class FinalizeUploadServiceTest {
UploadSession session = uploadedSession(10);
FileView result =
service.finalizeUpload(
session,
FinalizeUploadRequest.synchronousWithoutDigest(),
FileserverFixtures.context());
service.handle(
new FinalizeUploadCommand(
session.uploadId(),
FinalizeUploadRequest.synchronousWithoutDigest(),
FileserverFixtures.context()));
assertThat(result.state()).isEqualTo(FileState.VERIFYING);
assertThat(result.isDownloadable()).isFalse();
@@ -265,10 +281,11 @@ class FinalizeUploadServiceTest {
assertThatThrownBy(
() ->
service.finalizeUpload(
session,
FinalizeUploadRequest.synchronousWithoutDigest(),
FileserverFixtures.context()))
service.handle(
new FinalizeUploadCommand(
session.uploadId(),
FinalizeUploadRequest.synchronousWithoutDigest(),
FileserverFixtures.context())))
.isInstanceOf(FileserverException.class);
assertThat(content.publishedCount()).isZero();
@@ -283,10 +300,11 @@ class FinalizeUploadServiceTest {
assertThatThrownBy(
() ->
service.finalizeUpload(
session,
FinalizeUploadRequest.synchronousWithoutDigest(),
FileserverFixtures.context()))
service.handle(
new FinalizeUploadCommand(
session.uploadId(),
FinalizeUploadRequest.synchronousWithoutDigest(),
FileserverFixtures.context())))
.isInstanceOf(AmbiguousCompletionException.class)
.satisfies(
failure -> {
@@ -309,14 +327,15 @@ class FinalizeUploadServiceTest {
// given
FileId fileId = FileId.of(UUID.randomUUID());
metadata.insert(FileserverFixtures.draft(fileId, 10));
UploadSession session = FileserverFixtures.session(fileId, 10, 10);
UploadSession session = sessions.seed(FileserverFixtures.session(fileId, 10, 10));
// when
FileView result =
service.finalizeUpload(
session,
FinalizeUploadRequest.synchronousWithoutDigest(),
FileserverFixtures.context());
service.handle(
new FinalizeUploadCommand(
session.uploadId(),
FinalizeUploadRequest.synchronousWithoutDigest(),
FileserverFixtures.context()));
// then
assertThat(result.state()).isEqualTo(FileState.READY);
@@ -335,7 +354,7 @@ class FinalizeUploadServiceTest {
FileState.CREATED,
FileState.UPLOADING,
FileRecordMutation.none());
return FileserverFixtures.session(fileId, declaredLength, committedOffset);
return sessions.seed(FileserverFixtures.session(fileId, declaredLength, committedOffset));
}
/** Moves the record to VERIFYING so the injected failure lands on the READY commit. */
@@ -22,7 +22,6 @@ import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.api.transfer.UploadMode;
import dev.caskeleton.application.fileserver.cleanup.CleanupType;
import dev.caskeleton.application.fileserver.concurrency.WriterLeaseCoordinator;
import dev.caskeleton.application.fileserver.observability.FileserverMetricsPort;
import dev.caskeleton.application.fileserver.quota.StorageUsagePort;
import dev.caskeleton.application.fileserver.quota.TransferAdmissionController;
import dev.caskeleton.application.fileserver.quota.TransferAdmissionProperties;
@@ -52,7 +51,7 @@ import java.util.OptionalLong;
import java.util.Set;
import org.junit.jupiter.api.Test;
class UploadApplicationServiceTest {
class ResumableUploadUseCasesTest {
private static final long MAX_FILE = 100L * 1024 * 1024;
@@ -64,7 +63,7 @@ class UploadApplicationServiceTest {
private final InMemoryCleanupQueue cleanup = new InMemoryCleanupQueue();
private final DirectTransactions transactions = new DirectTransactions();
private final UploadApplicationService service = serviceAt(FileserverFixtures.NOW);
private final UploadUseCases service = serviceAt(FileserverFixtures.NOW);
@Test
void authorizationRunsBeforeQuotaAndStorageMutation() {
@@ -107,7 +106,7 @@ class UploadApplicationServiceTest {
new TransferAdmissionProperties(16, 1, 64, 0.70, 0.85),
StorageUsagePort.unknown(),
MAX_FILE);
UploadApplicationService narrow = service(FileserverFixtures.NOW, admission);
UploadUseCases narrow = service(FileserverFixtures.NOW, admission);
try (TransferPermit namespaceFull =
admission.acquireUpload(QuotaScope.ofNamespace(FileserverFixtures.NAMESPACE.value()), 1)) {
@@ -362,7 +361,7 @@ class UploadApplicationServiceTest {
@Test
void anExpiredUploadCanNoLongerBeAppended() {
UploadSessionView created = service.create(createRequest(), FileserverFixtures.context());
UploadApplicationService afterExpiry = serviceAt(FileserverFixtures.NOW.plusSeconds(7200));
UploadUseCases afterExpiry = serviceAt(FileserverFixtures.NOW.plusSeconds(7200));
assertThatThrownBy(
() ->
@@ -427,17 +426,16 @@ class UploadApplicationServiceTest {
.isInstanceOf(dev.caskeleton.application.fileserver.api.error.FileNotFoundException.class);
}
private UploadApplicationService serviceAt(java.time.Instant instant) {
private UploadUseCases serviceAt(java.time.Instant instant) {
return service(
instant,
new TransferAdmissionController(
TransferAdmissionProperties.standard(), StorageUsagePort.unknown(), MAX_FILE));
}
private UploadApplicationService service(
java.time.Instant instant, TransferAdmissionController admission) {
private UploadUseCases service(java.time.Instant instant, TransferAdmissionController admission) {
Clock clock = Clock.fixed(instant, ZoneOffset.UTC);
return new DefaultUploadApplicationService(
return UploadUseCases.over(
new UploadStores(metadata, sessions, cleanup),
new UploadPolicies(
accessPolicy,
@@ -452,7 +450,6 @@ class UploadApplicationServiceTest {
quota,
admission,
new SequentialUploadIdentifierFactory(),
FileserverMetricsPort.noop(),
transactions,
clock);
}
@@ -0,0 +1,98 @@
package dev.caskeleton.application.fileserver.upload;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.catchThrowable;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.UploadId;
import dev.caskeleton.application.fileserver.api.error.AmbiguousCompletionException;
import dev.caskeleton.application.fileserver.api.transfer.UploadMode;
import dev.caskeleton.application.fileserver.port.in.AppendUploadUseCase;
import dev.caskeleton.application.fileserver.port.in.CancelUploadUseCase;
import dev.caskeleton.application.fileserver.port.in.CreateUploadUseCase;
import dev.caskeleton.application.fileserver.port.in.FinalizeUploadUseCase;
import dev.caskeleton.application.fileserver.port.in.UploadFileCommand;
import dev.caskeleton.application.fileserver.testkit.FileserverFixtures;
import java.io.ByteArrayInputStream;
import java.nio.channels.Channels;
import java.util.List;
import java.util.Optional;
import java.util.OptionalLong;
import java.util.UUID;
import java.util.concurrent.CopyOnWriteArrayList;
import org.junit.jupiter.api.Test;
class UploadFileApplicationUseCaseTest {
private static final UploadId UPLOAD_ID =
UploadId.of(UUID.fromString("00000000-0000-7000-8000-000000000041"));
private static final FileId FILE_ID =
FileId.of(UUID.fromString("00000000-0000-7000-8000-000000000042"));
private final List<UploadId> cancelled = new CopyOnWriteArrayList<>();
private final CreateUploadUseCase create =
command ->
new UploadSessionView(
UPLOAD_ID, FILE_ID, 0, OptionalLong.of(3), FileserverFixtures.NOW.plusSeconds(3600));
private final CancelUploadUseCase cancel =
command -> {
cancelled.add(command.uploadId());
return null;
};
@Test
void appendFailureCancelsTheCreatedUploadBeforePropagating() {
// given
RuntimeException failure = new IllegalStateException("append failed");
AppendUploadUseCase append =
command -> {
throw failure;
};
FinalizeUploadUseCase finalizer =
command -> {
throw new AssertionError("finalize must not run after append failure");
};
UploadFileApplicationUseCase useCase =
new UploadFileApplicationUseCase(create, append, finalizer, cancel);
// when
Throwable thrown = catchThrowable(() -> useCase.handle(command()));
// then
assertThat(List.of(thrown, cancelled)).containsExactly(failure, List.of(UPLOAD_ID));
}
@Test
void ambiguousFinalizeIsLeftForReconciliationInsteadOfBlindCancellation() {
// given
AmbiguousCompletionException ambiguous =
AmbiguousCompletionException.forUpload("publish outcome unknown", UPLOAD_ID);
AppendUploadUseCase append = command -> new AppendUploadResult(3, 3, FileserverFixtures.DIGEST);
FinalizeUploadUseCase finalizer =
command -> {
throw ambiguous;
};
UploadFileApplicationUseCase useCase =
new UploadFileApplicationUseCase(create, append, finalizer, cancel);
// when
Throwable thrown = catchThrowable(() -> useCase.handle(command()));
// then
assertThat(List.of(thrown, cancelled)).containsExactly(ambiguous, List.of());
}
private static UploadFileCommand command() {
return new UploadFileCommand(
new CreateUploadRequest(
"report.bin",
Optional.of("application/octet-stream"),
OptionalLong.of(3),
Optional.empty(),
UploadMode.SINGLE_SHOT),
Channels.newChannel(new ByteArrayInputStream(new byte[] {1, 2, 3})),
3,
FinalizeUploadRequest.synchronousWithoutDigest(),
FileserverFixtures.context());
}
}
@@ -0,0 +1,92 @@
package dev.caskeleton.application.fileserver.upload;
import dev.caskeleton.application.fileserver.api.UploadId;
import dev.caskeleton.application.fileserver.api.metadata.FileQuotaPort;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.concurrency.WriterLeaseCoordinator;
import dev.caskeleton.application.fileserver.observability.FileserverMetricsPort;
import dev.caskeleton.application.fileserver.port.in.AppendUploadCommand;
import dev.caskeleton.application.fileserver.port.in.AppendUploadUseCase;
import dev.caskeleton.application.fileserver.port.in.CancelUploadCommand;
import dev.caskeleton.application.fileserver.port.in.CancelUploadUseCase;
import dev.caskeleton.application.fileserver.port.in.CreateUploadCommand;
import dev.caskeleton.application.fileserver.port.in.CreateUploadUseCase;
import dev.caskeleton.application.fileserver.port.in.GetUploadStatusQuery;
import dev.caskeleton.application.fileserver.port.in.GetUploadStatusUseCase;
import dev.caskeleton.application.fileserver.quota.TransferAdmissionController;
import dev.caskeleton.application.transaction.TransactionPort;
import java.nio.channels.ReadableByteChannel;
import java.time.Clock;
import java.util.Optional;
/**
* The four resumable-upload use cases over one set of fakes, called the way a transport calls them.
*
* <p>Each method builds the command and hands it to the use case; nothing else happens here, so a
* test reads as a sequence of client operations rather than a sequence of command constructions.
*/
record UploadUseCases(
CreateUploadUseCase create,
AppendUploadUseCase append,
GetUploadStatusUseCase status,
CancelUploadUseCase cancel) {
static UploadUseCases over(
UploadStores stores,
UploadPolicies policies,
WriterLeaseCoordinator leases,
UploadStoragePort storage,
FileQuotaPort quota,
TransferAdmissionController admission,
UploadIdentifierPort identifiers,
TransactionPort transactions,
Clock clock) {
return new UploadUseCases(
new CreateUploadApplicationUseCase(
stores, policies, storage, quota, admission, identifiers, transactions, clock),
new AppendUploadApplicationUseCase(
stores,
policies,
leases,
storage,
admission,
FileserverMetricsPort.noop(),
transactions,
clock),
new GetUploadStatusApplicationUseCase(stores, policies.access(), transactions, clock),
new CancelUploadApplicationUseCase(stores, policies.access(), transactions));
}
UploadSessionView create(CreateUploadRequest request, RequestContext context) {
return create.handle(new CreateUploadCommand(request, context));
}
AppendUploadResult append(
UploadId uploadId,
long expectedOffset,
ReadableByteChannel content,
long contentLength,
Optional<String> expectedChunkSha256,
RequestContext context) {
return append.handle(
new AppendUploadCommand(
uploadId, expectedOffset, content, contentLength, expectedChunkSha256, context));
}
AppendUploadResult append(
UploadId uploadId,
long expectedOffset,
ReadableByteChannel content,
long contentLength,
RequestContext context) {
return append(uploadId, expectedOffset, content, contentLength, Optional.empty(), context);
}
UploadSessionView status(UploadId uploadId, RequestContext context) {
return status.handle(new GetUploadStatusQuery(uploadId, context));
}
void cancel(UploadId uploadId, RequestContext context) {
cancel.handle(new CancelUploadCommand(uploadId, context));
}
}