Rustango docs
← Guías

Trabajos en segundo plano

Cierto trabajo no debería suceder durante una petición — enviar un correo de bienvenida, redimensionar una subida, sincronizar una API de terceros. Hacerlo en línea hace esperar al usuario y acopla la respuesta a una llamada externa poco fiable. Un trabajo en segundo plano mueve ese trabajo a una cola: el handler retorna de inmediato, y un pool de workers ejecuta el trabajo momentos después, con reintentos automáticos y una ruta dead-letter para los fallos — una cola de tareas, íntegramente en 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

¿Un término nuevo aquí? cola, worker, reintento/backoff, dead-letter — ver el glosario.

Fuente: rustango::jobs (Job, JobQueue, InMemoryJobQueue, JobError, JobDeadLetter) y rustango::jobs::DatabaseJobQueue (la cola respaldada por tabla, alias de pg::PgJobQueue) — tras la feature jobs; DatabaseJobQueue y make:worker necesitan además jobs-postgres (ambas activas por defecto).

Versión ejecutable: los fragmentos in-memory, de reintento y de dead-letter están copiados de jobs_doc.rs (cargo test -p rustango --test jobs_doc); la cola persistente se prueba con dogfooding sobre SQLite mediante jobs_sqlite_live.rs (cargo test -p rustango --features sqlite,jobs-postgres --test jobs_sqlite_live).

Tabla de contenidos


Paso 1 — Definir un trabajo

Un trabajo es una struct serializable que implementa Job. El payload es lo que se encola (serializado a JSON); run() es el trabajo. NAME enruta un payload encolado de vuelta a su handler, así que debe ser único.

Genera un esqueleto con la CLI — cargo run -- make:job WelcomeEmail escribe src/welcome_email.rs; añade pub mod welcome_email; a src/lib.rs — o escríbelo a mano:

// 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() recibe solo el payload: ni pool de base de datos ni mailer. Así que pon en el payload lo que el trabajo necesita, como la dirección. El Paso 4 le da al trabajo un mailer para que pueda enviar de verdad.

run() retorna:

  • Ok(()) — hecho.
  • Err(JobError::Retryable(msg)) — transitorio; el worker reintenta con backoff.
  • Err(JobError::Fatal(msg)) — permanente; omite reintentos, dead-letter inmediato.

Sobrescribe const MAX_ATTEMPTS: u32 = 3; en la impl para cambiar el tope de intentos totales — no de reintentos. El valor por defecto de 5 es una ejecución inicial más cuatro reintentos; MAX_ATTEMPTS = 3 da dos reintentos. 0 cuenta como 1: el trabajo se ejecuta una vez.

Un handler que necesita estado que el payload no puede llevar, como un mailer, se registra con queue.register_with(move |job: WelcomeEmail| async move { … }). Esa closure se ejecuta en lugar de Job::run y puede guardar valores que muevas a ella. Ambas colas incluidas lo admiten. El Paso 4 muestra uno completo.


Paso 2 — Iniciar una cola

Para un único proceso (y para dev y tests), InMemoryJobQueue ejecuta los trabajos en tareas worker de tokio — sin base de datos. Registra cada tipo de trabajo, luego start() los workers (los trabajos no se recogen hasta que lo hagas):

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() da a los trabajos en curso un periodo de gracia (shutdown_grace, 5 s por defecto), y luego los aborta y los vuelve a encolar. Los trabajos en cola y los reintentos aparcados siguen en cola, y un nuevo start() los recoge.

Los trabajos son at-least-once. Un trabajo en curso ve la parada con JobCtx::stopping, y un trabajo abortado vuelve a ejecutarse desde el principio (la cola en BD libera su fila aunque el trabajo acabara de terminar). El aborto gasta un intento. Haz que cada trabajo sea idempotente.

Mantén el Arc<InMemoryJobQueue> en el estado de tu aplicación para que los handlers puedan alcanzarlo.

In-memory significa in-memory. Los trabajos encolados o en curso se pierden al reiniciar. Para todo lo que no puedas permitirte perder, usa la cola persistente.


Paso 3 — Despachar desde un handler

Una vez la cola está en marcha, despachar es una sola llamada — encola y retorna de inmediato, así que la petición no espera al trabajo:

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

Un worker lo recoge y ejecuta run() momentos después. Verificado de extremo a extremo: los tres trabajos despachados se ejecutan todos en los workers.

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

Paso 4 — Cablearlo en tu aplicación

Juntando los pasos 1–3 para la aplicación de Primeros pasos: dale al trabajo un mailer, regístralo una sola vez en el arranque, inicia los workers, entrega la cola a una ruta y drena al apagar.

Primero el archivo del trabajo. Conserva el trabajo WelcomeEmail del Paso 1 y añade dos cosas: una función register y una ruta /signup.

// 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 es un Arc, así que &*mailer pasa el mailer que lleva dentro.

Luego src/main.rs. Es el archivo generado de Primeros pasos, con la cola añadida. El scaffolder pone el cuerpo en run(); las líneas van ahí. Las líneas marcadas con NEW son las nuevas — conserva las líneas del admin y de los ajustes:

// 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
}

Pruébalo con cargo run y, en otra terminal:

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

La petición responde 201 al momento. Con el backend de correo por defecto (la consola), el correo aparece en la terminal del servidor un instante después.

Para enviar un Email que construyes en el handler no necesitas tu propio tipo de trabajo: rustango::email_jobs::register_email_job y dispatch_email lo hacen en dos llamadas. Mira Envíalo fuera de la petición.

Pon el drenaje en on_shutdown, no después de run(). Las versiones anteriores de este ejemplo llamaban a queue.shutdown() en la línea posterior a run(), y esa línea no podía ejecutarse nunca: nada manejaba SIGTERM, así que la parada del orquestador mataba el proceso de inmediato. Ahora run() retorna con la señal — pero on_shutdown sigue siendo el lugar correcto, porque también se ejecuta en la ruta de tenancy y se ordena bien respecto al drenaje del servidor.

Almacena el tipo de cola concreto. El trait JobQueue no es object-safe (sus register/dispatch son genéricos), así que no puedes mantener Arc<dyn JobQueue> en el estado — conserva el Arc<InMemoryJobQueue> concreto (o Arc<DatabaseJobQueue>).

Un trabajo que lee la base de datos

En main.rs un trabajo no puede guardar el pool de base de datos del servidor. Cli abre ese pool cuando arranca el servidor, y eso ocurre después de construir tu cola. Tienes dos opciones:

  • Pon los datos en el payload, como hace WelcomeEmail con la dirección. El handler sí puede leer la base de datos: una ruta montada con nest_with recibe el pool, como en Primeros pasos, Paso 12b.
  • Ejecuta el trabajo en un proceso worker. Abre su propio pool, y register_with puede guardar el pool junto al mailer.

Ejecutar los workers (CLI + producción)

start() lanza los workers como tareas de tokio dentro del proceso actual. Así que cuando arrancas tu aplicación con la CLI — cargo run (que ejecuta el servidor) — los workers corren justo a su lado. Para la mayoría de las aplicaciones eso es todo lo que necesitas: un proceso sirve peticiones y drena la cola; no hay un comando worker aparte.

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

Un proceso worker dedicado (producción)

A escala, a menudo quieres los workers separados del nivel web — para que un pico de tráfico no pueda dejar sin recursos a los trabajos, y para escalar cada uno de forma independiente. Con la cola persistente cada proceso extrae de la misma tabla rustango_jobs, así que simplemente ejecuta un segundo binario, sin servidor, que construye la cola, la inicia y bloquea hasta una señal. cargo run -- make:worker Worker escribe un esqueleto. Aquí el worker abre su propio pool, así que su closure de register_with puede guardar el pool y el mailer. El trabajo lee el modelo Post de Primeros pasos:

// 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(())
}

Despliégalo como su propio contenedor/servicio y escálalo a N réplicas — todas extraen de la tabla compartida de forma segura. El proceso web entonces solo necesita dispatch, pero debe register cada tipo de job que despacha (sin start()), o construir su cola con .allow_unregistered_dispatch(); un dispatch no registrado se rechaza. Empareja el worker con un barrido periódico reclaim_stuck_jobs_pool para recuperar trabajos de un worker que se ha caído.

Dos colas distintas sobre una tabla (por ejemplo, un mailer y un generador de informes con sus propios handlers) se quitan los trabajos entre sí. Da a cada una su nombre con .queue_name("mailer") en el lado que despacha y en el que trabaja: una cola con nombre solo ejecuta sus trabajos, y una sin nombre solo los trabajos sin nombre. Los workers anteriores a queue_name lo ignoran y ejecutan también los trabajos con nombre: detenlos antes de despachar en una cola con nombre.


Reintentos y backoff

Un trabajo que retorna Retryable se reencola con backoff exponencial (1s, 2s, 4s, 8s, …, con tope en 1024s) hasta agotar MAX_ATTEMPTS intentos totales. Úsalo para fallos transitorios — un timeout, una API con límite de tasa, un 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
        }
    }
}

El test que lo respalda despacha un trabajo que falla una vez y luego tiene éxito, y afirma que se ejecutó más de una vez y finalmente tuvo éxito — el reintento realmente ocurre.

Para cambiar la espera de todos los trabajos de un tipo, sobrescribe fn retry_backoff(failed_attempt: u32) -> Duration en el impl (failed_attempt vale 0 tras la primera ejecución). Para fijar el límite o la espera a partir del payload, sobrescribe fn max_attempts(&self) -> u32 o fn retry_delay(&self, failed_attempt: u32) -> Duration; por defecto devuelven MAX_ATTEMPTS y retry_backoff. El límite se lee al despachar. jobs::exponential_backoff(base, failed_attempt) es la curva por defecto con tu propia base: base, doblada por cada fallo, con tope en base · 1024.


El contexto del trabajo: id, intento, parada

Ambas colas llaman a Job::run_with(&self, ctx: &JobCtx). Por defecto llama a run(), así que los trabajos que solo implementan run funcionan sin cambios. Sobrescríbelo para leer:

  • ctx.id() — el id del trabajo, el mismo en cada reintento. Único solo en su cola.
  • ctx.idempotency_key(scope) — el id bajo tu ámbito, para un sistema externo.
  • ctx.attempt() — 1 en la primera ejecución, 2 en el primer reintento.
  • ctx.stopping() / ctx.is_stopping() — la cola se está deteniendo; termina dentro de shutdown_grace o la ejecución se aborta y vuelve a la cola.

Usa idempotency_key como la clave que ve un sistema externo, para que un cobro reintentado no se cobre dos veces. El id de la cola en BD es el id de la fila más su momento de encolado, así que una tabla recreada no lo repite. Los tenants con su propia tabla de trabajos empiezan igualmente en la fila 1; pasa un ámbito que distinga las tablas, como el slug del tenant:

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);   // la misma clave en cada reintento
        stripe_charge(self.order_id, self.cents, &key)
            .await
            .map_err(|e| JobError::Retryable(e.to_string()))
    }
}

Un handler pasado a register_with recibe solo el payload, no el contexto.


El handler dead-letter

Cuando un trabajo agota sus reintentos — o retorna Fatal de inmediato — se entrega al callback dead-letter en lugar de desvanecerse. Registra uno (antes de start) para registrar, alertar o persistir el fallo:

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;

Un error Fatal omite los reintentos y aterriza aquí en el primer intento:

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

El test confirma que el callback se dispara exactamente una vez para un trabajo Fatal, con el name y el error del trabajo intactos.


La cola persistente (producción)

InMemoryJobQueue es de un solo proceso y olvida al reiniciar. Para despliegues reales — múltiples workers, múltiples réplicas, trabajos que deben sobrevivir a una caída — usa DatabaseJobQueue (el mismo tipo que PgJobQueue). Los trabajos viven en una tabla rustango_jobs; los workers reservan una fila dentro de una transacción (FOR UPDATE SKIP LOCKED en PostgreSQL y MySQL, un solo UPDATE … RETURNING en SQLite), así que es seguro entre procesos. Es tri-dialecto (PostgreSQL, MySQL, SQLite). Las definiciones Job del paso 1 no cambian.

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?;

Despachar dentro de una transacción. Dentro de un bloque atomic sobre el propio pool de la cola, dispatch se une al bloque: el trabajo se revierte con él, y ningún worker despierta antes del commit. No mantengas el TxGuard del bloque durante la llamada.

Recuperar workers caídos. Si un worker muere a mitad de un trabajo, la fila queda bloqueada. Ejecuta un barrido periódico para liberar los bloqueos más antiguos que un umbral, de modo que otro worker retome el trabajo:

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

O deja que lo haga la cola: .reclaim_stuck_after(Duration::from_secs(300)) en el builder barre el pool de la cola al hacer start y luego cada min(umbral, 60s). Está apagado por defecto, y el umbral se eleva al menos a tres heartbeats.

Un trabajo en curso renueva su bloqueo cada heartbeat_interval (10 s por defecto), así que mantén el umbral muy por encima. Cada recogida gasta un intento, así que un trabajo que tumba a su worker va a dead-letter cuando se agotan las MAX_ATTEMPTS ejecuciones. Un trabajo que hace panic es un fallo Retryable; el worker sigue funcionando.

Tanto el flujo dispatch-and-run como reclaim_stuck_jobs_pool se prueban con dogfooding contra SQLite en jobs_sqlite_live.rs.


Trabajos con multi-tenancy

Un worker no es un request. Nada resolvió un tenant para él — ningún host, ninguna cabecera, ningún middleware se ejecutó — así que un trabajo no lleva contexto de tenant: run(&self) solo recibe el payload deserializado. El aislamiento viene del pool sobre el que se construyó la cola, y de ahí sale la regla:

Una cola por pool de tenant. Un id de tenant en el payload es enrutado, no aislamiento.

Esa única decisión es la que hace seguro cada modo:

ModoDónde vive rustango_jobsPor qué un worker permanece acotado
databasedentro de la propia base de datos / archivo SQLite del tenantlas filas de otro tenant no están en la tabla que consulta el worker — las lecturas entre tenants no son expresables
schema (PG)en el esquema del tenantscoped_pool_dyn devuelve un pool con search_path incorporado en sus connect options, no un SET por request — así cada checkout queda acotado durante toda la vida del pool, incluido un worker que viva días

Construye las colas en el arranque, una por tenant activo:

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));
}

El despacho va entonces a la cola de ese tenant — en un handler de request, a la que está indexada por el Org que el resolver ya produjo.

Qué no hacer. Una sola cola sobre el pool del registry con un campo org_id en el payload pone los trabajos de todos los tenants en una tabla compartida, y deja a cada run() la tarea de acordarse de reacotar. Un solo reacotado olvidado es una escritura entre tenants. Si necesitas una cola compartida por razones operativas, resuelve el pool del tenant como lo primero que hace run() y no vuelvas a tocar el pool del registry después.

Límites conocidos. El framework no hace el fan-out por ti: no hay supervisor de workers por tenant, ni Job::run(&ctx) con el tenant adjunto, ni un barrido reclaim_stuck_jobs_pool consciente del tenant — iteras sobre los tenants tú mismo, como arriba (.reclaim_stuck_after(..) en la cola de cada tenant barre el pool de ese tenant). Los tenants provisionados después del arranque no obtienen workers hasta que el proceso se reinicia. Es una carencia conocida.

Contexto ambiental: solo fuente de auditoría y zona horaria. InMemoryJobQueue los captura en dispatch y el scheduler en every(), y ambos los reinstalan alrededor de la ejecución. PgJobQueue los guarda en rustango_jobs.context; ensure_table_pool añade la columna a una tabla antigua. Sin la columna, los trabajos corren como AuditSource::System. Ninguna cola lleva sesión ni tenant.

Una fuente del admin del tenant nombra a un usuario de ese tenant, así que solo se registra en escrituras por el pool que tenancy::with_tenant (o for_each_tenant) entrega para ese tenant. Las demás escrituras, también las hechas por otro pool dentro, registran system:

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

Barridos programados con multi-tenancy

El mismo problema de «un worker no es un request» golpea al trabajo basado en el tiempo, y los propios helpers de barrido del framework son donde muerde: MediaManager::purge_orphans, audit::cleanup_older_than_pool y prunable::prune_all toman un solo pool, y cada tabla que tocan es por tenant. Un pool significa un tenant — y un pool del registry en modo esquema significa solo public, mientras las filas de cada tenant se acumulan y el barrido igual informa éxito.

Haz el fan-out con for_each_tenant, que resuelve el pool propio de cada tenant activo y sigue adelante cuando uno falla:

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");
}

Un tenant roto — credencial rotada, base de datos inalcanzable — queda registrado en el informe en lugar de abortar la ejecución, de modo que no puede dejar sin barrer a los tenants que van después. Las orgs inactivas se omiten. purge_orphans es el único barrido que sale de la base de datos (borra objetos de almacenamiento), así que tiene purge_orphans_dry_run: la misma consulta, sin borrar nada — vale la pena mirarlo antes de cablear el barrido real.

Si proteges el barrido para que solo una réplica lo ejecute, acota el lock por 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;

Sin acotar, todos los tenants compiten por un único lock:nightly_prune: el primero gana y el resto se omite durante toda la TTL, en silencio — un acquire rechazado es el resultado esperado, así que no se registra nada. Es una carencia conocida.


Referencia

Backends

BackendUsar para¿Sobrevive al reinicio?
InMemoryJobQueueun solo proceso, dev, testsno
DatabaseJobQueue (PgJobQueue)producción; multi-worker / multi-réplicasí (tabla rustango_jobs)

JobError

VarianteEfecto
Retryable(String)reencolar con backoff exponencial, hasta MAX_ATTEMPTS
Fatal(String)omitir reintentos → dead-letter de inmediato
Queue(String)error interno de la cola (serialización/registro)

Métodos de JobQueue: register::<T>() · dispatch(&payload) · start() · register_with::<T, _, _>(handler) · shutdown() · pending_count() (trabajos esperando a ser recogidos). Job::run_with recibe un JobCtx (id, attempt, stopping). Ambas colas tienen on_dead_letter y shutdown_grace. DatabaseJobQueue añade ensure_table_pool, with_workers_pool, new_pool, poll_interval, heartbeat_interval, queue_name, reclaim_stuck_after y reclaim_stuck_jobs_pool. jobs::inmemory_from_settings(&settings.jobs) construye una InMemoryJobQueue con [jobs] concurrency workers (4 por defecto).


Véase también

  • Planificador — para trabajo recurrente basado en el tiempo a intervalo fijo (Scheduler::every + Duration; no hay expresiones cron), en contraste con los trabajos bajo demanda.
  • Correo — la carga de trabajo canónica del «hazlo en un trabajo».
  • Caché — la otra manera de mantener rápidos los handlers de peticiones.
  • Signals — hooks fire-and-forget que a menudo despachan un trabajo.
  • Comandos de tenancy — el provisionamiento de los tenants sobre los que una cola por tenant hace fan-out.