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
151fn pool_registry() -> &'static RwLock<HashMap<String, rustango::sql::Pool>> {
152    static REG: OnceLock<RwLock<HashMap<String, rustango::sql::Pool>>> = OnceLock::new();
153    REG.get_or_init(|| RwLock::new(HashMap::new()))
154}
155
156/// Stash a tenant's DB pool so a deserialized [`ReferenceIndexJob`] can
157/// resolve it in `run()`. Idempotent. Called automatically by
158/// [`reindex_page`] from the in-hand pool, so hosts don't normally
159/// call it.
160pub fn register_pool(tenant_slug: impl Into<String>, pool: rustango::sql::Pool) {
161    if let Ok(mut m) = pool_registry().write() {
162        m.insert(tenant_slug.into(), pool);
163    }
164}
165
166fn registered_pool(tenant_slug: &str) -> Option<rustango::sql::Pool> {
167    pool_registry().read().ok()?.get(tenant_slug).cloned()
168}
169
170/// The tenant registry, recorded by the boot-time seed so a job can find
171/// a tenant this process never served.
172static REGISTRY: OnceLock<rustango::sql::Pool> = OnceLock::new();
173
174/// Record the tenant registry pool for `resolve_pool`'s fallback.
175/// Called by [`crate::seed::ensure_seeded`]; the first call wins.
176pub fn set_registry(registry: rustango::sql::Pool) {
177    let _ = REGISTRY.set(registry);
178}
179
180/// A tenant's pool: the one this process registered, or — for a durable
181/// job drained by another process or after a restart — resolved from the
182/// registry by slug, and then registered. `None` when neither knows it.
183pub(crate) async fn resolve_pool(tenant_slug: &str) -> Option<rustango::sql::Pool> {
184    if let Some(pool) = registered_pool(tenant_slug) {
185        return Some(pool);
186    }
187    let registry = REGISTRY.get()?;
188    let pool = scoped_pool_for(registry, tenant_slug).await?;
189    register_pool(tenant_slug, pool.clone());
190    Some(pool)
191}
192
193async fn scoped_pool_for(
194    registry: &rustango::sql::Pool,
195    tenant_slug: &str,
196) -> Option<rustango::sql::Pool> {
197    use rustango::core::Column as _;
198    use rustango::tenancy::{Org, TenantPools};
199    let org = Org::objects()
200        .where_(Org::slug.eq(tenant_slug.to_owned()))
201        .first(registry)
202        .await
203        .ok()??;
204    match registry {
205        #[cfg(feature = "postgres")]
206        rustango::sql::Pool::Postgres(pg) => {
207            TenantPools::<rustango::sql::sqlx::Postgres>::new(pg.clone()).scoped_pool_dyn(&org).await.ok()
208        }
209        #[cfg(feature = "sqlite")]
210        rustango::sql::Pool::Sqlite(sq) => {
211            TenantPools::<rustango::sql::sqlx::Sqlite>::new(sq.clone()).scoped_pool_dyn(&org).await.ok()
212        }
213        #[cfg(feature = "mysql")]
214        rustango::sql::Pool::Mysql(my) => {
215            TenantPools::<rustango::sql::sqlx::MySql>::new(my.clone()).scoped_pool_dyn(&org).await.ok()
216        }
217    }
218}
219
220// ---- cache-purge job ---------------------------------------------
221
222/// Drop the public-cache entries for `urls` on one tenant. Enqueued
223/// after a page mutation commits. Retriable — a transient
224/// backend hiccup is retried with backoff; a missing tenant
225/// registration is fatal (a startup-wiring gap, not transient).
226#[derive(Debug, Clone, Serialize, Deserialize)]
227pub struct CachePurgeJob {
228    pub tenant_slug: String,
229    pub urls: Vec<String>,
230}
231
232#[async_trait]
233impl Job for CachePurgeJob {
234    const NAME: &'static str = "rcms.cache_purge";
235
236    async fn run(&self) -> Result<(), JobError> {
237        let Some(invalidator) = resolve_invalidator(&self.tenant_slug) else {
238            return Err(JobError::Fatal(format!(
239                "cache_purge: no invalidator registered for tenant `{}`",
240                self.tenant_slug
241            )));
242        };
243        // #428 — one batch call so a bulk-purge backend (Cloudflare
244        // `files`, Azure `contentPaths`) collapses the save into a
245        // single round-trip; the default impl still loops per-URL.
246        invalidator
247            .invalidate_urls(&self.tenant_slug, &self.urls)
248            .await;
249        Ok(())
250    }
251}
252
253/// Purge `urls` for `tenant_slug`. Dispatches a retriable
254/// [`CachePurgeJob`] when a sink is installed; otherwise purges
255/// **inline** against the in-hand `invalidator` (today's behavior).
256/// Drive this from the detached `on_commit` task in
257/// [`crate::cache_invalidate::invalidate_urls_on_commit`].
258pub async fn purge_urls(
259    invalidator: Arc<dyn PageCacheInvalidator>,
260    tenant_slug: String,
261    urls: Vec<String>,
262) {
263    if urls.is_empty() {
264        return;
265    }
266    let Some(sink) = sink() else {
267        purge_inline(invalidator.as_ref(), &tenant_slug, &urls).await;
268        return;
269    };
270    // Make the invalidator resolvable inside the deserialized job.
271    register_invalidator(tenant_slug.clone(), invalidator.clone());
272    let job = CachePurgeJob {
273        tenant_slug: tenant_slug.clone(),
274        urls: urls.clone(),
275    };
276    if let Err(e) = sink.dispatch_cache_purge(job).await {
277        tracing::warn!(
278            target: "rustango_cms::task_queue",
279            error = %e,
280            "cache_purge dispatch failed; purging inline so stale entries aren't stranded",
281        );
282        purge_inline(invalidator.as_ref(), &tenant_slug, &urls).await;
283    }
284}
285
286async fn purge_inline(invalidator: &dyn PageCacheInvalidator, tenant_slug: &str, urls: &[String]) {
287    // #428 — batch fan-out (see `CachePurgeJob::run`).
288    invalidator.invalidate_urls(tenant_slug, urls).await;
289}
290
291// ---- reference-index job -----------------------------------------
292
293/// Serializable form of [`crate::reference_index::Reference`]. The
294/// `Reference` itself can't be deserialized (its `to_kind` is a
295/// `&'static str`); the job payload carries owned strings and
296/// `to_reference` maps `to_kind` back to the interned constant.
297#[derive(Debug, Clone, Serialize, Deserialize)]
298pub struct OwnedRef {
299    pub to_kind: String,
300    pub to_id: i64,
301    pub field_path: String,
302}
303
304impl OwnedRef {
305    fn from_ref(r: &crate::reference_index::Reference) -> Self {
306        Self {
307            to_kind: r.to_kind.to_owned(),
308            to_id: r.to_id,
309            field_path: r.field_path.clone(),
310        }
311    }
312
313    /// Back to a `Reference` with an interned `to_kind`, or `None` for
314    /// an unknown kind (forward-compat guard — skipped on rebuild).
315    fn to_reference(&self) -> Option<crate::reference_index::Reference> {
316        let kind = kind_const(&self.to_kind)?;
317        Some(crate::reference_index::Reference {
318            to_kind: kind,
319            to_id: self.to_id,
320            field_path: self.field_path.clone(),
321        })
322    }
323}
324
325fn kind_const(s: &str) -> Option<&'static str> {
326    use crate::reference_index::{KIND_MEDIA, KIND_PAGE, KIND_SNIPPET};
327    [KIND_PAGE, KIND_SNIPPET, KIND_MEDIA]
328        .into_iter()
329        .find(|k| *k == s)
330}
331
332/// Rebuild a page's outbound reference rows. Carries the
333/// already-scanned refs in its payload, so `run()` only needs the
334/// tenant pool (resolved from the registry) to replace the rows —
335/// retriable if that write hits a transient error.
336#[derive(Debug, Clone, Serialize, Deserialize)]
337pub struct ReferenceIndexJob {
338    pub tenant_slug: String,
339    pub page_id: i64,
340    pub refs: Vec<OwnedRef>,
341}
342
343#[async_trait]
344impl Job for ReferenceIndexJob {
345    const NAME: &'static str = "rcms.reference_index";
346
347    async fn run(&self) -> Result<(), JobError> {
348        let Some(pool) = resolve_pool(&self.tenant_slug).await else {
349            return Err(JobError::Fatal(format!(
350                "reference_index: no pool registered for tenant `{}`",
351                self.tenant_slug
352            )));
353        };
354        let refs = self
355            .refs
356            .iter()
357            .filter_map(OwnedRef::to_reference)
358            .collect();
359        crate::reference_index::reindex_source(
360            &pool,
361            crate::reference_index::KIND_PAGE,
362            self.page_id,
363            refs,
364        )
365        .await
366        .map_err(|e| JobError::Retryable(format!("reference_index: {e}")))
367    }
368}
369
370/// Rebuild `page_id`'s reference rows from the already-scanned `refs`.
371/// Dispatches a retriable [`ReferenceIndexJob`] when a sink is
372/// installed; otherwise reindexes **inline** (today's behavior).
373/// Best-effort — errors are logged, never propagated, so a transient
374/// index hiccup can't block a save.
375pub async fn reindex_page(
376    pool: &rustango::sql::Pool,
377    tenant_slug: &str,
378    page_id: i64,
379    refs: Vec<crate::reference_index::Reference>,
380) {
381    let Some(sink) = sink() else {
382        reindex_inline(pool, page_id, refs).await;
383        return;
384    };
385    register_pool(tenant_slug.to_owned(), pool.clone());
386    let job = ReferenceIndexJob {
387        tenant_slug: tenant_slug.to_owned(),
388        page_id,
389        refs: refs.iter().map(OwnedRef::from_ref).collect(),
390    };
391    if let Err(e) = sink.dispatch_reference_index(job).await {
392        tracing::warn!(
393            target: "rustango_cms::task_queue",
394            error = %e,
395            "reference_index dispatch failed; reindexing inline",
396        );
397        reindex_inline(pool, page_id, refs).await;
398    }
399}
400
401async fn reindex_inline(
402    pool: &rustango::sql::Pool,
403    page_id: i64,
404    refs: Vec<crate::reference_index::Reference>,
405) {
406    if let Err(e) = crate::reference_index::reindex_source(
407        pool,
408        crate::reference_index::KIND_PAGE,
409        page_id,
410        refs,
411    )
412    .await
413    {
414        tracing::warn!(
415            target: "rustango_cms::task_queue",
416            page_id,
417            error = %e,
418            "inline reference reindex failed",
419        );
420    }
421}
422
423// ---- search-index job (#408 × #432) ------------------------------
424
425/// What a [`SearchIndexJob`] does to a page's search document.
426#[derive(Debug, Clone, Serialize, Deserialize)]
427pub enum SearchIndexAction {
428    /// Upsert the page into the external search index (it's published).
429    Index(crate::search::SearchDoc),
430    /// Remove the page from the index (deleted / unpublished / expired).
431    Delete(i64),
432}
433
434/// Keep an external [`crate::search::SearchBackend`] (Elasticsearch) in
435/// sync with a page change. A no-op at run time when no backend
436/// is installed — the built-in Postgres FTS path queries live data and
437/// needs no index. Retriable: an ES hiccup is retried rather than
438/// silently dropping the update.
439#[derive(Debug, Clone, Serialize, Deserialize)]
440pub struct SearchIndexJob {
441    pub tenant_slug: String,
442    pub action: SearchIndexAction,
443}
444
445#[async_trait]
446impl Job for SearchIndexJob {
447    const NAME: &'static str = "rcms.search_index";
448
449    async fn run(&self) -> Result<(), JobError> {
450        // The backend is a process global; no per-tenant resource
451        // registry needed. No backend installed → nothing to index.
452        let Some(backend) = crate::search::backend() else {
453            return Ok(());
454        };
455        match &self.action {
456            SearchIndexAction::Index(doc) => backend.index(&self.tenant_slug, doc).await,
457            SearchIndexAction::Delete(page_id) => backend.delete(&self.tenant_slug, *page_id).await,
458        }
459        Ok(())
460    }
461}
462
463/// Keep the external search index in step with a saved page: a page in
464/// a public status (published or archived) is indexed, any other
465/// status is removed (so draft / scheduled / expired pages drop out of
466/// search — archived pages now STAY findable). **No-op when no external
467/// [`crate::search::SearchBackend`] is installed** — the Postgres FTS
468/// path needs no maintained index. Dispatched via the queue when a sink
469/// is set, else run inline. Best-effort.
470pub async fn sync_page_search(tenant_slug: &str, page: &crate::page::Page) {
471    if crate::search::backend().is_none() {
472        return;
473    }
474    let Some(page_id) = page.id.get().copied() else {
475        return;
476    };
477    let is_public = page.status == crate::page::PageStatus::Published.as_str()
478        || page.status == crate::page::PageStatus::Archived.as_str();
479    let action = if is_public {
480        SearchIndexAction::Index(crate::search::SearchDoc {
481            page_id,
482            title: page.title.clone(),
483            seo_title: page.seo_title.clone(),
484            seo_description: page.seo_description.clone(),
485            url_path: page.url_path.clone(),
486            status: page.status.clone(),
487        })
488    } else {
489        SearchIndexAction::Delete(page_id)
490    };
491    let job = SearchIndexJob {
492        tenant_slug: tenant_slug.to_owned(),
493        action,
494    };
495    match sink() {
496        Some(s) => {
497            if let Err(e) = s.dispatch_search_index(job.clone()).await {
498                tracing::warn!(
499                    target: "rustango_cms::task_queue",
500                    error = %e,
501                    "search_index dispatch failed; running inline",
502                );
503                job.run().await.log_warn("search index job failed; the index may be stale");
504            }
505        }
506        None => {
507            job.run().await.log_warn("search index job failed; the index may be stale");
508        }
509    }
510}
511
512/// Remove a page from the external search index (on hard delete). No-op
513/// when no backend is installed. Queue-dispatched or inline.
514pub async fn remove_page_search(tenant_slug: &str, page_id: i64) {
515    if crate::search::backend().is_none() {
516        return;
517    }
518    let job = SearchIndexJob {
519        tenant_slug: tenant_slug.to_owned(),
520        action: SearchIndexAction::Delete(page_id),
521    };
522    match sink() {
523        Some(s) => {
524            if s.dispatch_search_index(job.clone()).await.is_err() {
525                job.run().await.log_warn("search index job failed; the index may be stale");
526            }
527        }
528        None => {
529            job.run().await.log_warn("search index job failed; the index may be stale");
530        }
531    }
532}
533
534#[cfg(test)]
535mod tests {
536    use super::*;
537    use std::sync::atomic::{AtomicUsize, Ordering};
538
539    /// Counts how many `invalidate_url` calls it received.
540    struct Counting(Arc<AtomicUsize>);
541
542    #[async_trait]
543    impl PageCacheInvalidator for Counting {
544        async fn invalidate_url(&self, _tenant_slug: &str, _url_path: &str) {
545            self.0.fetch_add(1, Ordering::SeqCst);
546        }
547    }
548
549    #[test]
550    fn job_round_trips_and_has_stable_name() {
551        let job = CachePurgeJob {
552            tenant_slug: "acme".to_owned(),
553            urls: vec!["/a".to_owned(), "/b".to_owned()],
554        };
555        let json = serde_json::to_string(&job).unwrap();
556        let back: CachePurgeJob = serde_json::from_str(&json).unwrap();
557        assert_eq!(back.tenant_slug, "acme");
558        assert_eq!(back.urls, vec!["/a", "/b"]);
559        assert_eq!(CachePurgeJob::NAME, "rcms.cache_purge");
560    }
561
562    #[tokio::test]
563    async fn run_purges_when_invalidator_registered() {
564        let n = Arc::new(AtomicUsize::new(0));
565        register_invalidator("acme-run", Arc::new(Counting(n.clone())));
566        let job = CachePurgeJob {
567            tenant_slug: "acme-run".to_owned(),
568            urls: vec!["/x".to_owned(), "/y".to_owned(), "/z".to_owned()],
569        };
570        assert!(job.run().await.is_ok());
571        assert_eq!(n.load(Ordering::SeqCst), 3);
572    }
573
574    #[tokio::test]
575    async fn run_is_fatal_without_registration() {
576        let job = CachePurgeJob {
577            tenant_slug: "never-registered-tenant".to_owned(),
578            urls: vec!["/x".to_owned()],
579        };
580        match job.run().await {
581            Err(JobError::Fatal(_)) => {}
582            other => panic!("expected Fatal, got {other:?}"),
583        }
584    }
585
586    #[tokio::test]
587    async fn purge_urls_runs_inline_when_no_sink() {
588        // No sink installed in tests → the inline path drives the
589        // in-hand invalidator directly.
590        let n = Arc::new(AtomicUsize::new(0));
591        let inv: Arc<dyn PageCacheInvalidator> = Arc::new(Counting(n.clone()));
592        purge_urls(
593            inv,
594            "acme-inline".to_owned(),
595            vec!["/a".to_owned(), "/b".to_owned()],
596        )
597        .await;
598        assert_eq!(n.load(Ordering::SeqCst), 2);
599        // Empty url list is a no-op.
600        let inv2: Arc<dyn PageCacheInvalidator> = Arc::new(Counting(n.clone()));
601        purge_urls(inv2, "acme-inline".to_owned(), vec![]).await;
602        assert_eq!(n.load(Ordering::SeqCst), 2);
603    }
604
605    #[test]
606    fn owned_ref_round_trips_known_kind_skips_unknown() {
607        use crate::reference_index::{Reference, KIND_MEDIA};
608        let r = Reference {
609            to_kind: KIND_MEDIA,
610            to_id: 7,
611            field_path: "body".to_owned(),
612        };
613        let owned = OwnedRef::from_ref(&r);
614        assert_eq!(owned.to_kind, "cms_media");
615        let back = owned.to_reference().expect("known kind");
616        assert_eq!(back.to_kind, KIND_MEDIA);
617        assert_eq!(back.to_id, 7);
618        // Unknown kind → dropped on rebuild (forward-compat guard).
619        let bogus = OwnedRef {
620            to_kind: "cms_widget".to_owned(),
621            to_id: 1,
622            field_path: "x".to_owned(),
623        };
624        assert!(bogus.to_reference().is_none());
625    }
626
627    #[test]
628    fn reference_index_job_round_trips_and_named() {
629        let job = ReferenceIndexJob {
630            tenant_slug: "acme".to_owned(),
631            page_id: 9,
632            refs: vec![OwnedRef {
633                to_kind: "cms_media".to_owned(),
634                to_id: 3,
635                field_path: "hero".to_owned(),
636            }],
637        };
638        let json = serde_json::to_string(&job).unwrap();
639        let back: ReferenceIndexJob = serde_json::from_str(&json).unwrap();
640        assert_eq!(back.page_id, 9);
641        assert_eq!(back.refs.len(), 1);
642        assert_eq!(ReferenceIndexJob::NAME, "rcms.reference_index");
643    }
644
645    #[tokio::test]
646    async fn reference_index_job_is_fatal_without_pool() {
647        let job = ReferenceIndexJob {
648            tenant_slug: "tenant-with-no-registered-pool".to_owned(),
649            page_id: 1,
650            refs: vec![],
651        };
652        match job.run().await {
653            Err(JobError::Fatal(_)) => {}
654            other => panic!("expected Fatal, got {other:?}"),
655        }
656    }
657
658    #[test]
659    fn search_index_job_round_trips_both_actions() {
660        let idx = SearchIndexJob {
661            tenant_slug: "acme".to_owned(),
662            action: SearchIndexAction::Index(crate::search::SearchDoc {
663                page_id: 5,
664                title: "Hi".to_owned(),
665                seo_title: String::new(),
666                seo_description: String::new(),
667                url_path: "/hi".to_owned(),
668                status: "published".to_owned(),
669            }),
670        };
671        let back: SearchIndexJob =
672            serde_json::from_str(&serde_json::to_string(&idx).unwrap()).unwrap();
673        assert!(matches!(back.action, SearchIndexAction::Index(d) if d.page_id == 5));
674        let del = SearchIndexJob {
675            tenant_slug: "acme".to_owned(),
676            action: SearchIndexAction::Delete(9),
677        };
678        let back2: SearchIndexJob =
679            serde_json::from_str(&serde_json::to_string(&del).unwrap()).unwrap();
680        assert!(matches!(back2.action, SearchIndexAction::Delete(9)));
681        assert_eq!(SearchIndexJob::NAME, "rcms.search_index");
682    }
683
684    #[tokio::test]
685    async fn search_index_job_is_noop_without_backend() {
686        // No SearchBackend installed (the default) → run() succeeds as a
687        // no-op; the Postgres FTS path needs no maintained index.
688        let job = SearchIndexJob {
689            tenant_slug: "acme".to_owned(),
690            action: SearchIndexAction::Delete(1),
691        };
692        assert!(job.run().await.is_ok());
693    }
694}