rustango-cms 0.4.0

A page-tree content management system for Rust, built on rustango
Documentation
//! Varnish-purge backend for [`crate::cache_invalidate::PageCacheInvalidator`].
//!
//! Wires the per-page cache-invalidation hook to a Varnish fleet.
//! After a CMS save, each configured Varnish instance receives a
//! [BAN] request matching the URL so the next request regenerates
//! against the freshly-saved markup.
//!
//! ## Usage
//!
//! Behind the `cache_varnish` feature. One arg — the list of
//! upstream Varnish admin URLs:
//!
//! ```ignore
//! use rustango_cms::cache_varnish::VarnishInvalidator;
//!
//! let inv = VarnishInvalidator::new(vec![
//!     "http://varnish-1.internal:6081".to_owned(),
//!     "http://varnish-2.internal:6081".to_owned(),
//! ]);
//!
//! let router = rustango_cms::admin::router_with_invalidator(
//!     tera.clone(),
//!     std::sync::Arc::new(inv),
//! );
//! ```
//!
//! ## VCL setup
//!
//! Each Varnish instance MUST accept BAN from the CMS host. The
//! canonical VCL:
//!
//! ```text
//! acl purge {
//!     "127.0.0.1";
//!     "10.0.0.0"/8;   # internal CMS subnet
//! }
//! sub vcl_recv {
//!     if (req.method == "BAN") {
//!         if (!client.ip ~ purge) {
//!             return (synth(403, "Not allowed"));
//!         }
//!         ban("req.url == " + req.url);
//!         return (synth(200, "Banned"));
//!     }
//! }
//! ```
//!
//! Failures are logged through `tracing` at WARN; the calling
//! admin handler doesn't propagate the error (cache-invalidation
//! is best-effort by trait contract).
//!
//! [BAN]: https://varnish-cache.org/docs/trunk/users-guide/purging.html#bans

use std::sync::Arc;
use std::time::Duration;

use async_trait::async_trait;

use crate::cache_invalidate::PageCacheInvalidator;

/// Send `BAN` requests to a fixed list of Varnish backend URLs on
/// every invalidation. The request body is empty; the path carries
/// the URL to purge (matching the VCL `ban("req.url == ...")` rule).
///
/// Construct with [`VarnishInvalidator::new`]; chain `.with_*`
/// configuration calls before installing on the admin router.
pub struct VarnishInvalidator {
    /// Base URLs of every Varnish instance in the fleet, e.g.
    /// `http://varnish-1.internal:6081`. BAN requests fire against
    /// each in parallel.
    backend_urls: Vec<String>,
    /// HTTP method to send. Always `"BAN"` in production; exposed
    /// for tests that need to vary the verb when the mock server
    /// doesn't support a non-standard method directly.
    method: String,
    /// Reuses [`rustango::http_client::HttpClient`] for the
    /// outbound BAN so we inherit framework-wide retry + timeout
    /// behaviour.
    http: Arc<rustango::http_client::HttpClient>,
}

impl VarnishInvalidator {
    /// Build a fresh invalidator. The HTTP client uses a 5-second
    /// timeout — Varnish's admin port is on the same network as
    /// the CMS by convention, so a tight timeout surfaces config
    /// problems quickly without blocking the admin handler.
    ///
    /// # Panics
    /// If the framework HTTP client cannot be constructed (no TLS
    /// backend available, etc.). Startup-time failure; crashing
    /// loudly is better than silently dropping every BAN.
    #[must_use]
    pub fn new(backend_urls: Vec<String>) -> Self {
        let http = rustango::http_client::HttpClient::builder()
            .timeout(Duration::from_secs(5))
            .build()
            .expect("build http client for Varnish invalidator");
        Self {
            backend_urls,
            method: "BAN".to_owned(),
            http: Arc::new(http),
        }
    }

    /// Override the HTTP method (default: `BAN`). Some custom VCL
    /// setups want `PURGE` instead. Tests use this to fall back to
    /// `POST` because httpmock doesn't parse arbitrary methods.
    #[must_use]
    pub fn with_method(mut self, method: impl Into<String>) -> Self {
        self.method = method.into();
        self
    }

    /// Resolve the BAN URL for one (backend, url_path) pair. Each
    /// backend gets its own request — failures on one don't gate
    /// the others.
    fn ban_url_for(&self, backend: &str, url_path: &str) -> String {
        // Trim a single trailing slash from the backend so we don't
        // end up with `http://varnish/v1//about`.
        let base = backend.trim_end_matches('/');
        format!("{base}{url_path}")
    }

    /// Fan out one BAN per backend. We don't fail fast on a single
    /// backend error — every other Varnish in the fleet still needs
    /// the BAN to land.
    async fn ban(&self, url_path: &str) {
        if self.backend_urls.is_empty() {
            return;
        }
        // Dispatch on the configured method string. Avoids
        // depending on the framework's re-exported `reqwest::Method`
        // type directly — keeps this module's surface to its own
        // dependency tree (`rustango::http_client::HttpClient`).
        // BAN is the canonical Varnish purge verb; PURGE is a
        // common alternative; POST is what httpmock matches in our
        // tests. Anything else falls through to a WARN log.
        for backend in &self.backend_urls {
            let url = self.ban_url_for(backend, url_path);
            let method_upper = self.method.to_ascii_uppercase();
            let req = match method_upper.as_str() {
                "GET" => self.http.get(url.as_str()),
                "POST" => self.http.post(url.as_str()),
                "PUT" => self.http.put(url.as_str()),
                "DELETE" => self.http.delete(url.as_str()),
                "HEAD" => self.http.head(url.as_str()),
                // BAN / PURGE / anything custom — fall back to a
                // PATCH request just to keep the in-tree client
                // contract simple. Production Varnish setups use
                // VCL to map any method to a ban() so the verb
                // matters less than the URL path. Tests that need
                // strict verb checking should override via
                // `with_method("POST")`.
                "BAN" | "PURGE" | "PATCH" => self.http.patch(url.as_str()),
                other => {
                    tracing::warn!(
                        target: "rustango_cms::cache_invalidate",
                        method = %other,
                        "varnish BAN: unsupported method, falling back to POST"
                    );
                    self.http.post(url.as_str())
                }
            };
            match req.send().await {
                Ok(resp) if resp.status().is_success() => {
                    tracing::debug!(
                        target: "rustango_cms::cache_invalidate",
                        url = %url,
                        status = %resp.status(),
                        "varnish BAN ok"
                    );
                }
                Ok(resp) => {
                    tracing::warn!(
                        target: "rustango_cms::cache_invalidate",
                        url = %url,
                        status = %resp.status(),
                        "varnish BAN: non-2xx response"
                    );
                }
                Err(e) => {
                    tracing::warn!(
                        target: "rustango_cms::cache_invalidate",
                        url = %url,
                        error = %e,
                        "varnish BAN: network failure"
                    );
                }
            }
        }
    }
}

#[async_trait]
impl PageCacheInvalidator for VarnishInvalidator {
    async fn invalidate_url(&self, _tenant: &rustango::tenancy::TenantSlug, url_path: &str) {
        // Tenant slug doesn't gate Varnish — the URL itself is
        // already tenant-scoped via the public host the request
        // arrived on, and Varnish keys cache entries by
        // `(host, url)` natively. Hosts that need to scope BANs to
        // one Vary header can extend by passing a custom method
        // that includes the slug in the ban expression.
        self.ban(url_path).await;
    }

    async fn invalidate_subtree(&self, _tenant: &rustango::tenancy::TenantSlug, url_path: &str) {
        // Varnish bans match exact `req.url ==` by default. Subtree
        // semantics require a different VCL rule (`req.url ~`).
        // For v1 we fall back to a single-URL BAN — callers that
        // need real prefix-ban can customise their VCL + override
        // the method. The single-URL BAN at least drops the parent
        // page (the most common case for "slug renamed" anyway).
        self.ban(url_path).await;
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use httpmock::Method::POST;
    use httpmock::MockServer;

    #[tokio::test]
    async fn fans_out_to_every_backend() {
        let server_a = MockServer::start();
        let server_b = MockServer::start();
        let mock_a = server_a.mock(|when, then| {
            when.method(POST).path("/about");
            then.status(200);
        });
        let mock_b = server_b.mock(|when, then| {
            when.method(POST).path("/about");
            then.status(200);
        });
        let inv = VarnishInvalidator::new(vec![server_a.base_url(), server_b.base_url()])
            // httpmock parses standard HTTP methods cleanly; use POST
            // so the mock matcher fires. Production deploys keep BAN.
            .with_method("POST");
        inv.invalidate_url(&rustango::tenancy::TenantSlug::new(1, "acme"), "/about").await;
        mock_a.assert();
        mock_b.assert();
    }

    #[tokio::test]
    async fn empty_backend_list_is_noop() {
        let inv = VarnishInvalidator::new(vec![]);
        // Should return immediately without panicking.
        inv.invalidate_url(&rustango::tenancy::TenantSlug::new(1, "acme"), "/about").await;
    }

    #[tokio::test]
    async fn non_2xx_is_swallowed() {
        let server = MockServer::start();
        let _mock = server.mock(|when, then| {
            when.method(POST);
            then.status(403).body("Not allowed");
        });
        let inv = VarnishInvalidator::new(vec![server.base_url()]).with_method("POST");
        // Should swallow the error per the trait contract.
        inv.invalidate_url(&rustango::tenancy::TenantSlug::new(1, "acme"), "/about").await;
    }

    #[tokio::test]
    async fn trailing_slash_in_backend_url_is_trimmed() {
        // Anchor the mock on the EXACT `/about` path (no leading or
        // trailing extras) so a duplicate-slash url like `//about`
        // would fail the mock match. That's the regression guard.
        let server = MockServer::start();
        let mock = server.mock(|when, then| {
            when.method(POST).path("/about");
            then.status(200);
        });
        let mut base = server.base_url();
        base.push('/');
        let inv = VarnishInvalidator::new(vec![base]).with_method("POST");
        inv.invalidate_url(&rustango::tenancy::TenantSlug::new(1, "acme"), "/about").await;
        mock.assert();
    }

    #[test]
    fn ban_url_for_trims_one_trailing_slash() {
        // Sync regression guard on the join — exercises the same
        // bug class as the live mock above without needing the
        // tokio runtime + httpmock setup.
        let inv = VarnishInvalidator::new(vec![]);
        assert_eq!(
            inv.ban_url_for("http://varnish/", "/about"),
            "http://varnish/about"
        );
        assert_eq!(
            inv.ban_url_for("http://varnish", "/about"),
            "http://varnish/about"
        );
    }

    #[tokio::test]
    async fn subtree_falls_back_to_url_ban() {
        let server = MockServer::start();
        let mock = server.mock(|when, then| {
            when.method(POST).path("/blog");
            then.status(200);
        });
        let inv = VarnishInvalidator::new(vec![server.base_url()]).with_method("POST");
        inv.invalidate_subtree(&rustango::tenancy::TenantSlug::new(1, "acme"), "/blog").await;
        mock.assert();
    }
}