bookclerk_cover::http_cache

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

HTTP caching for the images the daemon serves and the ones it fetches.

Serving. Every image the cover service answers with carries a strong EntityTag derived from its bytes, so a browser that already holds a copy can ask again with If-None-Match and get a 304 Not Modified instead of the body. if_none_match reads that request header.

Fetching. When the covers plugin fetches an image, it passes the upstream server's caching headers back to the host. upstream_policy reads them into an [UpstreamPolicy]: whether the image may be stored and for how long it stays fresh, clamped between FRESHNESS_FLOOR and FRESHNESS_CEILING, plus the Validators to send on the next fetch so an unchanged image costs a 304.

Both kinds of header come from outside (any client, any image host), so they are untrusted input: the readers work on byte slices with no I/O, never allocate in proportion to the input, and treat anything they cannot read as absent, which only ever costs a full answer or an earlier refresh. The cache_headers fuzz target drives them against an independent oracle.

Item Kind Summary
EntityTag struct A strong entity tag naming one exact image body.
UpstreamHeaders struct The caching headers of one upstream image response, as raw bytes; None for a header the response did not carry.
Validators struct Validators to send when fetching the image again, so an unchanged image costs a 304 Not Modified.
UpstreamPolicy struct What the host does with one fetched image, read from upstream's headers.
Storage enum Whether a fetched image may be kept, and for how long it is fresh.
if_none_match function Whether an If-None-Match header matches tag, so the answer may be 304 Not Modified.
upstream_policy function Reads upstream's caching headers into the host's policy for one image.
MAX_IF_NONE_MATCH_BYTES constant Longest If-None-Match header read, in bytes. A browser sends one tag; a longer header is treated as no match rather than scanned.
FRESHNESS_FLOOR constant Shortest time a fetched image stays fresh, whatever upstream says: an image host asking for no-cache or max-age=0 is asked again after an hour, not on every view.
FRESHNESS_DEFAULT constant How long a fetched image stays fresh when upstream sends no max-age, s-maxage or Expires.
FRESHNESS_CEILING constant Longest time a fetched image stays fresh, whatever upstream says, so a changed profile picture or logo shows within a week.
MAX_RESPONSE_HEADER_BYTES constant Longest upstream header value read, in bytes (the plugin ABI's maxCoverHeaderBytes); a longer value is treated as absent.

Structs

EntityTag

pub struct EntityTag {
    /* private fields */
}

A strong entity tag naming one exact image body.

The opaque part is the first 32 lowercase hex digits of the body's SHA-256, so equal bodies always get equal tags and the tag never needs storing beside the image.

EntityTag::of

pub fn of(body: &[u8]) -> Self

The tag for body.

Arguments
  • body - The exact bytes the response carries.

EntityTag::opaque

pub fn opaque(&self) -> &str

The opaque part, without quotes.

EntityTag::header_value

pub fn header_value(&self) -> String

The ETag header value: the opaque part in double quotes.

Implements: Clone, Debug, Eq, Hash, PartialEq

UpstreamHeaders

pub struct UpstreamHeaders<'a> {
    pub cache_control: Option<&'a [u8]>,
    pub expires: Option<&'a [u8]>,
    pub date: Option<&'a [u8]>,
    pub age: Option<&'a [u8]>,
    pub etag: Option<&'a [u8]>,
    pub last_modified: Option<&'a [u8]>,
}

The caching headers of one upstream image response, as raw bytes; None for a header the response did not carry.

Fields

  • cache_control: Cache-Control.
  • expires: Expires.
  • date: Date.
  • age: Age.
  • etag: ETag.
  • last_modified: Last-Modified.

Implements: Clone, Copy, Debug, Default, Eq, PartialEq

Validators

pub struct Validators {
    /* private fields */
}

Validators to send when fetching the image again, so an unchanged image costs a 304 Not Modified.

Validators::new

pub fn new(etag: Option<&str>, last_modified: Option<SystemTime>) -> Self

Validators from stored values, as a cache index kept them.

Arguments
  • etag - A stored entity tag; dropped unless it is one well-formed tag no longer than MAX_RESPONSE_HEADER_BYTES.
  • last_modified - A stored modification time.

Validators::if_none_match

pub fn if_none_match(&self) -> Option<&str>

The If-None-Match value to send, when upstream sent an ETag.

Validators::last_modified

pub fn last_modified(&self) -> Option<SystemTime>

When upstream says the image last changed.

Validators::if_modified_since

pub fn if_modified_since(&self) -> Option<String>

The If-Modified-Since value to send, when upstream sent a Last-Modified.

Validators::is_empty

pub fn is_empty(&self) -> bool

Whether there is anything to revalidate with.

Implements: Clone, Debug, Default, Eq, PartialEq

UpstreamPolicy

pub struct UpstreamPolicy {
    pub storage: Storage,
    pub validators: Validators,
}

What the host does with one fetched image, read from upstream's headers.

Fields

  • storage: Whether to keep it and for how long it is fresh.
  • validators: What to revalidate it with.

Implements: Clone, Debug, Eq, PartialEq

Enums

Storage

pub enum Storage {
    DoNotStore,
    Store { fresh_for: Duration },
}

Whether a fetched image may be kept, and for how long it is fresh.

Variants

  • DoNotStore: Upstream sent no-store: serve this answer, keep nothing.
  • Store: Keep the image; it is fresh for this long from when it was received, always between FRESHNESS_FLOOR and FRESHNESS_CEILING.
    • fresh_for: Freshness lifetime left at receipt.

Implements: Clone, Copy, Debug, Eq, PartialEq

Functions

if_none_match

pub fn if_none_match(header: &[u8], tag: &EntityTag) -> bool

Whether an If-None-Match header matches tag, so the answer may be 304 Not Modified.

Follows RFC 9110 section 13.1.2: the header is * or a comma-separated list of entity tags, each "opaque" or weak W/"opaque", compared with the weak comparison function (the W/ prefix is ignored). Optional whitespace may surround each element and empty elements are skipped. A header that does not follow this grammar, or is longer than MAX_IF_NONE_MATCH_BYTES, matches nothing.

Arguments

  • header - The raw header value; several header lines joined with , read the same as one.
  • tag - The current tag of the representation.

Returns

true when the client's copy is current.

upstream_policy

pub fn upstream_policy(
    headers: &UpstreamHeaders<'_>,
    received: SystemTime,
) -> UpstreamPolicy

Reads upstream's caching headers into the host's policy for one image.

Follows RFC 9111 for a shared cache, with Bookclerk's limits:

  • no-store means Storage::DoNotStore. private is ignored: the host keeps images for its own users, and a picture marked private is still the one the user asked for.
  • The lifetime is the first s-maxage, else the first max-age, else Expires minus Date (or minus received when Date is absent or unreadable; an unreadable Expires means already stale), else FRESHNESS_DEFAULT. no-cache means a lifetime of zero.
  • An explicit lifetime loses the response's age: the larger of Age and received minus Date.
  • The result is clamped to FRESHNESS_FLOOR ..= FRESHNESS_CEILING.

A header longer than MAX_RESPONSE_HEADER_BYTES is read as absent.

Arguments

  • headers - Upstream's caching headers.
  • received - When the host received the response.

Returns

The storage decision and the validators.

Constants

MAX_IF_NONE_MATCH_BYTES

pub const MAX_IF_NONE_MATCH_BYTES: usize = _;

Longest If-None-Match header read, in bytes. A browser sends one tag; a longer header is treated as no match rather than scanned.

FRESHNESS_FLOOR

pub const FRESHNESS_FLOOR: Duration = _;

Shortest time a fetched image stays fresh, whatever upstream says: an image host asking for no-cache or max-age=0 is asked again after an hour, not on every view.

FRESHNESS_DEFAULT

pub const FRESHNESS_DEFAULT: Duration = _;

How long a fetched image stays fresh when upstream sends no max-age, s-maxage or Expires.

FRESHNESS_CEILING

pub const FRESHNESS_CEILING: Duration = _;

Longest time a fetched image stays fresh, whatever upstream says, so a changed profile picture or logo shows within a week.

MAX_RESPONSE_HEADER_BYTES

pub const MAX_RESPONSE_HEADER_BYTES: usize = 1024;

Longest upstream header value read, in bytes (the plugin ABI's maxCoverHeaderBytes); a longer value is treated as absent.

Generated from crates/bookclerk-cover at main · View as Markdown