refactor(core): replace Box<dyn Any> extensions with generic type parameter

Author: AndreyErmilov

hitbox-backend/src/composition/context.rs

@@ -108,14 +108,6 @@ impl Context for CompositionContext {
         self.inner.set_stored(stored);
     }
 
-    fn extensions(&self) -> Option<&(dyn Any + Send + Sync)> {
-        self.inner.extensions()
-    }
-
-    fn set_extensions(&mut self, ext: Option<Box<dyn Any + Send + Sync>>) {
-        self.inner.set_extensions(ext);
-    }
-
     fn as_any(&self) -> &dyn Any {
         self
     }

hitbox-core/src/context.rs

@@ -192,18 +192,6 @@ pub trait Context: Send + Sync {
         // Default implementation does nothing
     }
 
-    // Protocol extensions
-
-    /// Returns a reference to the protocol-specific extension data, if any.
-    fn extensions(&self) -> Option<&(dyn Any + Send + Sync)> {
-        None
-    }
-
-    /// Sets protocol-specific extension data.
-    fn set_extensions(&mut self, _ext: Option<Box<dyn Any + Send + Sync>>) {
-        // Default implementation does nothing
-    }
-
     // Type identity and conversion
 
     /// Returns a reference to self as `Any` for downcasting.
@@ -277,9 +265,14 @@ pub fn finalize_context(ctx: BoxContext) -> CacheContext {
 /// Context information about a cache operation.
 ///
 /// This is the single source of truth for all cache operation metadata.
-/// Protocol-specific data (e.g., HTTP status codes) is stored in [`extensions`](Self::extensions).
-#[derive(Debug, Default)]
-pub struct CacheContext {
+/// The `Ext` type parameter carries protocol-specific data (e.g., HTTP status codes).
+///
+/// - Inside the FSM: `CacheContext` (= `CacheContext<()>`) — protocol-agnostic
+/// - At the integration boundary: `CacheContext<Option<HttpCacheData>>` — protocol-specific
+///
+/// Use [`with_extensions`](Self::with_extensions) to transform between extension types.
+#[derive(Debug, Clone, Default)]
+pub struct CacheContext<Ext = ()> {
     /// What the cache did with this request (hit, stale, collapsed, or forwarded).
     pub status: CacheStatus,
     /// Read mode for this operation.
@@ -293,28 +286,10 @@ pub struct CacheContext {
     pub stored: bool,
     /// Protocol-specific extension data.
     ///
-    /// Each protocol crate defines its own struct and stores it here.
-    /// Costs 8 bytes (null pointer) when unused, one small heap allocation when used.
-    ///
-    /// Examples:
-    /// - HTTP: `HttpCacheData { upstream_status: u16 }`
-    /// - gRPC: `GrpcCacheData { grpc_status: i32 }`
-    pub extensions: Option<Box<dyn Any + Send + Sync>>,
-}
-
-impl Clone for CacheContext {
-    fn clone(&self) -> Self {
-        Self {
-            status: self.status,
-            read_mode: self.read_mode,
-            source: self.source.clone(),
-            timing: self.timing,
-            stored: self.stored,
-            // Extensions are protocol-specific and not cloned.
-            // They are only needed at the header-generation point.
-            extensions: None,
-        }
-    }
+    /// Defaults to `()` inside the FSM. Protocol crates use their own type:
+    /// - HTTP: `Option<HttpCacheData>`
+    /// - gRPC: `Option<GrpcCacheData>`
+    pub extensions: Ext,
 }
 
 impl CacheContext {
@@ -327,6 +302,31 @@ impl CacheContext {
     }
 }
 
+impl<Ext> CacheContext<Ext> {
+    /// Transform this context's extension type.
+    ///
+    /// Copies all protocol-agnostic fields and replaces extensions with the new value.
+    /// Used at the integration boundary to add protocol-specific data.
+    ///
+    /// # Example
+    ///
+    /// ```ignore
+    /// let ctx: CacheContext = finalize_context(box_ctx); // CacheContext<()>
+    /// let http_ctx = ctx.with_extensions(Some(HttpCacheData { upstream_status: 200 }));
+    /// // http_ctx: CacheContext<Option<HttpCacheData>>
+    /// ```
+    pub fn with_extensions<NewExt>(self, extensions: NewExt) -> CacheContext<NewExt> {
+        CacheContext {
+            status: self.status,
+            read_mode: self.read_mode,
+            source: self.source,
+            timing: self.timing,
+            stored: self.stored,
+            extensions,
+        }
+    }
+}
+
 impl Context for CacheContext {
     fn status(&self) -> CacheStatus {
         self.status
@@ -368,14 +368,6 @@ impl Context for CacheContext {
         self.stored = stored;
     }
 
-    fn extensions(&self) -> Option<&(dyn Any + Send + Sync)> {
-        self.extensions.as_deref()
-    }
-
-    fn set_extensions(&mut self, ext: Option<Box<dyn Any + Send + Sync>>) {
-        self.extensions = ext;
-    }
-
     fn as_any(&self) -> &dyn Any {
         self
     }
@@ -393,25 +385,26 @@ impl Context for CacheContext {
 ///
 /// This trait provides a protocol-agnostic way to attach cache status
 /// metadata to responses. Each protocol (HTTP, gRPC, etc.) implements
-/// this trait with its own configuration type.
-///
-/// The full [`CacheContext`] is passed, giving implementations access to
-/// status, timing, stored flag, and protocol-specific extensions.
+/// this trait with its own configuration and extension types.
 ///
 /// # Example
 ///
 /// ```ignore
 /// use hitbox_core::{CacheContext, CacheStatusExt};
 ///
 /// // For HTTP responses (implemented in hitbox-http)
-/// response.cache_status(&cache_context, &config);
+/// let http_ctx = cache_context.with_extensions(Some(http_data));
+/// response.cache_status(&http_ctx, &config);
 /// ```
 pub trait CacheStatusExt {
     /// Configuration type for applying cache status (e.g., header name for HTTP).
     type Config;
 
+    /// Protocol-specific extension type carried by [`CacheContext`].
+    type Extensions;
+
     /// Applies cache status information to the response.
-    fn cache_status(&mut self, context: &CacheContext, config: &Self::Config);
+    fn cache_status(&mut self, context: &CacheContext<Self::Extensions>, config: &Self::Config);
 }
 
 #[cfg(test)]
@@ -433,7 +426,7 @@ mod tests {
         println!("BoxContext size: {} bytes", box_ctx_size);
         println!("S4 inline space: {} bytes", s4_space);
 
-        // CacheContext now exceeds S4 due to timing + stored + extensions fields.
+        // CacheContext now exceeds S4 due to timing + stored fields.
         // SmallBox automatically falls back to heap allocation, which is fine
         // since context is created once per request.
         println!(
@@ -461,4 +454,17 @@ mod tests {
         assert!(!CacheStatus::Forward(ForwardReason::Expired).is_served_from_cache());
         assert!(!CacheStatus::Forward(ForwardReason::Bypass).is_served_from_cache());
     }
+
+    #[test]
+    fn test_with_extensions() {
+        let ctx: CacheContext = CacheContext {
+            status: CacheStatus::Hit,
+            stored: true,
+            ..Default::default()
+        };
+        let ext_ctx = ctx.with_extensions(Some(42u16));
+        assert_eq!(ext_ctx.status, CacheStatus::Hit);
+        assert!(ext_ctx.stored);
+        assert_eq!(ext_ctx.extensions, Some(42u16));
+    }
 }

hitbox-http/src/cache_status.rs

@@ -83,7 +83,10 @@ impl HttpCacheStatusConfig {
 /// Formats the RFC 9211 `Cache-Status` header value.
 ///
 /// See: <https://www.rfc-editor.org/rfc/rfc9211>
-fn format_cache_status(ctx: &CacheContext, cache_name: &str) -> String {
+/// Type alias for the HTTP-specific cache context.
+pub type HttpCacheContext = CacheContext<Option<HttpCacheData>>;
+
+fn format_cache_status(ctx: &HttpCacheContext, cache_name: &str) -> String {
     let mut buf = String::with_capacity(64);
     buf.push_str(cache_name);
 
@@ -114,9 +117,7 @@ fn format_cache_status(ctx: &CacheContext, cache_name: &str) -> String {
             let _ = write!(buf, "; fwd={fwd_value}");
 
             // Add fwd-status from protocol extensions
-            if let Some(ext) = &ctx.extensions
-                && let Some(http_data) = ext.downcast_ref::<HttpCacheData>()
-            {
+            if let Some(http_data) = &ctx.extensions {
                 let _ = write!(buf, "; fwd-status={}", http_data.upstream_status);
             }
         }
@@ -134,7 +135,7 @@ fn format_cache_status(ctx: &CacheContext, cache_name: &str) -> String {
 ///
 /// Returns `None` if the response wasn't served from cache.
 /// Per RFC 9111 §5.1, caches MUST generate an Age header in responses served from cache.
-fn compute_age(ctx: &CacheContext) -> Option<u64> {
+fn compute_age(ctx: &HttpCacheContext) -> Option<u64> {
     if !ctx.status.is_served_from_cache() {
         return None;
     }
@@ -150,8 +151,9 @@ where
     ResBody: HttpBody,
 {
     type Config = HttpCacheStatusConfig;
+    type Extensions = Option<HttpCacheData>;
 
-    fn cache_status(&mut self, context: &CacheContext, config: &Self::Config) {
+    fn cache_status(&mut self, context: &HttpCacheContext, config: &Self::Config) {
         // RFC 9211: Cache-Status structured header
         let cache_status_value = format_cache_status(context, &config.cache_name);
         if let Ok(value) = HeaderValue::from_str(&cache_status_value) {
@@ -191,7 +193,7 @@ mod tests {
         let created = Utc::now() - Duration::seconds(900);
         let expire = Utc::now() + Duration::seconds(2700);
 
-        let ctx = CacheContext {
+        let ctx: HttpCacheContext = CacheContext {
             status: CacheStatus::Hit,
             timing: Some(CacheTiming {
                 created_at: created,
@@ -210,7 +212,7 @@ mod tests {
 
     #[test]
     fn test_format_cache_miss() {
-        let ctx = CacheContext {
+        let ctx: HttpCacheContext = CacheContext {
             status: CacheStatus::Forward(ForwardReason::Miss),
             stored: true,
             ..Default::default()
@@ -222,12 +224,12 @@ mod tests {
 
     #[test]
     fn test_format_cache_miss_with_fwd_status() {
-        let ctx = CacheContext {
+        let ctx: HttpCacheContext = CacheContext {
             status: CacheStatus::Forward(ForwardReason::Miss),
             stored: true,
-            extensions: Some(Box::new(HttpCacheData {
+            extensions: Some(HttpCacheData {
                 upstream_status: 200,
-            })),
+            }),
             ..Default::default()
         };
 
@@ -237,7 +239,7 @@ mod tests {
 
     #[test]
     fn test_format_cache_bypass() {
-        let ctx = CacheContext {
+        let ctx: HttpCacheContext = CacheContext {
             status: CacheStatus::Forward(ForwardReason::Bypass),
             ..Default::default()
         };
@@ -251,7 +253,7 @@ mod tests {
         let created = Utc::now() - Duration::seconds(3720);
         let expire = Utc::now() - Duration::seconds(120);
 
-        let ctx = CacheContext {
+        let ctx: HttpCacheContext = CacheContext {
             status: CacheStatus::Stale,
             timing: Some(CacheTiming {
                 created_at: created,
@@ -269,7 +271,7 @@ mod tests {
 
     #[test]
     fn test_format_collapsed() {
-        let ctx = CacheContext {
+        let ctx: HttpCacheContext = CacheContext {
             status: CacheStatus::Collapsed,
             timing: Some(CacheTiming {
                 created_at: Utc::now(),
@@ -284,12 +286,12 @@ mod tests {
 
     #[test]
     fn test_format_expired_forward() {
-        let ctx = CacheContext {
+        let ctx: HttpCacheContext = CacheContext {
             status: CacheStatus::Forward(ForwardReason::Expired),
             stored: true,
-            extensions: Some(Box::new(HttpCacheData {
+            extensions: Some(HttpCacheData {
                 upstream_status: 200,
-            })),
+            }),
             ..Default::default()
         };
 
@@ -299,7 +301,7 @@ mod tests {
 
     #[test]
     fn test_format_custom_cache_name() {
-        let ctx = CacheContext {
+        let ctx: HttpCacheContext = CacheContext {
             status: CacheStatus::Hit,
             ..Default::default()
         };
@@ -310,7 +312,7 @@ mod tests {
 
     #[test]
     fn test_compute_age_cache_hit() {
-        let ctx = CacheContext {
+        let ctx: HttpCacheContext = CacheContext {
             status: CacheStatus::Hit,
             timing: Some(CacheTiming {
                 created_at: Utc::now() - Duration::seconds(900),
@@ -325,7 +327,7 @@ mod tests {
 
     #[test]
     fn test_compute_age_cache_miss_returns_none() {
-        let ctx = CacheContext {
+        let ctx: HttpCacheContext = CacheContext {
             status: CacheStatus::Forward(ForwardReason::Miss),
             ..Default::default()
         };
@@ -335,7 +337,7 @@ mod tests {
 
     #[test]
     fn test_compute_age_no_timing_returns_none() {
-        let ctx = CacheContext {
+        let ctx: HttpCacheContext = CacheContext {
             status: CacheStatus::Hit,
             timing: None,
             ..Default::default()
@@ -346,12 +348,12 @@ mod tests {
 
     #[test]
     fn test_format_upstream_error_not_stored() {
-        let ctx = CacheContext {
+        let ctx: HttpCacheContext = CacheContext {
             status: CacheStatus::Forward(ForwardReason::Miss),
             stored: false,
-            extensions: Some(Box::new(HttpCacheData {
+            extensions: Some(HttpCacheData {
                 upstream_status: 500,
-            })),
+            }),
             ..Default::default()
         };
 

hitbox-reqwest/src/middleware.rs

@@ -140,21 +140,23 @@ where
             ));
 
         // Execute cache future
-        let (response, mut cache_context) = cache_future.await;
+        let (response, cache_context) = cache_future.await;
 
         // Convert CacheableHttpResponse back to reqwest::Response
         let mut cacheable_response = response?;
 
         // Set HTTP-specific extension data (upstream status code)
-        if matches!(cache_context.status, CacheStatus::Forward(_)) {
-            let status_code = cacheable_response.parts.status.as_u16();
-            cache_context.extensions = Some(Box::new(HttpCacheData {
-                upstream_status: status_code,
-            }));
-        }
+        let http_ext = if matches!(cache_context.status, CacheStatus::Forward(_)) {
+            Some(HttpCacheData {
+                upstream_status: cacheable_response.parts.status.as_u16(),
+            })
+        } else {
+            None
+        };
+        let http_ctx = cache_context.with_extensions(http_ext);
 
         // Add cache status headers (RFC 9211 Cache-Status, Age, legacy x-cache-status)
-        cacheable_response.cache_status(&cache_context, &self.cache_status_config);
+        cacheable_response.cache_status(&http_ctx, &self.cache_status_config);
 
         let http_response = cacheable_response.into_response();
         let (parts, buffered_body) = http_response.into_parts();