✨ (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()`.
This commit is contained in:
parent
4c3f4dab1b
commit
86d9f0e213
22 changed files with 3678 additions and 1 deletions
24
extensions/pagetop-cron/Cargo.toml
Normal file
24
extensions/pagetop-cron/Cargo.toml
Normal file
|
|
@ -0,0 +1,24 @@
|
|||
[package]
|
||||
name = "pagetop-cron"
|
||||
version = "0.1.0"
|
||||
|
||||
description = """
|
||||
Programación de tareas para aplicaciones PageTop: expresiones cron, intervalos y ejecución bajo
|
||||
demanda.
|
||||
"""
|
||||
categories = ["date-and-time", "web-programming"]
|
||||
keywords = ["pagetop", "cron", "scheduler", "jobs", "ssr"]
|
||||
|
||||
repository.workspace = true
|
||||
homepage.workspace = true
|
||||
edition.workspace = true
|
||||
rust-version.workspace = true
|
||||
license.workspace = true
|
||||
authors.workspace = true
|
||||
|
||||
[dependencies]
|
||||
pagetop.workspace = true
|
||||
croner.workspace = true
|
||||
serde.workspace = true
|
||||
thiserror.workspace = true
|
||||
tokio.workspace = true
|
||||
201
extensions/pagetop-cron/LICENSE-APACHE
Normal file
201
extensions/pagetop-cron/LICENSE-APACHE
Normal file
|
|
@ -0,0 +1,201 @@
|
|||
Apache License
|
||||
Version 2.0, January 2004
|
||||
http://www.apache.org/licenses/
|
||||
|
||||
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||
|
||||
1. Definitions.
|
||||
|
||||
"License" shall mean the terms and conditions for use, reproduction,
|
||||
and distribution as defined by Sections 1 through 9 of this document.
|
||||
|
||||
"Licensor" shall mean the copyright owner or entity authorized by
|
||||
the copyright owner that is granting the License.
|
||||
|
||||
"Legal Entity" shall mean the union of the acting entity and all
|
||||
other entities that control, are controlled by, or are under common
|
||||
control with that entity. For the purposes of this definition,
|
||||
"control" means (i) the power, direct or indirect, to cause the
|
||||
direction or management of such entity, whether by contract or
|
||||
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||
|
||||
"You" (or "Your") shall mean an individual or Legal Entity
|
||||
exercising permissions granted by this License.
|
||||
|
||||
"Source" form shall mean the preferred form for making modifications,
|
||||
including but not limited to software source code, documentation
|
||||
source, and configuration files.
|
||||
|
||||
"Object" form shall mean any form resulting from mechanical
|
||||
transformation or translation of a Source form, including but
|
||||
not limited to compiled object code, generated documentation,
|
||||
and conversions to other media types.
|
||||
|
||||
"Work" shall mean the work of authorship, whether in Source or
|
||||
Object form, made available under the License, as indicated by a
|
||||
copyright notice that is included in or attached to the work
|
||||
(an example is provided in the Appendix below).
|
||||
|
||||
"Derivative Works" shall mean any work, whether in Source or Object
|
||||
form, that is based on (or derived from) the Work and for which the
|
||||
editorial revisions, annotations, elaborations, or other modifications
|
||||
represent, as a whole, an original work of authorship. For the purposes
|
||||
of this License, Derivative Works shall not include works that remain
|
||||
separable from, or merely link (or bind by name) to the interfaces of,
|
||||
the Work and Derivative Works thereof.
|
||||
|
||||
"Contribution" shall mean any work of authorship, including
|
||||
the original version of the Work and any modifications or additions
|
||||
to that Work or Derivative Works thereof, that is intentionally
|
||||
submitted to Licensor for inclusion in the Work by the copyright owner
|
||||
or by an individual or Legal Entity authorized to submit on behalf of
|
||||
the copyright owner. For the purposes of this definition, "submitted"
|
||||
means any form of electronic, verbal, or written communication sent
|
||||
to the Licensor or its representatives, including but not limited to
|
||||
communication on electronic mailing lists, source code control systems,
|
||||
and issue tracking systems that are managed by, or on behalf of, the
|
||||
Licensor for the purpose of discussing and improving the Work, but
|
||||
excluding communication that is conspicuously marked or otherwise
|
||||
designated in writing by the copyright owner as "Not a Contribution."
|
||||
|
||||
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||
on behalf of whom a Contribution has been received by Licensor and
|
||||
subsequently incorporated within the Work.
|
||||
|
||||
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
copyright license to reproduce, prepare Derivative Works of,
|
||||
publicly display, publicly perform, sublicense, and distribute the
|
||||
Work and such Derivative Works in Source or Object form.
|
||||
|
||||
3. Grant of Patent License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
(except as stated in this section) patent license to make, have made,
|
||||
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||
where such license applies only to those patent claims licensable
|
||||
by such Contributor that are necessarily infringed by their
|
||||
Contribution(s) alone or by combination of their Contribution(s)
|
||||
with the Work to which such Contribution(s) was submitted. If You
|
||||
institute patent litigation against any entity (including a
|
||||
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||
or a Contribution incorporated within the Work constitutes direct
|
||||
or contributory patent infringement, then any patent licenses
|
||||
granted to You under this License for that Work shall terminate
|
||||
as of the date such litigation is filed.
|
||||
|
||||
4. Redistribution. You may reproduce and distribute copies of the
|
||||
Work or Derivative Works thereof in any medium, with or without
|
||||
modifications, and in Source or Object form, provided that You
|
||||
meet the following conditions:
|
||||
|
||||
(a) You must give any other recipients of the Work or
|
||||
Derivative Works a copy of this License; and
|
||||
|
||||
(b) You must cause any modified files to carry prominent notices
|
||||
stating that You changed the files; and
|
||||
|
||||
(c) You must retain, in the Source form of any Derivative Works
|
||||
that You distribute, all copyright, patent, trademark, and
|
||||
attribution notices from the Source form of the Work,
|
||||
excluding those notices that do not pertain to any part of
|
||||
the Derivative Works; and
|
||||
|
||||
(d) If the Work includes a "NOTICE" text file as part of its
|
||||
distribution, then any Derivative Works that You distribute must
|
||||
include a readable copy of the attribution notices contained
|
||||
within such NOTICE file, excluding those notices that do not
|
||||
pertain to any part of the Derivative Works, in at least one
|
||||
of the following places: within a NOTICE text file distributed
|
||||
as part of the Derivative Works; within the Source form or
|
||||
documentation, if provided along with the Derivative Works; or,
|
||||
within a display generated by the Derivative Works, if and
|
||||
wherever such third-party notices normally appear. The contents
|
||||
of the NOTICE file are for informational purposes only and
|
||||
do not modify the License. You may add Your own attribution
|
||||
notices within Derivative Works that You distribute, alongside
|
||||
or as an addendum to the NOTICE text from the Work, provided
|
||||
that such additional attribution notices cannot be construed
|
||||
as modifying the License.
|
||||
|
||||
You may add Your own copyright statement to Your modifications and
|
||||
may provide additional or different license terms and conditions
|
||||
for use, reproduction, or distribution of Your modifications, or
|
||||
for any such Derivative Works as a whole, provided Your use,
|
||||
reproduction, and distribution of the Work otherwise complies with
|
||||
the conditions stated in this License.
|
||||
|
||||
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||
any Contribution intentionally submitted for inclusion in the Work
|
||||
by You to the Licensor shall be under the terms and conditions of
|
||||
this License, without any additional terms or conditions.
|
||||
Notwithstanding the above, nothing herein shall supersede or modify
|
||||
the terms of any separate license agreement you may have executed
|
||||
with Licensor regarding such Contributions.
|
||||
|
||||
6. Trademarks. This License does not grant permission to use the trade
|
||||
names, trademarks, service marks, or product names of the Licensor,
|
||||
except as required for reasonable and customary use in describing the
|
||||
origin of the Work and reproducing the content of the NOTICE file.
|
||||
|
||||
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||
agreed to in writing, Licensor provides the Work (and each
|
||||
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||
implied, including, without limitation, any warranties or conditions
|
||||
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||
appropriateness of using or redistributing the Work and assume any
|
||||
risks associated with Your exercise of permissions under this License.
|
||||
|
||||
8. Limitation of Liability. In no event and under no legal theory,
|
||||
whether in tort (including negligence), contract, or otherwise,
|
||||
unless required by applicable law (such as deliberate and grossly
|
||||
negligent acts) or agreed to in writing, shall any Contributor be
|
||||
liable to You for damages, including any direct, indirect, special,
|
||||
incidental, or consequential damages of any character arising as a
|
||||
result of this License or out of the use or inability to use the
|
||||
Work (including but not limited to damages for loss of goodwill,
|
||||
work stoppage, computer failure or malfunction, or any and all
|
||||
other commercial damages or losses), even if such Contributor
|
||||
has been advised of the possibility of such damages.
|
||||
|
||||
9. Accepting Warranty or Additional Liability. While redistributing
|
||||
the Work or Derivative Works thereof, You may choose to offer,
|
||||
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||
or other liability obligations and/or rights consistent with this
|
||||
License. However, in accepting such obligations, You may act only
|
||||
on Your own behalf and on Your sole responsibility, not on behalf
|
||||
of any other Contributor, and only if You agree to indemnify,
|
||||
defend, and hold each Contributor harmless for any liability
|
||||
incurred by, or claims asserted against, such Contributor by reason
|
||||
of your accepting any such warranty or additional liability.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
|
||||
APPENDIX: How to apply the Apache License to your work.
|
||||
|
||||
To apply the Apache License to your work, attach the following
|
||||
boilerplate notice, with the fields enclosed by brackets "[]"
|
||||
replaced with your own identifying information. (Don't include
|
||||
the brackets!) The text should be enclosed in the appropriate
|
||||
comment syntax for the file format. We also recommend that a
|
||||
file or class name and description of purpose be included on the
|
||||
same "printed page" as the copyright notice for easier
|
||||
identification within third-party archives.
|
||||
|
||||
Copyright 2026 Manuel Cillero
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
21
extensions/pagetop-cron/LICENSE-MIT
Normal file
21
extensions/pagetop-cron/LICENSE-MIT
Normal file
|
|
@ -0,0 +1,21 @@
|
|||
MIT License
|
||||
|
||||
Copyright (c) 2026 Manuel Cillero
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
333
extensions/pagetop-cron/README.md
Normal file
333
extensions/pagetop-cron/README.md
Normal file
|
|
@ -0,0 +1,333 @@
|
|||
<div align="center">
|
||||
|
||||
<h1>PageTop Cron</h1>
|
||||
|
||||
<p>Programación de tareas para aplicaciones <strong>PageTop</strong>.</p>
|
||||
|
||||
[](https://docs.rs/pagetop-cron)
|
||||
[](https://crates.io/crates/pagetop-cron)
|
||||
[](https://crates.io/crates/pagetop-cron)
|
||||
[](https://git.cillero.es/manuelcillero/pagetop/src/branch/main/extensions/pagetop-cron#licencia)
|
||||
|
||||
</div>
|
||||
|
||||
Ejecuta trabajos periódicos en segundo plano mientras la aplicación está en marcha: cada noche a
|
||||
las 4:30, cada diez minutos, el último día de cada mes, o unos segundos después de terminar la
|
||||
ejecución anterior. Cada extensión declara sus trabajos en el código con una acción, y quien
|
||||
administra la aplicación decide en los archivos de configuración cómo se ejecutan, y puede cambiar
|
||||
cuándo se ejecuta cada trabajo o desactivarlo sin recompilar.
|
||||
|
||||
## Sobre PageTop
|
||||
|
||||
[PageTop](https://docs.rs/pagetop) es un entorno de desarrollo que reivindica la esencia de la web
|
||||
clásica para crear soluciones web SSR (*renderizadas en el servidor*) modulares, extensibles y
|
||||
configurables, basadas en HTML, CSS y JavaScript.
|
||||
|
||||
## Guía rápida
|
||||
|
||||
**Añade la dependencia** a tu `Cargo.toml`:
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
pagetop-cron = "..."
|
||||
```
|
||||
|
||||
**Escribe el trabajo** como una función asíncrona que recibe un `JobContext` y devuelve un
|
||||
`JobResult`. Con `?` puede propagar cualquier error, que se registra en las trazas:
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
use pagetop_cron::prelude::*;
|
||||
|
||||
async fn cleanup(_cx: JobContext) -> JobResult {
|
||||
// Borra los carritos abandonados hace más de 30 días...
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
**Declara el trabajo** con la acción `DeclareCronJobs` en la extensión que lo aporta, que depende
|
||||
de `pagetop-cron`:
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
use pagetop_cron::prelude::*;
|
||||
|
||||
fn declare_jobs(jobs: &mut CronJobs) {
|
||||
jobs.add(
|
||||
Job::new("shop.cleanup", Schedule::cron("30 4 * * *"), cleanup)
|
||||
.with_title(Lc::n("Remove abandoned carts"))
|
||||
.with_timeout(Duration::minutes(15)),
|
||||
);
|
||||
}
|
||||
|
||||
struct Shop;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Shop {
|
||||
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
vec![&pagetop_cron::Cron]
|
||||
}
|
||||
|
||||
fn actions(&self) -> Vec<ActionBox> {
|
||||
actions![DeclareCronJobs::new(declare_jobs)]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Y ya está: al ejecutar la aplicación con `Application::run()`, el trabajo se ejecuta cada día a
|
||||
las 4:30 en la zona horaria de la aplicación (`[app].timezone`). La clave (`"shop.cleanup"`)
|
||||
identifica el trabajo en las trazas, en la configuración y al ejecutarlo bajo demanda; conviene
|
||||
empezarla por el nombre de la extensión.
|
||||
|
||||
## Cuándo se ejecuta un trabajo
|
||||
|
||||
`Schedule` ofrece tres formas de programarlo:
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
use pagetop_cron::prelude::*;
|
||||
|
||||
// Según una expresión cron: cada día a las 4:30.
|
||||
Schedule::cron("30 4 * * *");
|
||||
// Cada cinco minutos desde que *empieza* la ejecución anterior (ritmo fijo).
|
||||
Schedule::fixed_rate(Duration::minutes(5));
|
||||
// Treinta segundos después de que *termina* la ejecución anterior (nunca se solapan).
|
||||
Schedule::fixed_delay(Duration::seconds(30));
|
||||
```
|
||||
|
||||
Las expresiones cron siguen la sintaxis clásica de cinco campos, con un sexto campo opcional para
|
||||
los segundos y un séptimo, también opcional, para el año, y admiten además `L`, `W` y `#` (último
|
||||
día del mes, día laborable más cercano, enésimo día de la semana) y apodos como `@daily`. Se
|
||||
interpretan en la zona horaria de la aplicación y respetan los cambios de hora. Todos los
|
||||
detalles, con ejemplos, en `Schedule`.
|
||||
|
||||
Para procesar colas o tareas pendientes, `fixed_delay()` suele ser la mejor opción: cada ejecución
|
||||
procesa lo que dejó la anterior y nunca coinciden dos.
|
||||
|
||||
## Opciones de cada trabajo
|
||||
|
||||
`Job` ofrece además:
|
||||
|
||||
| Método | Uso |
|
||||
|-----------------------|------------------------------------------------------------------|
|
||||
| `with_title()` | Título descriptivo, traducible, para listados y paneles. |
|
||||
| `with_timeout()` | Tiempo máximo de cada ejecución; si lo supera, se cancela. |
|
||||
| `with_overlap()` | Qué hacer si la ejecución anterior sigue en curso (`Overlap`). |
|
||||
| `with_timezone()` | Zona horaria propia para su expresión cron. |
|
||||
| `with_run_on_start()` | Se ejecuta también al arrancar la aplicación. |
|
||||
|
||||
Si llega la hora de un trabajo y su ejecución anterior aún no ha terminado, por defecto se omite la
|
||||
nueva (`Overlap::Skip`); con `Overlap::Allow` se ejecuta a la vez.
|
||||
|
||||
La función del trabajo puede ser también un cierre. Accede a los ajustes y servicios de la
|
||||
aplicación igual que un *handler*, p. ej. con los `SETTINGS` de cada extensión o con `dbconn()` de
|
||||
`pagetop-seaorm`:
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
use pagetop_cron::prelude::*;
|
||||
|
||||
let job = Job::new("app.heartbeat", Schedule::fixed_rate(Duration::minutes(1)), |cx| async move {
|
||||
trace::info!("Heartbeat from \"{}\" ({:?})", cx.key(), cx.trigger());
|
||||
Ok(())
|
||||
});
|
||||
```
|
||||
|
||||
Un `panic!` dentro de un trabajo no afecta a la aplicación ni a sus siguientes ejecuciones: se
|
||||
registra como un fallo más.
|
||||
|
||||
## Modos de ejecución
|
||||
|
||||
Quien administra la aplicación elige cómo se ejecutan los trabajos con `mode`, en la sección
|
||||
`[cron]` (todas las opciones en `config`):
|
||||
|
||||
| `mode` | Los trabajos se ejecutan... |
|
||||
|--------------|-------------------------------------------------------------------------|
|
||||
| `"internal"` | Por defecto. Con el planificador de la propia aplicación. |
|
||||
| `"external"` | Cuando un programa externo llama a `POST /cron` con la clave secreta. |
|
||||
| `"off"` | Nunca de forma automática; sólo bajo demanda con `run_now()`. |
|
||||
|
||||
### Una sola instancia: `"internal"`
|
||||
|
||||
Con `"internal"`, cada proceso de la aplicación lleva su propio reloj y lanza los trabajos cuando
|
||||
les toca. Con un solo proceso siempre en marcha (un servidor, un servicio de *systemd*, un
|
||||
contenedor) es justo lo que se necesita, y no hay que configurar nada.
|
||||
|
||||
### Varias instancias
|
||||
|
||||
Si la misma aplicación se ejecuta en varios procesos a la vez, cada uno lanza todos los trabajos
|
||||
con `"internal"`:
|
||||
|
||||
```text
|
||||
+--> instancia A (internal) --> limpieza a las 4:30
|
||||
balanceador ---+--> instancia B (internal) --> limpieza a las 4:30
|
||||
+--> instancia C (internal) --> limpieza a las 4:30
|
||||
```
|
||||
|
||||
La limpieza se hace tres veces, y un boletín se enviaría tres veces. Las instancias no se ponen de
|
||||
acuerdo entre sí, así que hay dos formas de evitarlo:
|
||||
|
||||
- **`"internal"` en una instancia y `"off"` en las demás.** Es lo más sencillo si las instancias
|
||||
se configuran a mano, pero esa instancia queda distinta del resto: si se detiene, nadie ejecuta
|
||||
los trabajos.
|
||||
- **`"external"` en todas.** Ninguna tiene reloj propio: un único reloj fuera de la aplicación
|
||||
llama periódicamente a `POST /cron`, y el balanceador entrega cada llamada a una sola instancia,
|
||||
que ejecuta lo programado desde la llamada anterior:
|
||||
|
||||
```text
|
||||
crontab (en una sola máquina) --POST /cron--> balanceador --> instancia B ejecuta lo pendiente
|
||||
```
|
||||
|
||||
### Cuándo usar `"external"`
|
||||
|
||||
- **Réplicas idénticas o autoescalado** (Kubernetes, Docker Swarm, varias máquinas tras un
|
||||
balanceador). Todas arrancan con la misma imagen y la misma configuración, así que no se puede
|
||||
dejar una distinta. Con `"external"` todas son iguales y cualquiera puede atender la llamada.
|
||||
- **Plataformas que detienen la aplicación cuando no hay tráfico** (escalado a cero). Si nadie
|
||||
visita el sitio de madrugada, no queda ningún proceso vivo y el reloj interno de las 4:30 no
|
||||
existe; algunas plataformas, además, sólo dan CPU mientras se atiende una petición. La llamada
|
||||
externa despierta la aplicación y le da tiempo para ejecutar lo pendiente. Estas plataformas
|
||||
suelen ofrecer su propio planificador para hacerla.
|
||||
- **Planificar desde las herramientas de operaciones** que ya se usan, como un *CronJob* de
|
||||
Kubernetes o un temporizador de *systemd*. La llamada responde `200 OK` aunque falle algún
|
||||
trabajo, para que un reintento no repita los demás; el resultado de cada uno viene en el cuerpo
|
||||
de la respuesta y, para avisar de los fallos, está la acción `AfterJobRun`.
|
||||
|
||||
Con una sola instancia siempre en marcha, `"external"` no aporta nada: añade piezas (un `crontab`,
|
||||
una clave secreta, una ruta expuesta) y pierde precisión. Mejor `"internal"`.
|
||||
|
||||
### Configurar `"external"`
|
||||
|
||||
```toml
|
||||
[cron]
|
||||
mode = "external"
|
||||
trigger_token = "..." # Clave secreta propia, mejor en config/local.toml.
|
||||
trigger_interval_secs = 60 # Una llamada por minuto (el valor por defecto).
|
||||
```
|
||||
|
||||
La clave debe tener al menos 16 caracteres (letras, dígitos, `-` o `_`), o la aplicación no
|
||||
arranca; `openssl rand -hex 32` genera una adecuada. Viaja en la cabecera
|
||||
`Authorization: Bearer <clave>`, no en la ruta, porque los *proxies* y los balanceadores suelen
|
||||
registrar las rutas de las peticiones. Para que tampoco aparezca en la lista de procesos del
|
||||
sistema, `curl` puede leer la cabecera de un archivo que sólo pueda leer el usuario del `crontab`:
|
||||
|
||||
```text
|
||||
# crontab del sistema: comprueba los trabajos cada minuto. El archivo contiene la línea
|
||||
# "Authorization: Bearer <clave>".
|
||||
* * * * * curl -fsS -X POST -H @/etc/miapp/cron-header https://example.com/cron > /dev/null
|
||||
```
|
||||
|
||||
La llamada responde cuando terminan los trabajos que ejecuta, con `200 OK` y una línea por trabajo
|
||||
con su resultado (`succeeded`, `failed`, `timed out` o `panicked`); sin la clave correcta responde
|
||||
`404 Not Found`, igual que una ruta que no existe. Esperar mantiene viva la aplicación en las
|
||||
plataformas que sólo dan CPU mientras se atiende una petición, así que el tiempo de espera del
|
||||
programa externo debe superar lo que tarde el trabajo más largo; conviene limitarlo con
|
||||
`with_timeout()`. Si el programa externo corta antes, los trabajos siguen igualmente, pero en esas
|
||||
plataformas pueden quedarse sin CPU.
|
||||
|
||||
Cada llamada ejecuta lo programado en el último minuto, sea cual sea la instancia que la recibe y
|
||||
aunque acabe de arrancar: una llamada a las 4:30:20 ejecuta lo programado desde las 4:29:00
|
||||
(excluido) hasta las 4:30:00. Así ninguna instancia necesita recordar qué hicieron las demás, pero
|
||||
el programa externo debe llamar una vez, y sólo una, cada minuto: si falta una llamada se pierden
|
||||
sus ejecuciones, y si sobra, dos instancias pueden repetirlas. Para llamar con otra frecuencia
|
||||
(p. ej. cada cuarto de hora, en una plataforma que despierta la aplicación en cada llamada),
|
||||
indícala en `trigger_interval_secs` (`900`) y programa los trabajos en múltiplos de ella. La
|
||||
precisión es la del intervalo: con una llamada por minuto, un trabajo programado cada diez
|
||||
segundos se ejecuta una vez por minuto.
|
||||
|
||||
Una llamada de más suele ser un reintento. La respuesta es `200 OK` aunque falle algún trabajo, así
|
||||
que el programa externo sólo reintenta tras un error de red o si se agota su tiempo de espera; pero
|
||||
si el reintento llega a otra instancia, ésta ejecuta de nuevo lo mismo, porque las instancias no
|
||||
comparten estado. Desactiva los reintentos del programa externo (p. ej. `backoffLimit: 0` en un
|
||||
*CronJob* de Kubernetes) y, si un trabajo no debe repetirse nunca, que lo compruebe él mismo (p. ej.
|
||||
en la base de datos) antes de hacer nada.
|
||||
|
||||
## Ajustar un trabajo desde la configuración
|
||||
|
||||
Cada trabajo puede cambiarse por su clave, sin tocar el código, en la subsección
|
||||
`[cron.jobs."clave"]` (ver `JobSettings`):
|
||||
|
||||
```toml
|
||||
[cron.jobs."shop.cleanup"]
|
||||
schedule = "0 5 * * SUN" # Sólo los domingos a las 5:00.
|
||||
timeout_secs = 1800 # Tiempo máximo de 30 minutos (0 = sin límite).
|
||||
|
||||
[cron.jobs."shop.reminders"]
|
||||
enabled = false # Desactivado: sólo se ejecuta bajo demanda.
|
||||
```
|
||||
|
||||
La programación admite la misma sintaxis que `Schedule::parse()`, incluidos `"@every 10m"` y
|
||||
`"@delay 30s"`. Una programación no válida detiene el arranque indicando el trabajo, y una clave
|
||||
que no corresponde a ningún trabajo se ignora con un aviso en las trazas.
|
||||
|
||||
## Ejecutar y consultar los trabajos
|
||||
|
||||
`run_now()` ejecuta un trabajo en el acto y devuelve su `JobRun`: útil para un botón
|
||||
«Ejecutar ahora» de un panel de administración, para una orden de mantenimiento o para las
|
||||
pruebas. `jobs()` y `job()` devuelven su `JobStatus`: programación efectiva, próxima
|
||||
ejecución, resultado de la última y número de ejecuciones, fallos y omisiones.
|
||||
|
||||
Para reaccionar a cada ejecución terminada (registrarla, enviar métricas, avisar cuando falla un
|
||||
trabajo), registra la acción `AfterJobRun`.
|
||||
|
||||
## Detener la aplicación
|
||||
|
||||
Al detener la aplicación (Ctrl+C o `SIGTERM`), el planificador deja de lanzar ejecuciones y espera
|
||||
a que terminen las que están en curso, hasta `cron.shutdown_timeout_secs` (30 s por defecto). Un
|
||||
trabajo largo puede comprobar `JobContext::is_stopping()` para dejar su trabajo en un punto
|
||||
seguro antes de que se agote ese tiempo.
|
||||
|
||||
## Pruebas
|
||||
|
||||
El planificador sólo se pone en marcha con `Application::run()` (ver `Extension::start()`), nunca
|
||||
en las pruebas que preparan la aplicación y obtienen su servidor con `Application::test()`. En
|
||||
ellas, los trabajos se ejecutan cuando la prueba quiere con `run_now()`:
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
|
||||
#[pagetop::test]
|
||||
async fn cleanup_job_succeeds() {
|
||||
Application::prepare(&Shop).await;
|
||||
let run = pagetop_cron::run_now("shop.cleanup").await.unwrap();
|
||||
assert!(run.outcome().is_success(), "{}", run.outcome());
|
||||
}
|
||||
```
|
||||
|
||||
## Qué no hace
|
||||
|
||||
Para mantenerse sencilla, la extensión no guarda nada fuera de la memoria:
|
||||
|
||||
- **No recupera las ejecuciones perdidas.** Si la aplicación estaba detenida cuando tocaba una
|
||||
ejecución, no se hace al volver a arrancar; la siguiente llega según su programación. Para
|
||||
trabajos que no deben perder ninguna, combina la programación con `with_run_on_start()`, o
|
||||
guarda en la base de datos qué queda pendiente y procésalo en cada ejecución.
|
||||
- **No es una cola de trabajos.** Para tareas puntuales que deben sobrevivir a un reinicio (un
|
||||
correo que no se pudo enviar, una importación...), cada extensión guarda las pendientes en su
|
||||
propia tabla y declara un trabajo periódico que las procesa.
|
||||
- **No coordina varias instancias** por sí misma; ver «Varias instancias».
|
||||
|
||||
## Créditos
|
||||
|
||||
Las expresiones cron se interpretan con [croner](https://github.com/hexagon/croner-rust), la misma
|
||||
biblioteca que usa *tokio-cron-scheduler*, distribuida bajo licencia
|
||||
[MIT](https://github.com/hexagon/croner-rust/blob/master/LICENSE).
|
||||
|
||||
## Advertencia
|
||||
|
||||
**PageTop** es un proyecto personal para aprender [Rust](https://www.rust-lang.org/es) y conocer su
|
||||
ecosistema. Su API está sujeta a cambios frecuentes. No se recomienda su uso en producción, al menos
|
||||
hasta que se libere la versión **1.0.0**.
|
||||
|
||||
## Licencia
|
||||
|
||||
El código está disponible bajo una doble licencia:
|
||||
|
||||
* **Licencia MIT**
|
||||
([LICENSE-MIT](LICENSE-MIT) o también https://opensource.org/licenses/MIT)
|
||||
|
||||
* **Licencia Apache, Versión 2.0**
|
||||
([LICENSE-APACHE](LICENSE-APACHE) o también https://www.apache.org/licenses/LICENSE-2.0)
|
||||
|
||||
Puedes elegir la licencia que prefieras. Este enfoque de doble licencia es el estándar de facto en
|
||||
el ecosistema Rust.
|
||||
19
extensions/pagetop-cron/config/common.toml
Normal file
19
extensions/pagetop-cron/config/common.toml
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
# Configuración para las pruebas de este crate: zona horaria de Madrid, modo externo, para probar
|
||||
# la ruta de las llamadas externas, y ajustes propios de algunos trabajos de prueba.
|
||||
|
||||
[app]
|
||||
timezone = "Europe/Madrid"
|
||||
|
||||
[cron]
|
||||
mode = "external"
|
||||
trigger_token = "test-token-0123456789"
|
||||
|
||||
[cron.jobs."test.disabled"]
|
||||
enabled = false
|
||||
|
||||
[cron.jobs."test.overridden"]
|
||||
schedule = "@delay 90s"
|
||||
timeout_secs = 0
|
||||
|
||||
[cron.jobs."test.not_declared"]
|
||||
enabled = false
|
||||
139
extensions/pagetop-cron/src/config.rs
Normal file
139
extensions/pagetop-cron/src/config.rs
Normal file
|
|
@ -0,0 +1,139 @@
|
|||
//! Ajustes de configuración de `pagetop-cron`.
|
||||
//!
|
||||
//! Ejemplo:
|
||||
//!
|
||||
//! ```toml
|
||||
//! [cron]
|
||||
//! mode = "internal"
|
||||
//!
|
||||
//! # Ajustes propios de un trabajo, por su clave.
|
||||
//! [cron.jobs."shop.cleanup"]
|
||||
//! schedule = "30 4 * * *"
|
||||
//! timeout_secs = 600
|
||||
//!
|
||||
//! [cron.jobs."shop.reminders"]
|
||||
//! enabled = false
|
||||
//! ```
|
||||
//!
|
||||
//! Uso:
|
||||
//!
|
||||
//! ```rust,no_run
|
||||
//! use pagetop_cron::config::{self, CronMode};
|
||||
//!
|
||||
//! assert_eq!(config::SETTINGS.mode, CronMode::Internal);
|
||||
//! ```
|
||||
//!
|
||||
//! Todas las opciones, con su valor por defecto, se documentan en [`CronSettings`] y
|
||||
//! [`JobSettings`].
|
||||
//!
|
||||
//! Consulta [`pagetop::config`] para ver cómo PageTop lee los archivos de configuración y aplica
|
||||
//! los valores a los ajustes.
|
||||
|
||||
use pagetop::prelude::*;
|
||||
|
||||
use serde::Deserialize;
|
||||
|
||||
use std::collections::HashMap;
|
||||
|
||||
/// Ajustes de la sección `[cron]`, cargados al arrancar la aplicación.
|
||||
pub static SETTINGS: LazySettings<CronSettings> = LazySettings::new();
|
||||
|
||||
/// Sección **`[cron]`** de la configuración.
|
||||
#[settings(section = "cron")]
|
||||
pub struct CronSettings {
|
||||
/// Cómo se ejecutan los trabajos programados. Por defecto, con el planificador de la propia
|
||||
/// aplicación ([`CronMode::Internal`]).
|
||||
pub mode: CronMode,
|
||||
/// Clave secreta que autoriza las llamadas a `POST /cron` con [`CronMode::External`], enviada
|
||||
/// en la cabecera `Authorization: Bearer <clave>`. Obligatoria en ese modo, con 16 caracteres
|
||||
/// o más (letras, dígitos, `-` o `_`), o la aplicación no arranca. Conviene guardarla en
|
||||
/// `config/local.toml`, que no se versiona.
|
||||
pub trigger_token: Option<String>,
|
||||
/// Segundos entre dos llamadas a `POST /cron` con [`CronMode::External`]. Cada llamada ejecuta
|
||||
/// los trabajos programados en el último intervalo de esta duración, contado en múltiplos
|
||||
/// exactos desde el 1 de enero de 1970 (UTC), así que el programa externo debe llamar una vez,
|
||||
/// y sólo una, en cada intervalo.
|
||||
#[default = 60]
|
||||
pub trigger_interval_secs: u64,
|
||||
/// Segundos que se espera, al detener la aplicación, a que terminen los trabajos en curso.
|
||||
/// Pasado ese tiempo, la aplicación termina igualmente.
|
||||
#[default = 30]
|
||||
pub shutdown_timeout_secs: u64,
|
||||
|
||||
/// Ajustes de trabajos concretos, cada uno en la subsección `[cron.jobs."clave"]`. Las claves
|
||||
/// que no corresponden a ningún trabajo declarado se ignoran con un aviso en las trazas.
|
||||
pub jobs: HashMap<String, JobSettings>,
|
||||
}
|
||||
|
||||
/// Forma de ejecutar los trabajos programados. Usado en [`CronSettings::mode`].
|
||||
#[derive(AutoDefault, Clone, Copy, Debug, Deserialize, Eq, PartialEq)]
|
||||
#[serde(rename_all = "lowercase")]
|
||||
pub enum CronMode {
|
||||
/// La propia aplicación ejecuta cada trabajo según su programación mientras está en marcha. Es
|
||||
/// el valor por defecto. Con varias instancias de la aplicación, **cada una** ejecuta los
|
||||
/// trabajos: deja este modo en una sola y usa [`CronMode::Off`] en las demás.
|
||||
#[default]
|
||||
Internal,
|
||||
/// Los trabajos sólo se ejecutan cuando un programa externo (`crontab`, un temporizador de
|
||||
/// *systemd*, un servicio de la nube...) llama a `POST /cron` con la clave
|
||||
/// [`trigger_token`](CronSettings::trigger_token), una vez cada
|
||||
/// [`trigger_interval_secs`](CronSettings::trigger_interval_secs): cada llamada ejecuta los
|
||||
/// trabajos programados desde la anterior. Útil para varias instancias tras un balanceador,
|
||||
/// porque cada llamada sólo llega a una de ellas, y para las plataformas que detienen la
|
||||
/// aplicación cuando no hay tráfico, porque no depende de lo que recuerde cada proceso.
|
||||
External,
|
||||
/// Ningún trabajo se ejecuta de forma automática; sólo bajo demanda con
|
||||
/// [`run_now()`](crate::run_now). Útil en las instancias que no deben ejecutar trabajos y
|
||||
/// para detenerlos temporalmente.
|
||||
Off,
|
||||
}
|
||||
|
||||
/// Subsección **`[cron.jobs."clave"]`** de la configuración, con los ajustes de un trabajo.
|
||||
///
|
||||
/// Permite a quien administra la aplicación cambiar cuándo se ejecuta un trabajo, o desactivarlo,
|
||||
/// sin modificar el código. Los ajustes que no se indican mantienen lo declarado en el código.
|
||||
#[settings]
|
||||
pub struct JobSettings {
|
||||
/// `false` desactiva el trabajo: deja de ejecutarse de forma automática, aunque se puede
|
||||
/// ejecutar bajo demanda con [`run_now()`](crate::run_now).
|
||||
#[default = true]
|
||||
pub enabled: bool,
|
||||
/// Sustituye la programación declarada en el código, con la sintaxis de
|
||||
/// [`Schedule::parse()`](crate::Schedule::parse) (p. ej. `"*/10 * * * *"` o `"@every 5m"`).
|
||||
/// Una programación no válida detiene el arranque.
|
||||
pub schedule: Option<String>,
|
||||
/// Sustituye el tiempo máximo de cada ejecución, en segundos. `0` quita el límite.
|
||||
pub timeout_secs: Option<u64>,
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::{CronSettings, config};
|
||||
|
||||
// `reference.toml` documents every option; with unknown keys rejected, loading it proves that
|
||||
// it only documents keys that exist, with values of the right type.
|
||||
const REFERENCE: &str = include_str!("../../../config/reference.toml");
|
||||
|
||||
#[test]
|
||||
fn reference_toml_documents_only_existing_keys() {
|
||||
config::load_from_str::<CronSettings>(REFERENCE).unwrap();
|
||||
}
|
||||
|
||||
// Job keys usually contain dots, which TOML only accepts quoted. They must reach the map as a
|
||||
// single key, not as nested tables.
|
||||
#[test]
|
||||
fn quoted_job_keys_with_dots_are_kept_whole() {
|
||||
let settings = config::load_from_str::<CronSettings>(
|
||||
r#"
|
||||
[cron.jobs."shop.cleanup"]
|
||||
enabled = false
|
||||
schedule = "@hourly"
|
||||
"#,
|
||||
)
|
||||
.unwrap();
|
||||
let job = &settings.jobs["shop.cleanup"];
|
||||
assert!(!job.enabled);
|
||||
assert_eq!(job.schedule.as_deref(), Some("@hourly"));
|
||||
assert_eq!(job.timeout_secs, None);
|
||||
}
|
||||
}
|
||||
87
extensions/pagetop-cron/src/declare.rs
Normal file
87
extensions/pagetop-cron/src/declare.rs
Normal file
|
|
@ -0,0 +1,87 @@
|
|||
use pagetop::prelude::*;
|
||||
|
||||
use crate::Job;
|
||||
|
||||
/// Tipo de función que declara trabajos en un [`CronJobs`].
|
||||
pub type FnDeclareCronJobs = fn(jobs: &mut CronJobs);
|
||||
|
||||
/// Trabajos declarados por las extensiones. Ver [`DeclareCronJobs`].
|
||||
#[derive(AutoDefault)]
|
||||
pub struct CronJobs {
|
||||
jobs: Vec<Job>,
|
||||
}
|
||||
|
||||
impl CronJobs {
|
||||
/// Añade un trabajo.
|
||||
pub fn add(&mut self, job: Job) {
|
||||
self.jobs.push(job);
|
||||
}
|
||||
|
||||
// Recoge los trabajos de todas las extensiones.
|
||||
pub(crate) fn collect() -> Vec<Job> {
|
||||
let mut jobs = CronJobs::default();
|
||||
dispatch_actions(|action: &DeclareCronJobs| (action.f)(&mut jobs));
|
||||
jobs.jobs
|
||||
}
|
||||
}
|
||||
|
||||
/// Acción para declarar trabajos programados.
|
||||
///
|
||||
/// Cada extensión registra esta acción con una función que añade sus trabajos. Se despacha una
|
||||
/// sola vez, al inicializar `pagetop-cron`, así que los trabajos quedan fijos durante toda la vida
|
||||
/// de la aplicación, como las propias acciones.
|
||||
///
|
||||
/// # Ejemplo
|
||||
///
|
||||
/// ```rust,no_run
|
||||
/// use pagetop::prelude::*;
|
||||
/// use pagetop_cron::prelude::*;
|
||||
///
|
||||
/// async fn cleanup(_cx: JobContext) -> JobResult {
|
||||
/// // Borra los carritos abandonados...
|
||||
/// Ok(())
|
||||
/// }
|
||||
///
|
||||
/// fn declare_jobs(jobs: &mut CronJobs) {
|
||||
/// jobs.add(
|
||||
/// Job::new("shop.cleanup", Schedule::cron("30 4 * * *"), cleanup)
|
||||
/// .with_title(Lc::n("Remove abandoned carts")),
|
||||
/// );
|
||||
/// }
|
||||
///
|
||||
/// struct Shop;
|
||||
///
|
||||
/// #[async_trait]
|
||||
/// impl Extension for Shop {
|
||||
/// fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
/// vec![&pagetop_cron::Cron]
|
||||
/// }
|
||||
///
|
||||
/// fn actions(&self) -> Vec<ActionBox> {
|
||||
/// actions![DeclareCronJobs::new(declare_jobs)]
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
pub struct DeclareCronJobs {
|
||||
f: FnDeclareCronJobs,
|
||||
weight: Weight,
|
||||
}
|
||||
|
||||
impl ActionDispatcher for DeclareCronJobs {
|
||||
fn weight(&self) -> Weight {
|
||||
self.weight
|
||||
}
|
||||
}
|
||||
|
||||
impl DeclareCronJobs {
|
||||
/// Registra una función que declara trabajos.
|
||||
pub fn new(f: FnDeclareCronJobs) -> Self {
|
||||
DeclareCronJobs { f, weight: 0 }
|
||||
}
|
||||
|
||||
/// Opcional. Las acciones de menor peso se aplican antes. Se pueden usar valores negativos.
|
||||
pub fn with_weight(mut self, value: Weight) -> Self {
|
||||
self.weight = value;
|
||||
self
|
||||
}
|
||||
}
|
||||
50
extensions/pagetop-cron/src/error.rs
Normal file
50
extensions/pagetop-cron/src/error.rs
Normal file
|
|
@ -0,0 +1,50 @@
|
|||
//! Errores de `pagetop-cron`.
|
||||
|
||||
/// Errores al declarar, configurar o ejecutar trabajos programados.
|
||||
#[derive(Debug, thiserror::Error)]
|
||||
pub enum CronError {
|
||||
/// Una programación no es válida (p. ej. una expresión cron mal escrita o un intervalo nulo).
|
||||
#[error("invalid schedule \"{schedule}\": {reason}")]
|
||||
InvalidSchedule {
|
||||
/// Programación tal como se indicó.
|
||||
schedule: String,
|
||||
/// Motivo del error.
|
||||
reason: String,
|
||||
},
|
||||
/// La clave de un trabajo no es válida.
|
||||
#[error(
|
||||
"invalid job key \"{0}\": use lowercase letters, digits, '_', '-' and '.', starting with a \
|
||||
letter or digit"
|
||||
)]
|
||||
InvalidKey(String),
|
||||
/// Dos trabajos se declaran con la misma clave.
|
||||
#[error("job \"{0}\" is declared more than once")]
|
||||
DuplicateJob(String),
|
||||
/// Un trabajo no se puede programar, por su declaración o por sus ajustes.
|
||||
#[error("invalid job \"{key}\"")]
|
||||
InvalidJob {
|
||||
/// Clave del trabajo.
|
||||
key: String,
|
||||
/// Motivo del error.
|
||||
#[source]
|
||||
source: Box<CronError>,
|
||||
},
|
||||
/// Un ajuste de la sección `[cron]` no es válido.
|
||||
#[error("invalid cron setting \"{key}\": {reason}")]
|
||||
InvalidSetting {
|
||||
/// Clave del ajuste, p. ej. `"cron.trigger_token"`.
|
||||
key: &'static str,
|
||||
/// Motivo del error.
|
||||
reason: String,
|
||||
},
|
||||
/// No hay ningún trabajo declarado con la clave indicada.
|
||||
#[error("unknown job \"{0}\"")]
|
||||
UnknownJob(String),
|
||||
/// El trabajo ya se está ejecutando y no admite ejecuciones simultáneas
|
||||
/// ([`Overlap::Skip`](crate::Overlap::Skip)).
|
||||
#[error("job \"{0}\" is already running")]
|
||||
AlreadyRunning(String),
|
||||
/// Los trabajos aún no están disponibles: la aplicación no se ha preparado.
|
||||
#[error("cron jobs are not available until the application is prepared")]
|
||||
NotInitialized,
|
||||
}
|
||||
240
extensions/pagetop-cron/src/job.rs
Normal file
240
extensions/pagetop-cron/src/job.rs
Normal file
|
|
@ -0,0 +1,240 @@
|
|||
use pagetop::prelude::*;
|
||||
|
||||
use tokio::sync::watch;
|
||||
|
||||
use crate::{RunTrigger, Schedule};
|
||||
|
||||
use std::future::Future;
|
||||
use std::pin::Pin;
|
||||
use std::sync::Arc;
|
||||
|
||||
/// Resultado de una ejecución de un trabajo.
|
||||
///
|
||||
/// Con [`BoxError`] el trabajo puede propagar con `?` cualquier error; el error se registra en las
|
||||
/// trazas y en el estado del trabajo ([`JobStatus`](crate::JobStatus)).
|
||||
pub type JobResult = Result<(), BoxError>;
|
||||
|
||||
// Función del trabajo, ya preparada para ejecutarse en una tarea propia.
|
||||
pub(crate) type JobFn =
|
||||
Arc<dyn Fn(JobContext) -> Pin<Box<dyn Future<Output = JobResult> + Send>> + Send + Sync>;
|
||||
|
||||
/// Qué hacer a la hora de ejecutar un trabajo si no ha terminado la ejecución anterior.
|
||||
///
|
||||
/// Usado en [`Job::with_overlap()`]. Las ejecuciones programadas con [`Schedule::fixed_delay()`]
|
||||
/// nunca se solapan entre sí; con esa programación, sólo decide qué ocurre si se pide
|
||||
/// [`run_now()`](crate::run_now) durante una de ellas.
|
||||
#[derive(AutoDefault, Clone, Copy, Debug, Eq, PartialEq)]
|
||||
pub enum Overlap {
|
||||
/// Se omite la nueva ejecución y se registra un aviso. Es el valor por defecto, porque la
|
||||
/// mayoría de los trabajos no esperan ejecutarse dos veces a la vez sobre los mismos datos.
|
||||
#[default]
|
||||
Skip,
|
||||
/// Se ejecuta igualmente, a la vez que la anterior.
|
||||
Allow,
|
||||
}
|
||||
|
||||
/// Un trabajo programado: una función asíncrona que se ejecuta según una [`Schedule`].
|
||||
///
|
||||
/// Se identifica por una clave única, que conviene empezar por el nombre de la extensión
|
||||
/// (`"shop.cleanup"`), con letras minúsculas, dígitos, `_`, `-` y `.`. La clave aparece en las
|
||||
/// trazas y es la que usa la configuración para cambiar o desactivar el trabajo
|
||||
/// (`[cron.jobs."shop.cleanup"]`) y [`run_now()`](crate::run_now) para ejecutarlo bajo demanda.
|
||||
///
|
||||
/// La función recibe un [`JobContext`] y devuelve un [`JobResult`]. Accede a los ajustes y a los
|
||||
/// servicios de la aplicación igual que un *handler*: con los `SETTINGS` de cada extensión, o con
|
||||
/// funciones como `dbconn()` de `pagetop-seaorm`.
|
||||
///
|
||||
/// Los trabajos se declaran con la acción [`DeclareCronJobs`](crate::DeclareCronJobs).
|
||||
///
|
||||
/// # Ejemplo
|
||||
///
|
||||
/// ```rust,no_run
|
||||
/// use pagetop::prelude::*;
|
||||
/// use pagetop_cron::prelude::*;
|
||||
///
|
||||
/// async fn purge_sessions(_cx: JobContext) -> JobResult {
|
||||
/// // Borra las sesiones caducadas...
|
||||
/// Ok(())
|
||||
/// }
|
||||
///
|
||||
/// let job = Job::new("shop.purge_sessions", Schedule::cron("0 3 * * *"), purge_sessions)
|
||||
/// .with_title(Lc::n("Purge expired sessions"))
|
||||
/// .with_timeout(Duration::minutes(10));
|
||||
/// ```
|
||||
#[derive(Clone, Getters)]
|
||||
pub struct Job {
|
||||
/// Devuelve la clave única del trabajo.
|
||||
key: CowStr,
|
||||
/// Devuelve el título descriptivo del trabajo.
|
||||
title: Lc,
|
||||
/// Devuelve la programación declarada en el código.
|
||||
schedule: Schedule,
|
||||
#[getters(skip)]
|
||||
run: JobFn,
|
||||
/// Devuelve qué hacer si la ejecución anterior aún no ha terminado.
|
||||
#[getters(copy)]
|
||||
overlap: Overlap,
|
||||
/// Devuelve el tiempo máximo de cada ejecución, si lo hay.
|
||||
#[getters(copy)]
|
||||
timeout: Option<Duration>,
|
||||
/// Devuelve la zona horaria propia del trabajo, si la tiene.
|
||||
#[getters(copy)]
|
||||
timezone: Option<Tz>,
|
||||
/// Devuelve si el trabajo se ejecuta también al arrancar la aplicación.
|
||||
#[getters(copy)]
|
||||
run_on_start: bool,
|
||||
}
|
||||
|
||||
impl Job {
|
||||
/// Crea un trabajo con su clave, su programación y la función que ejecuta.
|
||||
///
|
||||
/// La función puede ser una `async fn` o un cierre que devuelva un *future*. El *future* debe
|
||||
/// ser `Send + 'static`: si el cierre usa datos propios, los clona dentro de un bloque
|
||||
/// `async move`.
|
||||
pub fn new<F, Fut>(key: impl Into<CowStr>, schedule: Schedule, run: F) -> Self
|
||||
where
|
||||
F: Fn(JobContext) -> Fut + Send + Sync + 'static,
|
||||
Fut: Future<Output = JobResult> + Send + 'static,
|
||||
{
|
||||
Job {
|
||||
key: key.into(),
|
||||
title: Lc::none(),
|
||||
schedule,
|
||||
run: Arc::new(move |cx| Box::pin(run(cx))),
|
||||
overlap: Overlap::default(),
|
||||
timeout: None,
|
||||
timezone: None,
|
||||
run_on_start: false,
|
||||
}
|
||||
}
|
||||
|
||||
/// Título descriptivo para listados y paneles. Sin título, se muestra la clave.
|
||||
pub fn with_title(mut self, title: Lc) -> Self {
|
||||
self.title = title;
|
||||
self
|
||||
}
|
||||
|
||||
/// Qué hacer cuando llega la hora de una ejecución y la anterior aún no ha terminado. Por
|
||||
/// defecto, [`Overlap::Skip`].
|
||||
pub fn with_overlap(mut self, overlap: Overlap) -> Self {
|
||||
self.overlap = overlap;
|
||||
self
|
||||
}
|
||||
|
||||
/// Tiempo máximo de cada ejecución. Si se supera, la ejecución se cancela (el *future* deja
|
||||
/// de ejecutarse en el siguiente `.await`) y se registra como
|
||||
/// [`JobOutcome::TimedOut`](crate::JobOutcome::TimedOut). Sin valor, no hay límite.
|
||||
///
|
||||
/// Un trabajo que no llega a ningún `.await` (un cálculo largo, una llamada bloqueante) no se
|
||||
/// puede cancelar: sigue en marcha hasta terminar y, mientras tanto, cuenta como en curso.
|
||||
///
|
||||
/// La configuración puede cambiarlo con `timeout_secs` (ver
|
||||
/// [`JobSettings`](crate::config::JobSettings)).
|
||||
pub fn with_timeout(mut self, timeout: impl Into<Option<Duration>>) -> Self {
|
||||
self.timeout = timeout.into();
|
||||
self
|
||||
}
|
||||
|
||||
/// Zona horaria en la que se interpreta la expresión cron de este trabajo, p. ej.
|
||||
/// `Tz::Europe__Madrid`. Sin valor, la de la aplicación (`[app].timezone`).
|
||||
pub fn with_timezone(mut self, timezone: impl Into<Option<Tz>>) -> Self {
|
||||
self.timezone = timezone.into();
|
||||
self
|
||||
}
|
||||
|
||||
/// Ejecuta también el trabajo al arrancar la aplicación, además de según su programación. Útil
|
||||
/// para no esperar a la primera ejecución programada, p. ej. para procesar lo que quedó
|
||||
/// pendiente al detener la aplicación.
|
||||
///
|
||||
/// Con `mode = "external"` se ejecuta en la primera llamada a `POST /cron` que recibe cada
|
||||
/// proceso de la aplicación, y con `mode = "off"` no se ejecuta.
|
||||
pub fn with_run_on_start(mut self) -> Self {
|
||||
self.run_on_start = true;
|
||||
self
|
||||
}
|
||||
|
||||
// Función del trabajo, para ejecutarla en una tarea propia.
|
||||
pub(crate) fn runner(&self) -> JobFn {
|
||||
Arc::clone(&self.run)
|
||||
}
|
||||
}
|
||||
|
||||
// **< JobContext >*********************************************************************************
|
||||
|
||||
/// Datos de la ejecución en curso que recibe la función de un [`Job`].
|
||||
///
|
||||
/// Además de indicar qué provocó la ejecución, permite a los trabajos largos saber si la aplicación
|
||||
/// se está deteniendo, para dejar su trabajo en un punto seguro antes de que se agote el tiempo de
|
||||
/// espera (`cron.shutdown_timeout_secs`).
|
||||
///
|
||||
/// # Ejemplo
|
||||
///
|
||||
/// ```rust,no_run
|
||||
/// use pagetop::prelude::*;
|
||||
/// use pagetop_cron::prelude::*;
|
||||
///
|
||||
/// async fn send_newsletters(cx: JobContext) -> JobResult {
|
||||
/// for batch in 0..100 {
|
||||
/// if cx.is_stopping() {
|
||||
/// // Lo que falte se enviará en la siguiente ejecución.
|
||||
/// trace::info!("Stopping \"{}\" at batch {batch}", cx.key());
|
||||
/// break;
|
||||
/// }
|
||||
/// // Envía el lote...
|
||||
/// }
|
||||
/// Ok(())
|
||||
/// }
|
||||
/// ```
|
||||
#[derive(Clone, Debug)]
|
||||
pub struct JobContext {
|
||||
key: CowStr,
|
||||
trigger: RunTrigger,
|
||||
scheduled_at: Option<DateTime<Utc>>,
|
||||
stop: watch::Receiver<bool>,
|
||||
}
|
||||
|
||||
impl JobContext {
|
||||
pub(crate) fn new(
|
||||
key: CowStr,
|
||||
trigger: RunTrigger,
|
||||
scheduled_at: Option<DateTime<Utc>>,
|
||||
stop: watch::Receiver<bool>,
|
||||
) -> Self {
|
||||
JobContext {
|
||||
key,
|
||||
trigger,
|
||||
scheduled_at,
|
||||
stop,
|
||||
}
|
||||
}
|
||||
|
||||
/// Clave del trabajo.
|
||||
pub fn key(&self) -> &str {
|
||||
&self.key
|
||||
}
|
||||
|
||||
/// Qué provocó esta ejecución.
|
||||
pub fn trigger(&self) -> RunTrigger {
|
||||
self.trigger
|
||||
}
|
||||
|
||||
/// Momento en que estaba programada esta ejecución, en UTC. Puede ser algo anterior al momento
|
||||
/// real en que empieza. `None` si no se debe a la programación (al arrancar o bajo demanda).
|
||||
pub fn scheduled_at(&self) -> Option<DateTime<Utc>> {
|
||||
self.scheduled_at
|
||||
}
|
||||
|
||||
/// Devuelve `true` si la aplicación se está deteniendo.
|
||||
pub fn is_stopping(&self) -> bool {
|
||||
*self.stop.borrow()
|
||||
}
|
||||
|
||||
/// Espera hasta que la aplicación empiece a detenerse. Pensado para `tokio::select!`, junto a
|
||||
/// la espera de otra operación que se quiera interrumpir.
|
||||
pub async fn stopping(&self) {
|
||||
let mut stop = self.stop.clone();
|
||||
if stop.wait_for(|stopping| *stopping).await.is_err() {
|
||||
std::future::pending::<()>().await;
|
||||
}
|
||||
}
|
||||
}
|
||||
442
extensions/pagetop-cron/src/lib.rs
Normal file
442
extensions/pagetop-cron/src/lib.rs
Normal file
|
|
@ -0,0 +1,442 @@
|
|||
/*!
|
||||
<div align="center">
|
||||
|
||||
<h1>PageTop Cron</h1>
|
||||
|
||||
<p>Programación de tareas para aplicaciones <strong>PageTop</strong>.</p>
|
||||
|
||||
[](https://docs.rs/pagetop-cron)
|
||||
[](https://crates.io/crates/pagetop-cron)
|
||||
[](https://crates.io/crates/pagetop-cron)
|
||||
[](https://git.cillero.es/manuelcillero/pagetop/src/branch/main/extensions/pagetop-cron#licencia)
|
||||
|
||||
</div>
|
||||
|
||||
Ejecuta trabajos periódicos en segundo plano mientras la aplicación está en marcha: cada noche a
|
||||
las 4:30, cada diez minutos, el último día de cada mes, o unos segundos después de terminar la
|
||||
ejecución anterior. Cada extensión declara sus trabajos en el código con una acción, y quien
|
||||
administra la aplicación decide en los archivos de configuración cómo se ejecutan, y puede cambiar
|
||||
cuándo se ejecuta cada trabajo o desactivarlo sin recompilar.
|
||||
|
||||
## Sobre PageTop
|
||||
|
||||
[PageTop](https://docs.rs/pagetop) es un entorno de desarrollo que reivindica la esencia de la web
|
||||
clásica para crear soluciones web SSR (*renderizadas en el servidor*) modulares, extensibles y
|
||||
configurables, basadas en HTML, CSS y JavaScript.
|
||||
|
||||
## Guía rápida
|
||||
|
||||
**Añade la dependencia** a tu `Cargo.toml`:
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
pagetop-cron = "..."
|
||||
```
|
||||
|
||||
**Escribe el trabajo** como una función asíncrona que recibe un [`JobContext`] y devuelve un
|
||||
[`JobResult`]. Con `?` puede propagar cualquier error, que se registra en las trazas:
|
||||
|
||||
```rust,no_run
|
||||
use pagetop::prelude::*;
|
||||
use pagetop_cron::prelude::*;
|
||||
|
||||
async fn cleanup(_cx: JobContext) -> JobResult {
|
||||
// Borra los carritos abandonados hace más de 30 días...
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
**Declara el trabajo** con la acción [`DeclareCronJobs`] en la extensión que lo aporta, que depende
|
||||
de `pagetop-cron`:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_cron::prelude::*;
|
||||
# async fn cleanup(_cx: JobContext) -> JobResult { Ok(()) }
|
||||
fn declare_jobs(jobs: &mut CronJobs) {
|
||||
jobs.add(
|
||||
Job::new("shop.cleanup", Schedule::cron("30 4 * * *"), cleanup)
|
||||
.with_title(Lc::n("Remove abandoned carts"))
|
||||
.with_timeout(Duration::minutes(15)),
|
||||
);
|
||||
}
|
||||
|
||||
struct Shop;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Shop {
|
||||
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
vec![&pagetop_cron::Cron]
|
||||
}
|
||||
|
||||
fn actions(&self) -> Vec<ActionBox> {
|
||||
actions![DeclareCronJobs::new(declare_jobs)]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Y ya está: al ejecutar la aplicación con [`Application::run()`], el trabajo se ejecuta cada día a
|
||||
las 4:30 en la zona horaria de la aplicación (`[app].timezone`). La clave (`"shop.cleanup"`)
|
||||
identifica el trabajo en las trazas, en la configuración y al ejecutarlo bajo demanda; conviene
|
||||
empezarla por el nombre de la extensión.
|
||||
|
||||
## Cuándo se ejecuta un trabajo
|
||||
|
||||
[`Schedule`] ofrece tres formas de programarlo:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_cron::prelude::*;
|
||||
// Según una expresión cron: cada día a las 4:30.
|
||||
Schedule::cron("30 4 * * *");
|
||||
// Cada cinco minutos desde que *empieza* la ejecución anterior (ritmo fijo).
|
||||
Schedule::fixed_rate(Duration::minutes(5));
|
||||
// Treinta segundos después de que *termina* la ejecución anterior (nunca se solapan).
|
||||
Schedule::fixed_delay(Duration::seconds(30));
|
||||
```
|
||||
|
||||
Las expresiones cron siguen la sintaxis clásica de cinco campos, con un sexto campo opcional para
|
||||
los segundos y un séptimo, también opcional, para el año, y admiten además `L`, `W` y `#` (último
|
||||
día del mes, día laborable más cercano, enésimo día de la semana) y apodos como `@daily`. Se
|
||||
interpretan en la zona horaria de la aplicación y respetan los cambios de hora. Todos los
|
||||
detalles, con ejemplos, en [`Schedule`].
|
||||
|
||||
Para procesar colas o tareas pendientes, `fixed_delay()` suele ser la mejor opción: cada ejecución
|
||||
procesa lo que dejó la anterior y nunca coinciden dos.
|
||||
|
||||
## Opciones de cada trabajo
|
||||
|
||||
[`Job`] ofrece además:
|
||||
|
||||
| Método | Uso |
|
||||
|-------------------------|---------------------------------------------------------------|
|
||||
| [`with_title()`] | Título descriptivo, traducible, para listados y paneles. |
|
||||
| [`with_timeout()`] | Tiempo máximo de cada ejecución; si lo supera, se cancela. |
|
||||
| [`with_overlap()`] | Qué hacer si la ejecución anterior sigue en curso ([`Overlap`]). |
|
||||
| [`with_timezone()`] | Zona horaria propia para su expresión cron. |
|
||||
| [`with_run_on_start()`] | Se ejecuta también al arrancar la aplicación. |
|
||||
|
||||
Si llega la hora de un trabajo y su ejecución anterior aún no ha terminado, por defecto se omite la
|
||||
nueva ([`Overlap::Skip`]); con [`Overlap::Allow`] se ejecuta a la vez.
|
||||
|
||||
[`with_title()`]: Job::with_title
|
||||
[`with_timeout()`]: Job::with_timeout
|
||||
[`with_overlap()`]: Job::with_overlap
|
||||
[`with_timezone()`]: Job::with_timezone
|
||||
[`with_run_on_start()`]: Job::with_run_on_start
|
||||
|
||||
La función del trabajo puede ser también un cierre. Accede a los ajustes y servicios de la
|
||||
aplicación igual que un *handler*, p. ej. con los `SETTINGS` de cada extensión o con `dbconn()` de
|
||||
`pagetop-seaorm`:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# use pagetop_cron::prelude::*;
|
||||
let job = Job::new("app.heartbeat", Schedule::fixed_rate(Duration::minutes(1)), |cx| async move {
|
||||
trace::info!("Heartbeat from \"{}\" ({:?})", cx.key(), cx.trigger());
|
||||
Ok(())
|
||||
});
|
||||
```
|
||||
|
||||
Un `panic!` dentro de un trabajo no afecta a la aplicación ni a sus siguientes ejecuciones: se
|
||||
registra como un fallo más.
|
||||
|
||||
## Modos de ejecución
|
||||
|
||||
Quien administra la aplicación elige cómo se ejecutan los trabajos con `mode`, en la sección
|
||||
`[cron]` (todas las opciones en [`config`]):
|
||||
|
||||
| `mode` | Los trabajos se ejecutan... |
|
||||
|--------------|-------------------------------------------------------------------------|
|
||||
| `"internal"` | Por defecto. Con el planificador de la propia aplicación. |
|
||||
| `"external"` | Cuando un programa externo llama a `POST /cron` con la clave secreta. |
|
||||
| `"off"` | Nunca de forma automática; sólo bajo demanda con [`run_now()`]. |
|
||||
|
||||
### Una sola instancia: `"internal"`
|
||||
|
||||
Con `"internal"`, cada proceso de la aplicación lleva su propio reloj y lanza los trabajos cuando
|
||||
les toca. Con un solo proceso siempre en marcha (un servidor, un servicio de *systemd*, un
|
||||
contenedor) es justo lo que se necesita, y no hay que configurar nada.
|
||||
|
||||
### Varias instancias
|
||||
|
||||
Si la misma aplicación se ejecuta en varios procesos a la vez, cada uno lanza todos los trabajos
|
||||
con `"internal"`:
|
||||
|
||||
```text
|
||||
+--> instancia A (internal) --> limpieza a las 4:30
|
||||
balanceador ---+--> instancia B (internal) --> limpieza a las 4:30
|
||||
+--> instancia C (internal) --> limpieza a las 4:30
|
||||
```
|
||||
|
||||
La limpieza se hace tres veces, y un boletín se enviaría tres veces. Las instancias no se ponen de
|
||||
acuerdo entre sí, así que hay dos formas de evitarlo:
|
||||
|
||||
- **`"internal"` en una instancia y `"off"` en las demás.** Es lo más sencillo si las instancias
|
||||
se configuran a mano, pero esa instancia queda distinta del resto: si se detiene, nadie ejecuta
|
||||
los trabajos.
|
||||
- **`"external"` en todas.** Ninguna tiene reloj propio: un único reloj fuera de la aplicación
|
||||
llama periódicamente a `POST /cron`, y el balanceador entrega cada llamada a una sola instancia,
|
||||
que ejecuta lo programado desde la llamada anterior:
|
||||
|
||||
```text
|
||||
crontab (en una sola máquina) --POST /cron--> balanceador --> instancia B ejecuta lo pendiente
|
||||
```
|
||||
|
||||
### Cuándo usar `"external"`
|
||||
|
||||
- **Réplicas idénticas o autoescalado** (Kubernetes, Docker Swarm, varias máquinas tras un
|
||||
balanceador). Todas arrancan con la misma imagen y la misma configuración, así que no se puede
|
||||
dejar una distinta. Con `"external"` todas son iguales y cualquiera puede atender la llamada.
|
||||
- **Plataformas que detienen la aplicación cuando no hay tráfico** (escalado a cero). Si nadie
|
||||
visita el sitio de madrugada, no queda ningún proceso vivo y el reloj interno de las 4:30 no
|
||||
existe; algunas plataformas, además, sólo dan CPU mientras se atiende una petición. La llamada
|
||||
externa despierta la aplicación y le da tiempo para ejecutar lo pendiente. Estas plataformas
|
||||
suelen ofrecer su propio planificador para hacerla.
|
||||
- **Planificar desde las herramientas de operaciones** que ya se usan, como un *CronJob* de
|
||||
Kubernetes o un temporizador de *systemd*. La llamada responde `200 OK` aunque falle algún
|
||||
trabajo, para que un reintento no repita los demás; el resultado de cada uno viene en el cuerpo
|
||||
de la respuesta y, para avisar de los fallos, está la acción [`AfterJobRun`].
|
||||
|
||||
Con una sola instancia siempre en marcha, `"external"` no aporta nada: añade piezas (un `crontab`,
|
||||
una clave secreta, una ruta expuesta) y pierde precisión. Mejor `"internal"`.
|
||||
|
||||
### Configurar `"external"`
|
||||
|
||||
```toml
|
||||
[cron]
|
||||
mode = "external"
|
||||
trigger_token = "..." # Clave secreta propia, mejor en config/local.toml.
|
||||
trigger_interval_secs = 60 # Una llamada por minuto (el valor por defecto).
|
||||
```
|
||||
|
||||
La clave debe tener al menos 16 caracteres (letras, dígitos, `-` o `_`), o la aplicación no
|
||||
arranca; `openssl rand -hex 32` genera una adecuada. Viaja en la cabecera
|
||||
`Authorization: Bearer <clave>`, no en la ruta, porque los *proxies* y los balanceadores suelen
|
||||
registrar las rutas de las peticiones. Para que tampoco aparezca en la lista de procesos del
|
||||
sistema, `curl` puede leer la cabecera de un archivo que sólo pueda leer el usuario del `crontab`:
|
||||
|
||||
```text
|
||||
# crontab del sistema: comprueba los trabajos cada minuto. El archivo contiene la línea
|
||||
# "Authorization: Bearer <clave>".
|
||||
* * * * * curl -fsS -X POST -H @/etc/miapp/cron-header https://example.com/cron > /dev/null
|
||||
```
|
||||
|
||||
La llamada responde cuando terminan los trabajos que ejecuta, con `200 OK` y una línea por trabajo
|
||||
con su resultado (`succeeded`, `failed`, `timed out` o `panicked`); sin la clave correcta responde
|
||||
`404 Not Found`, igual que una ruta que no existe. Esperar mantiene viva la aplicación en las
|
||||
plataformas que sólo dan CPU mientras se atiende una petición, así que el tiempo de espera del
|
||||
programa externo debe superar lo que tarde el trabajo más largo; conviene limitarlo con
|
||||
[`with_timeout()`]. Si el programa externo corta antes, los trabajos siguen igualmente, pero en esas
|
||||
plataformas pueden quedarse sin CPU.
|
||||
|
||||
Cada llamada ejecuta lo programado en el último minuto, sea cual sea la instancia que la recibe y
|
||||
aunque acabe de arrancar: una llamada a las 4:30:20 ejecuta lo programado desde las 4:29:00
|
||||
(excluido) hasta las 4:30:00. Así ninguna instancia necesita recordar qué hicieron las demás, pero
|
||||
el programa externo debe llamar una vez, y sólo una, cada minuto: si falta una llamada se pierden
|
||||
sus ejecuciones, y si sobra, dos instancias pueden repetirlas. Para llamar con otra frecuencia
|
||||
(p. ej. cada cuarto de hora, en una plataforma que despierta la aplicación en cada llamada),
|
||||
indícala en `trigger_interval_secs` (`900`) y programa los trabajos en múltiplos de ella. La
|
||||
precisión es la del intervalo: con una llamada por minuto, un trabajo programado cada diez
|
||||
segundos se ejecuta una vez por minuto.
|
||||
|
||||
Una llamada de más suele ser un reintento. La respuesta es `200 OK` aunque falle algún trabajo, así
|
||||
que el programa externo sólo reintenta tras un error de red o si se agota su tiempo de espera; pero
|
||||
si el reintento llega a otra instancia, ésta ejecuta de nuevo lo mismo, porque las instancias no
|
||||
comparten estado. Desactiva los reintentos del programa externo (p. ej. `backoffLimit: 0` en un
|
||||
*CronJob* de Kubernetes) y, si un trabajo no debe repetirse nunca, que lo compruebe él mismo (p. ej.
|
||||
en la base de datos) antes de hacer nada.
|
||||
|
||||
## Ajustar un trabajo desde la configuración
|
||||
|
||||
Cada trabajo puede cambiarse por su clave, sin tocar el código, en la subsección
|
||||
`[cron.jobs."clave"]` (ver [`JobSettings`](config::JobSettings)):
|
||||
|
||||
```toml
|
||||
[cron.jobs."shop.cleanup"]
|
||||
schedule = "0 5 * * SUN" # Sólo los domingos a las 5:00.
|
||||
timeout_secs = 1800 # Tiempo máximo de 30 minutos (0 = sin límite).
|
||||
|
||||
[cron.jobs."shop.reminders"]
|
||||
enabled = false # Desactivado: sólo se ejecuta bajo demanda.
|
||||
```
|
||||
|
||||
La programación admite la misma sintaxis que [`Schedule::parse()`], incluidos `"@every 10m"` y
|
||||
`"@delay 30s"`. Una programación no válida detiene el arranque indicando el trabajo, y una clave
|
||||
que no corresponde a ningún trabajo se ignora con un aviso en las trazas.
|
||||
|
||||
## Ejecutar y consultar los trabajos
|
||||
|
||||
[`run_now()`] ejecuta un trabajo en el acto y devuelve su [`JobRun`]: útil para un botón
|
||||
«Ejecutar ahora» de un panel de administración, para una orden de mantenimiento o para las
|
||||
pruebas. [`jobs()`] y [`job()`] devuelven su [`JobStatus`]: programación efectiva, próxima
|
||||
ejecución, resultado de la última y número de ejecuciones, fallos y omisiones.
|
||||
|
||||
Para reaccionar a cada ejecución terminada (registrarla, enviar métricas, avisar cuando falla un
|
||||
trabajo), registra la acción [`AfterJobRun`].
|
||||
|
||||
## Detener la aplicación
|
||||
|
||||
Al detener la aplicación (Ctrl+C o `SIGTERM`), el planificador deja de lanzar ejecuciones y espera
|
||||
a que terminen las que están en curso, hasta `cron.shutdown_timeout_secs` (30 s por defecto). Un
|
||||
trabajo largo puede comprobar [`JobContext::is_stopping()`] para dejar su trabajo en un punto
|
||||
seguro antes de que se agote ese tiempo.
|
||||
|
||||
## Pruebas
|
||||
|
||||
El planificador sólo se pone en marcha con [`Application::run()`] (ver
|
||||
[`Extension::start()`](pagetop::core::extension::Extension::start)), nunca en las pruebas que
|
||||
preparan la aplicación y obtienen su servidor con [`Application::test()`]. En ellas, los trabajos
|
||||
se ejecutan cuando la prueba quiere con [`run_now()`]:
|
||||
|
||||
```rust,no_run
|
||||
# use pagetop::prelude::*;
|
||||
# struct Shop;
|
||||
# #[async_trait]
|
||||
# impl Extension for Shop {}
|
||||
#[pagetop::test]
|
||||
async fn cleanup_job_succeeds() {
|
||||
Application::prepare(&Shop).await;
|
||||
let run = pagetop_cron::run_now("shop.cleanup").await.unwrap();
|
||||
assert!(run.outcome().is_success(), "{}", run.outcome());
|
||||
}
|
||||
```
|
||||
|
||||
## Qué no hace
|
||||
|
||||
Para mantenerse sencilla, la extensión no guarda nada fuera de la memoria:
|
||||
|
||||
- **No recupera las ejecuciones perdidas.** Si la aplicación estaba detenida cuando tocaba una
|
||||
ejecución, no se hace al volver a arrancar; la siguiente llega según su programación. Para
|
||||
trabajos que no deben perder ninguna, combina la programación con
|
||||
[`with_run_on_start()`](Job::with_run_on_start), o guarda en la base de datos qué queda
|
||||
pendiente y procésalo en cada ejecución.
|
||||
- **No es una cola de trabajos.** Para tareas puntuales que deben sobrevivir a un reinicio (un
|
||||
correo que no se pudo enviar, una importación...), cada extensión guarda las pendientes en su
|
||||
propia tabla y declara un trabajo periódico que las procesa.
|
||||
- **No coordina varias instancias** por sí misma; ver [varias instancias](#varias-instancias).
|
||||
|
||||
[`Application::run()`]: pagetop::app::Application::run
|
||||
[`Application::test()`]: pagetop::app::Application::test
|
||||
|
||||
## Créditos
|
||||
|
||||
Las expresiones cron se interpretan con [croner](https://github.com/hexagon/croner-rust), la misma
|
||||
biblioteca que usa *tokio-cron-scheduler*, distribuida bajo licencia
|
||||
[MIT](https://github.com/hexagon/croner-rust/blob/master/LICENSE).
|
||||
*/
|
||||
|
||||
#![doc(
|
||||
html_favicon_url = "https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/assets/favicon.ico"
|
||||
)]
|
||||
|
||||
use pagetop::prelude::*;
|
||||
|
||||
pub mod config;
|
||||
|
||||
mod error;
|
||||
pub use error::CronError;
|
||||
|
||||
mod schedule;
|
||||
pub use schedule::Schedule;
|
||||
|
||||
mod job;
|
||||
pub use job::{Job, JobContext, JobResult, Overlap};
|
||||
|
||||
mod run;
|
||||
pub use run::{AfterJobRun, FnAfterJobRun, JobOutcome, JobRun, RunTrigger};
|
||||
|
||||
mod status;
|
||||
pub use status::JobStatus;
|
||||
|
||||
mod declare;
|
||||
pub use declare::{CronJobs, DeclareCronJobs, FnDeclareCronJobs};
|
||||
|
||||
mod scheduler;
|
||||
pub use scheduler::{TRIGGER_PATH, job, jobs, run_due, run_now};
|
||||
|
||||
include_locales!(LOCALES_CRON);
|
||||
|
||||
/// Prelude de `pagetop-cron`.
|
||||
pub mod prelude {
|
||||
pub use crate::{AfterJobRun, CronJobs, DeclareCronJobs};
|
||||
pub use crate::{CronError, Job, JobContext, JobResult, Overlap, Schedule};
|
||||
pub use crate::{JobOutcome, JobRun, JobStatus, RunTrigger};
|
||||
}
|
||||
|
||||
/// Implementa la extensión `pagetop-cron`.
|
||||
pub struct Cron;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for Cron {
|
||||
fn name(&self) -> Lc {
|
||||
Lc::t("extension_name", &LOCALES_CRON)
|
||||
}
|
||||
|
||||
fn description(&self) -> Lc {
|
||||
Lc::t("extension_description", &LOCALES_CRON)
|
||||
}
|
||||
|
||||
fn settings(&self) -> Option<&'static dyn LoadSettings> {
|
||||
Some(&config::SETTINGS)
|
||||
}
|
||||
|
||||
async fn initialize(&self) -> Result<(), BoxError> {
|
||||
// Recoge y valida los trabajos de todas las extensiones: un error detiene el arranque.
|
||||
scheduler::initialize()?;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
async fn start(&self) -> Result<(), BoxError> {
|
||||
scheduler::start();
|
||||
Ok(())
|
||||
}
|
||||
|
||||
async fn shutdown(&self) {
|
||||
scheduler::shutdown().await;
|
||||
}
|
||||
|
||||
fn configure_router(&self, router: Router) -> Router {
|
||||
if config::SETTINGS.mode != config::CronMode::External {
|
||||
return router;
|
||||
}
|
||||
router.route(TRIGGER_PATH, web::post(trigger_post).fallback(not_found))
|
||||
}
|
||||
}
|
||||
|
||||
// POST {TRIGGER_PATH} - Lanza los trabajos pendientes (modo externo). La clave llega en la cabecera
|
||||
// `Authorization` y no en la ruta, que suelen registrar los *proxies* y los balanceadores. Sin la
|
||||
// clave correcta, o con otro método, responde la misma página 404 que una ruta inexistente.
|
||||
async fn trigger_post(request: HttpRequest) -> Response {
|
||||
let token = request
|
||||
.headers()
|
||||
.get(web::http::header::AUTHORIZATION)
|
||||
.and_then(|value| value.to_str().ok())
|
||||
.and_then(|value| value.split_once(' '))
|
||||
.filter(|(scheme, _)| scheme.eq_ignore_ascii_case("Bearer"))
|
||||
.map(|(_, token)| token.trim_start());
|
||||
if !token.is_some_and(scheduler::token_matches) {
|
||||
return ErrorPage::NotFound(Some(request)).into_response();
|
||||
}
|
||||
// Siempre `200 OK`, aunque falle algún trabajo: un reintento del programa externo podría
|
||||
// llegar a otra instancia y repetir también los que terminaron bien. Sólo se indica el tipo de
|
||||
// resultado; los mensajes de error, que pueden revelar detalles internos, van a las trazas.
|
||||
let runs = run_due().await;
|
||||
let mut body = util::join!("Ran ", runs.len().to_string(), " cron jobs\n");
|
||||
for run in &runs {
|
||||
body.push_str(run.key());
|
||||
body.push_str(": ");
|
||||
body.push_str(match run.outcome() {
|
||||
JobOutcome::Succeeded => "succeeded",
|
||||
JobOutcome::Failed(_) => "failed",
|
||||
JobOutcome::TimedOut => "timed out",
|
||||
JobOutcome::Panicked(_) => "panicked",
|
||||
});
|
||||
body.push('\n');
|
||||
}
|
||||
(web::http::StatusCode::OK, body).into_response()
|
||||
}
|
||||
|
||||
async fn not_found(request: HttpRequest) -> ErrorPage {
|
||||
ErrorPage::NotFound(Some(request))
|
||||
}
|
||||
2
extensions/pagetop-cron/src/locale/en-US/extension.ftl
Normal file
2
extensions/pagetop-cron/src/locale/en-US/extension.ftl
Normal file
|
|
@ -0,0 +1,2 @@
|
|||
extension_name = Scheduled jobs
|
||||
extension_description = Runs periodic jobs with cron expressions or intervals, and on demand.
|
||||
2
extensions/pagetop-cron/src/locale/es-ES/extension.ftl
Normal file
2
extensions/pagetop-cron/src/locale/es-ES/extension.ftl
Normal file
|
|
@ -0,0 +1,2 @@
|
|||
extension_name = Tareas programadas
|
||||
extension_description = Ejecuta tareas periódicas con expresiones cron o intervalos, y bajo demanda.
|
||||
165
extensions/pagetop-cron/src/run.rs
Normal file
165
extensions/pagetop-cron/src/run.rs
Normal file
|
|
@ -0,0 +1,165 @@
|
|||
use pagetop::prelude::*;
|
||||
|
||||
use std::fmt;
|
||||
|
||||
/// Qué provocó la ejecución de un trabajo.
|
||||
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
|
||||
pub enum RunTrigger {
|
||||
/// Su programación, con el planificador de la aplicación (`mode = "internal"`).
|
||||
Schedule,
|
||||
/// El arranque de la aplicación ([`Job::with_run_on_start()`](crate::Job::with_run_on_start)).
|
||||
/// Con `mode = "external"`, en la primera llamada a `POST /cron` que recibe el proceso.
|
||||
Startup,
|
||||
/// Una llamada a [`run_now()`](crate::run_now).
|
||||
Manual,
|
||||
/// Su programación, con una llamada externa a `POST /cron` (`mode = "external"`).
|
||||
External,
|
||||
}
|
||||
|
||||
impl RunTrigger {
|
||||
/// Nombre corto en inglés, para trazas y registros.
|
||||
pub const fn as_str(&self) -> &'static str {
|
||||
match self {
|
||||
RunTrigger::Schedule => "schedule",
|
||||
RunTrigger::Startup => "startup",
|
||||
RunTrigger::Manual => "manual",
|
||||
RunTrigger::External => "external",
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Resultado de una ejecución de un trabajo.
|
||||
#[derive(Clone, Debug, Eq, PartialEq)]
|
||||
pub enum JobOutcome {
|
||||
/// Terminó sin errores.
|
||||
Succeeded,
|
||||
/// Devolvió un error, con su mensaje y el de sus causas.
|
||||
Failed(String),
|
||||
/// Superó su tiempo máximo ([`Job::with_timeout()`](crate::Job::with_timeout)) y se canceló.
|
||||
TimedOut,
|
||||
/// Provocó un `panic!`, con su mensaje. El `panic!` no afecta a la aplicación ni a las
|
||||
/// siguientes ejecuciones.
|
||||
Panicked(String),
|
||||
}
|
||||
|
||||
impl JobOutcome {
|
||||
/// Devuelve `true` si la ejecución terminó sin errores.
|
||||
pub fn is_success(&self) -> bool {
|
||||
matches!(self, JobOutcome::Succeeded)
|
||||
}
|
||||
}
|
||||
|
||||
impl fmt::Display for JobOutcome {
|
||||
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||||
match self {
|
||||
JobOutcome::Succeeded => f.write_str("succeeded"),
|
||||
JobOutcome::Failed(error) => write!(f, "failed: {error}"),
|
||||
JobOutcome::TimedOut => f.write_str("timed out"),
|
||||
JobOutcome::Panicked(message) => write!(f, "panicked: {message}"),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Informe de una ejecución terminada de un trabajo.
|
||||
///
|
||||
/// Lo devuelve [`run_now()`](crate::run_now), lo recibe la acción [`AfterJobRun`] y se guarda la
|
||||
/// última de cada trabajo en su [`JobStatus`](crate::JobStatus).
|
||||
#[derive(Clone, Debug, Getters)]
|
||||
pub struct JobRun {
|
||||
/// Devuelve la clave del trabajo.
|
||||
key: CowStr,
|
||||
/// Devuelve qué provocó la ejecución.
|
||||
#[getters(copy)]
|
||||
trigger: RunTrigger,
|
||||
/// Devuelve el momento en que empezó, en UTC.
|
||||
#[getters(copy)]
|
||||
started_at: DateTime<Utc>,
|
||||
/// Devuelve cuánto duró.
|
||||
#[getters(copy)]
|
||||
duration: Duration,
|
||||
/// Devuelve cómo terminó.
|
||||
outcome: JobOutcome,
|
||||
}
|
||||
|
||||
impl JobRun {
|
||||
pub(crate) fn new(
|
||||
key: CowStr,
|
||||
trigger: RunTrigger,
|
||||
started_at: DateTime<Utc>,
|
||||
duration: Duration,
|
||||
outcome: JobOutcome,
|
||||
) -> Self {
|
||||
JobRun {
|
||||
key,
|
||||
trigger,
|
||||
started_at,
|
||||
duration,
|
||||
outcome,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// **< AfterJobRun >********************************************************************************
|
||||
|
||||
/// Tipo de función que recibe el informe de cada ejecución terminada. Ver [`AfterJobRun`].
|
||||
pub type FnAfterJobRun = fn(run: &JobRun);
|
||||
|
||||
/// Acción que se despacha al terminar cada ejecución de cualquier trabajo, con su informe.
|
||||
///
|
||||
/// Sirve para vigilar los trabajos sin tocarlos: registrar las ejecuciones en una tabla, enviar
|
||||
/// métricas o avisar cuando uno falla. La función es síncrona y se ejecuta en la tarea del
|
||||
/// trabajo; para algo lento (p. ej. enviar un correo) lanza una tarea con `tokio::spawn()`. Un
|
||||
/// `panic!` en la función se registra en las trazas y no afecta al trabajo.
|
||||
///
|
||||
/// # Ejemplo
|
||||
///
|
||||
/// ```rust,no_run
|
||||
/// use pagetop::prelude::*;
|
||||
/// use pagetop_cron::prelude::*;
|
||||
///
|
||||
/// fn alert_on_failure(run: &JobRun) {
|
||||
/// if !run.outcome().is_success() {
|
||||
/// trace::warn!("ALERT: job \"{}\" {}", run.key(), run.outcome());
|
||||
/// }
|
||||
/// }
|
||||
///
|
||||
/// struct Monitor;
|
||||
///
|
||||
/// #[async_trait]
|
||||
/// impl Extension for Monitor {
|
||||
/// fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
/// vec![&pagetop_cron::Cron]
|
||||
/// }
|
||||
///
|
||||
/// fn actions(&self) -> Vec<ActionBox> {
|
||||
/// actions![AfterJobRun::new(alert_on_failure)]
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
pub struct AfterJobRun {
|
||||
f: FnAfterJobRun,
|
||||
weight: Weight,
|
||||
}
|
||||
|
||||
impl ActionDispatcher for AfterJobRun {
|
||||
fn weight(&self) -> Weight {
|
||||
self.weight
|
||||
}
|
||||
}
|
||||
|
||||
impl AfterJobRun {
|
||||
/// Registra una función que recibe el informe de cada ejecución.
|
||||
pub fn new(f: FnAfterJobRun) -> Self {
|
||||
AfterJobRun { f, weight: 0 }
|
||||
}
|
||||
|
||||
/// Opcional. Las acciones de menor peso se aplican antes. Se pueden usar valores negativos.
|
||||
pub fn with_weight(mut self, value: Weight) -> Self {
|
||||
self.weight = value;
|
||||
self
|
||||
}
|
||||
|
||||
pub(crate) fn dispatch(run: &JobRun) {
|
||||
dispatch_actions(|action: &Self| (action.f)(run));
|
||||
}
|
||||
}
|
||||
376
extensions/pagetop-cron/src/schedule.rs
Normal file
376
extensions/pagetop-cron/src/schedule.rs
Normal file
|
|
@ -0,0 +1,376 @@
|
|||
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(())
|
||||
}
|
||||
}
|
||||
956
extensions/pagetop-cron/src/scheduler.rs
Normal file
956
extensions/pagetop-cron/src/scheduler.rs
Normal file
|
|
@ -0,0 +1,956 @@
|
|||
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"))
|
||||
);
|
||||
}
|
||||
}
|
||||
42
extensions/pagetop-cron/src/status.rs
Normal file
42
extensions/pagetop-cron/src/status.rs
Normal file
|
|
@ -0,0 +1,42 @@
|
|||
use pagetop::prelude::*;
|
||||
|
||||
use crate::{JobRun, Schedule};
|
||||
|
||||
/// Estado de un trabajo: programación efectiva, próxima ejecución y cómo fue la última.
|
||||
///
|
||||
/// Lo devuelven [`jobs()`](crate::jobs) y [`job()`](crate::job), p. ej. para mostrar los trabajos
|
||||
/// en un panel de administración o comprobarlos en las pruebas. Es una copia: no cambia aunque el
|
||||
/// trabajo se vuelva a ejecutar.
|
||||
#[derive(Clone, Debug, Getters)]
|
||||
pub struct JobStatus {
|
||||
/// Devuelve la clave del trabajo.
|
||||
pub(crate) key: CowStr,
|
||||
/// Devuelve el título del trabajo (`Lc::none()` si no tiene).
|
||||
pub(crate) title: Lc,
|
||||
/// Devuelve la programación efectiva, la de la configuración si la cambia.
|
||||
pub(crate) schedule: Schedule,
|
||||
/// Devuelve la zona horaria en la que se interpreta la programación.
|
||||
#[getters(copy)]
|
||||
pub(crate) timezone: Tz,
|
||||
/// Devuelve si el trabajo se ejecuta de forma automática (`false` si lo desactiva la
|
||||
/// configuración).
|
||||
#[getters(copy)]
|
||||
pub(crate) enabled: bool,
|
||||
/// Devuelve cuántas ejecuciones del trabajo están en curso.
|
||||
#[getters(copy)]
|
||||
pub(crate) running: usize,
|
||||
/// Devuelve la próxima ejecución programada, en UTC, si la hay.
|
||||
#[getters(copy)]
|
||||
pub(crate) next_run: Option<DateTime<Utc>>,
|
||||
/// Devuelve el informe de la última ejecución terminada, si la hay.
|
||||
pub(crate) last_run: Option<JobRun>,
|
||||
/// Devuelve cuántas ejecuciones han terminado desde que arrancó la aplicación.
|
||||
#[getters(copy)]
|
||||
pub(crate) runs: u64,
|
||||
/// Devuelve cuántas de esas ejecuciones no terminaron bien (error, tiempo agotado o `panic!`).
|
||||
#[getters(copy)]
|
||||
pub(crate) failures: u64,
|
||||
/// Devuelve cuántas ejecuciones se omitieron porque la anterior aún no había terminado.
|
||||
#[getters(copy)]
|
||||
pub(crate) skipped: u64,
|
||||
}
|
||||
288
extensions/pagetop-cron/tests/jobs.rs
Normal file
288
extensions/pagetop-cron/tests/jobs.rs
Normal file
|
|
@ -0,0 +1,288 @@
|
|||
// `config/common.toml` uses the external mode, the Madrid timezone and job settings for some of the
|
||||
// jobs declared here. The scheduler never starts in tests (`Application::run()` is not called), so
|
||||
// jobs only run through `run_now()` and the external trigger route.
|
||||
|
||||
use pagetop::prelude::*;
|
||||
use pagetop_cron::prelude::*;
|
||||
|
||||
use std::sync::Mutex;
|
||||
use std::sync::atomic::{AtomicUsize, Ordering};
|
||||
|
||||
// Never due while the tests run, so the external trigger only starts the jobs a test expects.
|
||||
const LATER: &str = "0 0 0 1 1 * 2099";
|
||||
|
||||
static OK_RUNS: AtomicUsize = AtomicUsize::new(0);
|
||||
static REPORTS: Mutex<Vec<(String, bool)>> = Mutex::new(Vec::new());
|
||||
|
||||
struct TestApp;
|
||||
|
||||
#[async_trait]
|
||||
impl Extension for TestApp {
|
||||
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||
vec![&pagetop_cron::Cron]
|
||||
}
|
||||
|
||||
fn actions(&self) -> Vec<ActionBox> {
|
||||
actions![
|
||||
DeclareCronJobs::new(declare_jobs),
|
||||
AfterJobRun::new(|run| {
|
||||
REPORTS
|
||||
.lock()
|
||||
.unwrap()
|
||||
.push((run.key().to_string(), run.outcome().is_success()));
|
||||
}),
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
fn declare_jobs(jobs: &mut CronJobs) {
|
||||
jobs.add(
|
||||
Job::new("test.ok", Schedule::cron(LATER), |_| async {
|
||||
OK_RUNS.fetch_add(1, Ordering::SeqCst);
|
||||
Ok(())
|
||||
})
|
||||
.with_title(Lc::n("Works")),
|
||||
);
|
||||
jobs.add(Job::new("test.fails", Schedule::cron(LATER), |_| async {
|
||||
Err(std::io::Error::other("boom").into())
|
||||
}));
|
||||
jobs.add(Job::new("test.panics", Schedule::cron(LATER), |_| async {
|
||||
panic!("kaboom");
|
||||
}));
|
||||
jobs.add(
|
||||
Job::new("test.slow", Schedule::cron(LATER), |_| async {
|
||||
tokio::time::sleep(std::time::Duration::from_secs(10)).await;
|
||||
Ok(())
|
||||
})
|
||||
.with_timeout(Duration::milliseconds(100)),
|
||||
);
|
||||
jobs.add(Job::new("test.busy", Schedule::cron(LATER), |_| async {
|
||||
tokio::time::sleep(std::time::Duration::from_millis(300)).await;
|
||||
Ok(())
|
||||
}));
|
||||
jobs.add(
|
||||
Job::new("test.parallel", Schedule::cron(LATER), |_| async {
|
||||
tokio::time::sleep(std::time::Duration::from_millis(300)).await;
|
||||
Ok(())
|
||||
})
|
||||
.with_overlap(Overlap::Allow),
|
||||
);
|
||||
jobs.add(Job::new(
|
||||
"test.context",
|
||||
Schedule::cron(LATER),
|
||||
|cx| async move {
|
||||
if cx.key() != "test.context"
|
||||
|| cx.trigger() != RunTrigger::Manual
|
||||
|| cx.scheduled_at().is_some()
|
||||
|| cx.is_stopping()
|
||||
{
|
||||
return Err("unexpected job context".into());
|
||||
}
|
||||
Ok(())
|
||||
},
|
||||
));
|
||||
jobs.add(Job::new(
|
||||
"test.disabled",
|
||||
Schedule::cron("* * * * *"),
|
||||
|_| async { Ok(()) },
|
||||
));
|
||||
jobs.add(
|
||||
Job::new("test.overridden", Schedule::cron("0 * * * *"), |_| async {
|
||||
Ok(())
|
||||
})
|
||||
.with_timeout(Duration::minutes(1)),
|
||||
);
|
||||
jobs.add(Job::new("test.due", Schedule::cron(LATER), |_| async { Ok(()) }).with_run_on_start());
|
||||
}
|
||||
|
||||
async fn prepare() {
|
||||
Application::prepare(&TestApp).await;
|
||||
}
|
||||
|
||||
fn reported(key: &str) -> Vec<bool> {
|
||||
REPORTS
|
||||
.lock()
|
||||
.unwrap()
|
||||
.iter()
|
||||
.filter(|(k, _)| k == key)
|
||||
.map(|(_, ok)| *ok)
|
||||
.collect()
|
||||
}
|
||||
|
||||
#[pagetop::test]
|
||||
async fn a_job_runs_on_demand_and_reports() {
|
||||
prepare().await;
|
||||
let before = OK_RUNS.load(Ordering::SeqCst);
|
||||
|
||||
let run = pagetop_cron::run_now("test.ok").await.unwrap();
|
||||
assert_eq!(run.key(), "test.ok");
|
||||
assert_eq!(run.trigger(), RunTrigger::Manual);
|
||||
assert_eq!(run.outcome(), &JobOutcome::Succeeded);
|
||||
assert!(run.duration() >= Duration::zero());
|
||||
assert_eq!(OK_RUNS.load(Ordering::SeqCst), before + 1);
|
||||
|
||||
let status = pagetop_cron::job("test.ok").unwrap();
|
||||
assert!(status.runs() >= 1);
|
||||
assert_eq!(status.failures(), 0);
|
||||
assert_eq!(status.last_run().unwrap().outcome(), &JobOutcome::Succeeded);
|
||||
assert!(reported("test.ok").contains(&true));
|
||||
}
|
||||
|
||||
#[pagetop::test]
|
||||
async fn the_job_receives_its_context() {
|
||||
prepare().await;
|
||||
let run = pagetop_cron::run_now("test.context").await.unwrap();
|
||||
assert!(run.outcome().is_success(), "{}", run.outcome());
|
||||
}
|
||||
|
||||
#[pagetop::test]
|
||||
async fn errors_and_panics_are_reported_as_failures() {
|
||||
prepare().await;
|
||||
|
||||
let run = pagetop_cron::run_now("test.fails").await.unwrap();
|
||||
assert_eq!(run.outcome(), &JobOutcome::Failed("boom".to_owned()));
|
||||
assert_eq!(run.outcome().to_string(), "failed: boom");
|
||||
|
||||
let run = pagetop_cron::run_now("test.panics").await.unwrap();
|
||||
assert_eq!(run.outcome(), &JobOutcome::Panicked("kaboom".to_owned()));
|
||||
// A panic does not prevent the next run.
|
||||
let run = pagetop_cron::run_now("test.panics").await.unwrap();
|
||||
assert!(matches!(run.outcome(), JobOutcome::Panicked(_)));
|
||||
|
||||
let status = pagetop_cron::job("test.panics").unwrap();
|
||||
assert_eq!(status.running(), 0);
|
||||
assert!(status.failures() >= 2);
|
||||
assert!(reported("test.fails").contains(&false));
|
||||
}
|
||||
|
||||
#[pagetop::test]
|
||||
async fn a_job_over_its_timeout_is_cancelled() {
|
||||
prepare().await;
|
||||
let clock = std::time::Instant::now();
|
||||
let run = pagetop_cron::run_now("test.slow").await.unwrap();
|
||||
assert_eq!(run.outcome(), &JobOutcome::TimedOut);
|
||||
assert!(clock.elapsed() < std::time::Duration::from_secs(5));
|
||||
// The run is released once the cancelled task has actually stopped.
|
||||
let mut running = 1;
|
||||
for _ in 0..50 {
|
||||
running = pagetop_cron::job("test.slow").unwrap().running();
|
||||
if running == 0 {
|
||||
break;
|
||||
}
|
||||
tokio::time::sleep(std::time::Duration::from_millis(20)).await;
|
||||
}
|
||||
assert_eq!(running, 0);
|
||||
}
|
||||
|
||||
#[pagetop::test]
|
||||
async fn overlapping_runs_are_refused_unless_allowed() {
|
||||
prepare().await;
|
||||
|
||||
let (first, second) = tokio::join!(pagetop_cron::run_now("test.busy"), async {
|
||||
tokio::time::sleep(std::time::Duration::from_millis(50)).await;
|
||||
pagetop_cron::run_now("test.busy").await
|
||||
});
|
||||
assert!(first.unwrap().outcome().is_success());
|
||||
assert!(matches!(second, Err(CronError::AlreadyRunning(key)) if key == "test.busy"));
|
||||
|
||||
let (first, second) = tokio::join!(pagetop_cron::run_now("test.parallel"), async {
|
||||
tokio::time::sleep(std::time::Duration::from_millis(50)).await;
|
||||
pagetop_cron::run_now("test.parallel").await
|
||||
});
|
||||
assert!(first.unwrap().outcome().is_success());
|
||||
assert!(second.unwrap().outcome().is_success());
|
||||
}
|
||||
|
||||
#[pagetop::test]
|
||||
async fn unknown_jobs_cannot_run() {
|
||||
prepare().await;
|
||||
let err = pagetop_cron::run_now("test.missing").await.unwrap_err();
|
||||
assert!(matches!(err, CronError::UnknownJob(key) if key == "test.missing"));
|
||||
assert!(pagetop_cron::job("test.missing").is_none());
|
||||
}
|
||||
|
||||
#[pagetop::test]
|
||||
async fn statuses_show_the_effective_settings() {
|
||||
prepare().await;
|
||||
let jobs = pagetop_cron::jobs();
|
||||
let keys: Vec<_> = jobs.iter().map(|job| job.key().to_string()).collect();
|
||||
let mut sorted = keys.clone();
|
||||
sorted.sort();
|
||||
assert_eq!(keys, sorted);
|
||||
assert_eq!(keys.len(), 10);
|
||||
|
||||
let ok = pagetop_cron::job("test.ok").unwrap();
|
||||
assert!(!ok.title().is_none());
|
||||
assert!(pagetop_cron::job("test.fails").unwrap().title().is_none());
|
||||
assert_eq!(ok.schedule().to_string(), LATER);
|
||||
assert_eq!(ok.timezone(), Tz::Europe__Madrid);
|
||||
assert!(ok.enabled());
|
||||
// External mode: the next run is known from startup.
|
||||
assert!(ok.next_run().is_some_and(|next| next > Utc::now()));
|
||||
|
||||
let disabled = pagetop_cron::job("test.disabled").unwrap();
|
||||
assert!(!disabled.enabled());
|
||||
assert!(disabled.next_run().is_none());
|
||||
|
||||
let overridden = pagetop_cron::job("test.overridden").unwrap();
|
||||
assert_eq!(overridden.schedule().to_string(), "@delay 1m30s");
|
||||
|
||||
// A disabled job still runs on demand.
|
||||
let run = pagetop_cron::run_now("test.disabled").await.unwrap();
|
||||
assert!(run.outcome().is_success());
|
||||
}
|
||||
|
||||
async fn post(app: &Router, auth: &str) -> (web::http::StatusCode, String) {
|
||||
let req = web::test::TestRequest::post()
|
||||
.uri("/cron")
|
||||
.header("authorization", auth)
|
||||
.to_request();
|
||||
let resp = web::test::send_request(app, req).await;
|
||||
let status = resp.status();
|
||||
(status, web::test::read_body_text(resp).await)
|
||||
}
|
||||
|
||||
#[pagetop::test]
|
||||
async fn the_external_trigger_runs_the_due_jobs() {
|
||||
let app = web::test::init_router(Application::prepare(&TestApp).await.test());
|
||||
|
||||
for auth in [
|
||||
"Bearer wrong-token-0123456789",
|
||||
"Bearer test-token-012345678",
|
||||
"test-token-0123456789",
|
||||
"Basic test-token-0123456789",
|
||||
] {
|
||||
let (status, _) = post(&app, auth).await;
|
||||
assert_eq!(status, web::http::StatusCode::NOT_FOUND, "{auth}");
|
||||
}
|
||||
// Without the header at all, with another method, or with the token in the path.
|
||||
let req = web::test::TestRequest::post().uri("/cron").to_request();
|
||||
let resp = web::test::send_request(&app, req).await;
|
||||
assert_eq!(resp.status(), web::http::StatusCode::NOT_FOUND);
|
||||
let req = web::test::TestRequest::get().uri("/cron").to_request();
|
||||
let resp = web::test::send_request(&app, req).await;
|
||||
assert_eq!(resp.status(), web::http::StatusCode::NOT_FOUND);
|
||||
let req = web::test::TestRequest::post()
|
||||
.uri("/cron/test-token-0123456789")
|
||||
.to_request();
|
||||
let resp = web::test::send_request(&app, req).await;
|
||||
assert_eq!(resp.status(), web::http::StatusCode::NOT_FOUND);
|
||||
assert_eq!(pagetop_cron::job("test.due").unwrap().runs(), 0);
|
||||
|
||||
// "test.due" runs on the first call because it runs on start. The scheme is case-insensitive.
|
||||
// The response arrives once the jobs have finished, with one line per job.
|
||||
let (status, body) = post(&app, "bearer test-token-0123456789").await;
|
||||
assert_eq!(status, web::http::StatusCode::OK);
|
||||
assert!(body.starts_with("Ran "), "{body}");
|
||||
assert!(body.contains("\ntest.due: succeeded\n"), "{body}");
|
||||
assert_eq!(pagetop_cron::job("test.due").unwrap().runs(), 1);
|
||||
let due = pagetop_cron::job("test.due").unwrap();
|
||||
assert_eq!(due.last_run().unwrap().trigger(), RunTrigger::Startup);
|
||||
assert!(due.next_run().is_some_and(|next| next > Utc::now()));
|
||||
|
||||
// Not again on later calls.
|
||||
let (status, body) = post(&app, "Bearer test-token-0123456789").await;
|
||||
assert_eq!(status, web::http::StatusCode::OK);
|
||||
assert!(!body.contains("test.due"), "{body}");
|
||||
assert_eq!(pagetop_cron::job("test.due").unwrap().runs(), 1);
|
||||
}
|
||||
180
extensions/pagetop-cron/tests/schedule.rs
Normal file
180
extensions/pagetop-cron/tests/schedule.rs
Normal file
|
|
@ -0,0 +1,180 @@
|
|||
use pagetop::prelude::*;
|
||||
use pagetop_cron::prelude::*;
|
||||
|
||||
fn at(text: &str) -> DateTime<Utc> {
|
||||
text.parse().unwrap()
|
||||
}
|
||||
|
||||
fn next(schedule: &str, after: &str, tz: Tz) -> String {
|
||||
Schedule::parse(schedule)
|
||||
.unwrap()
|
||||
.next_after(at(after), tz)
|
||||
.unwrap()
|
||||
.unwrap()
|
||||
.to_rfc3339()
|
||||
}
|
||||
|
||||
#[pagetop::test]
|
||||
async fn cron_expressions_and_nicknames_are_accepted() {
|
||||
for text in [
|
||||
"*/10 * * * *",
|
||||
"*/30 * * * * *",
|
||||
"30 4 * * *",
|
||||
"0 8-18 * * MON-FRI",
|
||||
"0 0 L * *",
|
||||
"0 9 15W * *",
|
||||
"0 9 * * MON#1",
|
||||
"0 18 * * 5L",
|
||||
"@yearly",
|
||||
"@annually",
|
||||
"@monthly",
|
||||
"@weekly",
|
||||
"@daily",
|
||||
"@hourly",
|
||||
] {
|
||||
let schedule = Schedule::parse(text).unwrap_or_else(|err| panic!("{text}: {err}"));
|
||||
// The text is kept as written.
|
||||
assert_eq!(schedule.to_string(), text);
|
||||
}
|
||||
}
|
||||
|
||||
#[pagetop::test]
|
||||
async fn intervals_are_parsed_and_written_back() {
|
||||
let cases = [
|
||||
(
|
||||
"@every 30s",
|
||||
"@every 30s",
|
||||
Schedule::fixed_rate(Duration::seconds(30)),
|
||||
),
|
||||
(
|
||||
"@every 1h30m",
|
||||
"@every 1h30m",
|
||||
Schedule::fixed_rate(Duration::minutes(90)),
|
||||
),
|
||||
(
|
||||
"@every 1h 30m",
|
||||
"@every 1h30m",
|
||||
Schedule::fixed_rate(Duration::minutes(90)),
|
||||
),
|
||||
(
|
||||
"@EVERY 2d",
|
||||
"@every 2d",
|
||||
Schedule::fixed_rate(Duration::days(2)),
|
||||
),
|
||||
(
|
||||
" @delay 500ms ",
|
||||
"@delay 500ms",
|
||||
Schedule::fixed_delay(Duration::milliseconds(500)),
|
||||
),
|
||||
(
|
||||
"@delay 90s",
|
||||
"@delay 1m30s",
|
||||
Schedule::fixed_delay(Duration::seconds(90)),
|
||||
),
|
||||
];
|
||||
for (text, written, expected) in cases {
|
||||
let schedule: Schedule = text.parse().unwrap();
|
||||
assert_eq!(schedule, expected, "{text}");
|
||||
assert_eq!(schedule.to_string(), written, "{text}");
|
||||
}
|
||||
}
|
||||
|
||||
#[pagetop::test]
|
||||
async fn invalid_schedules_are_rejected() {
|
||||
for text in [
|
||||
"",
|
||||
"61 * * * *",
|
||||
"* * *",
|
||||
"0 0 32 * *",
|
||||
"every day",
|
||||
"@every",
|
||||
"@every 0s",
|
||||
"@every 5",
|
||||
"@every 5x",
|
||||
"@every -1s",
|
||||
"@delay m",
|
||||
"@every 36501d",
|
||||
] {
|
||||
let err = Schedule::parse(text).unwrap_err();
|
||||
assert!(
|
||||
matches!(err, CronError::InvalidSchedule { .. }),
|
||||
"{text}: {err}"
|
||||
);
|
||||
}
|
||||
// Constructors do not validate; the first use does.
|
||||
let zero = Schedule::fixed_delay(Duration::zero());
|
||||
assert!(zero.next_after(Utc::now(), Tz::UTC).is_err());
|
||||
}
|
||||
|
||||
#[pagetop::test]
|
||||
async fn cron_expressions_follow_the_timezone() {
|
||||
// 9:00 in Madrid: 8:00 UTC in winter, 7:00 UTC in summer.
|
||||
let madrid = Tz::Europe__Madrid;
|
||||
assert_eq!(
|
||||
next("0 9 * * *", "2026-01-15T00:00:00Z", madrid),
|
||||
"2026-01-15T08:00:00+00:00"
|
||||
);
|
||||
assert_eq!(
|
||||
next("0 9 * * *", "2026-07-15T00:00:00Z", madrid),
|
||||
"2026-07-15T07:00:00+00:00"
|
||||
);
|
||||
assert_eq!(
|
||||
next("0 9 * * *", "2026-07-15T00:00:00Z", Tz::UTC),
|
||||
"2026-07-15T09:00:00+00:00"
|
||||
);
|
||||
}
|
||||
|
||||
#[pagetop::test]
|
||||
async fn special_characters_select_the_right_days() {
|
||||
let madrid = Tz::Europe__Madrid;
|
||||
// First Monday of November 2026 (CET, UTC+1).
|
||||
assert_eq!(
|
||||
next("0 9 * * MON#1", "2026-10-19T00:00:00Z", madrid),
|
||||
"2026-11-02T08:00:00+00:00"
|
||||
);
|
||||
// Last day of February 2026.
|
||||
assert_eq!(
|
||||
next("0 0 L * *", "2026-02-10T00:00:00Z", madrid),
|
||||
"2026-02-27T23:00:00+00:00"
|
||||
);
|
||||
// Last Friday of October 2026 (still CEST, UTC+2).
|
||||
assert_eq!(
|
||||
next("0 18 * * 5L", "2026-10-01T00:00:00Z", madrid),
|
||||
"2026-10-30T17:00:00+00:00"
|
||||
);
|
||||
// Nearest weekday to Saturday 15 August 2026: Friday 14.
|
||||
assert_eq!(
|
||||
next("0 9 15W * *", "2026-08-01T00:00:00Z", madrid),
|
||||
"2026-08-14T07:00:00+00:00"
|
||||
);
|
||||
}
|
||||
|
||||
#[pagetop::test]
|
||||
async fn daylight_saving_changes_run_once() {
|
||||
let madrid = Tz::Europe__Madrid;
|
||||
// Spring forward on 29 March 2026: 2:30 does not exist; it runs when the next hour starts
|
||||
// (3:00 CEST = 1:00 UTC), and the day after at 2:30 again.
|
||||
assert_eq!(
|
||||
next("30 2 * * *", "2026-03-28T12:00:00Z", madrid),
|
||||
"2026-03-29T01:00:00+00:00"
|
||||
);
|
||||
assert_eq!(
|
||||
next("30 2 * * *", "2026-03-29T01:00:00Z", madrid),
|
||||
"2026-03-30T00:30:00+00:00"
|
||||
);
|
||||
// Fall back on 25 October 2026: 2:30 happens twice; it runs only once.
|
||||
let first = next("30 2 * * *", "2026-10-24T12:00:00Z", madrid);
|
||||
assert_eq!(first, "2026-10-25T00:30:00+00:00");
|
||||
assert_eq!(
|
||||
next("30 2 * * *", &first, madrid),
|
||||
"2026-10-26T01:30:00+00:00"
|
||||
);
|
||||
}
|
||||
|
||||
#[pagetop::test]
|
||||
async fn intervals_ignore_the_timezone() {
|
||||
let after = "2026-03-29T00:30:00Z";
|
||||
let every = Schedule::fixed_rate(Duration::hours(1));
|
||||
let next = every.next_after(at(after), Tz::Europe__Madrid).unwrap();
|
||||
assert_eq!(next, Some(at("2026-03-29T01:30:00Z")));
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue