clean-architecture-backend-template/docs/fileserver/support-matrix.md

Fileserver support matrix

A support level here is a claim about evidence, not about intent. Every row names the CI job that produces that evidence; FileserverDocumentationCoverageTest fails the build if a row names a job that does not exist, so a level can never outlive the test that justified it.

Levels

Level	What it means
Stable	Certified on every pull request. Contract changes are breaking changes.
Beta	Certified nightly. The contract may still change with a deprecation notice.
Limited	Certified on the release gate only, under stated constraints.
Compatibility	Accepted but not optimized; known caveats are listed inline.
Experimental	Off by default, unratified upstream, may change without notice.

Runtime profiles

Profile	Level	CI job
Local filesystem (ext4) content store	Stable	fileserver-local-ext4-contract
Spring MVC transport (raw, multipart, batch, download)	Stable	fileserver-http-contract
Spring WebFlux transport	Experimental	fileserver-http-contract
Path, filename, range, and problem-detail hardening	Stable	fileserver-security-suite
Bounded-memory transfer	Stable	fileserver-bounded-memory
Application and architecture invariants	Stable	fileserver-unit-and-architecture
Runtime assembly (the capability starts with the flag on)	Stable	fileserver-unit-and-architecture
tus 1.0 resumable uploads	Stable	fileserver-http-contract
Crash-recovery matrix	Beta	fileserver-process-kill-matrix
NFSv4 ambiguity handling	Beta	fileserver-nfs-ambiguity
Large-file and slow-client performance	Beta	fileserver-large-file-performance
Multi-instance writer lease	Beta	fileserver-multi-instance-lease
Kubernetes ReadWriteOnce PVC	Limited	fileserver-pvc-certification (manifest checks in CI; cluster run is operator-driven)
Nginx X-Accel-Redirect delegation	Limited	fileserver-http-contract
Telemetry sensitive-data suppression	Stable	fileserver-sensitive-telemetry-scan
Documentation and support-claim coverage	Stable	fileserver-documentation-gate
Full release verification	Stable	fileserver-full-verification
HTTP resumable uploads draft-12	Experimental	fileserver-http-contract

Why WebFlux is Experimental, not Stable

The reactive router, handlers and readers are now wired: FileserverReactiveConfiguration contributes the scheduler, the handlers and a RouterFunction bean under @ConditionalOnWebApplication(type = REACTIVE) plus the platform master switch. Previously nothing built them at all, so "Stable" described the source tree rather than a running server.

It stays Experimental because the shipped composition cannot select it. adapter:inbound:web also puts DispatcherServlet on the classpath — deliberately, so adding spring-webflux does not drag a second embedded server onto the runtime — and Boot's application-type deduction therefore resolves SERVLET. A fork that removes the servlet stack and adds a reactive server gets working routes without editing any Fileserver code; the shipped template does not exercise that path.

Raising it to Stable requires a contract job that drives the routes over a running reactive server rather than through direct construction.

Explicitly not claimed

These have no job, and therefore no claim:

• An automated Kubernetes cluster result. fileserver-pvc-certification validates the manifest on every release and applies it only when a release cluster is configured; without one it warns and records that nothing was certified. The cluster tuple is produced by an operator and read from storage-certification.md.

• Kubernetes ReadWriteMany PVC. Concurrent writers across nodes are not certified.

• Windows NTFS as a production storage root. The filename policy strips the characters NTFS reserves, but no job certifies the publish path there.

• Object storage as a content store. The contract exists (ContentStoreContract) but no adapter implements it yet.

• Server-side malware scanning. The verification pipeline has the port and the verdict precedence; no scanner is shipped.

Where the rest is written down

• configuration.md — every app.fileserver-platform.* key, its default, and the conditions that fail startup rather than degrade.
• design-deviations.md — where the implementation departs from the frozen design, why, and the test that pins each decision.
• http-contract.md — the wire contract.
• security.md — the threat model and what enforces each control.
• operations.md — runbooks, each starting from a metric.
• storage-certification.md — how a volume is certified.
• upgrade-guide.md — what changes between versions.