trillium_cache/lib.rs
1//! HTTP cache for trillium implementing [RFC 9111] semantics, in two handler forms that
2//! share one caching engine.
3//!
4//! The primary form is a [`trillium-client`](https://docs.rs/trillium-client) handler,
5//! provided by the `client` module behind the `client` feature. Mount it on the client a
6//! [`trillium-proxy`](https://docs.rs/trillium-proxy) uses to reach its upstream, mark it
7//! shared, and the proxy becomes a CDN-style shared cache in front of that origin. On any
8//! other `trillium-client` it serves as a user-agent cache.
9//!
10//! The server form, [`Cache`], sits before a trillium handler and caches that handler's own
11//! responses.
12//!
13//! See the `client` module to get started, or [`Cache::new`] for the server form.
14//!
15//! ## Features
16//!
17//! - `client` — the `trillium-client` handler form (the `client` module), for caching at the
18//! user-agent layer and as a proxy's shared upstream cache.
19//!
20//! ## 0.1 status
21//!
22//! The server cache implements the bulk of RFC 9111: storability, freshness, conditional
23//! revalidation, `Vary`, unsafe-method invalidation, plus `stale-if-error` recovery from
24//! [RFC 5861]. The `stale-while-revalidate` directive is parsed but treated as synchronous
25//! revalidation in this release. The client handler supports the full set including
26//! background `stale-while-revalidate`.
27//!
28//! [RFC 9111]: https://www.rfc-editor.org/rfc/rfc9111
29//! [RFC 5861]: https://www.rfc-editor.org/rfc/rfc5861
30#![forbid(unsafe_code)]
31#![deny(
32 clippy::dbg_macro,
33 missing_copy_implementations,
34 rustdoc::missing_crate_level_docs,
35 missing_debug_implementations,
36 missing_docs,
37 nonstandard_style,
38 unused_qualifications
39)]
40
41#[cfg(doctest)]
42#[doc = include_str!("../README.md")]
43mod readme {}
44
45mod freshness;
46mod memory;
47mod policy;
48mod server;
49mod storability;
50mod storage;
51mod tee;
52mod tiered;
53mod validation;
54
55#[cfg(feature = "fs")]
56mod fs;
57#[cfg(feature = "fs")]
58mod fs_shims;
59
60#[cfg(feature = "client")]
61pub mod client;
62
63#[cfg(test)]
64mod test_helpers;
65
66#[cfg(feature = "fs")]
67pub use fs::{FileSystemStorage, FsPutHandle, FsStoredEntry};
68pub use memory::{InMemoryEntry, InMemoryPutHandle, InMemoryStorage};
69pub use policy::{CacheOptions, CachePolicy};
70pub use server::Cache;
71pub use storage::{CacheKey, CacheStorage, PutHandle, StoredEntry};
72pub use tiered::{TieredEntry, TieredPutHandle, TieredStorage};