refactor: 리펙토링 진행중 의존성 gradle은 얇게 유지, 각 모듈에서 처리하고 있는 부분에 대해서 리펙토링
This commit is contained in:
@@ -5,7 +5,7 @@
|
||||
- Module ID: `application-core`
|
||||
- Gradle path: `:application-core`
|
||||
- Focused test (derived from Gradle path): `./gradlew :application-core:test --console=plain`
|
||||
- Runtime baseline: Java 21; repository framework baseline: Spring Boot 4.0.0.
|
||||
- Runtime baseline: Java 21; repository framework baseline: the Spring Boot 4.x version pinned by the shared version catalog.
|
||||
- Registry SSOT: `src/config/architecture/modules.json`.
|
||||
|
||||
Package root: `dev.caskeleton.application`.
|
||||
@@ -61,6 +61,7 @@ Package root: `dev.caskeleton.application`.
|
||||
| `command.Command` | Marker for write intents. Plain immutable types built from domain values. |
|
||||
| `query.Query` | Marker for read intents. Plain immutable types built from domain values. |
|
||||
| `transaction.TransactionPort` | Outbound port for join-capable write/read, physical root-only write, and independent write boundaries. Implemented by `adapter-persistence`. |
|
||||
| `outbound.SecretSourcePort` | Framework-free outbound secret-resolution seam. Deployment selects a backend in app-bootstrap; concrete environment/cloud/vault readers belong to outbound adapter leaves. |
|
||||
| `transaction.NestedRootTransactionRejectedException` | Fail-fast signal raised before action/provider side effects when `inRootWrite` detects an actual ambient transaction. |
|
||||
| `transaction.TransactionMode` | `WRITE` / `READ_ONLY` / `REQUIRES_NEW`. `NESTED` and `NEVER` are intentionally absent. |
|
||||
| `transaction.Isolation` | `READ_COMMITTED` (pinned default) / `REPEATABLE_READ` / `SERIALIZABLE`. `READ_UNCOMMITTED` is forbidden (not declared); the vendor default is never used (engine defaults differ — PostgreSQL READ COMMITTED vs MySQL InnoDB REPEATABLE READ). Routing the stricter levels through `TransactionPort` is a `planned` joint change with `feature-application-port-usecase-contract`; the shipped call path pins `READ_COMMITTED`. |
|
||||
@@ -83,29 +84,6 @@ the two namespaces are zero, enforced by
|
||||
|
||||
## Notification R1 application boundary
|
||||
|
||||
- `dev.caskeleton.application.notification` owns only framework-free semantic values, code-owned
|
||||
kind policy, narrow outbound ports, dispatch/receipt/admission/reconciliation orchestration and
|
||||
writer-cutover command contracts.
|
||||
- Feature/application code creates a typed `NotificationIntentDraft`; `NotificationPlanPort`
|
||||
returns the application-owned immutable `NotificationFrozenPlan`, which is the only planning
|
||||
handoff consumed by append or inline attempt ports. Provider SDK, transport DTO, persistence
|
||||
entity, compiled adapter binding and raw recipient/template payload types are forbidden here.
|
||||
- Provider calls run outside database transactions. Dispatch and reconciliation use bounded
|
||||
claim/authorize/finalize transactions with opaque claim/version/execution tokens; an
|
||||
`INDETERMINATE` submission is terminal and must not be blindly retried.
|
||||
- Receipt reduction is order-independent and keeps delivery acceptance monotonic. Only hard bounce
|
||||
and complaint facts may request technical suppression; consent/unsubscribe policy is outside this
|
||||
capability.
|
||||
- Writer-cutover operations that must prove a physical commit use `inRootWrite`. Route/profile
|
||||
registries are application-owned exact inputs; signed inventory/quiescence verification is
|
||||
delegated to narrow verifier ports and the persistence operation must enforce locked durable
|
||||
state/journal invariants.
|
||||
- This is the R1 application contract proven with fakes. It does not claim PostgreSQL schema/locking,
|
||||
provider protocol, cryptographic verifier, or runtime wiring qualification; those belong to the
|
||||
notification/persistence/bootstrap adapters.
|
||||
|
||||
## Notification R1 application boundary
|
||||
|
||||
- `dev.caskeleton.application.notification` owns only framework-free semantic values, code-owned
|
||||
kind policy, narrow outbound ports, dispatch/receipt/admission/reconciliation orchestration and
|
||||
writer-cutover command contracts.
|
||||
@@ -256,7 +234,7 @@ The read side has two equally-valid shapes; pick per read, do not force one:
|
||||
```bash
|
||||
cd src
|
||||
./gradlew :application-core:test
|
||||
./gradlew :app-bootstrap:test --tests '*CleanArchitectureTest'
|
||||
./gradlew :app-bootstrap:architectureTest
|
||||
```
|
||||
|
||||
The messaging types above establish semantic contract R1 only. They do not claim JSON Schema
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
plugins {
|
||||
id 'ca.java-library'
|
||||
id 'java-test-fixtures'
|
||||
}
|
||||
|
||||
// Framework-free application use-case contract. Runtime dependencies are project-only;
|
||||
@@ -8,8 +9,6 @@ plugins {
|
||||
dependencies {
|
||||
implementation project(':shared-contract')
|
||||
|
||||
// Property-based verification for bounded object-storage identity and value contracts.
|
||||
testImplementation libs.jqwik
|
||||
}
|
||||
|
||||
def messagingApplicationContractQualification = extensions.getByName('strictQualification').register(
|
||||
|
||||
@@ -2,45 +2,45 @@
|
||||
# Manual edits can break the build and are not advised.
|
||||
# This file is expected to be part of source control.
|
||||
com.github.ben-manes.caffeine:caffeine:3.2.3=redisPolicyContractTestAnnotationProcessor
|
||||
com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor
|
||||
com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor
|
||||
com.github.ben-manes.caffeine:caffeine:3.2.4=annotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
com.github.kevinstern:software-and-algorithms:1.0=annotationProcessor,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
com.github.spotbugs:spotbugs-annotations:4.10.2=spotbugs
|
||||
com.github.spotbugs:spotbugs:4.10.2=spotbugs
|
||||
com.github.stephenc.jcip:jcip-annotations:1.0-1=spotbugs
|
||||
com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor
|
||||
com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor
|
||||
com.google.auto:auto-common:1.2.2=annotationProcessor,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor
|
||||
com.google.auto.service:auto-service-annotations:1.0.1=annotationProcessor,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
com.google.auto.value:auto-value-annotations:1.9=annotationProcessor,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
com.google.auto:auto-common:1.2.2=annotationProcessor,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
com.google.code.findbugs:jsr305:3.0.2=checkstyle,spotbugs
|
||||
com.google.code.gson:gson:2.13.2=spotbugs
|
||||
com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor
|
||||
com.google.errorprone:error_prone_annotation:2.49.0=annotationProcessor,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
com.google.errorprone:error_prone_annotations:2.41.0=spotbugs
|
||||
com.google.errorprone:error_prone_annotations:2.47.0=checkstyle
|
||||
com.google.errorprone:error_prone_annotations:2.49.0=annotationProcessor,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor
|
||||
com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor
|
||||
com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor
|
||||
com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor
|
||||
com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor
|
||||
com.google.guava:guava:33.5.0-jre=annotationProcessor,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor
|
||||
com.google.errorprone:error_prone_annotations:2.49.0=annotationProcessor,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
com.google.errorprone:error_prone_check_api:2.49.0=annotationProcessor,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
com.google.errorprone:error_prone_core:2.49.0=annotationProcessor,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
com.google.googlejavaformat:google-java-format:1.35.0=annotationProcessor,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
com.google.guava:failureaccess:1.0.3=annotationProcessor,checkstyle,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
com.google.guava:guava:33.5.0-jre=annotationProcessor,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
com.google.guava:guava:33.6.0-jre=checkstyle
|
||||
com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor
|
||||
com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor
|
||||
com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor
|
||||
com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins
|
||||
com.puppycrawl.tools:checkstyle:13.5.0=checkstyle
|
||||
commons-beanutils:commons-beanutils:1.11.0=checkstyle
|
||||
commons-collections:commons-collections:3.2.2=checkstyle
|
||||
commons-io:commons-io:2.21.0=spotbugs
|
||||
info.picocli:picocli:4.7.7=checkstyle
|
||||
io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor
|
||||
io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor
|
||||
javax.inject:javax.inject:1=annotationProcessor,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor
|
||||
io.github.eisop:dataflow-errorprone:3.41.0-eisop1=annotationProcessor,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
io.github.java-diff-utils:java-diff-utils:4.12=annotationProcessor,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
javax.inject:javax.inject:1=annotationProcessor,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
jaxen:jaxen:2.0.6=spotbugs
|
||||
net.bytebuddy:byte-buddy:1.17.8=redisPolicyContractTestCompileClasspath,redisPolicyContractTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
|
||||
net.jqwik:jqwik-api:1.9.1=redisPolicyContractTestCompileClasspath,redisPolicyContractTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
|
||||
net.jqwik:jqwik-engine:1.9.1=redisPolicyContractTestRuntimeClasspath,testRuntimeClasspath
|
||||
net.jqwik:jqwik-time:1.9.1=redisPolicyContractTestCompileClasspath,redisPolicyContractTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
|
||||
net.jqwik:jqwik-web:1.9.1=redisPolicyContractTestCompileClasspath,redisPolicyContractTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
|
||||
net.jqwik:jqwik:1.9.1=redisPolicyContractTestCompileClasspath,redisPolicyContractTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
|
||||
net.jqwik:jqwik-api:1.9.1=redisPolicyContractTestCompileClasspath,redisPolicyContractTestRuntimeClasspath
|
||||
net.jqwik:jqwik-engine:1.9.1=redisPolicyContractTestRuntimeClasspath
|
||||
net.jqwik:jqwik-time:1.9.1=redisPolicyContractTestCompileClasspath,redisPolicyContractTestRuntimeClasspath
|
||||
net.jqwik:jqwik-web:1.9.1=redisPolicyContractTestCompileClasspath,redisPolicyContractTestRuntimeClasspath
|
||||
net.jqwik:jqwik:1.9.1=redisPolicyContractTestCompileClasspath,redisPolicyContractTestRuntimeClasspath
|
||||
net.sf.saxon:Saxon-HE:12.9=checkstyle,spotbugs
|
||||
org.antlr:antlr4-runtime:4.13.2=checkstyle
|
||||
org.apache.bcel:bcel:6.12.0=spotbugs
|
||||
@@ -56,7 +56,7 @@ org.apache.maven.doxia:doxia-logging-api:1.12.0=checkstyle
|
||||
org.apache.maven.doxia:doxia-module-xdoc:1.12.0=checkstyle
|
||||
org.apache.maven.doxia:doxia-sink-api:1.12.0=checkstyle
|
||||
org.apache.xbean:xbean-reflect:3.7=checkstyle
|
||||
org.apiguardian:apiguardian-api:1.1.2=redisPolicyContractTestCompileClasspath,redisPolicyContractTestRuntimeClasspath,testCompileClasspath,testRuntimeClasspath
|
||||
org.apiguardian:apiguardian-api:1.1.2=redisPolicyContractTestCompileClasspath,redisPolicyContractTestRuntimeClasspath,testCompileClasspath
|
||||
org.assertj:assertj-core:3.27.6=redisPolicyContractTestCompileClasspath,redisPolicyContractTestRuntimeClasspath
|
||||
org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath
|
||||
org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle
|
||||
@@ -66,7 +66,7 @@ org.codehaus.plexus:plexus-utils:3.3.0=checkstyle
|
||||
org.dom4j:dom4j:2.2.0=spotbugs
|
||||
org.javassist:javassist:3.28.0-GA=checkstyle
|
||||
org.jspecify:jspecify:1.0.0=redisPolicyContractTestAnnotationProcessor,redisPolicyContractTestCompileClasspath
|
||||
org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath
|
||||
org.jspecify:jspecify:1.0.1=annotationProcessor,checkstyle,testAnnotationProcessor,testCompileClasspath,testFixturesAnnotationProcessor
|
||||
org.junit.jupiter:junit-jupiter-api:6.0.1=redisPolicyContractTestCompileClasspath,redisPolicyContractTestRuntimeClasspath
|
||||
org.junit.jupiter:junit-jupiter-api:6.0.3=testCompileClasspath,testRuntimeClasspath
|
||||
org.junit.jupiter:junit-jupiter-engine:6.0.1=redisPolicyContractTestRuntimeClasspath
|
||||
@@ -91,10 +91,10 @@ org.ow2.asm:asm-commons:9.10.1=spotbugs
|
||||
org.ow2.asm:asm-tree:9.10.1=spotbugs
|
||||
org.ow2.asm:asm-util:9.10.1=spotbugs
|
||||
org.ow2.asm:asm:9.10.1=spotbugs
|
||||
org.pcollections:pcollections:4.0.1=annotationProcessor,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor
|
||||
org.pcollections:pcollections:4.0.1=annotationProcessor,redisPolicyContractTestAnnotationProcessor,testAnnotationProcessor,testFixturesAnnotationProcessor
|
||||
org.reflections:reflections:0.10.2=checkstyle
|
||||
org.slf4j:slf4j-api:2.0.18=spotbugs,spotbugsSlf4j
|
||||
org.slf4j:slf4j-simple:2.0.17=spotbugsSlf4j
|
||||
org.slf4j:slf4j-simple:2.0.18=checkstyle
|
||||
org.xmlresolver:xmlresolver:5.3.3=checkstyle,spotbugs
|
||||
empty=compileClasspath,runtimeClasspath
|
||||
empty=compileClasspath,runtimeClasspath,testFixturesCompileClasspath,testFixturesRuntimeClasspath
|
||||
|
||||
Vendored
+5
-5
@@ -12,7 +12,11 @@ import java.util.Objects;
|
||||
* <p>When optional refresh coordination is enabled, the soft-lease owner refreshes synchronously.
|
||||
* This executor does not schedule an asynchronous stale-while-revalidate task. A valid stale
|
||||
* contender or a valid stale request facing coordination failure returns immediately instead.
|
||||
*
|
||||
* @deprecated the shipped runtime does not compose this executor. The algorithm remains available
|
||||
* as a verified reference, but callers must not assume template-level production support.
|
||||
*/
|
||||
@Deprecated
|
||||
public final class CacheAsideExecutor<K, V> {
|
||||
|
||||
private final CacheAsidePolicy policy;
|
||||
@@ -155,10 +159,6 @@ public final class CacheAsideExecutor<K, V> {
|
||||
CacheRefreshClaimAttempt attempt =
|
||||
Objects.requireNonNull(
|
||||
refreshCoordinator.newAttempt(), "cache refresh claim attempt must be non-null");
|
||||
if (!attempt.usable()) {
|
||||
throw new IllegalStateException(
|
||||
"enabled cache refresh coordinator returned an unusable attempt");
|
||||
}
|
||||
CacheRefreshClaimOutcome claim = claimWithOneUncertainRetry(key, attempt);
|
||||
if (claim instanceof CacheRefreshClaimOutcome.Contended) {
|
||||
SourceAttempt<V> deferred = staleDeferral(stale, claim);
|
||||
@@ -260,7 +260,7 @@ public final class CacheAsideExecutor<K, V> {
|
||||
}
|
||||
|
||||
private boolean shouldCoordinate(StaleCandidate<V> stale, boolean hardMiss) {
|
||||
if (refreshCoordinator == null || !refreshCoordinator.enabled()) {
|
||||
if (refreshCoordinator == null) {
|
||||
return false;
|
||||
}
|
||||
return stale != null
|
||||
|
||||
-4
@@ -12,10 +12,6 @@ import java.time.Duration;
|
||||
*/
|
||||
public interface CacheRefreshCoordinationPort<K> {
|
||||
|
||||
default boolean enabled() {
|
||||
return true;
|
||||
}
|
||||
|
||||
CacheRefreshClaimAttempt newAttempt();
|
||||
|
||||
CacheRefreshClaimOutcome claim(K key, CacheRefreshClaimAttempt attempt, Duration leaseTimeToLive);
|
||||
|
||||
-5
@@ -16,11 +16,6 @@ public final class DisabledCacheRefreshCoordinationPort<K>
|
||||
return (DisabledCacheRefreshCoordinationPort<K>) INSTANCE;
|
||||
}
|
||||
|
||||
@Override
|
||||
public boolean enabled() {
|
||||
return false;
|
||||
}
|
||||
|
||||
@Override
|
||||
public CacheRefreshClaimAttempt newAttempt() {
|
||||
return CacheRefreshClaimAttempt.unavailable();
|
||||
|
||||
+17
-8
@@ -1,23 +1,32 @@
|
||||
package dev.caskeleton.application.fileexport;
|
||||
|
||||
import dev.caskeleton.application.filepublication.PublishedFileReference;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* Immutable receipt for a file written through {@link FileExportPort}. Framework-neutral value
|
||||
* object (no Spring / IO types) so the application layer stays decoupled from the export backend.
|
||||
* Legacy receipt for a file written through {@link FileExportPort}.
|
||||
*
|
||||
* @param fileName the name the file was written under (never null/blank)
|
||||
* @param path the absolute path the file was written to (never null/blank)
|
||||
* <p>The original contract exposed the server's absolute filesystem path. That made the application
|
||||
* boundary depend on deployment topology and produced a value that is meaningless for SFTP, NFS
|
||||
* aliases or clustered storage. The compatibility receipt now carries only an opaque publication
|
||||
* reference.
|
||||
*
|
||||
* @param fileName the logical name the file was written under (never null/blank)
|
||||
* @param reference an opaque reference that never exposes a filesystem path or provider location
|
||||
* @param byteSize the written file size in bytes (never negative)
|
||||
* @param rowCount the number of data rows written, excluding the header (never negative)
|
||||
* @deprecated use the streaming {@link
|
||||
* dev.caskeleton.application.filepublication.FilePublicationPort} contract instead
|
||||
*/
|
||||
public record ExportedFile(String fileName, String path, long byteSize, long rowCount) {
|
||||
@Deprecated(forRemoval = true)
|
||||
public record ExportedFile(
|
||||
String fileName, PublishedFileReference reference, long byteSize, long rowCount) {
|
||||
|
||||
public ExportedFile {
|
||||
if (fileName == null || fileName.isBlank()) {
|
||||
throw new IllegalArgumentException("ExportedFile.fileName must be non-null and non-blank");
|
||||
}
|
||||
if (path == null || path.isBlank()) {
|
||||
throw new IllegalArgumentException("ExportedFile.path must be non-null and non-blank");
|
||||
}
|
||||
Objects.requireNonNull(reference, "reference");
|
||||
if (byteSize < 0) {
|
||||
throw new IllegalArgumentException(
|
||||
"ExportedFile.byteSize must be non-negative, was " + byteSize);
|
||||
|
||||
+17
-21
@@ -3,35 +3,31 @@ package dev.caskeleton.application.fileexport;
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* Outbound port for exporting tabular data as a delimited file — the "file server" boundary (a
|
||||
* stand-in for an NFS mount, shared file server, or SFTP drop). The application layer hands over
|
||||
* plain strings, so use cases stay decoupled from the export format and the destination filesystem.
|
||||
* The adapter is selected by configuration ({@code app.file-export}); see the {@code
|
||||
* adapter:outbound:fileserver} README for the on-disk layout and the CSV-escaping contract.
|
||||
* Legacy outbound port for exporting already-materialized tabular data as CSV.
|
||||
*
|
||||
* <p>The contract is deliberately domain-neutral: no framework or domain type crosses it. A caller
|
||||
* supplies a bare {@code fileName}, an optional {@code header} row, and the data {@code rows} as
|
||||
* lists of already-stringified field values; the adapter owns file placement, RFC-4180 escaping,
|
||||
* and byte encoding, and returns an {@link ExportedFile} receipt.
|
||||
* <p>This contract requires the caller to materialize every row in memory before the adapter is
|
||||
* invoked. The replacement {@link dev.caskeleton.application.filepublication.FilePublicationPort}
|
||||
* streams rows through a {@link dev.caskeleton.application.filepublication.TabularRowProducer} and
|
||||
* returns an opaque publication reference.
|
||||
*
|
||||
* @deprecated use {@link dev.caskeleton.application.filepublication.FilePublicationPort}; this
|
||||
* compatibility port retains whole-result materialization and will be removed
|
||||
*/
|
||||
@Deprecated(forRemoval = true)
|
||||
@SuppressWarnings("removal")
|
||||
public interface FileExportPort {
|
||||
|
||||
/**
|
||||
* Writes {@code header} + {@code rows} as a CSV file named {@code fileName} under the adapter's
|
||||
* configured base directory, overwriting any existing file at that name.
|
||||
* configured base directory.
|
||||
*
|
||||
* <p>Every field is escaped per RFC-4180: a field containing a comma, double-quote, carriage
|
||||
* return, or line feed is wrapped in double-quotes with embedded quotes doubled. A {@code null}
|
||||
* field is written as an empty field. The file is UTF-8 encoded.
|
||||
* <p>Every field is escaped per RFC-4180. A {@code null} field is written as an empty field. The
|
||||
* file is UTF-8 encoded.
|
||||
*
|
||||
* @param fileName the target file name (not a path); must be non-null and non-blank and must not
|
||||
* escape the base directory (no path separators that resolve outside it)
|
||||
* @param header the column names written as the first line; must be non-null (may be empty, in
|
||||
* which case no header line is written)
|
||||
* @param rows the data rows, each a list of field values in column order; must be non-null (may
|
||||
* be empty); individual field values may be {@code null}
|
||||
* @return an {@link ExportedFile} receipt (file name, absolute path, byte size, row count)
|
||||
* @throws IllegalArgumentException if {@code fileName} is blank or escapes the base directory
|
||||
* @param fileName the target logical file name; must be non-null and non-blank
|
||||
* @param header the column names written as the first line; must be non-null
|
||||
* @param rows the already-materialized data rows; must be non-null
|
||||
* @return a legacy receipt containing an opaque reference, byte size and row count
|
||||
*/
|
||||
ExportedFile exportCsv(String fileName, List<String> header, List<List<String>> rows);
|
||||
}
|
||||
|
||||
-12
@@ -1,12 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.admin;
|
||||
|
||||
/**
|
||||
* Durable sink for administrative actions.
|
||||
*
|
||||
* <p>Every mutating admin operation writes here, including the ones that failed: a rejected
|
||||
* force-delete attempt is exactly the event a reviewer most wants to see.
|
||||
*/
|
||||
public interface AdminAuditPort {
|
||||
|
||||
void record(AdminAuditRecord record);
|
||||
}
|
||||
-30
@@ -1,30 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.admin;
|
||||
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* One administrative action, recorded for review.
|
||||
*
|
||||
* <p>{@code actorFingerprint} is a stable pseudonym rather than a principal id, and no path, mount,
|
||||
* filename, or raw scanner response ever appears. An audit trail that leaked those would become a
|
||||
* second copy of exactly the data the rest of the design refuses to disclose.
|
||||
*/
|
||||
public record AdminAuditRecord(
|
||||
String operation,
|
||||
String reasonCode,
|
||||
String actorFingerprint,
|
||||
String traceId,
|
||||
boolean succeeded,
|
||||
String subjectId,
|
||||
Instant occurredAt) {
|
||||
|
||||
public AdminAuditRecord {
|
||||
Objects.requireNonNull(operation, "operation");
|
||||
Objects.requireNonNull(reasonCode, "reasonCode");
|
||||
Objects.requireNonNull(actorFingerprint, "actorFingerprint");
|
||||
Objects.requireNonNull(traceId, "traceId");
|
||||
Objects.requireNonNull(subjectId, "subjectId");
|
||||
Objects.requireNonNull(occurredAt, "occurredAt");
|
||||
}
|
||||
}
|
||||
-17
@@ -1,17 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.admin;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.ContentKey;
|
||||
|
||||
/**
|
||||
* Answers whether any record still claims a physical object.
|
||||
*
|
||||
* <p>An orphan scan walks storage and must decide, per object, whether deleting it would destroy
|
||||
* live data. That decision belongs to the metadata side, and it is deliberately the only question
|
||||
* the scan is allowed to ask: a scan that could read records would be tempted to reconstruct them.
|
||||
*/
|
||||
@FunctionalInterface
|
||||
public interface ContentReferenceLedger {
|
||||
|
||||
/** True when a file record names {@code key}, in any state. */
|
||||
boolean isReferenced(ContentKey key);
|
||||
}
|
||||
-270
@@ -1,270 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.admin;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.FileId;
|
||||
import dev.caskeleton.application.fileserver.api.FileState;
|
||||
import dev.caskeleton.application.fileserver.api.error.FileNotFoundException;
|
||||
import dev.caskeleton.application.fileserver.api.error.FileNotReadyException;
|
||||
import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode;
|
||||
import dev.caskeleton.application.fileserver.api.error.FileserverFailureContext;
|
||||
import dev.caskeleton.application.fileserver.api.metadata.FileMetadataStore;
|
||||
import dev.caskeleton.application.fileserver.api.metadata.FileRecord;
|
||||
import dev.caskeleton.application.fileserver.api.metadata.FileRecordMutation;
|
||||
import dev.caskeleton.application.fileserver.api.metadata.UploadSession;
|
||||
import dev.caskeleton.application.fileserver.api.metadata.UploadSessionStore;
|
||||
import dev.caskeleton.application.fileserver.api.security.FileAccessPolicy;
|
||||
import dev.caskeleton.application.fileserver.api.security.FileOperation;
|
||||
import dev.caskeleton.application.fileserver.api.security.RequestContext;
|
||||
import dev.caskeleton.application.fileserver.cleanup.CleanupBatchResult;
|
||||
import dev.caskeleton.application.fileserver.cleanup.CleanupQueue;
|
||||
import dev.caskeleton.application.fileserver.cleanup.CleanupRequest;
|
||||
import dev.caskeleton.application.fileserver.cleanup.CleanupService;
|
||||
import dev.caskeleton.application.fileserver.cleanup.CleanupType;
|
||||
import dev.caskeleton.application.fileserver.observability.SafeFileFingerprint;
|
||||
import dev.caskeleton.application.fileserver.upload.FileView;
|
||||
import dev.caskeleton.application.transaction.TransactionPort;
|
||||
import java.time.Clock;
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* The management plane, with its own authority and its own audit trail.
|
||||
*
|
||||
* <p>Two rules shape everything here. A reconcile is a dry run unless the caller explicitly opted
|
||||
* out <em>and</em> echoed the fingerprints it was shown, so a stale scan can never turn into a mass
|
||||
* delete. And every mutating action is audited whether it succeeded or not, because a refused
|
||||
* force-delete is exactly the event a reviewer needs to see.
|
||||
*/
|
||||
public final class DefaultFileserverAdminService implements FileserverAdminService {
|
||||
|
||||
private static final int MAXIMUM_ADMIN_PAGE = 1000;
|
||||
|
||||
private final StorageHealthPort healthPort;
|
||||
private final OrphanScanPort orphanScanPort;
|
||||
private final FileMetadataStore metadataStore;
|
||||
private final UploadSessionStore sessionStore;
|
||||
private final CleanupQueue cleanupQueue;
|
||||
private final CleanupService cleanupService;
|
||||
private final FileAccessPolicy accessPolicy;
|
||||
private final AdminAuditPort auditPort;
|
||||
private final SafeFileFingerprint fingerprint;
|
||||
private final TransactionPort transactions;
|
||||
private final Clock clock;
|
||||
|
||||
public DefaultFileserverAdminService(
|
||||
StorageHealthPort healthPort,
|
||||
OrphanScanPort orphanScanPort,
|
||||
FileMetadataStore metadataStore,
|
||||
UploadSessionStore sessionStore,
|
||||
CleanupQueue cleanupQueue,
|
||||
CleanupService cleanupService,
|
||||
FileAccessPolicy accessPolicy,
|
||||
AdminAuditPort auditPort,
|
||||
SafeFileFingerprint fingerprint,
|
||||
TransactionPort transactions,
|
||||
Clock clock) {
|
||||
this.healthPort = healthPort;
|
||||
this.orphanScanPort = orphanScanPort;
|
||||
this.metadataStore = metadataStore;
|
||||
this.sessionStore = sessionStore;
|
||||
this.cleanupQueue = cleanupQueue;
|
||||
this.cleanupService = cleanupService;
|
||||
this.accessPolicy = accessPolicy;
|
||||
this.auditPort = auditPort;
|
||||
this.fingerprint = fingerprint;
|
||||
this.transactions = transactions;
|
||||
this.clock = clock;
|
||||
}
|
||||
|
||||
@Override
|
||||
public StorageHealthReport storageHealth(RequestContext context) {
|
||||
authorizeRead(context);
|
||||
return healthPort.health();
|
||||
}
|
||||
|
||||
@Override
|
||||
public RuntimeCapabilityReport capabilities(RequestContext context) {
|
||||
authorizeRead(context);
|
||||
return healthPort.capabilities();
|
||||
}
|
||||
|
||||
@Override
|
||||
public List<OrphanObject> orphans(int limit, RequestContext context) {
|
||||
authorizeRead(context);
|
||||
return orphanScanPort.scan(boundedLimit(limit));
|
||||
}
|
||||
|
||||
@Override
|
||||
public OrphanReconcileReport reconcileOrphans(
|
||||
OrphanReconcileCommand command, RequestContext context) {
|
||||
accessPolicy.authorize(FileOperation.ADMIN_FORCE_DELETE, context.subject(), Optional.empty());
|
||||
List<OrphanObject> candidates = orphanScanPort.scan(boundedLimit(command.limit()));
|
||||
if (command.dryRun()) {
|
||||
audit("orphans:reconcile", command.reasonCode(), context, true, "dry-run");
|
||||
return new OrphanReconcileReport(true, candidates, 0, 0, 0);
|
||||
}
|
||||
|
||||
int deleted = 0;
|
||||
int mismatched = 0;
|
||||
long reclaimed = 0;
|
||||
for (OrphanObject candidate : candidates) {
|
||||
if (!command.expectedFingerprints().contains(candidate.fingerprint())) {
|
||||
mismatched++;
|
||||
continue;
|
||||
}
|
||||
if (reclaimed + candidate.sizeBytes() > command.maxBytes()) {
|
||||
break;
|
||||
}
|
||||
if (orphanScanPort.deleteIfFingerprintMatches(
|
||||
candidate.contentKey(), candidate.fingerprint())) {
|
||||
// Retirement moved the object to quarantine; the durable record of that intent is queued
|
||||
// immediately after. Without it a node that dies here leaves an object nobody is looking
|
||||
// for, in an area nothing scans.
|
||||
transactions.inWrite(
|
||||
() -> cleanupQueue.enqueue(CleanupRequest.forOrphan(candidate.contentKey())));
|
||||
deleted++;
|
||||
reclaimed += candidate.sizeBytes();
|
||||
} else {
|
||||
mismatched++;
|
||||
}
|
||||
}
|
||||
audit("orphans:reconcile", command.reasonCode(), context, true, "apply");
|
||||
return new OrphanReconcileReport(false, candidates, deleted, mismatched, reclaimed);
|
||||
}
|
||||
|
||||
@Override
|
||||
public FileView reverify(FileId fileId, RequestContext context) {
|
||||
accessPolicy.authorize(FileOperation.ADMIN_REVERIFY, context.subject(), Optional.empty());
|
||||
FileRecord record = requireRecord(fileId);
|
||||
if (record.state() != FileState.QUARANTINED) {
|
||||
audit("files:reverify", "REVERIFY_REJECTED", context, false, fileId.canonicalText());
|
||||
throw new FileNotReadyException(
|
||||
"only a quarantined file can be re-verified",
|
||||
FileserverFailureContext.forFileState(
|
||||
FileserverErrorCode.FILE_NOT_READY, fileId, record.state(), false));
|
||||
}
|
||||
FileRecord verifying =
|
||||
transactions.inWrite(
|
||||
() ->
|
||||
metadataStore.transition(
|
||||
record.fileId(),
|
||||
record.version(),
|
||||
FileState.QUARANTINED,
|
||||
FileState.VERIFYING,
|
||||
FileRecordMutation.none()));
|
||||
audit("files:reverify", "OPERATOR_REVERIFY", context, true, fileId.canonicalText());
|
||||
return FileView.of(verifying.toDescriptor());
|
||||
}
|
||||
|
||||
@Override
|
||||
public void forceDelete(ForceDeleteCommand command, RequestContext context) {
|
||||
accessPolicy.authorize(FileOperation.ADMIN_FORCE_DELETE, context.subject(), Optional.empty());
|
||||
FileRecord record = requireRecord(command.fileId());
|
||||
// An operator force-delete must not be able to leave a file unreachable with nothing queued to
|
||||
// reclaim its bytes, so retiring the record and queueing the content commit together.
|
||||
transactions.inWrite(
|
||||
() -> {
|
||||
FileRecord deleting = metadataStore.markDeleting(record.fileId(), record.version());
|
||||
deleting
|
||||
.contentKey()
|
||||
.ifPresent(
|
||||
key ->
|
||||
cleanupQueue.enqueue(
|
||||
CleanupRequest.forContent(
|
||||
CleanupType.DELETED_READY_CONTENT, deleting.fileId(), key)));
|
||||
});
|
||||
audit(
|
||||
"files:force-delete",
|
||||
command.reasonCode(),
|
||||
context,
|
||||
true,
|
||||
command.fileId().canonicalText());
|
||||
}
|
||||
|
||||
@Override
|
||||
public List<IncompleteUploadView> incompleteUploads(int limit, RequestContext context) {
|
||||
authorizeRead(context);
|
||||
List<IncompleteUploadView> views = new ArrayList<>();
|
||||
for (UploadSession session : sessionStore.findExpired(clock.instant(), boundedLimit(limit))) {
|
||||
views.add(
|
||||
new IncompleteUploadView(
|
||||
session.uploadId(),
|
||||
session.fileId(),
|
||||
session.committedOffset(),
|
||||
session.expiresAt(),
|
||||
session.leaseOwner(),
|
||||
session.leaseUntil()));
|
||||
}
|
||||
return List.copyOf(views);
|
||||
}
|
||||
|
||||
@Override
|
||||
public CleanupBatchResult cleanupUploads(int maxItems, long maxBytes, RequestContext context) {
|
||||
accessPolicy.authorize(FileOperation.ADMIN_FORCE_DELETE, context.subject(), Optional.empty());
|
||||
CleanupBatchResult result = cleanupService.runBatch(boundedLimit(maxItems), maxBytes);
|
||||
audit("uploads:cleanup", "OPERATOR_CLEANUP", context, true, "batch");
|
||||
return result;
|
||||
}
|
||||
|
||||
private void authorizeRead(RequestContext context) {
|
||||
accessPolicy.authorize(FileOperation.READ_METADATA, context.subject(), Optional.empty());
|
||||
}
|
||||
|
||||
/**
|
||||
* Caps every admin query.
|
||||
*
|
||||
* <p>An unbounded admin listing is a self-inflicted outage: it walks production storage or the
|
||||
* whole metadata table on an operator's keystroke.
|
||||
*/
|
||||
private static int boundedLimit(int requested) {
|
||||
return Math.max(1, Math.min(requested, MAXIMUM_ADMIN_PAGE));
|
||||
}
|
||||
|
||||
private void audit(
|
||||
String operation,
|
||||
String reasonCode,
|
||||
RequestContext context,
|
||||
boolean succeeded,
|
||||
String subjectId) {
|
||||
auditPort.record(
|
||||
new AdminAuditRecord(
|
||||
operation,
|
||||
reasonCode,
|
||||
actorFingerprint(context),
|
||||
context.traceId(),
|
||||
succeeded,
|
||||
subjectFingerprint(subjectId),
|
||||
clock.instant()));
|
||||
}
|
||||
|
||||
/**
|
||||
* Stable pseudonym for the acting operator.
|
||||
*
|
||||
* <p>An audit trail needs to correlate actions by the same actor without becoming a second
|
||||
* directory of who works here, so the principal is reduced to a fingerprint.
|
||||
*
|
||||
* <p>A keyed HMAC, not {@code hashCode()}. A 32-bit unkeyed hash over an enumerable identifier
|
||||
* space is reversible with a laptop and collides often enough that two operators can share a
|
||||
* pseudonym — which is worse than no pseudonym, because the trail then reads as if one person did
|
||||
* both things.
|
||||
*/
|
||||
private String actorFingerprint(RequestContext context) {
|
||||
return fingerprint.of(context.subject().principalId());
|
||||
}
|
||||
|
||||
/** The same reduction for the object of the action; a raw file id is a disclosure too. */
|
||||
private String subjectFingerprint(String subjectId) {
|
||||
return subjectId.isBlank() ? subjectId : fingerprint.of(subjectId);
|
||||
}
|
||||
|
||||
private FileRecord requireRecord(FileId fileId) {
|
||||
return metadataStore
|
||||
.find(fileId)
|
||||
.orElseThrow(
|
||||
() ->
|
||||
new FileNotFoundException(
|
||||
"file record does not exist",
|
||||
FileserverFailureContext.forFile(
|
||||
FileserverErrorCode.FILE_NOT_FOUND, fileId, false)));
|
||||
}
|
||||
}
|
||||
-34
@@ -1,34 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.admin;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.FileId;
|
||||
import dev.caskeleton.application.fileserver.api.security.RequestContext;
|
||||
import dev.caskeleton.application.fileserver.cleanup.CleanupBatchResult;
|
||||
import dev.caskeleton.application.fileserver.upload.FileView;
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* The management-plane surface.
|
||||
*
|
||||
* <p>Every method here is deliberately separate from the public application services: an operator
|
||||
* action is authorized against a different authority, is always audited, and may see counters a
|
||||
* tenant never should. Mixing them into the public services is how an admin capability ends up one
|
||||
* missing check away from being publicly reachable.
|
||||
*/
|
||||
public interface FileserverAdminService {
|
||||
|
||||
StorageHealthReport storageHealth(RequestContext context);
|
||||
|
||||
RuntimeCapabilityReport capabilities(RequestContext context);
|
||||
|
||||
List<OrphanObject> orphans(int limit, RequestContext context);
|
||||
|
||||
OrphanReconcileReport reconcileOrphans(OrphanReconcileCommand command, RequestContext context);
|
||||
|
||||
FileView reverify(FileId fileId, RequestContext context);
|
||||
|
||||
void forceDelete(ForceDeleteCommand command, RequestContext context);
|
||||
|
||||
List<IncompleteUploadView> incompleteUploads(int limit, RequestContext context);
|
||||
|
||||
CleanupBatchResult cleanupUploads(int maxItems, long maxBytes, RequestContext context);
|
||||
}
|
||||
-24
@@ -1,24 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.admin;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.FileId;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* Operator-forced removal of a file, bypassing the normal precondition.
|
||||
*
|
||||
* <p>The reason is mandatory and the caller must hold the second, force-delete-specific authority.
|
||||
* A force delete that needed only the ordinary delete permission would make every operator able to
|
||||
* destroy content the lifecycle rules exist to protect.
|
||||
*/
|
||||
public record ForceDeleteCommand(FileId fileId, String reasonCode) {
|
||||
|
||||
private static final int MINIMUM_REASON_LENGTH = 8;
|
||||
|
||||
public ForceDeleteCommand {
|
||||
Objects.requireNonNull(fileId, "fileId");
|
||||
Objects.requireNonNull(reasonCode, "reasonCode");
|
||||
if (reasonCode.strip().length() < MINIMUM_REASON_LENGTH) {
|
||||
throw new IllegalArgumentException("force delete requires an explicit reason");
|
||||
}
|
||||
}
|
||||
}
|
||||
-31
@@ -1,31 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.admin;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.FileId;
|
||||
import dev.caskeleton.application.fileserver.api.UploadId;
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* Operator view of an upload that never completed.
|
||||
*
|
||||
* <p>The original filename is deliberately absent: an operator triaging stuck uploads needs the
|
||||
* identity, the offset, and the lease, and a filename is user-supplied content that would put
|
||||
* arbitrary text into an admin console.
|
||||
*/
|
||||
public record IncompleteUploadView(
|
||||
UploadId uploadId,
|
||||
FileId fileId,
|
||||
long committedOffset,
|
||||
Instant expiresAt,
|
||||
Optional<String> leaseOwner,
|
||||
Optional<Instant> leaseUntil) {
|
||||
|
||||
public IncompleteUploadView {
|
||||
Objects.requireNonNull(uploadId, "uploadId");
|
||||
Objects.requireNonNull(fileId, "fileId");
|
||||
Objects.requireNonNull(expiresAt, "expiresAt");
|
||||
Objects.requireNonNull(leaseOwner, "leaseOwner");
|
||||
Objects.requireNonNull(leaseUntil, "leaseUntil");
|
||||
}
|
||||
}
|
||||
-24
@@ -1,24 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.admin;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.ContentKey;
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* A physical object with no metadata record pointing at it.
|
||||
*
|
||||
* <p>{@code fingerprint} is what makes an apply safe: the caller must echo the exact fingerprint it
|
||||
* was shown, so an object that changed between the scan and the apply is never deleted.
|
||||
*/
|
||||
public record OrphanObject(
|
||||
ContentKey contentKey, long sizeBytes, Instant observedAt, String fingerprint) {
|
||||
|
||||
public OrphanObject {
|
||||
Objects.requireNonNull(contentKey, "contentKey");
|
||||
Objects.requireNonNull(observedAt, "observedAt");
|
||||
Objects.requireNonNull(fingerprint, "fingerprint");
|
||||
if (sizeBytes < 0) {
|
||||
throw new IllegalArgumentException("sizeBytes must not be negative");
|
||||
}
|
||||
}
|
||||
}
|
||||
-40
@@ -1,40 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.admin;
|
||||
|
||||
import java.util.List;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* Request to reconcile orphaned physical objects.
|
||||
*
|
||||
* <p>{@code dryRun} defaults to true at every layer above this record. An apply additionally has to
|
||||
* name the exact fingerprints it intends to remove and a byte budget, so a reconcile can never turn
|
||||
* into an unbounded mass delete driven by a stale scan.
|
||||
*/
|
||||
public record OrphanReconcileCommand(
|
||||
boolean dryRun,
|
||||
int limit,
|
||||
long maxBytes,
|
||||
List<String> expectedFingerprints,
|
||||
String reasonCode) {
|
||||
|
||||
public OrphanReconcileCommand {
|
||||
Objects.requireNonNull(expectedFingerprints, "expectedFingerprints");
|
||||
Objects.requireNonNull(reasonCode, "reasonCode");
|
||||
if (limit < 1 || maxBytes < 1) {
|
||||
throw new IllegalArgumentException("limit and maxBytes must be positive");
|
||||
}
|
||||
if (!dryRun && expectedFingerprints.isEmpty()) {
|
||||
throw new IllegalArgumentException(
|
||||
"an apply must name the fingerprints it intends to remove");
|
||||
}
|
||||
if (reasonCode.isBlank()) {
|
||||
throw new IllegalArgumentException("reasonCode must be non-blank");
|
||||
}
|
||||
expectedFingerprints = List.copyOf(expectedFingerprints);
|
||||
}
|
||||
|
||||
/** Bounded dry run, the default and the only shape a caller can reach without opting in. */
|
||||
public static OrphanReconcileCommand dryRun(int limit) {
|
||||
return new OrphanReconcileCommand(true, limit, Long.MAX_VALUE, List.of(), "ORPHAN_SCAN");
|
||||
}
|
||||
}
|
||||
-26
@@ -1,26 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.admin;
|
||||
|
||||
import java.util.List;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* Outcome of one reconcile.
|
||||
*
|
||||
* <p>{@code dryRun} is echoed back deliberately: an operator reading a report must never have to
|
||||
* infer whether it described a plan or an action already taken.
|
||||
*/
|
||||
public record OrphanReconcileReport(
|
||||
boolean dryRun,
|
||||
List<OrphanObject> candidates,
|
||||
int deleted,
|
||||
int skippedFingerprintMismatch,
|
||||
long reclaimedBytes) {
|
||||
|
||||
public OrphanReconcileReport {
|
||||
Objects.requireNonNull(candidates, "candidates");
|
||||
if (deleted < 0 || skippedFingerprintMismatch < 0 || reclaimedBytes < 0) {
|
||||
throw new IllegalArgumentException("counters must not be negative");
|
||||
}
|
||||
candidates = List.copyOf(candidates);
|
||||
}
|
||||
}
|
||||
-36
@@ -1,36 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.admin;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.ContentKey;
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* Bounded scan for physical objects with no metadata record.
|
||||
*
|
||||
* <p>The scan is always bounded; an unbounded walk of a production content root is itself an
|
||||
* availability incident.
|
||||
*/
|
||||
public interface OrphanScanPort {
|
||||
|
||||
List<OrphanObject> scan(int limit);
|
||||
|
||||
/**
|
||||
* Retires one orphan, guarded by the fingerprint the caller was shown.
|
||||
*
|
||||
* <p>"Retires" rather than "deletes" on purpose. Checking that nothing references an object and
|
||||
* then unlinking it is not atomic against a record committed in between, and that ordering has no
|
||||
* safe variant: whichever step runs first, a live object can be destroyed with nothing left to
|
||||
* restore. The implementation therefore moves the object aside reversibly and re-checks, so a
|
||||
* record that appeared during the move puts the object straight back.
|
||||
*
|
||||
* @return true when the object was retired, false when it was left in place
|
||||
*/
|
||||
boolean deleteIfFingerprintMatches(ContentKey key, String expectedFingerprint);
|
||||
|
||||
/**
|
||||
* Reclaims a retired object for good, once nothing references it.
|
||||
*
|
||||
* <p>Separated from retirement so the destructive step is a second, later decision rather than
|
||||
* part of the same racing sequence.
|
||||
*/
|
||||
boolean purgeQuarantined(ContentKey key);
|
||||
}
|
||||
-25
@@ -1,25 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.admin;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.content.ContentStoreCapabilities;
|
||||
import dev.caskeleton.application.fileserver.api.content.PublishMode;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* What this deployment can actually do, as proven by the startup probe.
|
||||
*
|
||||
* <p>Every flag here came from a real filesystem probe rather than configuration, which is what
|
||||
* makes the endpoint useful for diagnosing a misconfigured mount. No physical path appears.
|
||||
*/
|
||||
public record RuntimeCapabilityReport(
|
||||
String storageType,
|
||||
PublishMode publishMode,
|
||||
ContentStoreCapabilities capabilities,
|
||||
String filesystemProfile) {
|
||||
|
||||
public RuntimeCapabilityReport {
|
||||
Objects.requireNonNull(storageType, "storageType");
|
||||
Objects.requireNonNull(publishMode, "publishMode");
|
||||
Objects.requireNonNull(capabilities, "capabilities");
|
||||
Objects.requireNonNull(filesystemProfile, "filesystemProfile");
|
||||
}
|
||||
}
|
||||
-14
@@ -1,14 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.admin;
|
||||
|
||||
/**
|
||||
* Live capacity and probe observation.
|
||||
*
|
||||
* <p>Behind this port sits the same startup probe that gated the application's boot, so the admin
|
||||
* answer and the startup decision can never disagree.
|
||||
*/
|
||||
public interface StorageHealthPort {
|
||||
|
||||
StorageHealthReport health();
|
||||
|
||||
RuntimeCapabilityReport capabilities();
|
||||
}
|
||||
-30
@@ -1,30 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.admin;
|
||||
|
||||
import java.util.List;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* Operator view of storage capacity and probe results.
|
||||
*
|
||||
* <p>It reports proportions and boolean probe outcomes, never the physical root, the mount, or the
|
||||
* device. An operator needs to know whether storage is healthy; disclosing where it lives only adds
|
||||
* a target.
|
||||
*/
|
||||
public record StorageHealthReport(
|
||||
long totalBytes,
|
||||
long usableBytes,
|
||||
double usedFraction,
|
||||
boolean writable,
|
||||
boolean atomicPublishProven,
|
||||
String filesystemProfile,
|
||||
List<String> probeWarnings) {
|
||||
|
||||
public StorageHealthReport {
|
||||
Objects.requireNonNull(filesystemProfile, "filesystemProfile");
|
||||
Objects.requireNonNull(probeWarnings, "probeWarnings");
|
||||
if (totalBytes < 0 || usableBytes < 0) {
|
||||
throw new IllegalArgumentException("byte counters must not be negative");
|
||||
}
|
||||
probeWarnings = List.copyOf(probeWarnings);
|
||||
}
|
||||
}
|
||||
-48
@@ -1,48 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api;
|
||||
|
||||
/**
|
||||
* Inclusive byte range over a concrete representation.
|
||||
*
|
||||
* <p>HTTP suffix and open-ended ranges are normalized into this value object by the transport range
|
||||
* resolver, using the current representation length. The core never sees an unresolved range.
|
||||
*/
|
||||
public record ByteRange(long startInclusive, long endInclusive) {
|
||||
|
||||
public ByteRange {
|
||||
if (startInclusive < 0 || endInclusive < startInclusive) {
|
||||
throw new IllegalArgumentException("invalid byte range");
|
||||
}
|
||||
}
|
||||
|
||||
public static ByteRange of(long startInclusive, long endInclusive) {
|
||||
return new ByteRange(startInclusive, endInclusive);
|
||||
}
|
||||
|
||||
/** Full-representation range for a non-empty representation. */
|
||||
public static ByteRange entire(long representationLength) {
|
||||
if (representationLength <= 0) {
|
||||
throw new IllegalArgumentException("representation length must be positive");
|
||||
}
|
||||
return new ByteRange(0, representationLength - 1);
|
||||
}
|
||||
|
||||
public long length() {
|
||||
return Math.addExact(Math.subtractExact(endInclusive, startInclusive), 1);
|
||||
}
|
||||
|
||||
public boolean overlaps(ByteRange other) {
|
||||
return startInclusive <= other.endInclusive && other.startInclusive <= endInclusive;
|
||||
}
|
||||
|
||||
/** True when this range and {@code other} touch or overlap and can be merged into one range. */
|
||||
public boolean isAdjacentOrOverlapping(ByteRange other) {
|
||||
return overlaps(other)
|
||||
|| endInclusive + 1 == other.startInclusive
|
||||
|| other.endInclusive + 1 == startInclusive;
|
||||
}
|
||||
|
||||
public ByteRange merge(ByteRange other) {
|
||||
return new ByteRange(
|
||||
Math.min(startInclusive, other.startInclusive), Math.max(endInclusive, other.endInclusive));
|
||||
}
|
||||
}
|
||||
-25
@@ -1,25 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api;
|
||||
|
||||
import java.util.regex.Pattern;
|
||||
|
||||
/**
|
||||
* Server-generated physical content key.
|
||||
*
|
||||
* <p>The key is never part of the public HTTP contract and never derives from a client filename.
|
||||
* The character class deliberately excludes {@code .}, so no traversal or extension-shaped segment
|
||||
* can survive validation.
|
||||
*/
|
||||
public record ContentKey(String value) {
|
||||
|
||||
private static final Pattern CANONICAL = Pattern.compile("[a-z0-9/_-]{16,200}");
|
||||
|
||||
public ContentKey {
|
||||
if (value == null || !CANONICAL.matcher(value).matches()) {
|
||||
throw new IllegalArgumentException("invalid content key");
|
||||
}
|
||||
}
|
||||
|
||||
public static ContentKey of(String value) {
|
||||
return new ContentKey(value);
|
||||
}
|
||||
}
|
||||
-53
@@ -1,53 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api;
|
||||
|
||||
import java.util.Map;
|
||||
import java.util.Set;
|
||||
|
||||
/**
|
||||
* Exact transition table from the Fileserver platform design.
|
||||
*
|
||||
* <p>Recovery transitions out of {@link FileState#FAILED} are structurally allowed here; the
|
||||
* recovery policy separately decides whether the stored {@code lastErrorCode} permits them.
|
||||
*/
|
||||
public final class DefaultFileStateMachine implements FileStateMachine {
|
||||
|
||||
private static final Map<FileState, Set<FileState>> ALLOWED =
|
||||
Map.ofEntries(
|
||||
Map.entry(FileState.CREATED, Set.of(FileState.UPLOADING)),
|
||||
Map.entry(
|
||||
FileState.UPLOADING,
|
||||
Set.of(FileState.UPLOADED, FileState.FAILED, FileState.EXPIRED, FileState.DELETING)),
|
||||
Map.entry(
|
||||
FileState.UPLOADED,
|
||||
Set.of(FileState.VERIFYING, FileState.FAILED, FileState.DELETING)),
|
||||
Map.entry(
|
||||
FileState.VERIFYING,
|
||||
Set.of(FileState.READY, FileState.QUARANTINED, FileState.REJECTED, FileState.FAILED)),
|
||||
Map.entry(
|
||||
FileState.QUARANTINED,
|
||||
Set.of(FileState.VERIFYING, FileState.READY, FileState.REJECTED, FileState.DELETING)),
|
||||
Map.entry(FileState.READY, Set.of(FileState.DELETING)),
|
||||
Map.entry(FileState.REJECTED, Set.of(FileState.DELETING)),
|
||||
Map.entry(
|
||||
FileState.FAILED,
|
||||
Set.of(
|
||||
FileState.UPLOADING, FileState.VERIFYING, FileState.DELETING, FileState.EXPIRED)),
|
||||
Map.entry(FileState.DELETING, Set.of(FileState.DELETED, FileState.FAILED)),
|
||||
Map.entry(FileState.EXPIRED, Set.of(FileState.DELETING)),
|
||||
Map.entry(FileState.DELETED, Set.of()));
|
||||
|
||||
@Override
|
||||
public boolean canTransition(FileState current, FileState target) {
|
||||
if (current == null || target == null) {
|
||||
return false;
|
||||
}
|
||||
return ALLOWED.getOrDefault(current, Set.of()).contains(target);
|
||||
}
|
||||
|
||||
@Override
|
||||
public void requireTransition(FileState current, FileState target) {
|
||||
if (!canTransition(current, target)) {
|
||||
throw new IllegalStateException("illegal file transition: " + current + " -> " + target);
|
||||
}
|
||||
}
|
||||
}
|
||||
-31
@@ -1,31 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api;
|
||||
|
||||
import java.util.Objects;
|
||||
import java.util.UUID;
|
||||
|
||||
/**
|
||||
* Opaque public identity of a stored file.
|
||||
*
|
||||
* <p>The value is hard to guess but is never treated as a bearer secret: every public operation
|
||||
* still runs the authorization hook. It never encodes a path, a physical key, or an original
|
||||
* filename.
|
||||
*/
|
||||
public record FileId(UUID value) {
|
||||
|
||||
public FileId {
|
||||
Objects.requireNonNull(value, "value");
|
||||
}
|
||||
|
||||
public static FileId of(UUID value) {
|
||||
return new FileId(value);
|
||||
}
|
||||
|
||||
public static FileId parse(String canonicalText) {
|
||||
Objects.requireNonNull(canonicalText, "canonicalText");
|
||||
return new FileId(UUID.fromString(canonicalText));
|
||||
}
|
||||
|
||||
public String canonicalText() {
|
||||
return value.toString();
|
||||
}
|
||||
}
|
||||
-31
@@ -1,31 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api;
|
||||
|
||||
/**
|
||||
* Authoritative lifecycle state of a file record.
|
||||
*
|
||||
* <p>Only {@link #READY} exposes readable immutable content. Every other state is excluded from
|
||||
* direct download and from delegated (Nginx) transfer.
|
||||
*/
|
||||
public enum FileState {
|
||||
CREATED,
|
||||
UPLOADING,
|
||||
UPLOADED,
|
||||
VERIFYING,
|
||||
QUARANTINED,
|
||||
READY,
|
||||
REJECTED,
|
||||
FAILED,
|
||||
DELETING,
|
||||
DELETED,
|
||||
EXPIRED;
|
||||
|
||||
/** True when the state permits public download authorization. */
|
||||
public boolean isPubliclyReadable() {
|
||||
return this == READY;
|
||||
}
|
||||
|
||||
/** True when no further lifecycle progress is possible through the public API. */
|
||||
public boolean isTerminal() {
|
||||
return this == DELETED;
|
||||
}
|
||||
}
|
||||
-14
@@ -1,14 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api;
|
||||
|
||||
/**
|
||||
* Single authority for allowed file lifecycle transitions.
|
||||
*
|
||||
* <p>Persistence adapters and transport adapters never assign {@link FileState} directly; they ask
|
||||
* this contract first so an illegal transition cannot enter the metadata store.
|
||||
*/
|
||||
public interface FileStateMachine {
|
||||
|
||||
void requireTransition(FileState current, FileState target);
|
||||
|
||||
boolean canTransition(FileState current, FileState target);
|
||||
}
|
||||
-23
@@ -1,23 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api;
|
||||
|
||||
import java.util.regex.Pattern;
|
||||
|
||||
/**
|
||||
* Logical storage and ownership namespace.
|
||||
*
|
||||
* <p>A namespace is a metadata grouping only. It is never a directory, a mount, or a bucket name.
|
||||
*/
|
||||
public record StorageNamespace(String value) {
|
||||
|
||||
private static final Pattern CANONICAL = Pattern.compile("[a-z][a-z0-9-]{1,62}");
|
||||
|
||||
public StorageNamespace {
|
||||
if (value == null || !CANONICAL.matcher(value).matches()) {
|
||||
throw new IllegalArgumentException("invalid storage namespace");
|
||||
}
|
||||
}
|
||||
|
||||
public static StorageNamespace of(String value) {
|
||||
return new StorageNamespace(value);
|
||||
}
|
||||
}
|
||||
-30
@@ -1,30 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api;
|
||||
|
||||
import java.util.Objects;
|
||||
import java.util.UUID;
|
||||
|
||||
/**
|
||||
* Opaque public identity of a resumable upload resource.
|
||||
*
|
||||
* <p>An upload resource has a lifecycle independent of the READY file it eventually produces, so
|
||||
* the two identities are never interchangeable.
|
||||
*/
|
||||
public record UploadId(UUID value) {
|
||||
|
||||
public UploadId {
|
||||
Objects.requireNonNull(value, "value");
|
||||
}
|
||||
|
||||
public static UploadId of(UUID value) {
|
||||
return new UploadId(value);
|
||||
}
|
||||
|
||||
public static UploadId parse(String canonicalText) {
|
||||
Objects.requireNonNull(canonicalText, "canonicalText");
|
||||
return new UploadId(UUID.fromString(canonicalText));
|
||||
}
|
||||
|
||||
public String canonicalText() {
|
||||
return value.toString();
|
||||
}
|
||||
}
|
||||
-19
@@ -1,19 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.content;
|
||||
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* Outcome of one durable append.
|
||||
*
|
||||
* <p>{@code committedOffset} only advances by bytes the store observed reaching the channel, so a
|
||||
* partial write can never inflate the resumable offset.
|
||||
*/
|
||||
public record AppendResult(long committedOffset, long appendedBytes, String sha256) {
|
||||
|
||||
public AppendResult {
|
||||
if (committedOffset < 0 || appendedBytes < 0) {
|
||||
throw new IllegalArgumentException("append offsets must not be negative");
|
||||
}
|
||||
Objects.requireNonNull(sha256, "sha256");
|
||||
}
|
||||
}
|
||||
-32
@@ -1,32 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.content;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.ByteRange;
|
||||
import dev.caskeleton.application.fileserver.api.ContentKey;
|
||||
import java.nio.ByteBuffer;
|
||||
import java.util.concurrent.CompletionStage;
|
||||
import java.util.concurrent.Flow;
|
||||
|
||||
/**
|
||||
* Non-blocking storage SPI with the same semantics as {@link BlockingContentStore}.
|
||||
*
|
||||
* <p>Streaming uses {@link Flow.Publisher} of {@link ByteBuffer} so the core stays free of Reactor
|
||||
* and Spring buffer types; the WebFlux adapter owns the conversion and the pooled-buffer lifecycle.
|
||||
*/
|
||||
public interface AsyncContentStore {
|
||||
|
||||
CompletionStage<UploadHandle> createUpload(CreateContentCommand command);
|
||||
|
||||
CompletionStage<AppendResult> append(
|
||||
UploadHandle handle, long expectedOffset, Flow.Publisher<ByteBuffer> content);
|
||||
|
||||
CompletionStage<StoredContent> finalizeUpload(
|
||||
UploadHandle handle, FinalizeContentCommand command);
|
||||
|
||||
CompletionStage<ContentMetadata> stat(ContentKey key);
|
||||
|
||||
Flow.Publisher<ByteBuffer> openRead(ContentKey key, ByteRange range);
|
||||
|
||||
CompletionStage<DeleteResult> delete(ContentKey key, DeletePrecondition precondition);
|
||||
|
||||
ContentStoreCapabilities capabilities();
|
||||
}
|
||||
-47
@@ -1,47 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.content;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.ByteRange;
|
||||
import dev.caskeleton.application.fileserver.api.ContentKey;
|
||||
import java.nio.channels.ReadableByteChannel;
|
||||
|
||||
/**
|
||||
* Blocking storage SPI shared by every content store implementation.
|
||||
*
|
||||
* <p>The contract is deliberately expressed as create / append / finalize / stat / openRead /
|
||||
* delete semantics rather than as a mirror of filesystem commands. No signature may name a {@code
|
||||
* Path}, a Spring {@code Resource}, a {@code DataBuffer}, a Reactor type, or a provider SDK type.
|
||||
*/
|
||||
public interface BlockingContentStore {
|
||||
|
||||
UploadHandle createUpload(CreateContentCommand command);
|
||||
|
||||
/**
|
||||
* Appends under a fence that is re-checked as the transfer proceeds.
|
||||
*
|
||||
* <p>The fence is a parameter rather than store state because ownership belongs to the caller's
|
||||
* lease, not to the object: the store knows how to stop writing, but only the caller knows when
|
||||
* it has lost the right to.
|
||||
*/
|
||||
AppendResult append(
|
||||
UploadHandle handle,
|
||||
long expectedOffset,
|
||||
ReadableByteChannel source,
|
||||
long contentLength,
|
||||
WriteFence fence);
|
||||
|
||||
/** Appends with no ownership to lose; see {@link WriteFence#unfenced()}. */
|
||||
default AppendResult append(
|
||||
UploadHandle handle, long expectedOffset, ReadableByteChannel source, long contentLength) {
|
||||
return append(handle, expectedOffset, source, contentLength, WriteFence.unfenced());
|
||||
}
|
||||
|
||||
StoredContent finalizeUpload(UploadHandle handle, FinalizeContentCommand command);
|
||||
|
||||
ContentMetadata stat(ContentKey key);
|
||||
|
||||
ReadableByteChannel openRead(ContentKey key, ByteRange range);
|
||||
|
||||
DeleteResult delete(ContentKey key, DeletePrecondition precondition);
|
||||
|
||||
ContentStoreCapabilities capabilities();
|
||||
}
|
||||
-12
@@ -1,12 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.content;
|
||||
|
||||
/**
|
||||
* Optional capacity reporting used by admission control and the admin plane.
|
||||
*
|
||||
* <p>Stores that cannot answer capacity simply do not implement this interface; the high-water
|
||||
* guards then degrade to reservation-only accounting.
|
||||
*/
|
||||
public interface CapacityAwareContentStore {
|
||||
|
||||
StorageCapacity capacity();
|
||||
}
|
||||
-22
@@ -1,22 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.content;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.ContentKey;
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* Physical observation of a stored object.
|
||||
*
|
||||
* <p>This is used for publish verification and reconciliation only. It is never the source of
|
||||
* public metadata, and its timestamp is never served as {@code Last-Modified}.
|
||||
*/
|
||||
public record ContentMetadata(ContentKey contentKey, long size, Instant lastModified) {
|
||||
|
||||
public ContentMetadata {
|
||||
Objects.requireNonNull(contentKey, "contentKey");
|
||||
Objects.requireNonNull(lastModified, "lastModified");
|
||||
if (size < 0) {
|
||||
throw new IllegalArgumentException("size must not be negative");
|
||||
}
|
||||
}
|
||||
}
|
||||
-22
@@ -1,22 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.content;
|
||||
|
||||
/**
|
||||
* Runtime capabilities of a content store, produced by a real startup probe.
|
||||
*
|
||||
* <p>These flags are never read from configuration alone: the local adapter proves each one against
|
||||
* the configured storage root before the application accepts traffic.
|
||||
*/
|
||||
public record ContentStoreCapabilities(
|
||||
boolean rangedRead,
|
||||
boolean atomicCreate,
|
||||
boolean atomicPublish,
|
||||
boolean conditionalWrite,
|
||||
boolean serverSideCopy,
|
||||
boolean delegatedDownload,
|
||||
boolean resumableAppend) {
|
||||
|
||||
/** Capability set with every optional feature disabled. */
|
||||
public static ContentStoreCapabilities none() {
|
||||
return new ContentStoreCapabilities(false, false, false, false, false, false, false);
|
||||
}
|
||||
}
|
||||
-16
@@ -1,16 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.content;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.ContentKey;
|
||||
import java.util.concurrent.CompletionStage;
|
||||
|
||||
/**
|
||||
* Optional server-side copy capability.
|
||||
*
|
||||
* <p>Stores without it fall back to an application-level stream copy. Automatic rollback of a
|
||||
* failed copy is never promised; an incomplete target goes to the cleanup queue.
|
||||
*/
|
||||
public interface CopyCapableContentStore {
|
||||
|
||||
CompletionStage<StoredContent> copy(
|
||||
ContentKey source, ContentKey target, CopyPrecondition precondition);
|
||||
}
|
||||
-19
@@ -1,19 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.content;
|
||||
|
||||
/**
|
||||
* Conditions a server-side copy must satisfy.
|
||||
*
|
||||
* <p>The default is create-only: an existing target is a failure, never a silent overwrite.
|
||||
*/
|
||||
public record CopyPrecondition(boolean createOnly) {
|
||||
|
||||
/** Create-only copy, the Fileserver default. */
|
||||
public static CopyPrecondition requireCreateOnly() {
|
||||
return new CopyPrecondition(true);
|
||||
}
|
||||
|
||||
/** Conditional replace, reachable only from a path that already validated a precondition. */
|
||||
public static CopyPrecondition allowConditionalReplace() {
|
||||
return new CopyPrecondition(false);
|
||||
}
|
||||
}
|
||||
-32
@@ -1,32 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.content;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.StorageNamespace;
|
||||
import dev.caskeleton.application.fileserver.api.UploadId;
|
||||
import java.util.Objects;
|
||||
import java.util.OptionalLong;
|
||||
|
||||
/**
|
||||
* Request to create a new staging object.
|
||||
*
|
||||
* <p>The command carries no client filename: the physical object is named from server-generated
|
||||
* identity only. {@code expectedLength} is advisory and is re-verified against the bytes that are
|
||||
* actually written.
|
||||
*/
|
||||
public record CreateContentCommand(
|
||||
UploadId uploadId,
|
||||
StorageNamespace namespace,
|
||||
OptionalLong expectedLength,
|
||||
long maximumLength) {
|
||||
|
||||
public CreateContentCommand {
|
||||
Objects.requireNonNull(uploadId, "uploadId");
|
||||
Objects.requireNonNull(namespace, "namespace");
|
||||
Objects.requireNonNull(expectedLength, "expectedLength");
|
||||
if (maximumLength <= 0) {
|
||||
throw new IllegalArgumentException("maximumLength must be positive");
|
||||
}
|
||||
if (expectedLength.isPresent() && expectedLength.getAsLong() < 0) {
|
||||
throw new IllegalArgumentException("expectedLength must not be negative");
|
||||
}
|
||||
}
|
||||
}
|
||||
-23
@@ -1,23 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.content;
|
||||
|
||||
import java.time.Duration;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* Internal descriptor a front proxy consumes to perform the actual transfer.
|
||||
*
|
||||
* <p>{@code internalUri} is always relative and always below the configured internal prefix.
|
||||
*/
|
||||
public record DelegatedDownloadDescriptor(String internalUri, Duration ttl) {
|
||||
|
||||
public DelegatedDownloadDescriptor {
|
||||
Objects.requireNonNull(internalUri, "internalUri");
|
||||
Objects.requireNonNull(ttl, "ttl");
|
||||
if (!internalUri.startsWith("/") || internalUri.contains("..")) {
|
||||
throw new IllegalArgumentException("internal uri must be a relative-rooted safe path");
|
||||
}
|
||||
if (ttl.isNegative() || ttl.isZero()) {
|
||||
throw new IllegalArgumentException("ttl must be positive");
|
||||
}
|
||||
}
|
||||
}
|
||||
-18
@@ -1,18 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.content;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.ByteRange;
|
||||
import dev.caskeleton.application.fileserver.api.ContentKey;
|
||||
import java.time.Duration;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* Optional capability to hand a transfer to a front proxy instead of streaming it in-process.
|
||||
*
|
||||
* <p>The descriptor is a validated relative internal URI. It never contains an absolute physical
|
||||
* path, and issuing a publicly signed URL is out of scope for this store family.
|
||||
*/
|
||||
public interface DelegatedDownloadStore {
|
||||
|
||||
DelegatedDownloadDescriptor createDelegation(
|
||||
ContentKey key, Optional<ByteRange> range, Duration ttl);
|
||||
}
|
||||
-32
@@ -1,32 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.content;
|
||||
|
||||
import java.util.Objects;
|
||||
import java.util.Optional;
|
||||
import java.util.OptionalLong;
|
||||
|
||||
/**
|
||||
* Conditions a physical delete must satisfy before it runs.
|
||||
*
|
||||
* <p>Cleanup never deletes an object whose observed size or digest disagrees with the record that
|
||||
* scheduled the deletion.
|
||||
*/
|
||||
public record DeletePrecondition(OptionalLong expectedSize, Optional<String> expectedSha256) {
|
||||
|
||||
public DeletePrecondition {
|
||||
Objects.requireNonNull(expectedSize, "expectedSize");
|
||||
Objects.requireNonNull(expectedSha256, "expectedSha256");
|
||||
}
|
||||
|
||||
/** Unconditional delete, used only where the caller already proved ownership. */
|
||||
public static DeletePrecondition none() {
|
||||
return new DeletePrecondition(OptionalLong.empty(), Optional.empty());
|
||||
}
|
||||
|
||||
public static DeletePrecondition ofSize(long expectedSize) {
|
||||
return new DeletePrecondition(OptionalLong.of(expectedSize), Optional.empty());
|
||||
}
|
||||
|
||||
public static DeletePrecondition ofSizeAndDigest(long expectedSize, String expectedSha256) {
|
||||
return new DeletePrecondition(OptionalLong.of(expectedSize), Optional.of(expectedSha256));
|
||||
}
|
||||
}
|
||||
-24
@@ -1,24 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.content;
|
||||
|
||||
/**
|
||||
* Outcome of a physical delete.
|
||||
*
|
||||
* <p>A delete of an object that is already gone is an idempotent success, but it is reported with
|
||||
* {@code alreadyAbsent} so reconciliation can record the divergence.
|
||||
*/
|
||||
public record DeleteResult(boolean deleted, boolean alreadyAbsent, long reclaimedBytes) {
|
||||
|
||||
public DeleteResult {
|
||||
if (reclaimedBytes < 0) {
|
||||
throw new IllegalArgumentException("reclaimedBytes must not be negative");
|
||||
}
|
||||
}
|
||||
|
||||
public static DeleteResult removed(long reclaimedBytes) {
|
||||
return new DeleteResult(true, false, reclaimedBytes);
|
||||
}
|
||||
|
||||
public static DeleteResult alreadyGone() {
|
||||
return new DeleteResult(true, true, 0);
|
||||
}
|
||||
}
|
||||
-24
@@ -1,24 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.content;
|
||||
|
||||
import java.util.Objects;
|
||||
import java.util.Optional;
|
||||
import java.util.OptionalLong;
|
||||
|
||||
/**
|
||||
* Request to turn a completed staging object into immutable published content.
|
||||
*
|
||||
* <p>{@code expectedSha256} is the digest the server computed while streaming, not a client
|
||||
* assertion. The store re-verifies length and digest before it exposes anything.
|
||||
*/
|
||||
public record FinalizeContentCommand(
|
||||
OptionalLong expectedLength,
|
||||
Optional<String> expectedSha256,
|
||||
PublishMode publishMode,
|
||||
boolean forceDurable) {
|
||||
|
||||
public FinalizeContentCommand {
|
||||
Objects.requireNonNull(expectedLength, "expectedLength");
|
||||
Objects.requireNonNull(expectedSha256, "expectedSha256");
|
||||
Objects.requireNonNull(publishMode, "publishMode");
|
||||
}
|
||||
}
|
||||
-14
@@ -1,14 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.content;
|
||||
|
||||
/**
|
||||
* How a completed upload becomes publicly visible.
|
||||
*
|
||||
* <p>{@link #ATOMIC_MOVE_PREFERRED} is the default: use a same-FileStore atomic move when the probe
|
||||
* proves it works, otherwise fall back to publishing a metadata pointer to an already-complete
|
||||
* immutable object.
|
||||
*/
|
||||
public enum PublishMode {
|
||||
ATOMIC_MOVE_REQUIRED,
|
||||
ATOMIC_MOVE_PREFERRED,
|
||||
METADATA_POINTER
|
||||
}
|
||||
-23
@@ -1,23 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.content;
|
||||
|
||||
/**
|
||||
* Usable and total bytes of a storage pool.
|
||||
*
|
||||
* <p>Neither value identifies a mount point or a physical root.
|
||||
*/
|
||||
public record StorageCapacity(long usableBytes, long totalBytes) {
|
||||
|
||||
public StorageCapacity {
|
||||
if (usableBytes < 0 || totalBytes < 0 || usableBytes > totalBytes) {
|
||||
throw new IllegalArgumentException("invalid storage capacity");
|
||||
}
|
||||
}
|
||||
|
||||
/** Fraction of the pool already consumed, in the closed interval zero to one. */
|
||||
public double usedFraction() {
|
||||
if (totalBytes == 0) {
|
||||
return 0;
|
||||
}
|
||||
return (double) (totalBytes - usableBytes) / (double) totalBytes;
|
||||
}
|
||||
}
|
||||
-22
@@ -1,22 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.content;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.ContentKey;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* Immutable content that a store has finished publishing.
|
||||
*
|
||||
* <p>Publication here means the physical object is complete and verified; the file becomes publicly
|
||||
* readable only once the metadata store commits the READY transition.
|
||||
*/
|
||||
public record StoredContent(
|
||||
ContentKey contentKey, long size, String sha256, boolean atomicMoveUsed) {
|
||||
|
||||
public StoredContent {
|
||||
Objects.requireNonNull(contentKey, "contentKey");
|
||||
Objects.requireNonNull(sha256, "sha256");
|
||||
if (size < 0) {
|
||||
throw new IllegalArgumentException("size must not be negative");
|
||||
}
|
||||
}
|
||||
}
|
||||
-34
@@ -1,34 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.content;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.StorageNamespace;
|
||||
import dev.caskeleton.application.fileserver.api.UploadId;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* Opaque handle to an in-progress staging object held by a content store.
|
||||
*
|
||||
* <p>The handle never exposes a path. Adapters that need physical detail keep it in their own
|
||||
* package-private subtype and downcast internally.
|
||||
*/
|
||||
public interface UploadHandle {
|
||||
|
||||
UploadId uploadId();
|
||||
|
||||
StorageNamespace namespace();
|
||||
|
||||
/**
|
||||
* Store-specific opaque token that lets the same store re-attach to the staging object after a
|
||||
* restart. It is never returned to a client.
|
||||
*/
|
||||
String stagingToken();
|
||||
|
||||
/** Throws when {@code handle} was produced by a different content store implementation. */
|
||||
static <T extends UploadHandle> T requireOwn(UploadHandle handle, Class<T> ownType) {
|
||||
Objects.requireNonNull(handle, "handle");
|
||||
if (!ownType.isInstance(handle)) {
|
||||
throw new IllegalArgumentException(
|
||||
"upload handle was not produced by " + ownType.getSimpleName());
|
||||
}
|
||||
return ownType.cast(handle);
|
||||
}
|
||||
}
|
||||
-35
@@ -1,35 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.content;
|
||||
|
||||
/**
|
||||
* Permission to keep writing, re-checked while a transfer is still in flight.
|
||||
*
|
||||
* <p>An upload holds a writer lease that is granted once and expires on a timer, but the transfer
|
||||
* it authorizes can run for minutes. Checking ownership only at the start leaves the interval where
|
||||
* a slow writer's lease lapses, another node takes it over, and both are appending to the same
|
||||
* staging object — with the loser's bytes landing at offsets the winner never accounted for.
|
||||
*
|
||||
* <p>The store therefore re-asks between buffers rather than trusting the initial grant. A refusal
|
||||
* aborts the transfer before the next write, and the store's own rollback returns the object to the
|
||||
* offset the append started from, so a fenced-out writer leaves no trace on the volume.
|
||||
*/
|
||||
@FunctionalInterface
|
||||
public interface WriteFence {
|
||||
|
||||
/**
|
||||
* Confirms this writer may still mutate the physical object.
|
||||
*
|
||||
* @throws dev.caskeleton.application.fileserver.api.error.FileserverException when ownership was
|
||||
* lost; the caller must not write again
|
||||
*/
|
||||
void requireStillOwned();
|
||||
|
||||
/**
|
||||
* A fence that never refuses.
|
||||
*
|
||||
* <p>For call sites with no ownership to lose — a contract test driving the store directly, or a
|
||||
* copy between two objects only this thread can reach.
|
||||
*/
|
||||
static WriteFence unfenced() {
|
||||
return () -> {};
|
||||
}
|
||||
}
|
||||
-41
@@ -1,41 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.error;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.FileId;
|
||||
import dev.caskeleton.application.fileserver.api.UploadId;
|
||||
|
||||
/**
|
||||
* The operation may or may not have taken effect and the server cannot decide which.
|
||||
*
|
||||
* <p>Typical causes are a lost rename response on a network filesystem, a vanished mount after a
|
||||
* successful force, and a missing database commit acknowledgement. This failure is never downgraded
|
||||
* to a retryable error and never blind-retried: it always carries {@code reconciliationRequired}.
|
||||
*/
|
||||
public final class AmbiguousCompletionException extends FileserverException {
|
||||
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
public AmbiguousCompletionException(String message, FileserverFailureContext context) {
|
||||
super(message, context);
|
||||
}
|
||||
|
||||
public AmbiguousCompletionException(
|
||||
String message, Throwable cause, FileserverFailureContext context) {
|
||||
super(message, cause, context);
|
||||
}
|
||||
|
||||
/** Ambiguous outcome for an upload resource. */
|
||||
public static AmbiguousCompletionException forUpload(String message, UploadId uploadId) {
|
||||
return new AmbiguousCompletionException(
|
||||
message,
|
||||
FileserverFailureContext.forUpload(
|
||||
FileserverErrorCode.AMBIGUOUS_COMPLETION, uploadId, false, true, true));
|
||||
}
|
||||
|
||||
/** Ambiguous outcome for a file record, typically a publish or metadata commit. */
|
||||
public static AmbiguousCompletionException forFile(String message, FileId fileId) {
|
||||
return new AmbiguousCompletionException(
|
||||
message,
|
||||
FileserverFailureContext.forFile(FileserverErrorCode.AMBIGUOUS_COMPLETION, fileId, false)
|
||||
.ambiguousRequiringReconciliation());
|
||||
}
|
||||
}
|
||||
-23
@@ -1,23 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.error;
|
||||
|
||||
/** Atomic publish was required by configuration but the storage probe proved it unavailable. */
|
||||
public final class AtomicPublishUnsupportedException extends FileserverException {
|
||||
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
public AtomicPublishUnsupportedException(String message, FileserverFailureContext context) {
|
||||
super(message, context);
|
||||
}
|
||||
|
||||
public AtomicPublishUnsupportedException(
|
||||
String message, Throwable cause, FileserverFailureContext context) {
|
||||
super(message, cause, context);
|
||||
}
|
||||
|
||||
/** Failure with no file or upload correlation. */
|
||||
public static AtomicPublishUnsupportedException of(String message) {
|
||||
return new AtomicPublishUnsupportedException(
|
||||
message,
|
||||
FileserverFailureContext.of(FileserverErrorCode.ATOMIC_PUBLISH_UNSUPPORTED, false));
|
||||
}
|
||||
}
|
||||
-22
@@ -1,22 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.error;
|
||||
|
||||
/** An optimistic version or writer-lease precondition lost to a concurrent writer. */
|
||||
public final class ConcurrentFileModificationException extends FileserverException {
|
||||
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
public ConcurrentFileModificationException(String message, FileserverFailureContext context) {
|
||||
super(message, context);
|
||||
}
|
||||
|
||||
public ConcurrentFileModificationException(
|
||||
String message, Throwable cause, FileserverFailureContext context) {
|
||||
super(message, cause, context);
|
||||
}
|
||||
|
||||
/** Failure with no file or upload correlation. */
|
||||
public static ConcurrentFileModificationException of(String message) {
|
||||
return new ConcurrentFileModificationException(
|
||||
message, FileserverFailureContext.of(FileserverErrorCode.CONCURRENT_MODIFICATION, true));
|
||||
}
|
||||
}
|
||||
-22
@@ -1,22 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.error;
|
||||
|
||||
/** The injected access policy denied the operation before any quota or storage mutation. */
|
||||
public final class FileAccessDeniedException extends FileserverException {
|
||||
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
public FileAccessDeniedException(String message, FileserverFailureContext context) {
|
||||
super(message, context);
|
||||
}
|
||||
|
||||
public FileAccessDeniedException(
|
||||
String message, Throwable cause, FileserverFailureContext context) {
|
||||
super(message, cause, context);
|
||||
}
|
||||
|
||||
/** Failure with no file or upload correlation. */
|
||||
public static FileAccessDeniedException of(String message) {
|
||||
return new FileAccessDeniedException(
|
||||
message, FileserverFailureContext.of(FileserverErrorCode.ACCESS_DENIED, false));
|
||||
}
|
||||
}
|
||||
-22
@@ -1,22 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.error;
|
||||
|
||||
/** Create-only target already exists; the server never silently overwrites. */
|
||||
public final class FileAlreadyExistsException extends FileserverException {
|
||||
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
public FileAlreadyExistsException(String message, FileserverFailureContext context) {
|
||||
super(message, context);
|
||||
}
|
||||
|
||||
public FileAlreadyExistsException(
|
||||
String message, Throwable cause, FileserverFailureContext context) {
|
||||
super(message, cause, context);
|
||||
}
|
||||
|
||||
/** Failure with no file or upload correlation. */
|
||||
public static FileAlreadyExistsException of(String message) {
|
||||
return new FileAlreadyExistsException(
|
||||
message, FileserverFailureContext.of(FileserverErrorCode.FILE_ALREADY_EXISTS, false));
|
||||
}
|
||||
}
|
||||
-24
@@ -1,24 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.error;
|
||||
|
||||
/**
|
||||
* Requested file identity does not exist, or existence hiding decided the caller may not learn that
|
||||
* it does.
|
||||
*/
|
||||
public final class FileNotFoundException extends FileserverException {
|
||||
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
public FileNotFoundException(String message, FileserverFailureContext context) {
|
||||
super(message, context);
|
||||
}
|
||||
|
||||
public FileNotFoundException(String message, Throwable cause, FileserverFailureContext context) {
|
||||
super(message, cause, context);
|
||||
}
|
||||
|
||||
/** Failure with no file or upload correlation. */
|
||||
public static FileNotFoundException of(String message) {
|
||||
return new FileNotFoundException(
|
||||
message, FileserverFailureContext.of(FileserverErrorCode.FILE_NOT_FOUND, false));
|
||||
}
|
||||
}
|
||||
-27
@@ -1,27 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.error;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.FileId;
|
||||
import dev.caskeleton.application.fileserver.api.FileState;
|
||||
|
||||
/**
|
||||
* The file exists but is not in {@link FileState#READY}, so no byte may be served.
|
||||
*
|
||||
* <p>This gate is evaluated before any content handle is opened and applies identically to direct
|
||||
* transfer and to delegated (Nginx) transfer.
|
||||
*/
|
||||
public final class FileNotReadyException extends FileserverException {
|
||||
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
public FileNotReadyException(String message, FileserverFailureContext context) {
|
||||
super(message, context);
|
||||
}
|
||||
|
||||
/** Gate failure carrying the observed non-READY state. */
|
||||
public static FileNotReadyException of(FileId fileId, FileState currentState) {
|
||||
return new FileNotReadyException(
|
||||
"file is not readable in state " + currentState,
|
||||
FileserverFailureContext.forFileState(
|
||||
FileserverErrorCode.FILE_NOT_READY, fileId, currentState, false));
|
||||
}
|
||||
}
|
||||
-21
@@ -1,21 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.error;
|
||||
|
||||
/** The declared or streamed byte count exceeded the configured maximum. */
|
||||
public final class FileTooLargeException extends FileserverException {
|
||||
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
public FileTooLargeException(String message, FileserverFailureContext context) {
|
||||
super(message, context);
|
||||
}
|
||||
|
||||
public FileTooLargeException(String message, Throwable cause, FileserverFailureContext context) {
|
||||
super(message, cause, context);
|
||||
}
|
||||
|
||||
/** Failure with no file or upload correlation. */
|
||||
public static FileTooLargeException of(String message) {
|
||||
return new FileTooLargeException(
|
||||
message, FileserverFailureContext.of(FileserverErrorCode.FILE_TOO_LARGE, false));
|
||||
}
|
||||
}
|
||||
-98
@@ -1,98 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.error;
|
||||
|
||||
import dev.caskeleton.shared.error.ApiErrorCode;
|
||||
import dev.caskeleton.shared.error.Category;
|
||||
import java.util.Locale;
|
||||
|
||||
/**
|
||||
* Stable Fileserver failure vocabulary shared by every transport adapter.
|
||||
*
|
||||
* <p>Implements the repository-wide {@link ApiErrorCode} contract rather than parallelling it. The
|
||||
* enum already carried a status and a retryability notion of its own, in its own shape, so a caller
|
||||
* that handles {@code ApiErrorCode} uniformly — the envelope writer, the error registry contract
|
||||
* tests, a fork's own handler — silently did not cover Fileserver failures. Same information,
|
||||
* inside the contract instead of beside it.
|
||||
*
|
||||
* <p>The status stays here, on the code, for the reason {@link ApiErrorCode} gives: it is a plain
|
||||
* integer, never a framework status type, so the module holding it stays framework-neutral and the
|
||||
* servlet transport, the reactive transport and the Nginx delegation path cannot answer the same
|
||||
* failure three different ways.
|
||||
*
|
||||
* <p>The URN is the {@code type} member of the emitted problem detail and has no counterpart in the
|
||||
* shared contract, so it remains Fileserver-specific.
|
||||
*/
|
||||
public enum FileserverErrorCode implements ApiErrorCode {
|
||||
BAD_REQUEST(400, Category.VALIDATION, false),
|
||||
UNAUTHENTICATED(401, Category.AUTH, false),
|
||||
ACCESS_DENIED(403, Category.AUTHZ, false),
|
||||
FILE_NOT_FOUND(404, Category.NOT_FOUND, false),
|
||||
FILE_ALREADY_EXISTS(409, Category.CONFLICT, false),
|
||||
FILE_NOT_READY(409, Category.CONFLICT, true),
|
||||
UPLOAD_OFFSET_MISMATCH(409, Category.CONFLICT, true),
|
||||
CONCURRENT_MODIFICATION(409, Category.CONFLICT, true),
|
||||
UPLOAD_EXPIRED(410, Category.CONFLICT, false),
|
||||
CONTENT_LENGTH_REQUIRED(411, Category.VALIDATION, false),
|
||||
PRECONDITION_FAILED(412, Category.CONFLICT, false),
|
||||
FILE_TOO_LARGE(413, Category.VALIDATION, false),
|
||||
QUOTA_EXCEEDED(413, Category.CONFLICT, false),
|
||||
UNSUPPORTED_MEDIA_TYPE(415, Category.VALIDATION, false),
|
||||
RANGE_NOT_SATISFIABLE(416, Category.VALIDATION, false),
|
||||
INTEGRITY_MISMATCH(422, Category.DATA_INTEGRITY, false),
|
||||
MALWARE_DETECTED(422, Category.DATA_INTEGRITY, false),
|
||||
INVALID_PATH(422, Category.VALIDATION, false),
|
||||
PATH_OUTSIDE_NAMESPACE(422, Category.VALIDATION, false),
|
||||
TRANSFER_ADMISSION_REJECTED(429, Category.RATE_LIMIT, true),
|
||||
PARTIAL_WRITE(500, Category.TRANSIENT_DEPENDENCY, false),
|
||||
// Never retryable by definition: the operation may already have taken effect, and a blind retry
|
||||
// is what turns an ambiguous outcome into a duplicated one.
|
||||
AMBIGUOUS_COMPLETION(500, Category.DATA_INTEGRITY, false),
|
||||
ATOMIC_PUBLISH_UNSUPPORTED(503, Category.PERMANENT_DEPENDENCY, false),
|
||||
STORAGE_UNAVAILABLE(503, Category.TRANSIENT_DEPENDENCY, true),
|
||||
TRANSFER_TIMEOUT(504, Category.TRANSIENT_DEPENDENCY, true),
|
||||
STORAGE_FULL(507, Category.TRANSIENT_DEPENDENCY, false);
|
||||
|
||||
private static final String PROBLEM_TYPE_PREFIX = "urn:fileserver:problem:";
|
||||
|
||||
private final int httpStatus;
|
||||
private final Category category;
|
||||
private final boolean retryable;
|
||||
|
||||
FileserverErrorCode(int httpStatus, Category category, boolean retryable) {
|
||||
this.httpStatus = httpStatus;
|
||||
this.category = category;
|
||||
this.retryable = retryable;
|
||||
}
|
||||
|
||||
@Override
|
||||
public String code() {
|
||||
return name();
|
||||
}
|
||||
|
||||
@Override
|
||||
public Category category() {
|
||||
return category;
|
||||
}
|
||||
|
||||
/** Design §19.3 status for this failure; identical across MVC, WebFlux, and Nginx delegation. */
|
||||
@Override
|
||||
public int httpStatus() {
|
||||
return httpStatus;
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether the same call may succeed on retry, as a property of the code.
|
||||
*
|
||||
* <p>Distinct from {@link FileserverFailureContext#retryable()}, which is what the server decided
|
||||
* about one particular occurrence. This is the ceiling: a code that is never retryable cannot be
|
||||
* made retryable by a context, and a client that only sees the code still gets a safe answer.
|
||||
*/
|
||||
@Override
|
||||
public boolean retryable() {
|
||||
return retryable;
|
||||
}
|
||||
|
||||
/** Problem-detail {@code type} URN, for example {@code urn:fileserver:problem:file-not-found}. */
|
||||
public String problemType() {
|
||||
return PROBLEM_TYPE_PREFIX + name().toLowerCase(Locale.ROOT).replace('_', '-');
|
||||
}
|
||||
}
|
||||
-35
@@ -1,35 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.error;
|
||||
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* Root of the stable Fileserver failure hierarchy.
|
||||
*
|
||||
* <p>Transport adapters map these failures through {@link #context()} alone; they never inspect a
|
||||
* storage-driver or JDBC exception. {@link #getMessage()} is server-log-only and must never be
|
||||
* copied into a client response body.
|
||||
*/
|
||||
public abstract class FileserverException extends RuntimeException {
|
||||
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
private final transient FileserverFailureContext context;
|
||||
|
||||
protected FileserverException(String message, FileserverFailureContext context) {
|
||||
super(message);
|
||||
this.context = Objects.requireNonNull(context, "context");
|
||||
}
|
||||
|
||||
protected FileserverException(String message, Throwable cause, FileserverFailureContext context) {
|
||||
super(message, cause);
|
||||
this.context = Objects.requireNonNull(context, "context");
|
||||
}
|
||||
|
||||
public final FileserverFailureContext context() {
|
||||
return context;
|
||||
}
|
||||
|
||||
public final FileserverErrorCode code() {
|
||||
return context.code();
|
||||
}
|
||||
}
|
||||
-152
@@ -1,152 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.error;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.FileId;
|
||||
import dev.caskeleton.application.fileserver.api.FileState;
|
||||
import dev.caskeleton.application.fileserver.api.UploadId;
|
||||
import java.util.Objects;
|
||||
import java.util.Optional;
|
||||
import java.util.OptionalLong;
|
||||
|
||||
/**
|
||||
* Machine-readable failure metadata attached to every {@link FileserverException}.
|
||||
*
|
||||
* <p>{@code ambiguous} means the operation may have taken effect on the storage or metadata side
|
||||
* even though no success was observed; such a failure is never downgraded to a plain retryable
|
||||
* error. The context never carries a physical path, a mount, a scanner credential, or a filename.
|
||||
*/
|
||||
public record FileserverFailureContext(
|
||||
FileserverErrorCode code,
|
||||
boolean retryable,
|
||||
boolean ambiguous,
|
||||
boolean reconciliationRequired,
|
||||
Optional<FileId> fileId,
|
||||
Optional<UploadId> uploadId,
|
||||
OptionalLong expectedOffset,
|
||||
OptionalLong currentOffset,
|
||||
Optional<FileState> currentState) {
|
||||
|
||||
public FileserverFailureContext {
|
||||
Objects.requireNonNull(code, "code");
|
||||
Objects.requireNonNull(fileId, "fileId");
|
||||
Objects.requireNonNull(uploadId, "uploadId");
|
||||
Objects.requireNonNull(expectedOffset, "expectedOffset");
|
||||
Objects.requireNonNull(currentOffset, "currentOffset");
|
||||
Objects.requireNonNull(currentState, "currentState");
|
||||
}
|
||||
|
||||
/** Failure with no file, upload, or offset correlation. */
|
||||
public static FileserverFailureContext of(FileserverErrorCode code, boolean retryable) {
|
||||
return new FileserverFailureContext(
|
||||
code,
|
||||
retryable,
|
||||
false,
|
||||
false,
|
||||
Optional.empty(),
|
||||
Optional.empty(),
|
||||
OptionalLong.empty(),
|
||||
OptionalLong.empty(),
|
||||
Optional.empty());
|
||||
}
|
||||
|
||||
/** Failure correlated to a file, optionally reporting the observed state. */
|
||||
public static FileserverFailureContext forFile(
|
||||
FileserverErrorCode code, FileId fileId, boolean retryable) {
|
||||
return new FileserverFailureContext(
|
||||
code,
|
||||
retryable,
|
||||
false,
|
||||
false,
|
||||
Optional.of(fileId),
|
||||
Optional.empty(),
|
||||
OptionalLong.empty(),
|
||||
OptionalLong.empty(),
|
||||
Optional.empty());
|
||||
}
|
||||
|
||||
/** Failure correlated to a file whose observed lifecycle state matters to the caller. */
|
||||
public static FileserverFailureContext forFileState(
|
||||
FileserverErrorCode code, FileId fileId, FileState currentState, boolean retryable) {
|
||||
return new FileserverFailureContext(
|
||||
code,
|
||||
retryable,
|
||||
false,
|
||||
false,
|
||||
Optional.of(fileId),
|
||||
Optional.empty(),
|
||||
OptionalLong.empty(),
|
||||
OptionalLong.empty(),
|
||||
Optional.of(currentState));
|
||||
}
|
||||
|
||||
/** Failure correlated to an upload resource, including the ambiguity and reconciliation flags. */
|
||||
public static FileserverFailureContext forUpload(
|
||||
FileserverErrorCode code,
|
||||
UploadId uploadId,
|
||||
boolean retryable,
|
||||
boolean ambiguous,
|
||||
boolean reconciliationRequired) {
|
||||
return new FileserverFailureContext(
|
||||
code,
|
||||
retryable,
|
||||
ambiguous,
|
||||
reconciliationRequired,
|
||||
Optional.empty(),
|
||||
Optional.of(uploadId),
|
||||
OptionalLong.empty(),
|
||||
OptionalLong.empty(),
|
||||
Optional.empty());
|
||||
}
|
||||
|
||||
/** Offset conflict reporting both the expected and the durably committed offset. */
|
||||
public static FileserverFailureContext forOffset(
|
||||
FileserverErrorCode code, long expectedOffset, long currentOffset) {
|
||||
return new FileserverFailureContext(
|
||||
code,
|
||||
true,
|
||||
false,
|
||||
false,
|
||||
Optional.empty(),
|
||||
Optional.empty(),
|
||||
OptionalLong.of(expectedOffset),
|
||||
OptionalLong.of(currentOffset),
|
||||
Optional.empty());
|
||||
}
|
||||
|
||||
/** Same context with the upload correlation filled in. */
|
||||
public FileserverFailureContext withUpload(UploadId uploadId) {
|
||||
return new FileserverFailureContext(
|
||||
code,
|
||||
retryable,
|
||||
ambiguous,
|
||||
reconciliationRequired,
|
||||
fileId,
|
||||
Optional.of(uploadId),
|
||||
expectedOffset,
|
||||
currentOffset,
|
||||
currentState);
|
||||
}
|
||||
|
||||
/**
|
||||
* Same context re-marked as an ambiguous outcome that must go through reconciliation.
|
||||
*
|
||||
* <p>An ambiguous failure is never retryable: the operation may already have taken effect.
|
||||
*/
|
||||
public FileserverFailureContext ambiguousRequiringReconciliation() {
|
||||
return new FileserverFailureContext(
|
||||
code, false, true, true, fileId, uploadId, expectedOffset, currentOffset, currentState);
|
||||
}
|
||||
|
||||
/** Same context with the file correlation filled in. */
|
||||
public FileserverFailureContext withFile(FileId fileId) {
|
||||
return new FileserverFailureContext(
|
||||
code,
|
||||
retryable,
|
||||
ambiguous,
|
||||
reconciliationRequired,
|
||||
Optional.of(fileId),
|
||||
uploadId,
|
||||
expectedOffset,
|
||||
currentOffset,
|
||||
currentState);
|
||||
}
|
||||
}
|
||||
-22
@@ -1,22 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.error;
|
||||
|
||||
/** The server-computed size or SHA-256 disagreed with the value the client asserted. */
|
||||
public final class IntegrityMismatchException extends FileserverException {
|
||||
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
public IntegrityMismatchException(String message, FileserverFailureContext context) {
|
||||
super(message, context);
|
||||
}
|
||||
|
||||
public IntegrityMismatchException(
|
||||
String message, Throwable cause, FileserverFailureContext context) {
|
||||
super(message, cause, context);
|
||||
}
|
||||
|
||||
/** Failure with no file or upload correlation. */
|
||||
public static IntegrityMismatchException of(String message) {
|
||||
return new IntegrityMismatchException(
|
||||
message, FileserverFailureContext.of(FileserverErrorCode.INTEGRITY_MISMATCH, false));
|
||||
}
|
||||
}
|
||||
-21
@@ -1,21 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.error;
|
||||
|
||||
/** A server-generated key or internal descriptor failed its structural validation. */
|
||||
public final class InvalidPathException extends FileserverException {
|
||||
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
public InvalidPathException(String message, FileserverFailureContext context) {
|
||||
super(message, context);
|
||||
}
|
||||
|
||||
public InvalidPathException(String message, Throwable cause, FileserverFailureContext context) {
|
||||
super(message, cause, context);
|
||||
}
|
||||
|
||||
/** Failure with no file or upload correlation. */
|
||||
public static InvalidPathException of(String message) {
|
||||
return new InvalidPathException(
|
||||
message, FileserverFailureContext.of(FileserverErrorCode.INVALID_PATH, false));
|
||||
}
|
||||
}
|
||||
-28
@@ -1,28 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.error;
|
||||
|
||||
/**
|
||||
* A request's headers or their combination are not valid for the operation.
|
||||
*
|
||||
* <p>This is separate from {@link UnsupportedMediaTypeException} on purpose: a missing protocol
|
||||
* version and an unsupported content type are different failures, and collapsing them would make
|
||||
* the emitted code disagree with the exception a reader sees in a stack trace.
|
||||
*/
|
||||
public final class MalformedRequestException extends FileserverException {
|
||||
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
public MalformedRequestException(String message, FileserverFailureContext context) {
|
||||
super(message, context);
|
||||
}
|
||||
|
||||
public MalformedRequestException(
|
||||
String message, Throwable cause, FileserverFailureContext context) {
|
||||
super(message, cause, context);
|
||||
}
|
||||
|
||||
/** Failure with no file or upload correlation. */
|
||||
public static MalformedRequestException of(String message) {
|
||||
return new MalformedRequestException(
|
||||
message, FileserverFailureContext.of(FileserverErrorCode.BAD_REQUEST, false));
|
||||
}
|
||||
}
|
||||
-22
@@ -1,22 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.error;
|
||||
|
||||
/** A malware or content-disarm verifier returned a reject verdict; content is never published. */
|
||||
public final class MalwareDetectedException extends FileserverException {
|
||||
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
public MalwareDetectedException(String message, FileserverFailureContext context) {
|
||||
super(message, context);
|
||||
}
|
||||
|
||||
public MalwareDetectedException(
|
||||
String message, Throwable cause, FileserverFailureContext context) {
|
||||
super(message, cause, context);
|
||||
}
|
||||
|
||||
/** Failure with no file or upload correlation. */
|
||||
public static MalwareDetectedException of(String message) {
|
||||
return new MalwareDetectedException(
|
||||
message, FileserverFailureContext.of(FileserverErrorCode.MALWARE_DETECTED, false));
|
||||
}
|
||||
}
|
||||
-21
@@ -1,21 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.error;
|
||||
|
||||
/** Fewer bytes than promised reached durable storage; the session stays recoverable. */
|
||||
public final class PartialWriteException extends FileserverException {
|
||||
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
public PartialWriteException(String message, FileserverFailureContext context) {
|
||||
super(message, context);
|
||||
}
|
||||
|
||||
public PartialWriteException(String message, Throwable cause, FileserverFailureContext context) {
|
||||
super(message, cause, context);
|
||||
}
|
||||
|
||||
/** Failure with no file or upload correlation. */
|
||||
public static PartialWriteException of(String message) {
|
||||
return new PartialWriteException(
|
||||
message, FileserverFailureContext.of(FileserverErrorCode.PARTIAL_WRITE, false));
|
||||
}
|
||||
}
|
||||
-22
@@ -1,22 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.error;
|
||||
|
||||
/** A resolved physical location escaped its configured storage root. */
|
||||
public final class PathOutsideNamespaceException extends FileserverException {
|
||||
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
public PathOutsideNamespaceException(String message, FileserverFailureContext context) {
|
||||
super(message, context);
|
||||
}
|
||||
|
||||
public PathOutsideNamespaceException(
|
||||
String message, Throwable cause, FileserverFailureContext context) {
|
||||
super(message, cause, context);
|
||||
}
|
||||
|
||||
/** Failure with no file or upload correlation. */
|
||||
public static PathOutsideNamespaceException of(String message) {
|
||||
return new PathOutsideNamespaceException(
|
||||
message, FileserverFailureContext.of(FileserverErrorCode.PATH_OUTSIDE_NAMESPACE, false));
|
||||
}
|
||||
}
|
||||
-21
@@ -1,21 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.error;
|
||||
|
||||
/** A quota scope reservation, commit, or concurrency limit rejected the request. */
|
||||
public final class QuotaExceededException extends FileserverException {
|
||||
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
public QuotaExceededException(String message, FileserverFailureContext context) {
|
||||
super(message, context);
|
||||
}
|
||||
|
||||
public QuotaExceededException(String message, Throwable cause, FileserverFailureContext context) {
|
||||
super(message, cause, context);
|
||||
}
|
||||
|
||||
/** Failure with no file or upload correlation. */
|
||||
public static QuotaExceededException of(String message) {
|
||||
return new QuotaExceededException(
|
||||
message, FileserverFailureContext.of(FileserverErrorCode.QUOTA_EXCEEDED, false));
|
||||
}
|
||||
}
|
||||
-34
@@ -1,34 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.error;
|
||||
|
||||
/**
|
||||
* No requested byte range intersects the current representation.
|
||||
*
|
||||
* <p>The representation length travels with the failure so the transport can emit the unsatisfiable
|
||||
* {@code Content-Range} form (an asterisk in place of the range, then a slash and the
|
||||
* representation length) without re-reading metadata.
|
||||
*/
|
||||
public final class RangeNotSatisfiableException extends FileserverException {
|
||||
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
private final long representationLength;
|
||||
|
||||
public RangeNotSatisfiableException(
|
||||
String message, long representationLength, FileserverFailureContext context) {
|
||||
super(message, context);
|
||||
this.representationLength = representationLength;
|
||||
}
|
||||
|
||||
/** Unsatisfiable range over a representation of {@code representationLength} bytes. */
|
||||
public static RangeNotSatisfiableException of(long representationLength) {
|
||||
return new RangeNotSatisfiableException(
|
||||
"requested range is not satisfiable",
|
||||
representationLength,
|
||||
FileserverFailureContext.of(FileserverErrorCode.RANGE_NOT_SATISFIABLE, false));
|
||||
}
|
||||
|
||||
/** Length of the representation the range was evaluated against. */
|
||||
public long representationLength() {
|
||||
return representationLength;
|
||||
}
|
||||
}
|
||||
-21
@@ -1,21 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.error;
|
||||
|
||||
/** The storage pool crossed its hard high-water mark or the filesystem reported no space. */
|
||||
public final class StorageFullException extends FileserverException {
|
||||
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
public StorageFullException(String message, FileserverFailureContext context) {
|
||||
super(message, context);
|
||||
}
|
||||
|
||||
public StorageFullException(String message, Throwable cause, FileserverFailureContext context) {
|
||||
super(message, cause, context);
|
||||
}
|
||||
|
||||
/** Failure with no file or upload correlation. */
|
||||
public static StorageFullException of(String message) {
|
||||
return new StorageFullException(
|
||||
message, FileserverFailureContext.of(FileserverErrorCode.STORAGE_FULL, false));
|
||||
}
|
||||
}
|
||||
-22
@@ -1,22 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.error;
|
||||
|
||||
/** The storage backend or a required verifier is temporarily unreachable. */
|
||||
public final class StorageUnavailableException extends FileserverException {
|
||||
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
public StorageUnavailableException(String message, FileserverFailureContext context) {
|
||||
super(message, context);
|
||||
}
|
||||
|
||||
public StorageUnavailableException(
|
||||
String message, Throwable cause, FileserverFailureContext context) {
|
||||
super(message, cause, context);
|
||||
}
|
||||
|
||||
/** Failure with no file or upload correlation. */
|
||||
public static StorageUnavailableException of(String message) {
|
||||
return new StorageUnavailableException(
|
||||
message, FileserverFailureContext.of(FileserverErrorCode.STORAGE_UNAVAILABLE, true));
|
||||
}
|
||||
}
|
||||
-23
@@ -1,23 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.error;
|
||||
|
||||
/** Instance or scope transfer permits were exhausted; the caller may retry after backoff. */
|
||||
public final class TransferAdmissionRejectedException extends FileserverException {
|
||||
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
public TransferAdmissionRejectedException(String message, FileserverFailureContext context) {
|
||||
super(message, context);
|
||||
}
|
||||
|
||||
public TransferAdmissionRejectedException(
|
||||
String message, Throwable cause, FileserverFailureContext context) {
|
||||
super(message, cause, context);
|
||||
}
|
||||
|
||||
/** Failure with no file or upload correlation. */
|
||||
public static TransferAdmissionRejectedException of(String message) {
|
||||
return new TransferAdmissionRejectedException(
|
||||
message,
|
||||
FileserverFailureContext.of(FileserverErrorCode.TRANSFER_ADMISSION_REJECTED, true));
|
||||
}
|
||||
}
|
||||
-22
@@ -1,22 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.error;
|
||||
|
||||
/** A downstream transfer exceeded its idle or total timeout budget. */
|
||||
public final class TransferTimeoutException extends FileserverException {
|
||||
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
public TransferTimeoutException(String message, FileserverFailureContext context) {
|
||||
super(message, context);
|
||||
}
|
||||
|
||||
public TransferTimeoutException(
|
||||
String message, Throwable cause, FileserverFailureContext context) {
|
||||
super(message, cause, context);
|
||||
}
|
||||
|
||||
/** Failure with no file or upload correlation. */
|
||||
public static TransferTimeoutException of(String message) {
|
||||
return new TransferTimeoutException(
|
||||
message, FileserverFailureContext.of(FileserverErrorCode.TRANSFER_TIMEOUT, true));
|
||||
}
|
||||
}
|
||||
-22
@@ -1,22 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.error;
|
||||
|
||||
/** The upload media type is outside the configured allowlist. */
|
||||
public final class UnsupportedMediaTypeException extends FileserverException {
|
||||
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
public UnsupportedMediaTypeException(String message, FileserverFailureContext context) {
|
||||
super(message, context);
|
||||
}
|
||||
|
||||
public UnsupportedMediaTypeException(
|
||||
String message, Throwable cause, FileserverFailureContext context) {
|
||||
super(message, cause, context);
|
||||
}
|
||||
|
||||
/** Failure with no file or upload correlation. */
|
||||
public static UnsupportedMediaTypeException of(String message) {
|
||||
return new UnsupportedMediaTypeException(
|
||||
message, FileserverFailureContext.of(FileserverErrorCode.UNSUPPORTED_MEDIA_TYPE, false));
|
||||
}
|
||||
}
|
||||
-21
@@ -1,21 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.error;
|
||||
|
||||
/** The upload resource passed its expiry and is no longer appendable. */
|
||||
public final class UploadExpiredException extends FileserverException {
|
||||
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
public UploadExpiredException(String message, FileserverFailureContext context) {
|
||||
super(message, context);
|
||||
}
|
||||
|
||||
public UploadExpiredException(String message, Throwable cause, FileserverFailureContext context) {
|
||||
super(message, cause, context);
|
||||
}
|
||||
|
||||
/** Failure with no file or upload correlation. */
|
||||
public static UploadExpiredException of(String message) {
|
||||
return new UploadExpiredException(
|
||||
message, FileserverFailureContext.of(FileserverErrorCode.UPLOAD_EXPIRED, false));
|
||||
}
|
||||
}
|
||||
-46
@@ -1,46 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.error;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.UploadId;
|
||||
|
||||
/**
|
||||
* The requested append offset disagrees with the durably committed offset.
|
||||
*
|
||||
* <p>The upload resource is never mutated when this is thrown: the client is expected to re-read
|
||||
* the current offset and resume from it.
|
||||
*/
|
||||
public final class UploadOffsetMismatchException extends FileserverException {
|
||||
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
public UploadOffsetMismatchException(String message, FileserverFailureContext context) {
|
||||
super(message, context);
|
||||
}
|
||||
|
||||
/** Mismatch reporting the offset the caller assumed and the offset that is actually durable. */
|
||||
public static UploadOffsetMismatchException of(long expectedOffset, long currentOffset) {
|
||||
return new UploadOffsetMismatchException(
|
||||
"upload offset mismatch: expected " + expectedOffset + " but committed " + currentOffset,
|
||||
FileserverFailureContext.forOffset(
|
||||
FileserverErrorCode.UPLOAD_OFFSET_MISMATCH, expectedOffset, currentOffset));
|
||||
}
|
||||
|
||||
/** Mismatch correlated to the upload resource the client addressed. */
|
||||
public static UploadOffsetMismatchException of(
|
||||
UploadId uploadId, long expectedOffset, long currentOffset) {
|
||||
return new UploadOffsetMismatchException(
|
||||
"upload offset mismatch: expected " + expectedOffset + " but committed " + currentOffset,
|
||||
FileserverFailureContext.forOffset(
|
||||
FileserverErrorCode.UPLOAD_OFFSET_MISMATCH, expectedOffset, currentOffset)
|
||||
.withUpload(uploadId));
|
||||
}
|
||||
|
||||
/** Offset the caller asserted, or {@code -1} when the context carries none. */
|
||||
public long expectedOffset() {
|
||||
return context().expectedOffset().orElse(-1L);
|
||||
}
|
||||
|
||||
/** Offset that is actually durable, or {@code -1} when the context carries none. */
|
||||
public long currentOffset() {
|
||||
return context().currentOffset().orElse(-1L);
|
||||
}
|
||||
}
|
||||
-33
@@ -1,33 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.metadata;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.FileId;
|
||||
import dev.caskeleton.application.fileserver.api.FileState;
|
||||
import dev.caskeleton.application.fileserver.api.StorageNamespace;
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* Public metadata view of a file.
|
||||
*
|
||||
* <p>The descriptor never carries a physical path, a content key, a raw scanner response, or raw
|
||||
* user metadata. {@code originalFilename} is untrusted display data only.
|
||||
*/
|
||||
public record FileDescriptor(
|
||||
FileId fileId,
|
||||
StorageNamespace namespace,
|
||||
FileState state,
|
||||
String originalFilename,
|
||||
String mediaType,
|
||||
long size,
|
||||
String sha256,
|
||||
String strongEtag,
|
||||
Instant publishedAt,
|
||||
long version) {
|
||||
|
||||
public FileDescriptor {
|
||||
Objects.requireNonNull(fileId, "fileId");
|
||||
Objects.requireNonNull(namespace, "namespace");
|
||||
Objects.requireNonNull(state, "state");
|
||||
Objects.requireNonNull(originalFilename, "originalFilename");
|
||||
}
|
||||
}
|
||||
-40
@@ -1,40 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.metadata;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.FileId;
|
||||
import dev.caskeleton.application.fileserver.api.FileState;
|
||||
import dev.caskeleton.application.fileserver.api.StorageNamespace;
|
||||
import java.util.List;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* Authoritative file metadata port.
|
||||
*
|
||||
* <p>Every transition is conditional on both the expected version and the expected state, so two
|
||||
* writers racing on the same record produce exactly one winner and one optimistic conflict.
|
||||
*/
|
||||
public interface FileMetadataStore {
|
||||
|
||||
FileRecord insert(FileRecordDraft draft);
|
||||
|
||||
Optional<FileRecord> find(FileId fileId);
|
||||
|
||||
FileRecord transition(
|
||||
FileId fileId,
|
||||
long expectedVersion,
|
||||
FileState expectedState,
|
||||
FileState targetState,
|
||||
FileRecordMutation mutation);
|
||||
|
||||
FileRecord markDeleting(FileId fileId, long expectedVersion);
|
||||
|
||||
/**
|
||||
* Moves a file to another logical namespace.
|
||||
*
|
||||
* <p>A namespace is a metadata grouping, so this changes one column and never touches the
|
||||
* immutable physical object. Copying gigabytes to express an ownership change would also break
|
||||
* every strong validator already handed to clients.
|
||||
*/
|
||||
FileRecord relocate(FileId fileId, long expectedVersion, StorageNamespace targetNamespace);
|
||||
|
||||
List<FileRecord> findRecoverable(FileRecoveryQuery query);
|
||||
}
|
||||
-20
@@ -1,20 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.metadata;
|
||||
|
||||
import java.time.Duration;
|
||||
|
||||
/**
|
||||
* Reservation-based quota accounting.
|
||||
*
|
||||
* <p>When the client declares no length, the caller reserves a profile-specific initial chunk and
|
||||
* extends it while appending. Every failure path releases the reservation.
|
||||
*/
|
||||
public interface FileQuotaService {
|
||||
|
||||
QuotaReservation reserve(QuotaScope scope, long expectedBytes, Duration ttl);
|
||||
|
||||
void extend(QuotaReservation reservation, long additionalBytes);
|
||||
|
||||
void commit(QuotaReservation reservation, long actualBytes);
|
||||
|
||||
void release(QuotaReservation reservation);
|
||||
}
|
||||
-76
@@ -1,76 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.metadata;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.ContentKey;
|
||||
import dev.caskeleton.application.fileserver.api.FileId;
|
||||
import dev.caskeleton.application.fileserver.api.FileState;
|
||||
import dev.caskeleton.application.fileserver.api.StorageNamespace;
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
import java.util.Optional;
|
||||
import java.util.OptionalLong;
|
||||
|
||||
/**
|
||||
* Authoritative metadata row for one file.
|
||||
*
|
||||
* <p>The relational record — not the filesystem — decides whether a file is publicly readable.
|
||||
* {@code version} backs every optimistic transition.
|
||||
*/
|
||||
public record FileRecord(
|
||||
FileId fileId,
|
||||
StorageNamespace namespace,
|
||||
FileState state,
|
||||
Optional<ContentKey> contentKey,
|
||||
String originalName,
|
||||
Optional<String> claimedMediaType,
|
||||
Optional<String> verifiedMediaType,
|
||||
OptionalLong expectedSize,
|
||||
OptionalLong actualSize,
|
||||
Optional<String> sha256,
|
||||
Optional<String> strongEtag,
|
||||
Optional<Instant> publishedAt,
|
||||
Optional<String> lastErrorCode,
|
||||
long version,
|
||||
Instant createdAt,
|
||||
Instant updatedAt) {
|
||||
|
||||
public FileRecord {
|
||||
Objects.requireNonNull(fileId, "fileId");
|
||||
Objects.requireNonNull(namespace, "namespace");
|
||||
Objects.requireNonNull(state, "state");
|
||||
Objects.requireNonNull(contentKey, "contentKey");
|
||||
Objects.requireNonNull(originalName, "originalName");
|
||||
Objects.requireNonNull(claimedMediaType, "claimedMediaType");
|
||||
Objects.requireNonNull(verifiedMediaType, "verifiedMediaType");
|
||||
Objects.requireNonNull(expectedSize, "expectedSize");
|
||||
Objects.requireNonNull(actualSize, "actualSize");
|
||||
Objects.requireNonNull(sha256, "sha256");
|
||||
Objects.requireNonNull(strongEtag, "strongEtag");
|
||||
Objects.requireNonNull(publishedAt, "publishedAt");
|
||||
Objects.requireNonNull(lastErrorCode, "lastErrorCode");
|
||||
Objects.requireNonNull(createdAt, "createdAt");
|
||||
Objects.requireNonNull(updatedAt, "updatedAt");
|
||||
if (version < 0) {
|
||||
throw new IllegalArgumentException("version must not be negative");
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Projects the public descriptor.
|
||||
*
|
||||
* <p>The verified media type wins over the claimed one, and an unpublished record reports the
|
||||
* neutral {@code application/octet-stream} rather than echoing the client assertion as fact.
|
||||
*/
|
||||
public FileDescriptor toDescriptor() {
|
||||
return new FileDescriptor(
|
||||
fileId,
|
||||
namespace,
|
||||
state,
|
||||
originalName,
|
||||
verifiedMediaType.orElse("application/octet-stream"),
|
||||
actualSize.orElse(0L),
|
||||
sha256.orElse(""),
|
||||
strongEtag.orElse(""),
|
||||
publishedAt.orElse(null),
|
||||
version);
|
||||
}
|
||||
}
|
||||
-29
@@ -1,29 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.metadata;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.FileId;
|
||||
import dev.caskeleton.application.fileserver.api.StorageNamespace;
|
||||
import java.util.Objects;
|
||||
import java.util.Optional;
|
||||
import java.util.OptionalLong;
|
||||
|
||||
/**
|
||||
* Insert payload for a new file record in {@code CREATED}.
|
||||
*
|
||||
* <p>{@code originalName} is already sanitized display text and {@code claimedMediaType} is the
|
||||
* untrusted client assertion; neither is used to build a physical key.
|
||||
*/
|
||||
public record FileRecordDraft(
|
||||
FileId fileId,
|
||||
StorageNamespace namespace,
|
||||
String originalName,
|
||||
Optional<String> claimedMediaType,
|
||||
OptionalLong expectedSize) {
|
||||
|
||||
public FileRecordDraft {
|
||||
Objects.requireNonNull(fileId, "fileId");
|
||||
Objects.requireNonNull(namespace, "namespace");
|
||||
Objects.requireNonNull(originalName, "originalName");
|
||||
Objects.requireNonNull(claimedMediaType, "claimedMediaType");
|
||||
Objects.requireNonNull(expectedSize, "expectedSize");
|
||||
}
|
||||
}
|
||||
-126
@@ -1,126 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.metadata;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.ContentKey;
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
import java.util.Optional;
|
||||
import java.util.OptionalLong;
|
||||
|
||||
/**
|
||||
* Field changes applied atomically with a state transition.
|
||||
*
|
||||
* <p>Only fields explicitly present are written, so a transition can never clear a published digest
|
||||
* or content key by omission.
|
||||
*/
|
||||
public record FileRecordMutation(
|
||||
Optional<ContentKey> contentKey,
|
||||
OptionalLong actualSize,
|
||||
Optional<String> sha256,
|
||||
Optional<String> strongEtag,
|
||||
Optional<String> verifiedMediaType,
|
||||
Optional<Instant> publishedAt,
|
||||
Optional<String> lastErrorCode) {
|
||||
|
||||
public FileRecordMutation {
|
||||
Objects.requireNonNull(contentKey, "contentKey");
|
||||
Objects.requireNonNull(actualSize, "actualSize");
|
||||
Objects.requireNonNull(sha256, "sha256");
|
||||
Objects.requireNonNull(strongEtag, "strongEtag");
|
||||
Objects.requireNonNull(verifiedMediaType, "verifiedMediaType");
|
||||
Objects.requireNonNull(publishedAt, "publishedAt");
|
||||
Objects.requireNonNull(lastErrorCode, "lastErrorCode");
|
||||
}
|
||||
|
||||
/** Transition that changes state only. */
|
||||
public static FileRecordMutation none() {
|
||||
return new FileRecordMutation(
|
||||
Optional.empty(),
|
||||
OptionalLong.empty(),
|
||||
Optional.empty(),
|
||||
Optional.empty(),
|
||||
Optional.empty(),
|
||||
Optional.empty(),
|
||||
Optional.empty());
|
||||
}
|
||||
|
||||
/** Publish mutation written together with the READY transition. */
|
||||
public static FileRecordMutation publish(
|
||||
ContentKey contentKey, long actualSize, String sha256, String strongEtag) {
|
||||
return new FileRecordMutation(
|
||||
Optional.of(contentKey),
|
||||
OptionalLong.of(actualSize),
|
||||
Optional.of(sha256),
|
||||
Optional.of(strongEtag),
|
||||
Optional.empty(),
|
||||
Optional.of(Instant.now()),
|
||||
Optional.empty());
|
||||
}
|
||||
|
||||
/** Publish mutation with an explicit publication instant, for deterministic tests and replay. */
|
||||
public static FileRecordMutation publishAt(
|
||||
ContentKey contentKey,
|
||||
long actualSize,
|
||||
String sha256,
|
||||
String strongEtag,
|
||||
Instant publishedAt) {
|
||||
return new FileRecordMutation(
|
||||
Optional.of(contentKey),
|
||||
OptionalLong.of(actualSize),
|
||||
Optional.of(sha256),
|
||||
Optional.of(strongEtag),
|
||||
Optional.empty(),
|
||||
Optional.of(publishedAt),
|
||||
Optional.empty());
|
||||
}
|
||||
|
||||
/** Records the streamed byte count and digest without publishing anything. */
|
||||
public static FileRecordMutation uploaded(long actualSize, String sha256) {
|
||||
return new FileRecordMutation(
|
||||
Optional.empty(),
|
||||
OptionalLong.of(actualSize),
|
||||
Optional.of(sha256),
|
||||
Optional.empty(),
|
||||
Optional.empty(),
|
||||
Optional.empty(),
|
||||
Optional.empty());
|
||||
}
|
||||
|
||||
/**
|
||||
* The same mutation with the verifier's media type attached.
|
||||
*
|
||||
* <p>Lets a publish carry the verified type in the one statement that makes the file readable,
|
||||
* instead of a follow-up write. An absent verdict leaves the column alone rather than clearing
|
||||
* it, which is the same omission rule the rest of this type follows.
|
||||
*/
|
||||
public FileRecordMutation withVerifiedMediaType(Optional<String> mediaType) {
|
||||
Objects.requireNonNull(mediaType, "mediaType");
|
||||
return mediaType.isEmpty()
|
||||
? this
|
||||
: new FileRecordMutation(
|
||||
contentKey, actualSize, sha256, strongEtag, mediaType, publishedAt, lastErrorCode);
|
||||
}
|
||||
|
||||
/** Records the verifier-established media type. */
|
||||
public static FileRecordMutation verified(String verifiedMediaType) {
|
||||
return new FileRecordMutation(
|
||||
Optional.empty(),
|
||||
OptionalLong.empty(),
|
||||
Optional.empty(),
|
||||
Optional.empty(),
|
||||
Optional.of(verifiedMediaType),
|
||||
Optional.empty(),
|
||||
Optional.empty());
|
||||
}
|
||||
|
||||
/** Records a stable failure code that the recovery policy later reads. */
|
||||
public static FileRecordMutation failure(String lastErrorCode) {
|
||||
return new FileRecordMutation(
|
||||
Optional.empty(),
|
||||
OptionalLong.empty(),
|
||||
Optional.empty(),
|
||||
Optional.empty(),
|
||||
Optional.empty(),
|
||||
Optional.empty(),
|
||||
Optional.of(lastErrorCode));
|
||||
}
|
||||
}
|
||||
-27
@@ -1,27 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.metadata;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.FileState;
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
import java.util.Set;
|
||||
|
||||
/**
|
||||
* Bounded query for records that may need reconciliation.
|
||||
*
|
||||
* <p>The limit is mandatory: recovery scans are always bounded so a large backlog cannot turn into
|
||||
* an unbounded scan.
|
||||
*/
|
||||
public record FileRecoveryQuery(Set<FileState> states, Instant notUpdatedSince, int limit) {
|
||||
|
||||
public FileRecoveryQuery {
|
||||
Objects.requireNonNull(states, "states");
|
||||
Objects.requireNonNull(notUpdatedSince, "notUpdatedSince");
|
||||
if (states.isEmpty()) {
|
||||
throw new IllegalArgumentException("at least one state is required");
|
||||
}
|
||||
if (limit <= 0 || limit > 1000) {
|
||||
throw new IllegalArgumentException("limit must be between 1 and 1000");
|
||||
}
|
||||
states = Set.copyOf(states);
|
||||
}
|
||||
}
|
||||
-34
@@ -1,34 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.metadata;
|
||||
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
import java.util.UUID;
|
||||
|
||||
/**
|
||||
* Durable claim on storage capacity held while an upload is in flight.
|
||||
*
|
||||
* <p>Reserved bytes are converted into committed usage only after the actual byte count is known,
|
||||
* so an over-reservation never becomes permanent consumption.
|
||||
*/
|
||||
public record QuotaReservation(
|
||||
UUID reservationId,
|
||||
QuotaScope scope,
|
||||
long reservedBytes,
|
||||
long committedBytes,
|
||||
Instant expiresAt,
|
||||
QuotaReservationStatus status,
|
||||
long version) {
|
||||
|
||||
public QuotaReservation {
|
||||
Objects.requireNonNull(reservationId, "reservationId");
|
||||
Objects.requireNonNull(scope, "scope");
|
||||
Objects.requireNonNull(expiresAt, "expiresAt");
|
||||
Objects.requireNonNull(status, "status");
|
||||
if (reservedBytes < 0 || committedBytes < 0) {
|
||||
throw new IllegalArgumentException("quota byte counts must not be negative");
|
||||
}
|
||||
if (version < 0) {
|
||||
throw new IllegalArgumentException("version must not be negative");
|
||||
}
|
||||
}
|
||||
}
|
||||
-14
@@ -1,14 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.metadata;
|
||||
|
||||
/**
|
||||
* Lifecycle of a quota reservation.
|
||||
*
|
||||
* <p>A reservation that is neither committed nor released before its expiry is reclaimed by the
|
||||
* cleanup worker so an abandoned upload cannot hold capacity forever.
|
||||
*/
|
||||
public enum QuotaReservationStatus {
|
||||
RESERVED,
|
||||
COMMITTED,
|
||||
RELEASED,
|
||||
EXPIRED
|
||||
}
|
||||
-33
@@ -1,33 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.metadata;
|
||||
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* Accounting boundary for reservations, commits, and concurrency permits.
|
||||
*
|
||||
* <p>A scope is a bounded label such as a tenant or a namespace. It is never a user identifier that
|
||||
* would make a metric or a log line high-cardinality.
|
||||
*/
|
||||
public record QuotaScope(String type, String value) {
|
||||
|
||||
public QuotaScope {
|
||||
Objects.requireNonNull(type, "type");
|
||||
Objects.requireNonNull(value, "value");
|
||||
if (type.isBlank() || value.isBlank()) {
|
||||
throw new IllegalArgumentException("quota scope must be non-blank");
|
||||
}
|
||||
}
|
||||
|
||||
public static QuotaScope ofNamespace(String namespace) {
|
||||
return new QuotaScope("namespace", namespace);
|
||||
}
|
||||
|
||||
public static QuotaScope ofTenant(String tenant) {
|
||||
return new QuotaScope("tenant", tenant);
|
||||
}
|
||||
|
||||
/** Stable key used for lock ordering and permit maps. */
|
||||
public String canonicalKey() {
|
||||
return type + ':' + value;
|
||||
}
|
||||
}
|
||||
-64
@@ -1,64 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.metadata;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.FileId;
|
||||
import dev.caskeleton.application.fileserver.api.UploadId;
|
||||
import dev.caskeleton.application.fileserver.api.transfer.UploadProtocol;
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
import java.util.Optional;
|
||||
import java.util.OptionalLong;
|
||||
import java.util.UUID;
|
||||
|
||||
/**
|
||||
* Durable state of one resumable upload.
|
||||
*
|
||||
* <p>{@code committedOffset} advances only by bytes proven durable, and the lease columns make the
|
||||
* single-writer rule enforceable across instances.
|
||||
*
|
||||
* <p>{@code terminal} says whether anyone may still write to this upload at all, which the lease
|
||||
* cannot: a lease answers "who is writing now", and an upload that has been cancelled or has failed
|
||||
* verification simply has no lease — indistinguishable, until this flag, from an idle live one.
|
||||
*/
|
||||
public record UploadSession(
|
||||
UploadId uploadId,
|
||||
FileId fileId,
|
||||
UploadProtocol protocol,
|
||||
OptionalLong expectedLength,
|
||||
long committedOffset,
|
||||
Instant expiresAt,
|
||||
Optional<String> leaseOwner,
|
||||
Optional<UUID> leaseToken,
|
||||
Optional<Instant> leaseUntil,
|
||||
boolean terminal,
|
||||
long version,
|
||||
Instant createdAt,
|
||||
Instant updatedAt) {
|
||||
|
||||
public UploadSession {
|
||||
Objects.requireNonNull(uploadId, "uploadId");
|
||||
Objects.requireNonNull(fileId, "fileId");
|
||||
Objects.requireNonNull(protocol, "protocol");
|
||||
Objects.requireNonNull(expectedLength, "expectedLength");
|
||||
Objects.requireNonNull(expiresAt, "expiresAt");
|
||||
Objects.requireNonNull(leaseOwner, "leaseOwner");
|
||||
Objects.requireNonNull(leaseToken, "leaseToken");
|
||||
Objects.requireNonNull(leaseUntil, "leaseUntil");
|
||||
Objects.requireNonNull(createdAt, "createdAt");
|
||||
Objects.requireNonNull(updatedAt, "updatedAt");
|
||||
if (committedOffset < 0) {
|
||||
throw new IllegalArgumentException("committedOffset must not be negative");
|
||||
}
|
||||
if (version < 0) {
|
||||
throw new IllegalArgumentException("version must not be negative");
|
||||
}
|
||||
}
|
||||
|
||||
public boolean isExpiredAt(Instant now) {
|
||||
return !now.isBefore(expiresAt);
|
||||
}
|
||||
|
||||
/** True when the declared length is known and already fully committed. */
|
||||
public boolean isComplete() {
|
||||
return expectedLength.isPresent() && expectedLength.getAsLong() == committedOffset;
|
||||
}
|
||||
}
|
||||
-25
@@ -1,25 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.metadata;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.FileId;
|
||||
import dev.caskeleton.application.fileserver.api.UploadId;
|
||||
import dev.caskeleton.application.fileserver.api.transfer.UploadProtocol;
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
import java.util.OptionalLong;
|
||||
|
||||
/** Insert payload for a new upload resource. */
|
||||
public record UploadSessionDraft(
|
||||
UploadId uploadId,
|
||||
FileId fileId,
|
||||
UploadProtocol protocol,
|
||||
OptionalLong expectedLength,
|
||||
Instant expiresAt) {
|
||||
|
||||
public UploadSessionDraft {
|
||||
Objects.requireNonNull(uploadId, "uploadId");
|
||||
Objects.requireNonNull(fileId, "fileId");
|
||||
Objects.requireNonNull(protocol, "protocol");
|
||||
Objects.requireNonNull(expectedLength, "expectedLength");
|
||||
Objects.requireNonNull(expiresAt, "expiresAt");
|
||||
}
|
||||
}
|
||||
-66
@@ -1,66 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.metadata;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.UploadId;
|
||||
import java.time.Duration;
|
||||
import java.time.Instant;
|
||||
import java.util.List;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* Upload resource and writer-lease port.
|
||||
*
|
||||
* <p>An offset commit always requires the lease token and the expected offset, so a writer whose
|
||||
* lease was taken over cannot advance the session.
|
||||
*/
|
||||
public interface UploadSessionStore {
|
||||
|
||||
UploadSession create(UploadSessionDraft draft);
|
||||
|
||||
Optional<UploadSession> find(UploadId uploadId);
|
||||
|
||||
WriterLease acquireLease(
|
||||
UploadId uploadId, String owner, Instant now, Duration leaseDuration, long expectedVersion);
|
||||
|
||||
/**
|
||||
* Extends a lease this node still holds.
|
||||
*
|
||||
* <p>Distinct from {@link #acquireLease} on purpose. Acquisition is only legal when no lease is
|
||||
* held or the held one has expired, which is exactly false for the writer that is mid-transfer;
|
||||
* routing renewal through acquisition would make every heartbeat fail and leave long uploads with
|
||||
* no way to keep the lease they are actively using.
|
||||
*
|
||||
* @throws dev.caskeleton.application.fileserver.api.error.ConcurrentFileModificationException
|
||||
* when the lease has expired or was taken over
|
||||
*/
|
||||
WriterLease renewLease(WriterLease lease, Instant now, Duration leaseDuration);
|
||||
|
||||
UploadSession commitOffset(
|
||||
UploadId uploadId, WriterLease lease, long expectedOffset, long committedOffset);
|
||||
|
||||
void releaseLease(UploadId uploadId, WriterLease lease);
|
||||
|
||||
/**
|
||||
* Ends the upload's writable life.
|
||||
*
|
||||
* <p>Called from the transaction that decides the upload is over and queues its staging cleanup,
|
||||
* so "nobody may write here again" and "these bytes are scheduled for deletion" become true
|
||||
* together. Queuing the cleanup on its own left a window in which a writer could still take a
|
||||
* lease on the object about to be removed.
|
||||
*
|
||||
* @return whether this call is the one that ended it
|
||||
*/
|
||||
boolean terminate(UploadId uploadId);
|
||||
|
||||
/**
|
||||
* Claims a terminal upload whose writer lease has lapsed, so its staged bytes can be deleted.
|
||||
*
|
||||
* <p>A claim, not a question. Reading the lease and then deleting leaves room for a writer to
|
||||
* acquire that lease in between, and the object removed is then one an upload is actively
|
||||
* appending to. The store settles it in the database and refuses writers afterwards.
|
||||
*
|
||||
* @return whether the caller may delete the staged bytes
|
||||
*/
|
||||
boolean claimForCleanup(UploadId uploadId, Instant now);
|
||||
|
||||
List<UploadSession> findExpired(Instant cutoff, int limit);
|
||||
}
|
||||
-34
@@ -1,34 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.metadata;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.UploadId;
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
import java.util.UUID;
|
||||
|
||||
/**
|
||||
* The single right to append to one upload resource.
|
||||
*
|
||||
* <p>The lease is acquired by a conditional database update. A local file lock or an NFS lock is
|
||||
* never used as the correctness mechanism, so a paused writer whose lease expired can no longer
|
||||
* commit.
|
||||
*/
|
||||
public record WriterLease(
|
||||
UploadId uploadId, String owner, UUID token, Instant expiresAt, long version) {
|
||||
|
||||
public WriterLease {
|
||||
Objects.requireNonNull(uploadId, "uploadId");
|
||||
Objects.requireNonNull(owner, "owner");
|
||||
Objects.requireNonNull(token, "token");
|
||||
Objects.requireNonNull(expiresAt, "expiresAt");
|
||||
if (owner.isBlank()) {
|
||||
throw new IllegalArgumentException("lease owner must be non-blank");
|
||||
}
|
||||
if (version < 0) {
|
||||
throw new IllegalArgumentException("version must not be negative");
|
||||
}
|
||||
}
|
||||
|
||||
public boolean isExpiredAt(Instant now) {
|
||||
return !now.isBefore(expiresAt);
|
||||
}
|
||||
}
|
||||
-22
@@ -1,22 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.security;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.metadata.FileDescriptor;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* Authorization hook the Fileserver calls on every public operation.
|
||||
*
|
||||
* <p>The Fileserver contains no business authorization rule of its own. The starter must not create
|
||||
* an allow-all implementation in a production profile: a missing policy is a startup failure, not a
|
||||
* silent permit.
|
||||
*/
|
||||
public interface FileAccessPolicy {
|
||||
|
||||
/**
|
||||
* Authorizes {@code operation}, throwing when it is denied.
|
||||
*
|
||||
* <p>{@code descriptor} is empty for operations that run before a file record exists.
|
||||
*/
|
||||
void authorize(
|
||||
FileOperation operation, FileAccessSubject subject, Optional<FileDescriptor> descriptor);
|
||||
}
|
||||
-32
@@ -1,32 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.security;
|
||||
|
||||
import java.util.Map;
|
||||
import java.util.Objects;
|
||||
import java.util.Set;
|
||||
|
||||
/**
|
||||
* Framework-free caller identity handed to the access policy.
|
||||
*
|
||||
* <p>The Fileserver never interprets these values: it only passes them to the injected policy. No
|
||||
* Spring Security type appears here.
|
||||
*/
|
||||
public record FileAccessSubject(
|
||||
String principalId, Set<String> roles, Map<String, String> attributes) {
|
||||
|
||||
public FileAccessSubject {
|
||||
Objects.requireNonNull(principalId, "principalId");
|
||||
Objects.requireNonNull(roles, "roles");
|
||||
Objects.requireNonNull(attributes, "attributes");
|
||||
roles = Set.copyOf(roles);
|
||||
attributes = Map.copyOf(attributes);
|
||||
}
|
||||
|
||||
/** Unauthenticated caller; a production policy is expected to deny it. */
|
||||
public static FileAccessSubject anonymous() {
|
||||
return new FileAccessSubject("anonymous", Set.of(), Map.of());
|
||||
}
|
||||
|
||||
public static FileAccessSubject of(String principalId, Set<String> roles) {
|
||||
return new FileAccessSubject(principalId, roles, Map.of());
|
||||
}
|
||||
}
|
||||
-19
@@ -1,19 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.security;
|
||||
|
||||
/**
|
||||
* Operations the access policy is consulted for.
|
||||
*
|
||||
* <p>Every public entry point maps to exactly one value; there is no unchecked operation.
|
||||
*/
|
||||
public enum FileOperation {
|
||||
CREATE,
|
||||
APPEND,
|
||||
FINALIZE,
|
||||
READ_METADATA,
|
||||
DOWNLOAD,
|
||||
DELETE,
|
||||
COPY,
|
||||
MOVE,
|
||||
ADMIN_REVERIFY,
|
||||
ADMIN_FORCE_DELETE
|
||||
}
|
||||
-17
@@ -1,17 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.security;
|
||||
|
||||
import java.util.concurrent.CompletionStage;
|
||||
|
||||
/**
|
||||
* One step of the verification pipeline.
|
||||
*
|
||||
* <p>A verifier returns only a stable code and bounded safe metadata. It never logs a content
|
||||
* sample, and a failure to reach an external scanner is {@link VerificationVerdict#RETRY}, never
|
||||
* {@link VerificationVerdict#ACCEPT}.
|
||||
*/
|
||||
public interface FileVerifier {
|
||||
|
||||
String verifierId();
|
||||
|
||||
CompletionStage<VerificationResult> verify(VerificationRequest request);
|
||||
}
|
||||
-155
@@ -1,155 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.security;
|
||||
|
||||
import java.nio.charset.StandardCharsets;
|
||||
import java.util.Locale;
|
||||
import java.util.Set;
|
||||
import java.util.regex.Pattern;
|
||||
|
||||
/**
|
||||
* Turns an untrusted client filename into display-only text.
|
||||
*
|
||||
* <p>The result is used for {@code Content-Disposition} and for the untrusted {@code originalName}
|
||||
* metadata column. It is never a physical filename, a path component, or a security verdict input.
|
||||
*/
|
||||
public final class OriginalFilenamePolicy {
|
||||
|
||||
private static final String FALLBACK = "file";
|
||||
|
||||
private static final Set<String> WINDOWS_RESERVED =
|
||||
Set.of(
|
||||
"CON", "PRN", "AUX", "NUL", "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7",
|
||||
"COM8", "COM9", "LPT1", "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9");
|
||||
|
||||
/**
|
||||
* Structural characters that must never survive into a name.
|
||||
*
|
||||
* <p>Path separators and NUL are the obvious ones. The colon is here because on Windows it opens
|
||||
* both a drive reference ({@code C:\...}) and an NTFS alternate data stream ({@code
|
||||
* name.txt:hidden}), so a name that keeps it is still path-shaped even after the slashes are
|
||||
* gone. Quote characters would break a header value.
|
||||
*/
|
||||
private static final Pattern STRUCTURAL = Pattern.compile("[/\\\\\\u0000\"';:]");
|
||||
|
||||
/** C0 and C1 control characters, including CR and LF. */
|
||||
private static final Pattern CONTROL = Pattern.compile("[\\p{Cntrl}\\u007f-\\u009f]");
|
||||
|
||||
/** Bidirectional override and isolate characters used for filename spoofing. */
|
||||
private static final Pattern BIDI =
|
||||
Pattern.compile("[\\u202a-\\u202e\\u2066-\\u2069\\u200e\\u200f]");
|
||||
|
||||
/** Runs of dots, which would otherwise leave a traversal-shaped display name. */
|
||||
private static final Pattern DOT_RUN = Pattern.compile("\\.{2,}");
|
||||
|
||||
private final int maximumByteLength;
|
||||
|
||||
public OriginalFilenamePolicy(int maximumByteLength) {
|
||||
if (maximumByteLength < 8) {
|
||||
throw new IllegalArgumentException("maximumByteLength must be at least 8");
|
||||
}
|
||||
this.maximumByteLength = maximumByteLength;
|
||||
}
|
||||
|
||||
/** Policy with the design's 255-byte UTF-8 bound. */
|
||||
public static OriginalFilenamePolicy standard() {
|
||||
return new OriginalFilenamePolicy(255);
|
||||
}
|
||||
|
||||
/**
|
||||
* Sanitizes {@code candidate}.
|
||||
*
|
||||
* <p>The steps run in a fixed order so the result is deterministic: remove structural and control
|
||||
* characters, collapse dot runs, trim leading dots and trailing dots or spaces, guard Windows
|
||||
* reserved names, then bound the UTF-8 length while preserving the final extension when it fits.
|
||||
*/
|
||||
public SanitizedFilename sanitize(String candidate) {
|
||||
if (candidate == null) {
|
||||
return new SanitizedFilename(FALLBACK);
|
||||
}
|
||||
String working = STRUCTURAL.matcher(candidate).replaceAll("");
|
||||
working = CONTROL.matcher(working).replaceAll("");
|
||||
working = BIDI.matcher(working).replaceAll("");
|
||||
working = DOT_RUN.matcher(working).replaceAll(".");
|
||||
working = stripLeading(working, '.');
|
||||
working = stripTrailing(working);
|
||||
working = guardReservedName(working);
|
||||
working = truncateToByteLength(working);
|
||||
working = stripTrailing(working);
|
||||
if (working.isEmpty()) {
|
||||
working = FALLBACK;
|
||||
}
|
||||
return new SanitizedFilename(working);
|
||||
}
|
||||
|
||||
private static String stripLeading(String value, char unwanted) {
|
||||
int start = 0;
|
||||
while (start < value.length() && value.charAt(start) == unwanted) {
|
||||
start++;
|
||||
}
|
||||
return value.substring(start);
|
||||
}
|
||||
|
||||
private static String stripTrailing(String value) {
|
||||
int end = value.length();
|
||||
while (end > 0) {
|
||||
char last = value.charAt(end - 1);
|
||||
if (last == '.' || last == ' ') {
|
||||
end--;
|
||||
} else {
|
||||
break;
|
||||
}
|
||||
}
|
||||
return value.substring(0, end).trim();
|
||||
}
|
||||
|
||||
private static String guardReservedName(String value) {
|
||||
if (value.isEmpty()) {
|
||||
return value;
|
||||
}
|
||||
int dot = value.indexOf('.');
|
||||
String stem = dot < 0 ? value : value.substring(0, dot);
|
||||
if (WINDOWS_RESERVED.contains(stem.toUpperCase(Locale.ROOT))) {
|
||||
return "_" + value;
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
/**
|
||||
* Bounds the UTF-8 byte length.
|
||||
*
|
||||
* <p>The final extension is preserved when it still fits, because losing it would change how the
|
||||
* client offers the download even though the stored media type is unaffected.
|
||||
*/
|
||||
private String truncateToByteLength(String value) {
|
||||
if (utf8Length(value) <= maximumByteLength) {
|
||||
return value;
|
||||
}
|
||||
int lastDot = value.lastIndexOf('.');
|
||||
String extension = lastDot > 0 ? value.substring(lastDot) : "";
|
||||
if (utf8Length(extension) > maximumByteLength / 2) {
|
||||
extension = "";
|
||||
}
|
||||
String stem = extension.isEmpty() ? value : value.substring(0, lastDot);
|
||||
int budget = maximumByteLength - utf8Length(extension);
|
||||
return truncateCodePoints(stem, budget) + extension;
|
||||
}
|
||||
|
||||
private static String truncateCodePoints(String value, int budget) {
|
||||
StringBuilder builder = new StringBuilder();
|
||||
int used = 0;
|
||||
for (int index = 0; index < value.length(); ) {
|
||||
int codePoint = value.codePointAt(index);
|
||||
int width = utf8Length(new String(Character.toChars(codePoint)));
|
||||
if (used + width > budget) {
|
||||
break;
|
||||
}
|
||||
builder.appendCodePoint(codePoint);
|
||||
used += width;
|
||||
index += Character.charCount(codePoint);
|
||||
}
|
||||
return builder.toString();
|
||||
}
|
||||
|
||||
private static int utf8Length(String value) {
|
||||
return value.getBytes(StandardCharsets.UTF_8).length;
|
||||
}
|
||||
}
|
||||
-21
@@ -1,21 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.security;
|
||||
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* Ambient information one Fileserver call carries.
|
||||
*
|
||||
* <p>{@code instanceId} is the writer-lease owner for this node. {@code traceId} correlates
|
||||
* observability without becoming a metric label.
|
||||
*/
|
||||
public record RequestContext(FileAccessSubject subject, String traceId, String instanceId) {
|
||||
|
||||
public RequestContext {
|
||||
Objects.requireNonNull(subject, "subject");
|
||||
Objects.requireNonNull(traceId, "traceId");
|
||||
Objects.requireNonNull(instanceId, "instanceId");
|
||||
if (instanceId.isBlank()) {
|
||||
throw new IllegalArgumentException("instanceId must be non-blank");
|
||||
}
|
||||
}
|
||||
}
|
||||
-25
@@ -1,25 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.security;
|
||||
|
||||
import java.nio.charset.StandardCharsets;
|
||||
import java.util.Objects;
|
||||
|
||||
/**
|
||||
* Display filename that is safe to place in a {@code Content-Disposition} header.
|
||||
*
|
||||
* <p>A sanitized name is never used to build a physical path or a content key: the physical object
|
||||
* is named from server-generated identity only.
|
||||
*/
|
||||
public record SanitizedFilename(String value) {
|
||||
|
||||
public SanitizedFilename {
|
||||
Objects.requireNonNull(value, "value");
|
||||
if (value.isEmpty()) {
|
||||
throw new IllegalArgumentException("sanitized filename must not be empty");
|
||||
}
|
||||
}
|
||||
|
||||
/** UTF-8 length of the sanitized name, which the policy bounds. */
|
||||
public int byteLength() {
|
||||
return value.getBytes(StandardCharsets.UTF_8).length;
|
||||
}
|
||||
}
|
||||
-36
@@ -1,36 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.security;
|
||||
|
||||
import dev.caskeleton.application.fileserver.api.ContentKey;
|
||||
import dev.caskeleton.application.fileserver.api.FileId;
|
||||
import dev.caskeleton.application.fileserver.api.UploadId;
|
||||
import java.util.Objects;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* Everything a verifier is allowed to know about the object under inspection.
|
||||
*
|
||||
* <p>The claimed media type and the sanitized filename are present as untrusted hints. A verifier
|
||||
* that needs bytes reads them through the content store using {@code stagingUploadId} or {@code
|
||||
* contentKey}; the request itself never carries a path or a stream.
|
||||
*/
|
||||
public record VerificationRequest(
|
||||
FileId fileId,
|
||||
Optional<UploadId> stagingUploadId,
|
||||
Optional<ContentKey> contentKey,
|
||||
long size,
|
||||
String sha256,
|
||||
Optional<String> claimedMediaType,
|
||||
SanitizedFilename sanitizedFilename) {
|
||||
|
||||
public VerificationRequest {
|
||||
Objects.requireNonNull(fileId, "fileId");
|
||||
Objects.requireNonNull(stagingUploadId, "stagingUploadId");
|
||||
Objects.requireNonNull(contentKey, "contentKey");
|
||||
Objects.requireNonNull(sha256, "sha256");
|
||||
Objects.requireNonNull(claimedMediaType, "claimedMediaType");
|
||||
Objects.requireNonNull(sanitizedFilename, "sanitizedFilename");
|
||||
if (size < 0) {
|
||||
throw new IllegalArgumentException("size must not be negative");
|
||||
}
|
||||
}
|
||||
}
|
||||
-50
@@ -1,50 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.security;
|
||||
|
||||
import java.util.Map;
|
||||
import java.util.Objects;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* A verifier's answer.
|
||||
*
|
||||
* <p>{@code safeMetadata} is a bounded, already-sanitized map. A scanner's raw response, a content
|
||||
* sample, and any credential are deliberately absent.
|
||||
*/
|
||||
public record VerificationResult(
|
||||
VerificationVerdict verdict,
|
||||
String code,
|
||||
Optional<String> verifiedMediaType,
|
||||
Map<String, String> safeMetadata) {
|
||||
|
||||
public VerificationResult {
|
||||
Objects.requireNonNull(verdict, "verdict");
|
||||
Objects.requireNonNull(code, "code");
|
||||
Objects.requireNonNull(verifiedMediaType, "verifiedMediaType");
|
||||
Objects.requireNonNull(safeMetadata, "safeMetadata");
|
||||
if (code.isBlank()) {
|
||||
throw new IllegalArgumentException("verification code must be non-blank");
|
||||
}
|
||||
safeMetadata = Map.copyOf(safeMetadata);
|
||||
}
|
||||
|
||||
public static VerificationResult accept(String code) {
|
||||
return new VerificationResult(VerificationVerdict.ACCEPT, code, Optional.empty(), Map.of());
|
||||
}
|
||||
|
||||
public static VerificationResult accept(String code, String verifiedMediaType) {
|
||||
return new VerificationResult(
|
||||
VerificationVerdict.ACCEPT, code, Optional.of(verifiedMediaType), Map.of());
|
||||
}
|
||||
|
||||
public static VerificationResult reject(String code) {
|
||||
return new VerificationResult(VerificationVerdict.REJECT, code, Optional.empty(), Map.of());
|
||||
}
|
||||
|
||||
public static VerificationResult quarantine(String code) {
|
||||
return new VerificationResult(VerificationVerdict.QUARANTINE, code, Optional.empty(), Map.of());
|
||||
}
|
||||
|
||||
public static VerificationResult retry(String code) {
|
||||
return new VerificationResult(VerificationVerdict.RETRY, code, Optional.empty(), Map.of());
|
||||
}
|
||||
}
|
||||
-29
@@ -1,29 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.security;
|
||||
|
||||
/**
|
||||
* Outcome of one verifier or of the whole pipeline.
|
||||
*
|
||||
* <p>Combination precedence is {@code REJECT > QUARANTINE > RETRY > ACCEPT}. A scanner timeout is
|
||||
* {@link #RETRY} and is never silently promoted to {@link #ACCEPT}.
|
||||
*/
|
||||
public enum VerificationVerdict {
|
||||
ACCEPT,
|
||||
QUARANTINE,
|
||||
REJECT,
|
||||
RETRY;
|
||||
|
||||
/** Rank used by the policy combiner; a higher rank dominates. */
|
||||
public int precedence() {
|
||||
return switch (this) {
|
||||
case REJECT -> 3;
|
||||
case QUARANTINE -> 2;
|
||||
case RETRY -> 1;
|
||||
case ACCEPT -> 0;
|
||||
};
|
||||
}
|
||||
|
||||
/** True when this verdict permits publishing content. */
|
||||
public boolean allowsPublish() {
|
||||
return this == ACCEPT;
|
||||
}
|
||||
}
|
||||
-54
@@ -1,54 +0,0 @@
|
||||
package dev.caskeleton.application.fileserver.api.transfer;
|
||||
|
||||
import java.time.Instant;
|
||||
import java.util.Objects;
|
||||
import java.util.Optional;
|
||||
|
||||
/**
|
||||
* Transport-neutral view of the conditional and range headers of one request.
|
||||
*
|
||||
* <p>Adapters translate their own header types into this record so the decision logic is shared and
|
||||
* cannot diverge between MVC and WebFlux.
|
||||
*/
|
||||
public record ConditionalRequest(
|
||||
Optional<String> ifMatch,
|
||||
Optional<String> ifNoneMatch,
|
||||
Optional<Instant> ifModifiedSince,
|
||||
Optional<Instant> ifUnmodifiedSince,
|
||||
Optional<String> ifRange,
|
||||
Optional<String> range,
|
||||
boolean headOnly) {
|
||||
|
||||
public ConditionalRequest {
|
||||
Objects.requireNonNull(ifMatch, "ifMatch");
|
||||
Objects.requireNonNull(ifNoneMatch, "ifNoneMatch");
|
||||
Objects.requireNonNull(ifModifiedSince, "ifModifiedSince");
|
||||
Objects.requireNonNull(ifUnmodifiedSince, "ifUnmodifiedSince");
|
||||
Objects.requireNonNull(ifRange, "ifRange");
|
||||
Objects.requireNonNull(range, "range");
|
||||
}
|
||||
|
||||
/** Unconditional full-representation GET. */
|
||||
public static ConditionalRequest plainGet() {
|
||||
return new ConditionalRequest(
|
||||
Optional.empty(),
|
||||
Optional.empty(),
|
||||
Optional.empty(),
|
||||
Optional.empty(),
|
||||
Optional.empty(),
|
||||
Optional.empty(),
|
||||
false);
|
||||
}
|
||||
|
||||
/** Unconditional GET restricted to one range. */
|
||||
public static ConditionalRequest rangeGet(String range) {
|
||||
return new ConditionalRequest(
|
||||
Optional.empty(),
|
||||
Optional.empty(),
|
||||
Optional.empty(),
|
||||
Optional.empty(),
|
||||
Optional.empty(),
|
||||
Optional.of(range),
|
||||
false);
|
||||
}
|
||||
}
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user