http-cache-stream

A HTTP caching middleware that supports streaming bodies and uses http-cache-semantics.
Explore the docs »

Request Feature · Report Bug · ⭐ Consider starring the repo! ⭐

Getting started

TODO: complete this section

How this crate differs from http-cache

The http-cache crate is a highly-configurable HTTP cache that supports different storage backends and middleware for many popular Rust HTTP client APIs.

The http-cache-stream crate is inspired by the implementation provided by http-cache, but differs in significant ways:

• http-cache-stream supports streaming of requests/responses and does not read a response body into memory to store in the cache.
• The default storage implementation for http-cache-stream uses advisory file locking to coordinate access to storage across multiple processes and threads.
• The default storage implementation is simple and provides no integrity of cached bodies, but does provide some fault tolerance for writes to cache storage (i.e. partially written cache entries are discarded).
• The API for http-cache-stream is not nearly as configurable as http-cache.
• Only a middleware implementation for reqwest will be made initially.

Development

To bootstrap a development environment, please use the following commands.

# Clone the repository
git clone [email protected]:stjude-rust-labs/http-cache-stream.git
cd http-cache-stream

# Build the crate
cargo build

# List out the examples
cargo run --example

# Run an example with a given name
cargo run --example '<name>'

Tests

Before submitting any pull requests, please make sure the code passes the following checks (from the root directory).

# Run the project's tests with tokio as the async runtime.
cargo test

# Run the reqwest middleware tests
cargo test -p http-cache-stream-reqwest

# Ensure the project doesn't have any linting warnings.
cargo clippy --all

# Ensure the project passes `cargo fmt`.
# Currently this requires nightly Rust.
cargo +nightly fmt --check

# Ensure the docs build.
cargo doc

Contributing

Contributions, issues, and feature requests are all welcome!

Please submit your changes as pull requests from a feature branch of your fork.

License and Legal

This project is licensed as either Apache 2.0 or MIT at your discretion. Additionally, please see the disclaimer that applies to all crates and command line tools made available by St. Jude Rust Labs.

Copyright © 2025-Present St. Jude Children's Research Hospital.