Enum CachePolicy 

pub enum CachePolicy {
    NoCache,
    Ttl {
        ttl_ms: u64,
    },
    StaleWhileRevalidate {
        ttl_ms: u64,
        stale_ms: u64,
    },
}

Available on crate feature core only.

How cached data is treated when a query is accessed.

• NoCache: Always fetch fresh data.
• Ttl: Use cached data if fresh (within TTL).
• StaleWhileRevalidate: Return stale data immediately while fetching fresh data in the background.

Variants

NoCache

Never cache — always fetch fresh data.

Ttl

Cache with a time-to-live. Data is considered fresh within the TTL.

Note: ttl_ms should be greater than zero. A ttl_ms of 0 is equivalent to NoCache for all practical purposes — data is only “fresh” at the exact instant it is stored, so every begin_request call triggers a new fetch. This is not validated at runtime in release builds, but a debug_assert will fire in debug builds if ttl_ms is zero.

Fields

ttl_ms: u64

StaleWhileRevalidate

Return stale data immediately while revalidating in the background.

Data within ttl_ms is served as a fresh cache hit (no refetch). Data between ttl_ms and ttl_ms + stale_ms is served as stale data and a background revalidation is triggered. After ttl_ms + stale_ms, data is considered expired and a normal fetch is performed (no stale data served).

Note: stale_ms should be greater than zero. Setting stale_ms to 0 effectively disables the stale-while-revalidate feature, degenerating to pure TTL behavior (the stale window is an empty set). Both ttl_ms and stale_ms should be greater than zero. This is not validated at runtime in release builds, but debug_asserts will fire in debug builds if either value is zero.

Fields

ttl_ms: u64

stale_ms: u64

Implementations

impl CachePolicy

pub fn label(self) -> String

Human-readable label.

Sub-second values are shown with millisecond precision (e.g. “500ms”) rather than truncating to “0s” via integer division.

Thin wrapper around the Display impl that allocates a String. Prefer format!("{policy}") or writing directly to a formatter to avoid the heap allocation for log/diagnostic callers.

pub fn can_short_circuit(self) -> bool

Whether this policy can short-circuit (return cached data without fetching).

Returns true for Ttl and StaleWhileRevalidate since both can serve cached data when it is fresh (within the TTL window). The actual freshness check is done separately in is_fresh.

pub fn can_serve_stale(self) -> bool

Whether this policy allows serving stale data while revalidating.

pub fn ttl_ms(self) -> Option<u64>

The TTL in milliseconds, if applicable.

pub fn stale_ms(self) -> Option<u64>

The stale-while-revalidate window in milliseconds beyond TTL.

Returns None for policies that are not StaleWhileRevalidate.

pub fn total_valid_ms(self) -> Option<u64>

Total valid window (TTL + stale) in milliseconds.

This is the maximum age at which data can still be served under this policy. For Ttl, this equals ttl_ms. For StaleWhileRevalidate, it equals ttl_ms + stale_ms. Returns None for NoCache.

On overflow (extremely large ttl_ms + stale_ms), saturates to u64::MAX, effectively treating the data as indefinitely valid.

pub fn is_fresh(self, age_ms: u64) -> bool

Whether the data is fresh (within the TTL window).

Returns false if the policy has no TTL or the data age exceeds TTL.

pub fn is_stale_but_serveable(self, age_ms: u64) -> bool

Whether the data is stale but still within the stale-while-revalidate window.

Data is “stale-but-serveable” when:

• The policy is StaleWhileRevalidate
• Data age is past TTL but within ttl_ms + stale_ms

pub fn is_expired(self, age_ms: u64) -> bool

Whether the data is expired (past the total valid window).

Returns true if the data age exceeds the total valid window for this policy.

Trait Implementations

impl Clone for CachePolicy

fn clone(&self) -> CachePolicy

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for CachePolicy

impl Debug for CachePolicy

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for CachePolicy

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for CachePolicy

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for CachePolicy

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Reproduces the exact strings produced by CachePolicy::label.

The duration formatting is inlined here (mirroring [format_duration]) so that no intermediate String is allocated when writing to a formatter — the whole point of the Display impl.

impl Eq for CachePolicy

impl PartialEq for CachePolicy

fn eq(&self, other: &CachePolicy) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for CachePolicy

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for CachePolicy