Merge pull request #253 from hit-box/multi-config

Multi-config CacheFuture routing

Author: singulared

hitbox-configuration/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 ### Added
 - Initial release
+- `Endpoint` now implements `CacheConfigs` for use with `SelectiveCacheFuture` ([#253](https://github.com/hit-box/hitbox/pull/253))
 
 ### Changed
+- `Endpoint` now stores `policy` as `Arc<PolicyConfig>` ([#253](https://github.com/hit-box/hitbox/pull/253))
 - Adapted to hitbox-http 0.3 Config-based extractor/predicate API, added `Transform::Truncate` ([#202](https://github.com/hit-box/hitbox/pull/202))
+
+### Fixed
+- README doctest missing type annotations for `Endpoint::builder()` ([#253](https://github.com/hit-box/hitbox/pull/253))

hitbox-configuration/Cargo.toml

@@ -27,6 +27,7 @@ serde_json = { workspace = true }
 serde-saphyr = { workspace = true }
 indexmap = { version = "2.10", features = ["serde"] }
 thiserror = { workspace = true }
+humantime-serde = "1"
 regex = { workspace = true }
 bytes = { workspace = true }
 bytesize = { version = "2", features = ["serde"] }

hitbox-configuration/src/config.rs

@@ -1,6 +1,6 @@
-use std::{fmt::Debug, sync::Arc};
+use std::{fmt::Debug, num::NonZeroU8, sync::Arc, time::Duration};
 
-use hitbox::policy::PolicyConfig;
+use hitbox::policy;
 use hitbox_http::{
     extractors::{MethodConfig, NeutralExtractor, method::MethodExtractor, path::PathExtractor},
     predicates::{
@@ -19,6 +19,89 @@ use crate::{
     types::MaybeUndefined,
 };
 
+// =============================================================================
+// Serde-enabled policy types for configuration parsing
+// =============================================================================
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, Eq, PartialEq, Default)]
+pub enum StalePolicy {
+    #[default]
+    Return,
+    Revalidate,
+    OffloadRevalidate,
+}
+
+impl From<StalePolicy> for policy::StalePolicy {
+    fn from(s: StalePolicy) -> Self {
+        match s {
+            StalePolicy::Return => policy::StalePolicy::Return,
+            StalePolicy::Revalidate => policy::StalePolicy::Revalidate,
+            StalePolicy::OffloadRevalidate => policy::StalePolicy::OffloadRevalidate,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, Eq, PartialEq, Default)]
+pub struct CacheBehaviorPolicy {
+    #[serde(default)]
+    stale: StalePolicy,
+}
+
+impl From<CacheBehaviorPolicy> for policy::CacheBehaviorPolicy {
+    fn from(s: CacheBehaviorPolicy) -> Self {
+        policy::CacheBehaviorPolicy {
+            stale: s.stale.into(),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Default, Serialize, Deserialize, Eq, PartialEq)]
+pub struct EnabledCacheConfig {
+    #[serde(default, with = "humantime_serde")]
+    ttl: Option<Duration>,
+    #[serde(default, with = "humantime_serde")]
+    stale: Option<Duration>,
+    #[serde(default)]
+    policy: CacheBehaviorPolicy,
+    concurrency: Option<NonZeroU8>,
+}
+
+impl From<EnabledCacheConfig> for policy::EnabledCacheConfig {
+    fn from(s: EnabledCacheConfig) -> Self {
+        policy::EnabledCacheConfig {
+            ttl: s.ttl,
+            stale: s.stale,
+            policy: s.policy.into(),
+            concurrency: s.concurrency,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, Eq, PartialEq)]
+pub enum PolicyConfig {
+    Enabled(EnabledCacheConfig),
+    Disabled,
+}
+
+impl Default for PolicyConfig {
+    fn default() -> Self {
+        PolicyConfig::Enabled(EnabledCacheConfig::default())
+    }
+}
+
+impl From<PolicyConfig> for policy::PolicyConfig {
+    fn from(s: PolicyConfig) -> Self {
+        match s {
+            PolicyConfig::Enabled(config) => policy::PolicyConfig::Enabled(config.into()),
+            PolicyConfig::Disabled => policy::PolicyConfig::Disabled,
+        }
+    }
+}
+
+// =============================================================================
+// ConfigEndpoint
+// =============================================================================
+
 #[derive(Serialize, Deserialize, Debug, Eq, PartialEq, Default)]
 pub struct ConfigEndpoint {
     #[serde(default)]
@@ -84,7 +167,7 @@ impl ConfigEndpoint {
             extractors,
             request_predicates,
             response_predicates,
-            policy: self.policy,
+            policy: Arc::new(self.policy.into()),
         })
     }
 }

hitbox-configuration/src/endpoint.rs

@@ -2,7 +2,7 @@ use std::{fmt::Debug, sync::Arc};
 
 use hitbox::{
     Extractor, Predicate,
-    config::{BoxExtractor, BoxPredicate, CacheConfig},
+    config::{BoxExtractor, BoxPredicate, CacheConfig, CacheConfigs},
     policy::PolicyConfig,
 };
 use hitbox_http::{CacheableHttpRequest, CacheableHttpResponse};
@@ -28,7 +28,7 @@ where
     pub request_predicates: ArcRequestPredicate<ReqBody>,
     pub response_predicates: ArcResponsePredicate<ResBody>,
     pub extractors: ArcRequestExtractor<ReqBody>,
-    pub policy: PolicyConfig,
+    pub policy: Arc<PolicyConfig>,
 }
 
 impl<ReqBody, ResBody> Debug for Endpoint<ReqBody, ResBody>
@@ -56,7 +56,7 @@ where
             request_predicates: Arc::clone(&self.request_predicates),
             response_predicates: Arc::clone(&self.response_predicates),
             extractors: Arc::clone(&self.extractors),
-            policy: self.policy.clone(),
+            policy: Arc::clone(&self.policy),
         }
     }
 }
@@ -103,8 +103,25 @@ where
         Arc::clone(&self.extractors)
     }
 
-    fn policy(&self) -> &PolicyConfig {
-        &self.policy
+    fn policy(&self) -> Arc<PolicyConfig> {
+        Arc::clone(&self.policy)
+    }
+}
+
+impl<ReqBody, ResBody> CacheConfigs<CacheableHttpRequest<ReqBody>, CacheableHttpResponse<ResBody>>
+    for Endpoint<ReqBody, ResBody>
+where
+    ReqBody: hyper::body::Body + Send + 'static,
+    ReqBody::Error: Send,
+    ReqBody::Data: Send,
+    ResBody: hyper::body::Body + Send + 'static,
+    ResBody::Error: Send,
+    ResBody::Data: Send,
+{
+    type Config = Self;
+
+    fn configs(&self) -> &[Self::Config] {
+        std::slice::from_ref(self)
     }
 }
 
@@ -128,7 +145,7 @@ where
     request_predicates: Option<ArcRequestPredicate<ReqBody>>,
     response_predicates: Option<ArcResponsePredicate<ResBody>>,
     extractors: Option<ArcRequestExtractor<ReqBody>>,
-    policy: PolicyConfig,
+    policy: Arc<PolicyConfig>,
 }
 
 impl<ReqBody, ResBody> EndpointBuilder<ReqBody, ResBody>
@@ -142,7 +159,7 @@ where
             request_predicates: None,
             response_predicates: None,
             extractors: None,
-            policy: PolicyConfig::default(),
+            policy: Arc::new(PolicyConfig::default()),
         }
     }
 
@@ -181,7 +198,10 @@ where
 
     /// Set the cache policy.
     pub fn policy(self, policy: PolicyConfig) -> Self {
-        Self { policy, ..self }
+        Self {
+            policy: Arc::new(policy),
+            ..self
+        }
     }
 
     /// Build the Endpoint, using defaults for any unset fields.

hitbox-configuration/tests/test_config_endpoint.rs

@@ -1,16 +1,10 @@
 use bytes::Bytes;
-use hitbox::policy::PolicyConfig;
 use hitbox_configuration::{ConfigEndpoint, types::MaybeUndefined};
 use http_body_util::Empty;
-use std::time::Duration;
 
 type ReqBody = Empty<Bytes>;
 type ResBody = Empty<Bytes>;
 
-fn default_policy() -> PolicyConfig {
-    PolicyConfig::builder().ttl(Duration::from_secs(60)).build()
-}
-
 #[test]
 fn test_extractors_variants() {
     for extractors in [
@@ -20,9 +14,7 @@ fn test_extractors_variants() {
     ] {
         let endpoint = ConfigEndpoint {
             extractors,
-            request: MaybeUndefined::Undefined,
-            response: MaybeUndefined::Undefined,
-            policy: default_policy(),
+            ..Default::default()
         };
         assert!(endpoint.extractors::<ReqBody>().is_ok());
     }
@@ -31,26 +23,17 @@ fn test_extractors_variants() {
 #[test]
 fn test_into_endpoint_variants() {
     // all undefined
-    let endpoint = ConfigEndpoint {
-        extractors: MaybeUndefined::Undefined,
-        request: MaybeUndefined::Undefined,
-        response: MaybeUndefined::Undefined,
-        policy: default_policy(),
-    };
+    let endpoint = ConfigEndpoint::default();
     assert!(endpoint.into_endpoint::<ReqBody, ResBody>().is_ok());
 
     // all null
     let endpoint = ConfigEndpoint {
         extractors: MaybeUndefined::Null,
         request: MaybeUndefined::Null,
         response: MaybeUndefined::Null,
-        policy: default_policy(),
+        ..Default::default()
     };
     assert!(endpoint.into_endpoint::<ReqBody, ResBody>().is_ok());
-
-    // default
-    let endpoint = ConfigEndpoint::default();
-    assert!(endpoint.into_endpoint::<ReqBody, ResBody>().is_ok());
 }
 
 #[test]

hitbox-core/CHANGELOG.md

@@ -5,6 +5,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Added
+- `CacheConfig` and `CacheConfigs` traits for cache configuration abstraction ([#253](https://github.com/hit-box/hitbox/pull/253))
+
+### Changed
+- `PolicyConfig` and related policy types moved from `hitbox` crate ([#253](https://github.com/hit-box/hitbox/pull/253))
+- **Breaking:** `CacheConfig::policy()` now returns `Arc<PolicyConfig>` instead of `&PolicyConfig` for consistency with other trait methods ([#253](https://github.com/hit-box/hitbox/pull/253))
 
 ### Changed
 - **Breaking:** `Upstream::call` now takes `self` by value instead of `&mut self` — the FSM calls upstream exactly once, so consuming is semantically correct and simplifies lifetime handling ([#206](https://github.com/hit-box/hitbox/pull/206))

hitbox-core/src/config.rs

@@ -0,0 +1,70 @@
+//! Cache configuration traits.
+//!
+//! - [`CacheConfig`] — single cache configuration (predicates, extractor, policy)
+//! - [`CacheConfigs`] — ordered collection of configurations for multi-config routing
+
+use std::sync::Arc;
+
+use crate::Extractor;
+use crate::policy::PolicyConfig;
+use crate::predicate::Predicate;
+
+/// Trait for cache configuration.
+///
+/// Provides predicates for determining cacheability, extractors for generating
+/// cache keys, and policy for TTL/staleness behavior.
+pub trait CacheConfig<Req, Res> {
+    /// Predicate type for filtering requests.
+    type RequestPredicate: Predicate<Subject = Req> + Send + Sync + 'static;
+    /// Predicate type for filtering responses.
+    type ResponsePredicate: Predicate<Subject = Res> + Send + Sync + 'static;
+    /// Extractor type for generating cache keys.
+    type Extractor: Extractor<Subject = Req> + Send + Sync + 'static;
+
+    /// Returns predicates that decide if a request should be cached.
+    fn request_predicates(&self) -> Self::RequestPredicate;
+    /// Returns predicates that decide if a response should be cached.
+    fn response_predicates(&self) -> Self::ResponsePredicate;
+    /// Returns extractors that generate cache keys from requests.
+    fn extractors(&self) -> Self::Extractor;
+    /// Returns TTL and behavior policy for cached entries.
+    fn policy(&self) -> Arc<PolicyConfig>;
+}
+
+/// Trait for providing one or more cache configurations.
+///
+/// Configurations are evaluated in order; first match wins.
+/// Use [`CacheConfig`] for a single configuration that wraps itself,
+/// or a multi-config container like `SelectiveConfig` for routing.
+pub trait CacheConfigs<Req, Res> {
+    /// The individual config type.
+    type Config: CacheConfig<Req, Res>;
+
+    /// Returns the ordered list of configurations.
+    fn configs(&self) -> &[Self::Config];
+}
+
+impl<T, Req, Res> CacheConfig<Req, Res> for Arc<T>
+where
+    T: CacheConfig<Req, Res>,
+{
+    type RequestPredicate = T::RequestPredicate;
+    type ResponsePredicate = T::ResponsePredicate;
+    type Extractor = T::Extractor;
+
+    fn request_predicates(&self) -> Self::RequestPredicate {
+        self.as_ref().request_predicates()
+    }
+
+    fn response_predicates(&self) -> Self::ResponsePredicate {
+        self.as_ref().response_predicates()
+    }
+
+    fn extractors(&self) -> Self::Extractor {
+        self.as_ref().extractors()
+    }
+
+    fn policy(&self) -> Arc<PolicyConfig> {
+        self.as_ref().policy()
+    }
+}

hitbox-core/src/lib.rs

@@ -2,6 +2,7 @@
 #![warn(missing_docs)]
 
 pub mod cacheable;
+pub mod config;
 pub mod context;
 pub mod extractor;
 pub mod key;
@@ -15,6 +16,7 @@ pub mod upstream;
 pub mod value;
 
 pub use cacheable::Cacheable;
+pub use config::{CacheConfig, CacheConfigs};
 pub use context::{
     BoxContext, CacheContext, CacheStatus, CacheStatusExt, Context, ReadMode, ResponseSource,
     finalize_context,
@@ -23,7 +25,10 @@ pub use extractor::Extractor;
 pub use key::{CacheKey, KeyPart, KeyParts};
 pub use label::BackendLabel;
 pub use offload::{DisabledOffload, Offload, OffloadKey};
-pub use policy::{CachePolicy, EntityPolicyConfig};
+pub use policy::{
+    CacheBehaviorPolicy, CachePolicy, ConcurrencyLimit, EnabledCacheConfig, EntityPolicyConfig,
+    PolicyConfig, PolicyConfigBuilder, StalePolicy,
+};
 pub use predicate::{And, Neutral, Not, Or, Predicate, PredicateExt, PredicateResult};
 pub use request::{CacheablePolicyData, CacheableRequest, RequestCachePolicy};
 pub use response::{CacheState, CacheableResponse, ResponseCachePolicy};