Prevent 304 responses for SSAT root documents

crates/trusted-server-adapter-cloudflare/src/platform.rs

@@ -253,13 +253,44 @@ fn is_hop_by_hop_response_header(name: &str, connection_tokens: &[String]) -> bo
     HOP_BY_HOP.iter().any(|header| *header == lower) || connection_tokens.contains(&lower)
 }
 
+/// Cache policy for the outbound Workers `fetch` derived from
+/// [`PlatformHttpRequest::bypass_cache`].
+///
+/// Workers subrequests are eligible for Cloudflare's cache by default, so an
+/// ad-stack navigation could otherwise be satisfied from cache (or revalidated
+/// into a bodyless 304) instead of receiving a complete origin body. Mapping
+/// the bypass flag to the runtime's `no-store` mode keeps the core contract's
+/// cache-bypass guarantee intact on this adapter.
+///
+/// Extracted as a free function over a target-independent enum so the mapping
+/// is testable on native targets, where the `#[cfg(target_arch = "wasm32")]`
+/// `execute` impl and its `worker` dependency are excluded from the test
+/// binary.
+#[cfg(any(target_arch = "wasm32", test))]
+#[derive(Debug, Clone, Copy, Eq, PartialEq)]
+enum OutboundCacheMode {
+    /// Leave the Workers runtime's default cache behavior in place.
+    RuntimeDefault,
+    /// Maps to `worker::CacheMode::NoStore`.
+    NoStore,
+}
+
+#[cfg(any(target_arch = "wasm32", test))]
+fn outbound_cache_mode(bypass_cache: bool) -> OutboundCacheMode {
+    if bypass_cache {
+        OutboundCacheMode::NoStore
+    } else {
+        OutboundCacheMode::RuntimeDefault
+    }
+}
+
 #[cfg(target_arch = "wasm32")]
 impl CloudflareHttpClient {
     async fn execute(
         &self,
         request: PlatformHttpRequest,
     ) -> Result<PlatformResponse, Report<PlatformError>> {
-        use worker::{Fetch, Headers, Method, Request, RequestInit, RequestRedirect};
+        use worker::{CacheMode, Fetch, Headers, Method, Request, RequestInit, RequestRedirect};
 
         // The Cloudflare fetch path cannot honor Fastly-style Image Optimizer
         // metadata, and it always buffers the response body (see below). The
@@ -279,6 +310,8 @@ impl CloudflareHttpClient {
             ));
         }
 
+        let cache_mode = outbound_cache_mode(request.bypass_cache);
+
         let uri = request.request.uri().to_string();
         // http::Method always stores uppercase; worker 0.7 implements From<String> only.
         let method = Method::from(request.request.method().to_string());
@@ -318,6 +351,17 @@ impl CloudflareHttpClient {
         init.with_method(method)
             .with_headers(headers)
             .with_redirect(RequestRedirect::Manual);
+        // Setting the `cache` field requires the `cache_option_enabled`
+        // compatibility flag, which is only on by default from compatibility
+        // date 2024-11-11. `wrangler.toml`/`wrangler.ci.toml` pin an earlier
+        // date and set the flag explicitly; without it the Workers runtime
+        // throws here rather than failing at deploy time.
+        match cache_mode {
+            OutboundCacheMode::NoStore => {
+                init.with_cache(CacheMode::NoStore);
+            }
+            OutboundCacheMode::RuntimeDefault => {}
+        }
         if !body_bytes.is_empty() {
             let uint8 = js_sys::Uint8Array::from(body_bytes.as_slice());
             init.with_body(Some(uint8.into()));
@@ -866,4 +910,26 @@ mod tests {
             "error message should include provider count"
         );
     }
+
+    // -----------------------------------------------------------------------
+    // outbound_cache_mode tests
+    // -----------------------------------------------------------------------
+
+    #[test]
+    fn outbound_cache_mode_maps_bypass_to_no_store() {
+        assert_eq!(
+            outbound_cache_mode(true),
+            OutboundCacheMode::NoStore,
+            "bypass_cache should force the Workers `no-store` cache mode"
+        );
+    }
+
+    #[test]
+    fn outbound_cache_mode_leaves_default_when_not_bypassing() {
+        assert_eq!(
+            outbound_cache_mode(false),
+            OutboundCacheMode::RuntimeDefault,
+            "requests without bypass_cache should keep the runtime default cache behavior"
+        );
+    }
 }

crates/trusted-server-adapter-cloudflare/wrangler.ci.toml

@@ -1,7 +1,9 @@
 name = "trusted-server"
 main = "build/index.js"
 compatibility_date = "2024-09-23"
-compatibility_flags = ["nodejs_compat"]
+# Keep in sync with wrangler.toml. `cache_option_enabled` is required for the
+# outbound `CacheMode::NoStore` cache bypass under this compatibility date.
+compatibility_flags = ["nodejs_compat", "cache_option_enabled"]
 # No [build] section — bundle is pre-built in CI; wrangler dev must not rebuild.
 
 [[kv_namespaces]]

crates/trusted-server-adapter-cloudflare/wrangler.toml

@@ -4,7 +4,12 @@ main = "build/index.js"
 # integration tests to pick up free runtime fixes. Keep in sync with the
 # minimum date supported by the worker crate version in Cargo.toml.
 compatibility_date = "2024-09-23"
-compatibility_flags = ["nodejs_compat"]
+# `cache_option_enabled` is on by default from compatibility date 2024-11-11.
+# The pinned date predates it, so the flag must be set explicitly: without it
+# the runtime throws when a subrequest sets the `cache` field on `RequestInit`.
+# The outbound HTTP client sets `CacheMode::NoStore` for cache-bypass requests
+# (auction-eligible publisher navigations), so this is a hard requirement.
+compatibility_flags = ["nodejs_compat", "cache_option_enabled"]
 
 [build]
 command = "bash build.sh"

crates/trusted-server-adapter-fastly/src/platform.rs

@@ -525,6 +525,12 @@ fn fastly_response_to_platform(
 // FastlyPlatformHttpClient
 // ---------------------------------------------------------------------------
 
+fn apply_fastly_cache_bypass(request: &mut fastly::Request, bypass_cache: bool) {
+    if bypass_cache {
+        request.set_pass(true);
+    }
+}
+
 /// Fastly implementation of [`PlatformHttpClient`].
 ///
 /// - [`send`](PlatformHttpClient::send) converts the platform request to a
@@ -552,11 +558,13 @@ impl PlatformHttpClient for FastlyPlatformHttpClient {
         let backend_name = request.backend_name.clone();
         let image_optimizer = request.image_optimizer;
         let stream_response = request.stream_response;
+        let bypass_cache = request.bypass_cache;
         let request_is_head = request.request.method() == edgezero_core::http::Method::HEAD;
         let mut fastly_req = edge_request_to_fastly(request.request)?;
         if let Some(options) = image_optimizer {
             apply_fastly_image_optimizer(&mut fastly_req, options)?;
         }
+        apply_fastly_cache_bypass(&mut fastly_req, bypass_cache);
         let fastly_resp = fastly_req
             .send(&backend_name)
             .change_context(PlatformError::HttpClient)?;
@@ -576,7 +584,9 @@ impl PlatformHttpClient for FastlyPlatformHttpClient {
             return Err(Report::new(PlatformError::HttpClient)
                 .attach("streaming responses are not supported with Fastly send_async"));
         }
-        let fastly_req = edge_request_to_fastly(request.request)?;
+        let bypass_cache = request.bypass_cache;
+        let mut fastly_req = edge_request_to_fastly(request.request)?;
+        apply_fastly_cache_bypass(&mut fastly_req, bypass_cache);
         let pending = fastly_req
             .send_async(&backend_name)
             .change_context(PlatformError::HttpClient)?;
@@ -903,6 +913,26 @@ mod tests {
 
     // --- FastlyPlatformHttpClient -------------------------------------------
 
+    #[test]
+    fn apply_fastly_cache_bypass_sets_pass_when_enabled() {
+        let mut request = fastly::Request::get("https://example.com/");
+        apply_fastly_cache_bypass(&mut request, true);
+        assert!(
+            format!("{request:?}").contains("cache_override: Pass"),
+            "enabled bypass should select Fastly pass mode"
+        );
+    }
+
+    #[test]
+    fn apply_fastly_cache_bypass_preserves_default_when_disabled() {
+        let mut request = fastly::Request::get("https://example.com/");
+        apply_fastly_cache_bypass(&mut request, false);
+        assert!(
+            format!("{request:?}").contains("cache_override: None"),
+            "disabled bypass should preserve Fastly read-through caching"
+        );
+    }
+
     #[test]
     fn fastly_response_to_platform_allows_oversized_bodiless_content_length() {
         let oversized_content_length = (MAX_PLATFORM_RESPONSE_BODY_BYTES + 1).to_string();

crates/trusted-server-core/src/integrations/gpt_diagnostics.rs

@@ -14,7 +14,7 @@ use edgezero_core::body::Body as EdgeBody;
 
 use crate::error::TrustedServerError;
 use crate::http_util::is_navigation_request;
-use crate::response_privacy::SURROGATE_CACHE_HEADERS;
+use crate::response_privacy::CDN_CACHE_HEADERS;
 use crate::settings::{IntegrationConfig, Settings};
 use crate::tsjs;
 
@@ -242,7 +242,7 @@ pub fn finalize_response(
             header::CACHE_CONTROL,
             HeaderValue::from_static("private, no-store"),
         );
-        for name in SURROGATE_CACHE_HEADERS {
+        for name in CDN_CACHE_HEADERS {
             response.headers_mut().remove(*name);
         }
     }

crates/trusted-server-core/src/platform/http.rs

@@ -23,6 +23,12 @@ pub struct PlatformHttpRequest {
     /// Adapters that cannot attach this metadata to their send path should
     /// return an error rather than silently dropping transformations.
     pub image_optimizer: Option<PlatformImageOptimizerOptions>,
+    /// Whether the platform's intermediary response cache must be bypassed.
+    ///
+    /// Adapters without an intermediary outbound cache may treat this as already
+    /// satisfied. The option defaults to `false` so existing call sites preserve
+    /// their current cache behavior.
+    pub bypass_cache: bool,
     /// Whether the response body should stay streaming in the platform response.
     ///
     /// Adapters that cannot preserve streaming response bodies should return an
@@ -38,6 +44,7 @@ impl PlatformHttpRequest {
             request,
             backend_name: backend_name.into(),
             image_optimizer: None,
+            bypass_cache: false,
             stream_response: false,
         }
     }
@@ -53,6 +60,13 @@ impl PlatformHttpRequest {
         self
     }
 
+    /// Bypass the platform's intermediary response cache for this request.
+    #[must_use]
+    pub fn with_cache_bypass(mut self) -> Self {
+        self.bypass_cache = true;
+        self
+    }
+
     /// Preserve the upstream response body as a stream when the adapter supports it.
     ///
     /// Asset routes use this to avoid materializing large image/static responses
@@ -317,8 +331,42 @@ pub trait PlatformHttpClient: Send + Sync {
 
 #[cfg(test)]
 mod tests {
+    use edgezero_core::body::Body;
+    use edgezero_core::http::request_builder;
+
     use super::*;
 
+    #[test]
+    fn platform_http_request_cache_bypass_defaults_to_false() {
+        let request = PlatformHttpRequest::new(
+            request_builder()
+                .body(Body::empty())
+                .expect("should build request"),
+            "stub-backend",
+        );
+
+        assert!(
+            !request.bypass_cache,
+            "should preserve existing cache behavior by default"
+        );
+    }
+
+    #[test]
+    fn platform_http_request_cache_bypass_builder_enables_bypass() {
+        let request = PlatformHttpRequest::new(
+            request_builder()
+                .body(Body::empty())
+                .expect("should build request"),
+            "stub-backend",
+        )
+        .with_cache_bypass();
+
+        assert!(
+            request.bypass_cache,
+            "should enable intermediary cache bypass"
+        );
+    }
+
     // ---------------------------------------------------------------------------
     // Error-correlation interim scope (before EdgeZero #213)
     // ---------------------------------------------------------------------------

crates/trusted-server-core/src/platform/test_support.rs

@@ -228,6 +228,7 @@ pub(crate) struct StubHttpClient {
     // streaming response support.
     streaming_responses_supported: std::sync::atomic::AtomicBool,
     image_optimizer_options: Mutex<Vec<Option<PlatformImageOptimizerOptions>>>,
+    cache_bypass_flags: Mutex<Vec<bool>>,
     stream_response_flags: Mutex<Vec<bool>>,
     request_methods: Mutex<Vec<String>>,
     request_uris: Mutex<Vec<String>>,
@@ -251,6 +252,7 @@ impl StubHttpClient {
             concurrent_fanout: std::sync::atomic::AtomicBool::new(true),
             streaming_responses_supported: std::sync::atomic::AtomicBool::new(false),
             image_optimizer_options: Mutex::new(Vec::new()),
+            cache_bypass_flags: Mutex::new(Vec::new()),
             stream_response_flags: Mutex::new(Vec::new()),
             request_methods: Mutex::new(Vec::new()),
             request_uris: Mutex::new(Vec::new()),
@@ -329,6 +331,14 @@ impl StubHttpClient {
             .clone()
     }
 
+    /// Return cache-bypass flags captured per `send` or `send_async` call, in order.
+    pub(crate) fn recorded_cache_bypass_flags(&self) -> Vec<bool> {
+        self.cache_bypass_flags
+            .lock()
+            .expect("should lock cache bypass flags")
+            .clone()
+    }
+
     /// Return streaming-response flags captured per `send` call, in order.
     pub fn recorded_stream_response_flags(&self) -> Vec<bool> {
         self.stream_response_flags
@@ -391,6 +401,10 @@ impl PlatformHttpClient for StubHttpClient {
             .lock()
             .expect("should lock image optimizer options")
             .push(request.image_optimizer.clone());
+        self.cache_bypass_flags
+            .lock()
+            .expect("should lock cache bypass flags")
+            .push(request.bypass_cache);
         self.stream_response_flags
             .lock()
             .expect("should lock stream response flags")
@@ -471,6 +485,10 @@ impl PlatformHttpClient for StubHttpClient {
             .lock()
             .expect("should lock calls")
             .push(backend_name.clone());
+        self.cache_bypass_flags
+            .lock()
+            .expect("should lock cache bypass flags")
+            .push(request.bypass_cache);
 
         let headers: Vec<(String, String)> = request
             .request
@@ -775,6 +793,11 @@ mod tests {
             vec!["stub-backend"],
             "should record the backend name"
         );
+        assert_eq!(
+            stub.recorded_cache_bypass_flags(),
+            vec![false],
+            "should record the default cache-bypass flag"
+        );
     }
 
     #[test]
@@ -820,8 +843,9 @@ mod tests {
 
         let pending_a = futures::executor::block_on(stub.send_async(make_req("backend-a")))
             .expect("should start request a");
-        let pending_b = futures::executor::block_on(stub.send_async(make_req("backend-b")))
-            .expect("should start request b");
+        let pending_b =
+            futures::executor::block_on(stub.send_async(make_req("backend-b").with_cache_bypass()))
+                .expect("should start request b");
 
         assert_eq!(
             pending_a.backend_name(),
@@ -860,6 +884,11 @@ mod tests {
             vec!["backend-a", "backend-b"],
             "should record both send_async calls in order"
         );
+        assert_eq!(
+            stub.recorded_cache_bypass_flags(),
+            vec![false, true],
+            "should record both send_async cache-bypass flags in order"
+        );
     }
 
     #[test]