updated docs and readmes

Author: 06chaynes

docs/book.toml

@@ -1,6 +1,5 @@
 [book]
 authors = ["Christian Haynes"]
 language = "en"
-multilingual = false
 src = "src"
 title = "http-cache"

docs/src/SUMMARY.md

@@ -16,5 +16,6 @@
 - [Backend Cache Manager Implementations](./managers/managers.md)
   - [cacache](./managers/cacache.md)
   - [moka](./managers/moka.md)
+  - [foyer](./managers/foyer.md)
   - [quick_cache](./managers/quick-cache.md)
   - [streaming_cache](./managers/streaming_cache.md)

docs/src/cache-modes.md

@@ -68,7 +68,7 @@ let cache = HttpCache {
 ```rust
 // Respect server headers but limit cache duration to 1 hour maximum
 let options = HttpCacheOptions {
-    max_ttl: Some(Duration::from_hours(1)),
+    max_ttl: Some(Duration::from_secs(3600)),
     ..Default::default()
 };
 let cache = HttpCache {
@@ -360,7 +360,7 @@ let options = HttpCacheOptions {
     })),
 
     // Global cache duration limit
-    max_ttl: Some(Duration::from_hours(24)),
+    max_ttl: Some(Duration::from_secs(86400)),
 
     // Enable cache status headers for debugging
     cache_status_headers: true,

docs/src/clients/reqwest.md

@@ -12,25 +12,29 @@ cargo add http-cache-reqwest
 
 - `manager-cacache`: (default) Enables the [`CACacheManager`](https://docs.rs/http-cache/latest/http_cache/struct.CACacheManager.html) backend cache manager.
 - `manager-moka`: Enables the [`MokaManager`](https://docs.rs/http-cache/latest/http_cache/struct.MokaManager.html) backend cache manager.
+- `manager-foyer`: Enables the [`FoyerManager`](https://docs.rs/http-cache/latest/http_cache/struct.FoyerManager.html) backend cache manager.
 - `streaming`: Enables streaming cache support for memory-efficient handling of large response bodies.
+- `rate-limiting`: Enables cache-aware rate limiting functionality.
+- `url-ada`: Enables ada-url for URL parsing.
 
 ## Usage
 
-In the following example we will construct our client using the builder provided by [`reqwest_middleware`](https://github.com/TrueLayer/reqwest-middleware) with our cache struct from [`http-cache-reqwest`](https://github.com/06chaynes/http-cache/tree/latest/http-cache-reqwest). This example will use the default mode, default cacache manager, and default http cache options.
+In the following example we will construct our client using the builder provided by [`reqwest_middleware`](https://github.com/TrueLayer/reqwest-middleware) with our cache struct from [`http-cache-reqwest`](https://github.com/06chaynes/http-cache/tree/main/http-cache-reqwest). This example will use the default mode, default cacache manager, and default http cache options.
 
 After constructing our client, we will make a request to the [MDN Caching Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching) which should result in an object stored in cache on disk.
 
 ```rust
 use reqwest::Client;
 use reqwest_middleware::{ClientBuilder, Result};
 use http_cache_reqwest::{Cache, CacheMode, CACacheManager, HttpCache, HttpCacheOptions};
+use std::path::PathBuf;
 
 #[tokio::main]
 async fn main() -> Result<()> {
     let client = ClientBuilder::new(Client::new())
         .with(Cache(HttpCache {
           mode: CacheMode::Default,
-          manager: CACacheManager::default(),
+          manager: CACacheManager::new(PathBuf::from("./cache"), false),
           options: HttpCacheOptions::default(),
         }))
         .build();
@@ -57,7 +61,7 @@ http-cache-reqwest = { version = "1.0", features = ["streaming"] }
 
 ```rust
 use http_cache::StreamingManager;
-use http_cache_reqwest::StreamingCache;
+use http_cache_reqwest::{StreamingCache, CacheMode};
 use reqwest::Client;
 use reqwest_middleware::ClientBuilder;
 use std::path::PathBuf;
@@ -66,9 +70,9 @@ use futures_util::StreamExt;
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
     // Create streaming cache manager
-    let cache_manager = StreamingManager::new(PathBuf::from("./cache"), true);
-    let streaming_cache = StreamingCache::new(cache_manager);
-    
+    let cache_manager = StreamingManager::new(PathBuf::from("./cache"));
+    let streaming_cache = StreamingCache::new(cache_manager, CacheMode::Default);
+
     // Build client with streaming cache
     let client = ClientBuilder::new(Client::new())
         .with(streaming_cache)
@@ -117,13 +121,14 @@ This ensures that your application continues to work seamlessly even when using
 use reqwest::Client;
 use reqwest_middleware::ClientBuilder;
 use http_cache_reqwest::{Cache, CacheMode, CACacheManager, HttpCache, HttpCacheOptions};
+use std::path::PathBuf;
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
     let client = ClientBuilder::new(Client::new())
         .with(Cache(HttpCache {
             mode: CacheMode::Default,
-            manager: CACacheManager::default(),
+            manager: CACacheManager::new(PathBuf::from("./cache"), false),
             options: HttpCacheOptions::default(),
         }))
         .build();
@@ -152,13 +157,14 @@ use reqwest_middleware::ClientBuilder;
 use http_cache_reqwest::{Cache, CacheMode, CACacheManager, HttpCache, HttpCacheOptions};
 use futures_util::stream;
 use bytes::Bytes;
+use std::path::PathBuf;
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
     let client = ClientBuilder::new(Client::new())
         .with(Cache(HttpCache {
             mode: CacheMode::Default,
-            manager: CACacheManager::default(),
+            manager: CACacheManager::new(PathBuf::from("./cache"), false),
             options: HttpCacheOptions::default(),
         }))
         .build();

docs/src/clients/surf.md

@@ -12,10 +12,11 @@ cargo add http-cache-surf
 
 - `manager-cacache`: (default) Enables the [`CACacheManager`](https://docs.rs/http-cache/latest/http_cache/struct.CACacheManager.html) backend cache manager.
 - `manager-moka`: Enables the [`MokaManager`](https://docs.rs/http-cache/latest/http_cache/struct.MokaManager.html) backend cache manager.
+- `manager-foyer`: Enables the [`FoyerManager`](https://docs.rs/http-cache/latest/http_cache/struct.FoyerManager.html) backend cache manager.
 
 ## Usage
 
-In the following example we will construct our client with our cache struct from [`http-cache-surf`](https://github.com/06chaynes/http-cache/tree/latest/http-cache-surf). This example will use the default mode, default cacache manager, and default http cache options.
+In the following example we will construct our client with our cache struct from [`http-cache-surf`](https://github.com/06chaynes/http-cache/tree/main/http-cache-surf). This example will use the default mode, default cacache manager, and default http cache options.
 
 After constructing our client, we will make a request to the [MDN Caching Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching) which should result in an object stored in cache on disk.
 
@@ -24,16 +25,17 @@ use http_cache_surf::{Cache, CacheMode, CACacheManager, HttpCache, HttpCacheOpti
 use surf::Client;
 use macro_rules_attribute::apply;
 use smol_macros::main;
+use std::path::PathBuf;
 
 #[apply(main!)]
 async fn main() -> surf::Result<()> {
     let client = Client::new()
         .with(Cache(HttpCache {
           mode: CacheMode::Default,
-          manager: CACacheManager::default(),
+          manager: CACacheManager::new(PathBuf::from("./cache"), false),
           options: HttpCacheOptions::default(),
         }));
-    
+
     client
         .get("https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching")
         .await?;

docs/src/clients/tower.md

@@ -12,7 +12,10 @@ cargo add http-cache-tower
 
 - `manager-cacache`: (default) Enables the [`CACacheManager`](https://docs.rs/http-cache/latest/http_cache/struct.CACacheManager.html) backend cache manager.
 - `manager-moka`: Enables the [`MokaManager`](https://docs.rs/http-cache/latest/http_cache/struct.MokaManager.html) backend cache manager.
+- `manager-foyer`: Enables the [`FoyerManager`](https://docs.rs/http-cache/latest/http_cache/struct.FoyerManager.html) backend cache manager.
 - `streaming`: Enables streaming cache support for memory-efficient handling of large response bodies.
+- `rate-limiting`: Enables cache-aware rate limiting functionality.
+- `url-ada`: Enables ada-url for URL parsing.
 
 ## Basic Usage
 
@@ -115,10 +118,11 @@ use http_cache::CACacheManager;
 use hyper_util::client::legacy::Client;
 use hyper_util::rt::TokioExecutor;
 use tower::{ServiceBuilder, ServiceExt};
+use std::path::PathBuf;
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let cache_manager = CACacheManager::default();
+    let cache_manager = CACacheManager::new(PathBuf::from("./cache"), false);
     let cache_layer = HttpCacheLayer::new(cache_manager);
 
     let client = Client::builder(TokioExecutor::new()).build_http();

docs/src/clients/ureq.md

@@ -6,17 +6,20 @@ Since ureq is a synchronous HTTP client, this implementation uses the [smol](htt
 
 ## Features
 
-- `json` - Enables JSON request/response support via `send_json()` and `into_json()` methods (requires `serde_json`)
-- `manager-cacache` - Enable [cacache](https://docs.rs/cacache/) cache manager (default)
-- `manager-moka` - Enable [moka](https://docs.rs/moka/) cache manager
+- `manager-cacache` (default): Enable [cacache](https://docs.rs/cacache/) cache manager.
+- `manager-moka`: Enable [moka](https://docs.rs/moka/) cache manager.
+- `manager-foyer`: Enable [foyer](https://github.com/foyer-rs/foyer) hybrid in-memory + disk cache manager.
+- `json`: Enables JSON request/response support via `send_json()` and `into_json()` methods (requires `serde_json`).
+- `rate-limiting`: Enable cache-aware rate limiting functionality.
+- `url-ada`: Enable ada-url for URL parsing.
 
 ## Basic Usage
 
 Add the dependency to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-http-cache-ureq = "1.0.0-alpha.1"
+http-cache-ureq = "1.0"
 ```
 
 Use the `CachedAgent` builder to create a cached HTTP client:
@@ -54,7 +57,7 @@ Enable the `json` feature to send and parse JSON data:
 
 ```toml
 [dependencies]
-http-cache-ureq = { version = "1.0.0-alpha.1", features = ["json"] }
+http-cache-ureq = { version = "1.0", features = ["json"] }
 ```
 
 ```rust
@@ -141,7 +144,7 @@ Use the Moka in-memory cache:
 
 ```toml
 [dependencies]
-http-cache-ureq = { version = "1.0.0-alpha.1", features = ["manager-moka"] }
+http-cache-ureq = { version = "1.0", features = ["manager-moka"] }
 ```
 
 ```rust

docs/src/development/supporting-a-backend-cache-manager.md

@@ -102,7 +102,9 @@ pub struct CacheMetadata {
 }
 ```
 
-This struct derives [serde](https://github.com/serde-rs/serde) Deserialize and Serialize to ease the serialization and deserialization with JSON for the streaming metadata, and [bincode](https://github.com/bincode-org/bincode) for the traditional Store struct.
+This struct derives [serde](https://github.com/serde-rs/serde) Deserialize and Serialize to ease the serialization and deserialization with JSON for the streaming metadata, and [postcard](https://github.com/jamesmunns/postcard) for the traditional Store struct.
+
+**Important:** The `bincode` serialization format has been deprecated due to RUSTSEC-2025-0141 (bincode is unmaintained). New implementations should use `postcard` instead. The library still supports bincode through legacy feature flags (`manager-cacache-bincode`, `manager-moka-bincode`) for backward compatibility, but these will be removed in the next major version.
 
 ### Part Two: Implementing the traditional `CacheManager` trait
 
@@ -126,7 +128,7 @@ impl CacheManager for CACacheManager {
         cache_key: &str,
     ) -> Result<Option<(HttpResponse, CachePolicy)>> {
         let store: Store = match cacache::read(&self.path, cache_key).await {
-            Ok(d) => bincode::deserialize(&d)?,
+            Ok(d) => postcard::from_bytes(&d)?,
             Err(_e) => {
                 return Ok(None);
             }
@@ -141,7 +143,7 @@ impl CacheManager for CACacheManager {
         policy: CachePolicy,
     ) -> Result<HttpResponse> {
         let data = Store { response, policy };
-        let bytes = bincode::serialize(&data)?;
+        let bytes = postcard::to_allocvec(&data)?;
         cacache::write(&self.path, cache_key, bytes).await?;
         Ok(data.response)
     }
@@ -273,6 +275,7 @@ async fn put<B>(
     response: Response<B>,
     policy: CachePolicy,
     _request_url: Url,
+    _metadata: Option<Vec<u8>>,
 ) -> Result<Response<Self::Body>>
 where
     B: http_body::Body + Send + 'static,

docs/src/development/supporting-an-http-client.md

@@ -12,7 +12,7 @@ The [`Middleware`](https://docs.rs/http-cache/latest/http_cache/trait.Middleware
 - `policy`: returns a [`CachePolicy`](https://docs.rs/http-cache-semantics/latest/http_cache_semantics/struct.CachePolicy.html) with default options for the given `HttpResponse`
 - `policy_with_options`: returns a [`CachePolicy`](https://docs.rs/http-cache-semantics/latest/http_cache_semantics/struct.CachePolicy.html) with the provided [`CacheOptions`](https://docs.rs/http-cache-semantics/latest/http_cache_semantics/struct.CacheOptions.html) for the given `HttpResponse`
 - `update_headers`: updates the request headers with the provided [`http::request::Parts`](https://docs.rs/http/latest/http/request/struct.Parts.html)
-- `force_no_cache`: overrides the `Cache-Control` header to 'no-cache' derective
+- `force_no_cache`: overrides the `Cache-Control` header to 'no-cache' directive
 - `parts`: returns the [`http::request::Parts`](https://docs.rs/http/latest/http/request/struct.Parts.html) from the request
 - `url`: returns the requested [`Url`](https://docs.rs/url/latest/url/struct.Url.html)
 - `method`: returns the method of the request as a `String`
@@ -36,7 +36,7 @@ The `update_headers` method is used to update the request headers with the provi
 
 ### The `force_no_cache` method
 
-The `force_no_cache` method is used to override the `Cache-Control` header to 'no-cache' derective. This is used to allow caching but force revalidation before resuse.
+The `force_no_cache` method is used to override the `Cache-Control` header to 'no-cache' directive. This is used to allow caching but force revalidation before reuse.
 
 ### The `parts` method
 
@@ -135,7 +135,7 @@ fn update_headers(&mut self, parts: &Parts) -> Result<()> {
 }
 ```
 
-The `force_no_cache` method is used to override the `Cache-Control` header in the request to 'no-cache' derective. This is used to allow caching but force revalidation before resuse.
+The `force_no_cache` method is used to override the `Cache-Control` header in the request to 'no-cache' directive. This is used to allow caching but force revalidation before reuse.
 
 ```rust
 fn force_no_cache(&mut self) -> Result<()> {

docs/src/managers/cacache.md

@@ -26,16 +26,22 @@ cargo add http-cache-tower
 
 ## Working with the manager directly
 
-First construct your manager instance. This example will use the default cache directory.
+First construct your manager instance. You need to specify the cache directory and whether cache entries should be fully removed from disk.
 
 ```rust
-let manager = CACacheManager::default();
+use std::path::PathBuf;
+
+let manager = CACacheManager::new(PathBuf::from("./my-cache"), false);
 ```
 
-You can also specify the cache directory and if you want the cache entries to be removed fully from disk.
+The second argument (`remove_fully`) controls whether cached entries are completely removed from disk when deleted:
 
 ```rust
-let manager = CACacheManager::new("./my-cache".into(), true);
+// Keep cache metadata on delete (faster, uses more disk space)
+let manager = CACacheManager::new(PathBuf::from("./my-cache"), false);
+
+// Fully remove entries from disk on delete (slower, saves disk space)
+let manager = CACacheManager::new(PathBuf::from("./my-cache"), true);
 ```
 
 You can attempt to retrieve a record from the cache using the `get` method. This method accepts a `&str` as the cache key and returns an `Result<Option<(HttpResponse, CachePolicy)>, BoxError>`.