- 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()`.
376 lines
15 KiB
Rust
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(())
|
|
}
|
|
}
|