Add indexed cache path-prefix purge

Author: eldryoth

ROADMAP.md

@@ -649,8 +649,9 @@ without parsing text fixtures for every module.
        otherwise personalized-content safe;
      - bounded cache-key indexing for memory and disk tiers is implemented as
        the foundation for broader invalidation. Indexed vhost/route scope
-       purge is implemented through the admin API. Path-prefix/wildcard purge
-       and a background purger for complete disk cleanup are still planned;
+       purge and path-prefix purge are implemented through the admin API.
+       Wildcard purge and a background purger for complete disk cleanup are
+       still planned;
      - startup cache-index loading that is incremental and bounded so large
        disk caches do not block the gateway;
      - byte-range/slice caching for large immutable files, with explicit

src/admin.rs

@@ -253,6 +253,17 @@ impl AdminApp {
                 header_value(headers, "x-fluxheim-cache-limit")
                     .or_else(|| query_param(query, "limit")),
             ),
+            ("POST", "/_fluxheim/cache/purge-prefix") => self.cache_purge_prefix_response(
+                header_value(headers, "x-fluxheim-cache-vhost")
+                    .or_else(|| query_param(query, "vhost")),
+                header_value(headers, "x-fluxheim-cache-route")
+                    .or_else(|| query_param(query, "route")),
+                header_value(headers, "x-fluxheim-cache-path-prefix")
+                    .or_else(|| query_param(query, "path_prefix"))
+                    .or_else(|| query_param(query, "prefix")),
+                header_value(headers, "x-fluxheim-cache-limit")
+                    .or_else(|| query_param(query, "limit")),
+            ),
             ("POST", "/_fluxheim/snapshot") => {
                 self.create_snapshot_response(header_value(headers, "x-fluxheim-message"))
             }
@@ -276,6 +287,7 @@ impl AdminApp {
                 | "/_fluxheim/cache/purge"
                 | "/_fluxheim/cache/purge-bulk"
                 | "/_fluxheim/cache/purge-index"
+                | "/_fluxheim/cache/purge-prefix"
                 | "/_fluxheim/snapshot"
                 | "/_fluxheim/rollback"
                 | "/_fluxheim/reload",
@@ -664,6 +676,65 @@ impl AdminApp {
         }
     }
 
+    #[cfg(feature = "cache")]
+    fn cache_purge_prefix_response(
+        &self,
+        vhost: Option<&str>,
+        route: Option<&str>,
+        path_prefix: Option<&str>,
+        limit: Option<&str>,
+    ) -> AdminResponse {
+        let Some(vhost) = vhost.map(str::trim).filter(|vhost| !vhost.is_empty()) else {
+            return error_response(
+                StatusCode::BAD_REQUEST,
+                "cache path-prefix purge vhost is required",
+            );
+        };
+        let path_prefix = match validated_cache_purge_path_prefix(path_prefix) {
+            Ok(path_prefix) => path_prefix,
+            Err(message) => return error_response(StatusCode::BAD_REQUEST, message),
+        };
+        let limit = match validated_cache_indexed_purge_limit(limit) {
+            Ok(limit) => limit,
+            Err(message) => return error_response(StatusCode::BAD_REQUEST, message),
+        };
+
+        match self.proxy.purge_indexed_image_cache_path_prefix(
+            crate::proxy::CacheIndexedPathPrefixPurgeRequest {
+                vhost,
+                route: route.filter(|route| !route.trim().is_empty()),
+                path_prefix,
+                limit,
+            },
+        ) {
+            Ok(result) => {
+                let body = format!(
+                    r#"{{"status":"ok","matched":{},"purged":{},"truncated":{},"vhost":"{}","route":{},"path_prefix":"{}","memory_matched":{},"memory_purged":{},"memory_truncated":{},"disk_matched":{},"disk_purged":{},"disk_truncated":{}}}"#,
+                    result.matched(),
+                    result.purged(),
+                    result.truncated(),
+                    json_escape(&result.vhost),
+                    cache_route_json(result.route.as_deref()),
+                    json_escape(path_prefix),
+                    result.memory_matched,
+                    result.memory_purged,
+                    result.memory_truncated,
+                    result.disk_matched,
+                    result.disk_purged,
+                    result.disk_truncated
+                );
+                json_response(StatusCode::OK, body.as_bytes())
+            }
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+                error_response(StatusCode::NOT_FOUND, &error.to_string())
+            }
+            Err(error) if error.kind() == std::io::ErrorKind::InvalidInput => {
+                error_response(StatusCode::BAD_REQUEST, &error.to_string())
+            }
+            Err(error) => error_response(StatusCode::INTERNAL_SERVER_ERROR, &error.to_string()),
+        }
+    }
+
     #[cfg(not(feature = "cache"))]
     fn cache_purge_response(
         &self,
@@ -700,6 +771,17 @@ impl AdminApp {
         error_response(StatusCode::BAD_REQUEST, "cache support is not compiled in")
     }
 
+    #[cfg(not(feature = "cache"))]
+    fn cache_purge_prefix_response(
+        &self,
+        _vhost: Option<&str>,
+        _route: Option<&str>,
+        _path_prefix: Option<&str>,
+        _limit: Option<&str>,
+    ) -> AdminResponse {
+        error_response(StatusCode::BAD_REQUEST, "cache support is not compiled in")
+    }
+
     fn apply_snapshot(
         &self,
         snapshot: &ConfigSnapshot,
@@ -1619,6 +1701,18 @@ fn validate_cache_purge_path_value(path: &str) -> Result<(), &'static str> {
     Ok(())
 }
 
+#[cfg(feature = "cache")]
+fn validated_cache_purge_path_prefix(prefix: Option<&str>) -> Result<&str, &'static str> {
+    let Some(prefix) = prefix.map(str::trim).filter(|prefix| !prefix.is_empty()) else {
+        return Err("cache path-prefix purge prefix is required and must start with /");
+    };
+    validate_cache_purge_path_value(prefix)?;
+    if prefix == "/" {
+        return Err("cache path-prefix purge prefix must not be /; use scope purge instead");
+    }
+    Ok(prefix)
+}
+
 #[cfg(feature = "cache")]
 fn path_contains_traversal_segment(path: &str) -> bool {
     path.split('/').any(|segment| matches!(segment, "." | ".."))
@@ -2007,6 +2101,62 @@ mod tests {
         assert!(body.contains(r#""truncated":false"#));
     }
 
+    #[cfg(feature = "cache")]
+    #[test]
+    fn cache_purge_prefix_endpoint_accepts_path_prefix() {
+        let config = Config {
+            vhosts: vec![VhostConfig {
+                name: "cached".to_owned(),
+                hosts: vec!["cached.example".to_owned()],
+                max_request_body_bytes: None,
+                acme_challenge: crate::config::VhostAcmeChallengeConfig::default(),
+                redirect: crate::config::VhostRedirectConfig::default(),
+                tls: crate::config::VhostTlsConfig::default(),
+                proxy: ProxyConfig::default(),
+                cache: CacheConfig {
+                    enabled: true,
+                    memory: crate::config::CacheMemoryConfig {
+                        enabled: true,
+                        max_size_bytes: ByteSize::from_bytes(2048),
+                    },
+                    max_object_bytes: ByteSize::from_bytes(512),
+                    ..CacheConfig::default()
+                },
+                headers: crate::config::VhostHeaderPolicyConfig::default(),
+                web: WebConfig::default(),
+                routes: Vec::new(),
+            }],
+            ..Config::default()
+        };
+        let app = app_with_config(config);
+
+        let response = app.handle(
+            "POST",
+            "/_fluxheim/cache/purge-prefix",
+            Some("vhost=cached&path_prefix=/assets/&limit=16"),
+            &auth_headers(),
+        );
+
+        assert_eq!(response.status, StatusCode::OK);
+        let body = String::from_utf8(response.body).unwrap();
+        assert!(body.contains(r#""vhost":"cached""#));
+        assert!(body.contains(r#""path_prefix":"/assets/""#));
+        assert!(body.contains(r#""matched":0"#));
+    }
+
+    #[cfg(feature = "cache")]
+    #[test]
+    fn cache_purge_prefix_endpoint_rejects_root_prefix() {
+        let response = app().handle(
+            "POST",
+            "/_fluxheim/cache/purge-prefix",
+            Some("vhost=cached&path_prefix=/"),
+            &auth_headers(),
+        );
+
+        assert_eq!(response.status, StatusCode::BAD_REQUEST);
+    }
+
     #[cfg(feature = "cache")]
     #[test]
     fn cache_purge_endpoint_rejects_missing_identity() {