Read-through cache for object storage
High-performance read-through cache for object storage.
/fetch API requiring a precise RangeHEAD|GET /fetch/{kind}/{object}kind + object form the cache keykind identifies the bucket set (up to 64 chars)object is the S3 object key| Header | Required | Description |
|---|---|---|
Range |
yes | Byte range in format bytes={first}-{last} |
C0-Bucket |
no | Bucket(s) containing the object |
C0-Config |
no | Override S3 request config |
C0-Bucket behavior:
kind is used as the singular bucket nameSee replica reads for selection, fallback, hedging, and download limits.
C0-Config overrides:
Space-separated key-value pairs to override S3 request configuration per page miss.
ct= Connect timeout (in case an existing connection could not be reused)rt= Read timeout (time-to-first-byte)ot= Operation timeout (across retries)oat= Operation attempt timeoutma= Maximum attempts for each bucket's primary SDK operationib= Initial backoff durationmb= Maximum backoff durationfps= Force path-style addressingSDK overrides are bounded by the server's download deadlines; early hedges use one SDK attempt.
GET /fetch/prod-videos/movie-2024.mp4 HTTP/1.1
Range: bytes=1048576-18874367
C0-Bucket: us-west-videos
C0-Bucket: us-east-videos-backup
C0-Config: ct=1000 oat=1500 ma=5 ib=10 mb=100The service maps requests to 16 MiB page-aligned ranges and the response has standard HTTP semantics (206 Partial Content, 404 Not Found etc.)
| Header | Description |
|---|---|
Content-Range |
Actual byte range served |
Content-Length |
Number of bytes in response |
Last-Modified |
Timestamp from first page |
Content-Type |
Always application/octet-stream |
C0-Status |
Status for first page |
C0-Status format: {first}-{last}; {bucket}; {cached_at}
cached_at is Unix timestamp with 0 implying a cache missUse HTTP/2 when you need per-page status for a multi-page read. HTTP/1.1 responses
include Content-Length and only the first page's status.
HTTP/1.1 206 Partial Content
Content-Range: bytes 1048576-18874367/52428800
Content-Length: 17825792
Content-Type: application/octet-stream
C0-Status: 1048576-16777215; us-west-videos; 1704067200
GET /stats returns throughput stats as JSON for load balancing and health checking.
GET /metrics returns a more comprehensive set of metrics in Prometheus text format.
Docker images are available.
…Use the nightly Cargo dependency commands so that the seven-day publication cooldown applies:
cargo +nightly add
cargo +nightly update
cargo +nightly update -p
cargo +nightly remove
cargo +nightly generate-lockfileUse --locked with normal build, check, test, run, document, fetch, and metadata commands. The pull request dependency gate verifies each proposed lockfile change before Rust build jobs start.
No open issues yet, or sync has not completed.