pagetop/extensions/pagetop-cron/src/run.rs
Manuel Cillero 86d9f0e213 ✨ (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()`.
2026-10-28 06:52:42 +01:00

165 lines
4.9 KiB
Rust

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