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}