NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
crates.io · #4949 most downloaded on crates.io
An HTTP caching middleware
Last release 29 days ago
09 Sep 2026
Release timing varies
gaps range from 1 weeks to 7 months
Most releases are documented
notes for 23 of 37 stable releases
1 version withdrawn
withdrawn after publishing
8 years old
45 releases · first in 2018
MSRV bumped from 1.89.0 to 1.90.0
url-ada now requires ada-url 4. ada-url sets links, so a dependency graph cannot contain both majorsVary mismatchesmax_ttl is now applied on the buffered path, not only the streaming one. A response carrying no explicit freshness is served fresh for max_ttl rather than expiring immediatelyMiddleware::policy, Middleware::policy_with_options and Middleware::method. None had callers once policy construction moved to HttpCacheOptions::create_cache_policy and cache keys stopped taking a method argument. These are required methods, so existing implementations of the trait must delete themasync-compat, async-lock, cfg-if, dashmap, futures, hex, serde_jsonOne column per quarter.
RedbManager cache backend using redb for persistent, synchronous on-disk caching that requires no async runtime
RedbManager cache backend using redb for persistent, synchronous on-disk caching that requires no async runtimemanager-redb feature flag for enabling RedbManagerStreamingCacheManager::update_metadata for refreshing a stored entry's headers, policy, and user metadata without touching the body file. This is a required method, so existing implementations of the trait must add it.CachedRequestMethod and CacheEntryToken response extensions, used by the streaming orchestrator to tell a manager which request method produced a response and which stored entry a cached response was served frommanager-cacache to manager-redb. manager-cacache (and CACacheManager) is now opt-in — enable the manager-cacache feature to keep using it. The cacache crate is no longer maintained upstream.RedbManager holds an exclusive file lock on its database: a second manager (or process) opening the same path fails at construction. Share one instance via Arc instead. This differs from the previous default CACacheManager, which allowed concurrent access to one cache directory.RedbManager stores are batched for durability: commits are flushed to disk every 64 writes (configurable via from_database_with_flush_interval) and on drop, so a crash can lose approximately the most recent 64 stores. Deletes commit durably, so invalidations survive a crash.StreamingManager metadata now includes a blake3 body checksum, verified while streaming; corrupt entries error the stream and self-heal to a miss. Existing streaming cache entries from earlier alphas fail to decode and are treated as misses (re-fetched once).StreamingBody::from_file_with_size now streams exactly size bytes and errors on a shorter file; it previously read to end of file, treating size as a hint.StreamingManager no longer prewarms its in-memory metadata cache at startup; hydration is lazy, so entry_count() reads 0 after a restart until keys are accessed.StreamingManager::Body is StreamingBody<UnsyncBoxBody<Bytes, StreamingError>>). Upstream body failures on that path surface as stream errors while the body is read, not as a middleware error before the response is returned.StreamingManager are serialized with per-key locks, so racing gets/puts can no longer drop freshly written entries.StreamingManager::put writes the response body to disk one frame at a time instead of collecting it into memory first, so peak memory no longer scales with response size. It returns a body backed by the committed on-disk entry rather than an in-memory copy.max_body_size are no longer an error: caching is declined and the response is served in full, uncached. A declared Content-Length over the limit skips writing to disk entirely. HEAD responses are exempt, since their Content-Length describes the entity rather than the empty body.Content-Length are served but not cached, so a truncated response is never stored (RFC 9111 s3.3). HEAD responses are exempt.connection, transfer-encoding, the rest of the RFC 9111 s3.1 set, and any field names listed in a Connection header. Live responses are unaffected.StreamingCacheManager::put documents when a stored entry becomes visible: at or after the returned body has been fully consumed. The bundled StreamingManager makes it visible before put returns, but implementations are not required to.HttpStreamingCache::run orchestrator for streaming cache operations, eliminating duplicated logic in downstream middleware crates
HttpStreamingCache::run orchestrator for streaming cache operations, eliminating duplicated logic in downstream middleware cratesFetchRequest enum for callback-based fetch dispatch in streaming pathsrun_no_cache_from_parts public method on HttpCache for cache-busting with pre-extracted request partsCachedUserMetadata for preserving user metadata through 304 re-cache operationsresponse_cache_mode_fn evaluation in conditional_fetch 200 branch (both paths)StreamingManager storage backend replaced with an embedded redb database (for metadata) plus raw tokio::fs files (for response bodies), fronted by moka as an in-memory hot cache. This replaces the previous cacache-based backend. Overwrites atomically replace prior content; there is no longer any background eviction-driven disk cleanup. Disk state is managed explicitly by put, delete, and clear. The on-disk format is not compatible with previous releases — users upgrading should delete the metadata.redb file, the bodies/ subdirectory, and the tmp/ subdirectory from their cache directory before the first run on this version.StreamingManager instance may point at a given cache directory at a time (enforced via the database file lock on metadata.redb). Attempting to construct a second instance while another is alive returns an error.StreamingManager::entry_count() now returns the count of entries currently warm in the in-memory hot cache, not the total number of entries persisted on disk. When the cache has fewer entries than the configured capacity, this equals the previous value; once capacity is exceeded, cold entries remain reachable via get but are not counted here.async_trait with native async functions in traits (RPITIT) for CacheManager, StreamingCacheManager, and Middleware traitsCacheAwareRateLimiter::until_key_ready now returns Pin<Box<dyn Future>> for dyn-compatibilityasync-trait dependencywarn to debug levelmodify_response_before_caching is now pub on HttpCacheOptionsStreamingManager now persists cache entries across service restarts (#159). Previously the key→content mapping was only kept in memory, so cached bodies on disk became unreachable orphans after restart.Set-Cookie, Via, Link) are now preserved correctly when merging headers from revalidation responses. Previously HttpResponse::update_headers, the streaming conditional_fetch Fresh/304 merges, and the streaming handle_not_modified path all lost or duplicated values for same-named headers.conditional_fetch 200 branch now checks should_cache_response before cachingmatches flag from BeforeRequest::Stalemodify_response_before_caching now called at correct point in streaming cache pathsmodify_response and manager.putOnlyIfCached 504 body now empty (consistent between streaming and non-streaming)url-standard feature flag as the new default URL implementation using the url crate
url-standard feature flag as the new default URL implementation using the url crateCACacheManager and MokaManager (reads legacy bincode data, writes postcard)StreamingManager rewritten to use cacache for disk storage with moka for metadata tracking and TinyLFU evictionhttp-cache-semantics from 2.1.0 to 3.0.0foyer to 0.22.3rand to 0.10.0url crate is now optional behind url-standard feature (enabled by default)runtime module, streaming no longer requires runtime-specific codeCacheMode enum variant matching logicempty_body method to StreamingCacheManager trait for creating empty body responses
empty_body method to StreamingCacheManager trait for creating empty body responsesget_ref_count method to ContentRefCounter for non-mutating reference count checksFoyerManager cache backend using foyer for hybrid in-memory and disk cachingmanager-foyer feature flag for enabling FoyerManagermanager-cacache-bincode and manager-moka-bincode feature flags for legacy bincode serializationurl-ada feature flag for using WHATWG-compliant ada-url as an alternative to the url crateurl_parse, url_set_path, url_set_query, url_hostname, url_host_str helper functions for URL operationsStreamingManager now wraps ContentRefCounter in Arc to ensure all clones share the same stateAcquire/Release/AcqRel) instead of Relaxedcacache-smol and cacache-tokio features in favor of tokio-only runtimecacache dependency now uses tokio-runtime by defaultremove_ref using atomic compare_exchange loop to prevent TOCTOU bugsStreamingManager is cloneddelete where reference count was decremented but not restored on non-orphaned contentdelete by using non-mutating get_ref_count instead of remove/add patternmodify_response field to HttpCacheOptions for modifying responses before storing in cache
modify_response field to HttpCacheOptions for modifying responses before storing in cachehttp-headers-compat feature flag for header compatibility optionsmetadata field to HttpResponse for storing arbitrary data with cached responsesmetadata_provider function to HttpCacheOptions for computing metadata on cache storeHttpHeaders serialization and insert behavior for bincode compatibilitymax_ttl field to HttpCacheOptions for controlling maximum cache duration
max_ttl field to HttpCacheOptions for controlling maximum cache durationDuration type in max_ttl field for better ergonomics and type safetyCacheMode::IgnoreRules moderate_limiter field to HttpCacheOptions for cache-aware rate limiting that only applies on cache missesCacheAwareRateLimiter trait for implementing rate limiting strategiesDomainRateLimiter for per-domain rate limiting using governorDirectRateLimiter for global rate limiting using governorrate-limiting feature flag for optional rate limiting functionalityStreamingManager with configurable size and entry limitsRwLock for better async performancelru cratemax_ttl implementation automatically enforces cache duration limits by modifying response cache-control headersmax_ttl usage across all cache modesStreamingCacheConfig simplified to essential configuration options:
max_cache_size: Optional cache size limit for LRU evictionmax_entries: Optional entry count limit for LRU evictionstreaming_buffer_size: Buffer size for streaming operations (default: 8192)StreamingManager implementation focused on core functionality and maintainabilityNew streaming cache architecture for handling large HTTP responses without buffering entirely in memory
StreamingCacheManager trait for streaming-aware cache backendsHttpCacheStreamInterface trait for composable streaming middleware patternsHttpStreamingCache struct for managing streaming cache operationsStreamingManager implementation using file-based storageStreamingBody type for handling both buffered and streaming scenariosCacheAnalysis struct for better separation of cache decision logicresponse_cache_mode_fn field to HttpCacheOptions for per-response cache mode overridesstreaming, streaming-tokio, streaming-smolMiddleware trait for better composabilitycacache-async-std feature to cacache-smol for consistencyremove_opts field to CACacheManager struct. This field is an instance of cacache::RemoveOpts that allows for customization of the removal options when
remove_opts field to CACacheManager struct. This field is an instance of cacache::RemoveOpts that allows for customization of the removal options when deleting items from the cache.
MSRV is now 1.82.0
Fixed missing implementation of CacheMode::Reload variant logic.
Fixed missing implementation of CacheMode::Reload variant logic.
MSRV is now 1.81.1
Updated the minimum versions of the following dependencies:
cache_status_headers field to HttpCacheOptions struct. This field is a boolean that determines if the cache status headers should be added to the resp
cache_status_headers field to HttpCacheOptions struct. This field is a boolean that determines if the cache status headers should be added to the response.Updated the minimum versions of the following dependencies:
overridden_cache_mode method to Middleware trait. This method allows for overriding any cache mode set in the configuration, including cache_mode_fn.
overridden_cache_mode method to Middleware trait. This method allows for overriding any cache mode set in the configuration, including cache_mode_fn.
Derive Default for the CacheMode enum with the mode Default selected to be used.
cache_mode_fn field to HttpCacheOptions struct. This is a closure that takes a &http::Parts and returns a CacheMode enum variant. This allows for the
cache_mode_fn field to HttpCacheOptions struct. This is a closure that takes a &http::request::Parts and returns a CacheMode enum variant. This allows for the overriding of cache mode on a per-request basis.
cache_bust field to HttpCacheOptions struct. This is a closure that takes http::request::Parts, Option<CacheKey>, the default cache key (&str) and returns Vec<String> of keys to bust the cache for.
can_cache_request method to HttpCache struct. This can be used by client implementations to determine if the request should be cached.
can_cache_request method to HttpCache struct. This can be used by client implementations to determine if the request should be cached.
run_no_cache method to HttpCache struct. This should be run by client implementations if the request is determined to not be cached.
IgnoreRules variant to the CacheMode enum. This mode will ignore the HTTP headers and always store a response given it was a 200 response. It will als
IgnoreRules variant to the CacheMode enum. This mode will ignore the HTTP headers and always store a response given it was a 200 response. It will also ignore the staleness when retrieving a response from the cache, so expiration of the cached response will need to be handled manually. If there was no cached response it will create a normal request, and will update the cache with the response.cacache-async-std feature, which enables async_std runtime support in the cacache backend manager. This feature is enabled by default.
cacache-async-std feature, which enables async_std runtime support in the cacache backend manager. This feature is enabled by default.
cacache-tokio feature, which enables tokio runtime support in the cacache backend manager. This feature is disabled by default.
CacheKey type, a closure that takes [http::Parts] and returns a [String].
CacheKey type, a closure that takes [http::request::Parts] and returns a [String].
HttpCacheOptions struct that contains the cache key (CacheKey) and the cache options (CacheOptions).
CacheManager trait get, put, and delete methods now require a cache_key argument rather than method and url arguments. This allows for custom keys to be specified.
Both the CACacheManager trait and MokaManager implementation have been updated to reflect the above change.
Updated the minimum versions of the following dependencies:
CACacheManager field path has changed to std::PathBuf
MSRV is now 1.66.1
CACacheManager field path has changed to std::path::PathBuf
Updated the minimum versions of the following dependencies:
BadVersion error type for unknown http versions.
BoxError type alias for Box<dyn std::error::Error + Send + Sync>.
BadVersion error type for unknown http versions.
BadHeader error type for bad http header values.
CacheError enum.
The following dependencies:
CacheError enum has been replaced in function by Box<dyn std::error::Error + Send + Sync>.
Result typedef is now std::result::Result<T, BoxError>.
Error type for the TryFrom implentation for the HttpVersion struct is now BoxError containing a BadVersion error.
CacheManager trait put method now returns Result<(), BoxError>.
Updated the minimum versions of the following dependencies:
Set conditional check for CacheError::Bincode to cfg(feature = "bincode")
CacheError::Bincode to cfg(feature = "bincode")Updated the minimum versions of the following dependencies:
MSRV is now 1.63.0
Updated the minimum versions of the following dependencies:
Updated the minimum versions of the following dependencies:
Updated the minimum versions of the following dependencies:
Updated the minimum versions of the following dependencies:
MSRV is now 1.62.1
Updated the minimum versions of the following dependencies:
Updated the minimum versions of the following dependencies:
MSRV is now 1.60.0
Updated the minimum versions of the following dependencies:
Added derive Eq to HttpVersion enum.
Eq to HttpVersion enum.Updated the minimum versions of the following dependencies:
The CacheManager trait is now implemented directly against the MokaManager struct rather than Arc . The Arc is now internal to the MokaManager struct
The CacheManager trait is now implemented directly against the MokaManager struct rather than Arc<MokaManager>. The Arc is now internal to the MokaManager struct as part of the cache field.
Updated the minimum versions of the following dependencies:
Updated the minimum versions of the following dependencies:
This changelog to keep a record of notable changes to the project.
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Your coding agent can read these notes before it upgrades. Set up the MCP server →