Module value 

Cached value types with expiration metadata.

This module provides types for wrapping cached data with expiration and staleness timestamps:

• CacheValue - Cached data with optional expire and stale timestamps
• CacheMeta - Just the metadata without the data

Expiration vs Staleness

Cache entries have two time-based states:

• Stale - The data is still usable but should be refreshed in the background
• Expired - The data is no longer valid and must be refreshed before use

This allows implementing “stale-while-revalidate” caching patterns where stale data is served immediately while fresh data is fetched asynchronously.

Cache States

The CacheValue::cache_state method evaluates timestamps and returns:

• CacheState::Actual - Data is fresh (neither stale nor expired)
• CacheState::Stale - Data is stale but not expired
• CacheState::Expired - Data has expired

use hitbox_core::value::CacheValue;
use chrono::Utc;

let value = CacheValue::new(
    "cached data",
    Some(Utc::now() + chrono::Duration::hours(1)),  // expires in 1 hour
    Some(Utc::now() + chrono::Duration::minutes(5)), // stale in 5 minutes
);

match value.cache_state() {
    CacheState::Actual(v) => println!("Fresh: {:?}", v.data()),
    CacheState::Stale(v) => println!("Stale, refresh in background"),
    CacheState::Expired(v) => println!("Expired, must refresh"),
}

Structs

CacheMeta

Cache expiration metadata without the data.

CacheValue

A cached value with expiration metadata.