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

This commit is contained in:
donghyeon-ka
2026-09-24 11:15:10 +09:00
parent 9da00eb782
commit 208077fddf
438 changed files with 5815 additions and 1528 deletions
+7 -1
View File
@@ -16,7 +16,12 @@ plugins {
dependencies {
implementation project(':application-core')
implementation project(':application-notification')
implementation project(':application-fileserver')
// `PresentationWebConfigTest` names the capability controllers as the examples of an absolute
// platform route the presentation prefix must not touch. Test scope only: the production graph
// has no edge to the capability, which is the whole point of the split.
testImplementation project(':adapter:inbound:web-fileserver')
// No `application-fileserver`. The capability's HTTP surface is
// `adapter:inbound:web-fileserver`, which depends on this leaf rather than living inside it.
implementation project(':shared-contract')
implementation 'org.springframework.boot:spring-boot-starter-web'
implementation 'org.springframework.boot:spring-boot-starter-security'
@@ -307,3 +312,4 @@ strictTestLanes {
tasks.named('check') {
dependsOn tasks.named('webSecurityBoundaryTest')
}
@@ -1,139 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.admin;
import dev.caskeleton.adapter.inbound.web.core.OwnsAbsoluteWebRoute;
import dev.caskeleton.adapter.inbound.web.fileserver.dto.UploadedFileResponse;
import dev.caskeleton.adapter.inbound.web.fileserver.security.FileserverRequestContextFactory;
import dev.caskeleton.application.fileserver.admin.FileserverAdminService;
import dev.caskeleton.application.fileserver.admin.ForceDeleteCommand;
import dev.caskeleton.application.fileserver.admin.IncompleteUploadView;
import dev.caskeleton.application.fileserver.admin.OrphanObject;
import dev.caskeleton.application.fileserver.admin.OrphanReconcileCommand;
import dev.caskeleton.application.fileserver.admin.OrphanReconcileReport;
import dev.caskeleton.application.fileserver.admin.RuntimeCapabilityReport;
import dev.caskeleton.application.fileserver.admin.StorageHealthReport;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.cleanup.CleanupBatchResult;
import jakarta.validation.Valid;
import java.util.List;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
/**
* The management plane, reachable only where it is explicitly enabled.
*
* <p>These routes live under {@code /internal/} and behind their own enablement property because
* they are not part of the public API surface: a deployment that exposes the public application
* port to the internet must be able to keep these off it entirely.
*
* <p>A reconcile without an explicit {@code dryRun=false} is always a dry run. That default lives
* here as well as in the command, because the most dangerous request is the one that omits a field.
*/
@OwnsAbsoluteWebRoute
@RestController
@ConditionalOnProperty(
prefix = "app.fileserver-platform",
name = {"enabled", "admin.enabled"},
havingValue = "true")
public class FileserverAdminController {
private static final int DEFAULT_PAGE = 100;
private final FileserverAdminService adminService;
private final FileserverRequestContextFactory contextFactory;
public FileserverAdminController(
FileserverAdminService adminService, FileserverRequestContextFactory contextFactory) {
this.adminService = adminService;
this.contextFactory = contextFactory;
}
@GetMapping(
path = "/internal/fileserver/storage-health",
produces = MediaType.APPLICATION_JSON_VALUE)
public StorageHealthReport storageHealth() {
return adminService.storageHealth(contextFactory.current());
}
@GetMapping(
path = "/internal/fileserver/capabilities",
produces = MediaType.APPLICATION_JSON_VALUE)
public RuntimeCapabilityReport capabilities() {
return adminService.capabilities(contextFactory.current());
}
@GetMapping(path = "/internal/fileserver/orphans", produces = MediaType.APPLICATION_JSON_VALUE)
public List<OrphanObject> orphans(@RequestParam(name = "limit", defaultValue = "100") int limit) {
return adminService.orphans(limit, contextFactory.current());
}
@PostMapping(
path = "/internal/fileserver/orphans:reconcile",
consumes = MediaType.APPLICATION_JSON_VALUE,
produces = MediaType.APPLICATION_JSON_VALUE)
public OrphanReconcileReport reconcileOrphans(@RequestBody OrphanReconcileHttpRequest request) {
return adminService.reconcileOrphans(toCommand(request), contextFactory.current());
}
@PostMapping(
path = "/internal/fileserver/files/{fileId}:reverify",
produces = MediaType.APPLICATION_JSON_VALUE)
public UploadedFileResponse reverify(@PathVariable("fileId") String fileId) {
return UploadedFileResponse.from(
adminService.reverify(FileId.parse(fileId), contextFactory.current()));
}
@PostMapping(
path = "/internal/fileserver/files/{fileId}:force-delete",
consumes = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity<Void> forceDelete(
@PathVariable("fileId") String fileId, @Valid @RequestBody ForceDeleteHttpRequest request) {
adminService.forceDelete(
new ForceDeleteCommand(FileId.parse(fileId), request.reasonCode()),
contextFactory.current());
return ResponseEntity.accepted().build();
}
@GetMapping(
path = "/internal/fileserver/uploads/incomplete",
produces = MediaType.APPLICATION_JSON_VALUE)
public List<IncompleteUploadView> incompleteUploads(
@RequestParam(name = "limit", defaultValue = "100") int limit) {
return adminService.incompleteUploads(limit, contextFactory.current());
}
@PostMapping(
path = "/internal/fileserver/uploads:cleanup",
produces = MediaType.APPLICATION_JSON_VALUE)
public CleanupBatchResult cleanupUploads(
@RequestParam(name = "maxItems", defaultValue = "100") int maxItems,
@RequestParam(name = "maxBytes", defaultValue = "1073741824") long maxBytes) {
return adminService.cleanupUploads(maxItems, maxBytes, contextFactory.current());
}
/**
* Reads the wire request conservatively.
*
* <p>Every absent field resolves to the safe value: a dry run, the default page, and no
* fingerprints. Nothing here can be omitted into a destructive default.
*/
private static OrphanReconcileCommand toCommand(OrphanReconcileHttpRequest request) {
boolean dryRun = request.dryRun() == null || request.dryRun();
int limit = request.limit() == null ? DEFAULT_PAGE : request.limit();
if (dryRun) {
return OrphanReconcileCommand.dryRun(limit);
}
return new OrphanReconcileCommand(
false,
limit,
request.maxBytes() == null ? 1L << 30 : request.maxBytes(),
request.expectedFingerprints() == null ? List.of() : request.expectedFingerprints(),
request.reasonCode() == null ? "ORPHAN_APPLY" : request.reasonCode());
}
}
@@ -1,7 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.admin;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;
/** Wire form of a force delete; the reason is mandatory and is recorded in the audit trail. */
public record ForceDeleteHttpRequest(@NotBlank @Size(min = 8, max = 200) String reasonCode) {}
@@ -1,16 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.admin;
import java.util.List;
/**
* Wire form of a reconcile request.
*
* <p>{@code dryRun} is a wrapper type on purpose: an absent field must mean "dry run", and a
* primitive would silently turn a missing value into {@code false}, which is an apply.
*/
public record OrphanReconcileHttpRequest(
Boolean dryRun,
Integer limit,
Long maxBytes,
List<String> expectedFingerprints,
String reasonCode) {}
@@ -1,96 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.config;
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
import dev.caskeleton.application.fileserver.api.error.FileserverException;
import dev.caskeleton.application.fileserver.api.error.FileserverFailureContext;
import dev.caskeleton.application.fileserver.api.error.TransferAdmissionRejectedException;
import dev.caskeleton.application.fileserver.api.error.TransferTimeoutException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
import java.util.function.Supplier;
import org.springframework.core.task.TaskRejectedException;
import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;
/**
* Admission control for blocking transfers.
*
* <p>The point of running transfers on their own bounded pool is not extra parallelism — the
* servlet thread blocks on the result either way — it is that the pool plus its bounded queue caps
* how many transfers can be in flight. Beyond that cap the request is rejected fast with a
* retryable {@code 429} instead of pinning a container thread until the container itself runs out.
*/
public final class BlockingTransferExecutor {
private final ThreadPoolTaskExecutor executor;
private final int awaitSeconds;
public BlockingTransferExecutor(ThreadPoolTaskExecutor executor, int awaitSeconds) {
this.executor = executor;
this.awaitSeconds = awaitSeconds;
}
/**
* Runs {@code work} on the transfer pool, translating saturation and timeout to design codes.
*
* <p>Submitted through {@link ThreadPoolTaskExecutor#submit} rather than {@code
* CompletableFuture.supplyAsync}. That distinction is the whole timeout contract: {@code
* CompletableFuture#cancel} ignores its {@code mayInterruptIfRunning} argument and never touches
* the worker thread, so a timed-out transfer used to return {@code 504} to the client while the
* worker kept streaming bytes into an abandoned response — holding a pool slot, a buffer and an
* open channel for as long as the copy took. A real {@code Future} interrupts, and an interrupted
* {@code FileChannel} closes itself, so the transfer actually stops.
*/
public <T> T call(Supplier<T> work) {
Future<T> future;
try {
future = executor.submit(work::get);
} catch (TaskRejectedException rejected) {
throw new TransferAdmissionRejectedException(
"transfer pool is saturated",
rejected,
FileserverFailureContext.of(FileserverErrorCode.TRANSFER_ADMISSION_REJECTED, true));
}
try {
return future.get(awaitSeconds, TimeUnit.SECONDS);
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
future.cancel(true);
throw new TransferTimeoutException(
"transfer was interrupted before completing",
interrupted,
FileserverFailureContext.of(FileserverErrorCode.TRANSFER_TIMEOUT, true));
} catch (TimeoutException timeout) {
// Interrupting is the point: the caller is about to answer 504, and a worker still copying
// into that response would keep a pool slot and an open channel for the rest of the transfer.
future.cancel(true);
throw new TransferTimeoutException(
"transfer did not complete within the configured budget",
timeout,
FileserverFailureContext.of(FileserverErrorCode.TRANSFER_TIMEOUT, true));
} catch (ExecutionException failure) {
throw rethrow(failure);
}
}
/**
* Unwraps the worker failure.
*
* <p>A Fileserver failure keeps its own context — wrapping it in an execution exception here
* would lose the code, the ambiguity flag, and the correct status.
*/
private static RuntimeException rethrow(ExecutionException failure) {
Throwable cause = failure.getCause();
if (cause instanceof FileserverException fileserverFailure) {
return fileserverFailure;
}
if (cause instanceof RuntimeException runtime) {
return runtime;
}
if (cause instanceof Error error) {
throw error;
}
return new IllegalStateException("transfer failed", cause);
}
}
@@ -1,38 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.config;
import dev.caskeleton.application.fileserver.api.StorageNamespace;
import java.time.Duration;
import java.util.Objects;
/**
* Transport-side Fileserver settings.
*
* <p>These are the values a controller needs and that the application layer must not read for
* itself: the default namespace for an unscoped request, the upload resource lifetime, and the
* batch part ceiling.
*/
public record FileserverWebProperties(
StorageNamespace defaultNamespace,
Duration uploadTtl,
int maxBatchParts,
boolean contentLengthRequired) {
private static final int DESIGN_MAX_BATCH_PARTS = 16;
public FileserverWebProperties {
Objects.requireNonNull(defaultNamespace, "defaultNamespace");
Objects.requireNonNull(uploadTtl, "uploadTtl");
if (uploadTtl.isNegative() || uploadTtl.isZero()) {
throw new IllegalArgumentException("uploadTtl must be positive");
}
if (maxBatchParts < 1 || maxBatchParts > DESIGN_MAX_BATCH_PARTS) {
throw new IllegalArgumentException("maxBatchParts must be between 1 and 16");
}
}
/** Design standard profile: 1 h upload lifetime, 16 batch parts, length optional. */
public static FileserverWebProperties standard(StorageNamespace defaultNamespace) {
return new FileserverWebProperties(
defaultNamespace, Duration.ofHours(1), DESIGN_MAX_BATCH_PARTS, false);
}
}
@@ -1,46 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.config;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.task.TaskDecorator;
import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;
/**
* The bounded pool every blocking Fileserver transfer runs on.
*
* <p>The abort policy is the design decision, not a leftover default: silently running the transfer
* on the caller's thread would defeat the bound, and an unbounded queue would trade a fast {@code
* 429} for an eventual heap exhaustion. Rejection is translated into a retryable response by {@link
* BlockingTransferExecutor}.
*
* <p>The pool is decorated so a transfer running on a worker thread still carries the caller's
* correlation context; without it every transfer log line would be untraceable back to its request.
*/
@Configuration(proxyBeanMethods = false)
@ConditionalOnProperty(prefix = "app.fileserver-platform", name = "enabled", havingValue = "true")
public class MvcTransferExecutorConfiguration {
@Bean(destroyMethod = "shutdown")
@ConditionalOnProperty(prefix = "app.fileserver-platform", name = "enabled", havingValue = "true")
public ThreadPoolTaskExecutor fileserverTransferExecutor(
TransferExecutorProperties properties, TaskDecorator taskDecorator) {
ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
executor.setTaskDecorator(taskDecorator);
executor.setCorePoolSize(properties.coreSize());
executor.setMaxPoolSize(properties.maxSize());
executor.setQueueCapacity(properties.queueCapacity());
executor.setThreadNamePrefix("fs-transfer-");
executor.setWaitForTasksToCompleteOnShutdown(true);
executor.setAwaitTerminationSeconds(properties.awaitSeconds());
executor.initialize();
return executor;
}
@Bean
@ConditionalOnProperty(prefix = "app.fileserver-platform", name = "enabled", havingValue = "true")
public BlockingTransferExecutor blockingTransferExecutor(
ThreadPoolTaskExecutor fileserverTransferExecutor, TransferExecutorProperties properties) {
return new BlockingTransferExecutor(fileserverTransferExecutor, properties.awaitSeconds());
}
}
@@ -1,28 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.config;
/**
* Bounds on the blocking transfer pool.
*
* <p>Every value is a hard bound. An unbounded queue would turn a saturation event into a heap
* exhaustion instead of a fast {@code 429}, which is why there is no "unlimited" option here.
*/
public record TransferExecutorProperties(
int coreSize, int maxSize, int queueCapacity, int awaitSeconds) {
public TransferExecutorProperties {
if (coreSize < 1 || maxSize < coreSize) {
throw new IllegalArgumentException("maxSize must be at least coreSize and both positive");
}
if (queueCapacity < 1) {
throw new IllegalArgumentException("queueCapacity must be positive");
}
if (awaitSeconds < 1) {
throw new IllegalArgumentException("awaitSeconds must be positive");
}
}
/** Design standard profile: core 8, max 32, queue 64. */
public static TransferExecutorProperties standard() {
return new TransferExecutorProperties(8, 32, 64, 300);
}
}
@@ -1,170 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.controller;
import dev.caskeleton.adapter.inbound.web.core.OwnsAbsoluteWebRoute;
import dev.caskeleton.adapter.inbound.web.fileserver.config.BlockingTransferExecutor;
import dev.caskeleton.adapter.inbound.web.fileserver.dto.UploadedFileResponse;
import dev.caskeleton.adapter.inbound.web.fileserver.http.HttpConditionalRequest;
import dev.caskeleton.adapter.inbound.web.fileserver.http.HttpDownloadDecision;
import dev.caskeleton.adapter.inbound.web.fileserver.http.HttpDownloadPlanner;
import dev.caskeleton.adapter.inbound.web.fileserver.http.MvcConditionalRequestFactory;
import dev.caskeleton.adapter.inbound.web.fileserver.http.MvcDownloadResponseWriter;
import dev.caskeleton.adapter.inbound.web.fileserver.http.ZeroCopyEligibility;
import dev.caskeleton.adapter.inbound.web.fileserver.nginx.NginxDownloadStrategy;
import dev.caskeleton.adapter.inbound.web.fileserver.security.FileserverRequestContextFactory;
import dev.caskeleton.application.fileserver.api.ByteRange;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.download.DownloadApplicationService;
import dev.caskeleton.application.fileserver.download.DownloadDescriptor;
import dev.caskeleton.application.fileserver.download.DownloadRequest;
import dev.caskeleton.application.fileserver.download.ZeroCopyTransferResult;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.channels.Channels;
import java.nio.channels.ReadableByteChannel;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
/**
* Metadata and content download endpoints.
*
* <p>GET and HEAD share one handler so their headers are identical by construction rather than by
* convention. Content is opened only after the decision says a body is expected, so a {@code 304},
* {@code 412}, or {@code 416} answer never reaches storage.
*/
@OwnsAbsoluteWebRoute
@RestController
@ConditionalOnProperty(prefix = "app.fileserver-platform", name = "enabled", havingValue = "true")
public class FileDownloadController {
private final DownloadApplicationService downloadService;
private final MvcConditionalRequestFactory conditionalFactory;
private final HttpDownloadPlanner downloadPlanner;
private final MvcDownloadResponseWriter responseWriter;
private final FileserverRequestContextFactory contextFactory;
private final BlockingTransferExecutor transferExecutor;
private final NginxDownloadStrategy delegationStrategy;
private final ZeroCopyEligibility zeroCopy;
/**
* The only constructor.
*
* <p>There is deliberately no shorter overload defaulting {@code zeroCopy} to disabled. Two
* constructors leave component scanning with no way to choose one, so the controller could not be
* instantiated at all; and a caller that took the short form would silently lose the optimization
* without saying so. Every construction site names its zero-copy policy.
*/
public FileDownloadController(
DownloadApplicationService downloadService,
MvcConditionalRequestFactory conditionalFactory,
HttpDownloadPlanner downloadPlanner,
MvcDownloadResponseWriter responseWriter,
FileserverRequestContextFactory contextFactory,
BlockingTransferExecutor transferExecutor,
NginxDownloadStrategy delegationStrategy,
ZeroCopyEligibility zeroCopy) {
this.downloadService = downloadService;
this.conditionalFactory = conditionalFactory;
this.downloadPlanner = downloadPlanner;
this.responseWriter = responseWriter;
this.contextFactory = contextFactory;
this.transferExecutor = transferExecutor;
this.delegationStrategy = delegationStrategy;
this.zeroCopy = zeroCopy;
}
@GetMapping(path = "/v1/files/{fileId}", produces = MediaType.APPLICATION_JSON_VALUE)
public UploadedFileResponse describe(@PathVariable("fileId") String fileId) {
return UploadedFileResponse.from(
downloadService.describeFile(FileId.parse(fileId), contextFactory.current()));
}
@RequestMapping(
path = "/v1/files/{fileId}/content",
method = {RequestMethod.GET, RequestMethod.HEAD})
public void download(
@PathVariable("fileId") String fileId,
@RequestParam(name = "inline", required = false, defaultValue = "false") boolean inline,
HttpServletRequest request,
HttpServletResponse response) {
boolean headOnly = RequestMethod.HEAD.name().equalsIgnoreCase(request.getMethod());
HttpConditionalRequest conditional = conditionalFactory.from(request, headOnly);
RequestContext context = contextFactory.current();
DownloadDescriptor descriptor =
downloadService.describe(new DownloadRequest(FileId.parse(fileId)), context);
HttpDownloadDecision decision = downloadPlanner.plan(descriptor, conditional, inline);
responseWriter.writeHeaders(decision, response);
if (!decision.bodyExpected()) {
return;
}
// Delegation is decided only after authorization and the READY gate, so the internal redirect
// can only ever name content this caller was already allowed to read.
if (delegationStrategy.shouldDelegate(decision)) {
delegationStrategy.delegate(decision.descriptor(), response);
return;
}
// `isSecure` is read here, on the container thread, because the request may be recycled before
// the transfer task runs.
boolean secure = request.isSecure();
transferExecutor.call(() -> stream(decision, response, secure));
}
/**
* Writes the described bytes.
*
* <p>A full representation is treated as a single range so the read path has exactly one shape;
* there is no separate "whole file" branch that could drift from the partial one.
*
* <p>A large plaintext response is offered to storage for a direct kernel transfer first. The
* gateway may decline for any reason, and the streaming write below is then used unchanged — the
* response is identical either way, which is what keeps this an optimization rather than a second
* contract.
*
* <p>The fallback is taken only when nothing reached the socket. A transfer that moved some bytes
* and then stopped has already committed the response, and streaming the representation on top of
* it would send the prefix twice — a body that is longer than its own {@code Content-Length} and
* matches neither the length nor the digest the client was promised. That case aborts instead.
*/
private Void stream(HttpDownloadDecision decision, HttpServletResponse response, boolean secure) {
if (!decision.isPartial() && decision.descriptor().representation().length() == 0) {
// A zero-length representation has no range at all. Clamping produced 0..0 — a one-byte
// request over an empty object — which storage correctly refused as unsatisfiable, so a
// legitimately empty file answered 416 instead of an empty 200.
return null;
}
DownloadDescriptor descriptor = decision.descriptor();
ByteRange range = decision.payloadRange();
try {
if (zeroCopy.isEligible(true, range.length(), secure)) {
ZeroCopyTransferResult transfer =
downloadService.transferContent(
descriptor, range, Channels.newChannel(response.getOutputStream()));
if (transfer.isComplete()) {
return null;
}
if (!transfer.allowsFallback()) {
throw new UncheckedIOException(
new IOException(
"direct transfer stopped after "
+ transfer.transferredBytes()
+ " bytes; the response is already committed and must not be re-sent"));
}
}
try (ReadableByteChannel content = downloadService.openContent(descriptor, range)) {
responseWriter.writeBody(content, response);
}
} catch (IOException exception) {
throw new UncheckedIOException(exception);
}
return null;
}
}
@@ -1,226 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.controller;
import dev.caskeleton.adapter.inbound.web.core.OwnsAbsoluteWebRoute;
import dev.caskeleton.adapter.inbound.web.fileserver.config.BlockingTransferExecutor;
import dev.caskeleton.adapter.inbound.web.fileserver.config.FileserverWebProperties;
import dev.caskeleton.adapter.inbound.web.fileserver.dto.BatchUploadItemResult;
import dev.caskeleton.adapter.inbound.web.fileserver.dto.BatchUploadResponse;
import dev.caskeleton.adapter.inbound.web.fileserver.dto.UploadedFileResponse;
import dev.caskeleton.adapter.inbound.web.fileserver.mapper.MultipartUploadRequestMapper;
import dev.caskeleton.adapter.inbound.web.fileserver.mapper.RawUploadRequestMapper;
import dev.caskeleton.adapter.inbound.web.fileserver.mapper.UploadIntent;
import dev.caskeleton.adapter.inbound.web.fileserver.security.FileserverRequestContextFactory;
import dev.caskeleton.application.fileserver.api.FileState;
import dev.caskeleton.application.fileserver.api.error.FileTooLargeException;
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
import dev.caskeleton.application.fileserver.api.error.FileserverException;
import dev.caskeleton.application.fileserver.api.error.FileserverFailureContext;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.api.transfer.UploadMode;
import dev.caskeleton.application.fileserver.upload.CreateUploadRequest;
import dev.caskeleton.application.fileserver.upload.FileView;
import dev.caskeleton.application.fileserver.upload.FinalizeUploadRequest;
import dev.caskeleton.application.fileserver.upload.SingleShotUploadService;
import jakarta.servlet.http.HttpServletRequest;
import java.io.IOException;
import java.io.InputStream;
import java.net.URI;
import java.nio.channels.Channels;
import java.nio.channels.ReadableByteChannel;
import java.time.Clock;
import java.util.ArrayList;
import java.util.List;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.multipart.MultipartFile;
/**
* Streaming upload endpoints.
*
* <p>Bytes are never materialized: the raw path wraps the servlet input stream and the multipart
* path wraps each part's stream, so a 2 GiB upload costs a bounded buffer rather than 2 GiB of
* heap. Every transfer goes through the bounded transfer pool, which turns overload into a fast
* retryable rejection instead of container-thread exhaustion.
*/
@OwnsAbsoluteWebRoute
@RestController
@ConditionalOnProperty(prefix = "app.fileserver-platform", name = "enabled", havingValue = "true")
public class FileUploadController {
private final SingleShotUploadService uploadService;
private final RawUploadRequestMapper rawMapper;
private final MultipartUploadRequestMapper multipartMapper;
private final FileserverRequestContextFactory contextFactory;
private final BlockingTransferExecutor transferExecutor;
private final FileserverWebProperties properties;
private final Clock clock;
public FileUploadController(
SingleShotUploadService uploadService,
RawUploadRequestMapper rawMapper,
MultipartUploadRequestMapper multipartMapper,
FileserverRequestContextFactory contextFactory,
BlockingTransferExecutor transferExecutor,
FileserverWebProperties properties,
Clock clock) {
this.uploadService = uploadService;
this.rawMapper = rawMapper;
this.multipartMapper = multipartMapper;
this.contextFactory = contextFactory;
this.transferExecutor = transferExecutor;
this.properties = properties;
this.clock = clock;
}
/** Raw streaming upload; the whole request body is the file. */
// The channel wraps the servlet request body. Closing it would close the container's input
// stream, which the container owns and reuses for keep-alive; the upload must read the body
// and leave the stream alone.
@SuppressWarnings("resource")
@PostMapping(path = "/v1/files:raw", produces = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity<UploadedFileResponse> uploadRaw(HttpServletRequest request)
throws IOException {
UploadIntent intent = rawMapper.map(request);
RequestContext context = contextFactory.current();
InputStream body = request.getInputStream();
FileView view =
transferExecutor.call(
() ->
upload(
intent,
Channels.newChannel(body),
declaredLength(intent),
context,
UploadMode.SINGLE_SHOT));
return created(view);
}
/** Multipart single upload. */
@PostMapping(
path = "/v1/files",
consumes = MediaType.MULTIPART_FORM_DATA_VALUE,
produces = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity<UploadedFileResponse> uploadMultipart(
@RequestParam("file") MultipartFile file) throws IOException {
UploadIntent intent = multipartMapper.map(file);
RequestContext context = contextFactory.current();
// Closed on every path, including a rejection thrown inside the transfer. A multipart part is
// backed by a temporary file or a buffer the container only releases when the stream is closed.
try (InputStream body = file.getInputStream()) {
ReadableByteChannel content = Channels.newChannel(body);
FileView view =
transferExecutor.call(
() -> upload(intent, content, file.getSize(), context, UploadMode.SINGLE_SHOT));
return created(view);
}
}
/**
* Bounded multi-file upload.
*
* <p>The batch is explicitly non-atomic: each part is an independent file, a failure never rolls
* back a sibling that already succeeded, and the response is always {@code 200} carrying the
* ordered per-part outcome.
*/
@PostMapping(
path = "/v1/files:batch",
consumes = MediaType.MULTIPART_FORM_DATA_VALUE,
produces = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity<BatchUploadResponse> uploadBatch(
@RequestParam("files") List<MultipartFile> files) {
requirePartCountWithinPolicy(files.size());
RequestContext context = contextFactory.current();
List<BatchUploadItemResult> results = new ArrayList<>(files.size());
for (int index = 0; index < files.size(); index++) {
results.add(uploadPart(files.get(index), index, context));
}
return ResponseEntity.ok(new BatchUploadResponse(results));
}
/**
* Uploads one batch part.
*
* <p>A part failure is converted to a per-part problem instead of aborting the request, which is
* what makes the endpoint's non-atomic contract observable rather than merely documented.
*/
private BatchUploadItemResult uploadPart(MultipartFile part, int index, RequestContext context) {
String clientPartId = partId(part, index);
try (InputStream body = part.getInputStream()) {
UploadIntent intent = multipartMapper.map(part);
ReadableByteChannel content = Channels.newChannel(body);
FileView view =
transferExecutor.call(
() -> upload(intent, content, part.getSize(), context, UploadMode.BATCH));
return BatchUploadItemResult.accepted(clientPartId, view);
} catch (FileserverException failure) {
return BatchUploadItemResult.rejected(clientPartId, failure.code());
} catch (IOException failure) {
return BatchUploadItemResult.rejected(clientPartId, FileserverErrorCode.STORAGE_UNAVAILABLE);
}
}
/**
* Records the application upload mode represented by this HTTP endpoint.
*
* <p>Wire details stay in the adapter; the application receives only lifecycle semantics such as
* single-shot or batch.
*/
private FileView upload(
UploadIntent intent,
ReadableByteChannel content,
long contentLength,
RequestContext context,
UploadMode mode) {
CreateUploadRequest request =
new CreateUploadRequest(
properties.defaultNamespace(),
intent.originalFilename(),
intent.claimedMediaType(),
intent.declaredLength(),
intent.expectedSha256(),
mode,
clock.instant().plus(properties.uploadTtl()));
return uploadService.upload(
request,
content,
contentLength,
new FinalizeUploadRequest(intent.expectedSha256(), false),
context);
}
/**
* Renders the completed upload.
*
* <p>READY is a finished object, so it answers {@code 201}; anything still under verification is
* {@code 202} with no public content behind it yet.
*/
private static ResponseEntity<UploadedFileResponse> created(FileView view) {
HttpStatus status = view.state() == FileState.READY ? HttpStatus.CREATED : HttpStatus.ACCEPTED;
return ResponseEntity.status(status)
.location(URI.create("/v1/files/" + view.fileId().canonicalText()))
.body(UploadedFileResponse.from(view));
}
private void requirePartCountWithinPolicy(int partCount) {
if (partCount > properties.maxBatchParts()) {
throw new FileTooLargeException(
"batch exceeds the configured maximum part count",
FileserverFailureContext.of(FileserverErrorCode.FILE_TOO_LARGE, false));
}
}
/** Stable per-part identity so a caller can correlate a result with what it sent. */
private static String partId(MultipartFile part, int index) {
String name = part.getOriginalFilename();
return name == null || name.isBlank() ? String.valueOf(index) : name;
}
private static long declaredLength(UploadIntent intent) {
return intent.declaredLength().isPresent() ? intent.declaredLength().getAsLong() : -1;
}
}
@@ -1,20 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.draft12;
/**
* The draft-12 header and media-type vocabulary.
*
* <p>Deliberately separate from the tus vocabulary even where the names coincide: sharing the
* constants would couple a Stable protocol to an unratified one, so a draft revision could silently
* change tus behaviour.
*/
public final class Draft12Headers {
public static final String UPLOAD_OFFSET = "Upload-Offset";
public static final String UPLOAD_COMPLETE = "Upload-Complete";
public static final String UPLOAD_LIMIT = "Upload-Limit";
/** Media type a draft-12 append carries. */
public static final String PARTIAL_UPLOAD = "application/partial-upload";
private Draft12Headers() {}
}
@@ -1,20 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.draft12;
/**
* The draft's offset-mismatch problem document.
*
* <p>It reports both offsets so the client can resume without a second round trip. This shape is
* the draft's own and is intentionally not the Fileserver problem document: a draft revision must
* be able to change it without touching the Stable contract.
*/
public record Draft12OffsetProblem(
String type, String title, int status, long expectedOffset, long providedOffset) {
public static final String TYPE =
"https://iana.org/assignments/http-problem-types#mismatching-upload-offset";
public static Draft12OffsetProblem of(long expectedOffset, long providedOffset) {
return new Draft12OffsetProblem(
TYPE, "Mismatching upload offset", 409, expectedOffset, providedOffset);
}
}
@@ -1,29 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.draft12;
import java.time.Duration;
import java.util.Objects;
/**
* Settings for the experimental draft-12 protocol.
*
* <p>Disabled by default. An unratified protocol that shipped enabled would make every deployment
* carry a surface whose contract can change without notice.
*/
public record Draft12Properties(
boolean enabled, long maxSize, Duration uploadTtl, boolean interimResponsesSupported) {
public Draft12Properties {
Objects.requireNonNull(uploadTtl, "uploadTtl");
if (maxSize <= 0) {
throw new IllegalArgumentException("maxSize must be positive");
}
if (uploadTtl.isNegative() || uploadTtl.isZero()) {
throw new IllegalArgumentException("uploadTtl must be positive");
}
}
/** Disabled profile, which is the shipped default. */
public static Draft12Properties disabled() {
return new Draft12Properties(false, 100L * 1024 * 1024, Duration.ofHours(1), false);
}
}
@@ -1,180 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.draft12;
import dev.caskeleton.adapter.inbound.web.core.OwnsAbsoluteWebRoute;
import dev.caskeleton.adapter.inbound.web.fileserver.config.BlockingTransferExecutor;
import dev.caskeleton.adapter.inbound.web.fileserver.config.FileserverWebProperties;
import dev.caskeleton.adapter.inbound.web.fileserver.security.FileserverRequestContextFactory;
import dev.caskeleton.application.fileserver.api.UploadId;
import dev.caskeleton.application.fileserver.api.error.MalformedRequestException;
import dev.caskeleton.application.fileserver.api.error.UploadOffsetMismatchException;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.api.transfer.UploadMode;
import dev.caskeleton.application.fileserver.upload.AppendUploadResult;
import dev.caskeleton.application.fileserver.upload.CreateUploadRequest;
import dev.caskeleton.application.fileserver.upload.FinalizeUploadRequest;
import dev.caskeleton.application.fileserver.upload.FinalizeUploadService;
import dev.caskeleton.application.fileserver.upload.UploadApplicationService;
import dev.caskeleton.application.fileserver.upload.UploadSessionView;
import jakarta.servlet.http.HttpServletRequest;
import java.io.IOException;
import java.io.InputStream;
import java.net.URI;
import java.nio.channels.Channels;
import java.time.Clock;
import java.util.Optional;
import java.util.OptionalLong;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.PatchMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
/**
* HTTP resumable uploads, draft-12. Experimental.
*
* <p>It shares no path, no header constant, and no response type with the tus adapter. That
* separation is the point: the draft is unratified, and a future revision must be able to change
* this surface without touching a Stable protocol that clients already depend on.
*
* <p>Only the researched part of the draft is implemented — {@code Upload-Offset}, {@code
* Upload-Complete}, the partial-upload media type, and the offset-mismatch problem type. Nothing is
* guessed from a later revision.
*/
@OwnsAbsoluteWebRoute
@RestController
@ExperimentalApi(specification = "draft-ietf-httpbis-resumable-upload-12")
@ConditionalOnProperty(
prefix = "app.fileserver-platform",
name = {"enabled", "httpbis-draft12.enabled"},
havingValue = "true")
public class Draft12UploadController {
private static final String DRAFT_PATH = "/v1/experimental/draft12/uploads";
private final UploadApplicationService uploadService;
private final FinalizeUploadService finalizeService;
private final FileserverRequestContextFactory contextFactory;
private final BlockingTransferExecutor transferExecutor;
private final FileserverWebProperties webProperties;
private final Draft12Properties draftProperties;
private final Clock clock;
public Draft12UploadController(
UploadApplicationService uploadService,
FinalizeUploadService finalizeService,
FileserverRequestContextFactory contextFactory,
BlockingTransferExecutor transferExecutor,
FileserverWebProperties webProperties,
Draft12Properties draftProperties,
Clock clock) {
this.uploadService = uploadService;
this.finalizeService = finalizeService;
this.contextFactory = contextFactory;
this.transferExecutor = transferExecutor;
this.webProperties = webProperties;
this.draftProperties = draftProperties;
this.clock = clock;
}
@PostMapping(DRAFT_PATH)
public ResponseEntity<Void> create(HttpServletRequest request) {
UploadSessionView created =
uploadService.create(
new CreateUploadRequest(
webProperties.defaultNamespace(),
filename(request),
Optional.empty(),
declaredLength(request),
Optional.empty(),
UploadMode.EXPERIMENTAL_RESUMABLE,
clock.instant().plus(draftProperties.uploadTtl())),
contextFactory.current());
return ResponseEntity.created(URI.create(DRAFT_PATH + "/" + created.uploadId().canonicalText()))
.header(Draft12Headers.UPLOAD_OFFSET, "0")
.header(Draft12Headers.UPLOAD_LIMIT, "max-size=" + draftProperties.maxSize())
.build();
}
@PatchMapping(path = DRAFT_PATH + "/{uploadId}", consumes = Draft12Headers.PARTIAL_UPLOAD)
// The channel wraps the servlet request body. Closing it would close the container's input
// stream, which the container owns and reuses for keep-alive; the upload must read the body
// and leave the stream alone.
@SuppressWarnings("resource")
public ResponseEntity<Void> append(
@PathVariable("uploadId") String uploadId, HttpServletRequest request) throws IOException {
UploadId id = UploadId.parse(uploadId);
long expectedOffset = requiredOffset(request);
boolean complete = isComplete(request);
RequestContext context = contextFactory.current();
InputStream body = request.getInputStream();
long declared = request.getContentLengthLong();
AppendUploadResult appended =
transferExecutor.call(
() ->
uploadService.append(
id, expectedOffset, Channels.newChannel(body), declared, context));
if (complete) {
finalizeService.finalizeUpload(id, FinalizeUploadRequest.synchronousWithoutDigest(), context);
}
return ResponseEntity.noContent()
.header(Draft12Headers.UPLOAD_OFFSET, String.valueOf(appended.committedOffset()))
.header(Draft12Headers.UPLOAD_COMPLETE, complete ? "?1" : "?0")
.build();
}
/**
* Renders the draft's own offset-mismatch problem document.
*
* <p>The draft defines a specific problem type carrying both offsets; mapping this through the
* shared Fileserver problem handler would answer the right status with the wrong body.
*/
@ExceptionHandler(UploadOffsetMismatchException.class)
public ResponseEntity<Draft12OffsetProblem> offsetMismatch(
UploadOffsetMismatchException failure) {
return ResponseEntity.status(409)
.contentType(MediaType.APPLICATION_PROBLEM_JSON)
.header(Draft12Headers.UPLOAD_OFFSET, String.valueOf(failure.currentOffset()))
.body(Draft12OffsetProblem.of(failure.currentOffset(), failure.expectedOffset()));
}
/**
* Reads the structured-field boolean {@code Upload-Complete}.
*
* <p>An absent header means the upload continues; only the explicit {@code ?1} form completes it,
* so a truncated request can never publish a partial object.
*/
private static boolean isComplete(HttpServletRequest request) {
return "?1".equals(request.getHeader(Draft12Headers.UPLOAD_COMPLETE));
}
private static long requiredOffset(HttpServletRequest request) {
String header = request.getHeader(Draft12Headers.UPLOAD_OFFSET);
if (header == null || header.isBlank()) {
throw MalformedRequestException.of("draft-12 append requires Upload-Offset");
}
try {
long value = Long.parseLong(header.trim());
if (value < 0) {
throw new NumberFormatException("negative");
}
return value;
} catch (NumberFormatException malformed) {
throw MalformedRequestException.of("Upload-Offset is not a non-negative integer");
}
}
private static OptionalLong declaredLength(HttpServletRequest request) {
long length = request.getContentLengthLong();
return length < 0 ? OptionalLong.empty() : OptionalLong.of(length);
}
private static String filename(HttpServletRequest request) {
String header = request.getHeader("X-Filename");
return header == null || header.isBlank() ? "upload.bin" : header;
}
}
@@ -1,23 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.draft12;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* Marks a type that implements an unratified specification.
*
* <p>An experimental protocol changes between drafts, so anything marked here may break on a
* specification revision even though this project's own contract did not change. The marker exists
* so that is visible in code review rather than discovered in production.
*/
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface ExperimentalApi {
/** The exact draft this type implements. */
String specification();
}
@@ -1,16 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.dto;
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
/**
* Failure of one batch part, in the same vocabulary the single-file endpoints use.
*
* <p>Only the stable code and its problem URN are exposed; the server-side message never crosses
* this boundary.
*/
public record BatchUploadItemProblem(String code, String type, int status) {
public static BatchUploadItemProblem of(FileserverErrorCode code) {
return new BatchUploadItemProblem(code.name(), code.problemType(), code.httpStatus());
}
}
@@ -1,24 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.dto;
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
import dev.caskeleton.application.fileserver.upload.FileView;
/**
* Result of one batch part.
*
* <p>A batch is explicitly non-atomic, so each part reports its own outcome and a failure never
* rolls back a sibling that already succeeded.
*/
public record BatchUploadItemResult(
String clientPartId, String status, String fileId, BatchUploadItemProblem problem) {
public static BatchUploadItemResult accepted(String clientPartId, FileView view) {
return new BatchUploadItemResult(
clientPartId, view.state().name(), view.fileId().canonicalText(), null);
}
public static BatchUploadItemResult rejected(String clientPartId, FileserverErrorCode code) {
return new BatchUploadItemResult(
clientPartId, "REJECTED", null, BatchUploadItemProblem.of(code));
}
}
@@ -1,21 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.dto;
import java.util.List;
/**
* Ordered per-part outcome of one batch upload.
*
* <p>The endpoint answers {@code 200} even when some parts failed: the batch has no request-wide
* atomicity, and pretending otherwise with a single status would hide the parts that succeeded.
*/
public record BatchUploadResponse(List<BatchUploadItemResult> results) {
public BatchUploadResponse {
results = List.copyOf(results);
}
/** True when every part succeeded, which the envelope layer reports as a plain success. */
public boolean fullySucceeded() {
return results.stream().allMatch(result -> result.problem() == null);
}
}
@@ -1,14 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.dto;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Pattern;
/**
* Target of a copy or move.
*
* <p>The namespace pattern is enforced at the boundary as syntax; the value object enforces it
* again as an invariant. {@code filename} is untrusted display data that the application layer
* sanitizes — it is never used to build a physical key.
*/
public record RelocateFileRequest(
@NotBlank @Pattern(regexp = "[a-z][a-z0-9-]{1,62}") String namespace, String filename) {}
@@ -1,30 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.dto;
import dev.caskeleton.application.fileserver.upload.FileView;
/**
* Wire projection of one completed upload.
*
* <p>It carries only what the public descriptor already exposes; no content key, physical path, or
* container temporary path ever appears here.
*/
public record UploadedFileResponse(
String fileId,
String state,
String filename,
String mediaType,
long size,
String sha256,
String etag) {
public static UploadedFileResponse from(FileView view) {
return new UploadedFileResponse(
view.fileId().canonicalText(),
view.state().name(),
view.descriptor().originalFilename(),
view.descriptor().mediaType(),
view.descriptor().size(),
view.descriptor().sha256(),
"\"" + view.descriptor().sha256() + "\"");
}
}
@@ -1,114 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.http;
import dev.caskeleton.application.fileserver.api.ByteRange;
import java.util.ArrayList;
import java.util.Comparator;
import java.util.List;
import java.util.Locale;
/** RFC 9110 byte-range parser with a mandatory work budget. */
public final class DefaultHttpRangeResolver implements HttpRangeResolver {
private static final String UNIT_PREFIX = "bytes=";
@Override
public HttpResolvedRanges resolve(
String rangeHeader, long representationLength, HttpRangePolicy policy) {
if (representationLength < 0) {
throw new IllegalArgumentException("representationLength must not be negative");
}
if (rangeHeader == null || rangeHeader.isBlank()) {
return HttpResolvedRanges.full(representationLength);
}
String normalized = rangeHeader.trim().toLowerCase(Locale.ROOT);
if (!normalized.startsWith(UNIT_PREFIX)) {
return HttpResolvedRanges.full(representationLength);
}
String[] specifiers = normalized.substring(UNIT_PREFIX.length()).split(",", -1);
if (specifiers.length > policy.maxRanges()) {
throw HttpRangeNotSatisfiableException.of(representationLength);
}
List<ByteRange> parsed = new ArrayList<>();
for (String specifier : specifiers) {
ByteRange range = parseSpecifier(specifier.trim(), representationLength);
if (range != null) {
parsed.add(range);
}
}
if (parsed.isEmpty()) {
throw HttpRangeNotSatisfiableException.of(representationLength);
}
List<ByteRange> effective = policy.mergeOverlaps() ? merge(parsed) : parsed;
if (effective.size() > policy.maxRanges()) {
throw HttpRangeNotSatisfiableException.of(representationLength);
}
long total = effective.stream().mapToLong(ByteRange::length).sum();
if (total > policy.maxTotalBytes()
|| total > representationLength * (long) policy.maxRanges()) {
throw HttpRangeNotSatisfiableException.of(representationLength);
}
return new HttpResolvedRanges(effective, representationLength);
}
private static ByteRange parseSpecifier(String specifier, long representationLength) {
int dash = specifier.indexOf('-');
if (dash < 0) {
throw HttpRangeNotSatisfiableException.of(representationLength);
}
String first = specifier.substring(0, dash).trim();
String last = specifier.substring(dash + 1).trim();
if (first.isEmpty()) {
long suffixLength = parseLong(last, representationLength);
if (suffixLength <= 0 || representationLength == 0) {
return null;
}
long start = Math.max(0, representationLength - suffixLength);
return new ByteRange(start, representationLength - 1);
}
long start = parseLong(first, representationLength);
if (start >= representationLength) {
return null;
}
if (last.isEmpty()) {
return new ByteRange(start, representationLength - 1);
}
long end = parseLong(last, representationLength);
if (end < start) {
return null;
}
return new ByteRange(start, Math.min(end, representationLength - 1));
}
private static long parseLong(String token, long representationLength) {
if (token.isEmpty() || !token.chars().allMatch(Character::isDigit)) {
throw HttpRangeNotSatisfiableException.of(representationLength);
}
try {
return Long.parseLong(token);
} catch (NumberFormatException exception) {
throw HttpRangeNotSatisfiableException.of(representationLength);
}
}
private static List<ByteRange> merge(List<ByteRange> ranges) {
List<ByteRange> sorted = new ArrayList<>(ranges);
sorted.sort(Comparator.comparingLong(ByteRange::startInclusive));
List<ByteRange> merged = new ArrayList<>();
ByteRange current = sorted.getFirst();
for (int index = 1; index < sorted.size(); index++) {
ByteRange next = sorted.get(index);
if (current.isAdjacentOrOverlapping(next)) {
current = current.merge(next);
} else {
merged.add(current);
current = next;
}
}
merged.add(current);
return merged;
}
}
@@ -1,47 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.http;
import java.time.Instant;
import java.util.Objects;
import java.util.Optional;
/** HTTP conditional/range headers parsed at the inbound boundary. */
public record HttpConditionalRequest(
Optional<String> ifMatch,
Optional<String> ifNoneMatch,
Optional<Instant> ifModifiedSince,
Optional<Instant> ifUnmodifiedSince,
Optional<String> ifRange,
Optional<String> range,
boolean headOnly) {
public HttpConditionalRequest {
Objects.requireNonNull(ifMatch, "ifMatch");
Objects.requireNonNull(ifNoneMatch, "ifNoneMatch");
Objects.requireNonNull(ifModifiedSince, "ifModifiedSince");
Objects.requireNonNull(ifUnmodifiedSince, "ifUnmodifiedSince");
Objects.requireNonNull(ifRange, "ifRange");
Objects.requireNonNull(range, "range");
}
public static HttpConditionalRequest plainGet() {
return new HttpConditionalRequest(
Optional.empty(),
Optional.empty(),
Optional.empty(),
Optional.empty(),
Optional.empty(),
Optional.empty(),
false);
}
public static HttpConditionalRequest rangeGet(String range) {
return new HttpConditionalRequest(
Optional.empty(),
Optional.empty(),
Optional.empty(),
Optional.empty(),
Optional.empty(),
Optional.of(range),
false);
}
}
@@ -1,87 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.http;
import dev.caskeleton.application.fileserver.api.security.SanitizedFilename;
import java.nio.charset.StandardCharsets;
import java.util.Locale;
import java.util.Set;
/** Builds injection-safe HTTP Content-Disposition values for uploaded content. */
public final class HttpContentDispositionFactory {
private static final Set<String> SCRIPTABLE_MEDIA_TYPES =
Set.of(
"text/html",
"application/xhtml+xml",
"image/svg+xml",
"application/xml",
"text/xml",
"application/xhtml",
"text/javascript",
"application/javascript");
private static final String FALLBACK_ASCII = "file";
public String attachment(SanitizedFilename filename) {
return build("attachment", filename);
}
public String inlineOrAttachment(SanitizedFilename filename, String mediaType) {
return build(isScriptable(mediaType) ? "attachment" : "inline", filename);
}
public boolean isScriptable(String mediaType) {
return mediaType != null && SCRIPTABLE_MEDIA_TYPES.contains(baseMediaType(mediaType));
}
private static String baseMediaType(String mediaType) {
int semicolon = mediaType.indexOf(';');
String base = semicolon < 0 ? mediaType : mediaType.substring(0, semicolon);
return base.trim().toLowerCase(Locale.ROOT);
}
private static String build(String disposition, SanitizedFilename filename) {
String ascii = toSafeAscii(filename.value());
String encoded = percentEncodeUtf8(filename.value());
return disposition + "; filename=\"" + ascii + "\"; filename*=UTF-8''" + encoded;
}
private static String toSafeAscii(String value) {
StringBuilder builder = new StringBuilder();
for (int index = 0; index < value.length(); index++) {
char character = value.charAt(index);
boolean safe =
(character >= 'a' && character <= 'z')
|| (character >= 'A' && character <= 'Z')
|| (character >= '0' && character <= '9')
|| character == '.'
|| character == '-'
|| character == '_'
|| character == ' ';
if (safe) {
builder.append(character);
}
}
String ascii = builder.toString().trim();
return ascii.isEmpty() ? FALLBACK_ASCII : ascii;
}
private static String percentEncodeUtf8(String value) {
StringBuilder builder = new StringBuilder();
for (byte raw : value.getBytes(StandardCharsets.UTF_8)) {
int unsigned = raw & 0xFF;
boolean unreserved =
(unsigned >= 'a' && unsigned <= 'z')
|| (unsigned >= 'A' && unsigned <= 'Z')
|| (unsigned >= '0' && unsigned <= '9')
|| unsigned == '.'
|| unsigned == '-'
|| unsigned == '_'
|| unsigned == '~';
if (unreserved) {
builder.append((char) unsigned);
} else {
builder.append('%').append(String.format(Locale.ROOT, "%02X", unsigned));
}
}
return builder.toString();
}
}
@@ -1,61 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.http;
import dev.caskeleton.application.fileserver.api.ByteRange;
import dev.caskeleton.application.fileserver.download.DownloadDescriptor;
import java.util.List;
import java.util.Objects;
/** Complete HTTP response decision derived from an authorized download descriptor. */
public record HttpDownloadDecision(
HttpDownloadOutcome outcome,
DownloadDescriptor descriptor,
List<ByteRange> ranges,
String contentDisposition,
String cacheControl,
boolean bodyExpected) {
public HttpDownloadDecision {
Objects.requireNonNull(outcome, "outcome");
Objects.requireNonNull(descriptor, "descriptor");
Objects.requireNonNull(ranges, "ranges");
Objects.requireNonNull(contentDisposition, "contentDisposition");
Objects.requireNonNull(cacheControl, "cacheControl");
ranges = List.copyOf(ranges);
}
public int status() {
return switch (outcome) {
case FULL -> 200;
case PARTIAL -> 206;
case NOT_MODIFIED -> 304;
case PRECONDITION_FAILED -> 412;
};
}
public boolean isPartial() {
return outcome == HttpDownloadOutcome.PARTIAL;
}
public ByteRange singleRange() {
if (ranges.size() != 1) {
throw new IllegalStateException("decision does not carry exactly one range");
}
return ranges.getFirst();
}
public ByteRange payloadRange() {
return isPartial() ? singleRange() : ByteRange.entire(descriptor.representation().length());
}
public long payloadLength() {
return switch (outcome) {
case FULL -> descriptor.representation().length();
case PARTIAL -> singleRange().length();
case NOT_MODIFIED, PRECONDITION_FAILED -> 0;
};
}
public String strongEtag() {
return "\"" + descriptor.representation().sha256() + "\"";
}
}
@@ -1,9 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.http;
/** Wire-level outcome selected from HTTP preconditions and range headers. */
public enum HttpDownloadOutcome {
FULL,
PARTIAL,
NOT_MODIFIED,
PRECONDITION_FAILED
}
@@ -1,122 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.http;
import dev.caskeleton.application.fileserver.api.transfer.FileRepresentation;
import dev.caskeleton.application.fileserver.download.DownloadDescriptor;
import java.time.Instant;
import java.util.List;
import java.util.Optional;
/** Owns HTTP conditional, Range, cache and content-disposition decisions for downloads. */
public final class HttpDownloadPlanner {
private final HttpRangeResolver rangeResolver;
private final HttpContentDispositionFactory dispositionFactory;
private final HttpDownloadPolicy policy;
public HttpDownloadPlanner(
HttpRangeResolver rangeResolver,
HttpContentDispositionFactory dispositionFactory,
HttpDownloadPolicy policy) {
this.rangeResolver = rangeResolver;
this.dispositionFactory = dispositionFactory;
this.policy = policy;
}
public HttpDownloadDecision plan(
DownloadDescriptor descriptor, HttpConditionalRequest request, boolean inlineRequested) {
FileRepresentation representation = descriptor.representation();
String etag = strongEtag(representation);
if (failsIfMatch(request, etag) || failsIfUnmodifiedSince(request, representation)) {
return decision(
HttpDownloadOutcome.PRECONDITION_FAILED, descriptor, List.of(), false, inlineRequested);
}
if (matchesIfNoneMatch(request, etag) || isNotModifiedSince(request, representation)) {
return decision(
HttpDownloadOutcome.NOT_MODIFIED, descriptor, List.of(), false, inlineRequested);
}
boolean bodyExpected = !request.headOnly();
if (request.range().isEmpty() || !ifRangeMatches(request, etag)) {
return decision(
HttpDownloadOutcome.FULL, descriptor, List.of(), bodyExpected, inlineRequested);
}
HttpResolvedRanges resolved =
rangeResolver.resolve(
request.range().orElseThrow(), representation.length(), policy.rangePolicy());
if (!resolved.isPartial()) {
return decision(
HttpDownloadOutcome.FULL, descriptor, List.of(), bodyExpected, inlineRequested);
}
return decision(
HttpDownloadOutcome.PARTIAL, descriptor, resolved.ranges(), bodyExpected, inlineRequested);
}
private HttpDownloadDecision decision(
HttpDownloadOutcome outcome,
DownloadDescriptor descriptor,
List<dev.caskeleton.application.fileserver.api.ByteRange> ranges,
boolean bodyExpected,
boolean inlineRequested) {
String disposition =
inlineRequested && policy.inlineAllowed()
? dispositionFactory.inlineOrAttachment(
descriptor.filename(), descriptor.representation().mediaType())
: dispositionFactory.attachment(descriptor.filename());
return new HttpDownloadDecision(
outcome, descriptor, ranges, disposition, policy.cacheControl(), bodyExpected);
}
private static boolean failsIfMatch(HttpConditionalRequest request, String etag) {
Optional<String> ifMatch = request.ifMatch();
if (ifMatch.isEmpty()) {
return false;
}
String value = ifMatch.orElseThrow().trim();
return !"*".equals(value) && !containsStrongEtag(value, etag);
}
private static boolean failsIfUnmodifiedSince(
HttpConditionalRequest request, FileRepresentation representation) {
return request.ifUnmodifiedSince().isPresent()
&& representation.publishedAt().isAfter(request.ifUnmodifiedSince().orElseThrow());
}
private static boolean matchesIfNoneMatch(HttpConditionalRequest request, String etag) {
Optional<String> ifNoneMatch = request.ifNoneMatch();
if (ifNoneMatch.isEmpty()) {
return false;
}
String value = ifNoneMatch.orElseThrow().trim();
return "*".equals(value) || containsStrongEtag(value, etag);
}
private static boolean isNotModifiedSince(
HttpConditionalRequest request, FileRepresentation representation) {
if (request.ifNoneMatch().isPresent() || request.ifModifiedSince().isEmpty()) {
return false;
}
Instant since = request.ifModifiedSince().orElseThrow();
return !representation.publishedAt().isAfter(since);
}
private static boolean ifRangeMatches(HttpConditionalRequest request, String etag) {
Optional<String> ifRange = request.ifRange();
return ifRange.isEmpty() || containsStrongEtag(ifRange.orElseThrow().trim(), etag);
}
private static String strongEtag(FileRepresentation representation) {
return "\"" + representation.sha256() + "\"";
}
private static boolean containsStrongEtag(String headerValue, String strongEtag) {
for (String candidate : List.of(headerValue.split(","))) {
String trimmed = candidate.trim();
if (!trimmed.startsWith("W/") && trimmed.equals(strongEtag)) {
return true;
}
}
return false;
}
}
@@ -1,16 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.http;
import java.util.Objects;
/** HTTP-only download response policy bound by the composition root. */
public record HttpDownloadPolicy(
HttpRangePolicy rangePolicy, String cacheControl, boolean inlineAllowed) {
public HttpDownloadPolicy {
Objects.requireNonNull(rangePolicy, "rangePolicy");
Objects.requireNonNull(cacheControl, "cacheControl");
if (cacheControl.isBlank()) {
throw new IllegalArgumentException("cacheControl must be non-blank");
}
}
}
@@ -1,28 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.http;
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
import dev.caskeleton.application.fileserver.api.error.FileserverException;
import dev.caskeleton.application.fileserver.api.error.FileserverFailureContext;
/** HTTP Range request for which no requested byte interval can be served. */
public final class HttpRangeNotSatisfiableException extends FileserverException {
private static final long serialVersionUID = 1L;
private final long representationLength;
private HttpRangeNotSatisfiableException(long representationLength) {
super(
"requested range is not satisfiable",
FileserverFailureContext.of(FileserverErrorCode.RANGE_NOT_SATISFIABLE, false));
this.representationLength = representationLength;
}
public static HttpRangeNotSatisfiableException of(long representationLength) {
return new HttpRangeNotSatisfiableException(representationLength);
}
public long representationLength() {
return representationLength;
}
}
@@ -1,32 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.http;
/** Bounded work budget for one HTTP Range request. */
public record HttpRangePolicy(int maxRanges, long maxTotalBytes, boolean mergeOverlaps) {
private static final int DESIGN_MAX_RANGES = 8;
public HttpRangePolicy {
if (maxRanges < 1 || maxRanges > DESIGN_MAX_RANGES) {
throw new IllegalArgumentException("maxRanges must be between 1 and 8");
}
if (maxTotalBytes <= 0) {
throw new IllegalArgumentException("maxTotalBytes must be positive");
}
}
public static HttpRangePolicy single(long maxTotalBytes) {
return new HttpRangePolicy(1, maxTotalBytes, false);
}
public static HttpRangePolicy unbounded() {
return new HttpRangePolicy(1, Long.MAX_VALUE, false);
}
public static HttpRangePolicy multi(int maxRanges, long maxTotalBytes) {
return new HttpRangePolicy(maxRanges, maxTotalBytes, true);
}
public boolean allowsMultipleRanges() {
return maxRanges > 1;
}
}
@@ -1,6 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.http;
/** Parses and bounds one HTTP Range header. */
public interface HttpRangeResolver {
HttpResolvedRanges resolve(String rangeHeader, long representationLength, HttpRangePolicy policy);
}
@@ -1,29 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.http;
import dev.caskeleton.application.fileserver.api.ByteRange;
import java.util.List;
import java.util.Objects;
/** HTTP byte ranges normalized against one immutable representation. */
public record HttpResolvedRanges(List<ByteRange> ranges, long representationLength) {
public HttpResolvedRanges {
Objects.requireNonNull(ranges, "ranges");
if (representationLength < 0) {
throw new IllegalArgumentException("representationLength must not be negative");
}
ranges = List.copyOf(ranges);
}
public static HttpResolvedRanges full(long representationLength) {
return new HttpResolvedRanges(List.of(), representationLength);
}
public boolean isPartial() {
return !ranges.isEmpty();
}
public long totalBytes() {
return ranges.stream().mapToLong(ByteRange::length).sum();
}
}
@@ -1,42 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.http;
import jakarta.servlet.http.HttpServletRequest;
import java.time.Instant;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeParseException;
import java.util.Optional;
import org.springframework.http.HttpHeaders;
/** Parses servlet conditional/range headers at the HTTP boundary. */
public final class MvcConditionalRequestFactory {
public HttpConditionalRequest from(HttpServletRequest request, boolean headOnly) {
return new HttpConditionalRequest(
header(request, HttpHeaders.IF_MATCH),
header(request, HttpHeaders.IF_NONE_MATCH),
date(request, HttpHeaders.IF_MODIFIED_SINCE),
date(request, HttpHeaders.IF_UNMODIFIED_SINCE),
header(request, HttpHeaders.IF_RANGE),
header(request, HttpHeaders.RANGE),
headOnly);
}
private static Optional<String> header(HttpServletRequest request, String name) {
String value = request.getHeader(name);
return value == null || value.isBlank() ? Optional.empty() : Optional.of(value);
}
private static Optional<Instant> date(HttpServletRequest request, String name) {
Optional<String> raw = header(request, name);
if (raw.isEmpty()) {
return Optional.empty();
}
try {
return Optional.of(
ZonedDateTime.parse(raw.orElseThrow(), DateTimeFormatter.RFC_1123_DATE_TIME).toInstant());
} catch (DateTimeParseException malformed) {
return Optional.empty();
}
}
}
@@ -1,66 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.http;
import dev.caskeleton.application.fileserver.api.ByteRange;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.io.OutputStream;
import java.nio.ByteBuffer;
import java.nio.channels.ReadableByteChannel;
import java.time.ZoneOffset;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;
import org.springframework.http.HttpHeaders;
/** Renders one HTTP download decision onto a servlet response. */
public final class MvcDownloadResponseWriter {
public static final String CONTENT_TYPE_OPTIONS = "X-Content-Type-Options";
private static final int BUFFER_BYTES = 64 * 1024;
private static final DateTimeFormatter HTTP_DATE =
DateTimeFormatter.RFC_1123_DATE_TIME.withZone(ZoneOffset.UTC);
public void writeHeaders(HttpDownloadDecision decision, HttpServletResponse response) {
response.setStatus(decision.status());
response.setHeader(HttpHeaders.ETAG, decision.strongEtag());
response.setHeader(
HttpHeaders.LAST_MODIFIED,
HTTP_DATE.format(
ZonedDateTime.ofInstant(
decision.descriptor().representation().publishedAt(), ZoneOffset.UTC)));
response.setHeader(HttpHeaders.ACCEPT_RANGES, "bytes");
response.setHeader(HttpHeaders.CACHE_CONTROL, decision.cacheControl());
response.setHeader(CONTENT_TYPE_OPTIONS, "nosniff");
if (decision.outcome() == HttpDownloadOutcome.NOT_MODIFIED) {
return;
}
response.setHeader(
HttpHeaders.CONTENT_TYPE, decision.descriptor().representation().mediaType());
response.setHeader(HttpHeaders.CONTENT_DISPOSITION, decision.contentDisposition());
response.setHeader(HttpHeaders.CONTENT_LENGTH, String.valueOf(decision.payloadLength()));
if (decision.isPartial()) {
ByteRange range = decision.singleRange();
response.setHeader(
HttpHeaders.CONTENT_RANGE,
"bytes "
+ range.startInclusive()
+ "-"
+ range.endInclusive()
+ "/"
+ decision.descriptor().representation().length());
}
}
public void writeBody(ReadableByteChannel content, HttpServletResponse response)
throws IOException {
ByteBuffer buffer = ByteBuffer.allocate(BUFFER_BYTES);
try (ReadableByteChannel source = content) {
OutputStream target = response.getOutputStream();
while (source.read(buffer) >= 0) {
buffer.flip();
target.write(buffer.array(), buffer.arrayOffset(), buffer.limit());
buffer.clear();
}
target.flush();
}
}
}
@@ -1,54 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.http;
import org.springframework.http.ZeroCopyHttpOutputMessage;
import org.springframework.http.server.reactive.ServerHttpResponse;
/**
* Decides whether a response may be written with a kernel-level file transfer.
*
* <p>Zero copy is an optimization and never a contract change, so it is taken only when every
* precondition holds at once: the response implementation supports it, the body needs no
* transformation, and the connection is not encrypted in user space (TLS has to see the plaintext,
* so a {@code sendfile} would bypass the very layer that must transform it).
*/
public final class ZeroCopyEligibility {
private final boolean enabled;
private final long minimumBytes;
public ZeroCopyEligibility(boolean enabled, long minimumBytes) {
if (minimumBytes < 0) {
throw new IllegalArgumentException("minimumBytes must not be negative");
}
this.enabled = enabled;
this.minimumBytes = minimumBytes;
}
/** Design default: enabled above 16 MiB. */
public static ZeroCopyEligibility standard() {
return new ZeroCopyEligibility(true, 16L * 1024 * 1024);
}
public static ZeroCopyEligibility disabled() {
return new ZeroCopyEligibility(false, Long.MAX_VALUE);
}
public boolean isEligible(ServerHttpResponse response, long payloadBytes, boolean secure) {
return isEligible(supportsZeroCopy(response), payloadBytes, secure);
}
/**
* Decides eligibility from already-resolved facts.
*
* <p>Separating the capability probe from the policy keeps the policy testable without
* constructing a server response, and keeps the probe in exactly one place.
*/
public boolean isEligible(boolean responseCapable, long payloadBytes, boolean secure) {
return enabled && responseCapable && !secure && payloadBytes >= minimumBytes;
}
/** True when the response implementation can hand a file straight to the kernel. */
public static boolean supportsZeroCopy(ServerHttpResponse response) {
return response instanceof ZeroCopyHttpOutputMessage;
}
}
@@ -1,119 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.lifecycle;
import dev.caskeleton.adapter.inbound.web.core.OwnsAbsoluteWebRoute;
import dev.caskeleton.adapter.inbound.web.fileserver.dto.RelocateFileRequest;
import dev.caskeleton.adapter.inbound.web.fileserver.dto.UploadedFileResponse;
import dev.caskeleton.adapter.inbound.web.fileserver.security.FileserverRequestContextFactory;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.StorageNamespace;
import dev.caskeleton.application.fileserver.lifecycle.CopyFileCommand;
import dev.caskeleton.application.fileserver.lifecycle.DeleteOutcome;
import dev.caskeleton.application.fileserver.lifecycle.FileLifecycleService;
import dev.caskeleton.application.fileserver.upload.FileView;
import jakarta.validation.Valid;
import java.net.URI;
import java.util.Optional;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RestController;
/**
* Delete, copy, and move endpoints.
*
* <p>The status codes carry meaning that the client needs. A delete that still has physical content
* to reclaim answers {@code 202}, not {@code 204}: the file is already unreadable, but the
* operation is not finished, and a caller waiting for storage to be freed must be able to tell the
* difference.
*
* <p>These routes live outside the {@code controller} package because AIP-136's colon verb is
* applied to a path variable here — the copy and move paths append the verb to the file-id segment
* — which the repository's AIP-122 segment rule does not model. The design fixes those paths, so
* the code moves rather than the contract.
*/
@OwnsAbsoluteWebRoute
@RestController
@ConditionalOnProperty(prefix = "app.fileserver-platform", name = "enabled", havingValue = "true")
public class FileLifecycleController {
private final FileLifecycleService lifecycleService;
private final FileserverRequestContextFactory contextFactory;
public FileLifecycleController(
FileLifecycleService lifecycleService, FileserverRequestContextFactory contextFactory) {
this.lifecycleService = lifecycleService;
this.contextFactory = contextFactory;
}
@DeleteMapping("/v1/files/{fileId}")
public ResponseEntity<Void> delete(
@PathVariable("fileId") String fileId,
@RequestHeader(name = HttpHeaders.IF_MATCH, required = false) String ifMatch) {
DeleteOutcome outcome =
lifecycleService.delete(
FileId.parse(fileId), expectedSha256(ifMatch), contextFactory.current());
return outcome.physicalCleanupScheduled()
? ResponseEntity.accepted().build()
: ResponseEntity.noContent().build();
}
@PostMapping(
path = "/v1/files/{fileId}:copy",
consumes = MediaType.APPLICATION_JSON_VALUE,
produces = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity<UploadedFileResponse> copy(
@PathVariable("fileId") String fileId,
@RequestHeader(name = HttpHeaders.IF_MATCH, required = false) String ifMatch,
@Valid @RequestBody RelocateFileRequest request) {
FileView copied =
lifecycleService.copy(
new CopyFileCommand(
FileId.parse(fileId),
StorageNamespace.of(request.namespace()),
Optional.ofNullable(request.filename()),
expectedSha256(ifMatch)),
contextFactory.current());
return ResponseEntity.accepted()
.location(URI.create("/v1/files/" + copied.fileId().canonicalText()))
.body(UploadedFileResponse.from(copied));
}
@PostMapping(
path = "/v1/files/{fileId}:move",
consumes = MediaType.APPLICATION_JSON_VALUE,
produces = MediaType.APPLICATION_JSON_VALUE)
public UploadedFileResponse move(
@PathVariable("fileId") String fileId,
@RequestHeader(name = HttpHeaders.IF_MATCH, required = false) String ifMatch,
@Valid @RequestBody RelocateFileRequest request) {
return UploadedFileResponse.from(
lifecycleService.move(
FileId.parse(fileId),
StorageNamespace.of(request.namespace()),
expectedSha256(ifMatch),
contextFactory.current()));
}
private static Optional<String> expectedSha256(String ifMatch) {
if (ifMatch == null || ifMatch.isBlank() || "*".equals(ifMatch.trim())) {
return Optional.empty();
}
String validator = ifMatch.trim();
if (!validator.startsWith("W/")
&& validator.length() >= 2
&& validator.startsWith("\"")
&& validator.endsWith("\"")) {
return Optional.of(validator.substring(1, validator.length() - 1));
}
// Preserve the old strong-comparison behavior: malformed or weak validators reach the
// application as a value that cannot equal a SHA-256 digest and therefore fail the
// precondition.
return Optional.of(validator);
}
}
@@ -1,34 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.mapper;
import java.util.Optional;
import java.util.OptionalLong;
import org.springframework.web.multipart.MultipartFile;
/**
* Reads one multipart part's intent.
*
* <p>The part is never materialized here: {@code getBytes()} would pull the whole file into the
* heap, which is exactly the failure mode the streaming design exists to avoid. Only the part's
* declared metadata is read.
*/
public final class MultipartUploadRequestMapper {
private static final String FALLBACK_FILENAME = "upload.bin";
public UploadIntent map(MultipartFile part) {
return new UploadIntent(
filename(part), claimedMediaType(part), OptionalLong.of(part.getSize()), Optional.empty());
}
private static String filename(MultipartFile part) {
String submitted = part.getOriginalFilename();
return submitted == null || submitted.isBlank() ? FALLBACK_FILENAME : submitted;
}
private static Optional<String> claimedMediaType(MultipartFile part) {
String contentType = part.getContentType();
return contentType == null || contentType.isBlank()
? Optional.empty()
: Optional.of(contentType);
}
}
@@ -1,72 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.mapper;
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
import dev.caskeleton.application.fileserver.api.error.FileserverFailureContext;
import dev.caskeleton.application.fileserver.api.error.UnsupportedMediaTypeException;
import jakarta.servlet.http.HttpServletRequest;
import java.util.Locale;
import java.util.Optional;
import java.util.OptionalLong;
/**
* Reads a raw streaming upload's intent from the request headers.
*
* <p>The filename arrives in a header and is treated exactly like a multipart filename: untrusted
* display data that the application layer sanitizes. This mapper never opens the body, so a
* rejected request costs no bytes.
*/
public final class RawUploadRequestMapper {
public static final String FILENAME_HEADER = "X-Filename";
public static final String DIGEST_HEADER = "X-Content-Sha256";
private static final String FALLBACK_FILENAME = "upload.bin";
private final boolean contentLengthRequired;
public RawUploadRequestMapper(boolean contentLengthRequired) {
this.contentLengthRequired = contentLengthRequired;
}
public UploadIntent map(HttpServletRequest request) {
OptionalLong declaredLength = declaredLength(request);
if (contentLengthRequired && declaredLength.isEmpty()) {
throw new UnsupportedMediaTypeException(
"this profile requires a declared Content-Length",
FileserverFailureContext.of(FileserverErrorCode.CONTENT_LENGTH_REQUIRED, false));
}
return new UploadIntent(
filename(request), claimedMediaType(request), declaredLength, digest(request));
}
private static String filename(HttpServletRequest request) {
String header = request.getHeader(FILENAME_HEADER);
return header == null || header.isBlank() ? FALLBACK_FILENAME : header;
}
private static Optional<String> claimedMediaType(HttpServletRequest request) {
String contentType = request.getContentType();
return contentType == null || contentType.isBlank()
? Optional.empty()
: Optional.of(contentType);
}
/**
* Reads the declared length.
*
* <p>A chunked request has no length; that is legal and the streamed hard limit still applies, so
* an absent value is reported as absent rather than as zero.
*/
private static OptionalLong declaredLength(HttpServletRequest request) {
long length = request.getContentLengthLong();
return length < 0 ? OptionalLong.empty() : OptionalLong.of(length);
}
private static Optional<String> digest(HttpServletRequest request) {
String header = request.getHeader(DIGEST_HEADER);
if (header == null || header.isBlank()) {
return Optional.empty();
}
return Optional.of(header.trim().toLowerCase(Locale.ROOT));
}
}
@@ -1,26 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.mapper;
import java.util.Objects;
import java.util.Optional;
import java.util.OptionalLong;
/**
* Transport-side reading of one upload's headers or part metadata.
*
* <p>It exists so the raw and multipart paths converge on one shape before anything reaches the
* application layer. Every field is untrusted client input; nothing here is used to build a
* physical key.
*/
public record UploadIntent(
String originalFilename,
Optional<String> claimedMediaType,
OptionalLong declaredLength,
Optional<String> expectedSha256) {
public UploadIntent {
Objects.requireNonNull(originalFilename, "originalFilename");
Objects.requireNonNull(claimedMediaType, "claimedMediaType");
Objects.requireNonNull(declaredLength, "declaredLength");
Objects.requireNonNull(expectedSha256, "expectedSha256");
}
}
@@ -1,64 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.nginx;
import dev.caskeleton.application.fileserver.api.ContentKey;
import dev.caskeleton.application.fileserver.api.error.InvalidPathException;
import java.util.regex.Pattern;
/**
* Rebuilds the internal URI from a validated content key.
*
* <p>Nothing here concatenates client input. The key has already been through {@link ContentKey}'s
* character class, and this class re-checks the sharded shape before emitting a URI, because a
* header that reaches Nginx as an internal redirect is effectively a filesystem lookup: a traversal
* that survived to this point would be served, not rejected.
*/
public final class DefaultNginxInternalUriMapper implements NginxInternalUriMapper {
private static final Pattern SHARDED_KEY =
Pattern.compile("[a-z0-9]{2}/[a-z0-9]{2}/[a-z0-9_-]{12,190}");
/** A well-formed key that names nothing; only the mapping's shape is under test. */
private static final String ATTESTATION_KEY = "00/00/startup-attestation";
private final NginxDelegationProperties properties;
public DefaultNginxInternalUriMapper(NginxDelegationProperties properties) {
this.properties = properties;
}
@Override
public String map(ContentKey key) {
return mapUnchecked(key.value());
}
/**
* Round-trips a representative key through the configured prefix and suffix.
*
* <p>A representative key rather than a real one: the attestation has to run before any object
* exists, and what it checks is the shape of the configuration, not the presence of content.
*/
@Override
public boolean attestMapping() {
try {
String uri = mapUnchecked(ATTESTATION_KEY);
return uri.startsWith("/")
&& uri.startsWith(properties.internalPrefix())
&& uri.endsWith(properties.objectSuffix())
&& uri.contains(ATTESTATION_KEY);
} catch (InvalidPathException misconfigured) {
return false;
}
}
@Override
public String mapUnchecked(String rawKey) {
if (rawKey == null || !SHARDED_KEY.matcher(rawKey).matches()) {
throw InvalidPathException.of("content key is not a valid sharded object key");
}
String uri = properties.internalPrefix() + rawKey + properties.objectSuffix();
if (uri.contains("..") || uri.contains("//") || uri.indexOf('\\') >= 0) {
throw InvalidPathException.of("internal uri failed its post-construction check");
}
return uri;
}
}
@@ -1,41 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.nginx;
import java.util.Objects;
import java.util.regex.Pattern;
/**
* Settings for handing large transfers to the front proxy.
*
* <p>The internal prefix must match an Nginx {@code location} marked {@code internal}; if it is
* not, the prefix becomes a publicly reachable path to raw content, so startup validates it rather
* than trusting configuration.
*/
public record NginxDelegationProperties(
boolean enabled, String internalPrefix, String objectSuffix, long minimumBytes) {
private static final Pattern SAFE_PREFIX = Pattern.compile("/[A-Za-z0-9_/-]{1,64}");
private static final Pattern SAFE_SUFFIX = Pattern.compile("(\\.[a-z0-9]{1,8})?");
public NginxDelegationProperties {
Objects.requireNonNull(internalPrefix, "internalPrefix");
Objects.requireNonNull(objectSuffix, "objectSuffix");
if (!SAFE_PREFIX.matcher(internalPrefix).matches() || !internalPrefix.endsWith("/")) {
throw new IllegalArgumentException("internalPrefix must be a safe rooted path ending in '/'");
}
if (!SAFE_SUFFIX.matcher(objectSuffix).matches()) {
throw new IllegalArgumentException("objectSuffix must be empty or a short lowercase suffix");
}
if (minimumBytes < 0) {
throw new IllegalArgumentException("minimumBytes must not be negative");
}
}
/** Design default: disabled, {@code /__files/} prefix, {@code .bin} objects, 16 MiB threshold. */
public static NginxDelegationProperties disabled() {
return new NginxDelegationProperties(false, "/__files/", ".bin", 16L * 1024 * 1024);
}
public static NginxDelegationProperties enabledWithDefaults() {
return new NginxDelegationProperties(true, "/__files/", ".bin", 16L * 1024 * 1024);
}
}
@@ -1,49 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.nginx;
import dev.caskeleton.adapter.inbound.web.fileserver.http.HttpDownloadDecision;
import dev.caskeleton.adapter.inbound.web.fileserver.http.HttpDownloadOutcome;
import dev.caskeleton.application.fileserver.download.DownloadDescriptor;
import jakarta.servlet.http.HttpServletResponse;
/**
* Decides whether one authorized download is handed to the front proxy, and writes the handoff.
*
* <p>Delegation happens strictly <em>after</em> authorization and the READY gate, so the internal
* redirect can only ever name content the caller was already allowed to read. A partial or
* conditional answer is never delegated: the proxy would have to re-derive the range and validator
* decisions, and two implementations of that logic is exactly the drift this design forbids.
*/
public final class NginxDownloadStrategy {
/** Header Nginx consumes; it must never be copied through to the client. */
public static final String ACCEL_REDIRECT_HEADER = "X-Accel-Redirect";
private final NginxDelegationProperties properties;
private final NginxInternalUriMapper uriMapper;
public NginxDownloadStrategy(
NginxDelegationProperties properties, NginxInternalUriMapper uriMapper) {
this.properties = properties;
this.uriMapper = uriMapper;
}
/** True when this descriptor should be transferred by the proxy rather than in-process. */
public boolean shouldDelegate(HttpDownloadDecision decision) {
return properties.enabled()
&& decision.bodyExpected()
&& decision.outcome() == HttpDownloadOutcome.FULL
&& decision.descriptor().representation().length() >= properties.minimumBytes();
}
/**
* Writes the handoff.
*
* <p>{@code Content-Length} is deliberately cleared: the proxy sets it from the file it actually
* sends, and a stale value from the metadata store would truncate or hang the response if the two
* ever disagreed.
*/
public void delegate(DownloadDescriptor descriptor, HttpServletResponse response) {
response.setHeader(ACCEL_REDIRECT_HEADER, uriMapper.map(descriptor.contentKey()));
response.setHeader("Content-Length", null);
}
}
@@ -1,33 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.nginx;
import dev.caskeleton.application.fileserver.api.ContentKey;
/**
* Turns a server-generated content key into the internal URI the front proxy serves.
*
* <p>The result is always relative and always below the configured internal prefix. An absolute
* physical path never crosses this boundary — the proxy resolves the prefix to a filesystem root
* itself, so the application never has to disclose where content lives.
*/
public interface NginxInternalUriMapper {
String map(ContentKey key);
/**
* Maps a raw string, validating it first.
*
* <p>This exists because internal callers are exactly where an unvalidated key would otherwise
* slip through; it validates rather than trusting the caller.
*/
String mapUnchecked(String rawKey);
/**
* Proves the configured mapping actually produces a usable internal URI.
*
* <p>Called once at startup instead of reading a setting in which a deployment asserts its own
* correctness. The failure this catches is silent by nature: a prefix the proxy does not resolve
* makes the server answer {@code 200} with an empty body, so the client believes it received the
* file. Better to refuse to start.
*/
boolean attestMapping();
}
@@ -1,46 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.problem;
import dev.caskeleton.application.fileserver.api.error.FileserverException;
import jakarta.servlet.http.HttpServletRequest;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.core.Ordered;
import org.springframework.core.annotation.Order;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
/**
* Maps every Fileserver failure onto its design status and problem document.
*
* <p>It is ordered ahead of the base operational handler, whose catch-all would otherwise resolve
* these to a generic internal error and lose the code. The status comes from the error code itself,
* so Spring MVC, Spring WebFlux, and the Nginx delegation path cannot drift apart.
*
* <p>Two headers are part of the contract rather than decoration: {@code Retry-After} on a
* retryable rejection, and the unsatisfied-range form of {@code Content-Range} on {@code 416},
* which is how a client learns the real representation length.
*/
@RestControllerAdvice
@ConditionalOnProperty(prefix = "app.fileserver-platform", name = "enabled", havingValue = "true")
@Order(Ordered.HIGHEST_PRECEDENCE)
public class FileserverExceptionHandler {
private final FileserverProblemFactory problemFactory;
public FileserverExceptionHandler(FileserverProblemFactory problemFactory) {
this.problemFactory = problemFactory;
}
@ExceptionHandler(FileserverException.class)
public ResponseEntity<FileserverProblem> handle(
FileserverException failure, HttpServletRequest request) {
FileserverProblem problem = problemFactory.create(failure.context(), request.getRequestURI());
ResponseEntity.BodyBuilder response =
ResponseEntity.status(problem.status()).contentType(MediaType.APPLICATION_PROBLEM_JSON);
// The header policy is shared with the reactive router; neither transport owns it.
FileserverProblemHeaders.of(failure).forEach(response::header);
return response.body(problem);
}
}
@@ -1,32 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.problem;
import com.fasterxml.jackson.annotation.JsonInclude;
/**
* RFC 9457 problem document for a Fileserver failure.
*
* <p>This is a transport-owned record rather than the framework's problem type, and it carries only
* the stable code plus the correlation fields the client can act on. The server-side exception
* message, physical path, mount, scanner credential, and filename never appear here.
*
* <p>{@code ambiguous} and {@code reconciliationRequired} are exposed deliberately: a client that
* gets an ambiguous failure must not blindly retry, because the operation may already have taken
* effect.
*/
@JsonInclude(JsonInclude.Include.NON_NULL)
public record FileserverProblem(
String type,
String title,
int status,
String code,
String detail,
String instance,
String traceId,
boolean retryable,
boolean ambiguous,
boolean reconciliationRequired,
String fileId,
String uploadId,
Long expectedOffset,
Long currentOffset,
String state) {}
@@ -1,45 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.problem;
import dev.caskeleton.adapter.inbound.web.observability.MdcKeys;
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
import dev.caskeleton.application.fileserver.api.error.FileserverFailureContext;
import java.util.OptionalLong;
import org.slf4j.MDC;
/**
* Builds the wire problem document from a failure context.
*
* <p>Everything the client sees is derived from the context — never from the exception message — so
* no code path can accidentally widen what a failure discloses.
*/
public final class FileserverProblemFactory {
public FileserverProblem create(FileserverFailureContext context, String instance) {
FileserverErrorCode code = context.code();
return new FileserverProblem(
code.problemType(),
FileserverProblemTitles.titleOf(code),
code.httpStatus(),
code.name(),
FileserverProblemTitles.titleOf(code),
instance,
traceId(),
context.retryable(),
context.ambiguous(),
context.reconciliationRequired(),
context.fileId().map(fileId -> fileId.canonicalText()).orElse(null),
context.uploadId().map(uploadId -> uploadId.canonicalText()).orElse(null),
boxed(context.expectedOffset()),
boxed(context.currentOffset()),
context.currentState().map(Enum::name).orElse(null));
}
private static Long boxed(OptionalLong value) {
return value.isPresent() ? value.getAsLong() : null;
}
private static String traceId() {
String traceId = MDC.get(MdcKeys.TRACE_ID);
return traceId == null || traceId.isBlank() ? null : traceId;
}
}
@@ -1,61 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.problem;
import dev.caskeleton.adapter.inbound.web.fileserver.http.HttpRangeNotSatisfiableException;
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
import dev.caskeleton.application.fileserver.api.error.FileserverException;
import java.util.LinkedHashMap;
import java.util.Map;
/**
* The headers a Fileserver failure carries, owned once for every transport.
*
* <p>These are contract, not decoration. {@code Retry-After} is how a client learns that a
* rejection is temporary and roughly how temporary; without it a well-behaved client either retries
* immediately — turning a saturation signal into a stampede — or gives up on something that would
* have succeeded in a second. The unsatisfied-range form of {@code Content-Range} is how a client
* learns the real representation length after a {@code 416}.
*
* <p>The table lived inside the servlet advice, and the reactive router simply did not have one, so
* the same failure answered with different headers depending on which transport served it. A shared
* owner is the only arrangement in which that cannot silently happen again: neither transport
* decides anything, both ask.
*/
public final class FileserverProblemHeaders {
/**
* How long a client should wait, per code.
*
* <p>The values are deliberately small and different from each other: a saturated pool drains in
* about a second, a storage outage does not. One shared constant would tell the client nothing.
*/
private static final Map<FileserverErrorCode, Integer> RETRY_AFTER_SECONDS =
Map.of(
FileserverErrorCode.TRANSFER_ADMISSION_REJECTED, 1,
FileserverErrorCode.STORAGE_UNAVAILABLE, 30,
FileserverErrorCode.ATOMIC_PUBLISH_UNSUPPORTED, 30,
FileserverErrorCode.TRANSFER_TIMEOUT, 5,
FileserverErrorCode.FILE_NOT_READY, 2,
FileserverErrorCode.CONCURRENT_MODIFICATION, 1);
private FileserverProblemHeaders() {}
/**
* Headers this failure must carry, in insertion order.
*
* <p>Returned as plain strings so neither Spring MVC's nor WebFlux's header type appears in the
* shared policy — the two transports differ in how they apply headers, not in which ones apply.
*/
public static Map<String, String> of(FileserverException failure) {
Map<String, String> headers = new LinkedHashMap<>();
Integer retryAfter = RETRY_AFTER_SECONDS.get(failure.code());
// Only a failure the server itself called retryable advertises a retry: telling a client to
// come back after a permanent rejection is worse than saying nothing.
if (retryAfter != null && failure.context().retryable()) {
headers.put("Retry-After", String.valueOf(retryAfter));
}
if (failure instanceof HttpRangeNotSatisfiableException unsatisfiable) {
headers.put("Content-Range", "bytes */" + unsatisfiable.representationLength());
}
return headers;
}
}
@@ -1,54 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.problem;
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
import java.util.EnumMap;
import java.util.Map;
/**
* Client-safe wording for every failure code.
*
* <p>The server-side exception message is log-only, so the wire needs its own vocabulary. Keeping
* it in one table is what stops a future handler from quietly echoing {@code getMessage()} — which
* is how storage paths and scanner responses leak into responses.
*/
final class FileserverProblemTitles {
private static final Map<FileserverErrorCode, String> TITLES =
new EnumMap<>(
Map.ofEntries(
Map.entry(FileserverErrorCode.BAD_REQUEST, "Malformed request"),
Map.entry(FileserverErrorCode.UNAUTHENTICATED, "Authentication required"),
Map.entry(FileserverErrorCode.ACCESS_DENIED, "Access denied"),
Map.entry(FileserverErrorCode.FILE_NOT_FOUND, "File not found"),
Map.entry(FileserverErrorCode.FILE_ALREADY_EXISTS, "File already exists"),
Map.entry(FileserverErrorCode.FILE_NOT_READY, "File is not ready"),
Map.entry(FileserverErrorCode.UPLOAD_OFFSET_MISMATCH, "Upload offset mismatch"),
Map.entry(FileserverErrorCode.CONCURRENT_MODIFICATION, "Concurrent modification"),
Map.entry(FileserverErrorCode.UPLOAD_EXPIRED, "Upload resource has expired"),
Map.entry(FileserverErrorCode.CONTENT_LENGTH_REQUIRED, "Content-Length is required"),
Map.entry(FileserverErrorCode.PRECONDITION_FAILED, "Precondition failed"),
Map.entry(FileserverErrorCode.FILE_TOO_LARGE, "File is too large"),
Map.entry(FileserverErrorCode.QUOTA_EXCEEDED, "Storage quota exceeded"),
Map.entry(FileserverErrorCode.UNSUPPORTED_MEDIA_TYPE, "Unsupported media type"),
Map.entry(FileserverErrorCode.RANGE_NOT_SATISFIABLE, "Range not satisfiable"),
Map.entry(FileserverErrorCode.INTEGRITY_MISMATCH, "Content integrity mismatch"),
Map.entry(FileserverErrorCode.MALWARE_DETECTED, "Content was rejected"),
Map.entry(FileserverErrorCode.INVALID_PATH, "Invalid path"),
Map.entry(FileserverErrorCode.PATH_OUTSIDE_NAMESPACE, "Path outside namespace"),
Map.entry(FileserverErrorCode.TRANSFER_ADMISSION_REJECTED, "Too many transfers"),
Map.entry(FileserverErrorCode.PARTIAL_WRITE, "Transfer did not complete"),
Map.entry(
FileserverErrorCode.AMBIGUOUS_COMPLETION, "Completion could not be confirmed"),
Map.entry(
FileserverErrorCode.ATOMIC_PUBLISH_UNSUPPORTED,
"Storage cannot publish atomically"),
Map.entry(FileserverErrorCode.STORAGE_UNAVAILABLE, "Storage is unavailable"),
Map.entry(FileserverErrorCode.TRANSFER_TIMEOUT, "Transfer timed out"),
Map.entry(FileserverErrorCode.STORAGE_FULL, "Storage is full")));
private FileserverProblemTitles() {}
static String titleOf(FileserverErrorCode code) {
return TITLES.getOrDefault(code, "Request failed");
}
}
@@ -1,150 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.reactive;
import java.io.IOException;
import java.io.InterruptedIOException;
import java.nio.ByteBuffer;
import java.nio.channels.ReadableByteChannel;
import java.util.concurrent.BlockingQueue;
import java.util.concurrent.LinkedBlockingQueue;
import java.util.concurrent.atomic.AtomicBoolean;
import org.reactivestreams.Subscriber;
import org.reactivestreams.Subscription;
import org.springframework.core.io.buffer.DataBuffer;
import org.springframework.core.io.buffer.DataBufferUtils;
import reactor.core.publisher.Flux;
/**
* Bridges a reactive body into the blocking channel the content store expects.
*
* <p>Two properties matter and are enforced structurally rather than by discipline. First, every
* pooled {@link DataBuffer} this subscriber observes is copied and released inside {@code onNext},
* so no buffer can survive a later cancellation or error path — there is no path where a pooled
* buffer is still owned by this class. Second, demand is replenished one item at a time as the
* reader consumes, so the number of buffers in flight never exceeds the configured prefetch no
* matter how fast the client sends.
*/
final class DataBufferByteChannel implements ReadableByteChannel, Subscriber<DataBuffer> {
/**
* Sentinel meaning the upstream finished.
*
* <p>It is a distinct type rather than an empty buffer so termination is decided by what the
* queue holds, never by comparing buffer identities.
*/
private static final Object END_OF_STREAM = new Object();
private final BlockingQueue<Object> ready = new LinkedBlockingQueue<>();
private final AtomicBoolean open = new AtomicBoolean(true);
private final int prefetch;
private volatile Subscription subscription;
private volatile Throwable failure;
private ByteBuffer current;
private DataBufferByteChannel(int prefetch) {
this.prefetch = prefetch;
}
/**
* Subscribes to {@code body} and exposes it as a blocking channel bounded by {@code prefetch}.
*/
static DataBufferByteChannel subscribeTo(Flux<DataBuffer> body, int prefetch) {
if (prefetch < 1) {
throw new IllegalArgumentException("prefetch must be positive");
}
DataBufferByteChannel channel = new DataBufferByteChannel(prefetch);
body.subscribe(channel);
return channel;
}
@Override
public void onSubscribe(Subscription subscription) {
this.subscription = subscription;
subscription.request(prefetch);
}
@Override
public void onNext(DataBuffer buffer) {
try {
ByteBuffer copy = ByteBuffer.allocate(buffer.readableByteCount());
buffer.toByteBuffer(copy);
copy.rewind();
ready.add(copy);
} finally {
DataBufferUtils.release(buffer);
}
}
@Override
public void onError(Throwable throwable) {
this.failure = throwable;
ready.add(END_OF_STREAM);
}
@Override
public void onComplete() {
ready.add(END_OF_STREAM);
}
@Override
public int read(ByteBuffer destination) throws IOException {
if (!open.get()) {
throw new IOException("channel is closed");
}
if (current == null || !current.hasRemaining()) {
current = nextChunk();
if (current == null) {
return -1;
}
}
int transferred = Math.min(destination.remaining(), current.remaining());
int limit = current.limit();
current.limit(current.position() + transferred);
destination.put(current);
current.limit(limit);
return transferred;
}
/**
* Waits for the next chunk and replenishes exactly one unit of demand.
*
* <p>Requesting only after a chunk has been consumed is what bounds the in-flight buffer count;
* an unconditional {@code request(Long.MAX_VALUE)} would let a fast client outrun the disk.
*/
private ByteBuffer nextChunk() throws IOException {
Object taken;
try {
taken = ready.take();
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
throw new InterruptedIOException("interrupted while waiting for the request body");
}
if (!(taken instanceof ByteBuffer chunk)) {
if (failure != null) {
throw new IOException("request body failed", failure);
}
return null;
}
Subscription pending = subscription;
if (pending != null) {
pending.request(1);
}
return chunk;
}
@Override
public boolean isOpen() {
return open.get();
}
@Override
public void close() {
if (open.compareAndSet(true, false)) {
Subscription current = subscription;
if (current != null) {
current.cancel();
}
ready.clear();
}
}
}
@@ -1,153 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.reactive;
import dev.caskeleton.adapter.inbound.web.fileserver.dto.UploadedFileResponse;
import dev.caskeleton.adapter.inbound.web.fileserver.http.HttpConditionalRequest;
import dev.caskeleton.adapter.inbound.web.fileserver.http.HttpDownloadDecision;
import dev.caskeleton.adapter.inbound.web.fileserver.http.HttpDownloadPlanner;
import dev.caskeleton.application.fileserver.api.ByteRange;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.download.DownloadApplicationService;
import dev.caskeleton.application.fileserver.download.DownloadDescriptor;
import dev.caskeleton.application.fileserver.download.DownloadRequest;
import java.nio.channels.ReadableByteChannel;
import java.time.Instant;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeParseException;
import java.util.Optional;
import org.springframework.core.io.buffer.DataBuffer;
import org.springframework.core.io.buffer.DataBufferUtils;
import org.springframework.core.io.buffer.DefaultDataBufferFactory;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpMethod;
import org.springframework.http.MediaType;
import org.springframework.web.reactive.function.server.ServerRequest;
import org.springframework.web.reactive.function.server.ServerResponse;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;
/**
* Reactive counterpart of the MVC download endpoints.
*
* <p>The decision comes from the same application service the servlet path uses, so status codes
* and headers cannot drift. Content is read on the dedicated I/O scheduler in bounded chunks, and
* every emitted buffer is released on cancellation — a client that disconnects mid-transfer must
* not leak the pooled buffers already in flight.
*/
public final class FileDownloadHandler {
private static final int CHUNK_BYTES = 64 * 1024;
private final DownloadApplicationService downloadService;
private final ReactiveDownloadResponseWriter responseWriter;
private final HttpDownloadPlanner downloadPlanner;
private final FileserverIoScheduler ioScheduler;
public FileDownloadHandler(
DownloadApplicationService downloadService,
ReactiveDownloadResponseWriter responseWriter,
HttpDownloadPlanner downloadPlanner,
FileserverIoScheduler ioScheduler) {
this.downloadService = downloadService;
this.responseWriter = responseWriter;
this.downloadPlanner = downloadPlanner;
this.ioScheduler = ioScheduler;
}
public Mono<ServerResponse> describe(ServerRequest request) {
FileId fileId = FileId.parse(request.pathVariable("fileId"));
return Mono.fromCallable(() -> downloadService.describeFile(fileId, contextOf(request)))
.subscribeOn(ioScheduler.scheduler())
.flatMap(
view ->
ServerResponse.ok()
.contentType(MediaType.APPLICATION_JSON)
.bodyValue(UploadedFileResponse.from(view)));
}
public Mono<ServerResponse> download(ServerRequest request) {
FileId fileId = FileId.parse(request.pathVariable("fileId"));
boolean headOnly = HttpMethod.HEAD.equals(request.method());
boolean inline = request.queryParam("inline").map(Boolean::parseBoolean).orElse(false);
RequestContext context = contextOf(request);
HttpConditionalRequest conditional = conditionalOf(request, headOnly);
return Mono.fromCallable(() -> downloadService.describe(new DownloadRequest(fileId), context))
.subscribeOn(ioScheduler.scheduler())
.map(descriptor -> downloadPlanner.plan(descriptor, conditional, inline))
.flatMap(this::respond);
}
private Mono<ServerResponse> respond(HttpDownloadDecision decision) {
ServerResponse.BodyBuilder builder =
ServerResponse.status(decision.status())
.headers(headers -> headers.putAll(responseWriter.headersFor(decision)));
if (!decision.bodyExpected()) {
return builder.build();
}
if (decision.descriptor().representation().length() == 0) {
return builder.body(Flux.empty(), DataBuffer.class);
}
return builder.body(content(decision), DataBuffer.class);
}
/**
* Streams the described bytes with bounded demand.
*
* <p>{@code readByteChannel} closes the channel and releases every buffer it emitted when the
* subscriber cancels, which is the behaviour a disconnecting client depends on.
*/
private Flux<DataBuffer> content(HttpDownloadDecision decision) {
ByteRange range = decision.payloadRange();
return DataBufferUtils.readByteChannel(
() -> openContent(decision.descriptor(), range),
DefaultDataBufferFactory.sharedInstance,
CHUNK_BYTES)
.subscribeOn(ioScheduler.scheduler());
}
private ReadableByteChannel openContent(DownloadDescriptor descriptor, ByteRange range) {
return downloadService.openContent(descriptor, range);
}
private static HttpConditionalRequest conditionalOf(ServerRequest request, boolean headOnly) {
HttpHeaders headers = request.headers().asHttpHeaders();
return new HttpConditionalRequest(
header(headers, HttpHeaders.IF_MATCH),
header(headers, HttpHeaders.IF_NONE_MATCH),
date(headers, HttpHeaders.IF_MODIFIED_SINCE),
date(headers, HttpHeaders.IF_UNMODIFIED_SINCE),
header(headers, HttpHeaders.IF_RANGE),
header(headers, HttpHeaders.RANGE),
headOnly);
}
private static Optional<String> header(HttpHeaders headers, String name) {
String value = headers.getFirst(name);
return value == null || value.isBlank() ? Optional.empty() : Optional.of(value);
}
/** A malformed HTTP-date is ignored rather than rejected, as RFC 9110 requires. */
private static Optional<Instant> date(HttpHeaders headers, String name) {
Optional<String> raw = header(headers, name);
if (raw.isEmpty()) {
return Optional.empty();
}
try {
return Optional.of(
ZonedDateTime.parse(raw.get(), DateTimeFormatter.RFC_1123_DATE_TIME).toInstant());
} catch (DateTimeParseException malformed) {
return Optional.empty();
}
}
private static RequestContext contextOf(ServerRequest request) {
return request
.attribute(ReactiveFileserverAttributes.REQUEST_CONTEXT)
.filter(RequestContext.class::isInstance)
.map(RequestContext.class::cast)
.orElseThrow(
() -> new IllegalStateException("fileserver request context attribute is missing"));
}
}
@@ -1,165 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.reactive;
import dev.caskeleton.adapter.inbound.web.fileserver.config.FileserverWebProperties;
import dev.caskeleton.adapter.inbound.web.fileserver.dto.BatchUploadItemResult;
import dev.caskeleton.adapter.inbound.web.fileserver.dto.BatchUploadResponse;
import dev.caskeleton.adapter.inbound.web.fileserver.dto.UploadedFileResponse;
import dev.caskeleton.adapter.inbound.web.fileserver.mapper.RawUploadRequestMapper;
import dev.caskeleton.adapter.inbound.web.fileserver.mapper.UploadIntent;
import dev.caskeleton.application.fileserver.api.FileState;
import dev.caskeleton.application.fileserver.api.error.FileserverException;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.api.transfer.UploadMode;
import dev.caskeleton.application.fileserver.upload.CreateUploadRequest;
import dev.caskeleton.application.fileserver.upload.FileView;
import dev.caskeleton.application.fileserver.upload.FinalizeUploadRequest;
import java.net.URI;
import java.time.Clock;
import java.util.List;
import java.util.Locale;
import java.util.Optional;
import java.util.OptionalLong;
import org.springframework.core.io.buffer.DataBuffer;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.codec.multipart.PartEvent;
import org.springframework.web.reactive.function.server.ServerRequest;
import org.springframework.web.reactive.function.server.ServerResponse;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;
/**
* Reactive counterpart of the MVC upload endpoints.
*
* <p>It answers the same statuses and headers as the servlet path because both build their response
* from the same {@link FileView}. The body is never joined into a single buffer; each request is
* consumed as a bounded stream so a large upload does not scale with heap.
*/
public final class FileUploadHandler {
private final ReactiveUploadApplicationService uploadService;
private final PartEventUploadReader partReader;
private final FileserverWebProperties properties;
private final Clock clock;
public FileUploadHandler(
ReactiveUploadApplicationService uploadService,
PartEventUploadReader partReader,
FileserverWebProperties properties,
Clock clock) {
this.uploadService = uploadService;
this.partReader = partReader;
this.properties = properties;
this.clock = clock;
}
/** Raw streaming upload; the whole request body is the file. */
public Mono<ServerResponse> uploadRaw(ServerRequest request) {
UploadIntent intent = rawIntent(request);
RequestContext context = contextOf(request);
return uploadService
.upload(
createRequest(intent),
request.bodyToFlux(DataBuffer.class),
declaredLength(intent),
new FinalizeUploadRequest(intent.expectedSha256(), false),
context)
.flatMap(FileUploadHandler::created);
}
/** Multipart single upload; only the first file part is consumed. */
public Mono<ServerResponse> uploadMultipart(ServerRequest request) {
RequestContext context = contextOf(request);
return partReader
.forEachPart(
request.bodyToFlux(PartEvent.class),
(intent, content) -> uploadOne(intent, content, context))
.next()
.flatMap(FileUploadHandler::created);
}
/** Bounded multi-file upload; each part answers independently and none rolls back a sibling. */
public Mono<ServerResponse> uploadBatch(ServerRequest request) {
RequestContext context = contextOf(request);
return partReader
.forEachPart(
request.bodyToFlux(PartEvent.class),
(intent, content) ->
uploadOne(intent, content, context)
.map(view -> BatchUploadItemResult.accepted(intent.originalFilename(), view))
.onErrorResume(
FileserverException.class,
failure ->
Mono.just(
BatchUploadItemResult.rejected(
intent.originalFilename(), failure.code()))))
.collectList()
.flatMap(
results ->
ServerResponse.ok()
.contentType(MediaType.APPLICATION_JSON)
.bodyValue(new BatchUploadResponse(List.copyOf(results))));
}
private Mono<FileView> uploadOne(
UploadIntent intent, Flux<DataBuffer> content, RequestContext context) {
return uploadService.upload(
createRequest(intent),
content,
declaredLength(intent),
new FinalizeUploadRequest(intent.expectedSha256(), false),
context);
}
private CreateUploadRequest createRequest(UploadIntent intent) {
return new CreateUploadRequest(
properties.defaultNamespace(),
intent.originalFilename(),
intent.claimedMediaType(),
intent.declaredLength(),
intent.expectedSha256(),
UploadMode.SINGLE_SHOT,
clock.instant().plus(properties.uploadTtl()));
}
/** READY is a finished object; anything still under verification is accepted, not created. */
private static Mono<ServerResponse> created(FileView view) {
HttpStatus status = view.state() == FileState.READY ? HttpStatus.CREATED : HttpStatus.ACCEPTED;
return ServerResponse.status(status)
.location(URI.create("/v1/files/" + view.fileId().canonicalText()))
.contentType(MediaType.APPLICATION_JSON)
.bodyValue(UploadedFileResponse.from(view));
}
private static UploadIntent rawIntent(ServerRequest request) {
HttpHeaders headers = request.headers().asHttpHeaders();
String filename = headers.getFirst(RawUploadRequestMapper.FILENAME_HEADER);
String digest = headers.getFirst(RawUploadRequestMapper.DIGEST_HEADER);
long declared = headers.getContentLength();
return new UploadIntent(
filename == null || filename.isBlank() ? "upload.bin" : filename,
Optional.ofNullable(headers.getContentType()).map(Object::toString),
declared < 0 ? OptionalLong.empty() : OptionalLong.of(declared),
Optional.ofNullable(digest).map(value -> value.trim().toLowerCase(Locale.ROOT)));
}
/**
* Context for one reactive request.
*
* <p>The reactive stack has no thread-bound security context, so the attribute the router filter
* publishes is the only correct source here.
*/
private static RequestContext contextOf(ServerRequest request) {
return request
.attribute(ReactiveFileserverAttributes.REQUEST_CONTEXT)
.filter(RequestContext.class::isInstance)
.map(RequestContext.class::cast)
.orElseThrow(
() -> new IllegalStateException("fileserver request context attribute is missing"));
}
private static long declaredLength(UploadIntent intent) {
return intent.declaredLength().isPresent() ? intent.declaredLength().getAsLong() : -1;
}
}
@@ -1,36 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.reactive;
import reactor.core.scheduler.Scheduler;
import reactor.core.scheduler.Schedulers;
/**
* The only place reactive Fileserver work is allowed to block.
*
* <p>The local content store is a blocking filesystem client. Running it on a Reactor Netty event
* loop would stall every other connection the loop owns, so all of it is offloaded here — a bounded
* pool with a bounded queue, which turns a filesystem stall into backpressure instead of an
* unbounded thread or task pile-up.
*/
public final class FileserverIoScheduler implements AutoCloseable {
private static final int TTL_SECONDS = 60;
private final Scheduler scheduler;
public FileserverIoScheduler(int workers, int queueCapacity) {
if (workers < 1 || queueCapacity < 1) {
throw new IllegalArgumentException("workers and queueCapacity must be positive");
}
this.scheduler =
Schedulers.newBoundedElastic(workers, queueCapacity, "fileserver-io", TTL_SECONDS, false);
}
public Scheduler scheduler() {
return scheduler;
}
@Override
public void close() {
scheduler.dispose();
}
}
@@ -1,110 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.reactive;
import dev.caskeleton.adapter.inbound.web.fileserver.config.FileserverWebProperties;
import dev.caskeleton.adapter.inbound.web.fileserver.config.TransferExecutorProperties;
import dev.caskeleton.adapter.inbound.web.fileserver.http.HttpDownloadPlanner;
import dev.caskeleton.adapter.inbound.web.fileserver.problem.FileserverProblemFactory;
import dev.caskeleton.adapter.inbound.web.fileserver.security.FileserverRequestContextFactory;
import dev.caskeleton.application.fileserver.download.DownloadApplicationService;
import dev.caskeleton.application.fileserver.upload.SingleShotUploadService;
import java.time.Clock;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.autoconfigure.condition.ConditionalOnWebApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.reactive.function.server.RouterFunction;
import org.springframework.web.reactive.function.server.ServerResponse;
/**
* Registers the reactive transport so it exists at runtime, not only in the source tree.
*
* <p>The router, the handlers and the part reader were written and tested, and nothing ever built
* them: no bean, no route, no dispatcher entry. A deployment that switched the platform on got the
* servlet transport and a set of classes that were never instantiated, while the support matrix
* advertised WebFlux as a supported profile.
*
* <p>The wiring lives in this module rather than in the composition root because {@code
* spring-webflux} is an {@code implementation} dependency here and deliberately invisible to {@code
* app-bootstrap} — the root cannot name {@link RouterFunction} at all, which is the mechanical
* reason the wiring was never written in the first place.
*
* <p>It stays inert in the shipped composition. This module also puts {@code DispatcherServlet} on
* the classpath, so Boot's application-type deduction resolves SERVLET and the condition below is
* false; a fork that removes the servlet stack and adds a reactive server gets working routes
* without touching this class. That is the honest support level, and the matrix says {@code
* Experimental} for exactly this reason.
*/
@Configuration(proxyBeanMethods = false)
@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.REACTIVE)
@ConditionalOnProperty(prefix = "app.fileserver-platform", name = "enabled", havingValue = "true")
public class FileserverReactiveConfiguration {
/**
* Blocking storage work never runs on the event loop.
*
* <p>Bounded by the same transfer settings the servlet pool uses: an unbounded elastic scheduler
* would trade an event-loop stall for an unbounded thread count, which is the worse of the two.
*/
@Bean(destroyMethod = "close")
@ConditionalOnMissingBean
public FileserverIoScheduler fileserverIoScheduler(TransferExecutorProperties properties) {
return new FileserverIoScheduler(properties.maxSize(), properties.queueCapacity());
}
@Bean
@ConditionalOnMissingBean
public PartEventUploadReader fileserverPartEventUploadReader(FileserverWebProperties properties) {
return new PartEventUploadReader(properties.maxBatchParts());
}
@Bean
@ConditionalOnMissingBean
public ReactiveUploadApplicationService fileserverReactiveUploadService(
SingleShotUploadService uploadService, FileserverIoScheduler ioScheduler) {
return new ReactiveUploadApplicationService(uploadService, ioScheduler);
}
@Bean
@ConditionalOnMissingBean
public ReactiveDownloadResponseWriter fileserverReactiveDownloadResponseWriter() {
return new ReactiveDownloadResponseWriter();
}
@Bean
@ConditionalOnMissingBean
public FileUploadHandler fileserverReactiveUploadHandler(
ReactiveUploadApplicationService uploadService,
PartEventUploadReader partReader,
FileserverWebProperties properties,
Clock clock) {
return new FileUploadHandler(uploadService, partReader, properties, clock);
}
@Bean
@ConditionalOnMissingBean
public FileDownloadHandler fileserverReactiveDownloadHandler(
DownloadApplicationService downloadService,
ReactiveDownloadResponseWriter responseWriter,
HttpDownloadPlanner downloadPlanner,
FileserverIoScheduler ioScheduler) {
return new FileDownloadHandler(downloadService, responseWriter, downloadPlanner, ioScheduler);
}
/**
* The routes themselves.
*
* <p>A {@link RouterFunction} bean is how WebFlux discovers routes; the factory existed but
* nothing ever called {@code routes()} on it.
*/
@Bean
public RouterFunction<ServerResponse> fileserverRoutes(
FileUploadHandler uploadHandler,
FileDownloadHandler downloadHandler,
FileserverProblemFactory problemFactory,
FileserverRequestContextFactory contextFactory) {
return new FileserverRouterFactory(
uploadHandler, downloadHandler, problemFactory, contextFactory::current)
.routes();
}
}
@@ -1,75 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.reactive;
import dev.caskeleton.adapter.inbound.web.fileserver.problem.FileserverProblem;
import dev.caskeleton.adapter.inbound.web.fileserver.problem.FileserverProblemFactory;
import dev.caskeleton.adapter.inbound.web.fileserver.problem.FileserverProblemHeaders;
import dev.caskeleton.application.fileserver.api.error.FileserverException;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import java.util.function.Supplier;
import org.springframework.http.MediaType;
import org.springframework.web.reactive.function.server.RequestPredicates;
import org.springframework.web.reactive.function.server.RouterFunction;
import org.springframework.web.reactive.function.server.RouterFunctions;
import org.springframework.web.reactive.function.server.ServerResponse;
import reactor.core.publisher.Mono;
/**
* Wires the reactive Fileserver routes and their failure translation.
*
* <p>The colon-verb paths are declared literally rather than nested under a prefix: {@code
* /v1/files:raw} is one path segment, and a nested route would silently turn it into {@code
* /v1/files/:raw}.
*
* <p>The failure filter lives here rather than in a global handler so the reactive routes translate
* Fileserver failures to exactly the same statuses and problem documents as the servlet advice.
*/
public final class FileserverRouterFactory {
private final FileUploadHandler uploadHandler;
private final FileDownloadHandler downloadHandler;
private final FileserverProblemFactory problemFactory;
private final Supplier<RequestContext> contextSupplier;
public FileserverRouterFactory(
FileUploadHandler uploadHandler,
FileDownloadHandler downloadHandler,
FileserverProblemFactory problemFactory,
Supplier<RequestContext> contextSupplier) {
this.uploadHandler = uploadHandler;
this.downloadHandler = downloadHandler;
this.problemFactory = problemFactory;
this.contextSupplier = contextSupplier;
}
public RouterFunction<ServerResponse> routes() {
return RouterFunctions.route()
.POST("/v1/files:raw", uploadHandler::uploadRaw)
.POST("/v1/files:batch", uploadHandler::uploadBatch)
.POST("/v1/files", uploadHandler::uploadMultipart)
.GET("/v1/files/{fileId}/content", downloadHandler::download)
.route(RequestPredicates.HEAD("/v1/files/{fileId}/content"), downloadHandler::download)
.GET("/v1/files/{fileId}", downloadHandler::describe)
.before(
request -> {
request
.attributes()
.put(ReactiveFileserverAttributes.REQUEST_CONTEXT, contextSupplier.get());
return request;
})
.onError(FileserverException.class, this::toProblem)
.build();
}
private Mono<ServerResponse> toProblem(
Throwable throwable, org.springframework.web.reactive.function.server.ServerRequest request) {
FileserverException failure = (FileserverException) throwable;
FileserverProblem problem =
problemFactory.create(failure.context(), request.requestPath().value());
ServerResponse.BodyBuilder builder =
ServerResponse.status(problem.status()).contentType(MediaType.APPLICATION_PROBLEM_JSON);
// Same table the servlet advice uses. Retry-After was missing here, so an identical failure
// told a servlet client to come back in a second and a reactive client nothing at all.
FileserverProblemHeaders.of(failure).forEach(builder::header);
return builder.bodyValue(problem);
}
}
@@ -1,93 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.reactive;
import dev.caskeleton.adapter.inbound.web.fileserver.mapper.UploadIntent;
import dev.caskeleton.application.fileserver.api.error.FileTooLargeException;
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
import dev.caskeleton.application.fileserver.api.error.FileserverFailureContext;
import java.util.Optional;
import java.util.OptionalLong;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.function.BiFunction;
import org.springframework.core.io.buffer.DataBuffer;
import org.springframework.core.io.buffer.DataBufferUtils;
import org.springframework.http.codec.multipart.FilePartEvent;
import org.springframework.http.codec.multipart.PartEvent;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;
/**
* Reads a multipart body as a sequence of part events, one part at a time.
*
* <p>Sequential windowing is the contract, not an implementation detail: part events arrive on one
* stream, so consuming two windows concurrently would interleave the bytes of different files. The
* part-count ceiling is enforced as windows arrive, so an oversized batch is rejected before the
* remaining parts are read rather than after.
*
* <p>A non-file part is drained and released rather than ignored — an ignored window would leave
* its pooled buffers unreferenced and unreleased.
*/
public final class PartEventUploadReader {
private static final String FALLBACK_FILENAME = "upload.bin";
private final int maxParts;
public PartEventUploadReader(int maxParts) {
if (maxParts < 1) {
throw new IllegalArgumentException("maxParts must be positive");
}
this.maxParts = maxParts;
}
/**
* Applies {@code handler} to each file part, in order.
*
* <p>{@code concatMap} rather than {@code flatMap} is required: it subscribes to the next window
* only after the previous one terminates, which is what keeps parts from interleaving.
*/
public <T> Flux<T> forEachPart(
Flux<PartEvent> events, BiFunction<UploadIntent, Flux<DataBuffer>, Mono<T>> handler) {
AtomicInteger seen = new AtomicInteger();
return events
.windowUntil(PartEvent::isLast)
.concatMap(
window ->
window.switchOnFirst((signal, rest) -> onePart(signal.get(), rest, seen, handler)));
}
private <T> Flux<T> onePart(
PartEvent first,
Flux<PartEvent> rest,
AtomicInteger seen,
BiFunction<UploadIntent, Flux<DataBuffer>, Mono<T>> handler) {
if (first == null) {
return Flux.empty();
}
if (seen.incrementAndGet() > maxParts) {
return drain(rest).thenMany(Flux.error(tooManyParts()));
}
if (!(first instanceof FilePartEvent filePart)) {
return drain(rest).thenMany(Flux.empty());
}
return handler.apply(intentOf(filePart), rest.map(PartEvent::content)).flux();
}
private static Mono<Void> drain(Flux<PartEvent> events) {
return events.doOnNext(event -> DataBufferUtils.release(event.content())).then();
}
private static UploadIntent intentOf(FilePartEvent part) {
String filename = part.filename();
return new UploadIntent(
filename == null || filename.isBlank() ? FALLBACK_FILENAME : filename,
Optional.ofNullable(part.headers().getContentType()).map(Object::toString),
OptionalLong.empty(),
Optional.empty());
}
private static FileTooLargeException tooManyParts() {
return new FileTooLargeException(
"batch exceeds the configured maximum part count",
FileserverFailureContext.of(FileserverErrorCode.FILE_TOO_LARGE, false));
}
}
@@ -1,48 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.reactive;
import dev.caskeleton.adapter.inbound.web.fileserver.http.HttpDownloadDecision;
import dev.caskeleton.adapter.inbound.web.fileserver.http.HttpDownloadOutcome;
import dev.caskeleton.application.fileserver.api.ByteRange;
import java.time.ZoneOffset;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;
import org.springframework.http.HttpHeaders;
/** Renders the shared HTTP download decision as WebFlux headers. */
public final class ReactiveDownloadResponseWriter {
public static final String CONTENT_TYPE_OPTIONS = "X-Content-Type-Options";
private static final DateTimeFormatter HTTP_DATE =
DateTimeFormatter.RFC_1123_DATE_TIME.withZone(ZoneOffset.UTC);
public HttpHeaders headersFor(HttpDownloadDecision decision) {
HttpHeaders headers = new HttpHeaders();
headers.set(HttpHeaders.ETAG, decision.strongEtag());
headers.set(
HttpHeaders.LAST_MODIFIED,
HTTP_DATE.format(
ZonedDateTime.ofInstant(
decision.descriptor().representation().publishedAt(), ZoneOffset.UTC)));
headers.set(HttpHeaders.ACCEPT_RANGES, "bytes");
headers.set(HttpHeaders.CACHE_CONTROL, decision.cacheControl());
headers.set(CONTENT_TYPE_OPTIONS, "nosniff");
if (decision.outcome() == HttpDownloadOutcome.NOT_MODIFIED) {
return headers;
}
headers.set(HttpHeaders.CONTENT_TYPE, decision.descriptor().representation().mediaType());
headers.set(HttpHeaders.CONTENT_DISPOSITION, decision.contentDisposition());
headers.set(HttpHeaders.CONTENT_LENGTH, String.valueOf(decision.payloadLength()));
if (decision.isPartial()) {
ByteRange range = decision.singleRange();
headers.set(
HttpHeaders.CONTENT_RANGE,
"bytes "
+ range.startInclusive()
+ "-"
+ range.endInclusive()
+ "/"
+ decision.descriptor().representation().length());
}
return headers;
}
}
@@ -1,19 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.reactive;
/**
* Names of the request attributes the reactive Fileserver routes rely on.
*
* <p>The reactive stack carries no thread-bound security context, so the caller identity has to
* travel with the exchange rather than through a holder.
*/
public final class ReactiveFileserverAttributes {
/**
* Attribute holding the resolved {@code RequestContext}.
*
* <p>Published by the router filter, consumed by the handlers.
*/
public static final String REQUEST_CONTEXT = "dev.caskeleton.fileserver.reactive.requestContext";
private ReactiveFileserverAttributes() {}
}
@@ -1,58 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.reactive;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.upload.CreateUploadRequest;
import dev.caskeleton.application.fileserver.upload.FileView;
import dev.caskeleton.application.fileserver.upload.FinalizeUploadRequest;
import dev.caskeleton.application.fileserver.upload.SingleShotUploadService;
import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.channels.ReadableByteChannel;
import org.springframework.core.io.buffer.DataBuffer;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;
/**
* Runs the blocking single-shot upload against a reactive body.
*
* <p>The whole body is never joined. Instead the reactive stream is turned into a bounded blocking
* channel and the upload is scheduled on the dedicated I/O pool, so a multi-gigabyte upload costs a
* fixed number of in-flight buffers and never touches an event-loop thread.
*/
public final class ReactiveUploadApplicationService {
/** In-flight buffer ceiling; also the initial reactive demand. */
static final int PREFETCH_BUFFERS = 8;
private final SingleShotUploadService uploadService;
private final FileserverIoScheduler ioScheduler;
public ReactiveUploadApplicationService(
SingleShotUploadService uploadService, FileserverIoScheduler ioScheduler) {
this.uploadService = uploadService;
this.ioScheduler = ioScheduler;
}
public Mono<FileView> upload(
CreateUploadRequest request,
Flux<DataBuffer> body,
long contentLength,
FinalizeUploadRequest finalizeRequest,
RequestContext context) {
return Mono.fromCallable(() -> transfer(request, body, contentLength, finalizeRequest, context))
.subscribeOn(ioScheduler.scheduler());
}
private FileView transfer(
CreateUploadRequest request,
Flux<DataBuffer> body,
long contentLength,
FinalizeUploadRequest finalizeRequest,
RequestContext context) {
try (ReadableByteChannel channel = DataBufferByteChannel.subscribeTo(body, PREFETCH_BUFFERS)) {
return uploadService.upload(request, channel, contentLength, finalizeRequest, context);
} catch (IOException exception) {
throw new UncheckedIOException(exception);
}
}
}
@@ -1,70 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.security;
import dev.caskeleton.adapter.inbound.web.auth.AuthenticatedPrincipal;
import dev.caskeleton.adapter.inbound.web.observability.MdcKeys;
import dev.caskeleton.application.fileserver.api.security.FileAccessSubject;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import java.util.LinkedHashSet;
import java.util.Set;
import org.slf4j.MDC;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.core.context.SecurityContextHolder;
/**
* Builds the framework-free {@link RequestContext} the Fileserver expects.
*
* <p>This is the single place a Spring Security type is translated into a {@link
* FileAccessSubject}; no Fileserver class below it ever sees an {@code Authentication}. An
* unauthenticated caller becomes the anonymous subject rather than a null one, so the injected
* access policy — not this adapter — decides whether that is allowed.
*/
public final class FileserverRequestContextFactory {
private static final String UNKNOWN_TRACE = "untraced";
private final String instanceId;
public FileserverRequestContextFactory(String instanceId) {
if (instanceId == null || instanceId.isBlank()) {
throw new IllegalArgumentException("instanceId must be non-blank");
}
this.instanceId = instanceId;
}
/** Context for the request currently bound to this thread. */
public RequestContext current() {
return new RequestContext(subject(), traceId(), instanceId);
}
private static FileAccessSubject subject() {
Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
if (authentication == null || !authentication.isAuthenticated()) {
return FileAccessSubject.anonymous();
}
Object principal = authentication.getPrincipal();
if (principal instanceof AuthenticatedPrincipal authenticated) {
return FileAccessSubject.of(authenticated.idpUserId(), authenticated.roles());
}
return FileAccessSubject.of(authentication.getName(), authorities(authentication));
}
private static Set<String> authorities(Authentication authentication) {
Set<String> roles = new LinkedHashSet<>();
for (GrantedAuthority authority : authentication.getAuthorities()) {
roles.add(authority.getAuthority());
}
return roles;
}
/**
* Correlation id for the current request.
*
* <p>The MDC value is set by the request-logging filter. A blank value degrades to a constant
* rather than a generated one: identifier generation at this layer is a different concern.
*/
private static String traceId() {
String traceId = MDC.get(MdcKeys.TRACE_ID);
return traceId == null || traceId.isBlank() ? UNKNOWN_TRACE : traceId;
}
}
@@ -1,53 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.tus;
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
import dev.caskeleton.application.fileserver.api.error.FileserverFailureContext;
import dev.caskeleton.application.fileserver.api.error.IntegrityMismatchException;
import dev.caskeleton.application.fileserver.api.error.MalformedRequestException;
import java.util.Base64;
import java.util.HexFormat;
import java.util.Locale;
import java.util.Set;
/**
* Verifies a tus {@code Upload-Checksum} against the digest the server computed.
*
* <p>The client value is only ever compared with the server's own digest; it never replaces it. A
* checksum the server did not compute proves nothing, and accepting one would let a client declare
* corrupt bytes to be intact.
*/
public final class TusChecksumVerifier {
private static final Set<String> SUPPORTED = Set.of("sha256");
/**
* Compares a checksum header with the server digest.
*
* @param header the raw {@code algorithm base64value} pair
* @param serverDigestHex the lowercase hex digest the server computed over the same bytes
*/
public void verify(String header, String serverDigestHex) {
String[] parts = header.trim().split(" ", 2);
if (parts.length != 2) {
throw MalformedRequestException.of("Upload-Checksum must be an algorithm and a base64 value");
}
String algorithm = parts[0].toLowerCase(Locale.ROOT);
if (!SUPPORTED.contains(algorithm)) {
throw MalformedRequestException.of("unsupported checksum algorithm");
}
byte[] claimed;
try {
claimed = Base64.getDecoder().decode(parts[1].trim());
} catch (IllegalArgumentException malformed) {
throw new MalformedRequestException(
"Upload-Checksum value is not valid base64",
malformed,
FileserverFailureContext.of(FileserverErrorCode.BAD_REQUEST, false));
}
if (!HexFormat.of().formatHex(claimed).equals(serverDigestHex)) {
throw new IntegrityMismatchException(
"client checksum does not match the server-computed digest",
FileserverFailureContext.of(FileserverErrorCode.INTEGRITY_MISMATCH, false));
}
}
}
@@ -1,209 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.tus;
import dev.caskeleton.adapter.inbound.web.core.OwnsAbsoluteWebRoute;
import dev.caskeleton.adapter.inbound.web.fileserver.config.BlockingTransferExecutor;
import dev.caskeleton.adapter.inbound.web.fileserver.config.FileserverWebProperties;
import dev.caskeleton.adapter.inbound.web.fileserver.security.FileserverRequestContextFactory;
import dev.caskeleton.application.fileserver.api.UploadId;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.api.transfer.UploadMode;
import dev.caskeleton.application.fileserver.upload.AppendUploadResult;
import dev.caskeleton.application.fileserver.upload.CreateUploadRequest;
import dev.caskeleton.application.fileserver.upload.FinalizeUploadRequest;
import dev.caskeleton.application.fileserver.upload.FinalizeUploadService;
import dev.caskeleton.application.fileserver.upload.UploadApplicationService;
import dev.caskeleton.application.fileserver.upload.UploadSessionView;
import jakarta.servlet.http.HttpServletRequest;
import java.io.IOException;
import java.io.InputStream;
import java.net.URI;
import java.nio.channels.Channels;
import java.time.Clock;
import java.time.Instant;
import java.time.ZoneOffset;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;
import java.util.Optional;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.http.HttpHeaders;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.PatchMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
/**
* tus 1.0 Stable resumable uploads.
*
* <p>This is a protocol mapping, not a second upload implementation: creation, append, and
* finalization all go through the same application services the plain HTTP endpoints use, so the
* offset, lease, and digest guarantees are identical no matter which protocol a client speaks.
*
* <p>Every protocol request validates {@code Tus-Resumable} first. An offset mismatch answers
* {@code 409} without touching the body, which is what makes a mismatched resume safe to retry.
*/
@OwnsAbsoluteWebRoute
@RestController
@ConditionalOnProperty(
prefix = "app.fileserver-platform",
name = {"enabled", "tus.enabled"},
havingValue = "true")
public class TusController {
private static final DateTimeFormatter HTTP_DATE =
DateTimeFormatter.RFC_1123_DATE_TIME.withZone(ZoneOffset.UTC);
private final UploadApplicationService uploadService;
private final FinalizeUploadService finalizeService;
private final TusRequestParser parser;
private final TusChecksumVerifier checksumVerifier;
private final FileserverRequestContextFactory contextFactory;
private final BlockingTransferExecutor transferExecutor;
private final FileserverWebProperties webProperties;
private final TusProperties tusProperties;
private final Clock clock;
public TusController(
UploadApplicationService uploadService,
FinalizeUploadService finalizeService,
TusRequestParser parser,
TusChecksumVerifier checksumVerifier,
FileserverRequestContextFactory contextFactory,
BlockingTransferExecutor transferExecutor,
FileserverWebProperties webProperties,
TusProperties tusProperties,
Clock clock) {
this.uploadService = uploadService;
this.finalizeService = finalizeService;
this.parser = parser;
this.checksumVerifier = checksumVerifier;
this.contextFactory = contextFactory;
this.transferExecutor = transferExecutor;
this.webProperties = webProperties;
this.tusProperties = tusProperties;
this.clock = clock;
}
/** Capability discovery; the only tus request that does not require a version header. */
@RequestMapping(path = "/v1/uploads", method = RequestMethod.OPTIONS)
public ResponseEntity<Void> options() {
return ResponseEntity.noContent()
.header(TusHeaders.RESUMABLE, tusProperties.version())
.header(TusHeaders.VERSION, tusProperties.version())
.header(TusHeaders.EXTENSION, tusProperties.extensionHeader())
.header(TusHeaders.MAX_SIZE, String.valueOf(tusProperties.maxSize()))
.build();
}
@PostMapping("/v1/uploads")
public ResponseEntity<Void> create(HttpServletRequest request) {
parser.requireProtocolVersion(request);
RequestContext context = contextFactory.current();
Instant expiresAt = clock.instant().plus(tusProperties.uploadTtl());
UploadSessionView created =
uploadService.create(
new CreateUploadRequest(
webProperties.defaultNamespace(),
parser.filename(request).orElse("upload.bin"),
Optional.ofNullable(parser.metadata(request).get("filetype")),
parser.declaredLength(request),
Optional.empty(),
UploadMode.RESUMABLE,
expiresAt),
context);
return ResponseEntity.created(URI.create("/v1/uploads/" + created.uploadId().canonicalText()))
.header(TusHeaders.RESUMABLE, tusProperties.version())
.header(TusHeaders.UPLOAD_OFFSET, "0")
.header(TusHeaders.UPLOAD_EXPIRES, httpDate(created.expiresAt()))
.build();
}
@RequestMapping(path = "/v1/uploads/{uploadId}", method = RequestMethod.HEAD)
public ResponseEntity<Void> status(
@PathVariable("uploadId") String uploadId, HttpServletRequest request) {
parser.requireProtocolVersion(request);
UploadSessionView session =
uploadService.status(UploadId.parse(uploadId), contextFactory.current());
ResponseEntity.HeadersBuilder<?> response =
ResponseEntity.noContent()
.header(TusHeaders.RESUMABLE, tusProperties.version())
.header(TusHeaders.UPLOAD_OFFSET, String.valueOf(session.committedOffset()))
.header(TusHeaders.UPLOAD_EXPIRES, httpDate(session.expiresAt()))
// A resumable resource must never be served from a cache: a stale offset would make the
// client resume from the wrong position.
.header(HttpHeaders.CACHE_CONTROL, "no-store");
if (session.expectedLength().isPresent()) {
response =
response.header(
TusHeaders.UPLOAD_LENGTH, String.valueOf(session.expectedLength().getAsLong()));
} else {
response = response.header(TusHeaders.UPLOAD_DEFER_LENGTH, "1");
}
return response.build();
}
// The channel wraps the servlet request body. Closing it would close the container's input
// stream, which the container owns and reuses for keep-alive; the upload must read the body
// and leave the stream alone.
@SuppressWarnings("resource")
@PatchMapping("/v1/uploads/{uploadId}")
public ResponseEntity<Void> append(
@PathVariable("uploadId") String uploadId, HttpServletRequest request) throws IOException {
parser.requireProtocolVersion(request);
parser.requireOffsetContentType(request);
UploadId id = UploadId.parse(uploadId);
long expectedOffset = parser.requiredOffset(request);
RequestContext context = contextFactory.current();
InputStream body = request.getInputStream();
long declared = request.getContentLengthLong();
AppendUploadResult appended =
transferExecutor.call(
() ->
uploadService.append(
id, expectedOffset, Channels.newChannel(body), declared, context));
parser
.checksum(request)
.ifPresent(header -> checksumVerifier.verify(header, appended.sha256Snapshot()));
UploadSessionView session = uploadService.status(id, context);
if (isComplete(session, appended)) {
finalizeService.finalizeUpload(id, FinalizeUploadRequest.synchronousWithoutDigest(), context);
}
return ResponseEntity.noContent()
.header(TusHeaders.RESUMABLE, tusProperties.version())
.header(TusHeaders.UPLOAD_OFFSET, String.valueOf(appended.committedOffset()))
.header(TusHeaders.UPLOAD_EXPIRES, httpDate(session.expiresAt()))
.build();
}
@DeleteMapping("/v1/uploads/{uploadId}")
public ResponseEntity<Void> terminate(
@PathVariable("uploadId") String uploadId, HttpServletRequest request) {
parser.requireProtocolVersion(request);
uploadService.cancel(UploadId.parse(uploadId), contextFactory.current());
return ResponseEntity.noContent().header(TusHeaders.RESUMABLE, tusProperties.version()).build();
}
/**
* Decides whether the upload just reached its declared length.
*
* <p>An upload with a deferred length is never auto-finalized here: only the client knows when it
* is done, and finalizing early would publish a truncated object.
*/
private static boolean isComplete(UploadSessionView session, AppendUploadResult appended) {
return session.expectedLength().isPresent()
&& session.expectedLength().getAsLong() == appended.committedOffset();
}
private static String httpDate(Instant instant) {
return HTTP_DATE.format(ZonedDateTime.ofInstant(instant, ZoneOffset.UTC));
}
}
@@ -1,21 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.tus;
/** The tus 1.0 header vocabulary, named once so no handler re-spells one. */
public final class TusHeaders {
public static final String RESUMABLE = "Tus-Resumable";
public static final String VERSION = "Tus-Version";
public static final String EXTENSION = "Tus-Extension";
public static final String MAX_SIZE = "Tus-Max-Size";
public static final String UPLOAD_OFFSET = "Upload-Offset";
public static final String UPLOAD_LENGTH = "Upload-Length";
public static final String UPLOAD_DEFER_LENGTH = "Upload-Defer-Length";
public static final String UPLOAD_METADATA = "Upload-Metadata";
public static final String UPLOAD_EXPIRES = "Upload-Expires";
public static final String UPLOAD_CHECKSUM = "Upload-Checksum";
/** The only content type a tus PATCH may carry. */
public static final String OFFSET_OCTET_STREAM = "application/offset+octet-stream";
private TusHeaders() {}
}
@@ -1,44 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.tus;
import java.time.Duration;
import java.util.List;
import java.util.Objects;
/**
* tus 1.0 profile.
*
* <p>The advertised extension list is what a client negotiates against, so it must describe what
* this server actually implements. Advertising an extension that is not wired is worse than not
* advertising it: the client will use it and fail mid-upload.
*/
public record TusProperties(
String version, List<String> extensions, long maxSize, Duration uploadTtl) {
public static final String RESUMABLE_VERSION = "1.0.0";
public TusProperties {
Objects.requireNonNull(version, "version");
Objects.requireNonNull(extensions, "extensions");
Objects.requireNonNull(uploadTtl, "uploadTtl");
if (maxSize <= 0) {
throw new IllegalArgumentException("maxSize must be positive");
}
if (uploadTtl.isNegative() || uploadTtl.isZero()) {
throw new IllegalArgumentException("uploadTtl must be positive");
}
extensions = List.copyOf(extensions);
}
/** Design standard profile: creation, expiration, checksum, and termination. */
public static TusProperties standard() {
return new TusProperties(
RESUMABLE_VERSION,
List.of("creation", "expiration", "checksum", "termination"),
100L * 1024 * 1024,
Duration.ofHours(1));
}
public String extensionHeader() {
return String.join(",", extensions);
}
}
@@ -1,140 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.tus;
import dev.caskeleton.application.fileserver.api.error.FileTooLargeException;
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
import dev.caskeleton.application.fileserver.api.error.FileserverFailureContext;
import dev.caskeleton.application.fileserver.api.error.MalformedRequestException;
import dev.caskeleton.application.fileserver.api.error.UnsupportedMediaTypeException;
import jakarta.servlet.http.HttpServletRequest;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
import java.util.LinkedHashMap;
import java.util.Locale;
import java.util.Map;
import java.util.Optional;
import java.util.OptionalLong;
/**
* Reads and validates the tus protocol headers of one request.
*
* <p>Version negotiation is checked first and unconditionally: a client that omits {@code
* Tus-Resumable} is not speaking tus, and answering it as though it were is how a plain POST gets
* silently treated as an upload creation.
*
* <p>{@code Upload-Metadata} is decoded but never trusted — the filename it carries is display data
* that the application layer sanitizes, exactly like a multipart filename.
*/
public final class TusRequestParser {
private static final String FILENAME_KEY = "filename";
private final TusProperties properties;
public TusRequestParser(TusProperties properties) {
this.properties = properties;
}
/** Rejects a request that is not this protocol version. */
public void requireProtocolVersion(HttpServletRequest request) {
String resumable = request.getHeader(TusHeaders.RESUMABLE);
if (!properties.version().equals(resumable)) {
throw MalformedRequestException.of("unsupported or missing tus protocol version");
}
}
/** Rejects a PATCH body that is not the tus offset media type. */
public void requireOffsetContentType(HttpServletRequest request) {
String contentType = request.getContentType();
if (contentType == null || !contentType.startsWith(TusHeaders.OFFSET_OCTET_STREAM)) {
throw new UnsupportedMediaTypeException(
"tus PATCH requires the offset octet-stream media type",
FileserverFailureContext.of(FileserverErrorCode.UNSUPPORTED_MEDIA_TYPE, false));
}
}
/**
* Reads the declared final length.
*
* <p>{@code Upload-Defer-Length: 1} means the client will declare it later, which is legal and
* distinct from a length of zero.
*/
public OptionalLong declaredLength(HttpServletRequest request) {
if ("1".equals(request.getHeader(TusHeaders.UPLOAD_DEFER_LENGTH))) {
return OptionalLong.empty();
}
String header = request.getHeader(TusHeaders.UPLOAD_LENGTH);
if (header == null || header.isBlank()) {
throw MalformedRequestException.of(
"tus creation requires Upload-Length or Upload-Defer-Length");
}
long length = parseNonNegative(header);
if (length > properties.maxSize()) {
throw new FileTooLargeException(
"declared upload length exceeds the advertised maximum",
FileserverFailureContext.of(FileserverErrorCode.FILE_TOO_LARGE, false));
}
return OptionalLong.of(length);
}
public long requiredOffset(HttpServletRequest request) {
String header = request.getHeader(TusHeaders.UPLOAD_OFFSET);
if (header == null || header.isBlank()) {
throw MalformedRequestException.of("tus PATCH requires Upload-Offset");
}
return parseNonNegative(header);
}
/** Display filename from {@code Upload-Metadata}, still untrusted at this point. */
public Optional<String> filename(HttpServletRequest request) {
return Optional.ofNullable(metadata(request).get(FILENAME_KEY));
}
/**
* Decodes the base64 pairs of {@code Upload-Metadata}.
*
* <p>A pair whose value does not decode is dropped rather than failing the request: metadata is
* advisory, and rejecting an upload over a cosmetic field would be worse than ignoring it.
*/
public Map<String, String> metadata(HttpServletRequest request) {
String header = request.getHeader(TusHeaders.UPLOAD_METADATA);
Map<String, String> decoded = new LinkedHashMap<>();
if (header == null || header.isBlank()) {
return decoded;
}
for (String pair : header.split(",", -1)) {
String[] parts = pair.trim().split(" ", 2);
if (parts.length != 2 || parts[0].isBlank()) {
continue;
}
try {
decoded.put(
parts[0].toLowerCase(Locale.ROOT),
new String(Base64.getDecoder().decode(parts[1]), StandardCharsets.UTF_8));
} catch (IllegalArgumentException undecodable) {
// Advisory metadata; a malformed pair is skipped, never fatal.
}
}
return decoded;
}
/** {@code Upload-Checksum} as {@code algorithm base64value}, when present. */
public Optional<String> checksum(HttpServletRequest request) {
String header = request.getHeader(TusHeaders.UPLOAD_CHECKSUM);
return header == null || header.isBlank() ? Optional.empty() : Optional.of(header.trim());
}
private static long parseNonNegative(String raw) {
try {
long value = Long.parseLong(raw.trim());
if (value < 0) {
throw new NumberFormatException("negative");
}
return value;
} catch (NumberFormatException malformed) {
throw new MalformedRequestException(
"tus header is not a non-negative integer",
malformed,
FileserverFailureContext.of(FileserverErrorCode.BAD_REQUEST, false));
}
}
}
@@ -1,116 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.admin;
import static org.assertj.core.api.Assertions.assertThat;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import dev.caskeleton.adapter.inbound.web.fileserver.testkit.FileserverWebFixtures;
import dev.caskeleton.adapter.inbound.web.fileserver.testkit.RecordingAdminService;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
class FileserverAdminControllerTest {
private final RecordingAdminService adminService = new RecordingAdminService();
private MockMvc mvc;
@BeforeEach
void setUp() {
mvc =
MockMvcBuilders.standaloneSetup(
new FileserverAdminController(adminService, FileserverWebFixtures.contextFactory()))
.build();
}
@Test
void orphanReconcileDefaultsToDryRunWhenTheFieldIsOmitted() throws Exception {
mvc.perform(
post("/internal/fileserver/orphans:reconcile")
.contentType(MediaType.APPLICATION_JSON)
.content("{\"limit\":100}"))
.andExpect(status().isOk())
.andExpect(jsonPath("$.dryRun").value(true));
assertThat(adminService.lastReconcile().dryRun()).isTrue();
assertThat(adminService.deletedObjectCount()).isZero();
}
@Test
void anExplicitApplyIsForwardedWithItsFingerprintsAndBudget() throws Exception {
mvc.perform(
post("/internal/fileserver/orphans:reconcile")
.contentType(MediaType.APPLICATION_JSON)
.content(
"{\"dryRun\":false,\"limit\":10,\"maxBytes\":1024,"
+ "\"expectedFingerprints\":[\"fp-1\"],\"reasonCode\":\"OPERATOR_APPLY\"}"))
.andExpect(status().isOk())
.andExpect(jsonPath("$.dryRun").value(false));
assertThat(adminService.lastReconcile().expectedFingerprints()).containsExactly("fp-1");
assertThat(adminService.lastReconcile().maxBytes()).isEqualTo(1024);
}
@Test
void capabilitiesNeverCarryAPhysicalPath() throws Exception {
String body =
mvc.perform(get("/internal/fileserver/capabilities"))
.andExpect(status().isOk())
.andReturn()
.getResponse()
.getContentAsString();
assertThat(body).doesNotContain("/var").doesNotContain("/srv").doesNotContain("mount");
}
@Test
void storageHealthReportsProportionsOnly() throws Exception {
mvc.perform(get("/internal/fileserver/storage-health"))
.andExpect(status().isOk())
.andExpect(jsonPath("$.usedFraction").exists())
.andExpect(jsonPath("$.filesystemProfile").value("linux-ext4"));
}
@Test
void aForceDeleteWithoutAReasonIsRejectedAtTheBoundary() throws Exception {
mvc.perform(
post("/internal/fileserver/files/"
+ "00000000-0000-0000-0000-000000000001:force-delete")
.contentType(MediaType.APPLICATION_JSON)
.content("{\"reasonCode\":\"short\"}"))
.andExpect(status().isBadRequest());
assertThat(adminService.forceDeletes()).isEmpty();
}
@Test
void aForceDeleteWithAReasonIsAcceptedAndForwarded() throws Exception {
mvc.perform(
post("/internal/fileserver/files/"
+ "00000000-0000-0000-0000-000000000001:force-delete")
.contentType(MediaType.APPLICATION_JSON)
.content("{\"reasonCode\":\"LEGAL_TAKEDOWN_2026_08\"}"))
.andExpect(status().isAccepted());
assertThat(adminService.forceDeletes())
.singleElement()
.satisfies(command -> assertThat(command.reasonCode()).isEqualTo("LEGAL_TAKEDOWN_2026_08"));
}
@Test
void incompleteUploadsNeverCarryAnOriginalFilename() throws Exception {
String body =
mvc.perform(get("/internal/fileserver/uploads/incomplete"))
.andExpect(status().isOk())
.andReturn()
.getResponse()
.getContentAsString();
assertThat(body).doesNotContain("filename").doesNotContain("originalName");
}
}
@@ -1,145 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.config;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.adapter.inbound.web.fileserver.testkit.FileserverWebFixtures;
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
import dev.caskeleton.application.fileserver.api.error.TransferAdmissionRejectedException;
import dev.caskeleton.application.fileserver.api.error.TransferTimeoutException;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.atomic.AtomicInteger;
import org.junit.jupiter.api.Test;
import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;
class MvcUploadExecutorSaturationTest {
@Test
void saturationIsARetryableRejectionRatherThanAnUnboundedQueue() throws Exception {
TransferExecutorProperties bounds = new TransferExecutorProperties(1, 1, 1, 5);
ThreadPoolTaskExecutor pool = FileserverWebFixtures.pool(bounds);
BlockingTransferExecutor executor = new BlockingTransferExecutor(pool, bounds.awaitSeconds());
CountDownLatch release = new CountDownLatch(1);
AtomicInteger rejections = new AtomicInteger();
List<Thread> callers = new ArrayList<>();
for (int index = 0; index < 8; index++) {
Thread caller =
new Thread(
() -> {
try {
executor.call(() -> await(release));
} catch (TransferAdmissionRejectedException rejected) {
rejections.incrementAndGet();
} catch (TransferTimeoutException ignored) {
// A caller that outlived the budget is not a saturation signal.
}
});
callers.add(caller);
caller.start();
}
Thread.sleep(200);
release.countDown();
for (Thread caller : callers) {
caller.join(TimeUnit.SECONDS.toMillis(10));
}
pool.shutdown();
assertThat(rejections.get())
.as("a pool of 1 with a queue of 1 cannot absorb 8 concurrent transfers")
.isPositive();
}
/**
* A timed-out transfer must stop, not merely stop being waited on.
*
* <p>{@code CompletableFuture#cancel} ignores {@code mayInterruptIfRunning}, so the previous
* implementation answered {@code 504} while the worker carried on copying into an abandoned
* response — still holding a pool slot, a transfer buffer and an open channel. Under sustained
* timeouts that is how a bounded pool stops being bounded.
*/
@Test
void aTimedOutTransferInterruptsItsWorkerRatherThanLeavingItRunning() throws Exception {
TransferExecutorProperties bounds = new TransferExecutorProperties(1, 1, 1, 1);
ThreadPoolTaskExecutor pool = FileserverWebFixtures.pool(bounds);
BlockingTransferExecutor executor = new BlockingTransferExecutor(pool, bounds.awaitSeconds());
CountDownLatch interrupted = new CountDownLatch(1);
assertThatThrownBy(
() ->
executor.call(
() -> {
try {
// Longer than the budget, so the caller times out while this is running.
Thread.sleep(TimeUnit.SECONDS.toMillis(30));
} catch (InterruptedException expected) {
Thread.currentThread().interrupt();
interrupted.countDown();
}
return null;
}))
.isInstanceOf(TransferTimeoutException.class);
assertThat(interrupted.await(10, TimeUnit.SECONDS))
.as("the worker must observe the interrupt, not keep running past the caller's timeout")
.isTrue();
pool.shutdown();
}
@Test
void aRejectionCarriesTheRetryableAdmissionCode() {
TransferExecutorProperties bounds = new TransferExecutorProperties(1, 1, 1, 5);
ThreadPoolTaskExecutor pool = FileserverWebFixtures.pool(bounds);
pool.shutdown();
BlockingTransferExecutor executor = new BlockingTransferExecutor(pool, bounds.awaitSeconds());
assertThatThrownBy(() -> executor.call(() -> "never runs"))
.isInstanceOf(TransferAdmissionRejectedException.class)
.satisfies(
failure -> {
TransferAdmissionRejectedException rejected =
(TransferAdmissionRejectedException) failure;
assertThat(rejected.code())
.isEqualTo(FileserverErrorCode.TRANSFER_ADMISSION_REJECTED);
assertThat(rejected.context().retryable()).isTrue();
});
}
@Test
void aTransferThatOverrunsItsBudgetBecomesATimeoutNotAHungThread() {
TransferExecutorProperties bounds = new TransferExecutorProperties(1, 1, 1, 1);
ThreadPoolTaskExecutor pool = FileserverWebFixtures.pool(bounds);
BlockingTransferExecutor executor = new BlockingTransferExecutor(pool, bounds.awaitSeconds());
assertThatThrownBy(() -> executor.call(() -> await(new CountDownLatch(1))))
.isInstanceOf(TransferTimeoutException.class);
pool.shutdown();
}
@Test
void aWorkerFailureKeepsItsOwnFileserverContext() {
BlockingTransferExecutor executor = FileserverWebFixtures.transferExecutor();
assertThatThrownBy(
() ->
executor.call(
() -> {
throw new IllegalStateException("worker blew up");
}))
.isInstanceOf(IllegalStateException.class)
.hasMessage("worker blew up");
}
private static String await(CountDownLatch latch) {
try {
latch.await(10, TimeUnit.SECONDS);
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
}
return "done";
}
}
@@ -1,220 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.controller;
import static org.assertj.core.api.Assertions.assertThat;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.head;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.header;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import dev.caskeleton.adapter.inbound.web.fileserver.http.MvcConditionalRequestFactory;
import dev.caskeleton.adapter.inbound.web.fileserver.http.MvcDownloadResponseWriter;
import dev.caskeleton.adapter.inbound.web.fileserver.http.ZeroCopyEligibility;
import dev.caskeleton.adapter.inbound.web.fileserver.problem.FileserverExceptionHandler;
import dev.caskeleton.adapter.inbound.web.fileserver.problem.FileserverProblemFactory;
import dev.caskeleton.adapter.inbound.web.fileserver.testkit.FileserverWebFixtures;
import dev.caskeleton.adapter.inbound.web.fileserver.testkit.StubDownloadService;
import dev.caskeleton.application.fileserver.api.FileState;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.MvcResult;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
class FileDownloadControllerContractTest {
private final StubDownloadService downloadService = new StubDownloadService();
private MockMvc mvc;
@BeforeEach
void setUp() {
mvc =
MockMvcBuilders.standaloneSetup(
new FileDownloadController(
downloadService,
new MvcConditionalRequestFactory(),
downloadService.httpPlanner(),
new MvcDownloadResponseWriter(),
FileserverWebFixtures.contextFactory(),
FileserverWebFixtures.transferExecutor(),
FileserverWebFixtures.noDelegation(),
ZeroCopyEligibility.disabled()))
.setControllerAdvice(new FileserverExceptionHandler(new FileserverProblemFactory()))
.build();
}
@Test
void aFullGetCarriesTheCompleteHeaderSetAndBody() throws Exception {
mvc.perform(get(contentUrl()))
.andExpect(status().isOk())
.andExpect(header().string("ETag", downloadService.strongEtag()))
.andExpect(header().string("Accept-Ranges", "bytes"))
.andExpect(header().string("Cache-Control", "private, no-store"))
.andExpect(header().exists("Last-Modified"))
.andExpect(header().string("Content-Length", "10"))
.andExpect(
header().string("Content-Disposition", org.hamcrest.Matchers.startsWith("attachment;")))
.andExpect(content().bytes(new byte[] {0, 1, 2, 3, 4, 5, 6, 7, 8, 9}));
}
/**
* A legitimately empty file is a 200 with no body, not a range error.
*
* <p>Treating the whole representation as the range {@code 0..0} asked storage for one byte of a
* zero-byte object, which is genuinely unsatisfiable — so uploading an empty file succeeded and
* downloading it answered 416 forever.
*/
@Test
void anEmptyRepresentationIsServedAsAnEmptyBody() throws Exception {
downloadService.store(new byte[0]);
mvc.perform(get(contentUrl()))
.andExpect(status().isOk())
.andExpect(header().string("Content-Length", "0"))
.andExpect(header().string("Accept-Ranges", "bytes"))
.andExpect(content().bytes(new byte[0]));
}
@Test
void headOfAnEmptyRepresentationMatchesItsGet() throws Exception {
downloadService.store(new byte[0]);
mvc.perform(head(contentUrl()))
.andExpect(status().isOk())
.andExpect(header().string("Content-Length", "0"))
.andExpect(content().bytes(new byte[0]));
}
@Test
void headMatchesGetHeadersWithoutBody() throws Exception {
MvcResult getResult = mvc.perform(get(contentUrl())).andExpect(status().isOk()).andReturn();
MvcResult headResult =
mvc.perform(head(contentUrl()))
.andExpect(status().isOk())
.andExpect(content().bytes(new byte[0]))
.andReturn();
assertThat(headResult.getResponse().getHeader("ETag"))
.isEqualTo(getResult.getResponse().getHeader("ETag"));
assertThat(headResult.getResponse().getHeader("Content-Length"))
.isEqualTo(getResult.getResponse().getHeader("Content-Length"));
assertThat(headResult.getResponse().getHeader("Content-Disposition"))
.isEqualTo(getResult.getResponse().getHeader("Content-Disposition"));
assertThat(downloadService.opened()).hasSize(1);
}
@Test
void returnsPartialContentForASingleRange() throws Exception {
mvc.perform(get(contentUrl()).header("Range", "bytes=2-4"))
.andExpect(status().isPartialContent())
.andExpect(header().string("Content-Range", "bytes 2-4/10"))
.andExpect(header().string("Content-Length", "3"))
.andExpect(content().bytes(new byte[] {2, 3, 4}));
}
@Test
void aSuffixRangeIsResolvedAgainstTheRepresentationLength() throws Exception {
mvc.perform(get(contentUrl()).header("Range", "bytes=-3"))
.andExpect(status().isPartialContent())
.andExpect(header().string("Content-Range", "bytes 7-9/10"))
.andExpect(content().bytes(new byte[] {7, 8, 9}));
}
@Test
void anOpenEndedRangeRunsToTheEnd() throws Exception {
mvc.perform(get(contentUrl()).header("Range", "bytes=8-"))
.andExpect(status().isPartialContent())
.andExpect(header().string("Content-Range", "bytes 8-9/10"))
.andExpect(content().bytes(new byte[] {8, 9}));
}
@Test
void anUnsatisfiableRangeReportsTheRealLength() throws Exception {
mvc.perform(get(contentUrl()).header("Range", "bytes=50-60"))
.andExpect(status().isRequestedRangeNotSatisfiable())
.andExpect(header().string("Content-Range", "bytes */10"));
assertThat(downloadService.neverOpened()).isTrue();
}
@Test
void aMatchingValidatorIsNotModifiedAndOpensNothing() throws Exception {
mvc.perform(get(contentUrl()).header("If-None-Match", downloadService.strongEtag()))
.andExpect(status().isNotModified());
assertThat(downloadService.neverOpened()).isTrue();
}
@Test
void aFailedIfMatchIsAPreconditionFailure() throws Exception {
mvc.perform(get(contentUrl()).header("If-Match", "\"stale\""))
.andExpect(status().isPreconditionFailed());
assertThat(downloadService.neverOpened()).isTrue();
}
@Test
void aStaleIfRangeDegradesToTheFullRepresentation() throws Exception {
mvc.perform(get(contentUrl()).header("Range", "bytes=2-4").header("If-Range", "\"stale\""))
.andExpect(status().isOk())
.andExpect(content().bytes(new byte[] {0, 1, 2, 3, 4, 5, 6, 7, 8, 9}));
}
@Test
void aMatchingIfRangeStillAnswersPartial() throws Exception {
mvc.perform(
get(contentUrl())
.header("Range", "bytes=2-4")
.header("If-Range", downloadService.strongEtag()))
.andExpect(status().isPartialContent())
.andExpect(header().string("Content-Range", "bytes 2-4/10"));
}
@Test
void aNonReadyFileIsAConflictAndIsNeverOpened() throws Exception {
downloadService.fileInState(FileState.VERIFYING);
mvc.perform(get(contentUrl()))
.andExpect(status().isConflict())
.andExpect(header().string("Content-Type", "application/problem+json"));
assertThat(downloadService.neverOpened()).isTrue();
}
@Test
void aProblemResponseNeverEchoesTheServerSideMessage() throws Exception {
downloadService.fileInState(FileState.QUARANTINED);
String body = mvc.perform(get(contentUrl())).andReturn().getResponse().getContentAsString();
assertThat(body).contains("\"code\":\"FILE_NOT_READY\"");
assertThat(body).contains("urn:fileserver:problem:file-not-ready");
assertThat(body).doesNotContain("publicly readable state");
}
@Test
void aScriptableFilenameIsStillOfferedAsAnAttachment() throws Exception {
downloadService.named("page.html", "text/html");
mvc.perform(get(contentUrl()))
.andExpect(
header()
.string("Content-Disposition", org.hamcrest.Matchers.startsWith("attachment;")));
}
@Test
void theMetadataEndpointReportsTheDescriptorWithoutOpeningContent() throws Exception {
mvc.perform(get("/v1/files/" + StubDownloadService.anyFileId().canonicalText()))
.andExpect(status().isOk())
.andExpect(
org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath("$.state")
.value("READY"));
assertThat(downloadService.neverOpened()).isTrue();
}
private static String contentUrl() {
return "/v1/files/" + StubDownloadService.anyFileId().canonicalText() + "/content";
}
}
@@ -1,185 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.controller;
import static org.assertj.core.api.Assertions.assertThat;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.multipart;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.header;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import dev.caskeleton.adapter.inbound.web.fileserver.mapper.MultipartUploadRequestMapper;
import dev.caskeleton.adapter.inbound.web.fileserver.mapper.RawUploadRequestMapper;
import dev.caskeleton.adapter.inbound.web.fileserver.testkit.FileserverWebFixtures;
import dev.caskeleton.adapter.inbound.web.fileserver.testkit.RecordingUploadService;
import dev.caskeleton.application.fileserver.api.FileState;
import dev.caskeleton.application.fileserver.api.error.FileTooLargeException;
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
import dev.caskeleton.application.fileserver.api.error.FileserverFailureContext;
import dev.caskeleton.application.fileserver.upload.CreateUploadRequest;
import java.nio.charset.StandardCharsets;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.http.MediaType;
import org.springframework.mock.web.MockMultipartFile;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
class FileUploadControllerTest {
private final RecordingUploadService uploadService = new RecordingUploadService();
private MockMvc mvc;
@BeforeEach
void setUp() {
mvc =
MockMvcBuilders.standaloneSetup(
new FileUploadController(
uploadService,
new RawUploadRequestMapper(false),
new MultipartUploadRequestMapper(),
FileserverWebFixtures.contextFactory(),
FileserverWebFixtures.transferExecutor(),
FileserverWebFixtures.properties(),
FileserverWebFixtures.clock()))
.build();
}
@Test
void rawUploadStreamsTheBodyAndAnswersCreated() throws Exception {
mvc.perform(
post("/v1/files:raw")
.contentType(MediaType.APPLICATION_OCTET_STREAM)
.header(RawUploadRequestMapper.FILENAME_HEADER, "report.bin")
.content("abc"))
.andExpect(status().isCreated())
.andExpect(header().exists("Location"))
.andExpect(jsonPath("$.state").value("READY"))
.andExpect(jsonPath("$.filename").value("report.bin"));
assertThat(uploadService.receivedBodies()).containsExactly("abc");
assertThat(uploadService.declaredContentLengths()).containsExactly(3L);
}
@Test
void theLocationHeaderPointsAtTheCreatedFileResource() throws Exception {
String location =
mvc.perform(
post("/v1/files:raw")
.contentType(MediaType.APPLICATION_OCTET_STREAM)
.header(RawUploadRequestMapper.FILENAME_HEADER, "report.bin")
.content("abc"))
.andReturn()
.getResponse()
.getHeader("Location");
assertThat(location).startsWith("/v1/files/");
}
@Test
void aStillVerifyingUploadIsAcceptedRatherThanCreated() throws Exception {
uploadService.answerWith(FileState.VERIFYING);
mvc.perform(
post("/v1/files:raw")
.contentType(MediaType.APPLICATION_OCTET_STREAM)
.header(RawUploadRequestMapper.FILENAME_HEADER, "report.bin")
.content("abc"))
.andExpect(status().isAccepted())
.andExpect(jsonPath("$.state").value("VERIFYING"));
}
@Test
void aRawUploadWithoutAFilenameHeaderStillGetsASafeDisplayName() throws Exception {
mvc.perform(
post("/v1/files:raw").contentType(MediaType.APPLICATION_OCTET_STREAM).content("abc"))
.andExpect(status().isCreated());
assertThat(uploadService.requests())
.singleElement()
.extracting(CreateUploadRequest::originalFilename)
.isEqualTo("upload.bin");
}
@Test
void theClaimedMediaTypeIsForwardedAsAClaimNotAsAFact() throws Exception {
mvc.perform(
post("/v1/files:raw")
.contentType(MediaType.APPLICATION_PDF)
.header(RawUploadRequestMapper.FILENAME_HEADER, "report.pdf")
.content("abc"))
.andExpect(status().isCreated());
assertThat(uploadService.requests().get(0).claimedMediaType())
.hasValueSatisfying(value -> assertThat(value).startsWith("application/pdf"));
}
@Test
void multipartUploadStreamsThePartWithoutMaterializingIt() throws Exception {
mvc.perform(
multipart("/v1/files")
.file(
new MockMultipartFile(
"file", "a.txt", "text/plain", "abc".getBytes(StandardCharsets.UTF_8))))
.andExpect(status().isCreated())
.andExpect(jsonPath("$.filename").value("a.txt"));
assertThat(uploadService.receivedBodies()).containsExactly("abc");
}
@Test
void batchReturnsPerPartResultsAndIsExplicitlyNonAtomic() throws Exception {
mvc.perform(
multipart("/v1/files:batch")
.file(
new MockMultipartFile(
"files", "a.txt", "text/plain", "a".getBytes(StandardCharsets.UTF_8)))
.file(
new MockMultipartFile(
"files", "b.txt", "text/plain", "b".getBytes(StandardCharsets.UTF_8))))
.andExpect(status().isOk())
.andExpect(jsonPath("$.results.length()").value(2))
.andExpect(jsonPath("$.results[0].clientPartId").value("a.txt"))
.andExpect(jsonPath("$.results[1].clientPartId").value("b.txt"));
}
@Test
void aFailedBatchPartNeverRollsBackTheSiblingThatSucceeded() throws Exception {
uploadService.failWith(
body ->
"b".equals(body)
? new FileTooLargeException(
"too large",
FileserverFailureContext.of(FileserverErrorCode.FILE_TOO_LARGE, false))
: null);
mvc.perform(
multipart("/v1/files:batch")
.file(
new MockMultipartFile(
"files", "a.txt", "text/plain", "a".getBytes(StandardCharsets.UTF_8)))
.file(
new MockMultipartFile(
"files", "b.txt", "text/plain", "b".getBytes(StandardCharsets.UTF_8))))
.andExpect(status().isOk())
.andExpect(jsonPath("$.results[0].status").value("READY"))
.andExpect(jsonPath("$.results[1].status").value("REJECTED"))
.andExpect(jsonPath("$.results[1].problem.code").value("FILE_TOO_LARGE"))
.andExpect(jsonPath("$.results[1].problem.status").value(413));
}
@Test
void aBatchResultNeverExposesAContainerTemporaryPath() throws Exception {
String body =
mvc.perform(
multipart("/v1/files:batch")
.file(
new MockMultipartFile(
"files", "a.txt", "text/plain", "a".getBytes(StandardCharsets.UTF_8))))
.andReturn()
.getResponse()
.getContentAsString();
assertThat(body).doesNotContain("/tmp").doesNotContain("multipart").doesNotContain("staging");
}
}
@@ -1,153 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.draft12;
import static org.assertj.core.api.Assertions.assertThat;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.patch;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.header;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import dev.caskeleton.adapter.inbound.web.fileserver.problem.FileserverExceptionHandler;
import dev.caskeleton.adapter.inbound.web.fileserver.problem.FileserverProblemFactory;
import dev.caskeleton.adapter.inbound.web.fileserver.testkit.FileserverWebFixtures;
import dev.caskeleton.adapter.inbound.web.fileserver.testkit.InMemoryUploadApplicationService;
import dev.caskeleton.adapter.inbound.web.fileserver.testkit.RecordingFinalizeService;
import dev.caskeleton.application.fileserver.api.UploadId;
import java.time.Duration;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
class Draft12ProtocolTest {
private static final Draft12Properties DRAFT =
new Draft12Properties(true, 100L * 1024 * 1024, Duration.ofHours(1), false);
private final InMemoryUploadApplicationService uploads = new InMemoryUploadApplicationService();
private final RecordingFinalizeService finalizeService = new RecordingFinalizeService();
private MockMvc mvc;
@BeforeEach
void setUp() {
mvc =
MockMvcBuilders.standaloneSetup(
new Draft12UploadController(
uploads,
finalizeService,
FileserverWebFixtures.contextFactory(),
FileserverWebFixtures.transferExecutor(),
FileserverWebFixtures.properties(),
DRAFT,
FileserverWebFixtures.clock()))
.setControllerAdvice(new FileserverExceptionHandler(new FileserverProblemFactory()))
.build();
}
@Test
void creationAnswersWithAZeroOffsetAndTheUploadLimit() throws Exception {
mvc.perform(post("/v1/experimental/draft12/uploads"))
.andExpect(status().isCreated())
.andExpect(header().string(Draft12Headers.UPLOAD_OFFSET, "0"))
.andExpect(header().string(Draft12Headers.UPLOAD_LIMIT, "max-size=" + DRAFT.maxSize()));
}
@Test
void anAppendAdvancesTheOffsetAndReportsIncompleteness() throws Exception {
String location = create();
mvc.perform(
patch(location)
.header(Draft12Headers.UPLOAD_OFFSET, "0")
.contentType(Draft12Headers.PARTIAL_UPLOAD)
.content("abc"))
.andExpect(status().isNoContent())
.andExpect(header().string(Draft12Headers.UPLOAD_OFFSET, "3"))
.andExpect(header().string(Draft12Headers.UPLOAD_COMPLETE, "?0"));
assertThat(finalizeService.finalized()).isEmpty();
}
@Test
void anExplicitCompleteFinalizesTheUpload() throws Exception {
String location = create();
mvc.perform(
patch(location)
.header(Draft12Headers.UPLOAD_OFFSET, "0")
.header(Draft12Headers.UPLOAD_COMPLETE, "?1")
.contentType(Draft12Headers.PARTIAL_UPLOAD)
.content("abc"))
.andExpect(status().isNoContent())
.andExpect(header().string(Draft12Headers.UPLOAD_COMPLETE, "?1"));
assertThat(finalizeService.finalized()).containsExactly(uploadIdOf(location));
}
@Test
void offsetMismatchReturnsTheDraftProblemDetailWithBothOffsets() throws Exception {
String location = create();
mvc.perform(
patch(location)
.header(Draft12Headers.UPLOAD_OFFSET, "0")
.contentType(Draft12Headers.PARTIAL_UPLOAD)
.content("abcdefghij"))
.andExpect(status().isNoContent());
mvc.perform(
patch(location)
.header(Draft12Headers.UPLOAD_OFFSET, "5")
.contentType(Draft12Headers.PARTIAL_UPLOAD)
.content("abc"))
.andExpect(status().isConflict())
.andExpect(jsonPath("$.expectedOffset").value(10))
.andExpect(jsonPath("$.providedOffset").value(5))
.andExpect(jsonPath("$.type").value(Draft12OffsetProblem.TYPE));
}
@Test
void anAppendWithoutAnOffsetIsRejected() throws Exception {
String location = create();
mvc.perform(patch(location).contentType(Draft12Headers.PARTIAL_UPLOAD).content("abc"))
.andExpect(status().isBadRequest());
}
@Test
void anAppendWithTheWrongMediaTypeIsNotEvenRouted() throws Exception {
String location = create();
mvc.perform(
patch(location)
.header(Draft12Headers.UPLOAD_OFFSET, "0")
.contentType("application/offset+octet-stream")
.content("abc"))
.andExpect(status().isUnsupportedMediaType());
}
@Test
void theDraftPathIsDisjointFromTheStableUploadPath() {
assertThat(Draft12Headers.PARTIAL_UPLOAD).isNotEqualTo("application/offset+octet-stream");
}
@Test
void theControllerDeclaresWhichDraftItImplements() {
ExperimentalApi marker = Draft12UploadController.class.getAnnotation(ExperimentalApi.class);
assertThat(marker).isNotNull();
assertThat(marker.specification()).isEqualTo("draft-ietf-httpbis-resumable-upload-12");
}
private String create() throws Exception {
return mvc.perform(post("/v1/experimental/draft12/uploads"))
.andExpect(status().isCreated())
.andReturn()
.getResponse()
.getHeader("Location");
}
private static UploadId uploadIdOf(String location) {
return UploadId.parse(location.substring(location.lastIndexOf('/') + 1));
}
}
@@ -1,64 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.http;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.application.fileserver.api.security.OriginalFilenamePolicy;
import dev.caskeleton.application.fileserver.api.security.SanitizedFilename;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.ValueSource;
class HttpContentDispositionFactoryTest {
private final HttpContentDispositionFactory factory = new HttpContentDispositionFactory();
private final OriginalFilenamePolicy policy = OriginalFilenamePolicy.standard();
@Test
void emitsAsciiAndUtf8FilenameParameters() {
assertThat(factory.attachment(new SanitizedFilename("report.pdf")))
.isEqualTo("attachment; filename=\"report.pdf\"; filename*=UTF-8''report.pdf");
}
@Test
void percentEncodesNonAsciiWithoutLeakingItIntoTheAsciiParameter() {
String header = factory.attachment(policy.sanitize("보고서.pdf"));
assertThat(header).contains("filename*=UTF-8''", "%").doesNotContain("보고서");
}
@Test
void neverEmitsNewlinesOrHostileQuotes() {
String header = factory.attachment(policy.sanitize("a\"; x=1\r\nSet-Cookie: b.pdf"));
assertThat(header).doesNotContain("\r", "\n");
assertThat(header.chars().filter(character -> character == '"').count()).isEqualTo(2);
}
@ParameterizedTest
@ValueSource(
strings = {
"text/html",
"image/svg+xml",
"application/xhtml+xml",
"TEXT/HTML; charset=utf-8",
"text/javascript"
})
void scriptableContentIsAlwaysAttachment(String mediaType) {
assertThat(factory.isScriptable(mediaType)).isTrue();
assertThat(factory.inlineOrAttachment(new SanitizedFilename("a.html"), mediaType))
.startsWith("attachment;");
}
@Test
void nonScriptableContentMayBeInline() {
assertThat(factory.isScriptable("image/png")).isFalse();
assertThat(factory.inlineOrAttachment(new SanitizedFilename("a.png"), "image/png"))
.startsWith("inline;");
}
@Test
void filenameWithNoAsciiSurvivorsFallsBackSafely() {
assertThat(factory.attachment(policy.sanitize("보고서")))
.startsWith("attachment; filename=\"file\";");
}
}
@@ -1,210 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.http;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.application.fileserver.api.ByteRange;
import dev.caskeleton.application.fileserver.api.ContentKey;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.security.SanitizedFilename;
import dev.caskeleton.application.fileserver.api.transfer.FileRepresentation;
import dev.caskeleton.application.fileserver.download.DownloadDescriptor;
import java.time.Instant;
import java.util.Optional;
import java.util.UUID;
import org.junit.jupiter.api.Test;
class HttpDownloadPlannerTest {
private static final Instant PUBLISHED = Instant.parse("2026-08-07T10:00:00Z");
private final HttpDownloadPlanner planner =
new HttpDownloadPlanner(
new DefaultHttpRangeResolver(),
new HttpContentDispositionFactory(),
new HttpDownloadPolicy(HttpRangePolicy.unbounded(), "private, no-store", false));
@Test
void mismatchedIfRangeFallsBackToFullResponse() {
HttpDownloadDecision result =
planner.plan(
descriptor("new", 100),
conditional(
builder -> {
builder.ifRange = Optional.of("\"old\"");
builder.range = Optional.of("bytes=0-9");
}),
false);
assertThat(result.status()).isEqualTo(200);
assertThat(result.ranges()).isEmpty();
}
@Test
void matchingIfRangeServesPartialResponse() {
HttpDownloadDecision result =
planner.plan(
descriptor("new", 100),
conditional(
builder -> {
builder.ifRange = Optional.of("\"new\"");
builder.range = Optional.of("bytes=0-9");
}),
false);
assertThat(result.status()).isEqualTo(206);
assertThat(result.ranges()).containsExactly(new ByteRange(0, 9));
assertThat(result.payloadLength()).isEqualTo(10);
}
@Test
void ifMatchFailureWinsBeforeCacheValidators() {
HttpDownloadDecision result =
planner.plan(
descriptor("current", 100),
conditional(
builder -> {
builder.ifMatch = Optional.of("\"other\"");
builder.ifNoneMatch = Optional.of("\"current\"");
}),
false);
assertThat(result.status()).isEqualTo(412);
assertThat(result.bodyExpected()).isFalse();
}
@Test
void wildcardIfMatchMatchesAnExistingRepresentation() {
HttpDownloadDecision result =
planner.plan(
descriptor("current", 100),
conditional(builder -> builder.ifMatch = Optional.of("*")),
false);
assertThat(result.status()).isEqualTo(200);
}
@Test
void matchingIfNoneMatchIsNotModified() {
HttpDownloadDecision result =
planner.plan(
descriptor("current", 100),
conditional(builder -> builder.ifNoneMatch = Optional.of("\"current\"")),
false);
assertThat(result.status()).isEqualTo(304);
assertThat(result.payloadLength()).isZero();
}
@Test
void weakValidatorDoesNotSatisfyStrongIfMatch() {
HttpDownloadDecision result =
planner.plan(
descriptor("current", 100),
conditional(builder -> builder.ifMatch = Optional.of("W/\"current\"")),
false);
assertThat(result.status()).isEqualTo(412);
}
@Test
void ifModifiedSinceIsConsultedOnlyWithoutIfNoneMatch() {
HttpDownloadDecision withoutEtag =
planner.plan(
descriptor("current", 100),
conditional(builder -> builder.ifModifiedSince = Optional.of(PUBLISHED)),
false);
HttpDownloadDecision withEtag =
planner.plan(
descriptor("current", 100),
conditional(
builder -> {
builder.ifModifiedSince = Optional.of(PUBLISHED);
builder.ifNoneMatch = Optional.of("\"stale\"");
}),
false);
assertThat(withoutEtag.status()).isEqualTo(304);
assertThat(withEtag.status()).isEqualTo(200);
}
@Test
void ifUnmodifiedSinceRejectsAChangedRepresentation() {
HttpDownloadDecision result =
planner.plan(
descriptor("current", 100),
conditional(
builder -> builder.ifUnmodifiedSince = Optional.of(PUBLISHED.minusSeconds(60))),
false);
assertThat(result.status()).isEqualTo(412);
}
@Test
void headKeepsTheRangeDecisionButSuppressesBody() {
HttpDownloadDecision get =
planner.plan(
descriptor("current", 10), HttpConditionalRequest.rangeGet("bytes=2-4"), false);
HttpDownloadDecision head =
planner.plan(
descriptor("current", 10),
conditional(
builder -> {
builder.range = Optional.of("bytes=2-4");
builder.headOnly = true;
}),
false);
assertThat(head.status()).isEqualTo(get.status());
assertThat(head.ranges()).isEqualTo(get.ranges());
assertThat(head.bodyExpected()).isFalse();
assertThat(head.payloadLength()).isEqualTo(get.payloadLength());
}
@Test
void unsatisfiableRangeCarriesRepresentationLength() {
assertThatThrownBy(
() ->
planner.plan(
descriptor("current", 100),
HttpConditionalRequest.rangeGet("bytes=500-600"),
false))
.isInstanceOf(HttpRangeNotSatisfiableException.class)
.extracting("representationLength")
.isEqualTo(100L);
}
private static DownloadDescriptor descriptor(String sha256, long length) {
return new DownloadDescriptor(
FileId.of(
UUID.nameUUIDFromBytes(
"http-planner".getBytes(java.nio.charset.StandardCharsets.UTF_8))),
new FileRepresentation(sha256, PUBLISHED, length, "application/octet-stream"),
ContentKey.of("ab/cd/http-planner-object"),
new SanitizedFilename("file.bin"));
}
private static HttpConditionalRequest conditional(
java.util.function.Consumer<Builder> customizer) {
Builder builder = new Builder();
customizer.accept(builder);
return new HttpConditionalRequest(
builder.ifMatch,
builder.ifNoneMatch,
builder.ifModifiedSince,
builder.ifUnmodifiedSince,
builder.ifRange,
builder.range,
builder.headOnly);
}
private static final class Builder {
private Optional<String> ifMatch = Optional.empty();
private Optional<String> ifNoneMatch = Optional.empty();
private Optional<Instant> ifModifiedSince = Optional.empty();
private Optional<Instant> ifUnmodifiedSince = Optional.empty();
private Optional<String> ifRange = Optional.empty();
private Optional<String> range = Optional.empty();
private boolean headOnly;
}
}
@@ -1,101 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.http;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.application.fileserver.api.ByteRange;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.CsvSource;
import org.junit.jupiter.params.provider.ValueSource;
class HttpRangeResolverTest {
private final HttpRangeResolver resolver = new DefaultHttpRangeResolver();
@ParameterizedTest
@CsvSource({"bytes=0-9,0,9", "bytes=90-,90,99", "bytes=-10,90,99"})
void resolvesSingleRanges(String header, long start, long end) {
HttpResolvedRanges result = resolver.resolve(header, 100, HttpRangePolicy.unbounded());
assertThat(result.ranges()).containsExactly(new ByteRange(start, end));
}
@Test
void resolvesFirstMiddleSuffixAndEndRanges() {
assertThat(resolver.resolve("bytes=0-0", 100, HttpRangePolicy.unbounded()).ranges())
.containsExactly(new ByteRange(0, 0));
assertThat(resolver.resolve("bytes=45-54", 100, HttpRangePolicy.unbounded()).ranges())
.containsExactly(new ByteRange(45, 54));
assertThat(resolver.resolve("bytes=99-99", 100, HttpRangePolicy.unbounded()).ranges())
.containsExactly(new ByteRange(99, 99));
assertThat(resolver.resolve("bytes=-1", 100, HttpRangePolicy.unbounded()).ranges())
.containsExactly(new ByteRange(99, 99));
}
@Test
void clampsRangesToTheRepresentation() {
assertThat(resolver.resolve("bytes=90-500", 100, HttpRangePolicy.unbounded()).ranges())
.containsExactly(new ByteRange(90, 99));
assertThat(resolver.resolve("bytes=-500", 100, HttpRangePolicy.unbounded()).ranges())
.containsExactly(new ByteRange(0, 99));
}
@Test
void unsatisfiableRangeCarriesRepresentationLength() {
assertThatThrownBy(() -> resolver.resolve("bytes=100-200", 100, HttpRangePolicy.unbounded()))
.isInstanceOf(HttpRangeNotSatisfiableException.class)
.extracting("representationLength")
.isEqualTo(100L);
}
@Test
void absentBlankOrUnknownUnitsServeTheFullRepresentation() {
assertThat(resolver.resolve(null, 100, HttpRangePolicy.unbounded()).isPartial()).isFalse();
assertThat(resolver.resolve(" ", 100, HttpRangePolicy.unbounded()).isPartial()).isFalse();
assertThat(resolver.resolve("items=0-9", 100, HttpRangePolicy.unbounded()).isPartial())
.isFalse();
}
@ParameterizedTest
@ValueSource(strings = {"bytes=abc-def", "bytes=0", "bytes=--5", "bytes=1-2-3"})
void malformedSpecifiersAreRejected(String header) {
assertThatThrownBy(() -> resolver.resolve(header, 100, HttpRangePolicy.unbounded()))
.isInstanceOf(HttpRangeNotSatisfiableException.class);
}
@Test
void rangeCountAndByteBudgetsBoundAmplification() {
String bomb = "bytes=0-0,2-2,4-4,6-6,8-8,10-10,12-12,14-14,16-16";
assertThatThrownBy(() -> resolver.resolve(bomb, 100, HttpRangePolicy.unbounded()))
.isInstanceOf(HttpRangeNotSatisfiableException.class);
assertThatThrownBy(() -> resolver.resolve("bytes=0-99", 100, HttpRangePolicy.multi(8, 10)))
.isInstanceOf(HttpRangeNotSatisfiableException.class);
}
@Test
void multiRangeProfileMergesOverlapsWithinItsBudget() {
HttpResolvedRanges result =
resolver.resolve("bytes=0-9,5-19,40-49", 100, HttpRangePolicy.multi(8, 1 << 20));
assertThat(result.ranges()).containsExactly(new ByteRange(0, 19), new ByteRange(40, 49));
assertThat(result.totalBytes()).isEqualTo(30);
}
@Test
void emptyRepresentationCannotSatisfyASuffixRange() {
assertThatThrownBy(() -> resolver.resolve("bytes=-10", 0, HttpRangePolicy.unbounded()))
.isInstanceOf(HttpRangeNotSatisfiableException.class);
}
@Test
void policiesRejectValuesOutsideTheDesignEnvelope() {
assertThatThrownBy(() -> new HttpRangePolicy(0, 100, false))
.isInstanceOf(IllegalArgumentException.class);
assertThatThrownBy(() -> new HttpRangePolicy(9, 100, false))
.isInstanceOf(IllegalArgumentException.class);
assertThat(HttpRangePolicy.unbounded().allowsMultipleRanges()).isFalse();
assertThat(HttpRangePolicy.multi(8, 100).allowsMultipleRanges()).isTrue();
}
}
@@ -1,44 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.http;
import static org.assertj.core.api.Assertions.assertThat;
import org.junit.jupiter.api.Test;
import org.springframework.mock.http.server.reactive.MockServerHttpResponse;
class ZeroCopyEligibilityTest {
private static final long SIXTEEN_MIB = 16L * 1024 * 1024;
@Test
void aLargePlaintextTransferOnACapableResponseIsEligible() {
assertThat(ZeroCopyEligibility.standard().isEligible(true, SIXTEEN_MIB, false)).isTrue();
}
@Test
void aSmallTransferIsNotWorthTheSyscall() {
assertThat(ZeroCopyEligibility.standard().isEligible(true, SIXTEEN_MIB - 1, false)).isFalse();
}
@Test
void anEncryptedConnectionIsNeverEligible() {
assertThat(ZeroCopyEligibility.standard().isEligible(true, SIXTEEN_MIB, true)).isFalse();
}
@Test
void aResponseThatCannotSendFileIsNeverEligible() {
assertThat(ZeroCopyEligibility.standard().isEligible(false, SIXTEEN_MIB, false)).isFalse();
}
@Test
void theDisabledProfileNeverTakesTheOptimization() {
assertThat(ZeroCopyEligibility.disabled().isEligible(true, Long.MAX_VALUE, false)).isFalse();
}
@Test
void theCapabilityProbeReadsTheResponseImplementation() {
assertThat(ZeroCopyEligibility.supportsZeroCopy(new MockServerHttpResponse()))
.isEqualTo(
new MockServerHttpResponse()
instanceof org.springframework.http.ZeroCopyHttpOutputMessage);
}
}
@@ -1,118 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.nginx;
import static org.assertj.core.api.Assertions.assertThat;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.header;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import dev.caskeleton.adapter.inbound.web.fileserver.controller.FileDownloadController;
import dev.caskeleton.adapter.inbound.web.fileserver.http.MvcConditionalRequestFactory;
import dev.caskeleton.adapter.inbound.web.fileserver.http.MvcDownloadResponseWriter;
import dev.caskeleton.adapter.inbound.web.fileserver.http.ZeroCopyEligibility;
import dev.caskeleton.adapter.inbound.web.fileserver.problem.FileserverExceptionHandler;
import dev.caskeleton.adapter.inbound.web.fileserver.problem.FileserverProblemFactory;
import dev.caskeleton.adapter.inbound.web.fileserver.testkit.FileserverWebFixtures;
import dev.caskeleton.adapter.inbound.web.fileserver.testkit.StubDownloadService;
import dev.caskeleton.application.fileserver.api.FileState;
import org.junit.jupiter.api.Test;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
class NginxDownloadDelegationTest {
private static final int LARGE_ENOUGH = 32;
private final StubDownloadService downloadService = new StubDownloadService();
@Test
void aLargeReadyDownloadIsHandedToTheProxyWithoutStreamingInProcess() throws Exception {
downloadService.store(new byte[LARGE_ENOUGH]);
MockMvc mvc = mvc(new NginxDelegationProperties(true, "/__files/", ".bin", LARGE_ENOUGH));
mvc.perform(get(contentUrl()))
.andExpect(status().isOk())
.andExpect(
header()
.string(
NginxDownloadStrategy.ACCEL_REDIRECT_HEADER,
"/__files/ab/cd/stub-object-000001.bin"))
.andExpect(header().string("ETag", downloadService.strongEtag()))
.andExpect(content().bytes(new byte[0]));
assertThat(downloadService.neverOpened())
.as("a delegated transfer must not also be read in-process")
.isTrue();
}
@Test
void aSmallDownloadIsStillServedInProcess() throws Exception {
downloadService.store(new byte[] {1, 2, 3});
MockMvc mvc = mvc(new NginxDelegationProperties(true, "/__files/", ".bin", LARGE_ENOUGH));
mvc.perform(get(contentUrl()))
.andExpect(status().isOk())
.andExpect(header().doesNotExist(NginxDownloadStrategy.ACCEL_REDIRECT_HEADER))
.andExpect(content().bytes(new byte[] {1, 2, 3}));
}
@Test
void aRangeRequestIsNeverDelegated() throws Exception {
downloadService.store(new byte[LARGE_ENOUGH]);
MockMvc mvc = mvc(new NginxDelegationProperties(true, "/__files/", ".bin", 1));
mvc.perform(get(contentUrl()).header("Range", "bytes=2-4"))
.andExpect(status().isPartialContent())
.andExpect(header().doesNotExist(NginxDownloadStrategy.ACCEL_REDIRECT_HEADER));
}
@Test
void aNotModifiedAnswerIsNeverDelegated() throws Exception {
downloadService.store(new byte[LARGE_ENOUGH]);
MockMvc mvc = mvc(new NginxDelegationProperties(true, "/__files/", ".bin", 1));
mvc.perform(get(contentUrl()).header("If-None-Match", downloadService.strongEtag()))
.andExpect(status().isNotModified())
.andExpect(header().doesNotExist(NginxDownloadStrategy.ACCEL_REDIRECT_HEADER));
}
@Test
void aNonReadyFileIsNeverDelegated() throws Exception {
downloadService.fileInState(FileState.VERIFYING);
MockMvc mvc = mvc(new NginxDelegationProperties(true, "/__files/", ".bin", 1));
mvc.perform(get(contentUrl()))
.andExpect(status().isConflict())
.andExpect(header().doesNotExist(NginxDownloadStrategy.ACCEL_REDIRECT_HEADER));
}
@Test
void theDisabledProfileNeverEmitsTheHeader() throws Exception {
downloadService.store(new byte[LARGE_ENOUGH]);
MockMvc mvc = mvc(NginxDelegationProperties.disabled());
mvc.perform(get(contentUrl()))
.andExpect(status().isOk())
.andExpect(header().doesNotExist(NginxDownloadStrategy.ACCEL_REDIRECT_HEADER));
}
private MockMvc mvc(NginxDelegationProperties properties) {
return MockMvcBuilders.standaloneSetup(
new FileDownloadController(
downloadService,
new MvcConditionalRequestFactory(),
downloadService.httpPlanner(),
new MvcDownloadResponseWriter(),
FileserverWebFixtures.contextFactory(),
FileserverWebFixtures.transferExecutor(),
new NginxDownloadStrategy(
properties, new DefaultNginxInternalUriMapper(properties)),
ZeroCopyEligibility.disabled()))
.setControllerAdvice(new FileserverExceptionHandler(new FileserverProblemFactory()))
.build();
}
private static String contentUrl() {
return "/v1/files/" + StubDownloadService.anyFileId().canonicalText() + "/content";
}
}
@@ -1,60 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.nginx;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.application.fileserver.api.ContentKey;
import dev.caskeleton.application.fileserver.api.error.InvalidPathException;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.ValueSource;
class NginxInternalUriMapperTest {
private final NginxInternalUriMapper mapper =
new DefaultNginxInternalUriMapper(NginxDelegationProperties.enabledWithDefaults());
@Test
void mapsAValidatedContentKeyWithoutExposingAnAbsolutePath() {
String internalUri = mapper.map(ContentKey.of("ab/cd/0123456789abcdef"));
assertThat(internalUri).isEqualTo("/__files/ab/cd/0123456789abcdef.bin");
assertThat(internalUri).doesNotContain("/var/lib").doesNotContain("..").doesNotContain("\\");
}
@Test
void theUriIsAlwaysRelativeToTheInternalPrefix() {
assertThat(mapper.map(ContentKey.of("ab/cd/0123456789abcdef"))).startsWith("/__files/");
}
@ParameterizedTest
@ValueSource(
strings = {
"../../etc/passwd",
"/etc/passwd",
"ab/cd/../../../etc/passwd",
"ab/cd/short",
"AB/CD/0123456789abcdef",
"ab//cd/0123456789abcdef"
})
void rejectsAMalformedKeyEvenWhenCalledInternally(String rawKey) {
assertThatThrownBy(() -> mapper.mapUnchecked(rawKey)).isInstanceOf(InvalidPathException.class);
}
@Test
void aNullKeyIsRejectedRatherThanProducingAPrefixOnlyUri() {
assertThatThrownBy(() -> mapper.mapUnchecked(null)).isInstanceOf(InvalidPathException.class);
}
@Test
void anUnsafeInternalPrefixIsRejectedAtConstruction() {
assertThatThrownBy(() -> new NginxDelegationProperties(true, "/../files/", ".bin", 1))
.isInstanceOf(IllegalArgumentException.class);
}
@Test
void anInternalPrefixWithoutATrailingSlashIsRejected() {
assertThatThrownBy(() -> new NginxDelegationProperties(true, "/__files", ".bin", 1))
.isInstanceOf(IllegalArgumentException.class);
}
}
@@ -1,84 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.problem;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.inbound.web.fileserver.http.HttpRangeNotSatisfiableException;
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
import dev.caskeleton.application.fileserver.api.error.FileserverFailureContext;
import dev.caskeleton.application.fileserver.api.error.StorageUnavailableException;
import dev.caskeleton.application.fileserver.api.error.TransferAdmissionRejectedException;
import java.util.Map;
import org.junit.jupiter.api.Test;
/**
* The response contract must not depend on which transport happened to serve the request.
*
* <p>The servlet advice owned a {@code Retry-After} table and the reactive router had none, so the
* same rejection told one client to come back in a second and the other nothing at all. A client
* that cannot tell a temporary refusal from a permanent one either retries immediately — turning a
* saturation signal into a stampede — or abandons work that would have succeeded.
*/
class FileserverProblemHeaderParityTest {
@Test
void aRetryableRejectionAdvertisesHowLongToWait() {
Map<String, String> headers =
FileserverProblemHeaders.of(
new TransferAdmissionRejectedException(
"saturated",
FileserverFailureContext.of(
FileserverErrorCode.TRANSFER_ADMISSION_REJECTED, true)));
assertThat(headers).containsEntry("Retry-After", "1");
}
/**
* A permanent failure must stay silent about retrying.
*
* <p>The code alone is not enough to decide: the same code can arrive retryable or not, and
* telling a client to come back after a permanent rejection is worse than saying nothing.
*/
@Test
void aFailureTheServerCalledPermanentAdvertisesNoRetry() {
Map<String, String> headers =
FileserverProblemHeaders.of(
new StorageUnavailableException(
"gone for good",
FileserverFailureContext.of(FileserverErrorCode.STORAGE_UNAVAILABLE, false)));
assertThat(headers).doesNotContainKey("Retry-After");
}
@Test
void anUnsatisfiableRangeDisclosesTheRepresentationLength() {
Map<String, String> headers =
FileserverProblemHeaders.of(HttpRangeNotSatisfiableException.of(4096));
assertThat(headers).containsEntry("Content-Range", "bytes */4096");
}
/**
* Both transports read this one table, which is what makes parity structural.
*
* <p>Asserting that the servlet advice and the reactive router each emit the same headers would
* need two running servers; asserting that neither of them owns a table is cheaper and catches
* the reintroduction of a private copy, which is how the drift happened the first time.
*/
@Test
void neitherTransportKeepsItsOwnRetryAfterTable() throws Exception {
assertThat(declaredFieldNames(FileserverExceptionHandler.class))
.noneMatch(name -> name.toUpperCase(java.util.Locale.ROOT).contains("RETRY"));
assertThat(
declaredFieldNames(
Class.forName(
"dev.caskeleton.adapter.inbound.web.fileserver.reactive"
+ ".FileserverRouterFactory")))
.noneMatch(name -> name.toUpperCase(java.util.Locale.ROOT).contains("RETRY"));
}
private static java.util.List<String> declaredFieldNames(Class<?> type) {
return java.util.Arrays.stream(type.getDeclaredFields())
.map(java.lang.reflect.Field::getName)
.toList();
}
}
@@ -1,93 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.reactive;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.adapter.inbound.web.fileserver.testkit.CountingDataBufferFactory;
import java.io.IOException;
import java.nio.ByteBuffer;
import java.nio.channels.ReadableByteChannel;
import java.nio.charset.StandardCharsets;
import java.util.concurrent.atomic.AtomicLong;
import org.junit.jupiter.api.Test;
import org.springframework.core.io.buffer.DataBuffer;
import reactor.core.publisher.Flux;
class DataBufferReleaseTest {
private final CountingDataBufferFactory buffers = new CountingDataBufferFactory();
@Test
void everyObservedBufferIsReleasedOnceTheBodyIsFullyRead() throws Exception {
ReadableByteChannel channel =
DataBufferByteChannel.subscribeTo(Flux.just(buffers.wrap("abc"), buffers.wrap("def")), 8);
assertThat(drain(channel)).isEqualTo("abcdef");
assertThat(buffers.releasedCount()).isEqualTo(buffers.allocatedCount());
}
@Test
void closingEarlyStillLeavesNoBufferRetained() throws Exception {
ReadableByteChannel channel =
DataBufferByteChannel.subscribeTo(
Flux.just(buffers.wrap("abc"), buffers.wrap("def"), buffers.wrap("ghi")), 8);
ByteBuffer first = ByteBuffer.allocate(3);
channel.read(first);
channel.close();
assertThat(buffers.releasedCount()).isEqualTo(buffers.allocatedCount());
}
@Test
void anUpstreamFailureSurfacesAsAnIoFailureRatherThanASilentTruncation() {
ReadableByteChannel channel =
DataBufferByteChannel.subscribeTo(
Flux.concat(
Flux.just(buffers.wrap("abc")),
Flux.error(new IllegalStateException("connection reset"))),
8);
assertThatThrownBy(() -> drain(channel))
.isInstanceOf(IOException.class)
.hasMessageContaining("request body failed");
}
@Test
void inFlightBuffersNeverExceedThePrefetch() throws Exception {
AtomicLong maxOutstanding = new AtomicLong();
AtomicLong outstanding = new AtomicLong();
Flux<DataBuffer> body =
Flux.range(0, 64)
.map(index -> buffers.wrap("chunk" + index))
.doOnNext(
buffer -> maxOutstanding.accumulateAndGet(outstanding.incrementAndGet(), Math::max))
.doOnNext(buffer -> outstanding.decrementAndGet());
ReadableByteChannel channel = DataBufferByteChannel.subscribeTo(body, 4);
drain(channel);
assertThat(maxOutstanding.get()).isLessThanOrEqualTo(4);
}
@Test
void aClosedChannelRefusesFurtherReads() throws Exception {
ReadableByteChannel channel =
DataBufferByteChannel.subscribeTo(Flux.just(buffers.wrap("abc")), 8);
channel.close();
assertThat(channel.isOpen()).isFalse();
assertThatThrownBy(() -> channel.read(ByteBuffer.allocate(3))).isInstanceOf(IOException.class);
}
private static String drain(ReadableByteChannel channel) throws IOException {
ByteBuffer buffer = ByteBuffer.allocate(64);
StringBuilder received = new StringBuilder();
while (channel.read(buffer) >= 0) {
buffer.flip();
received.append(StandardCharsets.UTF_8.decode(buffer));
buffer.clear();
}
return received.toString();
}
}
@@ -1,90 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.reactive;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.inbound.web.fileserver.testkit.CountingDataBufferFactory;
import dev.caskeleton.application.fileserver.api.error.FileTooLargeException;
import java.nio.charset.StandardCharsets;
import java.util.List;
import org.junit.jupiter.api.Test;
import org.springframework.core.io.buffer.DataBuffer;
import org.springframework.core.io.buffer.DataBufferUtils;
import org.springframework.http.MediaType;
import org.springframework.http.codec.multipart.FilePartEvent;
import org.springframework.http.codec.multipart.FormPartEvent;
import org.springframework.http.codec.multipart.PartEvent;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;
import reactor.test.StepVerifier;
class PartEventUploadReaderTest {
private final CountingDataBufferFactory buffers = new CountingDataBufferFactory();
@Test
void partsAreReadSequentiallyAndNeverInterleave() {
PartEventUploadReader reader = new PartEventUploadReader(16);
List<String> collected =
reader
.<String>forEachPart(
Flux.concat(filePart("a.txt", "aaa"), filePart("b.txt", "bbb")),
(intent, content) ->
content
.map(PartEventUploadReaderTest::text)
.collectList()
.map(chunks -> intent.originalFilename() + "=" + String.join("", chunks)))
.collectList()
.block();
assertThat(collected).containsExactly("a.txt=aaa", "b.txt=bbb");
}
@Test
void anOversizedBatchIsRejectedAsSoonAsTheLimitIsCrossed() {
PartEventUploadReader reader = new PartEventUploadReader(1);
StepVerifier.create(
reader.forEachPart(
Flux.concat(filePart("a.txt", "aaa"), filePart("b.txt", "bbb")),
(intent, content) -> release(content).then(Mono.just(intent.originalFilename()))))
.expectNext("a.txt")
.expectError(FileTooLargeException.class)
.verify();
}
@Test
void aNonFilePartIsDrainedRatherThanLeftUnreleased() {
PartEventUploadReader reader = new PartEventUploadReader(16);
List<String> collected =
reader
.<String>forEachPart(
Flux.concat(
FormPartEvent.create("note", "hello").cast(PartEvent.class),
filePart("a.txt", "aaa")),
(intent, content) -> release(content).then(Mono.just(intent.originalFilename())))
.collectList()
.block();
assertThat(collected).containsExactly("a.txt");
assertThat(buffers.releasedCount()).isEqualTo(buffers.allocatedCount());
}
/** Drains and releases a part body, which is what a real handler's channel bridge does. */
private static Mono<Void> release(Flux<DataBuffer> content) {
return content.doOnNext(DataBufferUtils::release).then();
}
private Flux<PartEvent> filePart(String filename, String payload) {
DataBuffer buffer = buffers.wrap(payload);
return FilePartEvent.create("files", filename, MediaType.TEXT_PLAIN, Flux.just(buffer))
.cast(PartEvent.class);
}
private static String text(DataBuffer buffer) {
byte[] bytes = new byte[buffer.readableByteCount()];
buffer.read(bytes);
return new String(bytes, StandardCharsets.UTF_8);
}
}
@@ -1,211 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.reactive;
import static org.assertj.core.api.Assertions.assertThat;
import dev.caskeleton.adapter.inbound.web.fileserver.dto.UploadedFileResponse;
import dev.caskeleton.adapter.inbound.web.fileserver.mapper.RawUploadRequestMapper;
import dev.caskeleton.adapter.inbound.web.fileserver.problem.FileserverProblemFactory;
import dev.caskeleton.adapter.inbound.web.fileserver.testkit.CountingDataBufferFactory;
import dev.caskeleton.adapter.inbound.web.fileserver.testkit.FileserverWebFixtures;
import dev.caskeleton.adapter.inbound.web.fileserver.testkit.RecordingUploadService;
import dev.caskeleton.adapter.inbound.web.fileserver.testkit.StubDownloadService;
import dev.caskeleton.application.fileserver.api.FileState;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.Test;
import org.springframework.core.io.buffer.DataBuffer;
import org.springframework.http.MediaType;
import org.springframework.test.web.reactive.server.WebTestClient;
import reactor.core.publisher.Flux;
class ReactiveFileserverContractTest {
private final CountingDataBufferFactory buffers = new CountingDataBufferFactory();
private final RecordingUploadService uploadService = new RecordingUploadService();
private final StubDownloadService downloadService = new StubDownloadService();
private final FileserverIoScheduler ioScheduler = new FileserverIoScheduler(4, 32);
private final WebTestClient client = WebTestClient.bindToRouterFunction(routes()).build();
@AfterEach
void closeScheduler() {
ioScheduler.close();
}
@Test
void rawUploadConsumesTheStreamWithoutJoiningTheWholeBody() {
client
.post()
.uri("/v1/files:raw")
.contentType(MediaType.APPLICATION_OCTET_STREAM)
.header(RawUploadRequestMapper.FILENAME_HEADER, "large.bin")
.body(Flux.just(buffers.wrap("abc"), buffers.wrap("def")), DataBuffer.class)
.exchange()
.expectStatus()
.isCreated()
.expectHeader()
.exists("Location")
.expectBody()
.jsonPath("$.state")
.isEqualTo("READY");
assertThat(uploadService.receivedBodies()).containsExactly("abcdef");
assertThat(buffers.releasedCount()).isEqualTo(buffers.allocatedCount());
}
@Test
void aStillVerifyingUploadIsAcceptedRatherThanCreated() {
uploadService.answerWith(FileState.VERIFYING);
client
.post()
.uri("/v1/files:raw")
.contentType(MediaType.APPLICATION_OCTET_STREAM)
.header(RawUploadRequestMapper.FILENAME_HEADER, "large.bin")
.body(Flux.just(buffers.wrap("abc")), DataBuffer.class)
.exchange()
.expectStatus()
.isAccepted();
}
@Test
void rangeHeadersMatchTheServletContract() {
client
.get()
.uri(contentUrl())
.header("Range", "bytes=2-4")
.exchange()
.expectStatus()
.isEqualTo(206)
.expectHeader()
.valueEquals("Content-Range", "bytes 2-4/10")
.expectHeader()
.valueEquals("Content-Length", "3")
.expectHeader()
.valueEquals("Accept-Ranges", "bytes")
.expectBody(byte[].class)
.isEqualTo(new byte[] {2, 3, 4});
}
@Test
void aFullGetCarriesTheSameValidatorsAsTheServletPath() {
client
.get()
.uri(contentUrl())
.exchange()
.expectStatus()
.isOk()
.expectHeader()
.valueEquals("ETag", downloadService.strongEtag())
.expectHeader()
.valueEquals("Cache-Control", "private, no-store")
.expectBody(byte[].class)
.isEqualTo(new byte[] {0, 1, 2, 3, 4, 5, 6, 7, 8, 9});
}
@Test
void aMatchingValidatorIsNotModifiedAndOpensNothing() {
client
.get()
.uri(contentUrl())
.header("If-None-Match", downloadService.strongEtag())
.exchange()
.expectStatus()
.isNotModified();
assertThat(downloadService.neverOpened()).isTrue();
}
@Test
void anUnsatisfiableRangeIsAProblemDocumentCarryingTheRealLength() {
client
.get()
.uri(contentUrl())
.header("Range", "bytes=50-60")
.exchange()
.expectStatus()
.isEqualTo(416)
.expectHeader()
.valueEquals("Content-Range", "bytes */10")
.expectHeader()
.contentType(MediaType.APPLICATION_PROBLEM_JSON);
}
@Test
void aNonReadyFileIsAConflictProblemDocument() {
downloadService.fileInState(FileState.VERIFYING);
client
.get()
.uri(contentUrl())
.exchange()
.expectStatus()
.isEqualTo(409)
.expectBody()
.jsonPath("$.code")
.isEqualTo("FILE_NOT_READY");
assertThat(downloadService.neverOpened()).isTrue();
}
@Test
void headCarriesTheSameHeadersWithoutABody() {
byte[] body =
client
.head()
.uri(contentUrl())
.exchange()
.expectStatus()
.isOk()
.expectHeader()
.valueEquals("ETag", downloadService.strongEtag())
.expectHeader()
.valueEquals("Content-Length", "10")
.expectBody(byte[].class)
.returnResult()
.getResponseBody();
assertThat(body)
.satisfiesAnyOf(value -> assertThat(value).isNull(), value -> assertThat(value).isEmpty());
}
@Test
void theMetadataEndpointReportsTheDescriptor() {
client
.get()
.uri("/v1/files/" + StubDownloadService.anyFileId().canonicalText())
.exchange()
.expectStatus()
.isOk()
.expectBody(UploadedFileResponse.class)
.value(response -> assertThat(response.state()).isEqualTo("READY"));
}
private org.springframework.web.reactive.function.server.RouterFunction<
org.springframework.web.reactive.function.server.ServerResponse>
routes() {
ReactiveUploadApplicationService reactiveUpload =
new ReactiveUploadApplicationService(uploadService, ioScheduler);
FileUploadHandler uploadHandler =
new FileUploadHandler(
reactiveUpload,
new PartEventUploadReader(16),
FileserverWebFixtures.properties(),
FileserverWebFixtures.clock());
FileDownloadHandler downloadHandler =
new FileDownloadHandler(
downloadService,
new ReactiveDownloadResponseWriter(),
downloadService.httpPlanner(),
ioScheduler);
return new FileserverRouterFactory(
uploadHandler,
downloadHandler,
new FileserverProblemFactory(),
() -> FileserverWebFixtures.requestContext())
.routes();
}
private static String contentUrl() {
return "/v1/files/" + StubDownloadService.anyFileId().canonicalText() + "/content";
}
}
@@ -1,197 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.security;
import static org.assertj.core.api.Assertions.assertThat;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.header;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import dev.caskeleton.adapter.inbound.web.fileserver.controller.FileDownloadController;
import dev.caskeleton.adapter.inbound.web.fileserver.controller.FileUploadController;
import dev.caskeleton.adapter.inbound.web.fileserver.http.MvcConditionalRequestFactory;
import dev.caskeleton.adapter.inbound.web.fileserver.http.MvcDownloadResponseWriter;
import dev.caskeleton.adapter.inbound.web.fileserver.http.ZeroCopyEligibility;
import dev.caskeleton.adapter.inbound.web.fileserver.mapper.MultipartUploadRequestMapper;
import dev.caskeleton.adapter.inbound.web.fileserver.mapper.RawUploadRequestMapper;
import dev.caskeleton.adapter.inbound.web.fileserver.problem.FileserverExceptionHandler;
import dev.caskeleton.adapter.inbound.web.fileserver.problem.FileserverProblemFactory;
import dev.caskeleton.adapter.inbound.web.fileserver.testkit.FileserverWebFixtures;
import dev.caskeleton.adapter.inbound.web.fileserver.testkit.RecordingUploadService;
import dev.caskeleton.adapter.inbound.web.fileserver.testkit.StubDownloadService;
import dev.caskeleton.application.fileserver.api.security.OriginalFilenamePolicy;
import dev.caskeleton.application.fileserver.api.security.SanitizedFilename;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.ValueSource;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
class FileserverHardeningContractTest {
private final RecordingUploadService uploads = new RecordingUploadService();
private final StubDownloadService downloads = new StubDownloadService();
private final MockMvc uploadMvc =
MockMvcBuilders.standaloneSetup(
new FileUploadController(
uploads,
new RawUploadRequestMapper(false),
new MultipartUploadRequestMapper(),
FileserverWebFixtures.contextFactory(),
FileserverWebFixtures.transferExecutor(),
FileserverWebFixtures.properties(),
FileserverWebFixtures.clock()))
.setControllerAdvice(new FileserverExceptionHandler(new FileserverProblemFactory()))
.build();
private final MockMvc downloadMvc =
MockMvcBuilders.standaloneSetup(
new FileDownloadController(
downloads,
new MvcConditionalRequestFactory(),
downloads.httpPlanner(),
new MvcDownloadResponseWriter(),
FileserverWebFixtures.contextFactory(),
FileserverWebFixtures.transferExecutor(),
FileserverWebFixtures.noDelegation(),
ZeroCopyEligibility.disabled()))
.setControllerAdvice(new FileserverExceptionHandler(new FileserverProblemFactory()))
.build();
@ParameterizedTest
@ValueSource(
strings = {
"../x",
"../../etc/passwd",
"%2e%2e%2fx",
"/etc/passwd",
"C:\\Windows\\system.ini",
"..\\..\\windows\\win.ini"
})
void aPathShapedFilenameNeverReachesTheApplicationLayerIntact(String submitted) throws Exception {
uploadMvc
.perform(
post("/v1/files:raw")
.contentType(MediaType.APPLICATION_OCTET_STREAM)
.header(RawUploadRequestMapper.FILENAME_HEADER, submitted)
.content("abc"))
.andExpect(status().isCreated());
SanitizedFilename sanitized =
OriginalFilenamePolicy.standard()
.sanitize(uploads.requests().get(uploads.requests().size() - 1).originalFilename());
assertThat(sanitized.value())
.doesNotContain("..")
.doesNotContain("/")
.doesNotContain("\\")
.doesNotContain(":");
}
@ParameterizedTest
@ValueSource(strings = {"a\r\nX-Injected: 1.pdf", "a\nSet-Cookie: x=1.pdf", "a\u0000b.pdf"})
void aFilenameCarryingAnInjectionIsNeutralizedBeforeItReachesAHeader(String submitted) {
SanitizedFilename sanitized = OriginalFilenamePolicy.standard().sanitize(submitted);
assertThat(sanitized.value())
.doesNotContain("\r")
.doesNotContain("\n")
.doesNotContain("\u0000");
}
@Test
void aBidiOverrideInAFilenameIsRemoved() {
SanitizedFilename sanitized =
OriginalFilenamePolicy.standard().sanitize("invoice\u202egpj.exe");
assertThat(sanitized.value()).doesNotContain("\u202e");
}
@Test
void everyDownloadCarriesNosniff() throws Exception {
downloadMvc
.perform(get(contentUrl()))
.andExpect(status().isOk())
.andExpect(header().string(MvcDownloadResponseWriter.CONTENT_TYPE_OPTIONS, "nosniff"));
}
@Test
void scriptableContentIsAlwaysOfferedAsAnAttachment() throws Exception {
downloads.named("page.html", "text/html");
downloadMvc
.perform(get(contentUrl()).param("inline", "true"))
.andExpect(
header()
.string("Content-Disposition", org.hamcrest.Matchers.startsWith("attachment;")));
}
@Test
void excessiveRangesAreRejectedBeforeContentIsOpened() throws Exception {
downloadMvc
.perform(
get(contentUrl()).header("Range", "bytes=0-0,2-2,4-4,6-6,8-8,10-10,12-12,14-14,16-16"))
.andExpect(status().is4xxClientError());
assertThat(downloads.neverOpened()).isTrue();
}
@Test
void anUnsatisfiableRangeIsRejectedBeforeContentIsOpened() throws Exception {
downloadMvc
.perform(get(contentUrl()).header("Range", "bytes=9999-10000"))
.andExpect(status().is(416));
assertThat(downloads.neverOpened()).isTrue();
}
@Test
void aProblemDocumentNeverExposesAPathOrAJavaType() throws Exception {
downloads.fileInState(dev.caskeleton.application.fileserver.api.FileState.VERIFYING);
String body =
downloadMvc
.perform(get(contentUrl()))
.andExpect(status().isConflict())
.andReturn()
.getResponse()
.getContentAsString();
assertThat(body)
.doesNotContain("/var/lib")
.doesNotContain("staging")
.doesNotContain("java.nio.file")
.doesNotContain("Exception");
}
@Test
void theProblemDocumentCarriesTheStableCodeAndItsUrn() throws Exception {
downloads.fileInState(dev.caskeleton.application.fileserver.api.FileState.VERIFYING);
downloadMvc
.perform(get(contentUrl()))
.andExpect(status().isConflict())
.andExpect(header().string("Content-Type", "application/problem+json"))
.andExpect(
org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath("$.code")
.value("FILE_NOT_READY"))
.andExpect(
org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath("$.type")
.value("urn:fileserver:problem:file-not-ready"));
}
@Test
void aRetryableRejectionAdvisesWhenToComeBack() throws Exception {
downloads.fileInState(dev.caskeleton.application.fileserver.api.FileState.VERIFYING);
downloadMvc
.perform(get(contentUrl()))
.andExpect(status().isConflict())
.andExpect(header().exists("Retry-After"));
}
private static String contentUrl() {
return "/v1/files/" + StubDownloadService.anyFileId().canonicalText() + "/content";
}
}
@@ -1,48 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.testkit;
import java.util.concurrent.atomic.AtomicInteger;
import org.springframework.core.io.buffer.DataBuffer;
import org.springframework.core.io.buffer.DataBufferWrapper;
import org.springframework.core.io.buffer.PooledDataBuffer;
/**
* Reference-counted buffer whose release is observable.
*
* <p>A heap buffer's release is a no-op, so a leak test built on one proves nothing. This wrapper
* behaves like a pooled buffer — {@code DataBufferUtils.release} recognises it — and records
* exactly once when it is released.
*/
public final class CountingDataBuffer extends DataBufferWrapper implements PooledDataBuffer {
private final AtomicInteger releaseCounter;
private boolean allocated = true;
public CountingDataBuffer(DataBuffer delegate, AtomicInteger releaseCounter) {
super(delegate);
this.releaseCounter = releaseCounter;
}
@Override
public boolean isAllocated() {
return allocated;
}
@Override
public PooledDataBuffer retain() {
return this;
}
@Override
public PooledDataBuffer touch(Object hint) {
return this;
}
@Override
public boolean release() {
if (allocated) {
allocated = false;
releaseCounter.incrementAndGet();
}
return true;
}
}
@@ -1,30 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.testkit;
import java.nio.charset.StandardCharsets;
import java.util.concurrent.atomic.AtomicInteger;
import org.springframework.core.io.buffer.DataBuffer;
import org.springframework.core.io.buffer.DefaultDataBufferFactory;
/** Hands out counted buffers so a test can assert that every one of them was released. */
public final class CountingDataBufferFactory {
private final DefaultDataBufferFactory delegate = DefaultDataBufferFactory.sharedInstance;
private final AtomicInteger allocated = new AtomicInteger();
private final AtomicInteger released = new AtomicInteger();
public DataBuffer wrap(String payload) {
byte[] bytes = payload.getBytes(StandardCharsets.UTF_8);
DataBuffer buffer = delegate.allocateBuffer(Math.max(bytes.length, 1));
buffer.write(bytes);
allocated.incrementAndGet();
return new CountingDataBuffer(buffer, released);
}
public int allocatedCount() {
return allocated.get();
}
public int releasedCount() {
return released.get();
}
}
@@ -1,70 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.testkit;
import dev.caskeleton.adapter.inbound.web.fileserver.config.BlockingTransferExecutor;
import dev.caskeleton.adapter.inbound.web.fileserver.config.FileserverWebProperties;
import dev.caskeleton.adapter.inbound.web.fileserver.config.TransferExecutorProperties;
import dev.caskeleton.adapter.inbound.web.fileserver.nginx.DefaultNginxInternalUriMapper;
import dev.caskeleton.adapter.inbound.web.fileserver.nginx.NginxDelegationProperties;
import dev.caskeleton.adapter.inbound.web.fileserver.nginx.NginxDownloadStrategy;
import dev.caskeleton.adapter.inbound.web.fileserver.security.FileserverRequestContextFactory;
import dev.caskeleton.application.fileserver.api.StorageNamespace;
import dev.caskeleton.application.fileserver.api.security.FileAccessSubject;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import java.time.Clock;
import java.time.Instant;
import java.time.ZoneOffset;
import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;
/** Shared construction helpers for the Fileserver transport tests. */
public final class FileserverWebFixtures {
public static final Instant NOW = Instant.parse("2026-08-07T10:00:00Z");
private FileserverWebFixtures() {}
public static Clock clock() {
return Clock.fixed(NOW, ZoneOffset.UTC);
}
public static FileserverWebProperties properties() {
return FileserverWebProperties.standard(StorageNamespace.of("tenant-a"));
}
public static FileserverRequestContextFactory contextFactory() {
return new FileserverRequestContextFactory("node-test");
}
/**
* Ready-made context for the reactive routes, which resolve it per exchange rather than per
* thread.
*/
public static RequestContext requestContext() {
return new RequestContext(
FileAccessSubject.of("user-1", java.util.Set.of("uploader")), "trace-1", "node-test");
}
/** Delegation strategy that always transfers in-process, the default download profile. */
public static NginxDownloadStrategy noDelegation() {
NginxDelegationProperties properties = NginxDelegationProperties.disabled();
return new NginxDownloadStrategy(properties, new DefaultNginxInternalUriMapper(properties));
}
/** Transfer executor with the design's standard bounds. */
public static BlockingTransferExecutor transferExecutor() {
return transferExecutor(TransferExecutorProperties.standard());
}
public static BlockingTransferExecutor transferExecutor(TransferExecutorProperties properties) {
return new BlockingTransferExecutor(pool(properties), properties.awaitSeconds());
}
public static ThreadPoolTaskExecutor pool(TransferExecutorProperties properties) {
ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
executor.setCorePoolSize(properties.coreSize());
executor.setMaxPoolSize(properties.maxSize());
executor.setQueueCapacity(properties.queueCapacity());
executor.setThreadNamePrefix("fs-transfer-test-");
executor.initialize();
return executor;
}
}
@@ -1,159 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.testkit;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.UploadId;
import dev.caskeleton.application.fileserver.api.error.FileNotFoundException;
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
import dev.caskeleton.application.fileserver.api.error.FileserverFailureContext;
import dev.caskeleton.application.fileserver.api.error.UploadExpiredException;
import dev.caskeleton.application.fileserver.api.error.UploadOffsetMismatchException;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.upload.AppendUploadResult;
import dev.caskeleton.application.fileserver.upload.CreateUploadRequest;
import dev.caskeleton.application.fileserver.upload.UploadApplicationService;
import dev.caskeleton.application.fileserver.upload.UploadSessionView;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.ByteBuffer;
import java.nio.channels.ReadableByteChannel;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.HexFormat;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.UUID;
/**
* Upload service backed by in-memory buffers, with the real offset semantics.
*
* <p>The protocol adapters are only worth testing against something that actually enforces the
* offset rule, so this fake rejects a mismatched offset without mutating the buffer, exactly as the
* production service does.
*/
public final class InMemoryUploadApplicationService implements UploadApplicationService {
private final Map<UploadId, Session> sessions = new LinkedHashMap<>();
private boolean expired;
public void expireEverything() {
this.expired = true;
}
public String content(UploadId uploadId) {
return require(uploadId).buffer.toString(StandardCharsets.UTF_8);
}
public long offset(UploadId uploadId) {
return require(uploadId).buffer.size();
}
public boolean cancelled(UploadId uploadId) {
return require(uploadId).cancelled;
}
@Override
public UploadSessionView create(CreateUploadRequest request, RequestContext context) {
UploadId uploadId = UploadId.of(UUID.randomUUID());
Session session = new Session(FileId.of(UUID.randomUUID()), request);
sessions.put(uploadId, session);
return view(uploadId, session);
}
@Override
public AppendUploadResult append(
UploadId uploadId,
long expectedOffset,
ReadableByteChannel content,
long contentLength,
RequestContext context) {
requireNotExpired(uploadId);
Session session = require(uploadId);
if (expectedOffset != session.buffer.size()) {
throw UploadOffsetMismatchException.of(uploadId, expectedOffset, session.buffer.size());
}
long appended = drainInto(content, session.buffer);
return new AppendUploadResult(session.buffer.size(), appended, digestOf(session));
}
@Override
public UploadSessionView status(UploadId uploadId, RequestContext context) {
return view(uploadId, require(uploadId));
}
@Override
public void cancel(UploadId uploadId, RequestContext context) {
require(uploadId).cancelled = true;
}
private void requireNotExpired(UploadId uploadId) {
if (expired) {
throw new UploadExpiredException(
"upload resource has expired",
FileserverFailureContext.forUpload(
FileserverErrorCode.UPLOAD_EXPIRED, uploadId, false, false, false));
}
}
private static long drainInto(ReadableByteChannel content, ByteArrayOutputStream target) {
ByteBuffer buffer = ByteBuffer.allocate(8192);
long appended = 0;
try {
while (content.read(buffer) >= 0) {
buffer.flip();
while (buffer.hasRemaining()) {
target.write(buffer.get());
appended++;
}
buffer.clear();
}
} catch (IOException exception) {
throw new UncheckedIOException(exception);
}
return appended;
}
private static String digestOf(Session session) {
try {
return HexFormat.of()
.formatHex(MessageDigest.getInstance("SHA-256").digest(session.buffer.toByteArray()));
} catch (NoSuchAlgorithmException impossible) {
throw new IllegalStateException("SHA-256 is required by the platform", impossible);
}
}
private static UploadSessionView view(UploadId uploadId, Session session) {
return new UploadSessionView(
uploadId,
session.fileId,
session.buffer.size(),
session.request.expectedLength(),
session.request.expiresAt());
}
private Session require(UploadId uploadId) {
Session session = sessions.get(uploadId);
if (session == null) {
throw new FileNotFoundException(
"upload resource does not exist",
FileserverFailureContext.forUpload(
FileserverErrorCode.FILE_NOT_FOUND, uploadId, false, false, false));
}
return session;
}
/** One in-flight upload; the buffer is the durable state this fake models. */
private static final class Session {
private final FileId fileId;
private final CreateUploadRequest request;
private final ByteArrayOutputStream buffer = new ByteArrayOutputStream();
private boolean cancelled;
private Session(FileId fileId, CreateUploadRequest request) {
this.fileId = fileId;
this.request = request;
}
}
}
@@ -1,107 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.testkit;
import dev.caskeleton.application.fileserver.admin.FileserverAdminService;
import dev.caskeleton.application.fileserver.admin.ForceDeleteCommand;
import dev.caskeleton.application.fileserver.admin.IncompleteUploadView;
import dev.caskeleton.application.fileserver.admin.OrphanObject;
import dev.caskeleton.application.fileserver.admin.OrphanReconcileCommand;
import dev.caskeleton.application.fileserver.admin.OrphanReconcileReport;
import dev.caskeleton.application.fileserver.admin.RuntimeCapabilityReport;
import dev.caskeleton.application.fileserver.admin.StorageHealthReport;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.FileState;
import dev.caskeleton.application.fileserver.api.StorageNamespace;
import dev.caskeleton.application.fileserver.api.UploadId;
import dev.caskeleton.application.fileserver.api.content.ContentStoreCapabilities;
import dev.caskeleton.application.fileserver.api.content.PublishMode;
import dev.caskeleton.application.fileserver.api.metadata.FileDescriptor;
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.ArrayList;
import java.util.List;
import java.util.Optional;
import java.util.UUID;
/** Admin service that records what the controller forwarded, without touching storage. */
public final class RecordingAdminService implements FileserverAdminService {
private final List<ForceDeleteCommand> forceDeletes = new ArrayList<>();
private OrphanReconcileCommand lastReconcile;
public List<ForceDeleteCommand> forceDeletes() {
return List.copyOf(forceDeletes);
}
public OrphanReconcileCommand lastReconcile() {
return lastReconcile;
}
/** Always zero: this fake never deletes, so a dry-run assertion cannot pass by accident. */
public int deletedObjectCount() {
return 0;
}
@Override
public StorageHealthReport storageHealth(RequestContext context) {
return new StorageHealthReport(1000, 400, 0.6, true, true, "linux-ext4", List.of());
}
@Override
public RuntimeCapabilityReport capabilities(RequestContext context) {
return new RuntimeCapabilityReport(
"LOCAL",
PublishMode.ATOMIC_MOVE_PREFERRED,
new ContentStoreCapabilities(true, true, true, true, false, true, true),
"linux-ext4");
}
@Override
public List<OrphanObject> orphans(int limit, RequestContext context) {
return List.of();
}
@Override
public OrphanReconcileReport reconcileOrphans(
OrphanReconcileCommand command, RequestContext context) {
this.lastReconcile = command;
return new OrphanReconcileReport(command.dryRun(), List.of(), 0, 0, 0);
}
@Override
public FileView reverify(FileId fileId, RequestContext context) {
return FileView.of(
new FileDescriptor(
fileId,
StorageNamespace.of("tenant-a"),
FileState.VERIFYING,
"report.bin",
"application/octet-stream",
0,
"",
null,
1));
}
@Override
public void forceDelete(ForceDeleteCommand command, RequestContext context) {
forceDeletes.add(command);
}
@Override
public List<IncompleteUploadView> incompleteUploads(int limit, RequestContext context) {
return List.of(
new IncompleteUploadView(
UploadId.of(UUID.nameUUIDFromBytes(new byte[] {1})),
FileId.of(UUID.nameUUIDFromBytes(new byte[] {2})),
42,
FileserverWebFixtures.NOW,
Optional.of("node-a"),
Optional.of(FileserverWebFixtures.NOW)));
}
@Override
public CleanupBatchResult cleanupUploads(int maxItems, long maxBytes, RequestContext context) {
return CleanupBatchResult.empty();
}
}
@@ -1,48 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.testkit;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.FileState;
import dev.caskeleton.application.fileserver.api.StorageNamespace;
import dev.caskeleton.application.fileserver.api.UploadId;
import dev.caskeleton.application.fileserver.api.metadata.FileDescriptor;
import dev.caskeleton.application.fileserver.api.metadata.UploadSession;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.upload.FileView;
import dev.caskeleton.application.fileserver.upload.FinalizeUploadRequest;
import dev.caskeleton.application.fileserver.upload.FinalizeUploadService;
import java.util.ArrayList;
import java.util.List;
import java.util.UUID;
/** Records which uploads a protocol adapter decided to finalize. */
public final class RecordingFinalizeService implements FinalizeUploadService {
private final List<UploadId> finalized = new ArrayList<>();
public List<UploadId> finalized() {
return List.copyOf(finalized);
}
@Override
public FileView finalizeUpload(
UploadSession session, FinalizeUploadRequest request, RequestContext context) {
return finalizeUpload(session.uploadId(), request, context);
}
@Override
public FileView finalizeUpload(
UploadId uploadId, FinalizeUploadRequest request, RequestContext context) {
finalized.add(uploadId);
return FileView.of(
new FileDescriptor(
FileId.of(UUID.randomUUID()),
StorageNamespace.of("tenant-a"),
FileState.READY,
"report.bin",
"application/octet-stream",
0,
"",
FileserverWebFixtures.NOW,
1));
}
}
@@ -1,112 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.testkit;
import dev.caskeleton.application.fileserver.api.FileId;
import dev.caskeleton.application.fileserver.api.FileState;
import dev.caskeleton.application.fileserver.api.StorageNamespace;
import dev.caskeleton.application.fileserver.api.error.FileserverException;
import dev.caskeleton.application.fileserver.api.metadata.FileDescriptor;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.upload.CreateUploadRequest;
import dev.caskeleton.application.fileserver.upload.FileView;
import dev.caskeleton.application.fileserver.upload.FinalizeUploadRequest;
import dev.caskeleton.application.fileserver.upload.SingleShotUploadService;
import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.ByteBuffer;
import java.nio.channels.ReadableByteChannel;
import java.nio.charset.StandardCharsets;
import java.time.Instant;
import java.util.ArrayList;
import java.util.List;
import java.util.UUID;
import java.util.function.Function;
/**
* Single-shot upload service that drains the channel and records what it saw.
*
* <p>Draining is the point: a controller that buffered the body instead of streaming it would still
* pass a fake that ignored the channel, so this one proves the bytes actually arrived through the
* channel the controller handed over.
*/
public final class RecordingUploadService implements SingleShotUploadService {
private final List<String> receivedBodies = new ArrayList<>();
private final List<CreateUploadRequest> requests = new ArrayList<>();
private final List<Long> declaredContentLengths = new ArrayList<>();
private FileState resultState = FileState.READY;
private Function<String, FileserverException> failure;
public void answerWith(FileState state) {
this.resultState = state;
}
/** Makes the next uploads fail; the function decides per received body. */
public void failWith(Function<String, FileserverException> failure) {
this.failure = failure;
}
public List<String> receivedBodies() {
return List.copyOf(receivedBodies);
}
public List<CreateUploadRequest> requests() {
return List.copyOf(requests);
}
public List<Long> declaredContentLengths() {
return List.copyOf(declaredContentLengths);
}
@Override
public FileView upload(
CreateUploadRequest request,
ReadableByteChannel content,
long contentLength,
FinalizeUploadRequest finalizeRequest,
RequestContext context) {
String body = drain(content);
requests.add(request);
receivedBodies.add(body);
declaredContentLengths.add(contentLength);
FileserverException rejection = failure == null ? null : failure.apply(body);
if (rejection != null) {
throw rejection;
}
return view(request, body);
}
private static String drain(ReadableByteChannel channel) {
ByteBuffer buffer = ByteBuffer.allocate(8192);
StringBuilder received = new StringBuilder();
try {
while (channel.read(buffer) >= 0) {
buffer.flip();
received.append(StandardCharsets.UTF_8.decode(buffer));
buffer.clear();
}
} catch (IOException exception) {
throw new UncheckedIOException(exception);
}
return received.toString();
}
private FileView view(CreateUploadRequest request, String body) {
FileId fileId =
FileId.of(
UUID.nameUUIDFromBytes(
(request.originalFilename() + body).getBytes(StandardCharsets.UTF_8)));
FileDescriptor descriptor =
new FileDescriptor(
fileId,
StorageNamespace.of("tenant-a"),
resultState,
request.originalFilename(),
request.claimedMediaType().orElse("application/octet-stream"),
body.length(),
"c".repeat(64),
Instant.parse("2026-08-07T10:00:00Z"),
1);
return FileView.of(descriptor);
}
}
@@ -1,131 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.testkit;
import dev.caskeleton.adapter.inbound.web.fileserver.http.DefaultHttpRangeResolver;
import dev.caskeleton.adapter.inbound.web.fileserver.http.HttpContentDispositionFactory;
import dev.caskeleton.adapter.inbound.web.fileserver.http.HttpDownloadPlanner;
import dev.caskeleton.adapter.inbound.web.fileserver.http.HttpDownloadPolicy;
import dev.caskeleton.adapter.inbound.web.fileserver.http.HttpRangePolicy;
import dev.caskeleton.application.fileserver.api.ByteRange;
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 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.FileDescriptor;
import dev.caskeleton.application.fileserver.api.security.RequestContext;
import dev.caskeleton.application.fileserver.api.security.SanitizedFilename;
import dev.caskeleton.application.fileserver.api.transfer.FileRepresentation;
import dev.caskeleton.application.fileserver.download.DownloadApplicationService;
import dev.caskeleton.application.fileserver.download.DownloadDescriptor;
import dev.caskeleton.application.fileserver.download.DownloadRequest;
import dev.caskeleton.application.fileserver.download.ZeroCopyTransferResult;
import dev.caskeleton.application.fileserver.upload.FileView;
import java.io.ByteArrayInputStream;
import java.nio.channels.Channels;
import java.nio.channels.ReadableByteChannel;
import java.nio.channels.WritableByteChannel;
import java.time.Instant;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import java.util.UUID;
/** Download service backed by an in-memory immutable representation. */
public final class StubDownloadService implements DownloadApplicationService {
public static final String DIGEST = "d".repeat(64);
public static final Instant PUBLISHED_AT = Instant.parse("2026-08-07T10:00:00Z");
private final List<ByteRange> opened = new ArrayList<>();
private byte[] content = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9};
private FileState state = FileState.READY;
private String filename = "report.bin";
private String mediaType = "application/octet-stream";
public void store(byte[] bytes) {
this.content = bytes.clone();
}
public void fileInState(FileState state) {
this.state = state;
}
public void named(String filename, String mediaType) {
this.filename = filename;
this.mediaType = mediaType;
}
public List<ByteRange> opened() {
return List.copyOf(opened);
}
public boolean neverOpened() {
return opened.isEmpty();
}
public String strongEtag() {
return "\"" + DIGEST + "\"";
}
/** Real HTTP policy used by transport tests; only metadata/content remain stubbed. */
public HttpDownloadPlanner httpPlanner() {
return new HttpDownloadPlanner(
new DefaultHttpRangeResolver(),
new HttpContentDispositionFactory(),
new HttpDownloadPolicy(HttpRangePolicy.unbounded(), "private, no-store", false));
}
@Override
public FileView describeFile(FileId fileId, RequestContext context) {
return FileView.of(descriptor(fileId));
}
@Override
public DownloadDescriptor describe(DownloadRequest request, RequestContext context) {
if (!state.isPubliclyReadable()) {
throw new FileNotReadyException(
"file is not in a publicly readable state",
FileserverFailureContext.forFileState(
FileserverErrorCode.FILE_NOT_READY, request.fileId(), state, true));
}
return new DownloadDescriptor(
request.fileId(),
new FileRepresentation(DIGEST, PUBLISHED_AT, content.length, mediaType),
ContentKey.of("ab/cd/stub-object-000001"),
new SanitizedFilename(filename));
}
@Override
public ReadableByteChannel openContent(DownloadDescriptor descriptor, ByteRange range) {
opened.add(range);
int from = Math.toIntExact(range.startInclusive());
int to = Math.toIntExact(Math.min(range.endInclusive() + 1, content.length));
return Channels.newChannel(new ByteArrayInputStream(Arrays.copyOfRange(content, from, to)));
}
@Override
public ZeroCopyTransferResult transferContent(
DownloadDescriptor descriptor, ByteRange range, WritableByteChannel sink) {
return ZeroCopyTransferResult.notStarted();
}
private FileDescriptor descriptor(FileId fileId) {
return new FileDescriptor(
fileId,
StorageNamespace.of("tenant-a"),
state,
filename,
mediaType,
content.length,
DIGEST,
PUBLISHED_AT,
1);
}
public static FileId anyFileId() {
return FileId.of(
UUID.nameUUIDFromBytes("stub-download".getBytes(java.nio.charset.StandardCharsets.UTF_8)));
}
}
@@ -1,247 +0,0 @@
package dev.caskeleton.adapter.inbound.web.fileserver.tus;
import static org.assertj.core.api.Assertions.assertThat;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.delete;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.head;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.options;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.patch;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.header;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import dev.caskeleton.adapter.inbound.web.fileserver.problem.FileserverExceptionHandler;
import dev.caskeleton.adapter.inbound.web.fileserver.problem.FileserverProblemFactory;
import dev.caskeleton.adapter.inbound.web.fileserver.testkit.FileserverWebFixtures;
import dev.caskeleton.adapter.inbound.web.fileserver.testkit.InMemoryUploadApplicationService;
import dev.caskeleton.adapter.inbound.web.fileserver.testkit.RecordingFinalizeService;
import dev.caskeleton.application.fileserver.api.UploadId;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.Base64;
import java.util.HexFormat;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
class TusProtocolContractTest {
private static final TusProperties TUS = TusProperties.standard();
private final InMemoryUploadApplicationService uploads = new InMemoryUploadApplicationService();
private final RecordingFinalizeService finalizeService = new RecordingFinalizeService();
private MockMvc mvc;
@BeforeEach
void setUp() {
mvc =
MockMvcBuilders.standaloneSetup(
new TusController(
uploads,
finalizeService,
new TusRequestParser(TUS),
new TusChecksumVerifier(),
FileserverWebFixtures.contextFactory(),
FileserverWebFixtures.transferExecutor(),
FileserverWebFixtures.properties(),
TUS,
FileserverWebFixtures.clock()))
.setControllerAdvice(new FileserverExceptionHandler(new FileserverProblemFactory()))
.build();
}
@Test
void optionsAdvertisesTheVersionAndExtensions() throws Exception {
mvc.perform(options("/v1/uploads"))
.andExpect(status().isNoContent())
.andExpect(header().string(TusHeaders.VERSION, "1.0.0"))
.andExpect(
header().string(TusHeaders.EXTENSION, "creation,expiration,checksum,termination"))
.andExpect(header().string(TusHeaders.MAX_SIZE, String.valueOf(TUS.maxSize())));
}
@Test
void createHeadAndPatchFollowTheProtocol() throws Exception {
String location = create(6);
mvc.perform(
patch(location)
.header(TusHeaders.RESUMABLE, "1.0.0")
.header(TusHeaders.UPLOAD_OFFSET, "0")
.contentType(TusHeaders.OFFSET_OCTET_STREAM)
.content("abc"))
.andExpect(status().isNoContent())
.andExpect(header().string(TusHeaders.UPLOAD_OFFSET, "3"));
mvc.perform(head(location).header(TusHeaders.RESUMABLE, "1.0.0"))
.andExpect(status().isNoContent())
.andExpect(header().string(TusHeaders.UPLOAD_OFFSET, "3"))
.andExpect(header().string(TusHeaders.UPLOAD_LENGTH, "6"))
.andExpect(header().string("Cache-Control", "no-store"));
}
@Test
void mismatchedOffsetIsAConflictWithoutMutation() throws Exception {
String location = create(6);
appendAt(location, 0, "abc");
mvc.perform(
patch(location)
.header(TusHeaders.RESUMABLE, "1.0.0")
.header(TusHeaders.UPLOAD_OFFSET, "1")
.contentType(TusHeaders.OFFSET_OCTET_STREAM)
.content("x"))
.andExpect(status().isConflict());
assertThat(uploads.offset(uploadIdOf(location))).isEqualTo(3);
assertThat(uploads.content(uploadIdOf(location))).isEqualTo("abc");
}
@Test
void aRequestWithoutTheProtocolVersionIsRejectedBeforeAnythingHappens() throws Exception {
mvc.perform(post("/v1/uploads").header(TusHeaders.UPLOAD_LENGTH, "6"))
.andExpect(status().isBadRequest());
}
@Test
void aPatchWithTheWrongMediaTypeIsRejected() throws Exception {
String location = create(6);
mvc.perform(
patch(location)
.header(TusHeaders.RESUMABLE, "1.0.0")
.header(TusHeaders.UPLOAD_OFFSET, "0")
.contentType("application/octet-stream")
.content("abc"))
.andExpect(status().isUnsupportedMediaType());
}
@Test
void reachingTheDeclaredLengthFinalizesTheUpload() throws Exception {
String location = create(3);
appendAt(location, 0, "abc");
assertThat(finalizeService.finalized()).containsExactly(uploadIdOf(location));
}
@Test
void aDeferredLengthUploadIsNeverAutoFinalized() throws Exception {
String location =
mvc.perform(
post("/v1/uploads")
.header(TusHeaders.RESUMABLE, "1.0.0")
.header(TusHeaders.UPLOAD_DEFER_LENGTH, "1"))
.andExpect(status().isCreated())
.andReturn()
.getResponse()
.getHeader("Location");
appendAt(location, 0, "abc");
assertThat(finalizeService.finalized()).isEmpty();
mvc.perform(head(location).header(TusHeaders.RESUMABLE, "1.0.0"))
.andExpect(header().string(TusHeaders.UPLOAD_DEFER_LENGTH, "1"));
}
@Test
void aMatchingChecksumIsAcceptedAndAMismatchIsRejected() throws Exception {
String location = create(6);
mvc.perform(
patch(location)
.header(TusHeaders.RESUMABLE, "1.0.0")
.header(TusHeaders.UPLOAD_OFFSET, "0")
.header(TusHeaders.UPLOAD_CHECKSUM, "sha256 " + base64Sha256("abc"))
.contentType(TusHeaders.OFFSET_OCTET_STREAM)
.content("abc"))
.andExpect(status().isNoContent());
mvc.perform(
patch(location)
.header(TusHeaders.RESUMABLE, "1.0.0")
.header(TusHeaders.UPLOAD_OFFSET, "3")
.header(TusHeaders.UPLOAD_CHECKSUM, "sha256 " + base64Sha256("wrong"))
.contentType(TusHeaders.OFFSET_OCTET_STREAM)
.content("def"))
.andExpect(status().is(422));
}
@Test
void anExpiredUploadIsGoneRatherThanAConflict() throws Exception {
String location = create(6);
uploads.expireEverything();
mvc.perform(
patch(location)
.header(TusHeaders.RESUMABLE, "1.0.0")
.header(TusHeaders.UPLOAD_OFFSET, "0")
.contentType(TusHeaders.OFFSET_OCTET_STREAM)
.content("abc"))
.andExpect(status().isGone());
}
@Test
void terminationCancelsTheUploadResource() throws Exception {
String location = create(6);
mvc.perform(delete(location).header(TusHeaders.RESUMABLE, "1.0.0"))
.andExpect(status().isNoContent())
.andExpect(header().string(TusHeaders.RESUMABLE, "1.0.0"));
assertThat(uploads.cancelled(uploadIdOf(location))).isTrue();
}
@Test
void creationCarriesAnExpiryTheClientCanPlanAround() throws Exception {
mvc.perform(
post("/v1/uploads")
.header(TusHeaders.RESUMABLE, "1.0.0")
.header(TusHeaders.UPLOAD_LENGTH, "6"))
.andExpect(status().isCreated())
.andExpect(header().exists(TusHeaders.UPLOAD_EXPIRES))
.andExpect(header().string(TusHeaders.UPLOAD_OFFSET, "0"));
}
@Test
void aDeclaredLengthAboveTheAdvertisedMaximumIsRejected() throws Exception {
mvc.perform(
post("/v1/uploads")
.header(TusHeaders.RESUMABLE, "1.0.0")
.header(TusHeaders.UPLOAD_LENGTH, String.valueOf(TUS.maxSize() + 1)))
.andExpect(status().is(413));
}
private String create(long length) throws Exception {
return mvc.perform(
post("/v1/uploads")
.header(TusHeaders.RESUMABLE, "1.0.0")
.header(TusHeaders.UPLOAD_LENGTH, String.valueOf(length)))
.andExpect(status().isCreated())
.andReturn()
.getResponse()
.getHeader("Location");
}
private void appendAt(String location, long offset, String payload) throws Exception {
mvc.perform(
patch(location)
.header(TusHeaders.RESUMABLE, "1.0.0")
.header(TusHeaders.UPLOAD_OFFSET, String.valueOf(offset))
.contentType(TusHeaders.OFFSET_OCTET_STREAM)
.content(payload))
.andExpect(status().isNoContent());
}
private static UploadId uploadIdOf(String location) {
return UploadId.parse(location.substring(location.lastIndexOf('/') + 1));
}
private static String base64Sha256(String payload) throws Exception {
byte[] digest =
MessageDigest.getInstance("SHA-256").digest(payload.getBytes(StandardCharsets.UTF_8));
HexFormat.of().formatHex(digest);
return Base64.getEncoder().encodeToString(digest);
}
}
@@ -184,9 +184,31 @@ public final class WebBuildModel {
return List.copyOf(violations);
}
/** Every source root the module map governs. */
/**
* Every source root the module map governs.
*
* <p>Two, since the Fileserver capability's HTTP surface became `adapter:inbound:web-fileserver`.
* The module map did not move with it: `WebStableModule` still declares the twelve fileserver
* modules and their edges, because a second copy of the map in the second leaf would be a second
* answer to "is this edge declared", and one map with two source roots is what this method's
* plural has meant since it was written.
*
* <p>The sibling root is optional rather than required. A checkout that does not have it is a
* checkout where that leaf is absent, and the rules then govern what is present — the empty-scan
* guard in {@link #scan(List)} is what refuses a scan that found nothing at all.
*/
public static List<Path> platformSourceRoots() {
return List.of(mainSourceRoot());
Path own = mainSourceRoot();
Path sibling =
own.getParent()
.getParent()
.getParent()
.getParent()
.resolve("web-fileserver")
.resolve("src")
.resolve("main")
.resolve("java");
return Files.isDirectory(sibling) ? List.of(own, sibling) : List.of(own);
}
/**
@@ -0,0 +1,103 @@
package dev.caskeleton.adapter.inbound.web.mvc.autoconfigure;
import static org.assertj.core.api.Assertions.assertThat;
import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.core.annotation.AnnotatedElementUtils;
/**
* This leaf's auto-configurations are registered, not merely annotated.
*
* <p>Spring Boot needs two independent things before an auto-configuration runs: the annotation on
* the class, and a line naming it in {@code META-INF/spring/...AutoConfiguration.imports}. Tests
* that build a context with {@code AutoConfigurations.of(...)} supply the second one themselves, so
* they stay green for a capability that is present in no running application — which is exactly how
* several capabilities in this repository came to be assembled by nothing.
*
* <p>So this reads the registration file the jar actually ships and asserts both directions: every
* class this leaf means to register is named in it, and every name in it resolves to a class that
* carries {@code @AutoConfiguration}. A rename, a move or a deleted line fails here rather than in
* a deployment that starts and quietly does less than it says.
*/
class WebAutoConfigurationRegistrationTest {
private static final String IMPORTS_RESOURCE =
"META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports";
/** The auto-configurations this leaf publishes. */
private static final List<String> PUBLISHED_ROOTS =
List.of(
"dev.caskeleton.adapter.inbound.web.mvc.autoconfigure.WebMvcPlatformAutoConfiguration",
"dev.caskeleton.adapter.inbound.web.webflux.autoconfigure.WebFluxPlatformAutoConfiguration");
@Test
@DisplayName("the shipped registration file names every root this leaf publishes")
void theShippedRegistrationFileNamesEveryRoot() {
assertThat(registeredNames())
.as("the registration lines this leaf's own jar ships")
.containsAll(PUBLISHED_ROOTS);
}
@Test
@DisplayName("every registered name resolves to a real Boot auto-configuration")
void everyRegisteredNameResolvesToAnAutoConfiguration() {
for (String name : registeredNames()) {
Class<?> registered;
try {
registered =
Class.forName(name, false, WebAutoConfigurationRegistrationTest.class.getClassLoader());
} catch (ClassNotFoundException missing) {
throw new AssertionError(
IMPORTS_RESOURCE + " registers " + name + ", which does not exist", missing);
}
assertThat(AnnotatedElementUtils.hasAnnotation(registered, AutoConfiguration.class))
.as("%s is registered but is not annotated @AutoConfiguration", name)
.isTrue();
}
}
/**
* The registration lines this leaf's own resource declares.
*
* <p>Read from this leaf's source tree rather than from the classpath. {@code
* ClassLoader#getResources} returns every registration file on the test runtime classpath —
* Spring Boot's, springdoc's, and every dependency leaf's — so asserting over that set tests
* other people's modules and fails on their conditional classes. The file below is the one this
* leaf packages, which is the thing this contract is about.
*/
private static List<String> registeredNames() {
Path resource = leafRoot().resolve("src/main/resources/" + IMPORTS_RESOURCE);
assertThat(Files.isRegularFile(resource)).as("%s", resource).isTrue();
List<String> names;
try {
names =
Files.readAllLines(resource, StandardCharsets.UTF_8).stream()
.map(String::strip)
.filter(line -> !line.isEmpty() && !line.startsWith("#"))
.toList();
} catch (IOException failure) {
throw new UncheckedIOException("cannot read " + resource, failure);
}
assertThat(names).as("%s registers nothing", resource).isNotEmpty();
return names;
}
/** The nearest directory above the test's working directory that ships a registration file. */
private static Path leafRoot() {
for (Path path = Path.of("").toAbsolutePath(); path != null; path = path.getParent()) {
if (Files.isRegularFile(path.resolve("src/main/resources/" + IMPORTS_RESOURCE))) {
return path;
}
}
throw new IllegalStateException(
"no leaf shipping " + IMPORTS_RESOURCE + " found above " + Path.of("").toAbsolutePath());
}
}
@@ -0,0 +1,32 @@
package dev.caskeleton.adapter.inbound.web.testkit;
/**
* Socket budgets for the fixtures that drive a real server over a real socket.
*
* <p>One place, because the number is not a per-fixture judgement. None of these suites asserts
* latency — they assert the status, headers, problem code and body that came back — so the only
* requirement on a timeout is that it exceed the worst scheduling delay a healthy server can suffer
* on a loaded machine. Below that threshold the timeout stops being a safety net and becomes a
* second, invisible assertion about how busy the build host is.
*
* <p>That is not hypothetical here. With {@code org.gradle.parallel=true} these lanes run while
* SpotBugs analyses a dozen leaves, and at five-second connects and ten-second reads {@code
* ReactiveContractRecordingIT} and {@code ReactiveWebThrottleIT} failed a full {@code ci} run with
* {@code SocketTimeoutException} and passed when run alone. A lane that starts real servers and
* fails under load is the kind of gate people learn to re-run, and a gate people re-run is not a
* gate.
*
* <p>A suite whose subject *is* a timeout — the fault lanes' client read budget, the performance
* lanes' load measurements — does not use these. There the number is the contract, and it belongs
* next to the contract.
*/
public final class HttpFixtureTimeouts {
/** How long to wait for the connection itself. */
public static final int CONNECT_MILLIS = 15_000;
/** How long to wait for a response whose latency nothing asserts. */
public static final int READ_MILLIS = 30_000;
private HttpFixtureTimeouts() {}
}
@@ -1,5 +1,6 @@
package dev.caskeleton.adapter.inbound.web.testkit.budget;
import dev.caskeleton.adapter.inbound.web.testkit.HttpFixtureTimeouts;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
@@ -124,8 +125,8 @@ public final class HttpBudgetFixture {
HttpURLConnection connection =
(HttpURLConnection) URI.create(baseUrl + path).toURL().openConnection();
connection.setRequestMethod(method);
connection.setConnectTimeout(5_000);
connection.setReadTimeout(10_000);
connection.setConnectTimeout(HttpFixtureTimeouts.CONNECT_MILLIS);
connection.setReadTimeout(HttpFixtureTimeouts.READ_MILLIS);
return connection;
}
@@ -1,5 +1,6 @@
package dev.caskeleton.adapter.inbound.web.testkit.contract;
import dev.caskeleton.adapter.inbound.web.testkit.HttpFixtureTimeouts;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
@@ -86,8 +87,8 @@ public final class WebContractFixture {
HttpURLConnection connection =
(HttpURLConnection) URI.create(baseUrl + probe.path()).toURL().openConnection();
connection.setRequestMethod(probe.method());
connection.setConnectTimeout(5_000);
connection.setReadTimeout(15_000);
connection.setConnectTimeout(HttpFixtureTimeouts.CONNECT_MILLIS);
connection.setReadTimeout(HttpFixtureTimeouts.READ_MILLIS);
probe.headers().forEach(connection::setRequestProperty);
if (probe.body() != null) {
connection.setDoOutput(true);
@@ -1,5 +1,6 @@
package dev.caskeleton.adapter.inbound.web.testkit.fault;
import dev.caskeleton.adapter.inbound.web.testkit.HttpFixtureTimeouts;
import java.io.IOException;
import java.io.InputStream;
import java.net.HttpURLConnection;
@@ -51,7 +52,7 @@ public final class HttpResponseLossFixture implements ResponseLossFixture {
HttpURLConnection connection =
(HttpURLConnection) URI.create(baseUrl + path).toURL().openConnection();
connection.setRequestMethod(method);
connection.setConnectTimeout(5_000);
connection.setConnectTimeout(HttpFixtureTimeouts.CONNECT_MILLIS);
connection.setReadTimeout((int) FaultFixtureProtocol.CLIENT_READ_TIMEOUT.toMillis());
return connection;
}
@@ -86,7 +87,7 @@ public final class HttpResponseLossFixture implements ResponseLossFixture {
public int sideEffectCount() {
try {
HttpURLConnection connection = open(FaultFixtureProtocol.SIDE_EFFECTS_PATH, "GET");
connection.setReadTimeout(5_000);
connection.setReadTimeout(HttpFixtureTimeouts.READ_MILLIS);
try (InputStream body = connection.getInputStream()) {
return Integer.parseInt(new String(body.readAllBytes(), StandardCharsets.UTF_8).trim());
} finally {
@@ -100,7 +101,7 @@ public final class HttpResponseLossFixture implements ResponseLossFixture {
private Replay post(WebFaultPoint armed) throws IOException {
HttpURLConnection connection = open(FaultFixtureProtocol.CREATE_PATH, "POST");
if (armed == null) {
connection.setReadTimeout(10_000);
connection.setReadTimeout(HttpFixtureTimeouts.READ_MILLIS);
}
connection.setDoOutput(true);
connection.setRequestProperty("Content-Type", "application/json");
@@ -1,5 +1,6 @@
package dev.caskeleton.adapter.inbound.web.testkit.operation;
import dev.caskeleton.adapter.inbound.web.testkit.HttpFixtureTimeouts;
import java.io.IOException;
import java.io.InputStream;
import java.net.HttpURLConnection;
@@ -85,8 +86,8 @@ public final class HttpOperationFixture {
HttpURLConnection connection =
(HttpURLConnection) URI.create(baseUrl + path).toURL().openConnection();
connection.setRequestMethod(method);
connection.setConnectTimeout(5_000);
connection.setReadTimeout(10_000);
connection.setConnectTimeout(HttpFixtureTimeouts.CONNECT_MILLIS);
connection.setReadTimeout(HttpFixtureTimeouts.READ_MILLIS);
if ("POST".equals(method)) {
connection.setDoOutput(true);
connection.getOutputStream().close();
@@ -1,5 +1,6 @@
package dev.caskeleton.adapter.inbound.web.testkit.order;
import dev.caskeleton.adapter.inbound.web.testkit.HttpFixtureTimeouts;
import java.io.IOException;
import java.io.InputStream;
import java.net.HttpURLConnection;
@@ -57,8 +58,8 @@ public final class HttpPipelineFixture {
HttpURLConnection connection =
(HttpURLConnection) URI.create(baseUrl + path).toURL().openConnection();
connection.setRequestMethod(method);
connection.setConnectTimeout(5_000);
connection.setReadTimeout(10_000);
connection.setConnectTimeout(HttpFixtureTimeouts.CONNECT_MILLIS);
connection.setReadTimeout(HttpFixtureTimeouts.READ_MILLIS);
if (body != null) {
connection.setDoOutput(true);
connection.setRequestProperty("Content-Type", "application/json");
@@ -1,5 +1,6 @@
package dev.caskeleton.adapter.inbound.web.testkit.throttle;
import dev.caskeleton.adapter.inbound.web.testkit.HttpFixtureTimeouts;
import java.io.IOException;
import java.io.InputStream;
import java.net.HttpURLConnection;
@@ -41,6 +42,24 @@ public final class HttpThrottleFixture implements AutoCloseable {
}
}
/**
* How long {@link #awaitSlotTaken} waits for the holder to occupy the single write slot.
*
* <p>A liveness guard, not an assertion: if the slot is never taken the scenario cannot run, and
* failing is better than hanging. Ten seconds was short enough that a loaded machine could trip
* it before the holder was scheduled.
*/
private static final long SLOT_TAKEN_DEADLINE_SECONDS = 40;
/**
* How long the holding request is allowed to hold the slot.
*
* <p>Must stay comfortably above {@link #SLOT_TAKEN_DEADLINE_SECONDS}: if the holder gave up
* first, the slot would be free again while the scenario was still waiting to observe it taken,
* and the failure would name capacity rather than the fixture.
*/
private static final int HOLDER_TIMEOUT_MILLIS = 120_000;
private final String baseUrl;
private final ExecutorService holders = Executors.newCachedThreadPool();
@@ -55,17 +74,20 @@ public final class HttpThrottleFixture implements AutoCloseable {
/** Refills the quota and releases any held slot. */
public void reset() {
send("POST", ThrottleFixtureProtocol.RESET_PATH, 5_000);
send("POST", ThrottleFixtureProtocol.RESET_PATH, HttpFixtureTimeouts.READ_MILLIS);
}
/** Refills the quota, then makes the limiter's store unreachable. */
public void breakLimiterStore() {
send("POST", ThrottleFixtureProtocol.RESET_PATH + "?breakStore=true", 5_000);
send(
"POST",
ThrottleFixtureProtocol.RESET_PATH + "?breakStore=true",
HttpFixtureTimeouts.READ_MILLIS);
}
/** One call against the quota route. */
public Response callQuotaRoute() {
return send("GET", ThrottleFixtureProtocol.QUOTA_PATH, 5_000);
return send("GET", ThrottleFixtureProtocol.QUOTA_PATH, HttpFixtureTimeouts.READ_MILLIS);
}
/** Spends the whole quota, then calls once more. */
@@ -78,7 +100,7 @@ public final class HttpThrottleFixture implements AutoCloseable {
/** One call against the write route. */
public Response callWriteRoute() {
return send("POST", ThrottleFixtureProtocol.WRITE_PATH, 10_000);
return send("POST", ThrottleFixtureProtocol.WRITE_PATH, HttpFixtureTimeouts.READ_MILLIS);
}
/**
@@ -88,21 +110,29 @@ public final class HttpThrottleFixture implements AutoCloseable {
* refusal is caused by the slot being taken rather than by whichever request happened to win.
*/
public Response saturateAndCallWrite() {
send("POST", ThrottleFixtureProtocol.RESET_PATH + "?arm=true", 5_000);
send("POST", ThrottleFixtureProtocol.RESET_PATH + "?arm=true", HttpFixtureTimeouts.READ_MILLIS);
CompletableFuture<Response> holder =
CompletableFuture.supplyAsync(
() -> send("POST", ThrottleFixtureProtocol.WRITE_PATH + "?hold=true", 40_000), holders);
() ->
send(
"POST",
ThrottleFixtureProtocol.WRITE_PATH + "?hold=true",
HOLDER_TIMEOUT_MILLIS),
holders);
try {
awaitSlotTaken(holder);
// Refill the quota without letting go of the slot. Confirming the slot was taken cost
// several quota-charged probes, and the filter charges quota before it asks for capacity —
// so without this the next call is refused 429 and the 503 case never runs.
send("POST", ThrottleFixtureProtocol.RESET_PATH + "?releaseHold=false", 5_000);
send(
"POST",
ThrottleFixtureProtocol.RESET_PATH + "?releaseHold=false",
HttpFixtureTimeouts.READ_MILLIS);
return callWriteRoute();
} finally {
reset();
try {
holder.get(30, TimeUnit.SECONDS);
holder.get(SLOT_TAKEN_DEADLINE_SECONDS + 30, TimeUnit.SECONDS);
} catch (InterruptedException interrupted) {
Thread.currentThread().interrupt();
} catch (ExecutionException | TimeoutException ignored) {
@@ -114,7 +144,7 @@ public final class HttpThrottleFixture implements AutoCloseable {
private void awaitSlotTaken(CompletableFuture<Response> holder) {
// Polled rather than slept: a fixed sleep is either too short on a loaded machine or wasted
// time on an idle one, and the first is a flaky failure nobody can reproduce.
long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(10);
long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(SLOT_TAKEN_DEADLINE_SECONDS);
while (System.nanoTime() < deadline) {
if (holder.isDone()) {
throw new IllegalStateException("the holding request returned before the slot was taken");
@@ -124,8 +154,12 @@ public final class HttpThrottleFixture implements AutoCloseable {
// holder takes a while to occupy the slot, the quota runs out first and every remaining
// probe answers 429. The loop then never sees its 503 and fails on the deadline, which
// reads as a capacity bug and is a fixture bug.
send("POST", ThrottleFixtureProtocol.RESET_PATH + "?releaseHold=false", 5_000);
Response probe = send("POST", ThrottleFixtureProtocol.WRITE_PATH, 5_000);
send(
"POST",
ThrottleFixtureProtocol.RESET_PATH + "?releaseHold=false",
HttpFixtureTimeouts.READ_MILLIS);
Response probe =
send("POST", ThrottleFixtureProtocol.WRITE_PATH, HttpFixtureTimeouts.READ_MILLIS);
if (probe.status() == 503) {
return;
}
@@ -148,7 +182,7 @@ public final class HttpThrottleFixture implements AutoCloseable {
HttpURLConnection connection =
(HttpURLConnection) URI.create(baseUrl + path).toURL().openConnection();
connection.setRequestMethod(method);
connection.setConnectTimeout(5_000);
connection.setConnectTimeout(HttpFixtureTimeouts.CONNECT_MILLIS);
connection.setReadTimeout(readTimeoutMillis);
if ("POST".equals(method)) {
connection.setDoOutput(true);