refactor: 리펙토링 진행중 의존성 gradle은 얇게 유지, 각 모듈에서 처리하고 있는 부분에 대해서 리펙토링
This commit is contained in:
@@ -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
|
||||
+12
@@ -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);
|
||||
}
|
||||
+30
@@ -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");
|
||||
}
|
||||
}
|
||||
+17
@@ -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);
|
||||
}
|
||||
+270
@@ -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)));
|
||||
}
|
||||
}
|
||||
+34
@@ -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);
|
||||
}
|
||||
+24
@@ -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");
|
||||
}
|
||||
}
|
||||
}
|
||||
+31
@@ -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");
|
||||
}
|
||||
}
|
||||
+24
@@ -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");
|
||||
}
|
||||
}
|
||||
}
|
||||
+40
@@ -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");
|
||||
}
|
||||
}
|
||||
+26
@@ -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);
|
||||
}
|
||||
}
|
||||
+36
@@ -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);
|
||||
}
|
||||
+25
@@ -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");
|
||||
}
|
||||
}
|
||||
+14
@@ -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();
|
||||
}
|
||||
+30
@@ -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);
|
||||
}
|
||||
}
|
||||
+48
@@ -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));
|
||||
}
|
||||
}
|
||||
+25
@@ -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);
|
||||
}
|
||||
}
|
||||
+53
@@ -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);
|
||||
}
|
||||
}
|
||||
}
|
||||
+31
@@ -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();
|
||||
}
|
||||
}
|
||||
+31
@@ -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;
|
||||
}
|
||||
}
|
||||
+14
@@ -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);
|
||||
}
|
||||
+23
@@ -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);
|
||||
}
|
||||
}
|
||||
+30
@@ -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();
|
||||
}
|
||||
}
|
||||
+19
@@ -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");
|
||||
}
|
||||
}
|
||||
+32
@@ -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();
|
||||
}
|
||||
+47
@@ -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();
|
||||
}
|
||||
+12
@@ -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();
|
||||
}
|
||||
+22
@@ -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");
|
||||
}
|
||||
}
|
||||
}
|
||||
+22
@@ -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);
|
||||
}
|
||||
}
|
||||
+16
@@ -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);
|
||||
}
|
||||
+19
@@ -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);
|
||||
}
|
||||
}
|
||||
+32
@@ -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");
|
||||
}
|
||||
}
|
||||
}
|
||||
+23
@@ -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");
|
||||
}
|
||||
}
|
||||
}
|
||||
+18
@@ -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);
|
||||
}
|
||||
+32
@@ -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));
|
||||
}
|
||||
}
|
||||
+24
@@ -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);
|
||||
}
|
||||
}
|
||||
+24
@@ -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");
|
||||
}
|
||||
}
|
||||
+14
@@ -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
|
||||
}
|
||||
+23
@@ -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;
|
||||
}
|
||||
}
|
||||
+22
@@ -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");
|
||||
}
|
||||
}
|
||||
}
|
||||
+34
@@ -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);
|
||||
}
|
||||
}
|
||||
+35
@@ -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 () -> {};
|
||||
}
|
||||
}
|
||||
+41
@@ -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());
|
||||
}
|
||||
}
|
||||
+23
@@ -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));
|
||||
}
|
||||
}
|
||||
+22
@@ -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));
|
||||
}
|
||||
}
|
||||
+22
@@ -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));
|
||||
}
|
||||
}
|
||||
+22
@@ -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));
|
||||
}
|
||||
}
|
||||
+24
@@ -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));
|
||||
}
|
||||
}
|
||||
+27
@@ -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));
|
||||
}
|
||||
}
|
||||
+21
@@ -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));
|
||||
}
|
||||
}
|
||||
+98
@@ -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('_', '-');
|
||||
}
|
||||
}
|
||||
+35
@@ -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();
|
||||
}
|
||||
}
|
||||
+152
@@ -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);
|
||||
}
|
||||
}
|
||||
+22
@@ -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));
|
||||
}
|
||||
}
|
||||
+21
@@ -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));
|
||||
}
|
||||
}
|
||||
+28
@@ -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));
|
||||
}
|
||||
}
|
||||
+22
@@ -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));
|
||||
}
|
||||
}
|
||||
+21
@@ -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));
|
||||
}
|
||||
}
|
||||
+22
@@ -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));
|
||||
}
|
||||
}
|
||||
+21
@@ -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));
|
||||
}
|
||||
}
|
||||
+21
@@ -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));
|
||||
}
|
||||
}
|
||||
+22
@@ -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));
|
||||
}
|
||||
}
|
||||
+23
@@ -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));
|
||||
}
|
||||
}
|
||||
+22
@@ -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));
|
||||
}
|
||||
}
|
||||
+22
@@ -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));
|
||||
}
|
||||
}
|
||||
+21
@@ -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));
|
||||
}
|
||||
}
|
||||
+46
@@ -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);
|
||||
}
|
||||
}
|
||||
+27
@@ -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");
|
||||
}
|
||||
}
|
||||
+40
@@ -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);
|
||||
}
|
||||
+20
@@ -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);
|
||||
}
|
||||
+73
@@ -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);
|
||||
}
|
||||
}
|
||||
+29
@@ -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");
|
||||
}
|
||||
}
|
||||
+90
@@ -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));
|
||||
}
|
||||
}
|
||||
+27
@@ -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);
|
||||
}
|
||||
}
|
||||
+34
@@ -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");
|
||||
}
|
||||
}
|
||||
}
|
||||
+14
@@ -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
|
||||
}
|
||||
+33
@@ -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;
|
||||
}
|
||||
}
|
||||
+64
@@ -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;
|
||||
}
|
||||
}
|
||||
+25
@@ -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");
|
||||
}
|
||||
}
|
||||
+66
@@ -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);
|
||||
}
|
||||
+34
@@ -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);
|
||||
}
|
||||
}
|
||||
+27
@@ -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);
|
||||
}
|
||||
+32
@@ -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());
|
||||
}
|
||||
}
|
||||
+19
@@ -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
|
||||
}
|
||||
+17
@@ -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);
|
||||
}
|
||||
+155
@@ -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;
|
||||
}
|
||||
}
|
||||
+21
@@ -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");
|
||||
}
|
||||
}
|
||||
}
|
||||
+25
@@ -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;
|
||||
}
|
||||
}
|
||||
+36
@@ -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");
|
||||
}
|
||||
}
|
||||
}
|
||||
+50
@@ -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());
|
||||
}
|
||||
}
|
||||
+29
@@ -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;
|
||||
}
|
||||
}
|
||||
+26
@@ -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");
|
||||
}
|
||||
}
|
||||
}
|
||||
+14
@@ -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
|
||||
}
|
||||
+30
@@ -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;
|
||||
}
|
||||
}
|
||||
+19
@@ -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);
|
||||
}
|
||||
+26
@@ -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();
|
||||
}
|
||||
}
|
||||
+35
@@ -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);
|
||||
}
|
||||
+52
@@ -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));
|
||||
}
|
||||
}
|
||||
+12
@@ -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
Reference in New Issue
Block a user