Transport / unmounted service
ValidatedHTTP multi-drive API
The HTTP service exposes named mount-rs drives without creating a kernel mount. It is the cleanest boundary for containers, remote clients, and environments where FUSE/NFS/FSKit are unavailable. One process can serve its drives alone, or several can form a cluster in which any server accepts a request for any drive and forwards it to the drive’s owner, with optional automatic failover between owners.
Any platform that can run the CLI/service and an HTTP client can use the mount-free API. The listener is cleartext HTTP/1.1 (or cleartext HTTP/2 with http2_prior_knowledge) on loopback with bounded requests and an ephemeral port by default; allow_non_loopback lets it listen on a private network behind a proxy or load balancer. The server does not terminate TLS itself. A cluster additionally needs a Redis route registry, a membership file with each server’s pinned key for mutual-TLS HTTP/3 between servers, and metadata and block storage that every candidate owner of a drive can reach.
There is no FUSE, NFS, 9P, or FSKit mount. Each named drive retains its own FsDriver, stable ID, and bearer token; the API maps HTTP verbs to filesystem operations and one-byte-range reads. A token comes from an environment variable, read once at startup, or from a token file that lists the current token and optionally the previous one. With remote_sessions on split-store drives the same token also opens the session and handle routes used by the remote mount client; session counts, handles per session and the idle timeout are set under http.sessions.
The v1 contract, the session routes and the cluster configuration are written down, checked against the OpenAPI documents by tests, and exercised end to end from the built binary on every platform a release publishes for. Validated describes the software, not a deployment: TLS termination, identity, backup, capacity and alerting remain the operator’s job, and every CLI release is still a preview. CI run 44270883958 on main at source e0ee93a0 is the current evidence. Its serve-http-e2e jobs start the built binary and drive it over real sockets on Linux x86_64 and arm64, macOS arm64 and Intel, and Windows. cluster-http3 runs the cluster contract against a real Redis: forwarding, remote sessions, membership reload, token-file rotation and metrics on an owner, an ingress and a failover standby, and drive failover, including a crashed owner replaced only after its storage lease expires. The same job kills the primary of a Redis Sentinel deployment with two replicas and three sentinels under real servers, with and without TLS and passwords. cluster-mixed-release runs the cluster test with servers on the current commit and on 031050cc, in both directions. tidb-rustfs repeats failover with the lease in TiDB. The rust jobs run the transport suites and the OpenAPI conformance test on Linux, macOS and Windows, and http-observability runs the all-features health, readiness and OTLP checks. The same job partitions a Redis Sentinel deployment: an old primary cut off but still accepting writes, which every server stops using within about a second of the promotion; a split brain in which a standby finds the lease held and no drive changes owner; and servers cut off from the primary or from the sentinels. It also logs in as ACL users holding only the documented commands. The Windows serve-http-e2e job closes the server’s console window, idle and with a stalled download, and checks that the server stops inside the five seconds Windows allows with its lease released. Every job passed on the run’s first attempt. Not covered: clusters of mixed releases built from two published releases; Redis Cluster, which is not supported; Redis hosts with different clocks; and any deployed collector, dashboard or pager. Local HTTP/CLI checks cover bearer isolation, streamed reads/writes, ranges, truncate, concurrent writes, restart/reopen, and cleanup. The optional mount-rs-observability seam can attach a caller-owned telemetry handle throughHttpServerOptions::with_telemetry; the OTLP variant accepts only W3C trace propagation and emits bounded operation metadata without paths, tokens, file contents, block IDs, or arbitrary headers. The macOS arm64 W30.5 loopback collector test now receives non-empty/v1/traces, /v1/metrics, and/v1/logs payloads without raw path bytes, and the HTTP observability integration gate recorded 7 passes. Hosted CI run35599817215, source b26819e, also passed the all-features HTTP health/readiness, telemetry/OTLP, and strict-Clippy job 106333141914. This is hosted exporter-path and contract evidence only: deployed collector reachability, provider- aware readiness, dashboards, paging, SLOs, and production hardening remain open. That run predates the server’s request IDs, access log, listing pagination, per-kind /readyz checks, token-file rotation, Prometheus listener, cluster membership reload and drive failover; it is not evidence for any of them. Those are exercised by the transport and CLI test suites, the OpenAPI conformance test and scripts/serve-http-cluster-e2e.py, as described in the linked documents.
What the transport exposes
/v1/drives lists authorized drives; fs routes read/write/remove paths; entries lists directories; and bounded JSON operations cover mkdir, rename, truncate, and sync. Unknown drives and invalid tokens fail closed. Every response carries X-Request-Id: a well-formed client value is echoed, anything else is replaced by a generated one, and a forwarded request keeps its ID on both servers. entries?limit=N pages a listing in byte order of name and returns a next_cursor while more follows; without limit the response is the same complete array as before. /healthz reports liveness and /readyz reports readiness for every drive kind: split-store drives that have failed closed, and host and sqlite drives whose storage a background check, every two seconds, cannot open. The routes, status codes and bodies are described by an OpenAPI 3.1 document that a conformance test compares with a live server in both directions.
Run the local unmounted service with owned tokens
MOUNT_RS_MEMORY_TOKEN=demo-memory MOUNT_RS_SQLITE_TOKEN=demo-sqlite cargo run --locked -p mount-rs-cli -- serve-http --config apps/mount-rs-cli/examples/config-http.json
curl -H 'Authorization: Bearer demo-memory' http://127.0.0.1:PORT/v1/drives/memory/entries/Safe use and lifecycle
Keep bearer tokens in environment variables, token files or a secret manager, never in the JSON config or source. A drive whose token is a file rotates without a restart: the file is re-read on SIGHUP and every token_reload_seconds (30 by default), and the previous token keeps working until its line is removed. Put a TLS-terminating proxy or load balancer in front of the listener and bound request/chunk sizes to the deployment. access_log: true writes one JSON line per request to stderr with the request ID, route template, status, duration and byte counts, and never the path, query, token or client address. http.metrics serves Prometheus text on a separate listener, loopback unless explicitly allowed; both are off by default. Shutdown is bounded: requests get drain_timeout_ms, then the drives get drive_shutdown_timeout_ms (30 s by default) to release their writer leases; past that the process exits 1 and names the drives whose leases it did not release. In a cluster, the membership file is re-read on SIGHUP or a timer, the Redis connection takes rediss:// with a password and a private CA and refuses plaintext to another host unless allowed, and an owner keeps serving its own drives through a Redis outage.
Current limitations
PUT publishes atomically: readers see the old content or the complete new content, and an upload cut off while its body is still arriving leaves no partial file. Pagination bounds each response and lifts the response-size cap, but every page still enumerates the directory, so one with more entries than max_directory_entries (100,000 by default) cannot be listed even in pages, and a walk through the pages is not a snapshot. A token grants full access to its drive; there is no per-user identity, token expiry, CORS or TLS in the server. Token-file rotation also works with remote_sessions and forwarding, but the file is per server: the owner of a drive checks the token, so the rotation is made on every server that lists the drive, and nothing distributes the file or checks that the servers agree. A session stays with the token that opened it and is closed by idle expiry once that token is dropped; clients open a new session with the new token. Metrics are not split by drive, and in a cluster each server counts what it handled, so a forwarded request is counted by the ingress and by the owner (subtract mount_rs_http_forwarded_requests_total). Each drive has one owner at a time. Failover is opt-in, needs split-store drives with exclusive ownership, and cannot move a drive before the failed owner’s storage lease expires (240 s by default); requests in flight and sessions on the failed owner are lost, not replayed; nothing checks that candidates point at the same storage. The route registry is one Redis server or the primary of a Redis Sentinel deployment; Redis Cluster is not supported. While Redis fails over, requests that need forwarding get 503, and for up to five seconds afterwards a route can be missing or name the previous owner, which never serves it. The session routes, the cluster configuration and what a client sees from a cluster are covered by the compatibility policy and checked by tests; the server-to-server protocol is internal and carries a version: a server refuses a peer whose version it does not speak, with a 503 and nothing run. Clusters of mixed releases are tested for one pair of builds only, the current commit with main at 031050cc; no pair of published releases has been run together, so a rolling upgrade between releases should be rehearsed, or the cluster upgraded by stopping every server. The local demo does not prove internet-facing deployment security.
Sources: HTTP transport README · HTTP observability boundary · Observability platform qualification · HTTP server options and telemetry seam · Current CI evidence on main (run 44270883958) · Cluster contract, failover and Redis Sentinel job · Cluster of two builds job · Binary end-to-end job, Windows · Earlier hosted HTTP observability CI · CLI HTTP example · OpenAPI 3.1 contract · OpenAPI conformance test · serve-http operator runbook · serve-http compatibility policy · serve-http upgrade and rollback · serve-http threat model and hardening · serve-http service levels and backup · serve-http drive failover design · Cluster configuration: Redis, membership, failover · Maturity levels