🗃 trillium-cache — HTTP cache handler

An RFC 9111 HTTP cache for trillium, in two handler forms that share one caching engine.

The primary form is a trillium-client handler (the client feature). Add it to your client to cache at the user-agent layer; mark it .shared() for shared-cache (proxy/CDN) semantics. The server form caches a trillium handler's own responses.

Example

The client handler, with shared-cache semantics:

use trillium_cache::{client::Cache, InMemoryStorage};
use trillium_client::Client;
use trillium_smol::ClientConfig;

let client = Client::from(ClientConfig::new())
    .with_handler(Cache::new(InMemoryStorage::new()).shared());

Hand that client to trillium-proxy as its upstream client and the proxy becomes a shared, CDN-style cache in front of the origin:

let proxy = Proxy::new(client, "http://origin.example")
    .with_via_pseudonym("trillium-proxy");

The server form caches a trillium handler's own responses — place Cache before the handler whose responses you want cached:

use trillium::Conn;
use trillium_cache::{Cache, InMemoryStorage};

let app = (
    Cache::new(InMemoryStorage::new()),
    |conn: Conn| async move { conn.ok("hello") },
);

// run with your chosen runtime adapter, e.g.:
// trillium_smol::run(app);

Status

0.1. RFC 9111 coverage: storability, freshness, conditional revalidation, Vary, unsafe-method invalidation, plus stale-if-error recovery from RFC 5861. The client handler performs background stale-while-revalidate; the server handler does not — on the server, stale entries within their SWR window fall through to synchronous revalidation.

Safety

This crate uses #![forbid(unsafe_code)].

License