pagetop/extensions/pagetop-cron/src/schedule.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

376 lines
15 KiB
Rust

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