Skip to main content

Module task_queue

Module task_queue 

Source
Expand description

Pluggable background task queue for CMS heavy work.

Heavy post-request work (cache purge, search/reference indexing, scheduled publish) belongs on a pluggable, retriable queue. The rustango framework already ships the execution machinery — rustango::jobs: a Job trait + a JobQueue with an in-memory backend and a persistent Postgres backend (retry/backoff/dead-letter). This module wires CMS work onto it.

§Why a TaskSink

JobQueue’s methods are generic (dispatch::<T>), so it isn’t object-safe and the framework has no process-global queue — fine for an app that threads its concrete queue around, but a library buried under on_commit can’t reach it. So the CMS keeps a small object-safe TaskSink in a process global. Hosts wrap their concrete queue in JobQueueSink (a blanket adapter) and install it with set_sink.

§Inline default

With no sink installed (the common single-process deploy) the work runs inline (synchronously) — identical to the old detached-spawn behavior, just without retry/persistence.

§Context-free jobs

Job::run receives only its deserialized payload. Tenant-scoped jobs resolve their resources from a process registry (the pattern rustango::email_jobs uses for its mailer): register_invalidator stashes a tenant’s PageCacheInvalidator so a deserialized CachePurgeJob can find it in run().

Structs§

CachePurgeJob
Drop the public-cache entries for urls on one tenant. Enqueued after a page mutation commits. Retriable — a transient backend hiccup is retried with backoff; a missing tenant registration is fatal (a startup-wiring gap, not transient).
JobQueueSink
Adapter: turn any concrete framework JobQueue into a TaskSink. Hosts install it with set_sink(Arc::new(JobQueueSink(queue))).
OwnedRef
Serializable form of crate::reference_index::Reference. The Reference itself can’t be deserialized (its to_kind is a &'static str); the job payload carries owned strings and to_reference maps to_kind back to the interned constant.
ReferenceIndexJob
Rebuild a page’s outbound reference rows. Carries the already-scanned refs in its payload, so run() only needs the tenant pool (resolved from the registry) to replace the rows — retriable if that write hits a transient error.
SearchIndexJob
Keep an external crate::search::SearchBackend (Elasticsearch) in sync with a page change. A no-op at run time when no backend is installed — the built-in Postgres FTS path queries live data and needs no index. Retriable: an ES hiccup is retried rather than silently dropping the update.

Enums§

SearchIndexAction
What a SearchIndexJob does to a page’s search document.

Traits§

TaskSink
Object-safe enqueue surface the CMS holds globally. One method per CMS job kind (the set is small + CMS-owned). Hosts don’t implement this — they wrap their concrete JobQueue in JobQueueSink.

Functions§

default_invalidator
The process-wide invalidator, if one is set — for paths with no admin state of their own, such as MCP tools.
default_mailer
The process-wide mailer and its From: address, if one is set.
purge_urls
Purge urls for tenant. Dispatches a retriable CachePurgeJob when a sink is installed; otherwise purges inline against the in-hand invalidator (today’s behavior). Drive this from the detached on_commit task in crate::cache_invalidate::invalidate_urls_on_commit.
register_cms_jobs
Register every CMS job type on queue. Call once at startup before the queue’s start(); pair with set_sink.
register_invalidator
Stash a tenant’s cache invalidator so a deserialized CachePurgeJob can resolve it in run(). Idempotent. Called automatically by purge_urls from the in-hand invalidator, so hosts don’t normally call it.
register_pool
Stash a tenant’s DB pool so a deserialized ReferenceIndexJob can resolve it in run(). Idempotent. Called automatically by reindex_page from the in-hand pool, so hosts don’t normally call it.
reindex_page
Rebuild page_id’s reference rows from the already-scanned refs. Dispatches a retriable ReferenceIndexJob when a sink is installed; otherwise reindexes inline (today’s behavior). Best-effort — errors are logged, never propagated, so a transient index hiccup can’t block a save.
remove_page_search
Remove a page from the external search index (on hard delete). No-op when no backend is installed. Queue-dispatched or inline.
set_default_invalidator
Set the fallback cache invalidator for queued purge jobs. The first call wins.
set_default_mailer
Set the process-wide mailer. The first call wins.
set_registry
Record the tenant registry pool for resolve_pool’s fallback. Called by crate::seed::ensure_seeded; the first call wins.
set_sink
Install the background task sink. Call once at startup, after register_cms_jobs + the queue’s start(). Without it, CMS background work runs inline.
sync_page_search
Keep the external search index in step with a saved page: a page in a public status (published or archived) is indexed, any other status is removed (so draft / scheduled / expired pages drop out of search — archived pages now STAY findable). No-op when no external crate::search::SearchBackend is installed — the Postgres FTS path needs no maintained index. Dispatched via the queue when a sink is set, else run inline. Best-effort.