Add cache request header value bypass

Author: eldryoth

CHANGELOG.md

@@ -22,6 +22,8 @@ behavior when the change improves security or project direction.
   response headers are present, while still delivering the response normally.
 - Cache policies can now bypass lookup and storage when configured request
   headers such as `Cookie` or `Authorization` are present.
+- Cache policies can now bypass lookup and storage when configured request
+  header values such as `x-preview-mode = "1"` are present.
 - Cache policies can now bypass lookup and storage when configured cookie names
   such as `sessionid` or `wordpress_logged_in` are present.
 - Cache policies can now bypass lookup and storage when configured cookie

ROADMAP.md

@@ -633,9 +633,9 @@ without parsing text fixtures for every module.
        through typed `status_ttls` and `default_status_ttl_secs` policy;
      - explicit request-side bypass rules and response-side no-store rules
        based on bounded header, cookie, and query predicates. Implemented for
-       header-presence request bypass, raw query-parameter request bypass, and
-       cookie-name and exact cookie-value request bypass, plus response
-       no-store controls;
+       header-presence and exact header-value request bypass, raw
+       query-parameter request bypass, cookie-name and exact cookie-value
+       request bypass, plus response no-store controls;
      - stale serving controls for origin error, timeout, updating, and selected
        status classes;
      - optional cache-status response headers for production debugging;

docs/config-reference.md

@@ -457,6 +457,7 @@ status_header = "X-Cache-Status"
 hide_response_headers = ["set-cookie"]
 no_store_response_headers = ["x-app-no-store"]
 bypass_request_headers = ["cookie", "authorization"]
+bypass_request_header_values = { x-preview-mode = "1" }
 bypass_cookie_names = ["sessionid", "wordpress_logged_in"]
 bypass_cookie_values = { preview = "1" }
 bypass_query_params = ["preview", "token"]
@@ -513,6 +514,9 @@ listed request header is present. Use it on routes where a header such as
 `Cookie` or `Authorization` changes the upstream response but should not become
 part of the shared cache identity. The default is empty so explicit static
 asset routes can still cache browser requests that carry unrelated cookies.
+`bypass_request_header_values` disables lookup and storage only when a listed
+request header has the exact configured value. Use it for bounded flags such as
+`x-preview-mode = "1"` when header presence alone is too broad.
 `bypass_cookie_names` disables both cache lookup and cache storage when a
 listed cookie name appears in any `Cookie` request header. Only names are
 matched; values are ignored. This is narrower than bypassing on every `Cookie`
@@ -913,6 +917,7 @@ send_timeout_secs = 600
 enabled = true
 status_header = "X-Cache-Status"
 hide_response_headers = ["set-cookie"]
+bypass_request_header_values = { x-preview-mode = "1" }
 bypass_cookie_values = { preview = "1" }
 status_ttls = { "200" = 3600, "302" = 3600, "404" = 60 }
 stale_while_revalidate_secs = 30

examples/vhosts.toml

@@ -163,6 +163,7 @@ status_header = "X-Cache-Status"
 hide_response_headers = ["set-cookie"]
 no_store_response_headers = ["x-app-no-store"]
 bypass_request_headers = ["cookie", "authorization"]
+bypass_request_header_values = { x-preview-mode = "1" }
 bypass_cookie_names = ["sessionid", "wordpress_logged_in"]
 bypass_cookie_values = { preview = "1" }
 bypass_query_params = ["preview", "token"]

src/config.rs

@@ -3179,6 +3179,8 @@ pub struct CacheConfig {
     #[serde(default)]
     pub bypass_request_headers: Vec<String>,
     #[serde(default)]
+    pub bypass_request_header_values: BTreeMap<String, String>,
+    #[serde(default)]
     pub bypass_cookie_names: Vec<String>,
     #[serde(default)]
     pub bypass_cookie_values: BTreeMap<String, String>,
@@ -3226,6 +3228,7 @@ impl Default for CacheConfig {
             hide_response_headers: Vec::new(),
             no_store_response_headers: Vec::new(),
             bypass_request_headers: Vec::new(),
+            bypass_request_header_values: BTreeMap::new(),
             bypass_cookie_names: Vec::new(),
             bypass_cookie_values: BTreeMap::new(),
             bypass_query_params: Vec::new(),
@@ -3271,6 +3274,10 @@ impl CacheConfig {
         for header in &self.bypass_request_headers {
             validate_header_name(scope, header)?;
         }
+        for (header, value) in &self.bypass_request_header_values {
+            validate_header_name(scope, header)?;
+            validate_cache_bypass_request_header_value(scope, header, value)?;
+        }
         for cookie in &self.bypass_cookie_names {
             validate_cache_cookie_name(scope, cookie)?;
         }
@@ -3413,6 +3420,27 @@ fn validate_cache_query_param(scope: &'static str, param: &str) -> Result<(), Co
     Ok(())
 }
 
+fn validate_cache_bypass_request_header_value(
+    scope: &'static str,
+    header: &str,
+    value: &str,
+) -> Result<(), ConfigError> {
+    if value.trim().is_empty()
+        || value.len() > 4096
+        || value
+            .as_bytes()
+            .iter()
+            .any(|byte| matches!(byte, 0x00..=0x08 | 0x0a..=0x1f | 0x7f))
+    {
+        return Err(ConfigError::InvalidCacheBypassRequestHeaderValue {
+            scope,
+            header: header.to_owned(),
+            value: value.to_owned(),
+        });
+    }
+    Ok(())
+}
+
 fn validate_cache_cookie_name(scope: &'static str, name: &str) -> Result<(), ConfigError> {
     if name.is_empty() || name.len() > 128 || !valid_cookie_name(name) {
         return Err(ConfigError::InvalidCacheBypassCookieName {
@@ -3970,6 +3998,11 @@ pub enum ConfigError {
         scope: &'static str,
         param: String,
     },
+    InvalidCacheBypassRequestHeaderValue {
+        scope: &'static str,
+        header: String,
+        value: String,
+    },
     InvalidCacheBypassCookieName {
         scope: &'static str,
         name: String,
@@ -4395,6 +4428,14 @@ impl Display for ConfigError {
                 formatter,
                 "{scope}.bypass_query_params must contain raw query parameter names without whitespace, controls, '&', '=', '#', '?', or ';', got {param:?}"
             ),
+            Self::InvalidCacheBypassRequestHeaderValue {
+                scope,
+                header,
+                value,
+            } => write!(
+                formatter,
+                "{scope}.bypass_request_header_values[{header:?}] must contain a non-empty safe header value without controls, got {value:?}"
+            ),
             Self::InvalidCacheBypassCookieName { scope, name } => write!(
                 formatter,
                 "{scope}.bypass_cookie_names must contain cookie name tokens without whitespace or separators, got {name:?}"
@@ -7241,6 +7282,7 @@ mod tests {
             hide_response_headers = ["set-cookie"]
             no_store_response_headers = ["x-fluxheim-no-store"]
             bypass_request_headers = ["cookie", "authorization"]
+            bypass_request_header_values = { x-preview-mode = "1" }
             bypass_cookie_names = ["sessionid", "wordpress_logged_in"]
             bypass_cookie_values = { preview = "1" }
             bypass_query_params = ["preview", "token"]
@@ -7292,6 +7334,13 @@ mod tests {
             config.cache.bypass_request_headers,
             ["cookie".to_owned(), "authorization".to_owned()]
         );
+        assert_eq!(
+            config
+                .cache
+                .bypass_request_header_values
+                .get("x-preview-mode"),
+            Some(&"1".to_owned())
+        );
         assert_eq!(
             config.cache.bypass_cookie_names,
             ["sessionid".to_owned(), "wordpress_logged_in".to_owned()]
@@ -7409,6 +7458,28 @@ mod tests {
         );
     }
 
+    #[test]
+    fn rejects_invalid_cache_bypass_request_header_value() {
+        for value in ["", " ", "bad\nvalue"] {
+            let config: Config = toml::from_str(&format!(
+                r#"
+                [cache]
+                bypass_request_header_values = {{ x-preview-mode = {value:?} }}
+                "#,
+            ))
+            .unwrap();
+
+            assert_eq!(
+                config.validate(),
+                Err(ConfigError::InvalidCacheBypassRequestHeaderValue {
+                    scope: "cache",
+                    header: "x-preview-mode".to_owned(),
+                    value: value.to_owned()
+                })
+            );
+        }
+    }
+
     #[test]
     fn rejects_invalid_cache_no_store_response_header_name() {
         let config: Config = toml::from_str(

src/proxy.rs

@@ -2939,6 +2939,9 @@ fn request_cache_bypass(request: &RequestHeader, cache: &crate::config::CacheCon
     {
         return true;
     }
+    if request_headers_match_cache_bypass_value(request, &cache.bypass_request_header_values) {
+        return true;
+    }
     if request_cookies_match_cache_bypass(
         request_header_values(request, "cookie"),
         &cache.bypass_cookie_names,
@@ -2960,6 +2963,17 @@ fn request_cache_bypass(request: &RequestHeader, cache: &crate::config::CacheCon
     )
 }
 
+#[cfg(feature = "cache")]
+fn request_headers_match_cache_bypass_value(
+    request: &RequestHeader,
+    configured_values: &std::collections::BTreeMap<String, String>,
+) -> bool {
+    !configured_values.is_empty()
+        && configured_values.iter().any(|(header, configured)| {
+            request_header_values(request, header).any(|value| value == configured)
+        })
+}
+
 #[cfg(feature = "cache")]
 fn request_cookies_match_cache_bypass<'a>(
     cookie_headers: impl Iterator<Item = &'a str>,
@@ -5080,6 +5094,28 @@ mod tests {
         assert!(request_cache_bypass(&request, &cache));
     }
 
+    #[cfg(feature = "cache")]
+    #[test]
+    fn request_cache_bypass_honors_configured_request_header_values() {
+        let cache = CacheConfig {
+            bypass_request_header_values: [("x-preview-mode".to_owned(), "1".to_owned())].into(),
+            ..CacheConfig::default()
+        };
+
+        let mut request =
+            pingora::http::RequestHeader::build("GET", b"/assets/app.js", None).unwrap();
+        assert!(!request_cache_bypass(&request, &cache));
+
+        request.insert_header("x-preview-mode", "0").unwrap();
+        assert!(!request_cache_bypass(&request, &cache));
+
+        let mut request =
+            pingora::http::RequestHeader::build("GET", b"/assets/app.js", None).unwrap();
+        request.append_header("x-preview-mode", "0").unwrap();
+        request.append_header("x-preview-mode", "1").unwrap();
+        assert!(request_cache_bypass(&request, &cache));
+    }
+
     #[cfg(feature = "cache")]
     #[test]
     fn request_cache_bypass_honors_configured_cookie_names() {