hitbox_core/
policy.rs

1//! Cache policy types and configuration.
2//!
3//! This module provides types for representing cache decisions and
4//! configuring caching behavior:
5//!
6//! - [`CachePolicy`] - Result of a cache decision (cacheable or not)
7//! - [`EntityPolicyConfig`] - TTL configuration for cached entities
8//!
9//! ## Cache Policy
10//!
11//! [`CachePolicy`] represents the outcome of determining whether something
12//! should be cached. It's a two-variant enum that preserves type information
13//! for both cacheable and non-cacheable cases.
14//!
15//! ## Configuration
16//!
17//! [`EntityPolicyConfig`] provides TTL (time-to-live) settings for cached
18//! entries, supporting both expiration and staleness timeouts for
19//! stale-while-revalidate patterns.
20
21use std::time::Duration;
22
23/// Result of a cache decision.
24///
25/// Represents whether an entity should be cached or passed through without
26/// caching. Both variants preserve the entity, just wrapped differently.
27///
28/// # Type Parameters
29///
30/// * `C` - Type of the cacheable entity (usually the cached representation)
31/// * `N` - Type of the non-cacheable entity (usually the original response)
32///
33/// # Example
34///
35/// ```
36/// use hitbox_core::CachePolicy;
37///
38/// fn decide_caching(status: u16, body: String) -> CachePolicy<String, String> {
39///     if status == 200 {
40///         CachePolicy::Cacheable(body)
41///     } else {
42///         CachePolicy::NonCacheable(body)
43///     }
44/// }
45///
46/// match decide_caching(200, "OK".to_string()) {
47///     CachePolicy::Cacheable(data) => println!("Cache: {}", data),
48///     CachePolicy::NonCacheable(data) => println!("Pass through: {}", data),
49/// }
50/// ```
51#[derive(Debug)]
52pub enum CachePolicy<C, N> {
53    /// Entity should be cached.
54    Cacheable(C),
55    /// Entity should not be cached; pass through directly.
56    NonCacheable(N),
57}
58
59/// Configuration for entity caching TTLs.
60///
61/// Specifies how long cached entries should live and when they become stale.
62/// Used by [`CacheableResponse::cache_policy`](crate::response::CacheableResponse::cache_policy)
63/// to set timestamps on cached values.
64///
65/// # Fields
66///
67/// * `ttl` - Time until the entry expires (becomes invalid)
68/// * `stale_ttl` - Time until the entry becomes stale (should refresh in background)
69///
70/// # Example
71///
72/// ```
73/// use hitbox_core::EntityPolicyConfig;
74/// use std::time::Duration;
75///
76/// // Expire after 1 hour, become stale after 5 minutes
77/// let config = EntityPolicyConfig {
78///     ttl: Some(Duration::from_secs(3600)),
79///     stale_ttl: Some(Duration::from_secs(300)),
80/// };
81///
82/// // No expiration (cached forever until manually invalidated)
83/// let forever = EntityPolicyConfig::default();
84/// ```
85#[derive(Default)]
86pub struct EntityPolicyConfig {
87    /// Time until cached entries expire and become invalid.
88    pub ttl: Option<Duration>,
89    /// Time until cached entries become stale (for background refresh).
90    pub stale_ttl: Option<Duration>,
91}
hitbox_core/policy.rs

hitbox_core/
policy.rs
