Assert cache lookup purge indexing

Author: eldryoth

docs/cache-backends.md

@@ -445,6 +445,7 @@ fluxheim --config /etc/fluxheim/fluxheim.toml cache-lookup \
   --require-object \
   --expect-tier disk \
   --expect-status 200 \
+  --expect-purge-indexed \
   --expect-freshness-state fresh
 ```
 
@@ -468,7 +469,8 @@ Host header. For release scripts, `cache-lookup --require-object` fails when
 the selected key has no cached object, repeated `--expect-tier memory|disk`
 flags fail when no matching object is present in an allowed storage tier,
 repeated `--expect-status` flags fail when no matching object has an allowed
-cached HTTP status, and repeated
+cached HTTP status, `--expect-purge-indexed` fails when no matching object is
+reachable through the bounded purge index, and repeated
 `--expect-freshness-state fresh|stale|expired` flags fail when none of the
 matching objects has an allowed freshness state.
 

docs/versioning-plan.md

@@ -430,9 +430,10 @@ Stable scope:
     bounded safe request headers such as `Accept-Language` and
     `Accept-Encoding`, so operators can debug negotiated `Vary` variants
     without contacting upstreams. `cache-lookup` can fail closed for deploy
-    checks with `--require-object`, `--expect-tier`, `--expect-status`, and
-    `--expect-freshness-state fresh|stale|expired`, so scripts can assert that
-    warm objects exist and are in an acceptable serving state without
+    checks with `--require-object`, `--expect-tier`, `--expect-status`,
+    `--expect-purge-indexed`, and `--expect-freshness-state
+    fresh|stale|expired`, so scripts can assert that warm objects exist, are
+    purge-index reachable, and are in an acceptable serving state without
     contacting upstreams;
   - cache warm/import/export workflows for deploys and repository mirrors,
     including clear failure accounting and no hidden best-effort misses.

src/cli.rs

@@ -248,6 +248,10 @@ pub enum CliCommand {
         /// Required cached-object storage tier. May be repeated: memory, disk.
         #[arg(long = "expect-tier", value_name = "TIER")]
         expect_tiers: Vec<String>,
+
+        /// Require at least one matching cached object to be present in the purge index.
+        #[arg(long)]
+        expect_purge_indexed: bool,
     },
 }
 
@@ -477,6 +481,7 @@ fn run_command(
             expect_freshness_states,
             expect_statuses,
             expect_tiers,
+            expect_purge_indexed,
         } => run_cache_lookup_command(CacheLookupOptions {
             config_path,
             host: host.clone(),
@@ -488,6 +493,7 @@ fn run_command(
             expect_freshness_states: expect_freshness_states.clone(),
             expect_statuses: expect_statuses.clone(),
             expect_tiers: expect_tiers.clone(),
+            expect_purge_indexed: *expect_purge_indexed,
         }),
     }
 }
@@ -533,6 +539,7 @@ struct CacheLookupOptions<'a> {
     expect_freshness_states: Vec<String>,
     expect_statuses: Vec<u16>,
     expect_tiers: Vec<String>,
+    expect_purge_indexed: bool,
 }
 
 #[cfg(feature = "cache")]
@@ -870,6 +877,7 @@ fn run_cache_lookup_command(
         &expected_states,
         &options.expect_statuses,
         &expected_tiers,
+        options.expect_purge_indexed,
     )?;
 
     println!("cache object lookup:");
@@ -973,6 +981,7 @@ fn validate_cache_lookup_expectations(
     expected_states: &[crate::cache::CacheObjectFreshnessState],
     expected_statuses: &[u16],
     expected_tiers: &[crate::cache::CacheObjectTier],
+    expect_purge_indexed: bool,
 ) -> Result<(), Box<dyn Error + Send + Sync>> {
     if require_object && lookup.objects.is_empty() {
         return Err("cache-lookup expected at least one cached object, found none".into());
@@ -1051,6 +1060,9 @@ fn validate_cache_lookup_expectations(
             return Err(format!("cache-lookup expected tier {expected}, found {found}").into());
         }
     }
+    if expect_purge_indexed && !lookup.objects.iter().any(|object| object.purge_indexed) {
+        return Err("cache-lookup expected at least one purge-indexed object, found none".into());
+    }
     Ok(())
 }
 
@@ -1098,13 +1110,15 @@ fn run_cache_lookup_command(
         expect_freshness_states,
         expect_statuses,
         expect_tiers,
+        expect_purge_indexed,
     } = options;
     let _ = (config_path, host, headers, method, path, query);
     let _ = (
         require_object,
         expect_freshness_states,
         expect_statuses,
         expect_tiers,
+        expect_purge_indexed,
     );
     Err("cache-lookup requires the proxy and cache features".into())
 }
@@ -2785,7 +2799,7 @@ mod tests {
         let tiers = super::parse_cache_lookup_tiers(&["memory".to_owned()]).unwrap();
 
         assert!(
-            super::validate_cache_lookup_expectations(&lookup, true, &states, &[200], &tiers)
+            super::validate_cache_lookup_expectations(&lookup, true, &states, &[200], &tiers, true)
                 .is_ok()
         );
         assert!(
@@ -2794,14 +2808,15 @@ mod tests {
                 false,
                 &[crate::cache::CacheObjectFreshnessState::Fresh],
                 &[],
-                &[]
+                &[],
+                false
             )
             .unwrap_err()
             .to_string()
             .contains("expected freshness state fresh, found stale")
         );
         assert!(
-            super::validate_cache_lookup_expectations(&lookup, false, &[], &[404], &[])
+            super::validate_cache_lookup_expectations(&lookup, false, &[], &[404], &[], false)
                 .unwrap_err()
                 .to_string()
                 .contains("expected status 404, found 200")
@@ -2812,7 +2827,8 @@ mod tests {
                 false,
                 &[],
                 &[],
-                &[crate::cache::CacheObjectTier::Disk]
+                &[crate::cache::CacheObjectTier::Disk],
+                false
             )
             .unwrap_err()
             .to_string()
@@ -2837,12 +2853,26 @@ mod tests {
                 true,
                 &[],
                 &[],
-                &[]
+                &[],
+                false
             )
             .unwrap_err()
             .to_string()
             .contains("expected at least one cached object")
         );
+        assert!(
+            super::validate_cache_lookup_expectations(
+                &cache_lookup_without_objects(),
+                false,
+                &[],
+                &[],
+                &[],
+                true
+            )
+            .unwrap_err()
+            .to_string()
+            .contains("expected at least one purge-indexed object")
+        );
     }
 
     #[cfg(all(feature = "cache", feature = "proxy"))]