Experimental: Alpha Release

This crate is in early development. APIs are unstable and may change without notice. Not recommended for production use yet.

http_cache_tags_axum

🔒 HTTP caching middleware and tooling for Axum applications with reverse proxies like NGINX or CDNs.

Designed for SSR sites (e.g. Leptos) backed by a headless CMS — enables route-based cache metadata headers and fine-grained invalidation.

Features

Route pattern → cache key mapping (glob support)
Auto-set Last-Modified headers
Optional admin route for external invalidation
Thread-safe runtime store with DashMap
Middleware + Extractor support
TOML config + programmatic builder

Getting Started

1. Install

# Cargo.toml
[dependencies]
http_cache_tags_axum = { git = "<not available now>" }

2. Configure

cache.toml:

mode = "LastModified"

[auth]
secret = "your-shared-secret"

[admin]
path = "/_invalidate"

[routes]
"/blog/*" = ["posts"]
"/products/*" = ["products", "categories"]

Or build in code:

let config = CacheConfig::builder()
    .add_route("/blog/*", vec!["posts"])
    .admin_path(Some("/_invalidate".to_string()))
    .build();

// or from file
let config = CacheConfig::load_from_file("../path/to/cache.toml")?;

3. Mount Middleware

use axum::{Router, Extension};
use axum_cache_meta::{CacheRuntime, config::CacheConfig};

let config = CacheConfig::from_file("cache.toml")?;
let runtime = CacheRuntime::builder::config(config).build();

let app = runtime.attach_to(
    // your axum app
    Router::new()
        .route("/", get(handler)
    )
);

CacheMeta Extractor

Access resolved keys and last-modified time from inside handlers:

async fn handler(CacheMeta { keys, last_modified }: CacheMeta) -> impl IntoResponse {
    println!("Keys: {keys:?}, Modified: {last_modified:?}");
    Json("OK")
}

Admin Invalidation API

If enabled in config:

POST /_invalidate
Authorization: Bearer your-shared-secret
Content-Type: application/json

{
  "tags": ["posts", "categories"]
}

Clears the internal "dirty" flags and updates timestamps, triggering new Last-Modified values on next request.

Integration with NGINX / CDN

Add header caching rules in your reverse proxy:

location / {
    proxy_pass http://backend;
    proxy_set_header Host $host;
    proxy_cache my_cache;
    proxy_cache_valid 200 1h;
    proxy_cache_key $uri;
    add_header Last-Modified $upstream_http_last_modified;
    ...
}

Your app only needs to send the right Last-Modified headers — the reverse proxy handles freshness.

Feature Flags

TODO

TODO / Contributions Welcome

Redis adapter for shared cache
CLI tool for manual invalidation

License

MIT

http_cache_tags_axum 0.1.0-alpha.0