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 validation;
53
54#[cfg(feature = "client")]
55pub mod client;
56
57#[cfg(test)]
58mod test_helpers;
59
60pub use memory::{InMemoryEntry, InMemoryPutHandle, InMemoryStorage};
61pub use policy::{CacheOptions, CachePolicy};
62pub use server::Cache;
63pub use storage::{CacheKey, CacheStorage, PutHandle, StoredEntry};