✨ (cron): Añade la extensión pagetop-cron

- Trabajos programados con expresiones cron (croner), `fixed_rate()` y
  `fixed_delay()`, declarados con la acción `DeclareCronJobs` y
  ajustables por su clave en `[cron.jobs."clave"]`.
- Control de solapamiento, tiempo máximo, zona horaria por trabajo,
  ejecución al arrancar y bajo demanda con `run_now()`.
- Modo `external` sin estado, para réplicas y escalado a cero:
  `POST /cron` con `Authorization: Bearer`, ventanas alineadas de
  `trigger_interval_secs` y respuesta al terminar los trabajos.
- Estado con `jobs()`/`job()`, acción `AfterJobRun` y parada ordenada
  con `JobContext::is_stopping()`.
This commit is contained in:
Manuel Cillero 2026-10-28 06:52:42 +01:00
parent 4c3f4dab1b
commit 86d9f0e213
22 changed files with 3678 additions and 1 deletions

View file

@ -0,0 +1,139 @@
//! Ajustes de configuración de `pagetop-cron`.
//!
//! Ejemplo:
//!
//! ```toml
//! [cron]
//! mode = "internal"
//!
//! # Ajustes propios de un trabajo, por su clave.
//! [cron.jobs."shop.cleanup"]
//! schedule = "30 4 * * *"
//! timeout_secs = 600
//!
//! [cron.jobs."shop.reminders"]
//! enabled = false
//! ```
//!
//! Uso:
//!
//! ```rust,no_run
//! use pagetop_cron::config::{self, CronMode};
//!
//! assert_eq!(config::SETTINGS.mode, CronMode::Internal);
//! ```
//!
//! Todas las opciones, con su valor por defecto, se documentan en [`CronSettings`] y
//! [`JobSettings`].
//!
//! Consulta [`pagetop::config`] para ver cómo PageTop lee los archivos de configuración y aplica
//! los valores a los ajustes.
use pagetop::prelude::*;
use serde::Deserialize;
use std::collections::HashMap;
/// Ajustes de la sección `[cron]`, cargados al arrancar la aplicación.
pub static SETTINGS: LazySettings<CronSettings> = LazySettings::new();
/// Sección **`[cron]`** de la configuración.
#[settings(section = "cron")]
pub struct CronSettings {
/// Cómo se ejecutan los trabajos programados. Por defecto, con el planificador de la propia
/// aplicación ([`CronMode::Internal`]).
pub mode: CronMode,
/// Clave secreta que autoriza las llamadas a `POST /cron` con [`CronMode::External`], enviada
/// en la cabecera `Authorization: Bearer <clave>`. Obligatoria en ese modo, con 16 caracteres
/// o más (letras, dígitos, `-` o `_`), o la aplicación no arranca. Conviene guardarla en
/// `config/local.toml`, que no se versiona.
pub trigger_token: Option<String>,
/// Segundos entre dos llamadas a `POST /cron` con [`CronMode::External`]. Cada llamada ejecuta
/// los trabajos programados en el último intervalo de esta duración, contado en múltiplos
/// exactos desde el 1 de enero de 1970 (UTC), así que el programa externo debe llamar una vez,
/// y sólo una, en cada intervalo.
#[default = 60]
pub trigger_interval_secs: u64,
/// Segundos que se espera, al detener la aplicación, a que terminen los trabajos en curso.
/// Pasado ese tiempo, la aplicación termina igualmente.
#[default = 30]
pub shutdown_timeout_secs: u64,
/// Ajustes de trabajos concretos, cada uno en la subsección `[cron.jobs."clave"]`. Las claves
/// que no corresponden a ningún trabajo declarado se ignoran con un aviso en las trazas.
pub jobs: HashMap<String, JobSettings>,
}
/// Forma de ejecutar los trabajos programados. Usado en [`CronSettings::mode`].
#[derive(AutoDefault, Clone, Copy, Debug, Deserialize, Eq, PartialEq)]
#[serde(rename_all = "lowercase")]
pub enum CronMode {
/// La propia aplicación ejecuta cada trabajo según su programación mientras está en marcha. Es
/// el valor por defecto. Con varias instancias de la aplicación, **cada una** ejecuta los
/// trabajos: deja este modo en una sola y usa [`CronMode::Off`] en las demás.
#[default]
Internal,
/// Los trabajos sólo se ejecutan cuando un programa externo (`crontab`, un temporizador de
/// *systemd*, un servicio de la nube...) llama a `POST /cron` con la clave
/// [`trigger_token`](CronSettings::trigger_token), una vez cada
/// [`trigger_interval_secs`](CronSettings::trigger_interval_secs): cada llamada ejecuta los
/// trabajos programados desde la anterior. Útil para varias instancias tras un balanceador,
/// porque cada llamada sólo llega a una de ellas, y para las plataformas que detienen la
/// aplicación cuando no hay tráfico, porque no depende de lo que recuerde cada proceso.
External,
/// Ningún trabajo se ejecuta de forma automática; sólo bajo demanda con
/// [`run_now()`](crate::run_now). Útil en las instancias que no deben ejecutar trabajos y
/// para detenerlos temporalmente.
Off,
}
/// Subsección **`[cron.jobs."clave"]`** de la configuración, con los ajustes de un trabajo.
///
/// Permite a quien administra la aplicación cambiar cuándo se ejecuta un trabajo, o desactivarlo,
/// sin modificar el código. Los ajustes que no se indican mantienen lo declarado en el código.
#[settings]
pub struct JobSettings {
/// `false` desactiva el trabajo: deja de ejecutarse de forma automática, aunque se puede
/// ejecutar bajo demanda con [`run_now()`](crate::run_now).
#[default = true]
pub enabled: bool,
/// Sustituye la programación declarada en el código, con la sintaxis de
/// [`Schedule::parse()`](crate::Schedule::parse) (p. ej. `"*/10 * * * *"` o `"@every 5m"`).
/// Una programación no válida detiene el arranque.
pub schedule: Option<String>,
/// Sustituye el tiempo máximo de cada ejecución, en segundos. `0` quita el límite.
pub timeout_secs: Option<u64>,
}
#[cfg(test)]
mod tests {
use super::{CronSettings, config};
// `reference.toml` documents every option; with unknown keys rejected, loading it proves that
// it only documents keys that exist, with values of the right type.
const REFERENCE: &str = include_str!("../../../config/reference.toml");
#[test]
fn reference_toml_documents_only_existing_keys() {
config::load_from_str::<CronSettings>(REFERENCE).unwrap();
}
// Job keys usually contain dots, which TOML only accepts quoted. They must reach the map as a
// single key, not as nested tables.
#[test]
fn quoted_job_keys_with_dots_are_kept_whole() {
let settings = config::load_from_str::<CronSettings>(
r#"
[cron.jobs."shop.cleanup"]
enabled = false
schedule = "@hourly"
"#,
)
.unwrap();
let job = &settings.jobs["shop.cleanup"];
assert!(!job.enabled);
assert_eq!(job.schedule.as_deref(), Some("@hourly"));
assert_eq!(job.timeout_secs, None);
}
}

View file

@ -0,0 +1,87 @@
use pagetop::prelude::*;
use crate::Job;
/// Tipo de función que declara trabajos en un [`CronJobs`].
pub type FnDeclareCronJobs = fn(jobs: &mut CronJobs);
/// Trabajos declarados por las extensiones. Ver [`DeclareCronJobs`].
#[derive(AutoDefault)]
pub struct CronJobs {
jobs: Vec<Job>,
}
impl CronJobs {
/// Añade un trabajo.
pub fn add(&mut self, job: Job) {
self.jobs.push(job);
}
// Recoge los trabajos de todas las extensiones.
pub(crate) fn collect() -> Vec<Job> {
let mut jobs = CronJobs::default();
dispatch_actions(|action: &DeclareCronJobs| (action.f)(&mut jobs));
jobs.jobs
}
}
/// Acción para declarar trabajos programados.
///
/// Cada extensión registra esta acción con una función que añade sus trabajos. Se despacha una
/// sola vez, al inicializar `pagetop-cron`, así que los trabajos quedan fijos durante toda la vida
/// de la aplicación, como las propias acciones.
///
/// # Ejemplo
///
/// ```rust,no_run
/// use pagetop::prelude::*;
/// use pagetop_cron::prelude::*;
///
/// async fn cleanup(_cx: JobContext) -> JobResult {
/// // Borra los carritos abandonados...
/// Ok(())
/// }
///
/// fn declare_jobs(jobs: &mut CronJobs) {
/// jobs.add(
/// Job::new("shop.cleanup", Schedule::cron("30 4 * * *"), cleanup)
/// .with_title(Lc::n("Remove abandoned carts")),
/// );
/// }
///
/// struct Shop;
///
/// #[async_trait]
/// impl Extension for Shop {
/// fn dependencies(&self) -> Vec<ExtensionRef> {
/// vec![&pagetop_cron::Cron]
/// }
///
/// fn actions(&self) -> Vec<ActionBox> {
/// actions![DeclareCronJobs::new(declare_jobs)]
/// }
/// }
/// ```
pub struct DeclareCronJobs {
f: FnDeclareCronJobs,
weight: Weight,
}
impl ActionDispatcher for DeclareCronJobs {
fn weight(&self) -> Weight {
self.weight
}
}
impl DeclareCronJobs {
/// Registra una función que declara trabajos.
pub fn new(f: FnDeclareCronJobs) -> Self {
DeclareCronJobs { f, weight: 0 }
}
/// Opcional. Las acciones de menor peso se aplican antes. Se pueden usar valores negativos.
pub fn with_weight(mut self, value: Weight) -> Self {
self.weight = value;
self
}
}

View file

@ -0,0 +1,50 @@
//! Errores de `pagetop-cron`.
/// Errores al declarar, configurar o ejecutar trabajos programados.
#[derive(Debug, thiserror::Error)]
pub enum CronError {
/// Una programación no es válida (p. ej. una expresión cron mal escrita o un intervalo nulo).
#[error("invalid schedule \"{schedule}\": {reason}")]
InvalidSchedule {
/// Programación tal como se indicó.
schedule: String,
/// Motivo del error.
reason: String,
},
/// La clave de un trabajo no es válida.
#[error(
"invalid job key \"{0}\": use lowercase letters, digits, '_', '-' and '.', starting with a \
letter or digit"
)]
InvalidKey(String),
/// Dos trabajos se declaran con la misma clave.
#[error("job \"{0}\" is declared more than once")]
DuplicateJob(String),
/// Un trabajo no se puede programar, por su declaración o por sus ajustes.
#[error("invalid job \"{key}\"")]
InvalidJob {
/// Clave del trabajo.
key: String,
/// Motivo del error.
#[source]
source: Box<CronError>,
},
/// Un ajuste de la sección `[cron]` no es válido.
#[error("invalid cron setting \"{key}\": {reason}")]
InvalidSetting {
/// Clave del ajuste, p. ej. `"cron.trigger_token"`.
key: &'static str,
/// Motivo del error.
reason: String,
},
/// No hay ningún trabajo declarado con la clave indicada.
#[error("unknown job \"{0}\"")]
UnknownJob(String),
/// El trabajo ya se está ejecutando y no admite ejecuciones simultáneas
/// ([`Overlap::Skip`](crate::Overlap::Skip)).
#[error("job \"{0}\" is already running")]
AlreadyRunning(String),
/// Los trabajos aún no están disponibles: la aplicación no se ha preparado.
#[error("cron jobs are not available until the application is prepared")]
NotInitialized,
}

View file

@ -0,0 +1,240 @@
use pagetop::prelude::*;
use tokio::sync::watch;
use crate::{RunTrigger, Schedule};
use std::future::Future;
use std::pin::Pin;
use std::sync::Arc;
/// Resultado de una ejecución de un trabajo.
///
/// Con [`BoxError`] el trabajo puede propagar con `?` cualquier error; el error se registra en las
/// trazas y en el estado del trabajo ([`JobStatus`](crate::JobStatus)).
pub type JobResult = Result<(), BoxError>;
// Función del trabajo, ya preparada para ejecutarse en una tarea propia.
pub(crate) type JobFn =
Arc<dyn Fn(JobContext) -> Pin<Box<dyn Future<Output = JobResult> + Send>> + Send + Sync>;
/// Qué hacer a la hora de ejecutar un trabajo si no ha terminado la ejecución anterior.
///
/// Usado en [`Job::with_overlap()`]. Las ejecuciones programadas con [`Schedule::fixed_delay()`]
/// nunca se solapan entre sí; con esa programación, sólo decide qué ocurre si se pide
/// [`run_now()`](crate::run_now) durante una de ellas.
#[derive(AutoDefault, Clone, Copy, Debug, Eq, PartialEq)]
pub enum Overlap {
/// Se omite la nueva ejecución y se registra un aviso. Es el valor por defecto, porque la
/// mayoría de los trabajos no esperan ejecutarse dos veces a la vez sobre los mismos datos.
#[default]
Skip,
/// Se ejecuta igualmente, a la vez que la anterior.
Allow,
}
/// Un trabajo programado: una función asíncrona que se ejecuta según una [`Schedule`].
///
/// Se identifica por una clave única, que conviene empezar por el nombre de la extensión
/// (`"shop.cleanup"`), con letras minúsculas, dígitos, `_`, `-` y `.`. La clave aparece en las
/// trazas y es la que usa la configuración para cambiar o desactivar el trabajo
/// (`[cron.jobs."shop.cleanup"]`) y [`run_now()`](crate::run_now) para ejecutarlo bajo demanda.
///
/// La función recibe un [`JobContext`] y devuelve un [`JobResult`]. Accede a los ajustes y a los
/// servicios de la aplicación igual que un *handler*: con los `SETTINGS` de cada extensión, o con
/// funciones como `dbconn()` de `pagetop-seaorm`.
///
/// Los trabajos se declaran con la acción [`DeclareCronJobs`](crate::DeclareCronJobs).
///
/// # Ejemplo
///
/// ```rust,no_run
/// use pagetop::prelude::*;
/// use pagetop_cron::prelude::*;
///
/// async fn purge_sessions(_cx: JobContext) -> JobResult {
/// // Borra las sesiones caducadas...
/// Ok(())
/// }
///
/// let job = Job::new("shop.purge_sessions", Schedule::cron("0 3 * * *"), purge_sessions)
/// .with_title(Lc::n("Purge expired sessions"))
/// .with_timeout(Duration::minutes(10));
/// ```
#[derive(Clone, Getters)]
pub struct Job {
/// Devuelve la clave única del trabajo.
key: CowStr,
/// Devuelve el título descriptivo del trabajo.
title: Lc,
/// Devuelve la programación declarada en el código.
schedule: Schedule,
#[getters(skip)]
run: JobFn,
/// Devuelve qué hacer si la ejecución anterior aún no ha terminado.
#[getters(copy)]
overlap: Overlap,
/// Devuelve el tiempo máximo de cada ejecución, si lo hay.
#[getters(copy)]
timeout: Option<Duration>,
/// Devuelve la zona horaria propia del trabajo, si la tiene.
#[getters(copy)]
timezone: Option<Tz>,
/// Devuelve si el trabajo se ejecuta también al arrancar la aplicación.
#[getters(copy)]
run_on_start: bool,
}
impl Job {
/// Crea un trabajo con su clave, su programación y la función que ejecuta.
///
/// La función puede ser una `async fn` o un cierre que devuelva un *future*. El *future* debe
/// ser `Send + 'static`: si el cierre usa datos propios, los clona dentro de un bloque
/// `async move`.
pub fn new<F, Fut>(key: impl Into<CowStr>, schedule: Schedule, run: F) -> Self
where
F: Fn(JobContext) -> Fut + Send + Sync + 'static,
Fut: Future<Output = JobResult> + Send + 'static,
{
Job {
key: key.into(),
title: Lc::none(),
schedule,
run: Arc::new(move |cx| Box::pin(run(cx))),
overlap: Overlap::default(),
timeout: None,
timezone: None,
run_on_start: false,
}
}
/// Título descriptivo para listados y paneles. Sin título, se muestra la clave.
pub fn with_title(mut self, title: Lc) -> Self {
self.title = title;
self
}
/// Qué hacer cuando llega la hora de una ejecución y la anterior aún no ha terminado. Por
/// defecto, [`Overlap::Skip`].
pub fn with_overlap(mut self, overlap: Overlap) -> Self {
self.overlap = overlap;
self
}
/// Tiempo máximo de cada ejecución. Si se supera, la ejecución se cancela (el *future* deja
/// de ejecutarse en el siguiente `.await`) y se registra como
/// [`JobOutcome::TimedOut`](crate::JobOutcome::TimedOut). Sin valor, no hay límite.
///
/// Un trabajo que no llega a ningún `.await` (un cálculo largo, una llamada bloqueante) no se
/// puede cancelar: sigue en marcha hasta terminar y, mientras tanto, cuenta como en curso.
///
/// La configuración puede cambiarlo con `timeout_secs` (ver
/// [`JobSettings`](crate::config::JobSettings)).
pub fn with_timeout(mut self, timeout: impl Into<Option<Duration>>) -> Self {
self.timeout = timeout.into();
self
}
/// Zona horaria en la que se interpreta la expresión cron de este trabajo, p. ej.
/// `Tz::Europe__Madrid`. Sin valor, la de la aplicación (`[app].timezone`).
pub fn with_timezone(mut self, timezone: impl Into<Option<Tz>>) -> Self {
self.timezone = timezone.into();
self
}
/// Ejecuta también el trabajo al arrancar la aplicación, además de según su programación. Útil
/// para no esperar a la primera ejecución programada, p. ej. para procesar lo que quedó
/// pendiente al detener la aplicación.
///
/// Con `mode = "external"` se ejecuta en la primera llamada a `POST /cron` que recibe cada
/// proceso de la aplicación, y con `mode = "off"` no se ejecuta.
pub fn with_run_on_start(mut self) -> Self {
self.run_on_start = true;
self
}
// Función del trabajo, para ejecutarla en una tarea propia.
pub(crate) fn runner(&self) -> JobFn {
Arc::clone(&self.run)
}
}
// **< JobContext >*********************************************************************************
/// Datos de la ejecución en curso que recibe la función de un [`Job`].
///
/// Además de indicar qué provocó la ejecución, permite a los trabajos largos saber si la aplicación
/// se está deteniendo, para dejar su trabajo en un punto seguro antes de que se agote el tiempo de
/// espera (`cron.shutdown_timeout_secs`).
///
/// # Ejemplo
///
/// ```rust,no_run
/// use pagetop::prelude::*;
/// use pagetop_cron::prelude::*;
///
/// async fn send_newsletters(cx: JobContext) -> JobResult {
/// for batch in 0..100 {
/// if cx.is_stopping() {
/// // Lo que falte se enviará en la siguiente ejecución.
/// trace::info!("Stopping \"{}\" at batch {batch}", cx.key());
/// break;
/// }
/// // Envía el lote...
/// }
/// Ok(())
/// }
/// ```
#[derive(Clone, Debug)]
pub struct JobContext {
key: CowStr,
trigger: RunTrigger,
scheduled_at: Option<DateTime<Utc>>,
stop: watch::Receiver<bool>,
}
impl JobContext {
pub(crate) fn new(
key: CowStr,
trigger: RunTrigger,
scheduled_at: Option<DateTime<Utc>>,
stop: watch::Receiver<bool>,
) -> Self {
JobContext {
key,
trigger,
scheduled_at,
stop,
}
}
/// Clave del trabajo.
pub fn key(&self) -> &str {
&self.key
}
/// Qué provocó esta ejecución.
pub fn trigger(&self) -> RunTrigger {
self.trigger
}
/// Momento en que estaba programada esta ejecución, en UTC. Puede ser algo anterior al momento
/// real en que empieza. `None` si no se debe a la programación (al arrancar o bajo demanda).
pub fn scheduled_at(&self) -> Option<DateTime<Utc>> {
self.scheduled_at
}
/// Devuelve `true` si la aplicación se está deteniendo.
pub fn is_stopping(&self) -> bool {
*self.stop.borrow()
}
/// Espera hasta que la aplicación empiece a detenerse. Pensado para `tokio::select!`, junto a
/// la espera de otra operación que se quiera interrumpir.
pub async fn stopping(&self) {
let mut stop = self.stop.clone();
if stop.wait_for(|stopping| *stopping).await.is_err() {
std::future::pending::<()>().await;
}
}
}

View file

@ -0,0 +1,442 @@
/*!
<div align="center">
<h1>PageTop Cron</h1>
<p>Programación de tareas para aplicaciones <strong>PageTop</strong>.</p>
[![Doc API](https://img.shields.io/docsrs/pagetop-cron?label=Doc%20API&style=for-the-badge&logo=Docs.rs)](https://docs.rs/pagetop-cron)
[![Crates.io](https://img.shields.io/crates/v/pagetop-cron.svg?style=for-the-badge&logo=ipfs)](https://crates.io/crates/pagetop-cron)
[![Descargas](https://img.shields.io/crates/d/pagetop-cron.svg?label=Descargas&style=for-the-badge&logo=transmission)](https://crates.io/crates/pagetop-cron)
[![Licencia](https://img.shields.io/badge/license-MIT%2FApache-blue.svg?label=Licencia&style=for-the-badge)](https://git.cillero.es/manuelcillero/pagetop/src/branch/main/extensions/pagetop-cron#licencia)
</div>
Ejecuta trabajos periódicos en segundo plano mientras la aplicación está en marcha: cada noche a
las 4:30, cada diez minutos, el último día de cada mes, o unos segundos después de terminar la
ejecución anterior. Cada extensión declara sus trabajos en el código con una acción, y quien
administra la aplicación decide en los archivos de configuración cómo se ejecutan, y puede cambiar
cuándo se ejecuta cada trabajo o desactivarlo sin recompilar.
## Sobre PageTop
[PageTop](https://docs.rs/pagetop) es un entorno de desarrollo que reivindica la esencia de la web
clásica para crear soluciones web SSR (*renderizadas en el servidor*) modulares, extensibles y
configurables, basadas en HTML, CSS y JavaScript.
## Guía rápida
**Añade la dependencia** a tu `Cargo.toml`:
```toml
[dependencies]
pagetop-cron = "..."
```
**Escribe el trabajo** como una función asíncrona que recibe un [`JobContext`] y devuelve un
[`JobResult`]. Con `?` puede propagar cualquier error, que se registra en las trazas:
```rust,no_run
use pagetop::prelude::*;
use pagetop_cron::prelude::*;
async fn cleanup(_cx: JobContext) -> JobResult {
// Borra los carritos abandonados hace más de 30 días...
Ok(())
}
```
**Declara el trabajo** con la acción [`DeclareCronJobs`] en la extensión que lo aporta, que depende
de `pagetop-cron`:
```rust,no_run
# use pagetop::prelude::*;
# use pagetop_cron::prelude::*;
# async fn cleanup(_cx: JobContext) -> JobResult { Ok(()) }
fn declare_jobs(jobs: &mut CronJobs) {
jobs.add(
Job::new("shop.cleanup", Schedule::cron("30 4 * * *"), cleanup)
.with_title(Lc::n("Remove abandoned carts"))
.with_timeout(Duration::minutes(15)),
);
}
struct Shop;
#[async_trait]
impl Extension for Shop {
fn dependencies(&self) -> Vec<ExtensionRef> {
vec![&pagetop_cron::Cron]
}
fn actions(&self) -> Vec<ActionBox> {
actions![DeclareCronJobs::new(declare_jobs)]
}
}
```
Y ya está: al ejecutar la aplicación con [`Application::run()`], el trabajo se ejecuta cada día a
las 4:30 en la zona horaria de la aplicación (`[app].timezone`). La clave (`"shop.cleanup"`)
identifica el trabajo en las trazas, en la configuración y al ejecutarlo bajo demanda; conviene
empezarla por el nombre de la extensión.
## Cuándo se ejecuta un trabajo
[`Schedule`] ofrece tres formas de programarlo:
```rust,no_run
# use pagetop::prelude::*;
# use pagetop_cron::prelude::*;
// Según una expresión cron: cada día a las 4:30.
Schedule::cron("30 4 * * *");
// Cada cinco minutos desde que *empieza* la ejecución anterior (ritmo fijo).
Schedule::fixed_rate(Duration::minutes(5));
// Treinta segundos después de que *termina* la ejecución anterior (nunca se solapan).
Schedule::fixed_delay(Duration::seconds(30));
```
Las expresiones cron siguen la sintaxis clásica de cinco campos, con un sexto campo opcional para
los segundos y un séptimo, también opcional, para el año, y admiten además `L`, `W` y `#` (último
día del mes, día laborable más cercano, enésimo día de la semana) y apodos como `@daily`. Se
interpretan en la zona horaria de la aplicación y respetan los cambios de hora. Todos los
detalles, con ejemplos, en [`Schedule`].
Para procesar colas o tareas pendientes, `fixed_delay()` suele ser la mejor opción: cada ejecución
procesa lo que dejó la anterior y nunca coinciden dos.
## Opciones de cada trabajo
[`Job`] ofrece además:
| Método | Uso |
|-------------------------|---------------------------------------------------------------|
| [`with_title()`] | Título descriptivo, traducible, para listados y paneles. |
| [`with_timeout()`] | Tiempo máximo de cada ejecución; si lo supera, se cancela. |
| [`with_overlap()`] | Qué hacer si la ejecución anterior sigue en curso ([`Overlap`]). |
| [`with_timezone()`] | Zona horaria propia para su expresión cron. |
| [`with_run_on_start()`] | Se ejecuta también al arrancar la aplicación. |
Si llega la hora de un trabajo y su ejecución anterior aún no ha terminado, por defecto se omite la
nueva ([`Overlap::Skip`]); con [`Overlap::Allow`] se ejecuta a la vez.
[`with_title()`]: Job::with_title
[`with_timeout()`]: Job::with_timeout
[`with_overlap()`]: Job::with_overlap
[`with_timezone()`]: Job::with_timezone
[`with_run_on_start()`]: Job::with_run_on_start
La función del trabajo puede ser también un cierre. Accede a los ajustes y servicios de la
aplicación igual que un *handler*, p. ej. con los `SETTINGS` de cada extensión o con `dbconn()` de
`pagetop-seaorm`:
```rust,no_run
# use pagetop::prelude::*;
# use pagetop_cron::prelude::*;
let job = Job::new("app.heartbeat", Schedule::fixed_rate(Duration::minutes(1)), |cx| async move {
trace::info!("Heartbeat from \"{}\" ({:?})", cx.key(), cx.trigger());
Ok(())
});
```
Un `panic!` dentro de un trabajo no afecta a la aplicación ni a sus siguientes ejecuciones: se
registra como un fallo más.
## Modos de ejecución
Quien administra la aplicación elige cómo se ejecutan los trabajos con `mode`, en la sección
`[cron]` (todas las opciones en [`config`]):
| `mode` | Los trabajos se ejecutan... |
|--------------|-------------------------------------------------------------------------|
| `"internal"` | Por defecto. Con el planificador de la propia aplicación. |
| `"external"` | Cuando un programa externo llama a `POST /cron` con la clave secreta. |
| `"off"` | Nunca de forma automática; sólo bajo demanda con [`run_now()`]. |
### Una sola instancia: `"internal"`
Con `"internal"`, cada proceso de la aplicación lleva su propio reloj y lanza los trabajos cuando
les toca. Con un solo proceso siempre en marcha (un servidor, un servicio de *systemd*, un
contenedor) es justo lo que se necesita, y no hay que configurar nada.
### Varias instancias
Si la misma aplicación se ejecuta en varios procesos a la vez, cada uno lanza todos los trabajos
con `"internal"`:
```text
+--> instancia A (internal) --> limpieza a las 4:30
balanceador ---+--> instancia B (internal) --> limpieza a las 4:30
+--> instancia C (internal) --> limpieza a las 4:30
```
La limpieza se hace tres veces, y un boletín se enviaría tres veces. Las instancias no se ponen de
acuerdo entre sí, así que hay dos formas de evitarlo:
- **`"internal"` en una instancia y `"off"` en las demás.** Es lo más sencillo si las instancias
se configuran a mano, pero esa instancia queda distinta del resto: si se detiene, nadie ejecuta
los trabajos.
- **`"external"` en todas.** Ninguna tiene reloj propio: un único reloj fuera de la aplicación
llama periódicamente a `POST /cron`, y el balanceador entrega cada llamada a una sola instancia,
que ejecuta lo programado desde la llamada anterior:
```text
crontab (en una sola máquina) --POST /cron--> balanceador --> instancia B ejecuta lo pendiente
```
### Cuándo usar `"external"`
- **Réplicas idénticas o autoescalado** (Kubernetes, Docker Swarm, varias máquinas tras un
balanceador). Todas arrancan con la misma imagen y la misma configuración, así que no se puede
dejar una distinta. Con `"external"` todas son iguales y cualquiera puede atender la llamada.
- **Plataformas que detienen la aplicación cuando no hay tráfico** (escalado a cero). Si nadie
visita el sitio de madrugada, no queda ningún proceso vivo y el reloj interno de las 4:30 no
existe; algunas plataformas, además, sólo dan CPU mientras se atiende una petición. La llamada
externa despierta la aplicación y le da tiempo para ejecutar lo pendiente. Estas plataformas
suelen ofrecer su propio planificador para hacerla.
- **Planificar desde las herramientas de operaciones** que ya se usan, como un *CronJob* de
Kubernetes o un temporizador de *systemd*. La llamada responde `200 OK` aunque falle algún
trabajo, para que un reintento no repita los demás; el resultado de cada uno viene en el cuerpo
de la respuesta y, para avisar de los fallos, está la acción [`AfterJobRun`].
Con una sola instancia siempre en marcha, `"external"` no aporta nada: añade piezas (un `crontab`,
una clave secreta, una ruta expuesta) y pierde precisión. Mejor `"internal"`.
### Configurar `"external"`
```toml
[cron]
mode = "external"
trigger_token = "..." # Clave secreta propia, mejor en config/local.toml.
trigger_interval_secs = 60 # Una llamada por minuto (el valor por defecto).
```
La clave debe tener al menos 16 caracteres (letras, dígitos, `-` o `_`), o la aplicación no
arranca; `openssl rand -hex 32` genera una adecuada. Viaja en la cabecera
`Authorization: Bearer <clave>`, no en la ruta, porque los *proxies* y los balanceadores suelen
registrar las rutas de las peticiones. Para que tampoco aparezca en la lista de procesos del
sistema, `curl` puede leer la cabecera de un archivo que sólo pueda leer el usuario del `crontab`:
```text
# crontab del sistema: comprueba los trabajos cada minuto. El archivo contiene la línea
# "Authorization: Bearer <clave>".
* * * * * curl -fsS -X POST -H @/etc/miapp/cron-header https://example.com/cron > /dev/null
```
La llamada responde cuando terminan los trabajos que ejecuta, con `200 OK` y una línea por trabajo
con su resultado (`succeeded`, `failed`, `timed out` o `panicked`); sin la clave correcta responde
`404 Not Found`, igual que una ruta que no existe. Esperar mantiene viva la aplicación en las
plataformas que sólo dan CPU mientras se atiende una petición, así que el tiempo de espera del
programa externo debe superar lo que tarde el trabajo más largo; conviene limitarlo con
[`with_timeout()`]. Si el programa externo corta antes, los trabajos siguen igualmente, pero en esas
plataformas pueden quedarse sin CPU.
Cada llamada ejecuta lo programado en el último minuto, sea cual sea la instancia que la recibe y
aunque acabe de arrancar: una llamada a las 4:30:20 ejecuta lo programado desde las 4:29:00
(excluido) hasta las 4:30:00. Así ninguna instancia necesita recordar qué hicieron las demás, pero
el programa externo debe llamar una vez, y sólo una, cada minuto: si falta una llamada se pierden
sus ejecuciones, y si sobra, dos instancias pueden repetirlas. Para llamar con otra frecuencia
(p. ej. cada cuarto de hora, en una plataforma que despierta la aplicación en cada llamada),
indícala en `trigger_interval_secs` (`900`) y programa los trabajos en múltiplos de ella. La
precisión es la del intervalo: con una llamada por minuto, un trabajo programado cada diez
segundos se ejecuta una vez por minuto.
Una llamada de más suele ser un reintento. La respuesta es `200 OK` aunque falle algún trabajo, así
que el programa externo sólo reintenta tras un error de red o si se agota su tiempo de espera; pero
si el reintento llega a otra instancia, ésta ejecuta de nuevo lo mismo, porque las instancias no
comparten estado. Desactiva los reintentos del programa externo (p. ej. `backoffLimit: 0` en un
*CronJob* de Kubernetes) y, si un trabajo no debe repetirse nunca, que lo compruebe él mismo (p. ej.
en la base de datos) antes de hacer nada.
## Ajustar un trabajo desde la configuración
Cada trabajo puede cambiarse por su clave, sin tocar el código, en la subsección
`[cron.jobs."clave"]` (ver [`JobSettings`](config::JobSettings)):
```toml
[cron.jobs."shop.cleanup"]
schedule = "0 5 * * SUN" # Sólo los domingos a las 5:00.
timeout_secs = 1800 # Tiempo máximo de 30 minutos (0 = sin límite).
[cron.jobs."shop.reminders"]
enabled = false # Desactivado: sólo se ejecuta bajo demanda.
```
La programación admite la misma sintaxis que [`Schedule::parse()`], incluidos `"@every 10m"` y
`"@delay 30s"`. Una programación no válida detiene el arranque indicando el trabajo, y una clave
que no corresponde a ningún trabajo se ignora con un aviso en las trazas.
## Ejecutar y consultar los trabajos
[`run_now()`] ejecuta un trabajo en el acto y devuelve su [`JobRun`]: útil para un botón
«Ejecutar ahora» de un panel de administración, para una orden de mantenimiento o para las
pruebas. [`jobs()`] y [`job()`] devuelven su [`JobStatus`]: programación efectiva, próxima
ejecución, resultado de la última y número de ejecuciones, fallos y omisiones.
Para reaccionar a cada ejecución terminada (registrarla, enviar métricas, avisar cuando falla un
trabajo), registra la acción [`AfterJobRun`].
## Detener la aplicación
Al detener la aplicación (Ctrl+C o `SIGTERM`), el planificador deja de lanzar ejecuciones y espera
a que terminen las que están en curso, hasta `cron.shutdown_timeout_secs` (30 s por defecto). Un
trabajo largo puede comprobar [`JobContext::is_stopping()`] para dejar su trabajo en un punto
seguro antes de que se agote ese tiempo.
## Pruebas
El planificador sólo se pone en marcha con [`Application::run()`] (ver
[`Extension::start()`](pagetop::core::extension::Extension::start)), nunca en las pruebas que
preparan la aplicación y obtienen su servidor con [`Application::test()`]. En ellas, los trabajos
se ejecutan cuando la prueba quiere con [`run_now()`]:
```rust,no_run
# use pagetop::prelude::*;
# struct Shop;
# #[async_trait]
# impl Extension for Shop {}
#[pagetop::test]
async fn cleanup_job_succeeds() {
Application::prepare(&Shop).await;
let run = pagetop_cron::run_now("shop.cleanup").await.unwrap();
assert!(run.outcome().is_success(), "{}", run.outcome());
}
```
## Qué no hace
Para mantenerse sencilla, la extensión no guarda nada fuera de la memoria:
- **No recupera las ejecuciones perdidas.** Si la aplicación estaba detenida cuando tocaba una
ejecución, no se hace al volver a arrancar; la siguiente llega según su programación. Para
trabajos que no deben perder ninguna, combina la programación con
[`with_run_on_start()`](Job::with_run_on_start), o guarda en la base de datos qué queda
pendiente y procésalo en cada ejecución.
- **No es una cola de trabajos.** Para tareas puntuales que deben sobrevivir a un reinicio (un
correo que no se pudo enviar, una importación...), cada extensión guarda las pendientes en su
propia tabla y declara un trabajo periódico que las procesa.
- **No coordina varias instancias** por sí misma; ver [varias instancias](#varias-instancias).
[`Application::run()`]: pagetop::app::Application::run
[`Application::test()`]: pagetop::app::Application::test
## Créditos
Las expresiones cron se interpretan con [croner](https://github.com/hexagon/croner-rust), la misma
biblioteca que usa *tokio-cron-scheduler*, distribuida bajo licencia
[MIT](https://github.com/hexagon/croner-rust/blob/master/LICENSE).
*/
#![doc(
html_favicon_url = "https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/assets/favicon.ico"
)]
use pagetop::prelude::*;
pub mod config;
mod error;
pub use error::CronError;
mod schedule;
pub use schedule::Schedule;
mod job;
pub use job::{Job, JobContext, JobResult, Overlap};
mod run;
pub use run::{AfterJobRun, FnAfterJobRun, JobOutcome, JobRun, RunTrigger};
mod status;
pub use status::JobStatus;
mod declare;
pub use declare::{CronJobs, DeclareCronJobs, FnDeclareCronJobs};
mod scheduler;
pub use scheduler::{TRIGGER_PATH, job, jobs, run_due, run_now};
include_locales!(LOCALES_CRON);
/// Prelude de `pagetop-cron`.
pub mod prelude {
pub use crate::{AfterJobRun, CronJobs, DeclareCronJobs};
pub use crate::{CronError, Job, JobContext, JobResult, Overlap, Schedule};
pub use crate::{JobOutcome, JobRun, JobStatus, RunTrigger};
}
/// Implementa la extensión `pagetop-cron`.
pub struct Cron;
#[async_trait]
impl Extension for Cron {
fn name(&self) -> Lc {
Lc::t("extension_name", &LOCALES_CRON)
}
fn description(&self) -> Lc {
Lc::t("extension_description", &LOCALES_CRON)
}
fn settings(&self) -> Option<&'static dyn LoadSettings> {
Some(&config::SETTINGS)
}
async fn initialize(&self) -> Result<(), BoxError> {
// Recoge y valida los trabajos de todas las extensiones: un error detiene el arranque.
scheduler::initialize()?;
Ok(())
}
async fn start(&self) -> Result<(), BoxError> {
scheduler::start();
Ok(())
}
async fn shutdown(&self) {
scheduler::shutdown().await;
}
fn configure_router(&self, router: Router) -> Router {
if config::SETTINGS.mode != config::CronMode::External {
return router;
}
router.route(TRIGGER_PATH, web::post(trigger_post).fallback(not_found))
}
}
// POST {TRIGGER_PATH} - Lanza los trabajos pendientes (modo externo). La clave llega en la cabecera
// `Authorization` y no en la ruta, que suelen registrar los *proxies* y los balanceadores. Sin la
// clave correcta, o con otro método, responde la misma página 404 que una ruta inexistente.
async fn trigger_post(request: HttpRequest) -> Response {
let token = request
.headers()
.get(web::http::header::AUTHORIZATION)
.and_then(|value| value.to_str().ok())
.and_then(|value| value.split_once(' '))
.filter(|(scheme, _)| scheme.eq_ignore_ascii_case("Bearer"))
.map(|(_, token)| token.trim_start());
if !token.is_some_and(scheduler::token_matches) {
return ErrorPage::NotFound(Some(request)).into_response();
}
// Siempre `200 OK`, aunque falle algún trabajo: un reintento del programa externo podría
// llegar a otra instancia y repetir también los que terminaron bien. Sólo se indica el tipo de
// resultado; los mensajes de error, que pueden revelar detalles internos, van a las trazas.
let runs = run_due().await;
let mut body = util::join!("Ran ", runs.len().to_string(), " cron jobs\n");
for run in &runs {
body.push_str(run.key());
body.push_str(": ");
body.push_str(match run.outcome() {
JobOutcome::Succeeded => "succeeded",
JobOutcome::Failed(_) => "failed",
JobOutcome::TimedOut => "timed out",
JobOutcome::Panicked(_) => "panicked",
});
body.push('\n');
}
(web::http::StatusCode::OK, body).into_response()
}
async fn not_found(request: HttpRequest) -> ErrorPage {
ErrorPage::NotFound(Some(request))
}

View file

@ -0,0 +1,2 @@
extension_name = Scheduled jobs
extension_description = Runs periodic jobs with cron expressions or intervals, and on demand.

View file

@ -0,0 +1,2 @@
extension_name = Tareas programadas
extension_description = Ejecuta tareas periódicas con expresiones cron o intervalos, y bajo demanda.

View file

@ -0,0 +1,165 @@
use pagetop::prelude::*;
use std::fmt;
/// Qué provocó la ejecución de un trabajo.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum RunTrigger {
/// Su programación, con el planificador de la aplicación (`mode = "internal"`).
Schedule,
/// El arranque de la aplicación ([`Job::with_run_on_start()`](crate::Job::with_run_on_start)).
/// Con `mode = "external"`, en la primera llamada a `POST /cron` que recibe el proceso.
Startup,
/// Una llamada a [`run_now()`](crate::run_now).
Manual,
/// Su programación, con una llamada externa a `POST /cron` (`mode = "external"`).
External,
}
impl RunTrigger {
/// Nombre corto en inglés, para trazas y registros.
pub const fn as_str(&self) -> &'static str {
match self {
RunTrigger::Schedule => "schedule",
RunTrigger::Startup => "startup",
RunTrigger::Manual => "manual",
RunTrigger::External => "external",
}
}
}
/// Resultado de una ejecución de un trabajo.
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum JobOutcome {
/// Terminó sin errores.
Succeeded,
/// Devolvió un error, con su mensaje y el de sus causas.
Failed(String),
/// Superó su tiempo máximo ([`Job::with_timeout()`](crate::Job::with_timeout)) y se canceló.
TimedOut,
/// Provocó un `panic!`, con su mensaje. El `panic!` no afecta a la aplicación ni a las
/// siguientes ejecuciones.
Panicked(String),
}
impl JobOutcome {
/// Devuelve `true` si la ejecución terminó sin errores.
pub fn is_success(&self) -> bool {
matches!(self, JobOutcome::Succeeded)
}
}
impl fmt::Display for JobOutcome {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
JobOutcome::Succeeded => f.write_str("succeeded"),
JobOutcome::Failed(error) => write!(f, "failed: {error}"),
JobOutcome::TimedOut => f.write_str("timed out"),
JobOutcome::Panicked(message) => write!(f, "panicked: {message}"),
}
}
}
/// Informe de una ejecución terminada de un trabajo.
///
/// Lo devuelve [`run_now()`](crate::run_now), lo recibe la acción [`AfterJobRun`] y se guarda la
/// última de cada trabajo en su [`JobStatus`](crate::JobStatus).
#[derive(Clone, Debug, Getters)]
pub struct JobRun {
/// Devuelve la clave del trabajo.
key: CowStr,
/// Devuelve qué provocó la ejecución.
#[getters(copy)]
trigger: RunTrigger,
/// Devuelve el momento en que empezó, en UTC.
#[getters(copy)]
started_at: DateTime<Utc>,
/// Devuelve cuánto duró.
#[getters(copy)]
duration: Duration,
/// Devuelve cómo terminó.
outcome: JobOutcome,
}
impl JobRun {
pub(crate) fn new(
key: CowStr,
trigger: RunTrigger,
started_at: DateTime<Utc>,
duration: Duration,
outcome: JobOutcome,
) -> Self {
JobRun {
key,
trigger,
started_at,
duration,
outcome,
}
}
}
// **< AfterJobRun >********************************************************************************
/// Tipo de función que recibe el informe de cada ejecución terminada. Ver [`AfterJobRun`].
pub type FnAfterJobRun = fn(run: &JobRun);
/// Acción que se despacha al terminar cada ejecución de cualquier trabajo, con su informe.
///
/// Sirve para vigilar los trabajos sin tocarlos: registrar las ejecuciones en una tabla, enviar
/// métricas o avisar cuando uno falla. La función es síncrona y se ejecuta en la tarea del
/// trabajo; para algo lento (p. ej. enviar un correo) lanza una tarea con `tokio::spawn()`. Un
/// `panic!` en la función se registra en las trazas y no afecta al trabajo.
///
/// # Ejemplo
///
/// ```rust,no_run
/// use pagetop::prelude::*;
/// use pagetop_cron::prelude::*;
///
/// fn alert_on_failure(run: &JobRun) {
/// if !run.outcome().is_success() {
/// trace::warn!("ALERT: job \"{}\" {}", run.key(), run.outcome());
/// }
/// }
///
/// struct Monitor;
///
/// #[async_trait]
/// impl Extension for Monitor {
/// fn dependencies(&self) -> Vec<ExtensionRef> {
/// vec![&pagetop_cron::Cron]
/// }
///
/// fn actions(&self) -> Vec<ActionBox> {
/// actions![AfterJobRun::new(alert_on_failure)]
/// }
/// }
/// ```
pub struct AfterJobRun {
f: FnAfterJobRun,
weight: Weight,
}
impl ActionDispatcher for AfterJobRun {
fn weight(&self) -> Weight {
self.weight
}
}
impl AfterJobRun {
/// Registra una función que recibe el informe de cada ejecución.
pub fn new(f: FnAfterJobRun) -> Self {
AfterJobRun { f, weight: 0 }
}
/// Opcional. Las acciones de menor peso se aplican antes. Se pueden usar valores negativos.
pub fn with_weight(mut self, value: Weight) -> Self {
self.weight = value;
self
}
pub(crate) fn dispatch(run: &JobRun) {
dispatch_actions(|action: &Self| (action.f)(run));
}
}

View file

@ -0,0 +1,376 @@
use pagetop::prelude::*;
use croner::Cron;
use croner::parser::CronParser;
use crate::CronError;
use std::fmt;
use std::str::FromStr;
/// Cuándo se ejecuta un trabajo.
///
/// Hay tres formas de programar un trabajo:
///
/// | Constructor | Texto | Se ejecuta... |
/// |--------------------------------------|-----------------|-------------------------------------|
/// | [`cron()`](Self::cron) | `"*/5 * * * *"` | según una expresión cron. |
/// | [`fixed_rate()`](Self::fixed_rate) | `"@every 5m"` | 5 min tras **empezar** la anterior. |
/// | [`fixed_delay()`](Self::fixed_delay) | `"@delay 5m"` | 5 min tras **terminar** la anterior.|
///
/// Con `fixed_rate()` las ejecuciones siguen un ritmo fijo, aunque una dure más que el intervalo
/// (lo que ocurra entonces lo decide [`Overlap`](crate::Overlap)). Con `fixed_delay()` nunca se
/// solapan: es la opción natural para procesar colas o pendientes, porque cada ejecución empieza
/// con lo que dejó la anterior.
///
/// Los constructores no validan la programación: lo hace la aplicación al arrancar, que no
/// arranca si alguna no es válida e indica el trabajo afectado. Para validarla antes, por ejemplo
/// si procede de un texto que escribe alguien, usa [`parse()`](Self::parse).
///
/// # Expresiones cron
///
/// Siguen la sintaxis clásica de *cron* de cinco campos, con un sexto campo opcional al principio
/// para los segundos y un séptimo, también opcional, al final para el año:
///
/// ```text
/// ┌────────────── segundo (0-59), opcional
/// │ ┌──────────── minuto (0-59)
/// │ │ ┌────────── hora (0-23)
/// │ │ │ ┌──────── día del mes (1-31)
/// │ │ │ │ ┌────── mes (1-12 o JAN-DEC)
/// │ │ │ │ │ ┌──── día de la semana (0-7 o SUN-SAT; 0 y 7 son domingo)
/// │ │ │ │ │ │ ┌── año (p. ej. 2027), opcional
/// │ │ │ │ │ │ │
/// * * * * * * *
/// ```
///
/// Cada campo admite `*` (cualquier valor), listas (`1,15`), rangos (`1-5`) y pasos (`*/15`,
/// `0-30/10`). Además, el día del mes admite `L` (último día del mes) y `W` (día laborable más
/// cercano: `15W`), y el día de la semana admite `L` (último de ese día en el mes: `5L`, el último
/// viernes) y `#` (enésimo de ese día en el mes: `MON#1`, el primer lunes). Si se indican a la vez
/// el día del mes y el de la semana, basta con que se cumpla uno de ellos, como en *cron*.
///
/// También se aceptan los apodos `@yearly` (o `@annually`), `@monthly`, `@weekly` (el domingo),
/// `@daily` y `@hourly`, que se ejecutan al principio de cada periodo.
///
/// Algunos ejemplos:
///
/// | Expresión | Se ejecuta... |
/// |--------------------|--------------------------------------------------------|
/// | `*/10 * * * *` | cada diez minutos. |
/// | `*/30 * * * * *` | cada treinta segundos. |
/// | `30 4 * * *` | todos los días a las 4:30. |
/// | `0 8-18 * * MON-FRI` | a cada hora en punto, de 8 a 18, de lunes a viernes. |
/// | `0 0 L * *` | a medianoche del último día de cada mes. |
/// | `0 9 * * MON#1` | a las 9:00 del primer lunes de cada mes. |
///
/// Las expresiones se interpretan en la zona horaria del trabajo
/// ([`Job::with_timezone()`](crate::Job::with_timezone)) o, si no tiene, en la de la aplicación
/// (`[app].timezone`). Con el cambio de hora, una ejecución en una hora que no existe (de 2:00 a
/// 3:00 en primavera, en España) se hace al empezar la hora siguiente, y una en una hora que se
/// repite (de 2:00 a 3:00 en otoño) se hace una sola vez.
///
/// # Intervalos
///
/// En texto, un intervalo es una o varias cantidades con su unidad: `ms` (milisegundos), `s`
/// (segundos), `m` (minutos), `h` (horas) y `d` (días); p. ej. `"30s"`, `"5m"` o `"1h30m"`. No se
/// interpretan en ninguna zona horaria: un día es siempre de 24 horas.
///
/// La primera ejecución llega pasado un intervalo desde que arranca la aplicación, salvo que el
/// trabajo se ejecute también al arrancar ([`Job::with_run_on_start()`]).
///
/// Con el modo externo (`mode = "external"`) no se sabe cuándo empezó o terminó la ejecución
/// anterior, que pudo hacerla otra instancia de la aplicación. Ahí los dos intervalos se cuentan
/// igual, en múltiplos exactos desde el 1 de enero de 1970 (UTC): `"@every 10m"` se ejecuta a las
/// 10:00, 10:10, 10:20... (en UTC), y `"@delay 10m"` también.
///
/// [`Job::with_run_on_start()`]: crate::Job::with_run_on_start
///
/// # Ejemplo
///
/// Los intervalos son el [`Duration`] de las fechas de PageTop, que ya incluye su preludio.
///
/// ```rust
/// # use pagetop::prelude::*;
/// # use pagetop_cron::prelude::*;
/// let nightly = Schedule::cron("30 4 * * *");
/// let queue = Schedule::fixed_delay(Duration::seconds(10));
///
/// // Desde texto, p. ej. de la configuración, con validación.
/// assert_eq!(Schedule::parse("@delay 10s").unwrap(), queue);
/// assert!(Schedule::parse("61 * * * *").is_err());
/// assert_eq!(nightly.to_string(), "30 4 * * *");
/// ```
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct Schedule(Kind);
#[derive(Clone, Debug, Eq, PartialEq)]
enum Kind {
Cron(String),
FixedRate(Duration),
FixedDelay(Duration),
}
impl Schedule {
/// Programa el trabajo con una expresión cron (ver [la sintaxis](#expresiones-cron)).
pub fn cron(expression: impl Into<String>) -> Self {
Schedule(Kind::Cron(expression.into()))
}
/// Programa el trabajo cada `period`, contado desde que **empieza** la ejecución anterior.
pub fn fixed_rate(period: Duration) -> Self {
Schedule(Kind::FixedRate(period))
}
/// Programa el trabajo `delay` después de que **termina** la ejecución anterior.
pub fn fixed_delay(delay: Duration) -> Self {
Schedule(Kind::FixedDelay(delay))
}
/// Lee y valida una programación escrita como texto.
///
/// Admite una expresión cron o un apodo como `@daily` (ver [la sintaxis](#expresiones-cron)),
/// `"@every <intervalo>"` para [`fixed_rate()`](Self::fixed_rate) y `"@delay <intervalo>"`
/// para [`fixed_delay()`](Self::fixed_delay) (ver [los intervalos](#intervalos)). Es la
/// sintaxis de la clave `schedule` de los ajustes de cada trabajo, y la misma que devuelve
/// [`to_string()`](ToString::to_string).
///
/// # Ejemplo
///
/// ```rust
/// # use pagetop::prelude::*;
/// # use pagetop_cron::prelude::*;
/// let schedule = Schedule::parse("@every 1h30m").unwrap();
/// assert_eq!(schedule, Schedule::fixed_rate(Duration::minutes(90)));
/// assert_eq!(schedule.to_string(), "@every 1h30m");
/// ```
pub fn parse(text: &str) -> Result<Self, CronError> {
let text = text.trim();
let (head, rest) = text.split_once(char::is_whitespace).unwrap_or((text, ""));
let schedule = if head.eq_ignore_ascii_case("@every") {
Schedule::fixed_rate(parse_duration(rest).map_err(|reason| invalid(text, reason))?)
} else if head.eq_ignore_ascii_case("@delay") {
Schedule::fixed_delay(parse_duration(rest).map_err(|reason| invalid(text, reason))?)
} else {
Schedule::cron(text)
};
schedule.compile()?;
Ok(schedule)
}
/// Devuelve la primera ejecución posterior a `after` según esta programación, interpretando
/// las expresiones cron en la zona horaria `tz`.
///
/// Para [`fixed_rate()`](Self::fixed_rate) y [`fixed_delay()`](Self::fixed_delay) devuelve
/// `after` más el intervalo, suponiendo que `after` es el momento en que empieza (o termina)
/// la ejecución anterior. Devuelve `None` si una expresión cron ya no se cumple nunca (p. ej.
/// la de un año ya pasado), y un error si la programación no es válida.
///
/// # Ejemplo
///
/// ```rust
/// # use pagetop::prelude::*;
/// # use pagetop_cron::prelude::*;
/// let after = "2026-01-15T00:00:00Z".parse::<DateTime<Utc>>().unwrap();
/// let next = Schedule::cron("0 9 * * *").next_after(after, Tz::Europe__Madrid).unwrap();
/// // Las 9:00 en Madrid son las 8:00 UTC en invierno.
/// assert_eq!(next.unwrap().to_rfc3339(), "2026-01-15T08:00:00+00:00");
/// ```
pub fn next_after(
&self,
after: DateTime<Utc>,
tz: Tz,
) -> Result<Option<DateTime<Utc>>, CronError> {
Ok(self.compile()?.next_after(after, tz))
}
// Valida la programación y la prepara para calcular sus ejecuciones.
pub(crate) fn compile(&self) -> Result<Trigger, CronError> {
match &self.0 {
Kind::Cron(expression) => CronParser::new()
.parse(expression)
.map(|cron| Trigger::Cron(Box::new(cron)))
.map_err(|err| invalid(expression, err.to_string())),
Kind::FixedRate(period) => Ok(Trigger::FixedRate(positive(self, *period)?)),
Kind::FixedDelay(delay) => Ok(Trigger::FixedDelay(positive(self, *delay)?)),
}
}
}
impl FromStr for Schedule {
type Err = CronError;
fn from_str(text: &str) -> Result<Self, Self::Err> {
Schedule::parse(text)
}
}
impl fmt::Display for Schedule {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match &self.0 {
Kind::Cron(expression) => f.write_str(expression),
Kind::FixedRate(period) => write!(f, "@every {}", DurationText(*period)),
Kind::FixedDelay(delay) => write!(f, "@delay {}", DurationText(*delay)),
}
}
}
// **< Trigger >************************************************************************************
// Programación ya validada, lista para calcular las ejecuciones.
pub(crate) enum Trigger {
Cron(Box<Cron>),
FixedRate(Duration),
FixedDelay(Duration),
}
impl Trigger {
// Primera ejecución posterior a `after`.
pub(crate) fn next_after(&self, after: DateTime<Utc>, tz: Tz) -> Option<DateTime<Utc>> {
match self {
Trigger::Cron(cron) => cron
.find_next_occurrence(&after.with_timezone(&tz), false)
.ok()
.map(|next| next.with_timezone(&Utc)),
Trigger::FixedRate(interval) | Trigger::FixedDelay(interval) => {
after.checked_add_signed(*interval)
}
}
}
// Primera ejecución posterior a `after` sin depender de la anterior, para el modo externo: los
// intervalos se cuentan en múltiplos exactos desde 1970 (UTC), así que todas las instancias de
// la aplicación, y cualquier proceso recién arrancado, obtienen las mismas ejecuciones.
pub(crate) fn aligned_after(&self, after: DateTime<Utc>, tz: Tz) -> Option<DateTime<Utc>> {
match self {
Trigger::Cron(_) => self.next_after(after, tz),
Trigger::FixedRate(interval) | Trigger::FixedDelay(interval) => {
let period = interval.num_milliseconds();
let next = after.timestamp_millis().div_euclid(period).checked_add(1)?;
DateTime::from_timestamp_millis(next.checked_mul(period)?)
}
}
}
// Ejecución que sigue a la programada en `at`, ya pasada, cuando el reloj marca `now`.
//
// Con `fixed_rate()` se suma el intervalo a la ejecución programada, no al momento en que
// se despertó el planificador, para que el ritmo no se retrase un poco en cada ejecución. Si
// la siguiente también ha pasado (el equipo estuvo suspendido o el reloj saltó hacia
// delante), se omiten las perdidas y se mantiene el ritmo.
pub(crate) fn following(
&self,
at: DateTime<Utc>,
now: DateTime<Utc>,
tz: Tz,
) -> Option<DateTime<Utc>> {
match self {
Trigger::FixedRate(period) => {
let next = at.checked_add_signed(*period)?;
if next > now {
return Some(next);
}
let period = period.num_milliseconds();
let missed = (now - at).num_milliseconds() / period + 1;
at.checked_add_signed(Duration::try_milliseconds(missed.checked_mul(period)?)?)
}
_ => self.next_after(at.max(now), tz),
}
}
// Intervalo de espera tras cada ejecución, sólo con `fixed_delay()`.
pub(crate) fn delay(&self) -> Option<Duration> {
match self {
Trigger::FixedDelay(delay) => Some(*delay),
_ => None,
}
}
}
// **< Funciones auxiliares >***********************************************************************
fn invalid(schedule: &str, reason: impl Into<String>) -> CronError {
CronError::InvalidSchedule {
schedule: schedule.to_owned(),
reason: reason.into(),
}
}
// El intervalo debe ser de 1 ms a 100 años.
fn positive(schedule: &Schedule, interval: Duration) -> Result<Duration, CronError> {
if interval < Duration::milliseconds(1) || interval > Duration::days(36_500) {
return Err(invalid(
&schedule.to_string(),
"the interval must be between 1 ms and 100 years",
));
}
Ok(interval)
}
// Lee un intervalo como "30s", "5m" o "1h 30m".
fn parse_duration(text: &str) -> Result<Duration, String> {
const TOO_LARGE: &str = "interval too large";
let text = text.trim();
if text.is_empty() {
return Err("missing interval, e.g. \"5m\"".to_owned());
}
let mut total: i64 = 0;
let mut rest = text;
while !rest.is_empty() {
let digits = rest
.find(|c: char| !c.is_ascii_digit())
.unwrap_or(rest.len());
if digits == 0 {
return Err(format!("expected a number in \"{rest}\""));
}
let amount: i64 = rest[..digits].parse().map_err(|_| TOO_LARGE.to_owned())?;
rest = &rest[digits..];
let unit = rest
.find(|c: char| !c.is_ascii_alphabetic())
.unwrap_or(rest.len());
let millis = match &rest[..unit] {
"ms" => 1,
"s" => 1_000,
"m" => 60_000,
"h" => 3_600_000,
"d" => 86_400_000,
"" => return Err(format!("missing unit after {amount} (ms, s, m, h or d)")),
other => return Err(format!("unknown unit \"{other}\" (ms, s, m, h or d)")),
};
total = amount
.checked_mul(millis)
.and_then(|part| total.checked_add(part))
.ok_or_else(|| TOO_LARGE.to_owned())?;
rest = rest[unit..].trim_start();
}
Duration::try_milliseconds(total).ok_or_else(|| TOO_LARGE.to_owned())
}
// Escribe un intervalo con la sintaxis de `parse_duration()`, p. ej. "1h30m".
struct DurationText(Duration);
impl fmt::Display for DurationText {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
let mut millis = self.0.num_milliseconds();
if millis == 0 {
return f.write_str("0s");
}
if millis < 0 {
f.write_str("-")?;
millis = millis.saturating_abs();
}
for (unit, size) in [
("d", 86_400_000),
("h", 3_600_000),
("m", 60_000),
("s", 1_000),
("ms", 1),
] {
if millis >= size {
write!(f, "{}{unit}", millis / size)?;
millis %= size;
}
}
Ok(())
}
}

View file

@ -0,0 +1,956 @@
use pagetop::prelude::*;
use tokio::sync::{Notify, watch};
use crate::config::{CronMode, JobSettings, SETTINGS};
use crate::schedule::Trigger;
use crate::{AfterJobRun, CronError, CronJobs, Job, JobContext, JobOutcome, JobRun, JobStatus};
use crate::{Overlap, RunTrigger, Schedule};
use std::any::Any;
use std::collections::HashSet;
use std::panic::AssertUnwindSafe;
use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
use std::sync::{Arc, LazyLock, Mutex, MutexGuard, OnceLock, PoisonError};
use std::time::Instant;
/// Ruta de las llamadas externas que ejecutan los trabajos pendientes.
///
/// `POST /cron` con la cabecera `Authorization: Bearer {trigger_token}`, sólo para
/// `mode = "external"`.
pub const TRIGGER_PATH: &str = "/cron";
// Longitud mínima de `cron.trigger_token`.
const MIN_TOKEN_LEN: usize = 16;
// Espera máxima de una sola vez hasta la próxima ejecución. Al despertar se vuelve a calcular lo
// que falta con el reloj del sistema, así que un cambio de hora del equipo (o una suspensión, en
// la que no avanzan los temporizadores de Tokio) retrasa las ejecuciones como mucho este tiempo.
const MAX_NAP: std::time::Duration = std::time::Duration::from_secs(60);
// Trabajos declarados, construidos una sola vez al inicializar la extensión: preparar de nuevo la
// aplicación en el mismo proceso (las pruebas lo hacen) reutiliza los ya construidos.
static REGISTRY: OnceLock<Registry> = OnceLock::new();
// Evita lanzar dos veces el planificador.
static STARTED: AtomicBool = AtomicBool::new(false);
// Pasa a `true` al detener la aplicación: los bucles del planificador terminan y los trabajos lo
// ven en `JobContext::is_stopping()`.
static STOP: LazyLock<watch::Sender<bool>> = LazyLock::new(|| watch::Sender::new(false));
// Ejecuciones en curso de todos los trabajos, para esperarlas al detener la aplicación.
static ACTIVE: AtomicUsize = AtomicUsize::new(0);
static IDLE: Notify = Notify::const_new();
struct Registry {
entries: Vec<Arc<Entry>>,
}
// Un trabajo con sus ajustes ya aplicados y su estado.
struct Entry {
job: Job,
schedule: Schedule,
trigger: Trigger,
timezone: Tz,
timeout: Option<Duration>,
enabled: bool,
running: AtomicUsize,
state: Mutex<State>,
}
#[derive(AutoDefault)]
struct State {
next_run: Option<DateTime<Utc>>,
// Sólo en el modo externo: si falta la ejecución del arranque, y el último intervalo atendido.
pending_start: bool,
last_window: Option<DateTime<Utc>>,
last_run: Option<JobRun>,
runs: u64,
failures: u64,
skipped: u64,
}
// **< Construcción del registro >******************************************************************
// Recoge y valida los trabajos declarados. Un error detiene el arranque de la aplicación.
pub(crate) fn initialize() -> Result<(), CronError> {
if REGISTRY.get().is_none() {
let registry = build(CronJobs::collect(), Utc::now())?;
for entry in &registry.entries {
trace::debug!(
"Cron job \"{}\": \"{}\" ({}){}",
entry.job.key(),
entry.schedule,
entry.timezone,
if entry.enabled { "" } else { ", disabled" }
);
}
let _ = REGISTRY.set(registry);
}
Ok(())
}
fn build(jobs: Vec<Job>, now: DateTime<Utc>) -> Result<Registry, CronError> {
check_external_settings()?;
let default_tz = Timezone::default_tz();
let mut keys = HashSet::with_capacity(jobs.len());
let mut entries = Vec::with_capacity(jobs.len());
for job in jobs {
let key = job.key().to_string();
if !is_valid_key(&key) {
return Err(CronError::InvalidKey(key));
}
let entry = Entry::new(job, SETTINGS.jobs.get(&key), default_tz, now).map_err(|err| {
CronError::InvalidJob {
key: key.clone(),
source: Box::new(err),
}
})?;
if !keys.insert(key.clone()) {
return Err(CronError::DuplicateJob(key));
}
entries.push(Arc::new(entry));
}
for key in SETTINGS.jobs.keys() {
if !keys.contains(key) {
trace::warn!("Unknown cron job \"{key}\" in [cron.jobs], ignored. Check settings");
}
}
entries.sort_by(|a, b| a.job.key().cmp(b.job.key()));
Ok(Registry { entries })
}
fn is_valid_key(key: &str) -> bool {
key.starts_with(|c: char| c.is_ascii_lowercase() || c.is_ascii_digit())
&& key
.chars()
.all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || matches!(c, '_' | '-' | '.'))
}
// El modo externo necesita una clave larga y que se pueda escribir tal cual en la cabecera, y un
// intervalo entre llamadas válido.
fn check_external_settings() -> Result<(), CronError> {
if SETTINGS.mode != CronMode::External {
return Ok(());
}
let valid = trigger_token().is_some_and(|token| {
token.len() >= MIN_TOKEN_LEN
&& token
.chars()
.all(|c| c.is_ascii_alphanumeric() || matches!(c, '-' | '_'))
});
if !valid {
return Err(CronError::InvalidSetting {
key: "cron.trigger_token",
reason: format!(
"mode \"external\" needs a secret token of at least {MIN_TOKEN_LEN} letters, \
digits, '-' or '_'"
),
});
}
if trigger_interval().is_none() {
return Err(CronError::InvalidSetting {
key: "cron.trigger_interval_secs",
reason: "must be between 1 second and 100 years".to_owned(),
});
}
Ok(())
}
fn trigger_token() -> Option<&'static str> {
SETTINGS.trigger_token.as_deref().and_then(util::non_blank)
}
fn trigger_interval() -> Option<Duration> {
let secs = i64::try_from(SETTINGS.trigger_interval_secs).ok()?;
Duration::try_seconds(secs)
.filter(|interval| *interval >= Duration::seconds(1) && *interval <= Duration::days(36_500))
}
// Final del último intervalo completo de llamadas externas, en múltiplos exactos de `interval`
// desde 1970 (UTC): una llamada a las 4:30:20, con intervalos de un minuto, atiende el que va de
// las 4:29:00 a las 4:30:00, y lo mismo haría con cualquier otra instancia de la aplicación.
fn window_end(now: DateTime<Utc>, interval: Duration) -> Option<DateTime<Utc>> {
let size = interval.num_milliseconds();
DateTime::from_timestamp_millis(now.timestamp_millis().div_euclid(size).checked_mul(size)?)
}
// Compara la clave recibida con la configurada en un tiempo que no depende de dónde difieren, para
// no dar pistas sobre la clave a quien mida los tiempos de respuesta.
pub(crate) fn token_matches(given: &str) -> bool {
let Some(expected) = trigger_token() else {
return false;
};
let (given, expected) = (given.as_bytes(), expected.as_bytes());
given.len() == expected.len()
&& given
.iter()
.zip(expected)
.fold(0, |diff, (a, b)| diff | (a ^ b))
== 0
}
impl Entry {
fn new(
job: Job,
settings: Option<&JobSettings>,
default_tz: Tz,
now: DateTime<Utc>,
) -> Result<Self, CronError> {
let schedule = match settings
.and_then(|s| s.schedule.as_deref())
.and_then(util::non_blank)
{
Some(text) => Schedule::parse(text)?,
None => job.schedule().clone(),
};
let trigger = schedule.compile()?;
let timeout = match settings.and_then(|s| s.timeout_secs) {
Some(0) => None,
Some(secs) => Some(
i64::try_from(secs)
.ok()
.and_then(Duration::try_seconds)
.ok_or_else(|| CronError::InvalidSetting {
key: "cron.jobs.timeout_secs",
reason: "too large".to_owned(),
})?,
),
None => job.timeout(),
};
if timeout.is_some_and(|timeout| timeout <= Duration::zero()) {
return Err(CronError::InvalidSetting {
key: "timeout",
reason: "must be greater than zero".to_owned(),
});
}
let enabled = settings.is_none_or(|s| s.enabled);
let timezone = job.timezone().unwrap_or(default_tz);
// Con el modo externo, la próxima ejecución se conoce desde el arranque; la del arranque,
// si la hay, la hace la primera llamada.
let external = enabled && SETTINGS.mode == CronMode::External;
let pending_start = external && job.run_on_start();
let next_run = match (external, pending_start) {
(true, true) => Some(now),
(true, false) => trigger.aligned_after(now, timezone),
(false, _) => None,
};
Ok(Entry {
job,
schedule,
trigger,
timezone,
timeout,
enabled,
running: AtomicUsize::new(0),
state: Mutex::new(State {
next_run,
pending_start,
..State::default()
}),
})
}
// Decide si una llamada externa que atiende el intervalo que termina en `end` ejecuta el
// trabajo, y con qué causa y hora programada. Se decide y se anota en un solo bloqueo, para que
// dos llamadas simultáneas no lancen la misma ejecución. Un intervalo ya atendido, o anterior
// (el reloj del sistema retrocedió), no vuelve a ejecutar nada.
fn take_due(
&self,
end: DateTime<Utc>,
interval: Duration,
) -> Option<(RunTrigger, Option<DateTime<Utc>>)> {
let mut state = self.state();
let startup = std::mem::take(&mut state.pending_start);
let mut at = None;
if state.last_window.is_none_or(|last| last < end) {
state.last_window = Some(end);
at = self
.trigger
.aligned_after(end - interval, self.timezone)
.filter(|at| *at <= end);
state.next_run = self.trigger.aligned_after(end, self.timezone);
}
match (at, startup) {
(Some(at), _) => Some((RunTrigger::External, Some(at))),
(None, true) => Some((RunTrigger::Startup, None)),
(None, false) => None,
}
}
// Un `panic!` sólo puede ocurrir fuera de la sección protegida (se ejecutan en otra tarea),
// así que el estado sigue siendo coherente aunque el `Mutex` quede envenenado.
fn state(&self) -> MutexGuard<'_, State> {
self.state.lock().unwrap_or_else(PoisonError::into_inner)
}
fn set_next_run(&self, at: Option<DateTime<Utc>>) {
self.state().next_run = at;
}
// Reserva una ejecución, salvo que el trabajo no admita ejecuciones simultáneas y ya haya una.
fn try_begin(self: &Arc<Self>) -> Option<RunGuard> {
let began = match self.job.overlap() {
Overlap::Skip => self
.running
.compare_exchange(0, 1, Ordering::SeqCst, Ordering::SeqCst)
.is_ok(),
Overlap::Allow => {
self.running.fetch_add(1, Ordering::SeqCst);
true
}
};
if !began {
return None;
}
ACTIVE.fetch_add(1, Ordering::SeqCst);
Some(RunGuard(Arc::clone(self)))
}
fn skip(&self) {
self.state().skipped += 1;
trace::warn!(
"Cron job \"{}\" skipped: the previous run has not finished",
self.job.key()
);
}
fn record(&self, run: &JobRun) {
let mut state = self.state();
state.runs += 1;
if !run.outcome().is_success() {
state.failures += 1;
}
state.last_run = Some(run.clone());
}
fn status(&self) -> JobStatus {
let state = self.state();
JobStatus {
key: self.job.key().clone(),
title: self.job.title().clone(),
schedule: self.schedule.clone(),
timezone: self.timezone,
enabled: self.enabled,
running: self.running.load(Ordering::SeqCst),
next_run: state.next_run,
last_run: state.last_run.clone(),
runs: state.runs,
failures: state.failures,
skipped: state.skipped,
}
}
}
// Ejecución reservada; al soltarla se libera la reserva.
struct RunGuard(Arc<Entry>);
impl Drop for RunGuard {
fn drop(&mut self) {
self.0.running.fetch_sub(1, Ordering::SeqCst);
if ACTIVE.fetch_sub(1, Ordering::SeqCst) == 1 {
IDLE.notify_waiters();
}
}
}
// **< API pública >********************************************************************************
/// Devuelve el estado de todos los trabajos declarados, ordenados por su clave.
///
/// Vacío si la aplicación aún no se ha preparado.
pub fn jobs() -> Vec<JobStatus> {
REGISTRY
.get()
.map(|registry| registry.entries.iter().map(|e| e.status()).collect())
.unwrap_or_default()
}
/// Devuelve el estado de un trabajo por su clave, o `None` si no existe.
pub fn job(key: impl AsRef<str>) -> Option<JobStatus> {
find(key.as_ref()).ok().map(|entry| entry.status())
}
/// Ejecuta un trabajo ahora mismo y espera a que termine.
///
/// Funciona con cualquier modo de la sección `[cron]` y aunque la configuración desactive el
/// trabajo, y también en las pruebas, donde el planificador no se pone en marcha. Respeta el tiempo
/// máximo del trabajo, registra la ejecución en su estado y despacha [`AfterJobRun`], como
/// cualquier otra ejecución. No cambia su próxima ejecución programada.
///
/// Devuelve el informe de la ejecución, también si el trabajo falla: el error sólo indica que no se
/// ha podido ejecutar, porque no existe ([`CronError::UnknownJob`]), porque ya se está ejecutando y
/// no admite ejecuciones simultáneas ([`CronError::AlreadyRunning`]) o porque la aplicación aún no
/// se ha preparado ([`CronError::NotInitialized`]).
///
/// # Ejemplo
///
/// ```rust,no_run
/// # use pagetop::prelude::*;
/// # use pagetop_cron::prelude::*;
/// # async fn example() -> Result<(), CronError> {
/// let run = pagetop_cron::run_now("shop.cleanup").await?;
/// assert!(run.outcome().is_success());
/// # Ok(())
/// # }
/// ```
pub async fn run_now(key: impl AsRef<str>) -> Result<JobRun, CronError> {
let key = key.as_ref();
let entry = find(key)?;
let guard = entry
.try_begin()
.ok_or_else(|| CronError::AlreadyRunning(key.to_owned()))?;
// En su propia tarea: si se abandona la espera (p. ej. se cierra la conexión de la petición
// que la pidió), la ejecución sigue con su tiempo máximo y su reserva, y se registra igual.
match tokio::spawn(execute(guard, RunTrigger::Manual, None)).await {
Ok(run) => Ok(run),
Err(err) => std::panic::resume_unwind(err.into_panic()),
}
}
/// Ejecuta los trabajos programados en el último intervalo de llamadas externas.
///
/// Espera a que terminen y devuelve el informe de cada ejecución. Es lo que hace la ruta
/// `POST /cron` con `mode = "external"`, disponible por si la aplicación quiere ofrecer otra forma
/// de llamarlo (p. ej. una orden de su propia línea de comandos). Sólo funciona en ese modo: en los
/// demás no hace nada y devuelve `0`, porque las ejecuciones las decide el planificador interno o
/// nadie.
///
/// Cada llamada atiende el último intervalo completo de `cron.trigger_interval_secs` (un minuto
/// por defecto), contado en múltiplos exactos desde 1970 (UTC), y ejecuta una vez cada trabajo
/// programado en él; una llamada a las 4:30:20 ejecuta lo programado de las 4:29:00 (excluido) a
/// las 4:30:00. No depende de lo que recuerde cada proceso: con varias instancias tras un
/// balanceador, cada trabajo se ejecuta una sola vez aunque cada llamada llegue a una instancia
/// distinta, y una instancia arrancada por la propia llamada ejecuta igualmente lo que toca. A
/// cambio, el programa externo debe llamar una vez, y sólo una, en cada intervalo: si falta una
/// llamada se pierden sus ejecuciones, y si sobra, dos instancias distintas pueden repetirlas.
///
/// La precisión es la del intervalo: con uno de un minuto, un trabajo de cada diez segundos se
/// ejecuta una vez por minuto. Los trabajos con
/// [`with_run_on_start()`](crate::Job::with_run_on_start) se ejecutan además en la primera llamada
/// que recibe cada proceso.
///
/// Los trabajos se ejecutan a la vez, cada uno en su propia tarea, y la función espera a que
/// terminen todos. Así una plataforma que sólo da CPU mientras se atiende una petición la mantiene
/// hasta el final. Si se abandona la espera (p. ej. el programa externo cierra la conexión), los
/// trabajos siguen igualmente hasta terminar o agotar su tiempo máximo.
pub async fn run_due() -> Vec<JobRun> {
if SETTINGS.mode != CronMode::External {
trace::warn!("Cron run_due() ignored: [cron].mode is not \"external\"");
return Vec::new();
}
let (Some(registry), Some(interval)) = (REGISTRY.get(), trigger_interval()) else {
return Vec::new();
};
let Some(end) = window_end(Utc::now(), interval) else {
return Vec::new();
};
let mut tasks = Vec::new();
for entry in registry.entries.iter().filter(|e| e.enabled) {
let Some((trigger, at)) = entry.take_due(end, interval) else {
continue;
};
let Some(guard) = entry.try_begin() else {
entry.skip();
continue;
};
tasks.push(tokio::spawn(execute(guard, trigger, at)));
}
let mut runs = Vec::with_capacity(tasks.len());
for task in tasks {
// `execute()` ya aísla los `panic!` del trabajo; sólo falla si se detiene el *runtime*.
if let Ok(run) = task.await {
runs.push(run);
}
}
runs
}
fn find(key: &str) -> Result<&'static Arc<Entry>, CronError> {
REGISTRY
.get()
.ok_or(CronError::NotInitialized)?
.entries
.iter()
.find(|entry| entry.job.key() == key)
.ok_or_else(|| CronError::UnknownJob(key.to_owned()))
}
// **< Planificador >*******************************************************************************
// Pone en marcha el planificador según el modo configurado. Sólo una vez por proceso.
pub(crate) fn start() {
let Some(registry) = REGISTRY.get() else {
return;
};
if STARTED.swap(true, Ordering::SeqCst) {
return;
}
let total = registry.entries.len();
let enabled = registry.entries.iter().filter(|e| e.enabled).count();
match SETTINGS.mode {
CronMode::Internal => {
for entry in registry.entries.iter().filter(|e| e.enabled) {
tokio::spawn(job_loop(Arc::clone(entry)));
}
trace::info!("Cron scheduler started with {enabled} of {total} jobs");
}
CronMode::External => trace::info!(
"Cron jobs ({enabled} of {total}) run on authorized calls to POST {TRIGGER_PATH}"
),
CronMode::Off => {
trace::info!("Cron jobs ({total}) only run on demand: [cron].mode is \"off\"");
}
}
}
// Ejecuta un trabajo según su programación hasta que se detiene la aplicación.
async fn job_loop(entry: Arc<Entry>) {
let mut stop = STOP.subscribe();
if entry.job.run_on_start() {
launch(&entry, RunTrigger::Startup, None).await;
}
let mut next = entry.trigger.next_after(Utc::now(), entry.timezone);
while let Some(at) = next {
entry.set_next_run(Some(at));
if !sleep_until(at, &mut stop).await {
break;
}
launch(&entry, RunTrigger::Schedule, Some(at)).await;
next = entry.trigger.following(at, Utc::now(), entry.timezone);
}
if next.is_none() {
trace::info!(
"Cron job \"{}\" has no more runs scheduled",
entry.job.key()
);
}
entry.set_next_run(None);
}
// Lanza una ejecución. Con `fixed_delay()` espera a que termine, porque la siguiente se cuenta
// desde entonces; con el resto, la ejecución sigue en su propia tarea.
async fn launch(entry: &Arc<Entry>, trigger: RunTrigger, at: Option<DateTime<Utc>>) {
let Some(guard) = entry.try_begin() else {
entry.skip();
return;
};
if entry.trigger.delay().is_some() {
execute(guard, trigger, at).await;
} else {
tokio::spawn(execute(guard, trigger, at));
}
}
// Espera hasta `at` según el reloj del sistema. Devuelve `false` si la aplicación se detiene antes.
async fn sleep_until(at: DateTime<Utc>, stop: &mut watch::Receiver<bool>) -> bool {
loop {
if *stop.borrow() {
return false;
}
let remaining = match (at - Utc::now()).to_std() {
Ok(remaining) if !remaining.is_zero() => remaining,
_ => return true,
};
tokio::select! {
() = tokio::time::sleep(remaining.min(MAX_NAP)) => {}
changed = stop.changed() => {
if changed.is_err() {
return false;
}
}
}
}
}
// Ejecuta el trabajo en una tarea propia, que aísla sus `panic!` y permite cancelarlo si supera su
// tiempo máximo, y registra el resultado.
async fn execute(guard: RunGuard, trigger: RunTrigger, at: Option<DateTime<Utc>>) -> JobRun {
let entry = Arc::clone(&guard.0);
let key = entry.job.key().clone();
trace::debug!("Cron job \"{key}\" started ({})", trigger.as_str());
let cx = JobContext::new(key.clone(), trigger, at, STOP.subscribe());
let run = entry.job.runner();
let started_at = Utc::now();
let clock = Instant::now();
let mut task = tokio::spawn(async move { run(cx).await });
let joined = match entry.timeout.and_then(|timeout| timeout.to_std().ok()) {
Some(limit) => match tokio::time::timeout(limit, &mut task).await {
Ok(joined) => Some(joined),
Err(_) => {
task.abort();
None
}
},
None => Some((&mut task).await),
};
let timed_out = joined.is_none();
let outcome = match joined {
None => JobOutcome::TimedOut,
Some(Ok(Ok(()))) => JobOutcome::Succeeded,
Some(Ok(Err(err))) => JobOutcome::Failed(error_chain(err.as_ref())),
Some(Err(err)) if err.is_panic() => JobOutcome::Panicked(panic_message(err.into_panic())),
Some(Err(_)) => JobOutcome::Failed("cancelled".to_owned()),
};
let duration = Duration::from_std(clock.elapsed()).unwrap_or_default();
let run = JobRun::new(key, trigger, started_at, duration, outcome);
entry.record(&run);
match run.outcome() {
JobOutcome::Succeeded => trace::debug!(
"Cron job \"{}\" succeeded in {} ms",
run.key(),
duration.num_milliseconds()
),
outcome => trace::error!(
"Cron job \"{}\" {outcome} after {} ms",
run.key(),
duration.num_milliseconds()
),
}
// Un `panic!` en una acción no debe detener el bucle del trabajo ni su reprogramación.
if let Err(payload) = std::panic::catch_unwind(AssertUnwindSafe(|| AfterJobRun::dispatch(&run)))
{
trace::error!(
"AfterJobRun action panicked for cron job \"{}\": {}",
run.key(),
panic_message(payload)
);
}
if timed_out {
// Cancelar sólo surte efecto en el siguiente `.await` del trabajo: uno que no llega a
// ninguno (un cálculo largo, una llamada bloqueante) sigue en marcha. Mientras siga, la
// ejecución cuenta como en curso, para no solaparla con la siguiente ni dejar de esperarla
// al detener la aplicación.
tokio::spawn(async move {
let _ = task.await;
drop(guard);
});
} else {
drop(guard);
}
run
}
// Mensaje del error con el de sus causas. Muchos errores terminan ya con el texto de su causa, así
// que se omite cada causa con la que ya termina el mensaje.
fn error_chain(err: &(dyn std::error::Error + 'static)) -> String {
let mut message = err.to_string();
let mut source = err.source();
while let Some(cause) = source {
let cause_text = cause.to_string();
if !message.ends_with(&cause_text) {
message.push_str(": ");
message.push_str(&cause_text);
}
source = cause.source();
}
message
}
// Se desreferencia la caja para que `downcast_ref()` sea el de `dyn Any` y no el de `AnyCast`, que
// se aplicaría a la propia `Box`.
fn panic_message(payload: Box<dyn Any + Send>) -> String {
match payload.downcast::<String>() {
Ok(message) => *message,
Err(payload) => (*payload).downcast_ref::<&str>().map_or_else(
|| "unknown panic".to_owned(),
|message| (*message).to_owned(),
),
}
}
// Avisa a los trabajos de que la aplicación se detiene y espera, con un tiempo máximo, a que
// terminen las ejecuciones en curso.
pub(crate) async fn shutdown() {
STOP.send_replace(true);
let active = ACTIVE.load(Ordering::SeqCst);
if active == 0 {
return;
}
let limit = SETTINGS.shutdown_timeout_secs;
trace::info!("Waiting up to {limit} s for {active} running cron jobs to finish");
let idle = async {
loop {
let notified = IDLE.notified();
if ACTIVE.load(Ordering::SeqCst) == 0 {
break;
}
notified.await;
}
};
if tokio::time::timeout(std::time::Duration::from_secs(limit), idle)
.await
.is_err()
{
let running: Vec<String> = jobs()
.into_iter()
.filter(|job| job.running() > 0)
.map(|job| job.key().to_string())
.collect();
trace::warn!(
"Cron jobs still running after {limit} s, stopping anyway: {}",
running.join(", ")
);
}
}
#[cfg(test)]
mod tests {
use super::*;
// Settings come from this crate's `config/common.toml` (external mode, Madrid timezone).
fn load_settings() {
SETTINGS.load().unwrap();
}
async fn noop(_cx: JobContext) -> crate::JobResult {
Ok(())
}
fn job(key: &'static str, schedule: &str) -> Job {
Job::new(key, Schedule::cron(schedule), noop)
}
fn at(text: &str) -> DateTime<Utc> {
text.parse().unwrap()
}
fn build_error(jobs: Vec<Job>) -> CronError {
load_settings();
match build(jobs, Utc::now()) {
Ok(_) => panic!("build should fail"),
Err(err) => err,
}
}
#[pagetop::test]
async fn keys_must_be_lowercase_and_simple() {
for key in ["shop.cleanup", "mail_queue", "a-b.c_d", "0job"] {
assert!(is_valid_key(key), "{key}");
}
for key in [
"",
"Shop.cleanup",
".hidden",
"-x",
"with space",
"a/b",
"a:b",
] {
assert!(!is_valid_key(key), "{key}");
}
assert!(matches!(
build_error(vec![job("Bad", "* * * * *")]),
CronError::InvalidKey(key) if key == "Bad"
));
}
#[pagetop::test]
async fn duplicated_keys_stop_the_build() {
let err = build_error(vec![job("a.job", "* * * * *"), job("a.job", "@daily")]);
assert!(matches!(err, CronError::DuplicateJob(key) if key == "a.job"));
}
#[pagetop::test]
async fn invalid_schedules_and_timeouts_name_the_job() {
let err = build_error(vec![job("a.job", "61 * * * *")]);
assert_eq!(err.to_string(), "invalid job \"a.job\"");
let CronError::InvalidJob { source, .. } = err else {
panic!("unexpected error");
};
assert!(matches!(*source, CronError::InvalidSchedule { .. }));
let err = build_error(vec![job("a.job", "@daily").with_timeout(Duration::zero())]);
assert!(matches!(err, CronError::InvalidJob { .. }));
}
#[pagetop::test]
async fn settings_override_the_declared_job() {
load_settings();
let now = at("2026-01-15T10:00:00Z");
let registry = build(
vec![
job("test.overridden", "0 * * * *").with_timeout(Duration::minutes(1)),
job("test.disabled", "* * * * *"),
job("test.plain", "0 9 * * *"),
job("test.startup", "@daily").with_run_on_start(),
],
now,
)
.unwrap();
let entry = |key: &str| {
registry
.entries
.iter()
.find(|e| e.job.key() == key)
.unwrap()
};
let overridden = entry("test.overridden");
assert_eq!(overridden.schedule.to_string(), "@delay 1m30s");
assert_eq!(overridden.timeout, None);
// External mode: the first run is computed from startup.
assert_eq!(
overridden.state().next_run,
Some(at("2026-01-15T10:01:30Z"))
);
let disabled = entry("test.disabled");
assert!(!disabled.enabled);
assert_eq!(disabled.state().next_run, None);
// 9:00 in Madrid is 8:00 UTC in winter: already past, so tomorrow.
let plain = entry("test.plain");
assert_eq!(plain.timezone, Tz::Europe__Madrid);
assert_eq!(plain.state().next_run, Some(at("2026-01-16T08:00:00Z")));
assert_eq!(entry("test.startup").state().next_run, Some(now));
// Sorted by key.
let keys: Vec<_> = registry
.entries
.iter()
.map(|e| e.job.key().to_string())
.collect();
assert_eq!(
keys,
[
"test.disabled",
"test.overridden",
"test.plain",
"test.startup"
]
);
}
#[pagetop::test]
async fn external_calls_run_each_scheduled_run_once() {
load_settings();
let minute = Duration::minutes(1);
let registry = build(
vec![
job("test.plain", "0 9 * * *"),
Job::new(
"test.rate",
Schedule::fixed_rate(Duration::minutes(10)),
noop,
),
job("test.startup", "@daily").with_run_on_start(),
],
at("2026-01-15T07:50:00Z"),
)
.unwrap();
let entry = |key: &str| {
registry
.entries
.iter()
.find(|e| e.job.key() == key)
.unwrap()
};
// A call at 8:00:20 handles the minute that ends at 8:00:00 UTC (9:00 in Madrid).
let end = window_end(at("2026-01-15T08:00:20.500Z"), minute).unwrap();
assert_eq!(end, at("2026-01-15T08:00:00Z"));
let plain = entry("test.plain");
assert_eq!(
plain.take_due(end, minute),
Some((RunTrigger::External, Some(end)))
);
// A second call for the same minute, or for an earlier one (clock set back), runs nothing.
assert_eq!(plain.take_due(end, minute), None);
assert_eq!(plain.take_due(end - minute, minute), None);
assert_eq!(plain.take_due(end + minute, minute), None);
assert_eq!(plain.state().next_run, Some(at("2026-01-16T08:00:00Z")));
// Intervals count from 1970, so every instance agrees on their runs.
let rate = entry("test.rate");
assert_eq!(rate.state().next_run, Some(end));
assert_eq!(
rate.take_due(end, minute),
Some((RunTrigger::External, Some(end)))
);
assert_eq!(rate.take_due(end + minute, minute), None);
let later = end + Duration::minutes(10);
assert_eq!(
rate.take_due(later, minute),
Some((RunTrigger::External, Some(later)))
);
// A process started by the call itself still runs what is due.
let woken = build(
vec![job("test.plain", "0 9 * * *")],
at("2026-01-15T08:00:00.300Z"),
)
.unwrap();
assert_eq!(
woken.entries[0].take_due(end, minute),
Some((RunTrigger::External, Some(end)))
);
// The startup run only happens on the first call.
let startup = entry("test.startup");
assert_eq!(
startup.take_due(end, minute),
Some((RunTrigger::Startup, None))
);
assert_eq!(startup.take_due(end + minute, minute), None);
}
#[pagetop::test]
async fn only_the_configured_token_matches() {
load_settings();
assert!(token_matches("test-token-0123456789"));
assert!(!token_matches("test-token-012345678"));
assert!(!token_matches("test-token-0123456780"));
assert!(!token_matches(""));
}
#[pagetop::test]
async fn fixed_rate_keeps_its_pace() {
let trigger = Schedule::fixed_rate(Duration::seconds(10))
.compile()
.unwrap();
let start = at("2026-01-15T10:00:00Z");
let tz = Tz::UTC;
// Woken up a bit late: the next run keeps the pace, it does not drift.
let late = start + Duration::milliseconds(15);
assert_eq!(
trigger.following(start, late, tz),
Some(at("2026-01-15T10:00:10Z"))
);
// Several runs missed (e.g. a suspended machine): they are skipped, keeping the pace.
let much_later = start + Duration::seconds(35);
assert_eq!(
trigger.following(start, much_later, tz),
Some(at("2026-01-15T10:00:40Z"))
);
// Billions of missed runs (1 ms pace, 30 days asleep) keep the pace without overflowing.
let trigger = Schedule::fixed_rate(Duration::milliseconds(1))
.compile()
.unwrap();
let asleep = start + Duration::days(30) + Duration::microseconds(500);
assert_eq!(
trigger.following(start, asleep, tz),
Some(start + Duration::days(30) + Duration::milliseconds(1))
);
}
#[pagetop::test]
async fn fixed_delay_counts_from_the_end_of_the_run() {
let trigger = Schedule::fixed_delay(Duration::seconds(10))
.compile()
.unwrap();
let start = at("2026-01-15T10:00:00Z");
let finished = start + Duration::seconds(25);
assert_eq!(
trigger.following(start, finished, Tz::UTC),
Some(at("2026-01-15T10:00:35Z"))
);
}
}

View file

@ -0,0 +1,42 @@
use pagetop::prelude::*;
use crate::{JobRun, Schedule};
/// Estado de un trabajo: programación efectiva, próxima ejecución y cómo fue la última.
///
/// Lo devuelven [`jobs()`](crate::jobs) y [`job()`](crate::job), p. ej. para mostrar los trabajos
/// en un panel de administración o comprobarlos en las pruebas. Es una copia: no cambia aunque el
/// trabajo se vuelva a ejecutar.
#[derive(Clone, Debug, Getters)]
pub struct JobStatus {
/// Devuelve la clave del trabajo.
pub(crate) key: CowStr,
/// Devuelve el título del trabajo (`Lc::none()` si no tiene).
pub(crate) title: Lc,
/// Devuelve la programación efectiva, la de la configuración si la cambia.
pub(crate) schedule: Schedule,
/// Devuelve la zona horaria en la que se interpreta la programación.
#[getters(copy)]
pub(crate) timezone: Tz,
/// Devuelve si el trabajo se ejecuta de forma automática (`false` si lo desactiva la
/// configuración).
#[getters(copy)]
pub(crate) enabled: bool,
/// Devuelve cuántas ejecuciones del trabajo están en curso.
#[getters(copy)]
pub(crate) running: usize,
/// Devuelve la próxima ejecución programada, en UTC, si la hay.
#[getters(copy)]
pub(crate) next_run: Option<DateTime<Utc>>,
/// Devuelve el informe de la última ejecución terminada, si la hay.
pub(crate) last_run: Option<JobRun>,
/// Devuelve cuántas ejecuciones han terminado desde que arrancó la aplicación.
#[getters(copy)]
pub(crate) runs: u64,
/// Devuelve cuántas de esas ejecuciones no terminaron bien (error, tiempo agotado o `panic!`).
#[getters(copy)]
pub(crate) failures: u64,
/// Devuelve cuántas ejecuciones se omitieron porque la anterior aún no había terminado.
#[getters(copy)]
pub(crate) skipped: u64,
}