Skip to main content

http_cache_tower_server/
lib.rs

1//! Server-side HTTP response caching middleware for Tower.
2//!
3//! This crate provides Tower middleware for caching HTTP responses on the server side.
4//! Unlike client-side caching, this middleware caches your own application's responses
5//! to reduce load and improve performance.
6//!
7//! # Key Features
8//!
9//! - Response-first architecture: Caches based on response headers, not requests
10//! - Preserves request context: Maintains all request extensions (path params, state, etc.)
11//! - Handler-centric: Calls the handler first, then decides whether to cache
12//! - RFC 7234 compliant: Respects Cache-Control, Vary, and other standard headers
13//! - Reuses existing infrastructure: Leverages `CacheManager` trait from `http-cache`
14//!
15//! # Example
16//!
17//! ```rust
18//! use http::{Request, Response};
19//! use http_body_util::Full;
20//! use bytes::Bytes;
21//! use http_cache_tower_server::ServerCacheLayer;
22//! use tower::{Service, Layer};
23//! # use http_cache::{CacheManager, HttpResponse, HttpVersion};
24//! # use http_cache_semantics::CachePolicy;
25//! # use std::collections::HashMap;
26//! # use std::sync::{Arc, Mutex};
27//! #
28//! # #[derive(Clone)]
29//! # struct MemoryCacheManager {
30//! #     store: Arc<Mutex<HashMap<String, (HttpResponse, CachePolicy)>>>,
31//! # }
32//! #
33//! # impl MemoryCacheManager {
34//! #     fn new() -> Self {
35//! #         Self { store: Arc::new(Mutex::new(HashMap::new())) }
36//! #     }
37//! # }
38//! #
39//! # impl CacheManager for MemoryCacheManager {
40//! #     async fn get(&self, cache_key: &str) -> http_cache::Result<Option<(HttpResponse, CachePolicy)>> {
41//! #         Ok(self.store.lock().unwrap().get(cache_key).cloned())
42//! #     }
43//! #     async fn put(&self, cache_key: String, res: HttpResponse, policy: CachePolicy) -> http_cache::Result<HttpResponse> {
44//! #         self.store.lock().unwrap().insert(cache_key, (res.clone(), policy));
45//! #         Ok(res)
46//! #     }
47//! #     async fn delete(&self, cache_key: &str) -> http_cache::Result<()> {
48//! #         self.store.lock().unwrap().remove(cache_key);
49//! #         Ok(())
50//! #     }
51//! # }
52//!
53//! # tokio_test::block_on(async {
54//! let manager = MemoryCacheManager::new();
55//! let layer = ServerCacheLayer::new(manager);
56//!
57//! // Apply the layer to your Tower service
58//! let service = tower::service_fn(|_req: Request<Full<Bytes>>| async {
59//!     Ok::<_, std::io::Error>(
60//!         Response::builder()
61//!             .header("cache-control", "max-age=60")
62//!             .body(Full::new(Bytes::from("Hello, World!")))
63//!             .unwrap()
64//!     )
65//! });
66//!
67//! let mut cached_service = layer.layer(service);
68//! # });
69//! ```
70//!
71//! # Vary Header Support
72//!
73//! This cache enforces `Vary` headers using `http-cache-semantics`. When a response includes
74//! a `Vary` header, subsequent requests must have matching header values to receive the cached
75//! response. Requests with different header values will result in cache misses.
76//!
77//! For example, if a response has `Vary: Accept-Language`, a cached English response won't be
78//! served to a request with `Accept-Language: de`.
79//!
80//! # Security Warnings
81//!
82//! This is a **shared cache** - cached responses are served to ALL users. Improper configuration
83//! can leak user-specific data between different users.
84//!
85//! ## Authorization and Authentication
86//!
87//! This cache does not check for `Authorization` headers or session cookies in requests.
88//! Caching authenticated endpoints without proper cache key differentiation will cause
89//! user A's response to be served to user B.
90//!
91//! **Do NOT cache authenticated endpoints** unless you use a `CustomKeyer` that includes
92//! the user or session identifier in the cache key:
93//!
94//! ```rust
95//! # use http_cache_tower_server::CustomKeyer;
96//! # use http::Request;
97//! // Example: Include session ID in cache key
98//! let keyer = CustomKeyer::new(|req: &Request<()>| {
99//!     let session = req.headers()
100//!         .get("cookie")
101//!         .and_then(|v| v.to_str().ok())
102//!         .and_then(|c| extract_session_id(c))
103//!         .unwrap_or("anonymous");
104//!     format!("{} {} session:{}", req.method(), req.uri().path(), session)
105//! });
106//! # fn extract_session_id(cookie: &str) -> Option<&str> { None }
107//! ```
108//!
109//! ## General Security Considerations
110//!
111//! - Never cache responses containing user-specific data without user-specific cache keys
112//! - Validate cache keys to prevent cache poisoning attacks
113//! - Be careful with header-based caching due to header injection risks
114//! - Consider the `private` Cache-Control directive for user-specific responses (automatically rejected by this cache)
115
116#![warn(missing_docs)]
117#![deny(unsafe_code)]
118
119use bytes::Bytes;
120use http::{Request, Response, header::HeaderValue};
121use http_body::{Body as HttpBody, Frame};
122use http_body_util::BodyExt;
123use http_cache::{CacheManager, HttpResponse, HttpVersion};
124use http_cache_semantics::{BeforeRequest, CachePolicy};
125use serde::{Deserialize, Serialize};
126use std::collections::HashMap;
127use std::error::Error as StdError;
128use std::pin::Pin;
129use std::sync::Arc;
130use std::sync::atomic::{AtomicU64, Ordering};
131use std::task::{Context, Poll};
132use std::time::{Duration, SystemTime};
133use tower::{Layer, Service};
134
135type BoxError = Box<dyn StdError + Send + Sync>;
136
137/// Cache performance metrics.
138///
139/// Tracks hits, misses, and stores for monitoring cache effectiveness.
140#[derive(Debug, Default)]
141pub struct CacheMetrics {
142    /// Number of cache hits.
143    pub hits: AtomicU64,
144    /// Number of cache misses.
145    pub misses: AtomicU64,
146    /// Number of responses stored in cache.
147    pub stores: AtomicU64,
148    /// Number of responses skipped (too large, not cacheable, etc.).
149    pub skipped: AtomicU64,
150}
151
152impl CacheMetrics {
153    /// Create new metrics instance.
154    pub fn new() -> Self {
155        Self::default()
156    }
157
158    /// Calculate cache hit rate as a percentage (0.0 to 1.0).
159    pub fn hit_rate(&self) -> f64 {
160        let hits = self.hits.load(Ordering::Relaxed);
161        let total = hits + self.misses.load(Ordering::Relaxed);
162        if total == 0 { 0.0 } else { hits as f64 / total as f64 }
163    }
164
165    /// Reset all metrics to zero.
166    pub fn reset(&self) {
167        self.hits.store(0, Ordering::Relaxed);
168        self.misses.store(0, Ordering::Relaxed);
169        self.stores.store(0, Ordering::Relaxed);
170        self.skipped.store(0, Ordering::Relaxed);
171    }
172}
173
174/// A trait for generating cache keys from HTTP requests.
175pub trait Keyer: Clone + Send + Sync + 'static {
176    /// Generate a cache key for the given request.
177    fn cache_key<B>(&self, req: &Request<B>) -> String;
178}
179
180/// Default keyer that uses HTTP method and path.
181///
182/// Generates keys in the format: `{METHOD} {path}`
183///
184/// # Example
185///
186/// ```
187/// # use http::Request;
188/// # use http_cache_tower_server::{Keyer, DefaultKeyer};
189/// let keyer = DefaultKeyer;
190/// let req = Request::get("/users/123").body(()).unwrap();
191/// let key = keyer.cache_key(&req);
192/// assert_eq!(key, "GET /users/123");
193/// ```
194#[derive(Debug, Clone, Copy, Default)]
195pub struct DefaultKeyer;
196
197impl Keyer for DefaultKeyer {
198    fn cache_key<B>(&self, req: &Request<B>) -> String {
199        format!("{} {}", req.method(), req.uri().path())
200    }
201}
202
203/// Keyer that includes query parameters in the cache key.
204///
205/// Generates keys in the format: `{METHOD} {path}?{query}`
206///
207/// # Example
208///
209/// ```
210/// # use http::Request;
211/// # use http_cache_tower_server::{Keyer, QueryKeyer};
212/// let keyer = QueryKeyer;
213/// let req = Request::get("/users?page=1").body(()).unwrap();
214/// let key = keyer.cache_key(&req);
215/// assert_eq!(key, "GET /users?page=1");
216/// ```
217#[derive(Debug, Clone, Copy, Default)]
218pub struct QueryKeyer;
219
220impl Keyer for QueryKeyer {
221    fn cache_key<B>(&self, req: &Request<B>) -> String {
222        format!("{} {}", req.method(), req.uri())
223    }
224}
225
226/// Custom keyer that uses a user-provided function.
227///
228/// Use this when the default method+path keying is insufficient, such as:
229/// - Content negotiation based on request headers (Accept-Language, Accept-Encoding)
230/// - User-specific or session-specific caching
231/// - Query parameter normalization
232///
233/// # Examples
234///
235/// Basic custom format:
236///
237/// ```
238/// # use http::Request;
239/// # use http_cache_tower_server::{Keyer, CustomKeyer};
240/// let keyer = CustomKeyer::new(|req: &Request<()>| {
241///     format!("custom-{}-{}", req.method(), req.uri().path())
242/// });
243/// let req = Request::get("/users").body(()).unwrap();
244/// let key = keyer.cache_key(&req);
245/// assert_eq!(key, "custom-GET-/users");
246/// ```
247///
248/// Content negotiation (Accept-Language):
249///
250/// ```
251/// # use http::Request;
252/// # use http_cache_tower_server::{Keyer, CustomKeyer};
253/// let keyer = CustomKeyer::new(|req: &Request<()>| {
254///     let lang = req.headers()
255///         .get("accept-language")
256///         .and_then(|v| v.to_str().ok())
257///         .and_then(|s| s.split(',').next())
258///         .unwrap_or("en");
259///     format!("{} {} lang:{}", req.method(), req.uri().path(), lang)
260/// });
261/// ```
262///
263/// User-specific caching (session-based):
264///
265/// ```
266/// # use http::Request;
267/// # use http_cache_tower_server::{Keyer, CustomKeyer};
268/// let keyer = CustomKeyer::new(|req: &Request<()>| {
269///     let user_id = req.headers()
270///         .get("x-user-id")
271///         .and_then(|v| v.to_str().ok())
272///         .unwrap_or("anonymous");
273///     format!("{} {} user:{}", req.method(), req.uri().path(), user_id)
274/// });
275/// ```
276///
277/// # Security Warning
278///
279/// When caching user-specific or session-specific data, ensure the user/session identifier
280/// is included in the cache key. Failure to do so will cause responses from one user to be
281/// served to other users.
282#[derive(Clone)]
283pub struct CustomKeyer<F> {
284    func: F,
285}
286
287impl<F> CustomKeyer<F> {
288    /// Create a new custom keyer with the given function.
289    pub fn new(func: F) -> Self {
290        Self { func }
291    }
292}
293
294impl<F> Keyer for CustomKeyer<F>
295where
296    F: Fn(&Request<()>) -> String + Clone + Send + Sync + 'static,
297{
298    fn cache_key<B>(&self, req: &Request<B>) -> String {
299        // Create a temporary request with the same parts but () body
300        let mut temp_req = Request::builder()
301            .method(req.method())
302            .uri(req.uri())
303            .version(req.version())
304            .body(())
305            .expect("request built from valid parts");
306
307        // Copy headers for content negotiation support
308        *temp_req.headers_mut() = req.headers().clone();
309
310        (self.func)(&temp_req)
311    }
312}
313
314/// Configuration options for server-side caching.
315#[derive(Debug, Clone)]
316pub struct ServerCacheOptions {
317    /// Default TTL when response has no Cache-Control header.
318    pub default_ttl: Option<Duration>,
319
320    /// Maximum TTL, even if response specifies longer.
321    pub max_ttl: Option<Duration>,
322
323    /// Minimum TTL, even if response specifies shorter.
324    pub min_ttl: Option<Duration>,
325
326    /// Whether to add X-Cache headers (HIT/MISS).
327    pub cache_status_headers: bool,
328
329    /// Maximum response body size to cache (in bytes).
330    pub max_body_size: usize,
331
332    /// Whether to cache responses without explicit Cache-Control.
333    pub cache_by_default: bool,
334
335    /// Whether to respect Vary header for content negotiation.
336    ///
337    /// When true (default), cached responses are only served if the request's
338    /// headers match those specified in the response's Vary header. This is
339    /// enforced via `http-cache-semantics`.
340    pub respect_vary: bool,
341
342    /// Whether to respect Authorization headers per RFC 9111 §3.5.
343    ///
344    /// When true (default), requests with `Authorization` headers are not cached
345    /// unless the response explicitly permits it via `public`, `s-maxage`, or
346    /// `must-revalidate` directives.
347    ///
348    /// This prevents accidental caching of authenticated responses that could
349    /// leak user-specific data to other users.
350    pub respect_authorization: bool,
351}
352
353impl Default for ServerCacheOptions {
354    fn default() -> Self {
355        Self {
356            default_ttl: Some(Duration::from_secs(60)),
357            max_ttl: Some(Duration::from_secs(3600)),
358            min_ttl: None,
359            cache_status_headers: true,
360            max_body_size: 128 * 1024 * 1024,
361            cache_by_default: false,
362            respect_vary: true,
363            respect_authorization: true,
364        }
365    }
366}
367
368/// A cached HTTP response with metadata.
369#[derive(Debug, Clone, Serialize, Deserialize)]
370pub struct CachedResponse {
371    /// Response status code.
372    pub status: u16,
373
374    /// Response headers (multiple values per key to preserve multi-valued headers).
375    pub headers: HashMap<String, Vec<String>>,
376
377    /// Response body bytes.
378    pub body: Vec<u8>,
379
380    /// When this response was cached.
381    pub cached_at: SystemTime,
382
383    /// Time-to-live duration.
384    pub ttl: Duration,
385
386    /// Optional vary headers for content negotiation.
387    pub vary: Option<Vec<String>>,
388}
389
390impl CachedResponse {
391    /// Check if this cached response is stale.
392    pub fn is_stale(&self) -> bool {
393        SystemTime::now()
394            .duration_since(self.cached_at)
395            .unwrap_or(Duration::MAX)
396            > self.ttl
397    }
398
399    /// Convert to an HTTP response.
400    pub fn into_response(
401        self,
402    ) -> Result<Response<Bytes>, Box<dyn std::error::Error + Send + Sync>> {
403        let mut builder = Response::builder().status(self.status);
404
405        for (key, values) in self.headers {
406            for value in values {
407                if let Ok(header_value) = HeaderValue::from_str(&value) {
408                    builder = builder.header(&key, header_value);
409                }
410            }
411        }
412
413        Ok(builder.body(Bytes::from(self.body))?)
414    }
415}
416
417/// Response body types.
418#[derive(Debug)]
419pub enum ResponseBody {
420    /// Cached response body.
421    Cached(Bytes),
422    /// Fresh response body.
423    Fresh(Bytes),
424    /// Uncacheable response body.
425    Uncacheable(Bytes),
426}
427
428impl HttpBody for ResponseBody {
429    type Data = Bytes;
430    type Error = BoxError;
431
432    fn poll_frame(
433        mut self: Pin<&mut Self>,
434        _cx: &mut Context<'_>,
435    ) -> Poll<Option<std::result::Result<Frame<Self::Data>, Self::Error>>> {
436        let bytes = match &mut *self {
437            ResponseBody::Cached(b)
438            | ResponseBody::Fresh(b)
439            | ResponseBody::Uncacheable(b) => {
440                std::mem::replace(b, Bytes::new())
441            }
442        };
443
444        if bytes.is_empty() {
445            Poll::Ready(None)
446        } else {
447            Poll::Ready(Some(Ok(Frame::data(bytes))))
448        }
449    }
450
451    fn is_end_stream(&self) -> bool {
452        match self {
453            ResponseBody::Cached(b)
454            | ResponseBody::Fresh(b)
455            | ResponseBody::Uncacheable(b) => b.is_empty(),
456        }
457    }
458}
459
460/// Tower layer for server-side HTTP response caching.
461///
462/// This layer should be placed AFTER routing: a layer applies only to the
463/// routes added before it, so routes added after it are not cached.
464///
465/// # Shared Cache Behavior
466///
467/// This implements a **shared cache** as defined in RFC 9111. Responses cached by this layer
468/// are served to all users making requests with matching cache keys. The cache automatically
469/// rejects responses with the `private` directive, but does not inspect `Authorization` headers
470/// or session cookies.
471///
472/// For authenticated or user-specific endpoints, either:
473/// - Set `Cache-Control: private` in responses (prevents caching)
474/// - Use a `CustomKeyer` that includes user/session identifiers in the cache key
475#[derive(Clone)]
476pub struct ServerCacheLayer<M, K = DefaultKeyer>
477where
478    M: CacheManager,
479    K: Keyer,
480{
481    manager: M,
482    keyer: K,
483    options: ServerCacheOptions,
484    metrics: Arc<CacheMetrics>,
485}
486
487impl<M> ServerCacheLayer<M, DefaultKeyer>
488where
489    M: CacheManager,
490{
491    /// Create a new cache layer with default options.
492    pub fn new(manager: M) -> Self {
493        Self {
494            manager,
495            keyer: DefaultKeyer,
496            options: ServerCacheOptions::default(),
497            metrics: Arc::new(CacheMetrics::new()),
498        }
499    }
500}
501
502impl<M, K> ServerCacheLayer<M, K>
503where
504    M: CacheManager,
505    K: Keyer,
506{
507    /// Create a cache layer with a custom keyer.
508    pub fn with_keyer(manager: M, keyer: K) -> Self {
509        Self {
510            manager,
511            keyer,
512            options: ServerCacheOptions::default(),
513            metrics: Arc::new(CacheMetrics::new()),
514        }
515    }
516
517    /// Set custom options.
518    pub fn with_options(mut self, options: ServerCacheOptions) -> Self {
519        self.options = options;
520        self
521    }
522
523    /// Get a reference to the cache metrics.
524    pub fn metrics(&self) -> &Arc<CacheMetrics> {
525        &self.metrics
526    }
527
528    /// Invalidate a specific cache entry by its key.
529    pub async fn invalidate(&self, cache_key: &str) -> Result<(), BoxError> {
530        self.manager.delete(cache_key).await
531    }
532
533    /// Invalidate cache entry for a specific request.
534    ///
535    /// Uses the configured keyer to generate the cache key from the request.
536    pub async fn invalidate_request<B>(
537        &self,
538        req: &Request<B>,
539    ) -> Result<(), BoxError> {
540        let cache_key = self.keyer.cache_key(req);
541        self.invalidate(&cache_key).await
542    }
543}
544
545impl<S, M, K> Layer<S> for ServerCacheLayer<M, K>
546where
547    M: CacheManager + Clone,
548    K: Keyer,
549{
550    type Service = ServerCacheService<S, M, K>;
551
552    fn layer(&self, inner: S) -> Self::Service {
553        ServerCacheService {
554            inner,
555            manager: self.manager.clone(),
556            keyer: self.keyer.clone(),
557            options: self.options.clone(),
558            metrics: self.metrics.clone(),
559        }
560    }
561}
562
563/// Tower service that implements response caching.
564#[derive(Clone)]
565pub struct ServerCacheService<S, M, K>
566where
567    M: CacheManager,
568    K: Keyer,
569{
570    inner: S,
571    manager: M,
572    keyer: K,
573    options: ServerCacheOptions,
574    metrics: Arc<CacheMetrics>,
575}
576
577impl<S, ReqBody, ResBody, M, K> Service<Request<ReqBody>>
578    for ServerCacheService<S, M, K>
579where
580    S: Service<Request<ReqBody>, Response = Response<ResBody>>
581        + Clone
582        + Send
583        + 'static,
584    S::Error: Into<BoxError>,
585    S::Future: Send + 'static,
586    M: CacheManager + Clone,
587    K: Keyer,
588    ReqBody: Send + 'static,
589    ResBody: HttpBody + Send + 'static,
590    ResBody::Data: Send,
591    ResBody::Error: Into<BoxError>,
592{
593    type Response = Response<ResponseBody>;
594    type Error = BoxError;
595    type Future = Pin<
596        Box<
597            dyn std::future::Future<
598                    Output = std::result::Result<Self::Response, Self::Error>,
599                > + Send,
600        >,
601    >;
602
603    fn poll_ready(
604        &mut self,
605        cx: &mut Context<'_>,
606    ) -> Poll<std::result::Result<(), Self::Error>> {
607        self.inner.poll_ready(cx).map_err(Into::into)
608    }
609
610    fn call(&mut self, req: Request<ReqBody>) -> Self::Future {
611        let manager = self.manager.clone();
612        let keyer = self.keyer.clone();
613        let options = self.options.clone();
614        let metrics = self.metrics.clone();
615        let mut inner = self.inner.clone();
616
617        Box::pin(async move {
618            // Store request parts for later use in should_cache
619            let (req_parts, req_body) = req.into_parts();
620
621            // Generate cache key from request parts
622            let temp_req = Request::from_parts(req_parts.clone(), ());
623            let cache_key = keyer.cache_key(&temp_req);
624
625            // Try to get from cache
626            if let Ok(Some((cached_resp, policy))) =
627                manager.get(&cache_key).await
628            {
629                // Deserialize cached response first
630                if let Ok(cached) =
631                    serde_json::from_slice::<CachedResponse>(&cached_resp.body)
632                {
633                    // Check freshness using both CachePolicy and our TTL tracking.
634                    // CachePolicy handles Vary header matching.
635                    // Our is_stale() handles the TTL we assigned (especially for cache_by_default).
636                    let before_req =
637                        policy.before_request(&req_parts, SystemTime::now());
638
639                    // Determine if response had explicit freshness directives
640                    // (max-age or s-maxage). If it only has "public" or other directives
641                    // without explicit TTL, we use our own TTL tracking.
642                    let has_explicit_ttl = cached
643                        .headers
644                        .get("cache-control")
645                        .is_some_and(|cc_values| {
646                            cc_values.iter().any(|cc| {
647                                cc.contains("max-age")
648                                    || cc.contains("s-maxage")
649                            })
650                        });
651
652                    let is_fresh = match before_req {
653                        BeforeRequest::Fresh(_) => {
654                            // CachePolicy says fresh - use it
655                            true
656                        }
657                        BeforeRequest::Stale { .. } => {
658                            // CachePolicy says stale. This could be due to:
659                            // 1. Vary header mismatch
660                            // 2. Time-based staleness per cache headers
661                            // 3. No explicit TTL (cache_by_default or public-only)
662                            //
663                            // For case 3, our TTL tracking is authoritative.
664                            // For cases 1-2, we should respect CachePolicy.
665                            if has_explicit_ttl {
666                                // Had explicit TTL - trust CachePolicy
667                                false
668                            } else {
669                                // No explicit TTL - use our TTL
670                                !cached.is_stale()
671                            }
672                        }
673                    };
674
675                    if is_fresh {
676                        // Cache hit
677                        metrics.hits.fetch_add(1, Ordering::Relaxed);
678                        let mut response = cached.into_response()?;
679
680                        if options.cache_status_headers {
681                            response.headers_mut().insert(
682                                "x-cache",
683                                HeaderValue::from_static("HIT"),
684                            );
685                        }
686
687                        return Ok(response.map(ResponseBody::Cached));
688                    }
689                }
690            }
691
692            // Reconstruct request for handler
693            let req = Request::from_parts(req_parts.clone(), req_body);
694
695            // Cache miss or stale - call the handler
696            metrics.misses.fetch_add(1, Ordering::Relaxed);
697            let response = inner.call(req).await.map_err(Into::into)?;
698
699            // Split response to check if we should cache
700            let (res_parts, body) = response.into_parts();
701
702            // Check if we should cache this response
703            if let Some(ttl) = should_cache(&req_parts, &res_parts, &options) {
704                // Buffer the response body
705                let body_bytes = match collect_body(body).await {
706                    Ok(bytes) => bytes,
707                    Err(e) => {
708                        // If we can't collect the body, return an error response
709                        return Err(e);
710                    }
711                };
712
713                // Check size limit
714                if body_bytes.len() <= options.max_body_size {
715                    metrics.stores.fetch_add(1, Ordering::Relaxed);
716                    // Create cached response
717                    let cached = CachedResponse {
718                        status: res_parts.status.as_u16(),
719                        headers: {
720                            let mut map: HashMap<String, Vec<String>> =
721                                HashMap::new();
722                            for (k, v) in res_parts.headers.iter() {
723                                if let Ok(s) = v.to_str() {
724                                    map.entry(k.to_string())
725                                        .or_default()
726                                        .push(s.to_string());
727                                }
728                            }
729                            map
730                        },
731                        body: body_bytes.to_vec(),
732                        cached_at: SystemTime::now(),
733                        ttl,
734                        vary: extract_vary_headers(&res_parts),
735                    };
736
737                    // Store in cache (fire and forget)
738                    let cached_json = serde_json::to_vec(&cached)
739                        .map_err(|e| Box::new(e) as BoxError)?;
740                    let http_response = HttpResponse {
741                        body: cached_json,
742                        headers: Default::default(),
743                        status: 200,
744                        url: cache_key.clone().parse().unwrap_or_else(|_| {
745                            "http://localhost/".parse().unwrap()
746                        }),
747                        version: HttpVersion::Http11,
748                        metadata: None,
749                    };
750
751                    // Create CachePolicy from actual request/response for Vary support
752                    let policy_req = Request::from_parts(req_parts.clone(), ());
753                    let policy_res =
754                        Response::from_parts(res_parts.clone(), ());
755                    let policy = CachePolicy::new(&policy_req, &policy_res);
756
757                    // Spawn cache write asynchronously
758                    let manager_clone = manager.clone();
759                    tokio::spawn(async move {
760                        let _ = manager_clone
761                            .put(cache_key, http_response, policy)
762                            .await;
763                    });
764                } else {
765                    // Body too large
766                    metrics.skipped.fetch_add(1, Ordering::Relaxed);
767                }
768
769                // Return response with MISS header
770                let mut response = Response::from_parts(res_parts, body_bytes);
771                if options.cache_status_headers {
772                    response
773                        .headers_mut()
774                        .insert("x-cache", HeaderValue::from_static("MISS"));
775                }
776                return Ok(response.map(ResponseBody::Fresh));
777            }
778
779            // Don't cache - just return
780            metrics.skipped.fetch_add(1, Ordering::Relaxed);
781            let body_bytes = collect_body(body).await?;
782            Ok(Response::from_parts(res_parts, body_bytes)
783                .map(ResponseBody::Uncacheable))
784        })
785    }
786}
787
788/// Collect a body into bytes.
789async fn collect_body<B>(body: B) -> std::result::Result<Bytes, BoxError>
790where
791    B: HttpBody,
792    B::Error: Into<BoxError>,
793{
794    body.collect()
795        .await
796        .map(|collected| collected.to_bytes())
797        .map_err(Into::into)
798}
799
800/// Extract Vary headers from response parts.
801fn extract_vary_headers(parts: &http::response::Parts) -> Option<Vec<String>> {
802    parts
803        .headers
804        .get(http::header::VARY)
805        .and_then(|v| v.to_str().ok())
806        .map(|s| s.split(',').map(|h| h.trim().to_string()).collect())
807}
808
809/// Determine if a response should be cached based on its headers.
810/// Implements RFC 7234/9111 requirements for shared caches.
811/// Helper function to check if a Cache-Control directive is present.
812/// This properly parses directives by splitting on commas and matching exact names.
813fn has_directive(cache_control: &str, directive: &str) -> bool {
814    cache_control
815        .split(',')
816        .map(|d| d.trim())
817        .any(|d| d == directive || d.starts_with(&format!("{}=", directive)))
818}
819
820/// Check if response explicitly permits caching of authorized requests per RFC 9111 §3.5.
821///
822/// Returns true if the response contains directives that allow caching despite
823/// the request having an Authorization header.
824fn response_permits_authorized_caching(cc_str: &str) -> bool {
825    has_directive(cc_str, "public")
826        || has_directive(cc_str, "s-maxage")
827        || has_directive(cc_str, "must-revalidate")
828}
829
830fn should_cache(
831    req_parts: &http::request::Parts,
832    res_parts: &http::response::Parts,
833    options: &ServerCacheOptions,
834) -> Option<Duration> {
835    // RFC 7234: Only cache successful responses (2xx)
836    if !res_parts.status.is_success() {
837        return None;
838    }
839
840    // RFC 9111 §3.5: Check Authorization header
841    let has_authorization =
842        req_parts.headers.contains_key(http::header::AUTHORIZATION);
843
844    // RFC 7234: Check Cache-Control directives
845    if let Some(cc) = res_parts.headers.get(http::header::CACHE_CONTROL) {
846        let cc_str = cc.to_str().ok()?;
847
848        // RFC 9111 §3.5: If request has Authorization header, only cache if
849        // response explicitly permits it
850        if has_authorization
851            && options.respect_authorization
852            && !response_permits_authorized_caching(cc_str)
853        {
854            return None;
855        }
856
857        // RFC 7234: MUST NOT store if no-store directive present
858        if has_directive(cc_str, "no-store") {
859            return None;
860        }
861
862        // RFC 7234: MUST NOT store if no-cache
863        // Note: Per RFC, no-cache means "cache but always revalidate". However,
864        // without conditional request support (ETag/If-None-Match), we cannot
865        // revalidate, so we skip caching entirely.
866        if has_directive(cc_str, "no-cache") {
867            return None;
868        }
869
870        // RFC 7234: Shared caches MUST NOT store responses with private directive
871        if has_directive(cc_str, "private") {
872            return None;
873        }
874
875        // RFC 7234: s-maxage directive overrides max-age for shared caches
876        if let Some(s_maxage) = parse_s_maxage(cc_str) {
877            let ttl = Duration::from_secs(s_maxage);
878            let ttl = apply_ttl_constraints(ttl, options);
879            return Some(ttl);
880        }
881
882        // RFC 7234: Extract max-age for cache lifetime
883        if let Some(max_age) = parse_max_age(cc_str) {
884            let ttl = Duration::from_secs(max_age);
885            let ttl = apply_ttl_constraints(ttl, options);
886            return Some(ttl);
887        }
888
889        // RFC 7234: public directive makes response cacheable
890        if has_directive(cc_str, "public") {
891            return options.default_ttl;
892        }
893    } else {
894        // No Cache-Control header
895        // RFC 9111 §3.5: Don't cache authorized requests without explicit permission
896        if has_authorization && options.respect_authorization {
897            return None;
898        }
899    }
900
901    // RFC 7234: Check for Expires header if no Cache-Control
902    if let Some(expires) = res_parts.headers.get(http::header::EXPIRES)
903        && let Ok(expires_str) = expires.to_str()
904        && let Some(ttl) = parse_expires(expires_str)
905    {
906        let ttl = apply_ttl_constraints(ttl, options);
907        return Some(ttl);
908    }
909
910    // No explicit caching directive
911    if options.cache_by_default { options.default_ttl } else { None }
912}
913
914/// Apply min/max TTL constraints from options.
915fn apply_ttl_constraints(
916    ttl: Duration,
917    options: &ServerCacheOptions,
918) -> Duration {
919    let mut result = ttl;
920
921    if let Some(max) = options.max_ttl {
922        result = result.min(max);
923    }
924
925    if let Some(min) = options.min_ttl {
926        result = result.max(min);
927    }
928
929    result
930}
931
932/// Parse max-age from Cache-Control header.
933fn parse_max_age(cache_control: &str) -> Option<u64> {
934    for directive in cache_control.split(',') {
935        let directive = directive.trim();
936        if let Some(value) = directive.strip_prefix("max-age=") {
937            return value.parse().ok();
938        }
939    }
940    None
941}
942
943/// Parse s-maxage from Cache-Control header (shared cache specific).
944fn parse_s_maxage(cache_control: &str) -> Option<u64> {
945    for directive in cache_control.split(',') {
946        let directive = directive.trim();
947        if let Some(value) = directive.strip_prefix("s-maxage=") {
948            return value.parse().ok();
949        }
950    }
951    None
952}
953
954/// Parse Expires header to calculate TTL.
955///
956/// Returns the duration until expiration, or None if the date is invalid or in the past.
957fn parse_expires(expires: &str) -> Option<Duration> {
958    let expires_time = httpdate::parse_http_date(expires).ok()?;
959    let now = SystemTime::now();
960
961    expires_time.duration_since(now).ok()
962}
963
964#[cfg(test)]
965mod tests {
966    use super::*;
967
968    #[test]
969    fn test_default_keyer() {
970        let keyer = DefaultKeyer;
971        let req = Request::get("/users/123").body(()).unwrap();
972        let key = keyer.cache_key(&req);
973        assert_eq!(key, "GET /users/123");
974    }
975
976    #[test]
977    fn test_query_keyer() {
978        let keyer = QueryKeyer;
979        let req = Request::get("/users?page=1").body(()).unwrap();
980        let key = keyer.cache_key(&req);
981        assert_eq!(key, "GET /users?page=1");
982    }
983
984    #[test]
985    fn test_parse_max_age() {
986        assert_eq!(parse_max_age("max-age=3600"), Some(3600));
987        assert_eq!(parse_max_age("public, max-age=3600"), Some(3600));
988        assert_eq!(parse_max_age("max-age=3600, public"), Some(3600));
989        assert_eq!(parse_max_age("public"), None);
990    }
991
992    #[test]
993    fn test_parse_s_maxage() {
994        assert_eq!(parse_s_maxage("s-maxage=7200"), Some(7200));
995        assert_eq!(parse_s_maxage("public, s-maxage=7200"), Some(7200));
996        assert_eq!(parse_s_maxage("s-maxage=7200, max-age=3600"), Some(7200));
997        assert_eq!(parse_s_maxage("public"), None);
998    }
999
1000    #[test]
1001    fn test_apply_ttl_constraints() {
1002        let options = ServerCacheOptions {
1003            min_ttl: Some(Duration::from_secs(10)),
1004            max_ttl: Some(Duration::from_secs(100)),
1005            ..Default::default()
1006        };
1007
1008        assert_eq!(
1009            apply_ttl_constraints(Duration::from_secs(5), &options),
1010            Duration::from_secs(10)
1011        );
1012        assert_eq!(
1013            apply_ttl_constraints(Duration::from_secs(50), &options),
1014            Duration::from_secs(50)
1015        );
1016        assert_eq!(
1017            apply_ttl_constraints(Duration::from_secs(200), &options),
1018            Duration::from_secs(100)
1019        );
1020    }
1021}