refactor: 리펙토링 진행중 의존성 gradle은 얇게 유지, 각 모듈에서 처리하고 있는 부분에 대해서 리펙토링

This commit is contained in:
donghyeon-ka
2026-09-23 17:27:09 +09:00
parent 60b6a319e7
commit 9da00eb782
2485 changed files with 56091 additions and 23550 deletions
+10
View File
@@ -0,0 +1,10 @@
plugins {
id 'ca.java-library'
}
// Optional fileserver application product. Shared error codes are part of its public failure
// contract, so shared-contract is an explicit API edge rather than an accidental transitive one.
dependencies {
implementation project(':application-core')
implementation project(':shared-contract')
}
@@ -0,0 +1,84 @@
# This is a Gradle generated file for dependency locking.
# Manual edits can break the build and are not advised.
# This file is expected to be part of source control.
com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor
com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,testAnnotationProcessor
com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs
com.github.spotbugs:spotbugs:4.10.2=spotbugs
com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs
com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,testAnnotationProcessor
com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,testAnnotationProcessor
com.google.auto:auto-common:1.2.2=annotationProcessor,testAnnotationProcessor
com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs
com.google.code.gson:gson:2.13.2=spotbugs
com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_annotations:2.41.0=spotbugs
com.google.errorprone:error_prone_annotations:2.47.0=checkstyle
com.google.errorprone:error_prone_annotations:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,testAnnotationProcessor
com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,testAnnotationProcessor
com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.guava:guava:33.5.0-jre=annotationProcessor,testAnnotationProcessor
com.google.guava:guava:33.6.0-jre=checkstyle
com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor
com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor
com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins
com.puppycrawl.tools:checkstyle:13.5.0=checkstyle
commons-beanutils:commons-beanutils:1.11.0=checkstyle
commons-collections:commons-collections:3.2.2=checkstyle
commons-io:commons-io:2.21.0=spotbugs
info.picocli:picocli:4.7.7=checkstyle
io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,testAnnotationProcessor
io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,testAnnotationProcessor
javax.inject:javax.inject:1=annotationProcessor,testAnnotationProcessor
jaxen:jaxen:2.0.6=spotbugs
net.bytebuddy:byte-buddy:1.17.8=testCompileClasspath,testRuntimeClasspath
net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs
org.antlr:antlr4-runtime:4.13.2=checkstyle
org.apache.bcel:bcel:6.12.0=spotbugs
org.apache.commons:commons-lang3:3.20.0=checkstyle,spotbugs
org.apache.commons:commons-text:1.15.0=spotbugs
org.apache.commons:commons-text:1.3=checkstyle
org.apache.httpcomponents:httpclient:4.5.13=checkstyle
org.apache.httpcomponents:httpcore:4.4.16=checkstyle
org.apache.logging.log4j:log4j-api:2.25.5=spotbugs
org.apache.logging.log4j:log4j-core:2.25.5=spotbugs
org.apache.maven.doxia:doxia-core:1.12.0=checkstyle
org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle
org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle
org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle
org.apache.xbean:xbean-reflect:3.7=checkstyle
org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath
org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath
org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle
org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle
org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle
org.codehaus.plexus:plexus-utils:3.3.0=checkstyle
org.dom4j:dom4j:2.2.0=spotbugs
org.javassist:javassist:3.28.0-GA=checkstyle
org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath
org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter-engine:6.0.3=testRuntimeClasspath
org.junit.jupiter:junit-jupiter-params:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.jupiter:junit-jupiter:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-commons:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit.platform:junit-platform-engine:6.0.3=testRuntimeClasspath
org.junit.platform:junit-platform-launcher:6.0.3=testRuntimeClasspath
org.junit:junit-bom:6.0.3=testCompileClasspath,testRuntimeClasspath
org.junit:junit-bom:6.1.0=spotbugs
org.mockito:mockito-core:5.20.0=mockitoAgent
org.opentest4j:opentest4j:1.3.0=testCompileClasspath,testRuntimeClasspath
org.ow2.asm:asm-analysis:9.10.1=spotbugs
org.ow2.asm:asm-commons:9.10.1=spotbugs
org.ow2.asm:asm-tree:9.10.1=spotbugs
org.ow2.asm:asm-util:9.10.1=spotbugs
org.ow2.asm:asm:9.10.1=spotbugs
org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor
org.reflections:reflections:0.10.2=checkstyle
org.slf4j:slf4j-api:2.0.18=spotbugs,spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j
org.slf4j:slf4j-simple:2.0.18=checkstyle
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
empty=compileClasspath,runtimeClasspath
@@ -0,0 +1,12 @@
package dev.caskeleton.application.fileserver.admin;
/**
* Durable sink for administrative actions.
*
* <p>Every mutating admin operation writes here, including the ones that failed: a rejected
* force-delete attempt is exactly the event a reviewer most wants to see.
*/
public interface AdminAuditPort {
void record(AdminAuditRecord record);
}
@@ -0,0 +1,30 @@
package dev.caskeleton.application.fileserver.admin;
import java.time.Instant;
import java.util.Objects;
/**
* One administrative action, recorded for review.
*
* <p>{@code actorFingerprint} is a stable pseudonym rather than a principal id, and no path, mount,
* filename, or raw scanner response ever appears. An audit trail that leaked those would become a
* second copy of exactly the data the rest of the design refuses to disclose.
*/
public record AdminAuditRecord(
String operation,
String reasonCode,
String actorFingerprint,
String traceId,
boolean succeeded,
String subjectId,
Instant occurredAt) {
public AdminAuditRecord {
Objects.requireNonNull(operation, "operation");
Objects.requireNonNull(reasonCode, "reasonCode");
Objects.requireNonNull(actorFingerprint, "actorFingerprint");
Objects.requireNonNull(traceId, "traceId");
Objects.requireNonNull(subjectId, "subjectId");
Objects.requireNonNull(occurredAt, "occurredAt");
}
}
@@ -0,0 +1,17 @@
package dev.caskeleton.application.fileserver.admin;
import dev.caskeleton.application.fileserver.api.ContentKey;
/**
* Answers whether any record still claims a physical object.
*
* <p>An orphan scan walks storage and must decide, per object, whether deleting it would destroy
* live data. That decision belongs to the metadata side, and it is deliberately the only question
* the scan is allowed to ask: a scan that could read records would be tempted to reconstruct them.
*/
@FunctionalInterface
public interface ContentReferenceLedger {
/** True when a file record names {@code key}, in any state. */
boolean isReferenced(ContentKey key);
}
@@ -0,0 +1,270 @@
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.FileNotReadyException;
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
import dev.caskeleton.application.fileserver.api.error.FileserverFailureContext;
import dev.caskeleton.application.fileserver.api.metadata.FileMetadataStore;
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.UploadSessionStore;
import dev.caskeleton.application.fileserver.api.security.FileAccessPolicy;
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.CleanupQueue;
import dev.caskeleton.application.fileserver.cleanup.CleanupRequest;
import dev.caskeleton.application.fileserver.cleanup.CleanupService;
import dev.caskeleton.application.fileserver.cleanup.CleanupType;
import dev.caskeleton.application.fileserver.observability.SafeFileFingerprint;
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 FileMetadataStore metadataStore;
private final UploadSessionStore sessionStore;
private final CleanupQueue cleanupQueue;
private final CleanupService cleanupService;
private final FileAccessPolicy accessPolicy;
private final AdminAuditPort auditPort;
private final SafeFileFingerprint fingerprint;
private final TransactionPort transactions;
private final Clock clock;
public DefaultFileserverAdminService(
StorageHealthPort healthPort,
OrphanScanPort orphanScanPort,
FileMetadataStore metadataStore,
UploadSessionStore sessionStore,
CleanupQueue cleanupQueue,
CleanupService cleanupService,
FileAccessPolicy accessPolicy,
AdminAuditPort auditPort,
SafeFileFingerprint fingerprint,
TransactionPort transactions,
Clock clock) {
this.healthPort = healthPort;
this.orphanScanPort = orphanScanPort;
this.metadataStore = metadataStore;
this.sessionStore = sessionStore;
this.cleanupQueue = cleanupQueue;
this.cleanupService = cleanupService;
this.accessPolicy = accessPolicy;
this.auditPort = auditPort;
this.fingerprint = fingerprint;
this.transactions = transactions;
this.clock = clock;
}
@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 FileNotReadyException(
"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.
transactions.inWrite(
() -> {
FileRecord deleting = metadataStore.markDeleting(record.fileId(), record.version());
deleting
.contentKey()
.ifPresent(
key ->
cleanupQueue.enqueue(
CleanupRequest.forContent(
CleanupType.DELETED_READY_CONTENT, deleting.fileId(), key)));
});
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;
}
private void authorizeRead(RequestContext context) {
accessPolicy.authorize(FileOperation.READ_METADATA, 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)));
}
}
@@ -0,0 +1,34 @@
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,24 @@
package dev.caskeleton.application.fileserver.admin;
import dev.caskeleton.application.fileserver.api.FileId;
import java.util.Objects;
/**
* Operator-forced removal of a file, bypassing the normal precondition.
*
* <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.
*/
public record ForceDeleteCommand(FileId fileId, String reasonCode) {
private static final int MINIMUM_REASON_LENGTH = 8;
public ForceDeleteCommand {
Objects.requireNonNull(fileId, "fileId");
Objects.requireNonNull(reasonCode, "reasonCode");
if (reasonCode.strip().length() < MINIMUM_REASON_LENGTH) {
throw new IllegalArgumentException("force delete requires an explicit reason");
}
}
}
@@ -0,0 +1,31 @@
package dev.caskeleton.application.fileserver.admin;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.UploadId;
import java.time.Instant;
import java.util.Objects;
import java.util.Optional;
/**
* Operator view of an upload that never completed.
*
* <p>The original filename is deliberately absent: an operator triaging stuck uploads needs the
* identity, the offset, and the lease, and a filename is user-supplied content that would put
* arbitrary text into an admin console.
*/
public record IncompleteUploadView(
UploadId uploadId,
FileId fileId,
long committedOffset,
Instant expiresAt,
Optional<String> leaseOwner,
Optional<Instant> leaseUntil) {
public IncompleteUploadView {
Objects.requireNonNull(uploadId, "uploadId");
Objects.requireNonNull(fileId, "fileId");
Objects.requireNonNull(expiresAt, "expiresAt");
Objects.requireNonNull(leaseOwner, "leaseOwner");
Objects.requireNonNull(leaseUntil, "leaseUntil");
}
}
@@ -0,0 +1,24 @@
package dev.caskeleton.application.fileserver.admin;
import dev.caskeleton.application.fileserver.api.ContentKey;
import java.time.Instant;
import java.util.Objects;
/**
* A physical object with no metadata record pointing at it.
*
* <p>{@code fingerprint} is what makes an apply safe: the caller must echo the exact fingerprint it
* was shown, so an object that changed between the scan and the apply is never deleted.
*/
public record OrphanObject(
ContentKey contentKey, long sizeBytes, Instant observedAt, String fingerprint) {
public OrphanObject {
Objects.requireNonNull(contentKey, "contentKey");
Objects.requireNonNull(observedAt, "observedAt");
Objects.requireNonNull(fingerprint, "fingerprint");
if (sizeBytes < 0) {
throw new IllegalArgumentException("sizeBytes must not be negative");
}
}
}
@@ -0,0 +1,40 @@
package dev.caskeleton.application.fileserver.admin;
import java.util.List;
import java.util.Objects;
/**
* Request to reconcile orphaned physical 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.
*/
public record OrphanReconcileCommand(
boolean dryRun,
int limit,
long maxBytes,
List<String> expectedFingerprints,
String reasonCode) {
public OrphanReconcileCommand {
Objects.requireNonNull(expectedFingerprints, "expectedFingerprints");
Objects.requireNonNull(reasonCode, "reasonCode");
if (limit < 1 || maxBytes < 1) {
throw new IllegalArgumentException("limit and maxBytes must be positive");
}
if (!dryRun && expectedFingerprints.isEmpty()) {
throw new IllegalArgumentException(
"an apply must name the fingerprints it intends to remove");
}
if (reasonCode.isBlank()) {
throw new IllegalArgumentException("reasonCode must be non-blank");
}
expectedFingerprints = List.copyOf(expectedFingerprints);
}
/** 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");
}
}
@@ -0,0 +1,26 @@
package dev.caskeleton.application.fileserver.admin;
import java.util.List;
import java.util.Objects;
/**
* Outcome of one reconcile.
*
* <p>{@code dryRun} is echoed back deliberately: an operator reading a report must never have to
* infer whether it described a plan or an action already taken.
*/
public record OrphanReconcileReport(
boolean dryRun,
List<OrphanObject> candidates,
int deleted,
int skippedFingerprintMismatch,
long reclaimedBytes) {
public OrphanReconcileReport {
Objects.requireNonNull(candidates, "candidates");
if (deleted < 0 || skippedFingerprintMismatch < 0 || reclaimedBytes < 0) {
throw new IllegalArgumentException("counters must not be negative");
}
candidates = List.copyOf(candidates);
}
}
@@ -0,0 +1,36 @@
package dev.caskeleton.application.fileserver.admin;
import dev.caskeleton.application.fileserver.api.ContentKey;
import java.util.List;
/**
* Bounded scan for physical objects with no metadata record.
*
* <p>The scan is always bounded; an unbounded walk of a production content root is itself an
* availability incident.
*/
public interface OrphanScanPort {
List<OrphanObject> scan(int limit);
/**
* Retires one orphan, guarded by the fingerprint the caller was shown.
*
* <p>"Retires" rather than "deletes" on purpose. Checking that nothing references an object and
* then unlinking it is not atomic against a record committed in between, and that ordering has no
* safe variant: whichever step runs first, a live object can be destroyed with nothing left to
* restore. The implementation therefore moves the object aside reversibly and re-checks, so a
* record that appeared during the move puts the object straight back.
*
* @return true when the object was retired, false when it was left in place
*/
boolean deleteIfFingerprintMatches(ContentKey key, String expectedFingerprint);
/**
* Reclaims a retired object for good, once nothing references it.
*
* <p>Separated from retirement so the destructive step is a second, later decision rather than
* part of the same racing sequence.
*/
boolean purgeQuarantined(ContentKey key);
}
@@ -0,0 +1,25 @@
package dev.caskeleton.application.fileserver.admin;
import dev.caskeleton.application.fileserver.api.content.ContentStoreCapabilities;
import dev.caskeleton.application.fileserver.api.content.PublishMode;
import java.util.Objects;
/**
* What this deployment can actually do, as proven by the startup probe.
*
* <p>Every flag here came from a real filesystem probe rather than configuration, which is what
* makes the endpoint useful for diagnosing a misconfigured mount. No physical path appears.
*/
public record RuntimeCapabilityReport(
String storageType,
PublishMode publishMode,
ContentStoreCapabilities capabilities,
String filesystemProfile) {
public RuntimeCapabilityReport {
Objects.requireNonNull(storageType, "storageType");
Objects.requireNonNull(publishMode, "publishMode");
Objects.requireNonNull(capabilities, "capabilities");
Objects.requireNonNull(filesystemProfile, "filesystemProfile");
}
}
@@ -0,0 +1,14 @@
package dev.caskeleton.application.fileserver.admin;
/**
* Live capacity and probe observation.
*
* <p>Behind this port sits the same startup probe that gated the application's boot, so the admin
* answer and the startup decision can never disagree.
*/
public interface StorageHealthPort {
StorageHealthReport health();
RuntimeCapabilityReport capabilities();
}
@@ -0,0 +1,30 @@
package dev.caskeleton.application.fileserver.admin;
import java.util.List;
import java.util.Objects;
/**
* Operator view of storage capacity and probe results.
*
* <p>It reports proportions and boolean probe outcomes, never the physical root, the mount, or the
* device. An operator needs to know whether storage is healthy; disclosing where it lives only adds
* a target.
*/
public record StorageHealthReport(
long totalBytes,
long usableBytes,
double usedFraction,
boolean writable,
boolean atomicPublishProven,
String filesystemProfile,
List<String> probeWarnings) {
public StorageHealthReport {
Objects.requireNonNull(filesystemProfile, "filesystemProfile");
Objects.requireNonNull(probeWarnings, "probeWarnings");
if (totalBytes < 0 || usableBytes < 0) {
throw new IllegalArgumentException("byte counters must not be negative");
}
probeWarnings = List.copyOf(probeWarnings);
}
}
@@ -0,0 +1,48 @@
package dev.caskeleton.application.fileserver.api;
/**
* Inclusive byte range over a concrete representation.
*
* <p>HTTP suffix and open-ended ranges are normalized into this value object by the transport range
* resolver, using the current representation length. The core never sees an unresolved range.
*/
public record ByteRange(long startInclusive, long endInclusive) {
public ByteRange {
if (startInclusive < 0 || endInclusive < startInclusive) {
throw new IllegalArgumentException("invalid byte range");
}
}
public static ByteRange of(long startInclusive, long endInclusive) {
return new ByteRange(startInclusive, endInclusive);
}
/** Full-representation range for a non-empty representation. */
public static ByteRange entire(long representationLength) {
if (representationLength <= 0) {
throw new IllegalArgumentException("representation length must be positive");
}
return new ByteRange(0, representationLength - 1);
}
public long length() {
return Math.addExact(Math.subtractExact(endInclusive, startInclusive), 1);
}
public boolean overlaps(ByteRange other) {
return startInclusive <= other.endInclusive && other.startInclusive <= endInclusive;
}
/** True when this range and {@code other} touch or overlap and can be merged into one range. */
public boolean isAdjacentOrOverlapping(ByteRange other) {
return overlaps(other)
|| endInclusive + 1 == other.startInclusive
|| other.endInclusive + 1 == startInclusive;
}
public ByteRange merge(ByteRange other) {
return new ByteRange(
Math.min(startInclusive, other.startInclusive), Math.max(endInclusive, other.endInclusive));
}
}
@@ -0,0 +1,25 @@
package dev.caskeleton.application.fileserver.api;
import java.util.regex.Pattern;
/**
* Server-generated physical content key.
*
* <p>The key is never part of the public HTTP contract and never derives from a client filename.
* The character class deliberately excludes {@code .}, so no traversal or extension-shaped segment
* can survive validation.
*/
public record ContentKey(String value) {
private static final Pattern CANONICAL = Pattern.compile("[a-z0-9/_-]{16,200}");
public ContentKey {
if (value == null || !CANONICAL.matcher(value).matches()) {
throw new IllegalArgumentException("invalid content key");
}
}
public static ContentKey of(String value) {
return new ContentKey(value);
}
}
@@ -0,0 +1,53 @@
package dev.caskeleton.application.fileserver.api;
import java.util.Map;
import java.util.Set;
/**
* Exact transition table from the Fileserver platform design.
*
* <p>Recovery transitions out of {@link FileState#FAILED} are structurally allowed here; the
* recovery policy separately decides whether the stored {@code lastErrorCode} permits them.
*/
public final class DefaultFileStateMachine implements FileStateMachine {
private static final Map<FileState, Set<FileState>> ALLOWED =
Map.ofEntries(
Map.entry(FileState.CREATED, Set.of(FileState.UPLOADING)),
Map.entry(
FileState.UPLOADING,
Set.of(FileState.UPLOADED, FileState.FAILED, FileState.EXPIRED, FileState.DELETING)),
Map.entry(
FileState.UPLOADED,
Set.of(FileState.VERIFYING, FileState.FAILED, FileState.DELETING)),
Map.entry(
FileState.VERIFYING,
Set.of(FileState.READY, FileState.QUARANTINED, FileState.REJECTED, FileState.FAILED)),
Map.entry(
FileState.QUARANTINED,
Set.of(FileState.VERIFYING, FileState.READY, FileState.REJECTED, FileState.DELETING)),
Map.entry(FileState.READY, Set.of(FileState.DELETING)),
Map.entry(FileState.REJECTED, Set.of(FileState.DELETING)),
Map.entry(
FileState.FAILED,
Set.of(
FileState.UPLOADING, FileState.VERIFYING, FileState.DELETING, FileState.EXPIRED)),
Map.entry(FileState.DELETING, Set.of(FileState.DELETED, FileState.FAILED)),
Map.entry(FileState.EXPIRED, Set.of(FileState.DELETING)),
Map.entry(FileState.DELETED, Set.of()));
@Override
public boolean canTransition(FileState current, FileState target) {
if (current == null || target == null) {
return false;
}
return ALLOWED.getOrDefault(current, Set.of()).contains(target);
}
@Override
public void requireTransition(FileState current, FileState target) {
if (!canTransition(current, target)) {
throw new IllegalStateException("illegal file transition: " + current + " -> " + target);
}
}
}
@@ -0,0 +1,31 @@
package dev.caskeleton.application.fileserver.api;
import java.util.Objects;
import java.util.UUID;
/**
* Opaque public identity of a stored file.
*
* <p>The value is hard to guess but is never treated as a bearer secret: every public operation
* still runs the authorization hook. It never encodes a path, a physical key, or an original
* filename.
*/
public record FileId(UUID value) {
public FileId {
Objects.requireNonNull(value, "value");
}
public static FileId of(UUID value) {
return new FileId(value);
}
public static FileId parse(String canonicalText) {
Objects.requireNonNull(canonicalText, "canonicalText");
return new FileId(UUID.fromString(canonicalText));
}
public String canonicalText() {
return value.toString();
}
}
@@ -0,0 +1,31 @@
package dev.caskeleton.application.fileserver.api;
/**
* Authoritative lifecycle state of a file record.
*
* <p>Only {@link #READY} exposes readable immutable content. Every other state is excluded from
* direct download and from delegated (Nginx) transfer.
*/
public enum FileState {
CREATED,
UPLOADING,
UPLOADED,
VERIFYING,
QUARANTINED,
READY,
REJECTED,
FAILED,
DELETING,
DELETED,
EXPIRED;
/** True when the state permits public download authorization. */
public boolean isPubliclyReadable() {
return this == READY;
}
/** True when no further lifecycle progress is possible through the public API. */
public boolean isTerminal() {
return this == DELETED;
}
}
@@ -0,0 +1,14 @@
package dev.caskeleton.application.fileserver.api;
/**
* Single authority for allowed file lifecycle transitions.
*
* <p>Persistence adapters and transport adapters never assign {@link FileState} directly; they ask
* this contract first so an illegal transition cannot enter the metadata store.
*/
public interface FileStateMachine {
void requireTransition(FileState current, FileState target);
boolean canTransition(FileState current, FileState target);
}
@@ -0,0 +1,23 @@
package dev.caskeleton.application.fileserver.api;
import java.util.regex.Pattern;
/**
* Logical storage and ownership namespace.
*
* <p>A namespace is a metadata grouping only. It is never a directory, a mount, or a bucket name.
*/
public record StorageNamespace(String value) {
private static final Pattern CANONICAL = Pattern.compile("[a-z][a-z0-9-]{1,62}");
public StorageNamespace {
if (value == null || !CANONICAL.matcher(value).matches()) {
throw new IllegalArgumentException("invalid storage namespace");
}
}
public static StorageNamespace of(String value) {
return new StorageNamespace(value);
}
}
@@ -0,0 +1,30 @@
package dev.caskeleton.application.fileserver.api;
import java.util.Objects;
import java.util.UUID;
/**
* Opaque public identity of a resumable upload resource.
*
* <p>An upload resource has a lifecycle independent of the READY file it eventually produces, so
* the two identities are never interchangeable.
*/
public record UploadId(UUID value) {
public UploadId {
Objects.requireNonNull(value, "value");
}
public static UploadId of(UUID value) {
return new UploadId(value);
}
public static UploadId parse(String canonicalText) {
Objects.requireNonNull(canonicalText, "canonicalText");
return new UploadId(UUID.fromString(canonicalText));
}
public String canonicalText() {
return value.toString();
}
}
@@ -0,0 +1,19 @@
package dev.caskeleton.application.fileserver.api.content;
import java.util.Objects;
/**
* Outcome of one durable append.
*
* <p>{@code committedOffset} only advances by bytes the store observed reaching the channel, so a
* partial write can never inflate the resumable offset.
*/
public record AppendResult(long committedOffset, long appendedBytes, String sha256) {
public AppendResult {
if (committedOffset < 0 || appendedBytes < 0) {
throw new IllegalArgumentException("append offsets must not be negative");
}
Objects.requireNonNull(sha256, "sha256");
}
}
@@ -0,0 +1,32 @@
package dev.caskeleton.application.fileserver.api.content;
import dev.caskeleton.application.fileserver.api.ByteRange;
import dev.caskeleton.application.fileserver.api.ContentKey;
import java.nio.ByteBuffer;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.Flow;
/**
* Non-blocking storage SPI with the same semantics as {@link BlockingContentStore}.
*
* <p>Streaming uses {@link Flow.Publisher} of {@link ByteBuffer} so the core stays free of Reactor
* and Spring buffer types; the WebFlux adapter owns the conversion and the pooled-buffer lifecycle.
*/
public interface AsyncContentStore {
CompletionStage<UploadHandle> createUpload(CreateContentCommand command);
CompletionStage<AppendResult> append(
UploadHandle handle, long expectedOffset, Flow.Publisher<ByteBuffer> content);
CompletionStage<StoredContent> finalizeUpload(
UploadHandle handle, FinalizeContentCommand command);
CompletionStage<ContentMetadata> stat(ContentKey key);
Flow.Publisher<ByteBuffer> openRead(ContentKey key, ByteRange range);
CompletionStage<DeleteResult> delete(ContentKey key, DeletePrecondition precondition);
ContentStoreCapabilities capabilities();
}
@@ -0,0 +1,47 @@
package dev.caskeleton.application.fileserver.api.content;
import dev.caskeleton.application.fileserver.api.ByteRange;
import dev.caskeleton.application.fileserver.api.ContentKey;
import java.nio.channels.ReadableByteChannel;
/**
* Blocking storage SPI shared by every content store implementation.
*
* <p>The contract is deliberately expressed as create / append / finalize / stat / openRead /
* delete semantics rather than as a mirror of filesystem commands. No signature may name a {@code
* Path}, a Spring {@code Resource}, a {@code DataBuffer}, a Reactor type, or a provider SDK type.
*/
public interface BlockingContentStore {
UploadHandle createUpload(CreateContentCommand command);
/**
* Appends under a fence that is re-checked as the transfer proceeds.
*
* <p>The fence is a parameter rather than store state because ownership belongs to the caller's
* lease, not to the object: the store knows how to stop writing, but only the caller knows when
* it has lost the right to.
*/
AppendResult append(
UploadHandle handle,
long expectedOffset,
ReadableByteChannel source,
long contentLength,
WriteFence fence);
/** Appends with no ownership to lose; see {@link WriteFence#unfenced()}. */
default AppendResult append(
UploadHandle handle, long expectedOffset, ReadableByteChannel source, long contentLength) {
return append(handle, expectedOffset, source, contentLength, WriteFence.unfenced());
}
StoredContent finalizeUpload(UploadHandle handle, FinalizeContentCommand command);
ContentMetadata stat(ContentKey key);
ReadableByteChannel openRead(ContentKey key, ByteRange range);
DeleteResult delete(ContentKey key, DeletePrecondition precondition);
ContentStoreCapabilities capabilities();
}
@@ -0,0 +1,12 @@
package dev.caskeleton.application.fileserver.api.content;
/**
* Optional capacity reporting used by admission control and the admin plane.
*
* <p>Stores that cannot answer capacity simply do not implement this interface; the high-water
* guards then degrade to reservation-only accounting.
*/
public interface CapacityAwareContentStore {
StorageCapacity capacity();
}
@@ -0,0 +1,22 @@
package dev.caskeleton.application.fileserver.api.content;
import dev.caskeleton.application.fileserver.api.ContentKey;
import java.time.Instant;
import java.util.Objects;
/**
* Physical observation of a stored object.
*
* <p>This is used for publish verification and reconciliation only. It is never the source of
* public metadata, and its timestamp is never served as {@code Last-Modified}.
*/
public record ContentMetadata(ContentKey contentKey, long size, Instant lastModified) {
public ContentMetadata {
Objects.requireNonNull(contentKey, "contentKey");
Objects.requireNonNull(lastModified, "lastModified");
if (size < 0) {
throw new IllegalArgumentException("size must not be negative");
}
}
}
@@ -0,0 +1,22 @@
package dev.caskeleton.application.fileserver.api.content;
/**
* Runtime capabilities of a content store, produced by a real startup probe.
*
* <p>These flags are never read from configuration alone: the local adapter proves each one against
* the configured storage root before the application accepts traffic.
*/
public record ContentStoreCapabilities(
boolean rangedRead,
boolean atomicCreate,
boolean atomicPublish,
boolean conditionalWrite,
boolean serverSideCopy,
boolean delegatedDownload,
boolean resumableAppend) {
/** Capability set with every optional feature disabled. */
public static ContentStoreCapabilities none() {
return new ContentStoreCapabilities(false, false, false, false, false, false, false);
}
}
@@ -0,0 +1,16 @@
package dev.caskeleton.application.fileserver.api.content;
import dev.caskeleton.application.fileserver.api.ContentKey;
import java.util.concurrent.CompletionStage;
/**
* Optional server-side copy capability.
*
* <p>Stores without it fall back to an application-level stream copy. Automatic rollback of a
* failed copy is never promised; an incomplete target goes to the cleanup queue.
*/
public interface CopyCapableContentStore {
CompletionStage<StoredContent> copy(
ContentKey source, ContentKey target, CopyPrecondition precondition);
}
@@ -0,0 +1,19 @@
package dev.caskeleton.application.fileserver.api.content;
/**
* Conditions a server-side copy must satisfy.
*
* <p>The default is create-only: an existing target is a failure, never a silent overwrite.
*/
public record CopyPrecondition(boolean createOnly) {
/** Create-only copy, the Fileserver default. */
public static CopyPrecondition requireCreateOnly() {
return new CopyPrecondition(true);
}
/** Conditional replace, reachable only from a path that already validated a precondition. */
public static CopyPrecondition allowConditionalReplace() {
return new CopyPrecondition(false);
}
}
@@ -0,0 +1,32 @@
package dev.caskeleton.application.fileserver.api.content;
import dev.caskeleton.application.fileserver.api.StorageNamespace;
import dev.caskeleton.application.fileserver.api.UploadId;
import java.util.Objects;
import java.util.OptionalLong;
/**
* Request to create a new staging object.
*
* <p>The command carries no client filename: the physical object is named from server-generated
* identity only. {@code expectedLength} is advisory and is re-verified against the bytes that are
* actually written.
*/
public record CreateContentCommand(
UploadId uploadId,
StorageNamespace namespace,
OptionalLong expectedLength,
long maximumLength) {
public CreateContentCommand {
Objects.requireNonNull(uploadId, "uploadId");
Objects.requireNonNull(namespace, "namespace");
Objects.requireNonNull(expectedLength, "expectedLength");
if (maximumLength <= 0) {
throw new IllegalArgumentException("maximumLength must be positive");
}
if (expectedLength.isPresent() && expectedLength.getAsLong() < 0) {
throw new IllegalArgumentException("expectedLength must not be negative");
}
}
}
@@ -0,0 +1,23 @@
package dev.caskeleton.application.fileserver.api.content;
import java.time.Duration;
import java.util.Objects;
/**
* Internal descriptor a front proxy consumes to perform the actual transfer.
*
* <p>{@code internalUri} is always relative and always below the configured internal prefix.
*/
public record DelegatedDownloadDescriptor(String internalUri, Duration ttl) {
public DelegatedDownloadDescriptor {
Objects.requireNonNull(internalUri, "internalUri");
Objects.requireNonNull(ttl, "ttl");
if (!internalUri.startsWith("/") || internalUri.contains("..")) {
throw new IllegalArgumentException("internal uri must be a relative-rooted safe path");
}
if (ttl.isNegative() || ttl.isZero()) {
throw new IllegalArgumentException("ttl must be positive");
}
}
}
@@ -0,0 +1,18 @@
package dev.caskeleton.application.fileserver.api.content;
import dev.caskeleton.application.fileserver.api.ByteRange;
import dev.caskeleton.application.fileserver.api.ContentKey;
import java.time.Duration;
import java.util.Optional;
/**
* Optional capability to hand a transfer to a front proxy instead of streaming it in-process.
*
* <p>The descriptor is a validated relative internal URI. It never contains an absolute physical
* path, and issuing a publicly signed URL is out of scope for this store family.
*/
public interface DelegatedDownloadStore {
DelegatedDownloadDescriptor createDelegation(
ContentKey key, Optional<ByteRange> range, Duration ttl);
}
@@ -0,0 +1,32 @@
package dev.caskeleton.application.fileserver.api.content;
import java.util.Objects;
import java.util.Optional;
import java.util.OptionalLong;
/**
* Conditions a physical delete must satisfy before it runs.
*
* <p>Cleanup never deletes an object whose observed size or digest disagrees with the record that
* scheduled the deletion.
*/
public record DeletePrecondition(OptionalLong expectedSize, Optional<String> expectedSha256) {
public DeletePrecondition {
Objects.requireNonNull(expectedSize, "expectedSize");
Objects.requireNonNull(expectedSha256, "expectedSha256");
}
/** Unconditional delete, used only where the caller already proved ownership. */
public static DeletePrecondition none() {
return new DeletePrecondition(OptionalLong.empty(), Optional.empty());
}
public static DeletePrecondition ofSize(long expectedSize) {
return new DeletePrecondition(OptionalLong.of(expectedSize), Optional.empty());
}
public static DeletePrecondition ofSizeAndDigest(long expectedSize, String expectedSha256) {
return new DeletePrecondition(OptionalLong.of(expectedSize), Optional.of(expectedSha256));
}
}
@@ -0,0 +1,24 @@
package dev.caskeleton.application.fileserver.api.content;
/**
* Outcome of a physical delete.
*
* <p>A delete of an object that is already gone is an idempotent success, but it is reported with
* {@code alreadyAbsent} so reconciliation can record the divergence.
*/
public record DeleteResult(boolean deleted, boolean alreadyAbsent, long reclaimedBytes) {
public DeleteResult {
if (reclaimedBytes < 0) {
throw new IllegalArgumentException("reclaimedBytes must not be negative");
}
}
public static DeleteResult removed(long reclaimedBytes) {
return new DeleteResult(true, false, reclaimedBytes);
}
public static DeleteResult alreadyGone() {
return new DeleteResult(true, true, 0);
}
}
@@ -0,0 +1,24 @@
package dev.caskeleton.application.fileserver.api.content;
import java.util.Objects;
import java.util.Optional;
import java.util.OptionalLong;
/**
* Request to turn a completed staging object into immutable published content.
*
* <p>{@code expectedSha256} is the digest the server computed while streaming, not a client
* assertion. The store re-verifies length and digest before it exposes anything.
*/
public record FinalizeContentCommand(
OptionalLong expectedLength,
Optional<String> expectedSha256,
PublishMode publishMode,
boolean forceDurable) {
public FinalizeContentCommand {
Objects.requireNonNull(expectedLength, "expectedLength");
Objects.requireNonNull(expectedSha256, "expectedSha256");
Objects.requireNonNull(publishMode, "publishMode");
}
}
@@ -0,0 +1,14 @@
package dev.caskeleton.application.fileserver.api.content;
/**
* How a completed upload becomes publicly visible.
*
* <p>{@link #ATOMIC_MOVE_PREFERRED} is the default: use a same-FileStore atomic move when the probe
* proves it works, otherwise fall back to publishing a metadata pointer to an already-complete
* immutable object.
*/
public enum PublishMode {
ATOMIC_MOVE_REQUIRED,
ATOMIC_MOVE_PREFERRED,
METADATA_POINTER
}
@@ -0,0 +1,23 @@
package dev.caskeleton.application.fileserver.api.content;
/**
* Usable and total bytes of a storage pool.
*
* <p>Neither value identifies a mount point or a physical root.
*/
public record StorageCapacity(long usableBytes, long totalBytes) {
public StorageCapacity {
if (usableBytes < 0 || totalBytes < 0 || usableBytes > totalBytes) {
throw new IllegalArgumentException("invalid storage capacity");
}
}
/** Fraction of the pool already consumed, in the closed interval zero to one. */
public double usedFraction() {
if (totalBytes == 0) {
return 0;
}
return (double) (totalBytes - usableBytes) / (double) totalBytes;
}
}
@@ -0,0 +1,22 @@
package dev.caskeleton.application.fileserver.api.content;
import dev.caskeleton.application.fileserver.api.ContentKey;
import java.util.Objects;
/**
* Immutable content that a store has finished publishing.
*
* <p>Publication here means the physical object is complete and verified; the file becomes publicly
* readable only once the metadata store commits the READY transition.
*/
public record StoredContent(
ContentKey contentKey, long size, String sha256, boolean atomicMoveUsed) {
public StoredContent {
Objects.requireNonNull(contentKey, "contentKey");
Objects.requireNonNull(sha256, "sha256");
if (size < 0) {
throw new IllegalArgumentException("size must not be negative");
}
}
}
@@ -0,0 +1,34 @@
package dev.caskeleton.application.fileserver.api.content;
import dev.caskeleton.application.fileserver.api.StorageNamespace;
import dev.caskeleton.application.fileserver.api.UploadId;
import java.util.Objects;
/**
* Opaque handle to an in-progress staging object held by a content store.
*
* <p>The handle never exposes a path. Adapters that need physical detail keep it in their own
* package-private subtype and downcast internally.
*/
public interface UploadHandle {
UploadId uploadId();
StorageNamespace namespace();
/**
* Store-specific opaque token that lets the same store re-attach to the staging object after a
* restart. It is never returned to a client.
*/
String stagingToken();
/** Throws when {@code handle} was produced by a different content store implementation. */
static <T extends UploadHandle> T requireOwn(UploadHandle handle, Class<T> ownType) {
Objects.requireNonNull(handle, "handle");
if (!ownType.isInstance(handle)) {
throw new IllegalArgumentException(
"upload handle was not produced by " + ownType.getSimpleName());
}
return ownType.cast(handle);
}
}
@@ -0,0 +1,35 @@
package dev.caskeleton.application.fileserver.api.content;
/**
* Permission to keep writing, re-checked while a transfer is still in flight.
*
* <p>An upload holds a writer lease that is granted once and expires on a timer, but the transfer
* it authorizes can run for minutes. Checking ownership only at the start leaves the interval where
* a slow writer's lease lapses, another node takes it over, and both are appending to the same
* staging object — with the loser's bytes landing at offsets the winner never accounted for.
*
* <p>The store therefore re-asks between buffers rather than trusting the initial grant. A refusal
* aborts the transfer before the next write, and the store's own rollback returns the object to the
* offset the append started from, so a fenced-out writer leaves no trace on the volume.
*/
@FunctionalInterface
public interface WriteFence {
/**
* Confirms this writer may still mutate the physical object.
*
* @throws dev.caskeleton.application.fileserver.api.error.FileserverException when ownership was
* lost; the caller must not write again
*/
void requireStillOwned();
/**
* A fence that never refuses.
*
* <p>For call sites with no ownership to lose — a contract test driving the store directly, or a
* copy between two objects only this thread can reach.
*/
static WriteFence unfenced() {
return () -> {};
}
}
@@ -0,0 +1,41 @@
package dev.caskeleton.application.fileserver.api.error;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.UploadId;
/**
* The operation may or may not have taken effect and the server cannot decide which.
*
* <p>Typical causes are a lost rename response on a network filesystem, a vanished mount after a
* successful force, and a missing database commit acknowledgement. This failure is never downgraded
* to a retryable error and never blind-retried: it always carries {@code reconciliationRequired}.
*/
public final class AmbiguousCompletionException extends FileserverException {
private static final long serialVersionUID = 1L;
public AmbiguousCompletionException(String message, FileserverFailureContext context) {
super(message, context);
}
public AmbiguousCompletionException(
String message, Throwable cause, FileserverFailureContext context) {
super(message, cause, context);
}
/** Ambiguous outcome for an upload resource. */
public static AmbiguousCompletionException forUpload(String message, UploadId uploadId) {
return new AmbiguousCompletionException(
message,
FileserverFailureContext.forUpload(
FileserverErrorCode.AMBIGUOUS_COMPLETION, uploadId, false, true, true));
}
/** Ambiguous outcome for a file record, typically a publish or metadata commit. */
public static AmbiguousCompletionException forFile(String message, FileId fileId) {
return new AmbiguousCompletionException(
message,
FileserverFailureContext.forFile(FileserverErrorCode.AMBIGUOUS_COMPLETION, fileId, false)
.ambiguousRequiringReconciliation());
}
}
@@ -0,0 +1,23 @@
package dev.caskeleton.application.fileserver.api.error;
/** Atomic publish was required by configuration but the storage probe proved it unavailable. */
public final class AtomicPublishUnsupportedException extends FileserverException {
private static final long serialVersionUID = 1L;
public AtomicPublishUnsupportedException(String message, FileserverFailureContext context) {
super(message, context);
}
public AtomicPublishUnsupportedException(
String message, Throwable cause, FileserverFailureContext context) {
super(message, cause, context);
}
/** Failure with no file or upload correlation. */
public static AtomicPublishUnsupportedException of(String message) {
return new AtomicPublishUnsupportedException(
message,
FileserverFailureContext.of(FileserverErrorCode.ATOMIC_PUBLISH_UNSUPPORTED, false));
}
}
@@ -0,0 +1,22 @@
package dev.caskeleton.application.fileserver.api.error;
/** An optimistic version or writer-lease precondition lost to a concurrent writer. */
public final class ConcurrentFileModificationException extends FileserverException {
private static final long serialVersionUID = 1L;
public ConcurrentFileModificationException(String message, FileserverFailureContext context) {
super(message, context);
}
public ConcurrentFileModificationException(
String message, Throwable cause, FileserverFailureContext context) {
super(message, cause, context);
}
/** Failure with no file or upload correlation. */
public static ConcurrentFileModificationException of(String message) {
return new ConcurrentFileModificationException(
message, FileserverFailureContext.of(FileserverErrorCode.CONCURRENT_MODIFICATION, true));
}
}
@@ -0,0 +1,22 @@
package dev.caskeleton.application.fileserver.api.error;
/** The injected access policy denied the operation before any quota or storage mutation. */
public final class FileAccessDeniedException extends FileserverException {
private static final long serialVersionUID = 1L;
public FileAccessDeniedException(String message, FileserverFailureContext context) {
super(message, context);
}
public FileAccessDeniedException(
String message, Throwable cause, FileserverFailureContext context) {
super(message, cause, context);
}
/** Failure with no file or upload correlation. */
public static FileAccessDeniedException of(String message) {
return new FileAccessDeniedException(
message, FileserverFailureContext.of(FileserverErrorCode.ACCESS_DENIED, false));
}
}
@@ -0,0 +1,22 @@
package dev.caskeleton.application.fileserver.api.error;
/** Create-only target already exists; the server never silently overwrites. */
public final class FileAlreadyExistsException extends FileserverException {
private static final long serialVersionUID = 1L;
public FileAlreadyExistsException(String message, FileserverFailureContext context) {
super(message, context);
}
public FileAlreadyExistsException(
String message, Throwable cause, FileserverFailureContext context) {
super(message, cause, context);
}
/** Failure with no file or upload correlation. */
public static FileAlreadyExistsException of(String message) {
return new FileAlreadyExistsException(
message, FileserverFailureContext.of(FileserverErrorCode.FILE_ALREADY_EXISTS, false));
}
}
@@ -0,0 +1,24 @@
package dev.caskeleton.application.fileserver.api.error;
/**
* Requested file identity does not exist, or existence hiding decided the caller may not learn that
* it does.
*/
public final class FileNotFoundException extends FileserverException {
private static final long serialVersionUID = 1L;
public FileNotFoundException(String message, FileserverFailureContext context) {
super(message, context);
}
public FileNotFoundException(String message, Throwable cause, FileserverFailureContext context) {
super(message, cause, context);
}
/** Failure with no file or upload correlation. */
public static FileNotFoundException of(String message) {
return new FileNotFoundException(
message, FileserverFailureContext.of(FileserverErrorCode.FILE_NOT_FOUND, false));
}
}
@@ -0,0 +1,27 @@
package dev.caskeleton.application.fileserver.api.error;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.FileState;
/**
* The file exists but is not in {@link FileState#READY}, so no byte may be served.
*
* <p>This gate is evaluated before any content handle is opened and applies identically to direct
* transfer and to delegated (Nginx) transfer.
*/
public final class FileNotReadyException extends FileserverException {
private static final long serialVersionUID = 1L;
public FileNotReadyException(String message, FileserverFailureContext context) {
super(message, context);
}
/** Gate failure carrying the observed non-READY state. */
public static FileNotReadyException of(FileId fileId, FileState currentState) {
return new FileNotReadyException(
"file is not readable in state " + currentState,
FileserverFailureContext.forFileState(
FileserverErrorCode.FILE_NOT_READY, fileId, currentState, false));
}
}
@@ -0,0 +1,21 @@
package dev.caskeleton.application.fileserver.api.error;
/** The declared or streamed byte count exceeded the configured maximum. */
public final class FileTooLargeException extends FileserverException {
private static final long serialVersionUID = 1L;
public FileTooLargeException(String message, FileserverFailureContext context) {
super(message, context);
}
public FileTooLargeException(String message, Throwable cause, FileserverFailureContext context) {
super(message, cause, context);
}
/** Failure with no file or upload correlation. */
public static FileTooLargeException of(String message) {
return new FileTooLargeException(
message, FileserverFailureContext.of(FileserverErrorCode.FILE_TOO_LARGE, false));
}
}
@@ -0,0 +1,98 @@
package dev.caskeleton.application.fileserver.api.error;
import dev.caskeleton.shared.error.ApiErrorCode;
import dev.caskeleton.shared.error.Category;
import java.util.Locale;
/**
* Stable Fileserver failure vocabulary shared by every transport adapter.
*
* <p>Implements the repository-wide {@link ApiErrorCode} contract rather than parallelling it. The
* enum already carried a status and a retryability notion of its own, in its own shape, so a caller
* that handles {@code ApiErrorCode} uniformly — the envelope writer, the error registry contract
* tests, a fork's own handler — silently did not cover Fileserver failures. Same information,
* inside the contract instead of beside it.
*
* <p>The status stays here, on the code, for the reason {@link ApiErrorCode} gives: it is a plain
* integer, never a framework status type, so the module holding it stays framework-neutral and the
* servlet transport, the reactive transport and the Nginx delegation path cannot answer the same
* failure three different ways.
*
* <p>The URN is the {@code type} member of the emitted problem detail and has no counterpart in the
* shared contract, so it remains Fileserver-specific.
*/
public enum FileserverErrorCode implements ApiErrorCode {
BAD_REQUEST(400, Category.VALIDATION, false),
UNAUTHENTICATED(401, Category.AUTH, false),
ACCESS_DENIED(403, Category.AUTHZ, false),
FILE_NOT_FOUND(404, Category.NOT_FOUND, false),
FILE_ALREADY_EXISTS(409, Category.CONFLICT, false),
FILE_NOT_READY(409, Category.CONFLICT, true),
UPLOAD_OFFSET_MISMATCH(409, Category.CONFLICT, true),
CONCURRENT_MODIFICATION(409, Category.CONFLICT, true),
UPLOAD_EXPIRED(410, Category.CONFLICT, false),
CONTENT_LENGTH_REQUIRED(411, Category.VALIDATION, false),
PRECONDITION_FAILED(412, Category.CONFLICT, false),
FILE_TOO_LARGE(413, Category.VALIDATION, false),
QUOTA_EXCEEDED(413, Category.CONFLICT, false),
UNSUPPORTED_MEDIA_TYPE(415, Category.VALIDATION, false),
RANGE_NOT_SATISFIABLE(416, Category.VALIDATION, false),
INTEGRITY_MISMATCH(422, Category.DATA_INTEGRITY, false),
MALWARE_DETECTED(422, Category.DATA_INTEGRITY, false),
INVALID_PATH(422, Category.VALIDATION, false),
PATH_OUTSIDE_NAMESPACE(422, Category.VALIDATION, false),
TRANSFER_ADMISSION_REJECTED(429, Category.RATE_LIMIT, true),
PARTIAL_WRITE(500, Category.TRANSIENT_DEPENDENCY, false),
// Never retryable by definition: the operation may already have taken effect, and a blind retry
// is what turns an ambiguous outcome into a duplicated one.
AMBIGUOUS_COMPLETION(500, Category.DATA_INTEGRITY, false),
ATOMIC_PUBLISH_UNSUPPORTED(503, Category.PERMANENT_DEPENDENCY, false),
STORAGE_UNAVAILABLE(503, Category.TRANSIENT_DEPENDENCY, true),
TRANSFER_TIMEOUT(504, Category.TRANSIENT_DEPENDENCY, true),
STORAGE_FULL(507, Category.TRANSIENT_DEPENDENCY, false);
private static final String PROBLEM_TYPE_PREFIX = "urn:fileserver:problem:";
private final int httpStatus;
private final Category category;
private final boolean retryable;
FileserverErrorCode(int httpStatus, Category category, boolean retryable) {
this.httpStatus = httpStatus;
this.category = category;
this.retryable = retryable;
}
@Override
public String code() {
return name();
}
@Override
public Category category() {
return category;
}
/** Design §19.3 status for this failure; identical across MVC, WebFlux, and Nginx delegation. */
@Override
public int httpStatus() {
return httpStatus;
}
/**
* Whether the same call may succeed on retry, as a property of the code.
*
* <p>Distinct from {@link FileserverFailureContext#retryable()}, which is what the server decided
* about one particular occurrence. This is the ceiling: a code that is never retryable cannot be
* made retryable by a context, and a client that only sees the code still gets a safe answer.
*/
@Override
public boolean retryable() {
return retryable;
}
/** Problem-detail {@code type} URN, for example {@code urn:fileserver:problem:file-not-found}. */
public String problemType() {
return PROBLEM_TYPE_PREFIX + name().toLowerCase(Locale.ROOT).replace('_', '-');
}
}
@@ -0,0 +1,35 @@
package dev.caskeleton.application.fileserver.api.error;
import java.util.Objects;
/**
* Root of the stable Fileserver failure hierarchy.
*
* <p>Transport adapters map these failures through {@link #context()} alone; they never inspect a
* storage-driver or JDBC exception. {@link #getMessage()} is server-log-only and must never be
* copied into a client response body.
*/
public abstract class FileserverException extends RuntimeException {
private static final long serialVersionUID = 1L;
private final transient FileserverFailureContext context;
protected FileserverException(String message, FileserverFailureContext context) {
super(message);
this.context = Objects.requireNonNull(context, "context");
}
protected FileserverException(String message, Throwable cause, FileserverFailureContext context) {
super(message, cause);
this.context = Objects.requireNonNull(context, "context");
}
public final FileserverFailureContext context() {
return context;
}
public final FileserverErrorCode code() {
return context.code();
}
}
@@ -0,0 +1,152 @@
package dev.caskeleton.application.fileserver.api.error;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.FileState;
import dev.caskeleton.application.fileserver.api.UploadId;
import java.util.Objects;
import java.util.Optional;
import java.util.OptionalLong;
/**
* Machine-readable failure metadata attached to every {@link FileserverException}.
*
* <p>{@code ambiguous} means the operation may have taken effect on the storage or metadata side
* even though no success was observed; such a failure is never downgraded to a plain retryable
* error. The context never carries a physical path, a mount, a scanner credential, or a filename.
*/
public record FileserverFailureContext(
FileserverErrorCode code,
boolean retryable,
boolean ambiguous,
boolean reconciliationRequired,
Optional<FileId> fileId,
Optional<UploadId> uploadId,
OptionalLong expectedOffset,
OptionalLong currentOffset,
Optional<FileState> currentState) {
public FileserverFailureContext {
Objects.requireNonNull(code, "code");
Objects.requireNonNull(fileId, "fileId");
Objects.requireNonNull(uploadId, "uploadId");
Objects.requireNonNull(expectedOffset, "expectedOffset");
Objects.requireNonNull(currentOffset, "currentOffset");
Objects.requireNonNull(currentState, "currentState");
}
/** Failure with no file, upload, or offset correlation. */
public static FileserverFailureContext of(FileserverErrorCode code, boolean retryable) {
return new FileserverFailureContext(
code,
retryable,
false,
false,
Optional.empty(),
Optional.empty(),
OptionalLong.empty(),
OptionalLong.empty(),
Optional.empty());
}
/** Failure correlated to a file, optionally reporting the observed state. */
public static FileserverFailureContext forFile(
FileserverErrorCode code, FileId fileId, boolean retryable) {
return new FileserverFailureContext(
code,
retryable,
false,
false,
Optional.of(fileId),
Optional.empty(),
OptionalLong.empty(),
OptionalLong.empty(),
Optional.empty());
}
/** Failure correlated to a file whose observed lifecycle state matters to the caller. */
public static FileserverFailureContext forFileState(
FileserverErrorCode code, FileId fileId, FileState currentState, boolean retryable) {
return new FileserverFailureContext(
code,
retryable,
false,
false,
Optional.of(fileId),
Optional.empty(),
OptionalLong.empty(),
OptionalLong.empty(),
Optional.of(currentState));
}
/** Failure correlated to an upload resource, including the ambiguity and reconciliation flags. */
public static FileserverFailureContext forUpload(
FileserverErrorCode code,
UploadId uploadId,
boolean retryable,
boolean ambiguous,
boolean reconciliationRequired) {
return new FileserverFailureContext(
code,
retryable,
ambiguous,
reconciliationRequired,
Optional.empty(),
Optional.of(uploadId),
OptionalLong.empty(),
OptionalLong.empty(),
Optional.empty());
}
/** Offset conflict reporting both the expected and the durably committed offset. */
public static FileserverFailureContext forOffset(
FileserverErrorCode code, long expectedOffset, long currentOffset) {
return new FileserverFailureContext(
code,
true,
false,
false,
Optional.empty(),
Optional.empty(),
OptionalLong.of(expectedOffset),
OptionalLong.of(currentOffset),
Optional.empty());
}
/** Same context with the upload correlation filled in. */
public FileserverFailureContext withUpload(UploadId uploadId) {
return new FileserverFailureContext(
code,
retryable,
ambiguous,
reconciliationRequired,
fileId,
Optional.of(uploadId),
expectedOffset,
currentOffset,
currentState);
}
/**
* Same context re-marked as an ambiguous outcome that must go through reconciliation.
*
* <p>An ambiguous failure is never retryable: the operation may already have taken effect.
*/
public FileserverFailureContext ambiguousRequiringReconciliation() {
return new FileserverFailureContext(
code, false, true, true, fileId, uploadId, expectedOffset, currentOffset, currentState);
}
/** Same context with the file correlation filled in. */
public FileserverFailureContext withFile(FileId fileId) {
return new FileserverFailureContext(
code,
retryable,
ambiguous,
reconciliationRequired,
Optional.of(fileId),
uploadId,
expectedOffset,
currentOffset,
currentState);
}
}
@@ -0,0 +1,22 @@
package dev.caskeleton.application.fileserver.api.error;
/** The server-computed size or SHA-256 disagreed with the value the client asserted. */
public final class IntegrityMismatchException extends FileserverException {
private static final long serialVersionUID = 1L;
public IntegrityMismatchException(String message, FileserverFailureContext context) {
super(message, context);
}
public IntegrityMismatchException(
String message, Throwable cause, FileserverFailureContext context) {
super(message, cause, context);
}
/** Failure with no file or upload correlation. */
public static IntegrityMismatchException of(String message) {
return new IntegrityMismatchException(
message, FileserverFailureContext.of(FileserverErrorCode.INTEGRITY_MISMATCH, false));
}
}
@@ -0,0 +1,21 @@
package dev.caskeleton.application.fileserver.api.error;
/** A server-generated key or internal descriptor failed its structural validation. */
public final class InvalidPathException extends FileserverException {
private static final long serialVersionUID = 1L;
public InvalidPathException(String message, FileserverFailureContext context) {
super(message, context);
}
public InvalidPathException(String message, Throwable cause, FileserverFailureContext context) {
super(message, cause, context);
}
/** Failure with no file or upload correlation. */
public static InvalidPathException of(String message) {
return new InvalidPathException(
message, FileserverFailureContext.of(FileserverErrorCode.INVALID_PATH, false));
}
}
@@ -0,0 +1,28 @@
package dev.caskeleton.application.fileserver.api.error;
/**
* A request's headers or their combination are not valid for the operation.
*
* <p>This is separate from {@link UnsupportedMediaTypeException} on purpose: a missing request
* invariant version and an unsupported content type are different failures, and collapsing them
* would make the emitted code disagree with the exception a reader sees in a stack trace.
*/
public final class MalformedRequestException extends FileserverException {
private static final long serialVersionUID = 1L;
public MalformedRequestException(String message, FileserverFailureContext context) {
super(message, context);
}
public MalformedRequestException(
String message, Throwable cause, FileserverFailureContext context) {
super(message, cause, context);
}
/** Failure with no file or upload correlation. */
public static MalformedRequestException of(String message) {
return new MalformedRequestException(
message, FileserverFailureContext.of(FileserverErrorCode.BAD_REQUEST, false));
}
}
@@ -0,0 +1,22 @@
package dev.caskeleton.application.fileserver.api.error;
/** A malware or content-disarm verifier returned a reject verdict; content is never published. */
public final class MalwareDetectedException extends FileserverException {
private static final long serialVersionUID = 1L;
public MalwareDetectedException(String message, FileserverFailureContext context) {
super(message, context);
}
public MalwareDetectedException(
String message, Throwable cause, FileserverFailureContext context) {
super(message, cause, context);
}
/** Failure with no file or upload correlation. */
public static MalwareDetectedException of(String message) {
return new MalwareDetectedException(
message, FileserverFailureContext.of(FileserverErrorCode.MALWARE_DETECTED, false));
}
}
@@ -0,0 +1,21 @@
package dev.caskeleton.application.fileserver.api.error;
/** Fewer bytes than promised reached durable storage; the session stays recoverable. */
public final class PartialWriteException extends FileserverException {
private static final long serialVersionUID = 1L;
public PartialWriteException(String message, FileserverFailureContext context) {
super(message, context);
}
public PartialWriteException(String message, Throwable cause, FileserverFailureContext context) {
super(message, cause, context);
}
/** Failure with no file or upload correlation. */
public static PartialWriteException of(String message) {
return new PartialWriteException(
message, FileserverFailureContext.of(FileserverErrorCode.PARTIAL_WRITE, false));
}
}
@@ -0,0 +1,22 @@
package dev.caskeleton.application.fileserver.api.error;
/** A resolved physical location escaped its configured storage root. */
public final class PathOutsideNamespaceException extends FileserverException {
private static final long serialVersionUID = 1L;
public PathOutsideNamespaceException(String message, FileserverFailureContext context) {
super(message, context);
}
public PathOutsideNamespaceException(
String message, Throwable cause, FileserverFailureContext context) {
super(message, cause, context);
}
/** Failure with no file or upload correlation. */
public static PathOutsideNamespaceException of(String message) {
return new PathOutsideNamespaceException(
message, FileserverFailureContext.of(FileserverErrorCode.PATH_OUTSIDE_NAMESPACE, false));
}
}
@@ -0,0 +1,21 @@
package dev.caskeleton.application.fileserver.api.error;
/** A quota scope reservation, commit, or concurrency limit rejected the request. */
public final class QuotaExceededException extends FileserverException {
private static final long serialVersionUID = 1L;
public QuotaExceededException(String message, FileserverFailureContext context) {
super(message, context);
}
public QuotaExceededException(String message, Throwable cause, FileserverFailureContext context) {
super(message, cause, context);
}
/** Failure with no file or upload correlation. */
public static QuotaExceededException of(String message) {
return new QuotaExceededException(
message, FileserverFailureContext.of(FileserverErrorCode.QUOTA_EXCEEDED, false));
}
}
@@ -0,0 +1,21 @@
package dev.caskeleton.application.fileserver.api.error;
/** The storage pool crossed its hard high-water mark or the filesystem reported no space. */
public final class StorageFullException extends FileserverException {
private static final long serialVersionUID = 1L;
public StorageFullException(String message, FileserverFailureContext context) {
super(message, context);
}
public StorageFullException(String message, Throwable cause, FileserverFailureContext context) {
super(message, cause, context);
}
/** Failure with no file or upload correlation. */
public static StorageFullException of(String message) {
return new StorageFullException(
message, FileserverFailureContext.of(FileserverErrorCode.STORAGE_FULL, false));
}
}
@@ -0,0 +1,22 @@
package dev.caskeleton.application.fileserver.api.error;
/** The storage backend or a required verifier is temporarily unreachable. */
public final class StorageUnavailableException extends FileserverException {
private static final long serialVersionUID = 1L;
public StorageUnavailableException(String message, FileserverFailureContext context) {
super(message, context);
}
public StorageUnavailableException(
String message, Throwable cause, FileserverFailureContext context) {
super(message, cause, context);
}
/** Failure with no file or upload correlation. */
public static StorageUnavailableException of(String message) {
return new StorageUnavailableException(
message, FileserverFailureContext.of(FileserverErrorCode.STORAGE_UNAVAILABLE, true));
}
}
@@ -0,0 +1,23 @@
package dev.caskeleton.application.fileserver.api.error;
/** Instance or scope transfer permits were exhausted; the caller may retry after backoff. */
public final class TransferAdmissionRejectedException extends FileserverException {
private static final long serialVersionUID = 1L;
public TransferAdmissionRejectedException(String message, FileserverFailureContext context) {
super(message, context);
}
public TransferAdmissionRejectedException(
String message, Throwable cause, FileserverFailureContext context) {
super(message, cause, context);
}
/** Failure with no file or upload correlation. */
public static TransferAdmissionRejectedException of(String message) {
return new TransferAdmissionRejectedException(
message,
FileserverFailureContext.of(FileserverErrorCode.TRANSFER_ADMISSION_REJECTED, true));
}
}
@@ -0,0 +1,22 @@
package dev.caskeleton.application.fileserver.api.error;
/** A downstream transfer exceeded its idle or total timeout budget. */
public final class TransferTimeoutException extends FileserverException {
private static final long serialVersionUID = 1L;
public TransferTimeoutException(String message, FileserverFailureContext context) {
super(message, context);
}
public TransferTimeoutException(
String message, Throwable cause, FileserverFailureContext context) {
super(message, cause, context);
}
/** Failure with no file or upload correlation. */
public static TransferTimeoutException of(String message) {
return new TransferTimeoutException(
message, FileserverFailureContext.of(FileserverErrorCode.TRANSFER_TIMEOUT, true));
}
}
@@ -0,0 +1,22 @@
package dev.caskeleton.application.fileserver.api.error;
/** The upload media type is outside the configured allowlist. */
public final class UnsupportedMediaTypeException extends FileserverException {
private static final long serialVersionUID = 1L;
public UnsupportedMediaTypeException(String message, FileserverFailureContext context) {
super(message, context);
}
public UnsupportedMediaTypeException(
String message, Throwable cause, FileserverFailureContext context) {
super(message, cause, context);
}
/** Failure with no file or upload correlation. */
public static UnsupportedMediaTypeException of(String message) {
return new UnsupportedMediaTypeException(
message, FileserverFailureContext.of(FileserverErrorCode.UNSUPPORTED_MEDIA_TYPE, false));
}
}
@@ -0,0 +1,21 @@
package dev.caskeleton.application.fileserver.api.error;
/** The upload resource passed its expiry and is no longer appendable. */
public final class UploadExpiredException extends FileserverException {
private static final long serialVersionUID = 1L;
public UploadExpiredException(String message, FileserverFailureContext context) {
super(message, context);
}
public UploadExpiredException(String message, Throwable cause, FileserverFailureContext context) {
super(message, cause, context);
}
/** Failure with no file or upload correlation. */
public static UploadExpiredException of(String message) {
return new UploadExpiredException(
message, FileserverFailureContext.of(FileserverErrorCode.UPLOAD_EXPIRED, false));
}
}
@@ -0,0 +1,46 @@
package dev.caskeleton.application.fileserver.api.error;
import dev.caskeleton.application.fileserver.api.UploadId;
/**
* The requested append offset disagrees with the durably committed offset.
*
* <p>The upload resource is never mutated when this is thrown: the client is expected to re-read
* the current offset and resume from it.
*/
public final class UploadOffsetMismatchException extends FileserverException {
private static final long serialVersionUID = 1L;
public UploadOffsetMismatchException(String message, FileserverFailureContext context) {
super(message, context);
}
/** Mismatch reporting the offset the caller assumed and the offset that is actually durable. */
public static UploadOffsetMismatchException of(long expectedOffset, long currentOffset) {
return new UploadOffsetMismatchException(
"upload offset mismatch: expected " + expectedOffset + " but committed " + currentOffset,
FileserverFailureContext.forOffset(
FileserverErrorCode.UPLOAD_OFFSET_MISMATCH, expectedOffset, currentOffset));
}
/** Mismatch correlated to the upload resource the client addressed. */
public static UploadOffsetMismatchException of(
UploadId uploadId, long expectedOffset, long currentOffset) {
return new UploadOffsetMismatchException(
"upload offset mismatch: expected " + expectedOffset + " but committed " + currentOffset,
FileserverFailureContext.forOffset(
FileserverErrorCode.UPLOAD_OFFSET_MISMATCH, expectedOffset, currentOffset)
.withUpload(uploadId));
}
/** Offset the caller asserted, or {@code -1} when the context carries none. */
public long expectedOffset() {
return context().expectedOffset().orElse(-1L);
}
/** Offset that is actually durable, or {@code -1} when the context carries none. */
public long currentOffset() {
return context().currentOffset().orElse(-1L);
}
}
@@ -0,0 +1,27 @@
package dev.caskeleton.application.fileserver.api.metadata;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.FileState;
import dev.caskeleton.application.fileserver.api.StorageNamespace;
import java.time.Instant;
import java.util.Objects;
/** Public metadata view of a file, without transport-specific validators. */
public record FileDescriptor(
FileId fileId,
StorageNamespace namespace,
FileState state,
String originalFilename,
String mediaType,
long size,
String sha256,
Instant publishedAt,
long version) {
public FileDescriptor {
Objects.requireNonNull(fileId, "fileId");
Objects.requireNonNull(namespace, "namespace");
Objects.requireNonNull(state, "state");
Objects.requireNonNull(originalFilename, "originalFilename");
}
}
@@ -0,0 +1,40 @@
package dev.caskeleton.application.fileserver.api.metadata;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.FileState;
import dev.caskeleton.application.fileserver.api.StorageNamespace;
import java.util.List;
import java.util.Optional;
/**
* Authoritative file metadata port.
*
* <p>Every transition is conditional on both the expected version and the expected state, so two
* writers racing on the same record produce exactly one winner and one optimistic conflict.
*/
public interface FileMetadataStore {
FileRecord insert(FileRecordDraft draft);
Optional<FileRecord> find(FileId fileId);
FileRecord transition(
FileId fileId,
long expectedVersion,
FileState expectedState,
FileState targetState,
FileRecordMutation mutation);
FileRecord markDeleting(FileId fileId, long expectedVersion);
/**
* Moves a file to another logical namespace.
*
* <p>A namespace is a metadata grouping, so this changes one column and never touches the
* immutable physical object. Copying gigabytes to express an ownership change would also break
* every strong validator already handed to clients.
*/
FileRecord relocate(FileId fileId, long expectedVersion, StorageNamespace targetNamespace);
List<FileRecord> findRecoverable(FileRecoveryQuery query);
}
@@ -0,0 +1,20 @@
package dev.caskeleton.application.fileserver.api.metadata;
import java.time.Duration;
/**
* Reservation-based quota accounting.
*
* <p>When the client declares no length, the caller reserves a profile-specific initial chunk and
* extends it while appending. Every failure path releases the reservation.
*/
public interface FileQuotaService {
QuotaReservation reserve(QuotaScope scope, long expectedBytes, Duration ttl);
void extend(QuotaReservation reservation, long additionalBytes);
void commit(QuotaReservation reservation, long actualBytes);
void release(QuotaReservation reservation);
}
@@ -0,0 +1,73 @@
package dev.caskeleton.application.fileserver.api.metadata;
import dev.caskeleton.application.fileserver.api.ContentKey;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.FileState;
import dev.caskeleton.application.fileserver.api.StorageNamespace;
import java.time.Instant;
import java.util.Objects;
import java.util.Optional;
import java.util.OptionalLong;
/**
* Authoritative metadata row for one file.
*
* <p>The relational record — not the filesystem — decides whether a file is publicly readable.
* {@code version} backs every optimistic transition.
*/
public record FileRecord(
FileId fileId,
StorageNamespace namespace,
FileState state,
Optional<ContentKey> contentKey,
String originalName,
Optional<String> claimedMediaType,
Optional<String> verifiedMediaType,
OptionalLong expectedSize,
OptionalLong actualSize,
Optional<String> sha256,
Optional<Instant> publishedAt,
Optional<String> lastErrorCode,
long version,
Instant createdAt,
Instant updatedAt) {
public FileRecord {
Objects.requireNonNull(fileId, "fileId");
Objects.requireNonNull(namespace, "namespace");
Objects.requireNonNull(state, "state");
Objects.requireNonNull(contentKey, "contentKey");
Objects.requireNonNull(originalName, "originalName");
Objects.requireNonNull(claimedMediaType, "claimedMediaType");
Objects.requireNonNull(verifiedMediaType, "verifiedMediaType");
Objects.requireNonNull(expectedSize, "expectedSize");
Objects.requireNonNull(actualSize, "actualSize");
Objects.requireNonNull(sha256, "sha256");
Objects.requireNonNull(publishedAt, "publishedAt");
Objects.requireNonNull(lastErrorCode, "lastErrorCode");
Objects.requireNonNull(createdAt, "createdAt");
Objects.requireNonNull(updatedAt, "updatedAt");
if (version < 0) {
throw new IllegalArgumentException("version must not be negative");
}
}
/**
* Projects the public descriptor.
*
* <p>The verified media type wins over the claimed one, and an unpublished record reports the
* neutral {@code application/octet-stream} rather than echoing the client assertion as fact.
*/
public FileDescriptor toDescriptor() {
return new FileDescriptor(
fileId,
namespace,
state,
originalName,
verifiedMediaType.orElse("application/octet-stream"),
actualSize.orElse(0L),
sha256.orElse(""),
publishedAt.orElse(null),
version);
}
}
@@ -0,0 +1,29 @@
package dev.caskeleton.application.fileserver.api.metadata;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.StorageNamespace;
import java.util.Objects;
import java.util.Optional;
import java.util.OptionalLong;
/**
* Insert payload for a new file record in {@code CREATED}.
*
* <p>{@code originalName} is already sanitized display text and {@code claimedMediaType} is the
* untrusted client assertion; neither is used to build a physical key.
*/
public record FileRecordDraft(
FileId fileId,
StorageNamespace namespace,
String originalName,
Optional<String> claimedMediaType,
OptionalLong expectedSize) {
public FileRecordDraft {
Objects.requireNonNull(fileId, "fileId");
Objects.requireNonNull(namespace, "namespace");
Objects.requireNonNull(originalName, "originalName");
Objects.requireNonNull(claimedMediaType, "claimedMediaType");
Objects.requireNonNull(expectedSize, "expectedSize");
}
}
@@ -0,0 +1,90 @@
package dev.caskeleton.application.fileserver.api.metadata;
import dev.caskeleton.application.fileserver.api.ContentKey;
import java.time.Instant;
import java.util.Objects;
import java.util.Optional;
import java.util.OptionalLong;
/**
* Field changes applied atomically with a state transition.
*
* <p>Only fields explicitly present are written, so a transition can never clear a published digest
* or content key by omission.
*/
public record FileRecordMutation(
Optional<ContentKey> contentKey,
OptionalLong actualSize,
Optional<String> sha256,
Optional<String> verifiedMediaType,
Optional<Instant> publishedAt,
Optional<String> lastErrorCode) {
public FileRecordMutation {
Objects.requireNonNull(contentKey, "contentKey");
Objects.requireNonNull(actualSize, "actualSize");
Objects.requireNonNull(sha256, "sha256");
Objects.requireNonNull(verifiedMediaType, "verifiedMediaType");
Objects.requireNonNull(publishedAt, "publishedAt");
Objects.requireNonNull(lastErrorCode, "lastErrorCode");
}
public static FileRecordMutation none() {
return new FileRecordMutation(
Optional.empty(),
OptionalLong.empty(),
Optional.empty(),
Optional.empty(),
Optional.empty(),
Optional.empty());
}
public static FileRecordMutation publishAt(
ContentKey contentKey, long actualSize, String sha256, Instant publishedAt) {
return new FileRecordMutation(
Optional.of(contentKey),
OptionalLong.of(actualSize),
Optional.of(sha256),
Optional.empty(),
Optional.of(publishedAt),
Optional.empty());
}
public static FileRecordMutation uploaded(long actualSize, String sha256) {
return new FileRecordMutation(
Optional.empty(),
OptionalLong.of(actualSize),
Optional.of(sha256),
Optional.empty(),
Optional.empty(),
Optional.empty());
}
public FileRecordMutation withVerifiedMediaType(Optional<String> mediaType) {
Objects.requireNonNull(mediaType, "mediaType");
return mediaType.isEmpty()
? this
: new FileRecordMutation(
contentKey, actualSize, sha256, mediaType, publishedAt, lastErrorCode);
}
public static FileRecordMutation verified(String verifiedMediaType) {
return new FileRecordMutation(
Optional.empty(),
OptionalLong.empty(),
Optional.empty(),
Optional.of(verifiedMediaType),
Optional.empty(),
Optional.empty());
}
public static FileRecordMutation failure(String lastErrorCode) {
return new FileRecordMutation(
Optional.empty(),
OptionalLong.empty(),
Optional.empty(),
Optional.empty(),
Optional.empty(),
Optional.of(lastErrorCode));
}
}
@@ -0,0 +1,27 @@
package dev.caskeleton.application.fileserver.api.metadata;
import dev.caskeleton.application.fileserver.api.FileState;
import java.time.Instant;
import java.util.Objects;
import java.util.Set;
/**
* Bounded query for records that may need reconciliation.
*
* <p>The limit is mandatory: recovery scans are always bounded so a large backlog cannot turn into
* an unbounded scan.
*/
public record FileRecoveryQuery(Set<FileState> states, Instant notUpdatedSince, int limit) {
public FileRecoveryQuery {
Objects.requireNonNull(states, "states");
Objects.requireNonNull(notUpdatedSince, "notUpdatedSince");
if (states.isEmpty()) {
throw new IllegalArgumentException("at least one state is required");
}
if (limit <= 0 || limit > 1000) {
throw new IllegalArgumentException("limit must be between 1 and 1000");
}
states = Set.copyOf(states);
}
}
@@ -0,0 +1,34 @@
package dev.caskeleton.application.fileserver.api.metadata;
import java.time.Instant;
import java.util.Objects;
import java.util.UUID;
/**
* Durable claim on storage capacity held while an upload is in flight.
*
* <p>Reserved bytes are converted into committed usage only after the actual byte count is known,
* so an over-reservation never becomes permanent consumption.
*/
public record QuotaReservation(
UUID reservationId,
QuotaScope scope,
long reservedBytes,
long committedBytes,
Instant expiresAt,
QuotaReservationStatus status,
long version) {
public QuotaReservation {
Objects.requireNonNull(reservationId, "reservationId");
Objects.requireNonNull(scope, "scope");
Objects.requireNonNull(expiresAt, "expiresAt");
Objects.requireNonNull(status, "status");
if (reservedBytes < 0 || committedBytes < 0) {
throw new IllegalArgumentException("quota byte counts must not be negative");
}
if (version < 0) {
throw new IllegalArgumentException("version must not be negative");
}
}
}
@@ -0,0 +1,14 @@
package dev.caskeleton.application.fileserver.api.metadata;
/**
* Lifecycle of a quota reservation.
*
* <p>A reservation that is neither committed nor released before its expiry is reclaimed by the
* cleanup worker so an abandoned upload cannot hold capacity forever.
*/
public enum QuotaReservationStatus {
RESERVED,
COMMITTED,
RELEASED,
EXPIRED
}
@@ -0,0 +1,33 @@
package dev.caskeleton.application.fileserver.api.metadata;
import java.util.Objects;
/**
* Accounting boundary for reservations, commits, and concurrency permits.
*
* <p>A scope is a bounded label such as a tenant or a namespace. It is never a user identifier that
* would make a metric or a log line high-cardinality.
*/
public record QuotaScope(String type, String value) {
public QuotaScope {
Objects.requireNonNull(type, "type");
Objects.requireNonNull(value, "value");
if (type.isBlank() || value.isBlank()) {
throw new IllegalArgumentException("quota scope must be non-blank");
}
}
public static QuotaScope ofNamespace(String namespace) {
return new QuotaScope("namespace", namespace);
}
public static QuotaScope ofTenant(String tenant) {
return new QuotaScope("tenant", tenant);
}
/** Stable key used for lock ordering and permit maps. */
public String canonicalKey() {
return type + ':' + value;
}
}
@@ -0,0 +1,64 @@
package dev.caskeleton.application.fileserver.api.metadata;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.UploadId;
import dev.caskeleton.application.fileserver.api.transfer.UploadMode;
import java.time.Instant;
import java.util.Objects;
import java.util.Optional;
import java.util.OptionalLong;
import java.util.UUID;
/**
* Durable state of one resumable upload.
*
* <p>{@code committedOffset} advances only by bytes proven durable, and the lease columns make the
* single-writer rule enforceable across instances.
*
* <p>{@code terminal} says whether anyone may still write to this upload at all, which the lease
* cannot: a lease answers "who is writing now", and an upload that has been cancelled or has failed
* verification simply has no lease — indistinguishable, until this flag, from an idle live one.
*/
public record UploadSession(
UploadId uploadId,
FileId fileId,
UploadMode mode,
OptionalLong expectedLength,
long committedOffset,
Instant expiresAt,
Optional<String> leaseOwner,
Optional<UUID> leaseToken,
Optional<Instant> leaseUntil,
boolean terminal,
long version,
Instant createdAt,
Instant updatedAt) {
public UploadSession {
Objects.requireNonNull(uploadId, "uploadId");
Objects.requireNonNull(fileId, "fileId");
Objects.requireNonNull(mode, "mode");
Objects.requireNonNull(expectedLength, "expectedLength");
Objects.requireNonNull(expiresAt, "expiresAt");
Objects.requireNonNull(leaseOwner, "leaseOwner");
Objects.requireNonNull(leaseToken, "leaseToken");
Objects.requireNonNull(leaseUntil, "leaseUntil");
Objects.requireNonNull(createdAt, "createdAt");
Objects.requireNonNull(updatedAt, "updatedAt");
if (committedOffset < 0) {
throw new IllegalArgumentException("committedOffset must not be negative");
}
if (version < 0) {
throw new IllegalArgumentException("version must not be negative");
}
}
public boolean isExpiredAt(Instant now) {
return !now.isBefore(expiresAt);
}
/** True when the declared length is known and already fully committed. */
public boolean isComplete() {
return expectedLength.isPresent() && expectedLength.getAsLong() == committedOffset;
}
}
@@ -0,0 +1,25 @@
package dev.caskeleton.application.fileserver.api.metadata;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.UploadId;
import dev.caskeleton.application.fileserver.api.transfer.UploadMode;
import java.time.Instant;
import java.util.Objects;
import java.util.OptionalLong;
/** Insert payload for a new upload resource. */
public record UploadSessionDraft(
UploadId uploadId,
FileId fileId,
UploadMode mode,
OptionalLong expectedLength,
Instant expiresAt) {
public UploadSessionDraft {
Objects.requireNonNull(uploadId, "uploadId");
Objects.requireNonNull(fileId, "fileId");
Objects.requireNonNull(mode, "mode");
Objects.requireNonNull(expectedLength, "expectedLength");
Objects.requireNonNull(expiresAt, "expiresAt");
}
}
@@ -0,0 +1,66 @@
package dev.caskeleton.application.fileserver.api.metadata;
import dev.caskeleton.application.fileserver.api.UploadId;
import java.time.Duration;
import java.time.Instant;
import java.util.List;
import java.util.Optional;
/**
* Upload resource and writer-lease port.
*
* <p>An offset commit always requires the lease token and the expected offset, so a writer whose
* lease was taken over cannot advance the session.
*/
public interface UploadSessionStore {
UploadSession create(UploadSessionDraft draft);
Optional<UploadSession> find(UploadId uploadId);
WriterLease acquireLease(
UploadId uploadId, String owner, Instant now, Duration leaseDuration, long expectedVersion);
/**
* Extends a lease this node still holds.
*
* <p>Distinct from {@link #acquireLease} on purpose. Acquisition is only legal when no lease is
* held or the held one has expired, which is exactly false for the writer that is mid-transfer;
* routing renewal through acquisition would make every heartbeat fail and leave long uploads with
* no way to keep the lease they are actively using.
*
* @throws dev.caskeleton.application.fileserver.api.error.ConcurrentFileModificationException
* when the lease has expired or was taken over
*/
WriterLease renewLease(WriterLease lease, Instant now, Duration leaseDuration);
UploadSession commitOffset(
UploadId uploadId, WriterLease lease, long expectedOffset, long committedOffset);
void releaseLease(UploadId uploadId, WriterLease lease);
/**
* Ends the upload's writable life.
*
* <p>Called from the transaction that decides the upload is over and queues its staging cleanup,
* so "nobody may write here again" and "these bytes are scheduled for deletion" become true
* together. Queuing the cleanup on its own left a window in which a writer could still take a
* lease on the object about to be removed.
*
* @return whether this call is the one that ended it
*/
boolean terminate(UploadId uploadId);
/**
* Claims a terminal upload whose writer lease has lapsed, so its staged bytes can be deleted.
*
* <p>A claim, not a question. Reading the lease and then deleting leaves room for a writer to
* acquire that lease in between, and the object removed is then one an upload is actively
* appending to. The store settles it in the database and refuses writers afterwards.
*
* @return whether the caller may delete the staged bytes
*/
boolean claimForCleanup(UploadId uploadId, Instant now);
List<UploadSession> findExpired(Instant cutoff, int limit);
}
@@ -0,0 +1,34 @@
package dev.caskeleton.application.fileserver.api.metadata;
import dev.caskeleton.application.fileserver.api.UploadId;
import java.time.Instant;
import java.util.Objects;
import java.util.UUID;
/**
* The single right to append to one upload resource.
*
* <p>The lease is acquired by a conditional database update. A local file lock or an NFS lock is
* never used as the correctness mechanism, so a paused writer whose lease expired can no longer
* commit.
*/
public record WriterLease(
UploadId uploadId, String owner, UUID token, Instant expiresAt, long version) {
public WriterLease {
Objects.requireNonNull(uploadId, "uploadId");
Objects.requireNonNull(owner, "owner");
Objects.requireNonNull(token, "token");
Objects.requireNonNull(expiresAt, "expiresAt");
if (owner.isBlank()) {
throw new IllegalArgumentException("lease owner must be non-blank");
}
if (version < 0) {
throw new IllegalArgumentException("version must not be negative");
}
}
public boolean isExpiredAt(Instant now) {
return !now.isBefore(expiresAt);
}
}
@@ -0,0 +1,27 @@
package dev.caskeleton.application.fileserver.api.security;
import dev.caskeleton.application.fileserver.api.metadata.FileDescriptor;
import java.util.Optional;
/**
* Authorization hook the Fileserver calls on every public operation.
*
* <p>The Fileserver contains no business authorization rule of its own. A composition may implement
* this policy by delegating coarse permission checks to application-core's AuthorizationPort and
* object-specific decisions to ObjectAccessPolicy, but this interface remains product-specific:
* CREATE runs before a FileDescriptor exists and FileOperation is part of the fileserver contract.
* The core layer therefore cannot invent a universal operation-to-permission/object mapping.
*
* <p>The starter must not create an allow-all implementation in a production profile: a missing
* policy is a startup failure, not a silent permit.
*/
public interface FileAccessPolicy {
/**
* Authorizes {@code operation}, throwing when it is denied.
*
* <p>{@code descriptor} is empty for operations that run before a file record exists.
*/
void authorize(
FileOperation operation, FileAccessSubject subject, Optional<FileDescriptor> descriptor);
}
@@ -0,0 +1,32 @@
package dev.caskeleton.application.fileserver.api.security;
import java.util.Map;
import java.util.Objects;
import java.util.Set;
/**
* Framework-free caller identity handed to the access policy.
*
* <p>The Fileserver never interprets these values: it only passes them to the injected policy. No
* Spring Security type appears here.
*/
public record FileAccessSubject(
String principalId, Set<String> roles, Map<String, String> attributes) {
public FileAccessSubject {
Objects.requireNonNull(principalId, "principalId");
Objects.requireNonNull(roles, "roles");
Objects.requireNonNull(attributes, "attributes");
roles = Set.copyOf(roles);
attributes = Map.copyOf(attributes);
}
/** Unauthenticated caller; a production policy is expected to deny it. */
public static FileAccessSubject anonymous() {
return new FileAccessSubject("anonymous", Set.of(), Map.of());
}
public static FileAccessSubject of(String principalId, Set<String> roles) {
return new FileAccessSubject(principalId, roles, Map.of());
}
}
@@ -0,0 +1,19 @@
package dev.caskeleton.application.fileserver.api.security;
/**
* Operations the access policy is consulted for.
*
* <p>Every public entry point maps to exactly one value; there is no unchecked operation.
*/
public enum FileOperation {
CREATE,
APPEND,
FINALIZE,
READ_METADATA,
DOWNLOAD,
DELETE,
COPY,
MOVE,
ADMIN_REVERIFY,
ADMIN_FORCE_DELETE
}
@@ -0,0 +1,17 @@
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);
}
@@ -0,0 +1,155 @@
package dev.caskeleton.application.fileserver.api.security;
import java.nio.charset.StandardCharsets;
import java.util.Locale;
import java.util.Set;
import java.util.regex.Pattern;
/**
* Turns an untrusted client filename into display-only text.
*
* <p>The result is used for {@code Content-Disposition} and for the untrusted {@code originalName}
* metadata column. It is never a physical filename, a path component, or a security verdict input.
*/
public final class OriginalFilenamePolicy {
private static final String FALLBACK = "file";
private static final Set<String> WINDOWS_RESERVED =
Set.of(
"CON", "PRN", "AUX", "NUL", "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7",
"COM8", "COM9", "LPT1", "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9");
/**
* Structural characters that must never survive into a name.
*
* <p>Path separators and NUL are the obvious ones. The colon is here because on Windows it opens
* both a drive reference ({@code C:\...}) and an NTFS alternate data stream ({@code
* name.txt:hidden}), so a name that keeps it is still path-shaped even after the slashes are
* gone. Quote characters would break a header value.
*/
private static final Pattern STRUCTURAL = Pattern.compile("[/\\\\\\u0000\"';:]");
/** C0 and C1 control characters, including CR and LF. */
private static final Pattern CONTROL = Pattern.compile("[\\p{Cntrl}\\u007f-\\u009f]");
/** Bidirectional override and isolate characters used for filename spoofing. */
private static final Pattern BIDI =
Pattern.compile("[\\u202a-\\u202e\\u2066-\\u2069\\u200e\\u200f]");
/** Runs of dots, which would otherwise leave a traversal-shaped display name. */
private static final Pattern DOT_RUN = Pattern.compile("\\.{2,}");
private final int maximumByteLength;
public OriginalFilenamePolicy(int maximumByteLength) {
if (maximumByteLength < 8) {
throw new IllegalArgumentException("maximumByteLength must be at least 8");
}
this.maximumByteLength = maximumByteLength;
}
/** Policy with the design's 255-byte UTF-8 bound. */
public static OriginalFilenamePolicy standard() {
return new OriginalFilenamePolicy(255);
}
/**
* Sanitizes {@code candidate}.
*
* <p>The steps run in a fixed order so the result is deterministic: remove structural and control
* characters, collapse dot runs, trim leading dots and trailing dots or spaces, guard Windows
* reserved names, then bound the UTF-8 length while preserving the final extension when it fits.
*/
public SanitizedFilename sanitize(String candidate) {
if (candidate == null) {
return new SanitizedFilename(FALLBACK);
}
String working = STRUCTURAL.matcher(candidate).replaceAll("");
working = CONTROL.matcher(working).replaceAll("");
working = BIDI.matcher(working).replaceAll("");
working = DOT_RUN.matcher(working).replaceAll(".");
working = stripLeading(working, '.');
working = stripTrailing(working);
working = guardReservedName(working);
working = truncateToByteLength(working);
working = stripTrailing(working);
if (working.isEmpty()) {
working = FALLBACK;
}
return new SanitizedFilename(working);
}
private static String stripLeading(String value, char unwanted) {
int start = 0;
while (start < value.length() && value.charAt(start) == unwanted) {
start++;
}
return value.substring(start);
}
private static String stripTrailing(String value) {
int end = value.length();
while (end > 0) {
char last = value.charAt(end - 1);
if (last == '.' || last == ' ') {
end--;
} else {
break;
}
}
return value.substring(0, end).trim();
}
private static String guardReservedName(String value) {
if (value.isEmpty()) {
return value;
}
int dot = value.indexOf('.');
String stem = dot < 0 ? value : value.substring(0, dot);
if (WINDOWS_RESERVED.contains(stem.toUpperCase(Locale.ROOT))) {
return "_" + value;
}
return value;
}
/**
* Bounds the UTF-8 byte length.
*
* <p>The final extension is preserved when it still fits, because losing it would change how the
* client offers the download even though the stored media type is unaffected.
*/
private String truncateToByteLength(String value) {
if (utf8Length(value) <= maximumByteLength) {
return value;
}
int lastDot = value.lastIndexOf('.');
String extension = lastDot > 0 ? value.substring(lastDot) : "";
if (utf8Length(extension) > maximumByteLength / 2) {
extension = "";
}
String stem = extension.isEmpty() ? value : value.substring(0, lastDot);
int budget = maximumByteLength - utf8Length(extension);
return truncateCodePoints(stem, budget) + extension;
}
private static String truncateCodePoints(String value, int budget) {
StringBuilder builder = new StringBuilder();
int used = 0;
for (int index = 0; index < value.length(); ) {
int codePoint = value.codePointAt(index);
int width = utf8Length(new String(Character.toChars(codePoint)));
if (used + width > budget) {
break;
}
builder.appendCodePoint(codePoint);
used += width;
index += Character.charCount(codePoint);
}
return builder.toString();
}
private static int utf8Length(String value) {
return value.getBytes(StandardCharsets.UTF_8).length;
}
}
@@ -0,0 +1,21 @@
package dev.caskeleton.application.fileserver.api.security;
import java.util.Objects;
/**
* Ambient information one Fileserver call carries.
*
* <p>{@code instanceId} is the writer-lease owner for this node. {@code traceId} correlates
* observability without becoming a metric label.
*/
public record RequestContext(FileAccessSubject subject, String traceId, String instanceId) {
public RequestContext {
Objects.requireNonNull(subject, "subject");
Objects.requireNonNull(traceId, "traceId");
Objects.requireNonNull(instanceId, "instanceId");
if (instanceId.isBlank()) {
throw new IllegalArgumentException("instanceId must be non-blank");
}
}
}
@@ -0,0 +1,25 @@
package dev.caskeleton.application.fileserver.api.security;
import java.nio.charset.StandardCharsets;
import java.util.Objects;
/**
* Display filename that is safe to place in a {@code Content-Disposition} header.
*
* <p>A sanitized name is never used to build a physical path or a content key: the physical object
* is named from server-generated identity only.
*/
public record SanitizedFilename(String value) {
public SanitizedFilename {
Objects.requireNonNull(value, "value");
if (value.isEmpty()) {
throw new IllegalArgumentException("sanitized filename must not be empty");
}
}
/** UTF-8 length of the sanitized name, which the policy bounds. */
public int byteLength() {
return value.getBytes(StandardCharsets.UTF_8).length;
}
}
@@ -0,0 +1,36 @@
package dev.caskeleton.application.fileserver.api.security;
import dev.caskeleton.application.fileserver.api.ContentKey;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.UploadId;
import java.util.Objects;
import java.util.Optional;
/**
* Everything a verifier is allowed to know about the object under inspection.
*
* <p>The claimed media type and the sanitized filename are present as untrusted hints. A verifier
* that needs bytes reads them through the content store using {@code stagingUploadId} or {@code
* contentKey}; the request itself never carries a path or a stream.
*/
public record VerificationRequest(
FileId fileId,
Optional<UploadId> stagingUploadId,
Optional<ContentKey> contentKey,
long size,
String sha256,
Optional<String> claimedMediaType,
SanitizedFilename sanitizedFilename) {
public VerificationRequest {
Objects.requireNonNull(fileId, "fileId");
Objects.requireNonNull(stagingUploadId, "stagingUploadId");
Objects.requireNonNull(contentKey, "contentKey");
Objects.requireNonNull(sha256, "sha256");
Objects.requireNonNull(claimedMediaType, "claimedMediaType");
Objects.requireNonNull(sanitizedFilename, "sanitizedFilename");
if (size < 0) {
throw new IllegalArgumentException("size must not be negative");
}
}
}
@@ -0,0 +1,50 @@
package dev.caskeleton.application.fileserver.api.security;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;
/**
* A verifier's answer.
*
* <p>{@code safeMetadata} is a bounded, already-sanitized map. A scanner's raw response, a content
* sample, and any credential are deliberately absent.
*/
public record VerificationResult(
VerificationVerdict verdict,
String code,
Optional<String> verifiedMediaType,
Map<String, String> safeMetadata) {
public VerificationResult {
Objects.requireNonNull(verdict, "verdict");
Objects.requireNonNull(code, "code");
Objects.requireNonNull(verifiedMediaType, "verifiedMediaType");
Objects.requireNonNull(safeMetadata, "safeMetadata");
if (code.isBlank()) {
throw new IllegalArgumentException("verification code must be non-blank");
}
safeMetadata = Map.copyOf(safeMetadata);
}
public static VerificationResult accept(String code) {
return new VerificationResult(VerificationVerdict.ACCEPT, code, Optional.empty(), Map.of());
}
public static VerificationResult accept(String code, String verifiedMediaType) {
return new VerificationResult(
VerificationVerdict.ACCEPT, code, Optional.of(verifiedMediaType), Map.of());
}
public static VerificationResult reject(String code) {
return new VerificationResult(VerificationVerdict.REJECT, code, Optional.empty(), Map.of());
}
public static VerificationResult quarantine(String code) {
return new VerificationResult(VerificationVerdict.QUARANTINE, code, Optional.empty(), Map.of());
}
public static VerificationResult retry(String code) {
return new VerificationResult(VerificationVerdict.RETRY, code, Optional.empty(), Map.of());
}
}
@@ -0,0 +1,29 @@
package dev.caskeleton.application.fileserver.api.security;
/**
* Outcome of one verifier or of the whole pipeline.
*
* <p>Combination precedence is {@code REJECT > QUARANTINE > RETRY > ACCEPT}. A scanner timeout is
* {@link #RETRY} and is never silently promoted to {@link #ACCEPT}.
*/
public enum VerificationVerdict {
ACCEPT,
QUARANTINE,
REJECT,
RETRY;
/** Rank used by the policy combiner; a higher rank dominates. */
public int precedence() {
return switch (this) {
case REJECT -> 3;
case QUARANTINE -> 2;
case RETRY -> 1;
case ACCEPT -> 0;
};
}
/** True when this verdict permits publishing content. */
public boolean allowsPublish() {
return this == ACCEPT;
}
}
@@ -0,0 +1,26 @@
package dev.caskeleton.application.fileserver.api.transfer;
import java.time.Instant;
import java.util.Objects;
/**
* Immutable application view of readable file content.
*
* <p>The application exposes content facts only: digest, publication time, length and verified
* media type. HTTP validators and conditional-request semantics are derived by inbound adapters.
*/
public record FileRepresentation(
String sha256, Instant publishedAt, long length, String mediaType) {
public FileRepresentation {
Objects.requireNonNull(sha256, "sha256");
Objects.requireNonNull(publishedAt, "publishedAt");
Objects.requireNonNull(mediaType, "mediaType");
if (sha256.isBlank()) {
throw new IllegalArgumentException("sha256 must be non-blank");
}
if (length < 0) {
throw new IllegalArgumentException("length must not be negative");
}
}
}
@@ -0,0 +1,14 @@
package dev.caskeleton.application.fileserver.api.transfer;
/**
* Application-level shape of an upload session.
*
* <p>The mode describes lifecycle semantics only. Wire protocol names such as TUS or a particular
* HTTP draft are inbound-adapter concerns and are deliberately not represented here.
*/
public enum UploadMode {
SINGLE_SHOT,
BATCH,
RESUMABLE,
EXPERIMENTAL_RESUMABLE
}
@@ -0,0 +1,30 @@
package dev.caskeleton.application.fileserver.cleanup;
/**
* Outcome of one cleanup batch.
*
* <p>The skip counters are the interesting ones. {@code skippedActiveLease} means the worker found
* content an upload still owns and left it alone; {@code skippedStateChanged} means the record
* moved on since the item was queued. Both are correct outcomes, and counting them separately is
* what lets an operator tell a healthy backlog from a stuck one.
*/
public record CleanupBatchResult(
int deleted, int skippedActiveLease, int skippedStateChanged, int failed, long reclaimedBytes) {
public CleanupBatchResult {
if (deleted < 0 || skippedActiveLease < 0 || skippedStateChanged < 0 || failed < 0) {
throw new IllegalArgumentException("counters must not be negative");
}
if (reclaimedBytes < 0) {
throw new IllegalArgumentException("reclaimedBytes must not be negative");
}
}
public static CleanupBatchResult empty() {
return new CleanupBatchResult(0, 0, 0, 0, 0);
}
public int processed() {
return deleted + skippedActiveLease + skippedStateChanged + failed;
}
}
@@ -0,0 +1,19 @@
package dev.caskeleton.application.fileserver.cleanup;
import dev.caskeleton.application.fileserver.api.ContentKey;
import dev.caskeleton.application.fileserver.api.UploadId;
import dev.caskeleton.application.fileserver.api.content.DeletePrecondition;
import dev.caskeleton.application.fileserver.api.content.DeleteResult;
/**
* Physical removal, used only by the cleanup worker.
*
* <p>Keeping delete behind its own narrow port means no request-path service can reach it: physical
* removal is always deferred, never inline with a client call.
*/
public interface CleanupContentGateway {
DeleteResult delete(ContentKey key, DeletePrecondition precondition);
void discardStaging(UploadId uploadId);
}
@@ -0,0 +1,26 @@
package dev.caskeleton.application.fileserver.cleanup;
import java.util.Objects;
import java.util.UUID;
/**
* A persisted unit of deferred physical work.
*
* <p>The queue owns {@code cleanupId}; the application only ever supplies the {@link
* CleanupRequest}. The worker re-checks state, version, and lease before deleting, so an item can
* never remove content an active upload still owns.
*/
public record CleanupItem(UUID cleanupId, CleanupRequest request, int attempt) {
public CleanupItem {
Objects.requireNonNull(cleanupId, "cleanupId");
Objects.requireNonNull(request, "request");
if (attempt < 0) {
throw new IllegalArgumentException("attempt must not be negative");
}
}
public CleanupType type() {
return request.type();
}
}
@@ -0,0 +1,35 @@
package dev.caskeleton.application.fileserver.cleanup;
import java.time.Instant;
import java.util.List;
/**
* Durable queue of deferred physical work.
*
* <p>Enqueuing is always the last step of a state transition that already succeeded, so a queued
* item never implies that the logical operation is still pending. The queue assigns each item's
* identity, keeping identifier generation out of the application layer.
*/
public interface CleanupQueue {
void enqueue(CleanupRequest request);
List<CleanupItem> claimDue(Instant now, int limit);
void markDone(CleanupItem item);
void markFailed(CleanupItem item, String reasonCode, Instant nextAttemptAt);
/**
* Returns items whose worker died mid-claim to the queue.
*
* <p>A claim moves an item out of the due set, so an item whose worker performed the physical
* delete and then died is invisible to {@link #claimDue}: nothing reclaims it, and the file's
* quota and lifecycle stay unsettled for good. This is the only path back.
*
* @param now the moment expiry is judged against
* @param limit how many items one pass may reclaim
* @return how many items came back
*/
int reclaimExpiredClaims(Instant now, int limit);
}
@@ -0,0 +1,52 @@
package dev.caskeleton.application.fileserver.cleanup;
import dev.caskeleton.application.fileserver.api.ContentKey;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.UploadId;
import java.util.Objects;
import java.util.Optional;
/**
* Deferred physical work the application asks for.
*
* <p>A request carries no identity: the durable queue assigns one when it persists the item, the
* same way a database assigns a primary key. That keeps identifier generation out of the
* application layer entirely.
*/
public record CleanupRequest(
CleanupType type,
Optional<FileId> fileId,
Optional<UploadId> uploadId,
Optional<ContentKey> contentKey) {
public CleanupRequest {
Objects.requireNonNull(type, "type");
Objects.requireNonNull(fileId, "fileId");
Objects.requireNonNull(uploadId, "uploadId");
Objects.requireNonNull(contentKey, "contentKey");
}
public static CleanupRequest forContent(CleanupType type, FileId fileId, ContentKey contentKey) {
return new CleanupRequest(type, Optional.of(fileId), Optional.empty(), Optional.of(contentKey));
}
public static CleanupRequest forStaging(CleanupType type, FileId fileId, UploadId uploadId) {
return new CleanupRequest(type, Optional.of(fileId), Optional.of(uploadId), Optional.empty());
}
/**
* A physical object with no record at all, retired to quarantine and awaiting reclamation.
*
* <p>The absent {@code fileId} is the defining property, not an omission: an orphan is precisely
* an object no record claims. Queuing it is what makes the retirement durable — a node that dies
* between moving the object aside and reclaiming it would otherwise leave the object in
* quarantine with nothing recording why it is there or that anything still intends to remove it.
*/
public static CleanupRequest forOrphan(ContentKey contentKey) {
return new CleanupRequest(
CleanupType.ORPHAN_PHYSICAL_OBJECT,
Optional.empty(),
Optional.empty(),
Optional.of(contentKey));
}
}
@@ -0,0 +1,12 @@
package dev.caskeleton.application.fileserver.cleanup;
/**
* Bounded worker that performs the deferred physical work.
*
* <p>Every batch is capped by both an item count and a byte budget, so a large backlog is drained
* over many runs instead of monopolizing the storage device in one.
*/
public interface CleanupService {
CleanupBatchResult runBatch(int maxItems, long maxBytes);
}

Some files were not shown because too many files have changed in this diff Show More