Struct CacheControl

Source

pub struct CacheControl { /* private fields */ }

Expand description

A Cache-Control response header, built from one of four policies.

Add it to a response tuple: (CacheControl::public(Duration::from_secs(300)), Html(page)). It implements [IntoResponseParts] and Display (the header value). Durations are truncated to whole seconds. Free: no KV or D1 operation.

Constructor	Header	Use for
`no_store`	`no-store`	secrets, one-time tokens
`no_cache`	`private, no-cache`	per-visitor pages, with an `ETag`
`private`	`private, max-age=N`	per-visitor data that may be stale for N seconds
`public`	`public, max-age=N`	responses identical for every visitor

§Examples

use std::time::Duration;
use ocre::cache::CacheControl;

assert_eq!(CacheControl::no_cache().to_string(), "private, no-cache");
assert_eq!(
    CacheControl::public(Duration::from_secs(300)).stale_while_revalidate(Duration::from_secs(60)).to_string(),
    "public, max-age=300, stale-while-revalidate=60"
);

// As a response part:
use axum::response::IntoResponse;
let response = (CacheControl::public(Duration::from_secs(300)), "hello").into_response();
assert_eq!(response.headers()["cache-control"], "public, max-age=300");

Implementations§

Source §

impl CacheControl

Source

pub fn no_store() -> Self

A no-store policy: never keep a copy (pages with secrets, one-time tokens).

§Examples

assert_eq!(ocre::cache::CacheControl::no_store().to_string(), "no-store");

Source

pub fn no_cache() -> Self

A private, no-cache policy: the browser keeps a copy but asks every time.

With an ETag and Conditional the answer is usually a cheap 304. The right default for pages that depend on the visitor (session, locale, flash).

§Examples

assert_eq!(ocre::cache::CacheControl::no_cache().to_string(), "private, no-cache");

Source

pub fn private(max_age: Duration) -> Self

A private, max-age=N policy: the browser reuses its copy for max_age without asking.

Shared caches (Cloudflare) never store it. max_age is truncated to whole seconds.

§Examples

use std::time::Duration;
assert_eq!(ocre::cache::CacheControl::private(Duration::from_secs(60)).to_string(), "private, max-age=60");

Source

pub fn public(max_age: Duration) -> Self

A public, max-age=N policy: browsers and Cloudflare may reuse it for every visitor.

Only for responses identical for everyone: no session data, no locale unless it is in the path. With Workers Cache enabled (cache: { enabled: true } in worker of cloudflare.config.ts) such responses are served without running the Worker (no CPU, but each hit still counts toward the free plan’s 100,000 requests a day). max_age is truncated to whole seconds.

§Examples

use std::time::Duration;
assert_eq!(ocre::cache::CacheControl::public(Duration::from_secs(3600)).to_string(), "public, max-age=3600");

Source

pub fn stale_while_revalidate(self, window: Duration) -> Self

Adds stale-while-revalidate, serving the old copy for up to window while fetching a new one.

Applies after max-age runs out. Ignored by no_store and no_cache, which have no max-age.

§Examples

use std::time::Duration;
use ocre::cache::CacheControl;

let policy = CacheControl::private(Duration::from_secs(60)).stale_while_revalidate(Duration::from_secs(600));
assert_eq!(policy.to_string(), "private, max-age=60, stale-while-revalidate=600");
assert_eq!(CacheControl::no_store().stale_while_revalidate(Duration::from_secs(600)).to_string(), "no-store");