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§
- Cache
Purge Job - Drop the public-cache entries for
urlson 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). - JobQueue
Sink - Adapter: turn any concrete framework
JobQueueinto aTaskSink. Hosts install it withset_sink(Arc::new(JobQueueSink(queue))). - Owned
Ref - Serializable form of
crate::reference_index::Reference. TheReferenceitself can’t be deserialized (itsto_kindis a&'static str); the job payload carries owned strings andto_referencemapsto_kindback to the interned constant. - Reference
Index Job - 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. - Search
Index Job - 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§
- Search
Index Action - What a
SearchIndexJobdoes to a page’s search document.
Traits§
- Task
Sink - 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
JobQueueinJobQueueSink.
Functions§
- default_
invalidator - The process-wide invalidator, if one is set — for paths with no admin state of their own, such as MCP tools.
- purge_
urls - Purge
urlsfortenant_slug. Dispatches a retriableCachePurgeJobwhen a sink is installed; otherwise purges inline against the in-handinvalidator(today’s behavior). Drive this from the detachedon_committask incrate::cache_invalidate::invalidate_urls_on_commit. - register_
cms_ jobs - Register every CMS job type on
queue. Call once at startup before the queue’sstart(); pair withset_sink. - register_
invalidator - Stash a tenant’s cache invalidator so a deserialized
CachePurgeJobcan resolve it inrun(). Idempotent. Called automatically bypurge_urlsfrom the in-hand invalidator, so hosts don’t normally call it. - register_
pool - Stash a tenant’s DB pool so a deserialized
ReferenceIndexJobcan resolve it inrun(). Idempotent. Called automatically byreindex_pagefrom the in-hand pool, so hosts don’t normally call it. - reindex_
page - Rebuild
page_id’s reference rows from the already-scannedrefs. Dispatches a retriableReferenceIndexJobwhen 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_
registry - Record the tenant registry pool for
resolve_pool’s fallback. Called bycrate::seed::ensure_seeded; the first call wins. - set_
sink - Install the background task sink. Call once at startup, after
register_cms_jobs+ the queue’sstart(). 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::SearchBackendis installed — the Postgres FTS path needs no maintained index. Dispatched via the queue when a sink is set, else run inline. Best-effort.