Struct RouteCache 

pub struct RouteCache<C> { /* private fields */ }

Middleware that caches successful GET and HEAD responses.

Caching is opt-in. There are two ways to opt a route in:

• Per response. Put the layer on the whole app; it stores only responses marked Cache-Control: public (for example with Cached::public). Everything else passes through.
• Per route. Put the layer on one route with MethodRouter::layer and set default_ttl; that route’s responses are stored without a public marker.

use siderite_cache::{MemoryCache, RouteCache};
use siderite_core::{App, Cached, get};
use std::time::Duration;

let cache = MemoryCache::new(1024);
let _app = App::new()
    // Opted in by its response.
    .route("/news", get(|| async {
        Cached::public(Duration::from_secs(60), "news")
    }))
    // Opted in by placement.
    .route("/stats", get(|| async { "stats" }).layer(
        RouteCache::new(cache.clone())
            .default_ttl(Duration::from_secs(30)),
    ))
    // Never stored: no `public` marker.
    .route("/me", get(|| async { "private" }))
    .layer(RouteCache::new(cache));

Do not set default_ttl on an app-wide layer unless every GET route in the app is safe to share between users.

Behaviour

• Only GET and HEAD responses are stored. Successful unsafe target writes rotate a shared generation across every representation. Related URI dependencies require explicit application invalidation.
• The cache key is the method, scheme, Host, path and query (as received), plus the request’s Accept and Accept-Encoding values, so virtual hosts sharing one cache never see each other’s responses.
• Requests carrying credentials bypass the cache: Authorization, Proxy-Authorization, Cookie, X-API-Key, any header whose name contains auth, token, session, jwt, secret, api-key, apikey or access-key, and any header added with RouteCache::bypass_header. Such requests are neither answered from nor stored in the cache.
• Responses are stored only when the status is 200, there is no Set-Cookie, Cache-Control does not contain no-store, no-cache or private, Vary names no header outside the key, and the body length is known and at most RouteCache::max_body_bytes. Streaming bodies (server-sent events, file streams) pass through untouched.
• On top of that, a response needs Cache-Control: public unless default_ttl is set.
• The entry lives for s-maxage, else max-age, else default_ttl. A public response without any of these, or with a lifetime of zero, is not stored.
• Request no-cache refreshes; no-store bypasses without deleting older entries. Unsupported conditionals and ranges bypass. Date is retained and Age includes origin age and residence. Entries are versioned.
• Namespaces isolate layers by default. Stable namespaces intentionally share generations; key, header and encoded byte admission is bounded.
• Every GET/HEAD response is tagged with x-cache: hit or x-cache: miss.

Cache backend failures fail open: the request is served and treated as a miss. Failed write invalidation disables this layer. A database commit and distributed cache invalidation are separate operations; other nodes need an outage/restart consistency policy. No secret values are logged.

Implementations

impl<C: Cache> RouteCache<C>

pub fn new(cache: C) -> Self

Cache GET/HEAD 200 responses marked Cache-Control: public in cache.

pub fn namespace(self, namespace: impl Into<String>) -> Self

Set a stable app/deployment namespace for intentionally shared caches.

Args: namespace: Identity distinct from incompatible apps or revisions.

Returns: Configured layer; the default namespace is unique per instance.

pub fn trusted_proxies(self, proxies: TrustedProxies) -> Self

Resolve cache request scheme with the shared trusted-peer policy.

Args: proxies: Same immediate-peer policy used by other middleware.

Returns: Layer ignoring forwarded headers from untrusted peers.

pub fn byte_limits(self, key: usize, hdrs: usize, encoded: usize) -> Self

Bound keys, stored header bytes and serialized response bytes.

Args: key: Maximum key bytes, including namespace and generation. hdrs: Maximum stored header-name/value bytes. encoded: Maximum versioned serialized response size.

Returns: Layer bypassing oversized entries without failing the origin.

pub fn generation_ttl(self, ttl: Duration) -> Self

Set the lifetime of per-target generation markers.

Markers are created with this expiry (default DEFAULT_GENERATION_TTL, one hour) and stored representations never outlive it: a representation’s TTL is clamped to min(response ttl, generation_ttl). When a marker expires, the next request draws a fresh random generation, so earlier or in-flight fills become unreachable and read as safe misses.

Args: ttl: Marker lifetime. Zero means route caching is disabled: no request touches the backend, nothing is stored or invalidated, and responses carry x-cache: miss. A value above the backend’s portable limit is rejected by the backend, so every request bypasses the cache.

Note: max-age/s-maxage above ttl is capped to ttl (default one hour), as is default_ttl.

Returns: Configured layer. A custom Cache without set_if_absent_with_ttl makes the layer bypass storage.

pub fn max_new_targets(self, max: u64) -> Self

Bound the metadata one namespace can create (default DEFAULT_MAX_NEW_TARGETS).

At most max new target markers are admitted per namespace in each generation_ttl window, counted when a representation is first stored for a target, and counted exactly: a marker that would exceed the budget is never visible. Once the window’s budget is spent, further new targets bypass the cache (x-cache: miss) until the next window; targets that already have a marker keep hitting, and the layer remembers the spent window locally, so those requests cost one backend read.

Windows are floor(clock / generation_ttl). RedisCache reads the Redis server clock inside the admission script (and expires the counter on that same clock after two windows), so every process sharing a namespace uses one window whatever its own clock says; MemoryCache uses its own clock. A marker lives one generation_ttl, so live markers were created in at most two consecutive windows: at most 2 * max per namespace. A stored representation can outlive its marker’s creation window by up to another generation_ttl, so representations come from at most three windows: at most 3 * max * v per namespace, where v is the number of request variants (method, Accept, Accept-Encoding) seen per target. Fills still in the origin when their marker ages out add at most one representation each.

Zero admits nothing: GET and HEAD requests make no backend calls. Successful writes still invalidate, which is one backend call each, because other processes sharing the namespace may have markers.

The counter lives in the backend, so the bound holds across processes sharing a namespace, provided the backend does not evict the counter. Third-party Cache adapters that do not override Cache::admit_marker use the generic sequence, whose window comes from each process’s own clock: processes whose clocks differ by a large fraction of generation_ttl can then each spend a full budget, up to the number of distinct clock phases times the bound above. A Cache without increment_with_expiry or set_if_absent_with_ttl cannot enforce the budget, so the layer stops storing (one warning).

pub async fn invalidate_target(&self, req: &Request) -> Result<(), CacheError>

Invalidate every cached representation of one related target URI.

Args: req: Request identifying the target authority, scheme and URI.

Returns: Success after rotating its shared backend generation. Use this for application-specific list/detail dependencies after writes.

Errors

Invalid context, oversized key or cache backend failure. A failed invalidation disables this layer to avoid stale local reuse.

pub fn default_ttl(self, ttl: Duration) -> Self

Also store responses without Cache-Control: public, for ttl when they carry no max-age. Meant for a layer on a single route (see the type docs). A ttl of zero stores nothing.

pub fn bypass_header(self, name: HeaderName) -> Self

Bypass the cache for requests carrying name (a credential header).

pub fn max_body_bytes(self, bytes: u64) -> Self

Store only bodies of at most bytes (default DEFAULT_MAX_BODY_BYTES).

Trait Implementations

impl<C: Clone> Clone for RouteCache<C>

fn clone(&self) -> RouteCache<C>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<C: Debug> Debug for RouteCache<C>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<C: Cache> Layer<BoxCloneSyncService<Request<Body>, Response<Body>, Infallible>> for RouteCache<C>

type Service = BoxCloneSyncService<Request<Body>, Response<Body>, Infallible>

The wrapped service

fn layer(&self, inner: BoxService) -> Self::Service

Wrap the given service with the middleware, returning a new service that has been decorated with the middleware.