pagetop/extensions/pagetop-cron/src/scheduler.rs
Manuel Cillero 698b917fb1 ➖ Sustituye parking_lot por std::sync
PageTop ya no lo necesita como dependencia directa: `std::sync` cubre
los bloqueos del contexto, los temas y las trazas. No se detecta pérdida
de rendimiento en ningún caso.

Usa `unwrap()` en los bloqueos, también en las extensiones, porque sus
secciones exclusivas no pueden provocar panic. Sólo pagetop-cron ignora
el envenenamiento, porque calcula fechas con el bloqueo tomado.
2026-11-09 07:22:18 +01:00

957 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 &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,
}
}
// Los trabajos se ejecutan en otra tarea, fuera de la sección protegida. Dentro sólo podría
// fallar el cálculo de fechas de `take_due()`, que no deja el estado incoherente, así que un
// `Mutex` envenenado no debe detener el trabajo.
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"))
);
}
}