rustango-cms 0.4.0

A page-tree content management system for Rust, built on rustango
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
//! Cloudflare-purge backend for [`crate::cache_invalidate::PageCacheInvalidator`].
//!
//! Wires the per-page cache-invalidation hook to Cloudflare's
//! [purge_cache] API. After a CMS save, the public URL is dropped
//! from Cloudflare's edge cache so the next request regenerates
//! against the freshly-saved markup instead of waiting for the
//! cache TTL to elapse.
//!
//! ## Usage
//!
//! Behind the `cache_cloudflare` feature. Two args:
//!
//! ```ignore
//! use rustango_cms::cache_cloudflare::CloudflareInvalidator;
//!
//! let inv = CloudflareInvalidator::new(
//!     std::env::var("CLOUDFLARE_ZONE_ID").unwrap(),
//!     std::env::var("CLOUDFLARE_API_TOKEN").unwrap(),
//! )
//! .with_origin_host("acme.example.com");
//!
//! let router = rustango_cms::admin::router_with_invalidator(
//!     tera.clone(),
//!     std::sync::Arc::new(inv),
//! );
//! ```
//!
//! The token needs `Zone:Cache Purge:Edit` on the target zone —
//! [token-permissions]. Failures are logged through `tracing`
//! at WARN; the calling admin handler doesn't propagate the error
//! (cache-invalidation is best-effort by trait contract).
//!
//! [purge_cache]: https://developers.cloudflare.com/api/operations/zone-purge
//! [token-permissions]: https://developers.cloudflare.com/fundamentals/api/get-started/create-token/

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

use async_trait::async_trait;
use serde::Serialize;

use crate::cache_invalidate::PageCacheInvalidator;

/// Build absolute URLs the public router is serving by joining the
/// tenant's public host with the supplied url_path. Cloudflare's
/// purge API accepts full URLs (`https://example.com/about/`) and
/// drops the matching edge entry on every PoP. Per-tenant deploys
/// typically map one tenant to one origin host; multi-host setups
/// can register the additional hosts via
/// [`CloudflareInvalidator::with_tenant_host`].
///
/// Construct with [`CloudflareInvalidator::new`]; chain `.with_*`
/// configuration calls before installing on the admin router.
pub struct CloudflareInvalidator {
    /// Cloudflare zone id the URLs live under. Pulled from the
    /// dashboard or `cloudflare-cli zone list`.
    zone_id: String,
    /// API token with `Zone:Cache Purge:Edit` scoped to `zone_id`.
    api_token: String,
    /// Tenant-slug → list of public origin hosts. Most deploys map
    /// each tenant to one host; register additional ones here if
    /// the same content is served under multiple domains.
    tenant_hosts: HashMap<String, Vec<String>>,
    /// Default-when-no-tenant-mapping origin host. Set via
    /// [`Self::with_origin_host`]. Useful for single-tenant deploys.
    default_host: Option<String>,
    /// HTTPS / HTTP scheme to prepend to the URL. Defaults to
    /// `https` since Cloudflare-fronted origins are TLS-only in
    /// practice; expose a setter for the unusual dev case.
    scheme: String,
    /// Reuses [`rustango::http_client::HttpClient`] for the
    /// outbound POST so we inherit framework-wide retry + timeout
    /// behaviour.
    http: Arc<rustango::http_client::HttpClient>,
    /// Override of the API base URL — production points at
    /// `https://api.cloudflare.com`; the integration tests point at
    /// the httpmock server.
    api_base: String,
}

impl CloudflareInvalidator {
    /// Build a fresh invalidator. The HTTP client uses the
    /// framework's default 10-second timeout + exponential-backoff
    /// retry policy.
    ///
    /// # Panics
    /// If the framework HTTP client cannot be constructed (no TLS
    /// backend available, etc.). This is a startup-time failure;
    /// crashing loudly is better than silently dropping every purge.
    #[must_use]
    pub fn new(zone_id: impl Into<String>, api_token: impl Into<String>) -> Self {
        let http = rustango::http_client::HttpClient::builder()
            .timeout(Duration::from_secs(10))
            .build()
            .expect("build http client for Cloudflare invalidator");
        Self {
            zone_id: zone_id.into(),
            api_token: api_token.into(),
            tenant_hosts: HashMap::new(),
            default_host: None,
            scheme: "https".to_owned(),
            http: Arc::new(http),
            api_base: "https://api.cloudflare.com".to_owned(),
        }
    }

    /// Single-tenant convenience — every invalidation targets
    /// `<scheme>://<host><url_path>` regardless of tenant slug.
    /// Multi-tenant setups should use [`Self::with_tenant_host`]
    /// instead so each tenant resolves to its own public host(s).
    #[must_use]
    pub fn with_origin_host(mut self, host: impl Into<String>) -> Self {
        self.default_host = Some(host.into());
        self
    }

    /// Register an additional public host for `tenant_slug`. The
    /// same page URL gets purged for every registered host; useful
    /// when a tenant is served under both `acme.example.com` and a
    /// vanity domain `acme.com`.
    #[must_use]
    pub fn with_tenant_host(
        mut self,
        tenant_slug: impl Into<String>,
        host: impl Into<String>,
    ) -> Self {
        self.tenant_hosts
            .entry(tenant_slug.into())
            .or_default()
            .push(host.into());
        self
    }

    /// Override the URL scheme (default: `https`). Useful for
    /// localhost / dev where the public origin is HTTP-only.
    #[must_use]
    pub fn with_scheme(mut self, scheme: impl Into<String>) -> Self {
        self.scheme = scheme.into();
        self
    }

    /// Override the Cloudflare API base URL. Used by tests to point
    /// at an httpmock server; production keeps the default.
    #[must_use]
    pub fn with_api_base(mut self, api_base: impl Into<String>) -> Self {
        self.api_base = api_base.into();
        self
    }

    /// Resolve every public URL we need to purge for one
    /// `(tenant_slug, url_path)` pair. Joins each registered host
    /// (per-tenant + the fallback `default_host` if any) with the
    /// path. The path is taken verbatim — Cloudflare's API matches
    /// exact-URL purges, so callers should pre-normalise (leading
    /// `/`, no trailing slash for non-root).
    fn resolve_urls(&self, tenant_slug: &str, url_path: &str) -> Vec<String> {
        let mut hosts: Vec<&str> = self
            .tenant_hosts
            .get(tenant_slug)
            .map(|v| v.iter().map(String::as_str).collect())
            .unwrap_or_default();
        if hosts.is_empty() {
            if let Some(h) = self.default_host.as_deref() {
                hosts.push(h);
            }
        }
        hosts
            .into_iter()
            .map(|h| format!("{}://{}{}", self.scheme, h, url_path))
            .collect()
    }

    /// Max `files` entries per `purge_cache` request. Cloudflare caps
    /// the Free/Pro/Business tiers at 30 URLs per call; Enterprise
    /// allows more. We chunk at 30 so a single save spanning many
    /// descendant URLs works on every plan.
    const MAX_FILES_PER_REQUEST: usize = 30;

    /// POST to `/client/v4/zones/{zone_id}/purge_cache` with the
    /// exact-URL `files` list. Best-effort. Chunked at
    /// [`Self::MAX_FILES_PER_REQUEST`] so large subtree purges don't
    /// 400 on the non-Enterprise per-request cap. Exposed at
    /// module scope (vs the trait fn) so the integration tests can
    /// drive it without juggling an `Arc<dyn Trait>` cast.
    async fn purge(&self, urls: Vec<String>) {
        if urls.is_empty() {
            return;
        }
        #[derive(Serialize)]
        struct Body<'a> {
            files: &'a [String],
        }
        for chunk in urls.chunks(Self::MAX_FILES_PER_REQUEST) {
            self.send_purge(&Body { files: chunk }, "files").await;
        }
    }

    /// Purge by **cache-tag**. Cloudflare Enterprise stamps
    /// responses with `Cache-Tag` headers; purging a tag drops every
    /// edge entry carrying it in one call — far cheaper than
    /// enumerating URLs. The CMS doesn't auto-tag responses, so this
    /// is a public hook: a host that sets `Cache-Tag` (e.g. per
    /// page-type or per snippet) calls this after the relevant save.
    /// No-op on non-Enterprise zones (the API rejects `tags`).
    pub async fn purge_tags(&self, tags: Vec<String>) {
        if tags.is_empty() {
            return;
        }
        #[derive(Serialize)]
        struct Body {
            tags: Vec<String>,
        }
        self.send_purge(&Body { tags }, "tags").await;
    }

    /// Purge by **URL prefix** — Enterprise-only. Drops every
    /// edge entry whose URL starts with one of `prefixes`
    /// (`example.com/blog/`), i.e. a true subtree purge without
    /// enumerating each descendant. No-op on non-Enterprise zones.
    pub async fn purge_prefixes(&self, prefixes: Vec<String>) {
        if prefixes.is_empty() {
            return;
        }
        #[derive(Serialize)]
        struct Body {
            prefixes: Vec<String>,
        }
        self.send_purge(&Body { prefixes }, "prefixes").await;
    }

    /// Send one `purge_cache` POST with an arbitrary body shape
    /// (`files` / `tags` / `prefixes`). `kind` is only for log
    /// context. Failures are logged at WARN and swallowed per the
    /// [`PageCacheInvalidator`] best-effort contract.
    async fn send_purge<B: Serialize>(&self, body: &B, kind: &str) {
        let url = format!(
            "{}/client/v4/zones/{}/purge_cache",
            self.api_base, self.zone_id
        );
        let req = self.http.post(url.as_str());
        let req = match req.header("authorization", format!("Bearer {}", self.api_token)) {
            Ok(r) => r,
            Err(e) => {
                tracing::warn!(
                    target: "rustango_cms::cache_invalidate",
                    error = %e, %kind,
                    "cloudflare purge: header build failed"
                );
                return;
            }
        };
        let req = match req.json(body) {
            Ok(r) => r,
            Err(e) => {
                tracing::warn!(
                    target: "rustango_cms::cache_invalidate",
                    error = %e, %kind,
                    "cloudflare purge: body serialise failed"
                );
                return;
            }
        };
        match req.send().await {
            Ok(resp) if resp.status().is_success() => {
                tracing::debug!(
                    target: "rustango_cms::cache_invalidate",
                    status = %resp.status(), %kind,
                    "cloudflare purge ok"
                );
            }
            Ok(resp) => {
                tracing::warn!(
                    target: "rustango_cms::cache_invalidate",
                    status = %resp.status(), %kind,
                    "cloudflare purge: non-2xx response"
                );
            }
            Err(e) => {
                tracing::warn!(
                    target: "rustango_cms::cache_invalidate",
                    error = %e, %kind,
                    "cloudflare purge: network failure"
                );
            }
        }
    }
}

#[async_trait]
impl PageCacheInvalidator for CloudflareInvalidator {
    async fn invalidate_url(&self, tenant: &rustango::tenancy::TenantSlug, url_path: &str) {
        self.purge(self.resolve_urls(&tenant.slug, url_path)).await;
    }

    async fn invalidate_subtree(&self, tenant: &rustango::tenancy::TenantSlug, url_path: &str) {
        // Cloudflare's `purge_cache` API supports `prefixes` for
        // subtree purges, but it's an Enterprise-only feature. The
        // free / Pro / Business tiers only accept exact URLs. Fall
        // back to a single-URL purge — callers on an Enterprise zone
        // can call [`Self::purge_prefixes`] explicitly for a true
        // subtree drop. Keeping the default to the single-URL purge
        // gives Free/Pro/Business operators a working purge for the
        // most-common case.
        self.purge(self.resolve_urls(&tenant.slug, url_path)).await;
    }

    async fn invalidate_urls(&self, tenant: &rustango::tenancy::TenantSlug, url_paths: &[String]) {
        // #428 — batch every (path × host) into one `files` array
        // (chunked by `purge`) instead of one POST per path. A save
        // that touches a page + its descendants now costs a single
        // round-trip on the common case (≤30 URLs).
        let urls: Vec<String> = url_paths
            .iter()
            .flat_map(|p| self.resolve_urls(&tenant.slug, p))
            .collect();
        self.purge(urls).await;
    }
}

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

    /// Pure-Rust check — the `resolve_urls` build is exercised by
    /// the live tests below but a sync check keeps the URL-shape
    /// regression guard cheap.
    #[test]
    fn resolve_urls_uses_default_host_when_no_per_tenant() {
        let inv = CloudflareInvalidator::new("z", "t").with_origin_host("example.com");
        let urls = inv.resolve_urls("acme", "/about");
        assert_eq!(urls, vec!["https://example.com/about"]);
    }

    #[test]
    fn resolve_urls_per_tenant_overrides_default() {
        let inv = CloudflareInvalidator::new("z", "t")
            .with_origin_host("fallback.example.com")
            .with_tenant_host("acme", "acme.example.com")
            .with_tenant_host("acme", "acme.com");
        let urls = inv.resolve_urls("acme", "/pricing");
        assert!(urls.contains(&"https://acme.example.com/pricing".to_owned()));
        assert!(urls.contains(&"https://acme.com/pricing".to_owned()));
        assert!(
            !urls.contains(&"https://fallback.example.com/pricing".to_owned()),
            "fallback shouldn't fire when tenant has its own host: {urls:?}"
        );
    }

    #[test]
    fn resolve_urls_no_host_no_urls() {
        // No default host + no per-tenant registration → empty
        // list. The purge fn short-circuits before sending.
        let inv = CloudflareInvalidator::new("z", "t");
        assert!(inv.resolve_urls("acme", "/about").is_empty());
    }

    #[test]
    fn resolve_urls_custom_scheme() {
        let inv = CloudflareInvalidator::new("z", "t")
            .with_origin_host("example.com")
            .with_scheme("http");
        let urls = inv.resolve_urls("acme", "/about");
        assert_eq!(urls, vec!["http://example.com/about"]);
    }

    #[tokio::test]
    async fn purge_sends_correct_url_and_headers() {
        let server = MockServer::start();
        let mock = server.mock(|when, then| {
            when.method(POST)
                .path("/client/v4/zones/zone-xyz/purge_cache")
                .header("authorization", "Bearer secret-token")
                .header("content-type", "application/json")
                .json_body_includes(r#"{"files": ["https://example.com/about"]}"#);
            then.status(200).body(r#"{"success": true}"#);
        });
        let inv = CloudflareInvalidator::new("zone-xyz", "secret-token")
            .with_origin_host("example.com")
            .with_api_base(server.base_url());
        inv.invalidate_url(&rustango::tenancy::TenantSlug::new(1, "acme"), "/about").await;
        mock.assert();
    }

    #[tokio::test]
    async fn non_2xx_response_doesnt_panic() {
        let server = MockServer::start();
        let _mock = server.mock(|when, then| {
            when.method(POST);
            then.status(403).body(
                r#"{"success": false, "errors": [{"code": 1000, "message": "Invalid token"}]}"#,
            );
        });
        let inv = CloudflareInvalidator::new("z", "bad-token")
            .with_origin_host("example.com")
            .with_api_base(server.base_url());
        // Should swallow the error per the trait contract.
        inv.invalidate_url(&rustango::tenancy::TenantSlug::new(1, "acme"), "/about").await;
    }

    #[tokio::test]
    async fn no_host_no_request_fires() {
        // Forgetting to register a host shouldn't 500 the admin —
        // the empty URL list is short-circuited before the POST.
        let server = MockServer::start();
        let mock = server.mock(|when, then| {
            when.method(POST);
            then.status(200);
        });
        let inv = CloudflareInvalidator::new("z", "t").with_api_base(server.base_url());
        inv.invalidate_url(&rustango::tenancy::TenantSlug::new(1, "acme"), "/about").await;
        assert_eq!(mock.calls(), 0, "no host registered should mean no HTTP");
    }

    #[tokio::test]
    async fn subtree_falls_back_to_url_purge() {
        // Enterprise-only `prefixes` purge isn't shipped in v1 — the
        // subtree variant should send the same exact-URL purge as
        // the single-URL one.
        let server = MockServer::start();
        let mock = server.mock(|when, then| {
            when.method(POST).path("/client/v4/zones/z/purge_cache");
            then.status(200).body(r#"{"success": true}"#);
        });
        let inv = CloudflareInvalidator::new("z", "t")
            .with_origin_host("example.com")
            .with_api_base(server.base_url());
        inv.invalidate_subtree(&rustango::tenancy::TenantSlug::new(1, "acme"), "/blog").await;
        mock.assert();
    }

    #[tokio::test]
    async fn invalidate_urls_batches_into_one_request() {
        // #428 — three paths must collapse into ONE purge_cache POST
        // carrying all three exact URLs, not three separate calls.
        let server = MockServer::start();
        let mock = server.mock(|when, then| {
            when.method(POST)
                .path("/client/v4/zones/z/purge_cache")
                .json_body_includes(
                    r#"{"files": ["https://example.com/a", "https://example.com/b", "https://example.com/c"]}"#,
                );
            then.status(200).body(r#"{"success": true}"#);
        });
        let inv = CloudflareInvalidator::new("z", "t")
            .with_origin_host("example.com")
            .with_api_base(server.base_url());
        inv.invalidate_urls(&rustango::tenancy::TenantSlug::new(1, "acme"), &["/a".to_owned(), "/b".to_owned(), "/c".to_owned()])
            .await;
        assert_eq!(mock.calls(), 1, "three paths should batch into one POST");
    }

    #[tokio::test]
    async fn invalidate_urls_chunks_over_thirty() {
        // 31 URLs exceeds the 30-per-request cap → exactly two POSTs.
        let server = MockServer::start();
        let mock = server.mock(|when, then| {
            when.method(POST).path("/client/v4/zones/z/purge_cache");
            then.status(200).body(r#"{"success": true}"#);
        });
        let inv = CloudflareInvalidator::new("z", "t")
            .with_origin_host("example.com")
            .with_api_base(server.base_url());
        let paths: Vec<String> = (0..31).map(|i| format!("/p{i}")).collect();
        inv.invalidate_urls(&rustango::tenancy::TenantSlug::new(1, "acme"), &paths).await;
        assert_eq!(mock.calls(), 2, "31 URLs should split into 30 + 1");
    }

    #[tokio::test]
    async fn purge_tags_sends_tags_body() {
        let server = MockServer::start();
        let mock = server.mock(|when, then| {
            when.method(POST)
                .path("/client/v4/zones/z/purge_cache")
                .header("authorization", "Bearer tok")
                .json_body_includes(r#"{"tags": ["page-type:blog", "snippet:42"]}"#);
            then.status(200).body(r#"{"success": true}"#);
        });
        let inv = CloudflareInvalidator::new("z", "tok").with_api_base(server.base_url());
        inv.purge_tags(vec!["page-type:blog".to_owned(), "snippet:42".to_owned()])
            .await;
        mock.assert();
    }

    #[tokio::test]
    async fn purge_prefixes_sends_prefixes_body() {
        let server = MockServer::start();
        let mock = server.mock(|when, then| {
            when.method(POST)
                .path("/client/v4/zones/z/purge_cache")
                .json_body_includes(r#"{"prefixes": ["example.com/blog/"]}"#);
            then.status(200).body(r#"{"success": true}"#);
        });
        let inv = CloudflareInvalidator::new("z", "t").with_api_base(server.base_url());
        inv.purge_prefixes(vec!["example.com/blog/".to_owned()])
            .await;
        mock.assert();
    }

    #[tokio::test]
    async fn empty_tag_and_prefix_purges_are_noops() {
        let server = MockServer::start();
        let mock = server.mock(|when, then| {
            when.method(POST);
            then.status(200);
        });
        let inv = CloudflareInvalidator::new("z", "t").with_api_base(server.base_url());
        inv.purge_tags(vec![]).await;
        inv.purge_prefixes(vec![]).await;
        assert_eq!(mock.calls(), 0, "empty lists must not POST");
    }
}