Add Wasm cache-store content type context

Author: eldryoth

CHANGELOG.md

@@ -17,6 +17,8 @@ behavior when the change improves security or project direction.
   `wasm-device-class=mobile|desktop` cache-key variants.
 - Add fixed-ID Wasm cache-store TTL overrides and cache tag assignment.
 - Add fixed-ID Wasm cache-store response-header metadata for stored objects.
+- Add symbolic cache-store response content-type class inspection without raw
+  response-header exposure.
 - Add live listener tests proving separate mobile and desktop cache variants
   MISS independently and HIT the original variant on repeat.
 - Add live listener tests proving a plugin TTL override expires an otherwise
@@ -25,8 +27,9 @@ behavior when the change improves security or project direction.
   on cache HIT and forbidden stored-header IDs fail closed.
 - Add a checked-in Wasm cache-policy example plus a config template for the
   bounded `1.7.5` cache ABI.
-- Add live listener coverage that compiles the checked-in example source and
-  validates its documented cache-key, TTL, and stored-header behavior.
+- Add live listener coverage that compiles the checked-in example sources and
+  validates their documented image-only cache-key, TTL, and stored-header
+  behavior.
 
 ### Security
 
@@ -38,8 +41,8 @@ behavior when the change improves security or project direction.
   stored-header mutation counts above the hard cap through the plugin fail
   mode.
 - Keep arbitrary request headers, raw cache-key bytes, request bodies, cached
-  objects, arbitrary TTLs, arbitrary tag strings, and arbitrary stored response
-  headers unavailable in this slice.
+  objects, arbitrary TTLs, arbitrary tag strings, arbitrary response-header
+  inspection, and arbitrary stored response headers unavailable in this slice.
 
 ## 1.7.4 - 2026-07-07
 

README.md

@@ -137,7 +137,7 @@ Fluxheim is licensed under the European Union Public Licence 1.2.
 | GeoIP/Geo-Context policy | ✅ | `1.4.5`; optional `geoip` feature with local MMDB support for MaxMind GeoIP2/GeoLite2 and CIRCL Geo Open datasets, plus vhost/route country and ASN ACLs. |
 | Pingora-free runtime | ✅ | `1.6.34`; normal Fluxheim builds no longer compile Pingora crates. Server/listener/TLS, HTTP/1, HTTP/2, WebSocket, cache, load-balancer, admin, metrics, stream, and background-service paths run through Fluxheim-owned Rust crates. |
 | HTTP/3/QUIC | ❌ | Planned as a Fluxheim-owned `1.9` protocol milestone using the Rust `quinn`/`h3` stack after the `1.8` macOS/Windows production parity line. |
-| WASM extensibility | 🧪 | Active `1.7.x` line. `1.7.0` added the optional `wasm` feature, strict plugin-file loading, bounded Wasmtime execution, and real-Wasm smoke coverage. `1.7.1` adds config-level plugin registry validation, deterministic attachment ordering, admission limits, metrics, and live native HTTP/1 access-decision hooks. `1.7.2` adds bounded native HTTP/1 request/response header hooks. `1.7.3` starts bounded native HTTP/1 route-decision hooks with configured canary and mirror branch selection, including selected native load-balanced and persistent routes. `1.7.4` starts VCL-like cache-policy hooks with bounded cache-lookup and cache-store decisions for continue/pass/bypass/skip-store/deny around cache lookup and storage. `1.7.5` adds bounded symbolic cache-key component hooks for low-cardinality cache variants plus fixed-ID cache-store TTL/tag/header metadata and a checked-in cache-policy example. Direct backend choice, plugin-provided persistence keys, dynamic mirror/shadow target choice, and richer store policy hooks remain staged for later `1.7.x`. |
+| WASM extensibility | 🧪 | Active `1.7.x` line. `1.7.0` added the optional `wasm` feature, strict plugin-file loading, bounded Wasmtime execution, and real-Wasm smoke coverage. `1.7.1` adds config-level plugin registry validation, deterministic attachment ordering, admission limits, metrics, and live native HTTP/1 access-decision hooks. `1.7.2` adds bounded native HTTP/1 request/response header hooks. `1.7.3` starts bounded native HTTP/1 route-decision hooks with configured canary and mirror branch selection, including selected native load-balanced and persistent routes. `1.7.4` starts VCL-like cache-policy hooks with bounded cache-lookup and cache-store decisions for continue/pass/bypass/skip-store/deny around cache lookup and storage. `1.7.5` adds bounded symbolic cache-key component hooks for low-cardinality cache variants plus fixed-ID cache-store TTL/tag/header metadata, symbolic content-type inspection, and a checked-in cache-policy example. Direct backend choice, plugin-provided persistence keys, dynamic mirror/shadow target choice, and richer store policy hooks remain staged for later `1.7.x`. |
 
 See [Production Readiness](docs/production-readiness.md) for the precise
 stable-core promise and deployment checks. See

crates/fluxheim-server/src/native_http1_route_proxy_tests/upstream_cache.rs

@@ -178,6 +178,48 @@ pub(super) async fn upstream_cacheable_sequence(
     addr
 }
 
+#[cfg(feature = "wasm")]
+pub(super) async fn upstream_cacheable_content_type_sequence(
+    responses: &'static [(&'static str, &'static str, &'static str)],
+) -> std::net::SocketAddr {
+    let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let addr = listener.local_addr().unwrap();
+    tokio::spawn(async move {
+        for (expected_path, content_type, body) in responses {
+            let (mut stream, _) = listener.accept().await.unwrap();
+            let mut request = Vec::new();
+            let mut chunk = [0u8; 1024];
+            loop {
+                let read = stream.read(&mut chunk).await.unwrap();
+                if read == 0 {
+                    break;
+                }
+                request.extend_from_slice(&chunk[..read]);
+                if request.windows(4).any(|window| window == b"\r\n\r\n") {
+                    break;
+                }
+            }
+            let request = String::from_utf8(request).unwrap();
+            assert!(
+                request.starts_with(&format!("GET {expected_path} HTTP/1.1\r\n")),
+                "unexpected upstream request: {request:?}"
+            );
+            stream
+                .write_all(
+                    format!(
+                        "HTTP/1.1 200 OK\r\ncontent-type: {content_type}\r\ncache-control: max-age=60\r\ncontent-length: {}\r\n\r\n{}",
+                        body.len(),
+                        body
+                    )
+                    .as_bytes(),
+                )
+                .await
+                .unwrap();
+        }
+    });
+    addr
+}
+
 pub(super) async fn upstream_vary_sequence(
     responses: &'static [(&'static str, &'static str, &'static str, &'static str)],
 ) -> std::net::SocketAddr {

crates/fluxheim-server/src/native_http1_route_proxy_tests/wasm.rs

@@ -1115,6 +1115,75 @@ async fn native_wasm_cache_policy_example_matches_documented_behavior() {
     );
 }
 
+#[tokio::test]
+async fn native_wasm_cache_policy_example_leaves_non_image_store_metadata_unchanged() {
+    let fixture = WasmRouteFixture::new(&[
+        ("cache_lookup", WasmPluginBody::CacheLookupPolicyExample),
+        ("cache_store", WasmPluginBody::CacheStorePolicyExample),
+    ]);
+    let upstream = super::upstream_cacheable_content_type_sequence(&[(
+        "/static/non-image.png",
+        "text/plain",
+        "text-body",
+    )])
+    .await;
+    let mut config = fixture.config_with_attachments(
+        upstream,
+        vec![
+            wasm_attachment_phase(
+                "cache_lookup",
+                "route",
+                100,
+                fluxheim_config::WasmPluginPhase::CacheLookup,
+            ),
+            wasm_attachment_phase(
+                "cache_store",
+                "route",
+                100,
+                fluxheim_config::WasmPluginPhase::CacheStore,
+            ),
+        ],
+    );
+    config.vhosts[0].routes[0].path_exact = None;
+    config.vhosts[0].routes[0].path_prefix = Some("/".to_owned());
+    config.vhosts[0].routes[0].redirect = None;
+    config.vhosts[0].routes[0].proxy = Some(fluxheim_config::ProxyConfig {
+        upstreams: vec![upstream.to_string()],
+        ..Default::default()
+    });
+    let mut cache = native_proxy_memory_cache_config();
+    cache.content_types.push("text/plain".to_owned());
+    config.vhosts[0].routes[0].cache = Some(cache);
+    let router =
+        NativeHttp1HostRouter::from_config(&config, DownstreamHttp1Policy::default(), 0).unwrap();
+    let proxy = router_listener(router).await;
+
+    let first = downstream_get(proxy, "/static/non-image.png").await;
+    let hit = downstream_get(proxy, "/static/non-image.png").await;
+
+    assert!(
+        first.starts_with("HTTP/1.1 200 OK\r\n"),
+        "unexpected text first response: {first:?}"
+    );
+    assert!(first.ends_with("text-body"));
+    assert_eq!(
+        response_header(&first, "x-cache-status").as_deref(),
+        Some("MISS")
+    );
+    assert_eq!(response_header(&first, "x-fluxheim-cache-policy"), None);
+
+    assert!(
+        hit.starts_with("HTTP/1.1 200 OK\r\n"),
+        "unexpected text hit response: {hit:?}"
+    );
+    assert!(hit.ends_with("text-body"));
+    assert_eq!(
+        response_header(&hit, "x-cache-status").as_deref(),
+        Some("HIT")
+    );
+    assert_eq!(response_header(&hit, "x-fluxheim-cache-policy"), None);
+}
+
 #[tokio::test]
 async fn native_wasm_cache_store_deny_wins_over_earlier_skip() {
     let fixture = WasmRouteFixture::new(&[

crates/fluxheim-server/src/native_http1_route_wasm.rs

@@ -42,6 +42,7 @@ const HOST_CONTEXT_CANARY_HEADER: i32 = 2;
 const HOST_CONTEXT_MIRROR_HEADER: i32 = 3;
 const HOST_CONTEXT_RESPONSE_STATUS: i32 = 4;
 const HOST_CONTEXT_DEVICE_CLASS_HEADER: i32 = 5;
+const HOST_CONTEXT_RESPONSE_CONTENT_TYPE_CLASS: i32 = 6;
 const HEADER_X_POLICY_TIER: i32 = 1;
 const HEADER_X_FLUXHEIM_POLICY_BRANCH: i32 = 2;
 const HEADER_X_POWERED_BY: i32 = 3;
@@ -59,6 +60,10 @@ const VALUE_STATIC: i32 = 3;
 const VALUE_GOLD: i32 = 4;
 const VALUE_MOBILE: i32 = 5;
 const VALUE_DESKTOP: i32 = 6;
+const VALUE_CONTENT_TYPE_IMAGE: i32 = 7;
+const VALUE_CONTENT_TYPE_HTML: i32 = 8;
+const VALUE_CONTENT_TYPE_JSON: i32 = 9;
+const VALUE_CONTENT_TYPE_TEXT: i32 = 10;
 const PATH_CLASS_OTHER: i32 = 0;
 const PATH_CLASS_API: i32 = 1;
 const PATH_CLASS_STATIC: i32 = 2;
@@ -1012,6 +1017,7 @@ pub(crate) struct NativeWasmCacheLookupContext {
 pub(crate) struct NativeWasmCacheStoreContext {
     path_class: i32,
     response_status: i32,
+    response_content_type_class: i32,
 }
 
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
@@ -1081,6 +1087,7 @@ impl NativeWasmCacheStoreContext {
         Self {
             path_class,
             response_status: i32::from(response.status()),
+            response_content_type_class: wasm_response_content_type_class(response),
         }
     }
 }
@@ -1252,6 +1259,7 @@ fn wasm_cache_store_host_functions(
         move |kind, _unused| match kind {
             HOST_CONTEXT_PATH_CLASS => Ok(context.path_class),
             HOST_CONTEXT_RESPONSE_STATUS => Ok(context.response_status),
+            HOST_CONTEXT_RESPONSE_CONTENT_TYPE_CLASS => Ok(context.response_content_type_class),
             _ => Err("unknown wasm context field".to_owned()),
         },
     );
@@ -1442,6 +1450,33 @@ fn wasm_device_class_header(request: &NativeHttp1Request) -> i32 {
         .unwrap_or(0)
 }
 
+fn wasm_response_content_type_class(response: &NativeHttp1Response) -> i32 {
+    let Some((_, value)) = response
+        .headers()
+        .iter()
+        .find(|(name, _)| name.eq_ignore_ascii_case("content-type"))
+    else {
+        return 0;
+    };
+    let media_type = value
+        .split(';')
+        .next()
+        .unwrap_or_default()
+        .trim()
+        .to_ascii_lowercase();
+    if media_type.starts_with("image/") {
+        VALUE_CONTENT_TYPE_IMAGE
+    } else if media_type == "text/html" || media_type == "application/xhtml+xml" {
+        VALUE_CONTENT_TYPE_HTML
+    } else if media_type == "application/json" || media_type.ends_with("+json") {
+        VALUE_CONTENT_TYPE_JSON
+    } else if media_type.starts_with("text/") {
+        VALUE_CONTENT_TYPE_TEXT
+    } else {
+        0
+    }
+}
+
 fn locked_wasm_cache_key_components(
     state: &Arc<Mutex<Vec<NativeProxyCacheKeyComponent>>>,
 ) -> Vec<NativeProxyCacheKeyComponent> {

docs/versioning-plan.md

@@ -3127,9 +3127,10 @@ Stable scope:
   without storing while normal requests still produce MISS then HIT, and that a
   plugin can skip or deny storage before memory/disk writes.
 - `v1.7.5`: add the next bounded cache-policy ABI slice for cache-key
-  components, TTL override, tag assignment, store-admission header inspection,
-  and safe response-header mutation, with live tests for TTL bounds, tag
-  assignment, and low-cardinality key validation.
+  components, TTL override, tag assignment, symbolic store-admission
+  content-type inspection, and safe fixed response-header mutation, with live
+  tests for TTL bounds, tag assignment, image-only store metadata, and
+  low-cardinality key validation.
 - `v1.7.6`: harden the mature plugin runtime after the request, response,
   routing, and cache hook families exist. Finish atomic compiled-module reload
   generation handling, broaden admin and metrics visibility across all hook
@@ -4776,9 +4777,10 @@ circular dependencies.
   lookup/pass/bypass/deny and store continue/skip/deny decisions, with live
   cache HIT/MISS and skip-store tests.
 - `v1.7.5`: VCL-like cache policy mutation hooks for bounded symbolic
-  cache-key components and fixed-ID TTL/tag store metadata, with live
-  low-cardinality key and TTL expiry tests. Richer store-admission mutation
-  remains staged for a later cache-policy slice.
+  cache-key components, fixed-ID TTL/tag store metadata, symbolic content-type
+  inspection, and fixed stored response-header metadata, with live
+  low-cardinality key, image-only metadata, and TTL expiry tests. Richer
+  store-admission mutation remains staged for a later cache-policy slice.
 - `v1.7.6`: mature-runtime hardening across all hook families: compiled-module
   cache isolation, cross-family chain regression tests, reload hash-change
   tests, metrics/admin completeness, and secret-safe labels. The initial

docs/wasm-extensibility.md

@@ -188,7 +188,8 @@ Plugins attached to `cache-store` export `fluxheim_cache_store() -> i32`:
 - `2`: deny with `403`.
 
 The cache store host-call surface exposes only the path class, response status,
-fixed TTL IDs, fixed tag IDs, and one fixed stored response-header family.
+symbolic response content-type class, fixed TTL IDs, fixed tag IDs, and one
+fixed stored response-header family.
 Plugins can call `set_cache_ttl(1, 0)` for a short bounded TTL,
 `set_cache_ttl(2, 0)` for a medium bounded TTL, `add_cache_tag(1, 0)` for
 `wasm-policy`, `add_cache_tag(2, 0)` for `wasm-gold`,
@@ -201,6 +202,11 @@ request bodies, arbitrary cache-key bytes, arbitrary TTLs, arbitrary tag
 strings, arbitrary stored response headers, cached objects, and response-store
 body mutation are not exposed in `1.7.5`.
 
+Cache-store response-header inspection is also symbolic. `context(6, 0)`
+returns `0` for unset/other, `7` for image media types, `8` for HTML, `9` for
+JSON, and `10` for text media types. Plugins cannot read raw response header
+names or values through this cache-store surface.
+
 Cache-store chains use the same restrictive aggregation model as other hook
 families: every hook runs unless a hook returns `deny`; an earlier `skip` does
 not mask a later `deny`.
@@ -210,8 +216,8 @@ not mask a later `deny`.
 subset as concrete Wasm Text modules, and `examples/wasm/cache-policy.toml`
 shows the matching plugin/attachment config shape. The example is test-backed
 by a live native HTTP/1 listener test that compiles the checked-in sources and
-verifies mobile/desktop cache variants, short TTL expiry, and fixed stored
-response headers.
+verifies mobile/desktop cache variants, image-only store metadata, short TTL
+expiry, and fixed stored response headers.
 
 Allowed hooks:
 

docs/wasm-policy-example-parity.md

@@ -147,7 +147,8 @@ Required live test:
 Target line: starts in `v1.7.4` with cache lookup/pass/bypass/deny decisions
 and cache-store skip/deny decisions. `v1.7.5` adds bounded symbolic cache-key
 components with live low-cardinality variant tests plus fixed-ID TTL/tag/header
-store metadata with live TTL expiry and stored-header HIT coverage. The
+store metadata and symbolic response content-type inspection with live TTL
+expiry and stored-header HIT coverage. The
 checked-in `examples/wasm/cache-lookup-policy.wat` and
 `examples/wasm/cache-store-policy.wat` fixtures plus the
 `examples/wasm/cache-policy.toml` config template document this subset, and the

examples/wasm/README.md

@@ -12,6 +12,8 @@ production.
 - apply a bounded short TTL;
 - add the fixed `wasm-policy` cache tag;
 - add the fixed stored response header `x-fluxheim-cache-policy: wasm`.
+- apply those store mutations only when Fluxheim reports the response
+  content-type as the symbolic image class.
 
 The example intentionally uses separate modules for lookup and store phases
 because Fluxheim links only the host calls valid for the current phase. It also

examples/wasm/cache-store-policy.wat

@@ -1,22 +1,30 @@
 (module
+  (import "fluxheim_policy_v1" "context" (func $context (param i32 i32) (result i32)))
   (import "fluxheim_policy_v1" "set_cache_ttl" (func $set_cache_ttl (param i32 i32) (result i32)))
   (import "fluxheim_policy_v1" "add_cache_tag" (func $add_cache_tag (param i32 i32) (result i32)))
   (import "fluxheim_policy_v1" "set_cache_store_header" (func $set_cache_store_header (param i32 i32) (result i32)))
 
   (func (export "fluxheim_cache_store") (result i32)
-    i32.const 1
+    i32.const 6
     i32.const 0
-    call $set_cache_ttl
-    drop
+    call $context
+    i32.const 7
+    i32.eq
+    if
+      i32.const 1
+      i32.const 0
+      call $set_cache_ttl
+      drop
 
-    i32.const 1
-    i32.const 0
-    call $add_cache_tag
-    drop
+      i32.const 1
+      i32.const 0
+      call $add_cache_tag
+      drop
 
-    i32.const 1
-    i32.const 1
-    call $set_cache_store_header
-    drop
+      i32.const 1
+      i32.const 1
+      call $set_cache_store_header
+      drop
+    end
 
     i32.const 0))