- 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()`.
956 lines
34 KiB
Rust
956 lines
34 KiB
Rust
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 ®istry.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"))
|
|
);
|
|
}
|
|
}
|