Skip to main content

rustango_cms/
task_queue.rs

1//! Pluggable background task queue for CMS heavy work.
2//!
3//! Heavy post-request work (cache purge, search/reference indexing,
4//! scheduled publish) belongs on a pluggable, retriable queue. The
5//! `rustango` framework already ships the execution machinery —
6//! [`rustango::jobs`]: a [`Job`] trait + a [`JobQueue`] with an
7//! in-memory backend and a persistent Postgres backend
8//! (retry/backoff/dead-letter). This module **wires CMS work onto it**.
9//!
10//! ## Why a `TaskSink`
11//!
12//! `JobQueue`'s methods are generic (`dispatch::<T>`), so it isn't
13//! object-safe and the framework has no process-global queue — fine
14//! for an app that threads its concrete queue around, but a *library*
15//! buried under `on_commit` can't reach it. So the CMS keeps a small
16//! **object-safe [`TaskSink`]** in a process global. Hosts wrap their
17//! concrete queue in [`JobQueueSink`] (a blanket adapter) and install
18//! it with [`set_sink`].
19//!
20//! ## Inline default
21//!
22//! With no sink installed (the common single-process deploy) the work
23//! runs **inline** (synchronously) — identical to the old
24//! detached-spawn behavior, just without retry/persistence.
25//!
26//! ## Context-free jobs
27//!
28//! [`Job::run`] receives only its deserialized payload. Tenant-scoped
29//! jobs resolve their resources from a process registry (the pattern
30//! `rustango::email_jobs` uses for its mailer): [`register_invalidator`]
31//! stashes a tenant's [`PageCacheInvalidator`] so a deserialized
32//! [`CachePurgeJob`] can find it in `run()`.
33
34use crate::log_err::LogErr as _;
35use std::collections::HashMap;
36use std::sync::{Arc, OnceLock, RwLock};
37
38use async_trait::async_trait;
39use rustango::jobs::{Job, JobError, JobQueue};
40use serde::{Deserialize, Serialize};
41
42use crate::cache_invalidate::PageCacheInvalidator;
43
44// ---- object-safe sink + process-global handle --------------------
45
46/// Object-safe enqueue surface the CMS holds globally. One method per
47/// CMS job kind (the set is small + CMS-owned). Hosts don't implement
48/// this — they wrap their concrete [`JobQueue`] in [`JobQueueSink`].
49#[async_trait]
50pub trait TaskSink: Send + Sync + 'static {
51    /// Enqueue a [`CachePurgeJob`] for asynchronous, retriable run.
52    async fn dispatch_cache_purge(&self, job: CachePurgeJob) -> Result<(), JobError>;
53
54    /// Enqueue a [`ReferenceIndexJob`] for asynchronous, retriable run.
55    async fn dispatch_reference_index(&self, job: ReferenceIndexJob) -> Result<(), JobError>;
56
57    /// Enqueue a [`SearchIndexJob`] for asynchronous, retriable run.
58    async fn dispatch_search_index(&self, job: SearchIndexJob) -> Result<(), JobError>;
59}
60
61static SINK: OnceLock<Arc<dyn TaskSink>> = OnceLock::new();
62
63/// Install the background task sink. Call once at startup, after
64/// [`register_cms_jobs`] + the queue's `start()`. Without it, CMS
65/// background work runs inline.
66pub fn set_sink(sink: Arc<dyn TaskSink>) {
67    // Set once; a second install would be silently lost otherwise (#697).
68    if SINK.set(sink).is_err() {
69        tracing::error!(target: "rustango_cms", "set_sink: a task sink is already installed; this one is ignored");
70    }
71}
72
73fn sink() -> Option<&'static Arc<dyn TaskSink>> {
74    SINK.get()
75}
76
77/// Adapter: turn any concrete framework [`JobQueue`] into a
78/// [`TaskSink`]. Hosts install it with
79/// `set_sink(Arc::new(JobQueueSink(queue)))`.
80pub struct JobQueueSink<Q: JobQueue>(pub Arc<Q>);
81
82#[async_trait]
83impl<Q: JobQueue> TaskSink for JobQueueSink<Q> {
84    async fn dispatch_cache_purge(&self, job: CachePurgeJob) -> Result<(), JobError> {
85        self.0.dispatch::<CachePurgeJob>(&job).await
86    }
87    async fn dispatch_reference_index(&self, job: ReferenceIndexJob) -> Result<(), JobError> {
88        self.0.dispatch::<ReferenceIndexJob>(&job).await
89    }
90    async fn dispatch_search_index(&self, job: SearchIndexJob) -> Result<(), JobError> {
91        self.0.dispatch::<SearchIndexJob>(&job).await
92    }
93}
94
95/// Register every CMS job type on `queue`. Call once at startup before
96/// the queue's `start()`; pair with [`set_sink`].
97pub async fn register_cms_jobs<Q: JobQueue>(queue: &Q) {
98    queue.register::<CachePurgeJob>().await;
99    queue.register::<ReferenceIndexJob>().await;
100    queue.register::<SearchIndexJob>().await;
101}
102
103// ---- per-tenant resource registry (for context-free run()) -------
104
105fn invalidator_registry() -> &'static RwLock<HashMap<String, Arc<dyn PageCacheInvalidator>>> {
106    static REG: OnceLock<RwLock<HashMap<String, Arc<dyn PageCacheInvalidator>>>> = OnceLock::new();
107    REG.get_or_init(|| RwLock::new(HashMap::new()))
108}
109
110/// Stash a tenant's cache invalidator so a deserialized
111/// [`CachePurgeJob`] can resolve it in `run()`. Idempotent. Called
112/// automatically by [`purge_urls`] from the in-hand invalidator, so
113/// hosts don't normally call it.
114pub fn register_invalidator(
115    tenant_slug: impl Into<String>,
116    invalidator: Arc<dyn PageCacheInvalidator>,
117) {
118    if let Ok(mut m) = invalidator_registry().write() {
119        m.insert(tenant_slug.into(), invalidator);
120    }
121}
122
123fn resolve_invalidator(tenant_slug: &str) -> Option<Arc<dyn PageCacheInvalidator>> {
124    invalidator_registry()
125        .read()
126        .ok()
127        .and_then(|m| m.get(tenant_slug).cloned())
128        .or_else(|| DEFAULT_INVALIDATOR.get().cloned())
129}
130
131/// The invalidator a job falls back to when its tenant has no entry in
132/// this process — a durable queue drained by a worker that never served
133/// the tenant, or a job run after a restart. Set automatically by
134/// [`crate::admin::router_with_invalidator`]; a worker-only process calls
135/// [`set_default_invalidator`] itself.
136static DEFAULT_INVALIDATOR: OnceLock<Arc<dyn PageCacheInvalidator>> = OnceLock::new();
137
138/// The process-wide invalidator, if one is set — for paths with no admin
139/// state of their own, such as MCP tools.
140#[must_use]
141pub fn default_invalidator() -> Option<Arc<dyn PageCacheInvalidator>> {
142    DEFAULT_INVALIDATOR.get().cloned()
143}
144
145/// Set the fallback cache invalidator for queued purge jobs. The
146/// first call wins.
147pub fn set_default_invalidator(invalidator: Arc<dyn PageCacheInvalidator>) {
148    let _ = DEFAULT_INVALIDATOR.set(invalidator);
149}
150
151/// The mailer and `From:` address paths with no admin state use — the
152/// schedule sweep's publish emails (#945). Set by
153/// [`crate::admin::router_with_mailer`]; first call wins.
154static DEFAULT_MAILER: OnceLock<(Arc<dyn rustango::email::Mailer>, String)> = OnceLock::new();
155
156/// The process-wide mailer and its `From:` address, if one is set.
157#[must_use]
158pub fn default_mailer() -> Option<(Arc<dyn rustango::email::Mailer>, String)> {
159    DEFAULT_MAILER.get().cloned()
160}
161
162/// Set the process-wide mailer. The first call wins.
163pub fn set_default_mailer(mailer: Arc<dyn rustango::email::Mailer>, from: impl Into<String>) {
164    let _ = DEFAULT_MAILER.set((mailer, from.into()));
165}
166
167fn pool_registry() -> &'static RwLock<HashMap<String, rustango::sql::Pool>> {
168    static REG: OnceLock<RwLock<HashMap<String, rustango::sql::Pool>>> = OnceLock::new();
169    REG.get_or_init(|| RwLock::new(HashMap::new()))
170}
171
172/// Stash a tenant's DB pool so a deserialized [`ReferenceIndexJob`] can
173/// resolve it in `run()`. Idempotent. Called automatically by
174/// [`reindex_page`] from the in-hand pool, so hosts don't normally
175/// call it.
176pub fn register_pool(tenant_slug: impl Into<String>, pool: rustango::sql::Pool) {
177    if let Ok(mut m) = pool_registry().write() {
178        m.insert(tenant_slug.into(), pool);
179    }
180}
181
182fn registered_pool(tenant_slug: &str) -> Option<rustango::sql::Pool> {
183    pool_registry().read().ok()?.get(tenant_slug).cloned()
184}
185
186/// The tenant registry, recorded by the boot-time seed so a job can find
187/// a tenant this process never served.
188static REGISTRY: OnceLock<rustango::sql::Pool> = OnceLock::new();
189
190/// Record the tenant registry pool for `resolve_pool`'s fallback.
191/// Called by [`crate::seed::ensure_seeded`]; the first call wins.
192pub fn set_registry(registry: rustango::sql::Pool) {
193    let _ = REGISTRY.set(registry);
194}
195
196/// A tenant's pool: the one this process registered, or — for a durable
197/// job drained by another process or after a restart — resolved from the
198/// registry by slug, and then registered. `None` when neither knows it.
199pub(crate) async fn resolve_pool(tenant_slug: &str) -> Option<rustango::sql::Pool> {
200    if let Some(pool) = registered_pool(tenant_slug) {
201        return Some(pool);
202    }
203    let registry = REGISTRY.get()?;
204    let pool = scoped_pool_for(registry, tenant_slug).await?;
205    register_pool(tenant_slug, pool.clone());
206    Some(pool)
207}
208
209async fn registry_org(
210    registry: &rustango::sql::Pool,
211    tenant_slug: &str,
212) -> Option<rustango::tenancy::Org> {
213    use rustango::core::Column as _;
214    use rustango::tenancy::Org;
215    Org::objects()
216        .where_(Org::slug.eq(tenant_slug.to_owned()))
217        .first(registry)
218        .await
219        .ok()?
220}
221
222async fn scoped_pool_for(
223    registry: &rustango::sql::Pool,
224    tenant_slug: &str,
225) -> Option<rustango::sql::Pool> {
226    use rustango::tenancy::TenantPools;
227    let org = registry_org(registry, tenant_slug).await?;
228    match registry {
229        #[cfg(feature = "postgres")]
230        rustango::sql::Pool::Postgres(pg) => {
231            TenantPools::<rustango::sql::sqlx::Postgres>::new(pg.clone()).scoped_pool_dyn(&org).await.ok()
232        }
233        #[cfg(feature = "sqlite")]
234        rustango::sql::Pool::Sqlite(sq) => {
235            TenantPools::<rustango::sql::sqlx::Sqlite>::new(sq.clone()).scoped_pool_dyn(&org).await.ok()
236        }
237        #[cfg(feature = "mysql")]
238        rustango::sql::Pool::Mysql(my) => {
239            TenantPools::<rustango::sql::sqlx::MySql>::new(my.clone()).scoped_pool_dyn(&org).await.ok()
240        }
241    }
242}
243
244// ---- cache-purge job ---------------------------------------------
245
246/// Drop the public-cache entries for `urls` on one tenant. Enqueued
247/// after a page mutation commits. Retriable — a transient
248/// backend hiccup is retried with backoff; a missing tenant
249/// registration is fatal (a startup-wiring gap, not transient).
250#[derive(Debug, Clone, Serialize, Deserialize)]
251pub struct CachePurgeJob {
252    pub tenant_slug: String,
253    /// The tenant's org id, which the page cache keys on. Jobs queued
254    /// before 0.4.0 lack it and purge nothing; their TTL still runs out.
255    #[serde(default)]
256    pub org_id: i64,
257    pub urls: Vec<String>,
258}
259
260#[async_trait]
261impl Job for CachePurgeJob {
262    const NAME: &'static str = "rcms.cache_purge";
263
264    async fn run(&self) -> Result<(), JobError> {
265        let Some(invalidator) = resolve_invalidator(&self.tenant_slug) else {
266            return Err(JobError::Fatal(format!(
267                "cache_purge: no invalidator registered for tenant `{}`",
268                self.tenant_slug
269            )));
270        };
271        // #428 — one batch call so a bulk-purge backend (Cloudflare
272        // `files`, Azure `contentPaths`) collapses the save into a
273        // single round-trip; the default impl still loops per-URL.
274        let tenant = rustango::tenancy::TenantSlug::new(self.org_id, self.tenant_slug.clone());
275        invalidator.invalidate_urls(&tenant, &self.urls).await;
276        Ok(())
277    }
278}
279
280/// Purge `urls` for `tenant`. Dispatches a retriable
281/// [`CachePurgeJob`] when a sink is installed; otherwise purges
282/// **inline** against the in-hand `invalidator` (today's behavior).
283/// Drive this from the detached `on_commit` task in
284/// [`crate::cache_invalidate::invalidate_urls_on_commit`].
285pub async fn purge_urls(
286    invalidator: Arc<dyn PageCacheInvalidator>,
287    tenant: rustango::tenancy::TenantSlug,
288    urls: Vec<String>,
289) {
290    if urls.is_empty() {
291        return;
292    }
293    let Some(sink) = sink() else {
294        purge_inline(invalidator.as_ref(), &tenant, &urls).await;
295        return;
296    };
297    // Make the invalidator resolvable inside the deserialized job.
298    register_invalidator(tenant.slug.clone(), invalidator.clone());
299    let job = CachePurgeJob {
300        tenant_slug: tenant.slug.clone(),
301        org_id: tenant.org_id,
302        urls: urls.clone(),
303    };
304    if let Err(e) = sink.dispatch_cache_purge(job).await {
305        tracing::warn!(
306            target: "rustango_cms::task_queue",
307            error = %e,
308            "cache_purge dispatch failed; purging inline so stale entries aren't stranded",
309        );
310        purge_inline(invalidator.as_ref(), &tenant, &urls).await;
311    }
312}
313
314async fn purge_inline(
315    invalidator: &dyn PageCacheInvalidator,
316    tenant: &rustango::tenancy::TenantSlug,
317    urls: &[String],
318) {
319    // #428 — batch fan-out (see `CachePurgeJob::run`).
320    invalidator.invalidate_urls(tenant, urls).await;
321}
322
323// ---- reference-index job -----------------------------------------
324
325/// Serializable form of [`crate::reference_index::Reference`]. The
326/// `Reference` itself can't be deserialized (its `to_kind` is a
327/// `&'static str`); the job payload carries owned strings and
328/// `to_reference` maps `to_kind` back to the interned constant.
329#[derive(Debug, Clone, Serialize, Deserialize)]
330pub struct OwnedRef {
331    pub to_kind: String,
332    pub to_id: i64,
333    pub field_path: String,
334}
335
336impl OwnedRef {
337    fn from_ref(r: &crate::reference_index::Reference) -> Self {
338        Self {
339            to_kind: r.to_kind.to_owned(),
340            to_id: r.to_id,
341            field_path: r.field_path.clone(),
342        }
343    }
344
345    /// Back to a `Reference` with an interned `to_kind`, or `None` for
346    /// an unknown kind (forward-compat guard — skipped on rebuild).
347    fn to_reference(&self) -> Option<crate::reference_index::Reference> {
348        let kind = kind_const(&self.to_kind)?;
349        Some(crate::reference_index::Reference {
350            to_kind: kind,
351            to_id: self.to_id,
352            field_path: self.field_path.clone(),
353        })
354    }
355}
356
357fn kind_const(s: &str) -> Option<&'static str> {
358    use crate::reference_index::{KIND_MEDIA, KIND_PAGE, KIND_SNIPPET};
359    [KIND_PAGE, KIND_SNIPPET, KIND_MEDIA]
360        .into_iter()
361        .find(|k| *k == s)
362}
363
364/// Rebuild a page's outbound reference rows. Carries the
365/// already-scanned refs in its payload, so `run()` only needs the
366/// tenant pool (resolved from the registry) to replace the rows —
367/// retriable if that write hits a transient error.
368#[derive(Debug, Clone, Serialize, Deserialize)]
369pub struct ReferenceIndexJob {
370    pub tenant_slug: String,
371    pub page_id: i64,
372    pub refs: Vec<OwnedRef>,
373}
374
375#[async_trait]
376impl Job for ReferenceIndexJob {
377    const NAME: &'static str = "rcms.reference_index";
378
379    async fn run(&self) -> Result<(), JobError> {
380        let Some(pool) = resolve_pool(&self.tenant_slug).await else {
381            return Err(JobError::Fatal(format!(
382                "reference_index: no pool registered for tenant `{}`",
383                self.tenant_slug
384            )));
385        };
386        let refs = self
387            .refs
388            .iter()
389            .filter_map(OwnedRef::to_reference)
390            .collect();
391        crate::reference_index::reindex_source(
392            &pool,
393            crate::reference_index::KIND_PAGE,
394            self.page_id,
395            refs,
396        )
397        .await
398        .map_err(|e| JobError::Retryable(format!("reference_index: {e}")))
399    }
400}
401
402/// Rebuild `page_id`'s reference rows from the already-scanned `refs`.
403/// Dispatches a retriable [`ReferenceIndexJob`] when a sink is
404/// installed; otherwise reindexes **inline** (today's behavior).
405/// Best-effort — errors are logged, never propagated, so a transient
406/// index hiccup can't block a save.
407pub async fn reindex_page(
408    pool: &rustango::sql::Pool,
409    tenant_slug: &str,
410    page_id: i64,
411    refs: Vec<crate::reference_index::Reference>,
412) {
413    let Some(sink) = sink() else {
414        reindex_inline(pool, page_id, refs).await;
415        return;
416    };
417    register_pool(tenant_slug.to_owned(), pool.clone());
418    let job = ReferenceIndexJob {
419        tenant_slug: tenant_slug.to_owned(),
420        page_id,
421        refs: refs.iter().map(OwnedRef::from_ref).collect(),
422    };
423    if let Err(e) = sink.dispatch_reference_index(job).await {
424        tracing::warn!(
425            target: "rustango_cms::task_queue",
426            error = %e,
427            "reference_index dispatch failed; reindexing inline",
428        );
429        reindex_inline(pool, page_id, refs).await;
430    }
431}
432
433async fn reindex_inline(
434    pool: &rustango::sql::Pool,
435    page_id: i64,
436    refs: Vec<crate::reference_index::Reference>,
437) {
438    if let Err(e) = crate::reference_index::reindex_source(
439        pool,
440        crate::reference_index::KIND_PAGE,
441        page_id,
442        refs,
443    )
444    .await
445    {
446        tracing::warn!(
447            target: "rustango_cms::task_queue",
448            page_id,
449            error = %e,
450            "inline reference reindex failed",
451        );
452    }
453}
454
455// ---- search-index job (#408 × #432) ------------------------------
456
457/// What a [`SearchIndexJob`] does to a page's search document.
458#[derive(Debug, Clone, Serialize, Deserialize)]
459pub enum SearchIndexAction {
460    /// Upsert the page into the external search index (it's published).
461    Index(crate::search::SearchDoc),
462    /// Remove the page from the index (deleted / unpublished / expired).
463    Delete(i64),
464}
465
466/// Keep an external [`crate::search::SearchBackend`] (Elasticsearch) in
467/// sync with a page change. A no-op at run time when no backend
468/// is installed — the built-in Postgres FTS path queries live data and
469/// needs no index. Retriable: an ES hiccup is retried rather than
470/// silently dropping the update.
471#[derive(Debug, Clone, Serialize, Deserialize)]
472pub struct SearchIndexJob {
473    pub tenant_slug: String,
474    pub action: SearchIndexAction,
475}
476
477#[async_trait]
478impl Job for SearchIndexJob {
479    const NAME: &'static str = "rcms.search_index";
480
481    async fn run(&self) -> Result<(), JobError> {
482        // The backend is a process global; no per-tenant resource
483        // registry needed. No backend installed → nothing to index.
484        let Some(backend) = crate::search::backend() else {
485            return Ok(());
486        };
487        match &self.action {
488            SearchIndexAction::Index(doc) => backend.index(&self.tenant_slug, doc).await,
489            SearchIndexAction::Delete(page_id) => backend.delete(&self.tenant_slug, *page_id).await,
490        }
491        Ok(())
492    }
493}
494
495/// Keep the external search index in step with a saved page: a page in
496/// a public status (published or archived) is indexed, any other
497/// status is removed (so draft / scheduled / expired pages drop out of
498/// search — archived pages now STAY findable). **No-op when no external
499/// [`crate::search::SearchBackend`] is installed** — the Postgres FTS
500/// path needs no maintained index. Dispatched via the queue when a sink
501/// is set, else run inline. Best-effort.
502pub async fn sync_page_search(tenant_slug: &str, page: &crate::page::Page) {
503    if crate::search::backend().is_none() {
504        return;
505    }
506    let Some(page_id) = page.id.get().copied() else {
507        return;
508    };
509    let is_public = page.status == crate::page::PageStatus::Published.as_str()
510        || page.status == crate::page::PageStatus::Archived.as_str();
511    let action = if is_public {
512        SearchIndexAction::Index(crate::search::SearchDoc {
513            page_id,
514            title: page.title.clone(),
515            seo_title: page.seo_title.clone(),
516            seo_description: page.seo_description.clone(),
517            url_path: page.url_path.clone(),
518            status: page.status.clone(),
519        })
520    } else {
521        SearchIndexAction::Delete(page_id)
522    };
523    let job = SearchIndexJob {
524        tenant_slug: tenant_slug.to_owned(),
525        action,
526    };
527    match sink() {
528        Some(s) => {
529            if let Err(e) = s.dispatch_search_index(job.clone()).await {
530                tracing::warn!(
531                    target: "rustango_cms::task_queue",
532                    error = %e,
533                    "search_index dispatch failed; running inline",
534                );
535                job.run().await.log_warn("search index job failed; the index may be stale");
536            }
537        }
538        None => {
539            job.run().await.log_warn("search index job failed; the index may be stale");
540        }
541    }
542}
543
544/// Remove a page from the external search index (on hard delete). No-op
545/// when no backend is installed. Queue-dispatched or inline.
546pub async fn remove_page_search(tenant_slug: &str, page_id: i64) {
547    if crate::search::backend().is_none() {
548        return;
549    }
550    let job = SearchIndexJob {
551        tenant_slug: tenant_slug.to_owned(),
552        action: SearchIndexAction::Delete(page_id),
553    };
554    match sink() {
555        Some(s) => {
556            if s.dispatch_search_index(job.clone()).await.is_err() {
557                job.run().await.log_warn("search index job failed; the index may be stale");
558            }
559        }
560        None => {
561            job.run().await.log_warn("search index job failed; the index may be stale");
562        }
563    }
564}
565
566#[cfg(test)]
567mod tests {
568    use super::*;
569    use std::sync::atomic::{AtomicUsize, Ordering};
570
571    /// Counts how many `invalidate_url` calls it received.
572    struct Counting(Arc<AtomicUsize>);
573
574    #[async_trait]
575    impl PageCacheInvalidator for Counting {
576        async fn invalidate_url(&self, _tenant: &rustango::tenancy::TenantSlug, _url_path: &str) {
577            self.0.fetch_add(1, Ordering::SeqCst);
578        }
579    }
580
581    #[test]
582    fn job_round_trips_and_has_stable_name() {
583        let job = CachePurgeJob {
584            tenant_slug: "acme".to_owned(),
585            org_id: 1,
586            urls: vec!["/a".to_owned(), "/b".to_owned()],
587        };
588        let json = serde_json::to_string(&job).unwrap();
589        let back: CachePurgeJob = serde_json::from_str(&json).unwrap();
590        assert_eq!(back.tenant_slug, "acme");
591        assert_eq!(back.org_id, 1);
592        assert_eq!(back.urls, vec!["/a", "/b"]);
593        assert_eq!(CachePurgeJob::NAME, "rcms.cache_purge");
594    }
595
596    #[tokio::test]
597    async fn run_purges_when_invalidator_registered() {
598        let n = Arc::new(AtomicUsize::new(0));
599        register_invalidator("acme-run", Arc::new(Counting(n.clone())));
600        let job = CachePurgeJob {
601            tenant_slug: "acme-run".to_owned(),
602            org_id: 1,
603            urls: vec!["/x".to_owned(), "/y".to_owned(), "/z".to_owned()],
604        };
605        assert!(job.run().await.is_ok());
606        assert_eq!(n.load(Ordering::SeqCst), 3);
607    }
608
609    #[tokio::test]
610    async fn run_is_fatal_without_registration() {
611        let job = CachePurgeJob {
612            tenant_slug: "never-registered-tenant".to_owned(),
613            org_id: 1,
614            urls: vec!["/x".to_owned()],
615        };
616        match job.run().await {
617            Err(JobError::Fatal(_)) => {}
618            other => panic!("expected Fatal, got {other:?}"),
619        }
620    }
621
622    #[tokio::test]
623    async fn purge_urls_runs_inline_when_no_sink() {
624        // No sink installed in tests → the inline path drives the
625        // in-hand invalidator directly.
626        let n = Arc::new(AtomicUsize::new(0));
627        let inv: Arc<dyn PageCacheInvalidator> = Arc::new(Counting(n.clone()));
628        purge_urls(
629            inv,
630            rustango::tenancy::TenantSlug::new(1, "acme-inline"),
631            vec!["/a".to_owned(), "/b".to_owned()],
632        )
633        .await;
634        assert_eq!(n.load(Ordering::SeqCst), 2);
635        // Empty url list is a no-op.
636        let inv2: Arc<dyn PageCacheInvalidator> = Arc::new(Counting(n.clone()));
637        purge_urls(inv2, rustango::tenancy::TenantSlug::new(1, "acme-inline"), vec![]).await;
638        assert_eq!(n.load(Ordering::SeqCst), 2);
639    }
640
641    #[test]
642    fn owned_ref_round_trips_known_kind_skips_unknown() {
643        use crate::reference_index::{Reference, KIND_MEDIA};
644        let r = Reference {
645            to_kind: KIND_MEDIA,
646            to_id: 7,
647            field_path: "body".to_owned(),
648        };
649        let owned = OwnedRef::from_ref(&r);
650        assert_eq!(owned.to_kind, "cms_media");
651        let back = owned.to_reference().expect("known kind");
652        assert_eq!(back.to_kind, KIND_MEDIA);
653        assert_eq!(back.to_id, 7);
654        // Unknown kind → dropped on rebuild (forward-compat guard).
655        let bogus = OwnedRef {
656            to_kind: "cms_widget".to_owned(),
657            to_id: 1,
658            field_path: "x".to_owned(),
659        };
660        assert!(bogus.to_reference().is_none());
661    }
662
663    #[test]
664    fn reference_index_job_round_trips_and_named() {
665        let job = ReferenceIndexJob {
666            tenant_slug: "acme".to_owned(),
667            page_id: 9,
668            refs: vec![OwnedRef {
669                to_kind: "cms_media".to_owned(),
670                to_id: 3,
671                field_path: "hero".to_owned(),
672            }],
673        };
674        let json = serde_json::to_string(&job).unwrap();
675        let back: ReferenceIndexJob = serde_json::from_str(&json).unwrap();
676        assert_eq!(back.page_id, 9);
677        assert_eq!(back.refs.len(), 1);
678        assert_eq!(ReferenceIndexJob::NAME, "rcms.reference_index");
679    }
680
681    #[tokio::test]
682    async fn reference_index_job_is_fatal_without_pool() {
683        let job = ReferenceIndexJob {
684            tenant_slug: "tenant-with-no-registered-pool".to_owned(),
685            page_id: 1,
686            refs: vec![],
687        };
688        match job.run().await {
689            Err(JobError::Fatal(_)) => {}
690            other => panic!("expected Fatal, got {other:?}"),
691        }
692    }
693
694    #[test]
695    fn search_index_job_round_trips_both_actions() {
696        let idx = SearchIndexJob {
697            tenant_slug: "acme".to_owned(),
698            action: SearchIndexAction::Index(crate::search::SearchDoc {
699                page_id: 5,
700                title: "Hi".to_owned(),
701                seo_title: String::new(),
702                seo_description: String::new(),
703                url_path: "/hi".to_owned(),
704                status: "published".to_owned(),
705            }),
706        };
707        let back: SearchIndexJob =
708            serde_json::from_str(&serde_json::to_string(&idx).unwrap()).unwrap();
709        assert!(matches!(back.action, SearchIndexAction::Index(d) if d.page_id == 5));
710        let del = SearchIndexJob {
711            tenant_slug: "acme".to_owned(),
712            action: SearchIndexAction::Delete(9),
713        };
714        let back2: SearchIndexJob =
715            serde_json::from_str(&serde_json::to_string(&del).unwrap()).unwrap();
716        assert!(matches!(back2.action, SearchIndexAction::Delete(9)));
717        assert_eq!(SearchIndexJob::NAME, "rcms.search_index");
718    }
719
720    #[tokio::test]
721    async fn search_index_job_is_noop_without_backend() {
722        // No SearchBackend installed (the default) → run() succeeds as a
723        // no-op; the Postgres FTS path needs no maintained index.
724        let job = SearchIndexJob {
725            tenant_slug: "acme".to_owned(),
726            action: SearchIndexAction::Delete(1),
727        };
728        assert!(job.run().await.is_ok());
729    }
730}