v0.34.12

src/cache/model/entry.rs

@@ -182,15 +182,7 @@ impl Settings {
         ttl: u64,
         reason: &'static str,
     ) {
-        self.annotate_internal(
-            headers,
-            outcome,
-            hits,
-            ttl as i64,
-            Some(reason),
-            false,
-            None,
-        );
+        self.annotate_internal(headers, outcome, hits, ttl as i64, Some(reason), false, None);
     }
 
     pub fn annotate_reason_transformed(
@@ -202,15 +194,7 @@ impl Settings {
         reason: &'static str,
         transformed: bool,
     ) {
-        self.annotate_internal(
-            headers,
-            outcome,
-            hits,
-            ttl as i64,
-            Some(reason),
-            transformed,
-            None,
-        );
+        self.annotate_internal(headers, outcome, hits, ttl as i64, Some(reason), transformed, None);
     }
 
     pub fn annotate_reason_transformed_freshness(
@@ -223,16 +207,12 @@ impl Settings {
         transformed: bool,
     ) {
         self.annotate_internal(
-            headers,
-            outcome,
-            hits,
-            freshness_ttl,
-            Some(reason),
-            transformed,
-            None,
+            headers, outcome, hits, freshness_ttl, Some(reason), transformed, None,
         );
     }
 
+    // RFC 9211 distinguishes whether this request was forwarded from whether
+    // the legacy X-Cache metric counted the reused representation as a HIT.
     pub fn annotate_reason_transformed_forwarded(
         &self,
         headers: &mut HeaderMap,
@@ -305,11 +285,8 @@ impl Settings {
         }
         if self.expose_cache_status {
             let forwarded = forwarded.or_else(|| {
-                matches!(
-                    reason,
-                    Some("cache_revalidated" | "cache_revalidated_uncached")
-                )
-                .then_some(("stale", Some(StatusCode::NOT_MODIFIED)))
+                matches!(reason, Some("cache_revalidated" | "cache_revalidated_uncached"))
+                    .then_some(("stale", Some(StatusCode::NOT_MODIFIED)))
             });
             let mut value = if let Some((why, status)) = forwarded {
                 let mut value = format!("RustProxy; fwd={why}");
@@ -319,6 +296,8 @@ impl Settings {
                 value
             } else {
                 match outcome {
+                    // RFC 9211 permits a negative ttl when stale data is served
+                    // without sending the current request to the origin.
                     "HIT" => format!("RustProxy; hit; ttl={ttl}"),
                     "MISS" => "RustProxy; fwd=miss".to_owned(),
                     "BYPASS" if reason == Some("request_method") => {

src/cache/model/maintenance.rs

@@ -126,6 +126,7 @@ impl Drop for ColdReadGuard<'_> {
         }
     }
 }
+// RFC 9211 uses signed structured-field integers for freshness (negative when stale).
 fn cache_status_ttl(ttl: u64, age: u64) -> i64 {
     const MAX: i128 = 999_999_999_999_999;
     (i128::from(ttl) - i128::from(age)).clamp(-MAX, MAX) as i64

src/proxy/forward/web_source.rs

@@ -72,12 +72,18 @@
     let cached_revalidation = if let Some(ticket) = cache_ticket.as_ref() {
         state.cache.revalidation_tiered(ticket).await
     } else { None };
-    let freshness_headers = crate::cache::request_freshness_headers(
-        &request_headers, cache_settings,
-    );
-    let needs_validation = policy.revalidation_reason().is_some()
-        || cached_revalidation.as_ref().is_some_and(|cached|
-            !cached.reusable_for_request(&freshness_headers));
+    let (needs_validation, request_forces_validation) = {
+        let freshness_headers = crate::cache::request_freshness_headers(
+            &request_headers, cache_settings,
+        );
+        let freshness_revalidation_requested = cached_revalidation.as_ref().is_some_and(|cached|
+            cached.request_freshness_revalidation_reason(&freshness_headers).is_some());
+        let needs_validation = policy.revalidation_reason().is_some()
+            || cached_revalidation.as_ref().is_some_and(|cached|
+                !cached.reusable_for_request(&freshness_headers));
+        (needs_validation,
+            policy.revalidation_reason().is_some() || freshness_revalidation_requested)
+    };
     if let Some(ticket) = &cache_ticket {
         if !needs_validation {
             if let Some(mut hit) = state.cache.get_tiered(ticket, cache_settings).await {
@@ -260,10 +266,7 @@
     if let Some(cached) = &cached_revalidation {
         cache_settings.annotate_reason_transformed_forwarded(
             response.headers_mut(), outcome, 0, 0, reason, transformed,
-            cached.cache_status_forward_reason(
-                policy.revalidation_reason().is_some()
-                    || cached.request_freshness_revalidation_reason(&freshness_headers).is_some(),
-            ),
+            cached.cache_status_forward_reason(request_forces_validation),
             None,
         );
     } else {