Rustango docs
← Anleitungen

Hintergrund-Jobs

Manche Arbeit sollte nicht während eines Requests passieren — eine Willkommens-E-Mail senden, einen Upload skalieren, eine Drittanbieter-API synchronisieren. Es inline zu tun lässt den Benutzer warten und koppelt die Response an einen unzuverlässigen externen Aufruf. Ein Hintergrund-Job verschiebt diese Arbeit auf eine Queue: der Handler kehrt sofort zurück, und ein Pool von Workern führt den Job Augenblicke später aus, mit automatischen Retries und einem Dead-Letter-Pfad für Fehlschläge — eine Task-Queue, vollständig in Rust.

Background jobs in Rustango: a handler dispatches a Job onto a queue, worker tasks run it, retryable failures back off and retry, fatal ones go to a dead-letter handler

Ein Begriff hier neu für dich? Queue, Worker, Retry/Backoff, Dead-Letter — siehe das Glossar.

Quelle: rustango::jobs (Job, JobQueue, InMemoryJobQueue, JobError, JobDeadLetter) und rustango::jobs::DatabaseJobQueue (die tabellengestützte Queue, Alias von pg::PgJobQueue) — hinter der jobs-Feature; DatabaseJobQueue und make:worker brauchen zusätzlich jobs-postgres (beide standardmäßig aktiv).

Ausführbare Version: die In-Memory-, Retry- und Dead-Letter-Snippets sind aus jobs_doc.rs kopiert (cargo test -p rustango --test jobs_doc); die persistente Queue wird per Dogfooding auf SQLite durch jobs_sqlite_live.rs erprobt (cargo test -p rustango --features sqlite,jobs-postgres --test jobs_sqlite_live).

Inhaltsverzeichnis


Schritt 1 — Einen Job definieren

Ein Job ist ein serialisierbares Struct, das Job implementiert. Die Payload ist das, was in die Queue gestellt wird (nach JSON serialisiert); run() ist die Arbeit. NAME routet eine in die Queue gestellte Payload zurück zu ihrem Handler, er muss also eindeutig sein.

Erzeuge ein Gerüst mit der CLI — cargo run -- make:job WelcomeEmail schreibt src/welcome_email.rs; füge pub mod welcome_email; zu src/lib.rs hinzu — oder schreibe es von Hand:

// src/welcome_email.rs
use rustango::jobs::{Job, JobError};
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
pub struct WelcomeEmail {
    pub to: String,
}

#[async_trait::async_trait]   // the scaffolded Cargo.toml has `async-trait`
impl Job for WelcomeEmail {
    const NAME: &'static str = "welcome_email";

    async fn run(&self) -> Result<(), JobError> {
        tracing::info!(to = %self.to, "welcome email job ran");
        Ok(())
    }
}

run() bekommt nur das Payload: keinen Datenbank-Pool, keinen Mailer. Lege also ins Payload, was der Job braucht, etwa die Adresse. Schritt 4 gibt dem Job einen Mailer, damit er wirklich senden kann.

run() gibt zurück:

  • Ok(()) — erledigt.
  • Err(JobError::Retryable(msg)) — transient; der Worker wiederholt mit Backoff.
  • Err(JobError::Fatal(msg)) — permanent; überspringe Retries, Dead-Letter es sofort.

Überschreibe const MAX_ATTEMPTS: u32 = 3; auf dem Impl, um die Obergrenze für Gesamtversuche zu ändern — nicht für Retries. Der Standard 5 bedeutet einen ersten Lauf plus vier Retries; MAX_ATTEMPTS = 3 ergibt zwei Retries. 0 zählt als 1: der Job läuft einmal.

Braucht ein Handler Zustand, den das Payload nicht tragen kann, etwa einen Mailer, registriere ihn mit queue.register_with(move |job: WelcomeEmail| async move { … }). Diese Closure läuft anstelle von Job::run und kann Werte halten, die du in sie verschiebst. Beide eingebauten Queues können das. Schritt 4 zeigt ein vollständiges Beispiel.


Schritt 2 — Eine Queue starten

Für einen einzelnen Prozess (und für Dev und Tests) führt InMemoryJobQueue Jobs auf tokio-Worker-Tasks aus — ohne Datenbank. Registriere jeden Job-Typ, dann start() die Worker (Jobs werden nicht aufgenommen, bis du es tust):

use rustango::jobs::{InMemoryJobQueue, JobQueue};
use std::sync::Arc;

let queue = Arc::new(InMemoryJobQueue::with_workers(4));   // 4 worker tasks
queue.register::<WelcomeEmail>().await;                    // before start/dispatch
queue.start().await;

// ... app runs ...

queue.shutdown().await;   // on shutdown: drain in-flight jobs, then stop

shutdown() gibt laufenden Jobs eine Schonfrist (shutdown_grace, Standard 5s), bricht sie dann ab und stellt sie zurück in die Queue. Wartende Jobs und geparkte Retries bleiben in der Queue, und ein erneutes start() nimmt sie auf.

Jobs sind at-least-once. Ein laufender Job sieht den Stopp über JobCtx::stopping, und ein abgebrochener Job läuft wieder von vorn (die DB-Queue gibt ihre Zeile frei, auch wenn der Job gerade fertig war). Der Abbruch verbraucht einen Versuch. Mache jeden Job idempotent.

Behalte den Arc<InMemoryJobQueue> in deinem App-State, damit Handler ihn erreichen können.

In-Memory bedeutet In-Memory. In der Queue stehende oder in Bearbeitung befindliche Jobs gehen beim Neustart verloren. Für alles, dessen Verlust du dir nicht leisten kannst, verwende die persistente Queue.


Schritt 3 — Aus einem Handler dispatchen

Sobald die Queue läuft, ist das Dispatchen ein einziger Aufruf — er stellt in die Queue und kehrt sofort zurück, sodass der Request nicht auf die Arbeit wartet:

queue.dispatch(&WelcomeEmail { to: "[email protected]".into() }).await?;

Ein Worker nimmt ihn auf und führt run() Augenblicke später aus. Durchgängig verifiziert: alle drei dispatchten Jobs laufen auf den Workern.

for to in ["[email protected]", "[email protected]", "[email protected]"] {
    queue.dispatch(&WelcomeEmail { to: to.into() }).await.unwrap();
}
// → all three WelcomeEmail::run() calls execute on the worker pool

Schritt 4 — In deine App verdrahten

Die Schritte 1–3 zusammengesetzt, für die App aus Erste Schritte: gib dem Job einen Mailer, registriere ihn einmalig beim Boot, starte die Worker, übergib die Queue an eine Route und drain beim Shutdown.

Zuerst die Job-Datei. Sie behält den WelcomeEmail-Job aus Schritt 1 und fügt zwei Dinge hinzu: eine register-Funktion und eine /signup-Route.

// src/welcome_email.rs
use std::sync::Arc;

use axum::{http::StatusCode, routing::post, Extension, Json, Router};
use rustango::email::{BoxedMailer, Email};
use rustango::jobs::{InMemoryJobQueue, Job, JobError, JobQueue};
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
pub struct WelcomeEmail {
    pub to: String,
}

#[async_trait::async_trait]
impl Job for WelcomeEmail {
    const NAME: &'static str = "welcome_email";

    // Not called here: `register` below gives the queue a handler instead.
    async fn run(&self) -> Result<(), JobError> {
        tracing::info!(to = %self.to, "welcome email job ran");
        Ok(())
    }
}

/// Register the job with a handler that holds the mailer. Call it once at
/// boot, before `start()`.
pub async fn register<Q: JobQueue>(queue: &Q, mailer: BoxedMailer) {
    queue
        .register_with(move |job: WelcomeEmail| {
            // The closure runs once per job, so each run takes its own copy.
            let mailer = mailer.clone();
            async move {
                Email::new()
                    .to(job.to)
                    .subject("Welcome")
                    .body("Thanks for signing up.")
                    .send(&*mailer)
                    .await
                    .map_err(|e| {
                        if e.is_retryable() {
                            JobError::Retryable(e.to_string()) // mail server down
                        } else {
                            JobError::Fatal(e.to_string()) // bad address: no retry
                        }
                    })
            }
        })
        .await;
}

#[derive(Deserialize)]
pub struct Signup {
    pub email: String,
}

async fn signup(
    Extension(queue): Extension<Arc<InMemoryJobQueue>>,
    Json(form): Json<Signup>,
) -> StatusCode {
    // ... create the user here ...
    // `dispatch` returns at once; a worker sends the email.
    match queue.dispatch(&WelcomeEmail { to: form.email }).await {
        Ok(()) => StatusCode::CREATED,
        Err(e) => {
            tracing::error!(error = %e, "could not queue the welcome email");
            StatusCode::INTERNAL_SERVER_ERROR
        }
    }
}

pub fn router(queue: Arc<InMemoryJobQueue>) -> Router {
    Router::new()
        .route("/signup", post(signup))
        .layer(Extension(queue))
}

mailer ist ein Arc, also übergibt &*mailer den Mailer darin.

Dann src/main.rs. Das ist die generierte Datei aus Erste Schritte, ergänzt um die Queue. Der Scaffolder legt den Rumpf in run(); die Zeilen kommen dorthin. Die mit NEW markierten Zeilen sind neu — behalte die Admin- und Settings-Zeilen:

// src/main.rs: keep the scaffolded main(), which calls run()
use std::sync::Arc;

use myblog::urls;
use rustango::jobs::{InMemoryJobQueue, JobQueue}; // NEW

async fn run() -> Result<(), Box<dyn std::error::Error>> {
    let _ = dotenvy::dotenv();
    let loaded = rustango::config::Settings::load_from_env();
    let settings = loaded.as_ref().cloned().unwrap_or_default();
    let admin_settings = settings.clone();

    // NEW 1. The mailer, from the [mail] settings (see the email guide).
    let mailer = rustango::email::from_settings(&settings.mail)?;

    // NEW 2. Build the queue and register every job type BEFORE start().
    let queue = Arc::new(InMemoryJobQueue::with_workers(4));
    myblog::welcome_email::register(&*queue, mailer).await;
    queue
        .on_dead_letter(|dl| async move {
            tracing::error!(job = dl.name, attempts = dl.attempts, error = %dl.error,
                            "job dead-lettered");
        })
        .await;

    // NEW 3. Start the workers — tokio tasks that run inside THIS process.
    queue.start().await;
    let draining = Arc::clone(&queue);

    rustango::manage::Cli::new()
        // NEW 4. Mount the /signup route, which holds the queue.
        .api(urls::api().merge(myblog::welcome_email::router(queue)))
        .try_nest_with(urls::admin_prefix(&settings), move |pool| {
            urls::admin_router(pool, &admin_settings)
        })
        .with_health()
        .with_loaded_settings(loaded)
        // NEW 5. Drain the queue after the server stops (SIGINT and SIGTERM).
        .on_shutdown(move || async move { draining.shutdown().await })
        .run()
        .await
}

Probiere es mit cargo run aus, und in einem zweiten Terminal:

curl -X POST http://localhost:8080/signup \
     -H "content-type: application/json" \
     -d '{"email":"[email protected]"}'

Der Request antwortet sofort mit 201. Mit dem Standard-Mail-Backend (Konsole) erscheint die E-Mail einen Moment später im Terminal des Servers.

Um eine Email zu senden, die du im Handler baust, brauchst du keinen eigenen Job-Typ: rustango::email_jobs::register_email_job und dispatch_email erledigen das mit zwei Aufrufen. Siehe Sie außerhalb des Requests versenden.

Den Drain in on_shutdown legen, nicht hinter run(). Frühere Fassungen dieses Beispiels riefen queue.shutdown() in der Zeile nach run() auf, und die konnte nie ausgeführt werden: SIGTERM wurde nirgends behandelt, ein Stopp durch den Orchestrator beendete den Prozess also sofort. run() kehrt jetzt beim Signal zurück — aber on_shutdown bleibt der richtige Ort, weil der Hook auch auf dem Tenancy-Pfad läuft und korrekt gegen den Drain des Servers geordnet ist.

Speichere den konkreten Queue-Typ. Der JobQueue-Trait ist nicht object-safe (seine register/dispatch sind generisch), du kannst also nicht Arc<dyn JobQueue> im State halten — behalte den konkreten Arc<InMemoryJobQueue> (oder Arc<DatabaseJobQueue>).

Ein Job, der die Datenbank liest

In main.rs kann ein Job den Datenbank-Pool des Servers nicht halten. Cli öffnet diesen Pool erst, wenn der Server startet, und das ist nach dem Bau deiner Queue. Du hast zwei Möglichkeiten:

  • Lege die Daten ins Payload, so wie WelcomeEmail die Adresse. Der Handler kann die Datenbank lesen: Eine mit nest_with eingehängte Route bekommt den Pool, wie in Erste Schritte, Schritt 12b.
  • Lass den Job in einem Worker-Prozess laufen. Er öffnet seinen eigenen Pool, und register_with kann den Pool neben dem Mailer halten.

Die Worker laufen lassen (CLI + Produktion)

start() spawnt die Worker als tokio-Tasks innerhalb des aktuellen Prozesses. Wenn du also deine App mit der CLI startest — cargo run (das den Server ausführt) — laufen die Worker direkt daneben. Für die meisten Apps ist das alles, was du brauchst: ein Prozess bedient Requests und leert die Queue; es gibt keinen separaten Worker-Befehl.

cargo run                 # starts the server AND the in-process workers
cargo run -- make:job WelcomeEmail   # scaffold a new job type

Ein dedizierter Worker-Prozess (Produktion)

Im großen Maßstab willst du die Worker oft getrennt von der Web-Ebene — damit ein Traffic-Spike keine Jobs aushungern kann und du beide unabhängig skalierst. Mit der persistenten Queue zieht jeder Prozess aus derselben rustango_jobs-Tabelle, führe also einfach ein zweites, serverloses Binary aus, das die Queue baut, startet und bis zu einem Signal blockiert. cargo run -- make:worker Worker schreibt ein Gerüst. Hier öffnet der Worker seinen eigenen Pool, also kann seine register_with-Closure den Pool und den Mailer halten. Der Job liest das Post-Model aus Erste Schritte:

// src/bin/worker.rs — run with `cargo run --bin worker`
use std::sync::Arc;

use myblog::blog::models::Post;
use myblog::welcome_email::WelcomeEmail;
use rustango::email::Email;
use rustango::jobs::{DatabaseJobQueue, JobError, JobQueue};
use rustango::sql::{FetcherPool, Pool};

#[rustango::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // A worker never runs main.rs, so it loads `.env` and the settings itself.
    let _ = dotenvy::dotenv();
    let settings = rustango::config::Settings::load_from_env()?;
    let mailer = rustango::email::from_settings(&settings.mail)?;
    let pool = Pool::connect_from_env().await?; // DATABASE_URL
    DatabaseJobQueue::ensure_table_pool(&pool).await?;

    let queue = Arc::new(DatabaseJobQueue::with_workers_pool(pool.clone(), 8));
    // Register the SAME job types the web process dispatches.
    queue
        .register_with(move |job: WelcomeEmail| {
            let pool = pool.clone();
            let mailer = mailer.clone();
            async move {
                let posts = Post::objects()
                    .fetch(&pool)
                    .await
                    .map_err(|e| JobError::Retryable(e.to_string()))?;
                Email::new()
                    .to(job.to)
                    .subject("Welcome")
                    .body(format!("There are {} posts waiting for you.", posts.len()))
                    .send(&*mailer)
                    .await
                    .map_err(|e| JobError::Retryable(e.to_string()))
            }
        })
        .await;
    queue.start().await;

    // Blocks until Ctrl-C (SIGINT) *or* SIGTERM. `tokio::signal::ctrl_c()`
    // alone is SIGINT-only on Unix, so a worker waiting on it is killed
    // outright by `docker stop` / a pod eviction and drains nothing.
    rustango::shutdown::shutdown_signal().await;
    queue.shutdown().await;                     // drain in-flight, then exit
    Ok(())
}

Deploye es als eigenen Container/Service und skaliere auf N Replicas — sie ziehen alle sicher aus der geteilten Tabelle. Der Web-Prozess muss dann nur noch dispatch, muss aber jeden Job-Typ, den er sendet, registern (ohne start()), oder seine Queue mit .allow_unregistered_dispatch() bauen; ein nicht registrierter Dispatch wird abgelehnt. Kopple den Worker mit einem periodischen reclaim_stuck_jobs_pool-Sweep, um Jobs eines abgestürzten Workers zurückzuholen.

Zwei verschiedene Queues auf einer Tabelle (etwa ein Mailer und ein Report-Runner mit eigenen Handlern) greifen sich gegenseitig die Jobs. Gib jeder mit .queue_name("mailer") auf der dispatchenden und der arbeitenden Seite einen eigenen Namen: Eine benannte Queue führt nur ihre Jobs aus, eine unbenannte nur unbenannte Jobs. Worker von vor queue_name ignorieren es und führen auch benannte Jobs aus: Stoppe sie, bevor du auf eine benannte Queue dispatchst.


Retries und Backoff

Ein Job, der Retryable zurückgibt, wird mit exponentiellem Backoff (1s, 2s, 4s, 8s, …, gedeckelt bei 1024s) erneut in die Queue gestellt, bis MAX_ATTEMPTS Gesamtversuche aufgebraucht sind. Verwende es für transiente Fehler — einen Timeout, eine rate-limitierte API, einen Deadlock:

#[async_trait::async_trait]
impl Job for FlakyImport {
    const NAME: &'static str = "flaky_import";
    async fn run(&self) -> Result<(), JobError> {
        match call_external_api().await {
            Ok(_)  => Ok(()),
            Err(e) => Err(JobError::Retryable(e.to_string())),   // try again later
        }
    }
}

Der zugrunde liegende Test dispatcht einen Job, der einmal fehlschlägt und dann gelingt, und stellt sicher, dass er mehr als einmal lief und schließlich gelang — das Retry findet tatsächlich statt.

Um die Wartezeit für jeden Job eines Typs zu ändern, überschreibe fn retry_backoff(failed_attempt: u32) -> Duration im Impl (failed_attempt ist 0 nach dem ersten Lauf). Um die Obergrenze oder die Wartezeit aus dem Payload zu setzen, überschreibe fn max_attempts(&self) -> u32 oder fn retry_delay(&self, failed_attempt: u32) -> Duration; standardmäßig liefern sie MAX_ATTEMPTS und retry_backoff. Die Obergrenze wird beim Dispatch gelesen. jobs::exponential_backoff(base, failed_attempt) ist die Standardkurve mit eigener Basis: base, pro Fehlschlag verdoppelt, gedeckelt bei base · 1024.


Der Job-Kontext: ID, Versuch, Stopp

Beide Queues rufen Job::run_with(&self, ctx: &JobCtx) auf. Standardmäßig ruft es run() auf, also laufen Jobs, die nur run implementieren, unverändert. Überschreibe es, um Folgendes zu lesen:

  • ctx.id() — die ID des Jobs, bei jedem Retry dieselbe. Nur in ihrer Queue eindeutig.
  • ctx.idempotency_key(scope) — die ID unter deinem Scope, für ein externes System.
  • ctx.attempt() — 1 beim ersten Lauf, 2 beim ersten Retry.
  • ctx.stopping() / ctx.is_stopping() — die Queue fährt herunter; beende den Job innerhalb von shutdown_grace, sonst wird der Lauf abgebrochen und neu eingereiht.

Nutze idempotency_key als Schlüssel für ein externes System, damit eine wiederholte Abbuchung nicht doppelt abbucht. Die ID der Datenbank-Queue ist die Zeilen-ID plus ihr Einreihungszeitpunkt, eine neu angelegte Tabelle wiederholt sie also nicht. Tenants mit eigener Job-Tabelle beginnen trotzdem bei Zeile 1; übergib daher einen Scope, der die Tabellen unterscheidet, etwa den Tenant-Slug:

use rustango::jobs::{Job, JobCtx, JobError};

#[async_trait::async_trait]
impl Job for ChargeCard {
    const NAME: &'static str = "charge_card";

    async fn run(&self) -> Result<(), JobError> {
        Err(JobError::Fatal("ChargeCard runs through run_with".into()))
    }

    async fn run_with(&self, ctx: &JobCtx) -> Result<(), JobError> {
        let key = ctx.idempotency_key(&self.tenant);   // bei jedem Retry derselbe Schlüssel
        stripe_charge(self.order_id, self.cents, &key)
            .await
            .map_err(|e| JobError::Retryable(e.to_string()))
    }
}

Ein Handler, der an register_with übergeben wird, bekommt nur den Payload, nicht den Kontext.


Der Dead-Letter-Handler

Wenn ein Job seine Retries erschöpft — oder sofort Fatal zurückgibt — wird er an den Dead-Letter-Callback übergeben, statt zu verschwinden. Registriere einen (vor start), um den Fehlschlag zu loggen, zu alarmieren oder zu persistieren:

queue
    .on_dead_letter(|dl| async move {
        // dl: JobDeadLetter { name, payload, attempts, error }
        tracing::error!(job = dl.name, attempts = dl.attempts, error = %dl.error,
                        "job dead-lettered");
    })
    .await;

Ein Fatal-Fehler überspringt Retries und landet hier beim ersten Versuch:

async fn run(&self) -> Result<(), JobError> {
    Err(JobError::Fatal("unprocessable payload".into()))   // → dead-letter now
}

Der Test bestätigt, dass der Callback für einen Fatal-Job genau einmal feuert, mit intaktem name und error des Jobs.


Die persistente Queue (Produktion)

InMemoryJobQueue ist Einzelprozess und vergisst beim Neustart. Für echte Deployments — mehrere Worker, mehrere Replicas, Jobs, die einen Absturz überstehen müssen — verwende DatabaseJobQueue (derselbe Typ wie PgJobQueue). Jobs leben in einer rustango_jobs-Tabelle; Worker nehmen sie innerhalb einer Transaktion auf (FOR UPDATE SKIP LOCKED auf PostgreSQL und MySQL, ein einzelnes UPDATE … RETURNING auf SQLite), es ist also über Prozesse hinweg sicher. Sie ist tri-dialektisch (PostgreSQL, MySQL, SQLite). Die Job-Definitionen aus Schritt 1 bleiben unverändert.

use rustango::jobs::DatabaseJobQueue;   // = rustango::jobs::pg::PgJobQueue
use rustango::jobs::JobQueue;
use std::sync::Arc;
use std::time::Duration;

// 1. Create the jobs table once at boot (idempotent, tri-dialect).
DatabaseJobQueue::ensure_table_pool(&pool).await?;

// 2. Build the queue over your pool + N workers, and start it.
let queue = Arc::new(
    DatabaseJobQueue::with_workers_pool(pool.clone(), 4)
        .poll_interval(Duration::from_millis(50)),
);
queue.register::<WelcomeEmail>().await;
queue.start().await;

// 3. Dispatch exactly as before — now it's durable.
queue.dispatch(&WelcomeEmail { to: "[email protected]".into() }).await?;

Dispatch innerhalb einer Transaktion. Innerhalb eines atomic-Blocks auf dem eigenen Pool der Queue tritt dispatch dem Block bei: Der Job wird mit ihm zurückgerollt, und kein Worker wacht vor dem Commit auf. Halte den TxGuard des Blocks nicht über den Aufruf hinweg.

Abgestürzte Worker wiederherstellen. Stirbt ein Worker mitten im Job, bleibt die Zeile gesperrt. Führe einen periodischen Sweep aus, um Sperren älter als eine Schwelle freizugeben, damit ein anderer Worker den Job wieder aufnimmt:

// e.g. from a scheduled task every few minutes:
let reclaimed = DatabaseJobQueue::reclaim_stuck_jobs_pool(&pool, Duration::from_secs(300)).await?;

Oder die Queue erledigt es: .reclaim_stuck_after(Duration::from_secs(300)) am Builder fegt den eigenen Pool der Queue beim start und danach alle min(Schwelle, 60s). Standardmäßig aus; die Schwelle wird auf mindestens drei Heartbeats angehoben.

Ein laufender Job erneuert seine Sperre alle heartbeat_interval (Standard 10 s), halte die Schwelle also deutlich darüber. Jede Aufnahme verbraucht einen Versuch, ein Job, der seinen Worker abstürzen lässt, landet also im Dead-Letter, sobald MAX_ATTEMPTS Läufe verbraucht sind. Ein Job, der paniert, ist ein Retryable-Fehlschlag; der Worker läuft weiter.

Sowohl der Dispatch-and-Run-Fluss als auch reclaim_stuck_jobs_pool werden per Dogfooding gegen SQLite in jobs_sqlite_live.rs erprobt.


Jobs unter Multi-Tenancy

Ein Worker ist kein Request. Nichts hat für ihn einen Tenant aufgelöst — kein Host, kein Header, keine Middleware lief — also trägt ein Job keinen Tenant-Kontext: run(&self) erhält nur das deserialisierte Payload. Die Isolation kommt aus dem Pool, auf dem die Queue gebaut wurde, und daraus folgt die Regel:

Eine Queue pro Tenant-Pool. Eine Tenant-Id im Payload ist Routing, keine Isolation.

Diese eine Entscheidung ist es, die jeden Modus sicher macht:

ModusWo rustango_jobs liegtWarum ein Worker gescoped bleibt
databasein der eigenen Datenbank / SQLite-Datei des Tenantsdie Zeilen eines anderen Tenants stehen nicht in der Tabelle, die der Worker abfragt — Cross-Tenant-Lesezugriffe sind nicht ausdrückbar
schema (PG)im Schema des Tenantsscoped_pool_dyn liefert einen Pool, in dessen Connect-Options search_path eingebacken ist, statt eines SET pro Request — jeder Checkout ist also für die gesamte Lebensdauer des Pools gescoped, auch bei einem Worker, der tagelang läuft

Baue die Queues beim Boot, eine pro aktivem Tenant:

use rustango::core::Column as _;
use rustango::jobs::{DatabaseJobQueue, JobQueue};
use rustango::sql::FetcherPool as _;
use rustango::tenancy::{Org, TenantPools};
use std::sync::Arc;
use std::time::Duration;

let pools = Arc::new(TenantPools::new(registry));
let registry_pool = pools.registry_pool();

// The registry holds the tenant list; each `Org` names its own
// database (or PG schema).
let orgs: Vec<Org> = Org::objects()
    .where_(Org::active.eq(true))
    .fetch(&registry_pool)
    .await?;

let mut queues = Vec::new();
for org in orgs {
    let pool = pools.scoped_pool_dyn(&org).await?;   // scoped for its lifetime
    DatabaseJobQueue::ensure_table_pool(&pool).await?;

    let queue = Arc::new(
        DatabaseJobQueue::with_workers_pool(pool, 2)
            .poll_interval(Duration::from_secs(1)),
    );
    queue.register::<WelcomeEmail>().await;
    queue.start().await;
    queues.push((org.slug, queue));
}

Der Dispatch geht dann an die Queue dieses Tenants — in einem Request-Handler an die, die unter dem Org liegt, das der Resolver schon erzeugt hat.

Was man nicht tun sollte. Eine Queue auf dem Registry-Pool mit einem org_id-Feld im Payload legt die Jobs aller Tenants in eine gemeinsame Tabelle und überlässt es jedem run(), sich ans Re-Scoping zu erinnern. Ein einziges vergessenes Re-Scoping ist ein Cross-Tenant-Write. Wenn du aus betrieblichen Gründen eine gemeinsame Queue brauchst, löse den Tenant-Pool als erstes in run() auf und fasse den Registry-Pool danach nicht mehr an.

Bekannte Grenzen. Das Framework übernimmt den Fan-out nicht für dich: es gibt keinen Worker-Supervisor pro Tenant, kein Job::run(&ctx) mit angehängtem Tenant und keinen Tenant-bewussten reclaim_stuck_jobs_pool-Sweep — du iterierst selbst über die Tenants, wie oben (.reclaim_stuck_after(..) an der Queue jedes Tenants fegt den Pool dieses Tenants). Tenants, die nach dem Boot provisioniert werden, bekommen bis zum Prozess-Neustart keine Worker. Das ist eine bekannte Lücke.

Ambienter Kontext: nur Audit-Quelle und Zeitzone. InMemoryJobQueue erfasst sie bei dispatch, der Scheduler bei every(), und beide setzen sie um den Lauf wieder ein. PgJobQueue speichert sie in rustango_jobs.context; ensure_table_pool fügt die Spalte einer älteren Tabelle hinzu. Ohne die Spalte laufen Jobs als AuditSource::System. Keine Queue trägt eine Session oder einen Tenant.

Eine Quelle aus dem Tenant-Admin nennt einen Benutzer dieses Tenants. Sie wird nur bei Schreibvorgängen über den Pool erfasst, den tenancy::with_tenant (oder for_each_tenant) für diesen Tenant übergibt. Andere Schreibvorgänge, auch über einen anderen Pool darin, erfassen system:

rustango::tenancy::with_tenant(&pools, &org, |pool| async move {
    note.insert(&pool).await
})
.await??;

Geplante Sweeps unter Multi-Tenancy

Dasselbe „ein Worker ist kein Request"-Problem trifft auch zeitbasierte Arbeit, und die Sweep-Helfer des Frameworks sind die Stelle, an der es beißt: MediaManager::purge_orphans, audit::cleanup_older_than_pool und prunable::prune_all nehmen jeweils einen Pool, und jede Tabelle, die sie anfassen, ist pro Tenant. Ein Pool heißt ein Tenant — und ein Registry-Pool im Schema-Modus heißt nur public, während die Zeilen jedes Tenants anwachsen und der Sweep trotzdem Erfolg meldet.

Mach den Fan-out mit for_each_tenant: es löst für jeden aktiven Tenant dessen eigenen Pool auf und macht weiter, wenn ein Tenant scheitert:

use rustango::tenancy::for_each_tenant;

let opts = &opts;
let sweep = for_each_tenant(&pools, move |_org, pool| async move {
    rustango::prunable::prune_all(&pool, opts).await
})
.await?;

tracing::info!(ok = sweep.succeeded(), failed = sweep.failed(), "nightly prune");
for (slug, err) in sweep.errors() {
    tracing::warn!(%slug, %err, "tenant prune failed");
}

Ein kaputter Tenant — rotiertes Credential, nicht erreichbare Datenbank — landet im Report, statt den Lauf abzubrechen, und kann so die Tenants danach nicht aushungern. Inaktive Orgs werden übersprungen. purge_orphans ist der eine Sweep, der über die Datenbank hinausgreift (er löscht Storage-Objekte), darum gibt es purge_orphans_dry_run: dieselbe Query, löscht nichts — ein Blick darauf lohnt sich, bevor du das echte Ding verdrahtest.

Wenn du den Sweep so absicherst, dass nur eine Replica ihn ausführt, dann scope das Lock pro Tenant:

use rustango::cache::CacheScope;

let tenant = TenantSlug::of(&org).expect("a registry org");
let lock = CacheScope::for_tenant(cache.clone(), &tenant).locks();
// Tick every minute; this runs once per UTC day across replicas.
lock.once_per_period("nightly_prune", day, || prune(&org)).await;

Ungescoped konkurrieren alle Tenants um dasselbe lock:nightly_prune: der erste Tenant gewinnt, die übrigen werden für die gesamte TTL übersprungen — und zwar still, denn ein abgelehntes Acquire ist das erwartete Ergebnis, es wird nichts geloggt. Das ist eine bekannte Lücke.


Referenz

Backends

BackendVerwenden fürÜbersteht Neustart?
InMemoryJobQueueEinzelprozess, Dev, Testsnein
DatabaseJobQueue (PgJobQueue)Produktion; Multi-Worker / Multi-Replicaja (rustango_jobs-Tabelle)

JobError

VarianteWirkung
Retryable(String)erneut in die Queue mit exponentiellem Backoff, bis zu MAX_ATTEMPTS
Fatal(String)Retries überspringen → sofort Dead-Letter
Queue(String)interner Queue-Fehler (Serialisierung/Registrierung)

JobQueue-Methoden: register::<T>() · dispatch(&payload) · start() · register_with::<T, _, _>(handler) · shutdown() · pending_count() (Jobs, die auf Aufnahme warten). Job::run_with bekommt einen JobCtx (id, attempt, stopping). Beide Queues haben on_dead_letter und shutdown_grace. DatabaseJobQueue ergänzt ensure_table_pool, with_workers_pool, new_pool, poll_interval, heartbeat_interval, queue_name, reclaim_stuck_after und reclaim_stuck_jobs_pool. jobs::inmemory_from_settings(&settings.jobs) baut eine InMemoryJobQueue mit [jobs] concurrency Workern (Standard 4).


Siehe auch

  • Scheduler — für zeitbasierte wiederkehrende Arbeit in festem Intervall (Scheduler::every + Duration; keine Cron-Ausdrücke), im Gegensatz zu On-Demand-Jobs.
  • E-Mail — die kanonische „mach es in einem Job"-Workload.
  • Caching — der andere Weg, Request-Handler schnell zu halten.
  • Signals — Fire-and-Forget-Hooks, die oft einen Job dispatchen.
  • Tenancy-Befehle — das Provisionieren der Tenants, über die eine Queue pro Tenant fan-out macht.