diff --git a/Cargo.lock b/Cargo.lock index fddb5dcc..2b9dabd1 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -666,6 +666,17 @@ dependencies = [ "cfg-if", ] +[[package]] +name = "croner" +version = "4.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4b5b023fc2978536bbb2a3b71237964fc4630bec1eb31077b4977127f4cdb9c0" +dependencies = [ + "chrono", + "derive_builder", + "strum 0.27.2", +] + [[package]] name = "crossbeam-channel" version = "0.5.15" @@ -748,6 +759,7 @@ dependencies = [ "ident_case", "proc-macro2", "quote", + "strsim", "syn", ] @@ -782,6 +794,37 @@ dependencies = [ "powerfmt", ] +[[package]] +name = "derive_builder" +version = "0.20.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "507dfb09ea8b7fa618fcf76e953f4f5e192547945816d5358edffe39f6f94947" +dependencies = [ + "derive_builder_macro", +] + +[[package]] +name = "derive_builder_core" +version = "0.20.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2d5bcf7b024d6835cfb3d473887cd966994907effbe9227e8c8219824d06c4e8" +dependencies = [ + "darling", + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "derive_builder_macro" +version = "0.20.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ab63b0e2bf4d5928aff72e83a7dace85d7bba5fe12dcc3c5a572d78caffd3f3c" +dependencies = [ + "derive_builder_core", + "syn", +] + [[package]] name = "derive_more" version = "2.1.1" @@ -2156,6 +2199,17 @@ dependencies = [ "pagetop-statics", ] +[[package]] +name = "pagetop-cron" +version = "0.1.0" +dependencies = [ + "croner", + "pagetop", + "serde", + "thiserror", + "tokio", +] + [[package]] name = "pagetop-htmx" version = "0.1.0" @@ -2756,7 +2810,7 @@ dependencies = [ "sea-query-binder", "serde", "sqlx", - "strum", + "strum 0.26.3", "thiserror", "tracing", "url", @@ -3310,6 +3364,27 @@ version = "0.26.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "8fec0f0aef304996cf250b31b5a10dee7980c85da9d759361292b8bca5a18f06" +[[package]] +name = "strum" +version = "0.27.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "af23d6f6c1a224baef9d3f61e287d2761385a5b88fdab4eb4c6f11aeb54c4bcf" +dependencies = [ + "strum_macros", +] + +[[package]] +name = "strum_macros" +version = "0.27.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7695ce3845ea4b33927c055a39dc438a45b059f7c1b3d91d38d10355fb8cbca7" +dependencies = [ + "heck 0.5.0", + "proc-macro2", + "quote", + "syn", +] + [[package]] name = "subtle" version = "2.6.1" diff --git a/Cargo.toml b/Cargo.toml index 60af40a1..3b9603d1 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -11,6 +11,7 @@ members = [ "extensions/pagetop-bootsier", "extensions/pagetop-htmx", "extensions/pagetop-admin", + "extensions/pagetop-cron", "extensions/pagetop-mail", "extensions/pagetop-seaorm", "extensions/pagetop-user", @@ -34,6 +35,7 @@ chrono = "0.4" chrono-tz = "0.10" colored = "3.1" config = { version = "0.15", default-features = false, features = ["toml"] } +croner = { version = "4.0", default-features = false, features = ["chrono"] } figlet-rs = "1.0" fluent-templates = "0.14" getter-methods = "2.0" @@ -79,6 +81,7 @@ pagetop-statics = { version = "0.1", path = "helpers/pagetop-statics" } pagetop-admin = { version = "0.1", path = "extensions/pagetop-admin" } pagetop-aliner = { version = "0.1", path = "extensions/pagetop-aliner" } pagetop-bootsier = { version = "0.1", path = "extensions/pagetop-bootsier" } +pagetop-cron = { version = "0.1", path = "extensions/pagetop-cron" } pagetop-htmx = { version = "0.1", path = "extensions/pagetop-htmx" } pagetop-mail = { version = "0.1", path = "extensions/pagetop-mail" } pagetop-seaorm = { version = "0.0", path = "extensions/pagetop-seaorm" } diff --git a/config/reference.toml b/config/reference.toml index 41e082ce..668de457 100644 --- a/config/reference.toml +++ b/config/reference.toml @@ -157,6 +157,33 @@ accept_invalid_certs = false # Acepta certificados no válidos. PELIGROSO dir = "mail" # Directorio de los archivos .eml. Se crea si no existe. +# **< pagetop-cron >******************************************************************************** + +[cron] +mode = "internal" # Cómo se ejecutan los trabajos programados: + # "internal" -> con el planificador de la propia aplicación. + # "external" -> cuando un programa externo (crontab, systemd) + # llama a POST /cron con la cabecera + # "Authorization: Bearer {trigger_token}". + # "off" -> nunca de forma automática, sólo bajo demanda. + # Con varias instancias, "internal" sólo en una ("off" en las + # demás), o "external" en todas. +#trigger_token = "..." # Clave secreta del modo "external": 16 o más letras, + # dígitos, "-" o "_" (p. ej. de "openssl rand -hex 32"). + # Mejor en config/local.toml. +trigger_interval_secs = 60 # Segundos entre dos llamadas del modo "external": cada una + # ejecuta lo programado en el último intervalo, así que debe + # llegar una, y sólo una, por intervalo. +shutdown_timeout_secs = 30 # Espera máxima, al detener la aplicación, a que terminen los + # trabajos en curso. + +[cron.jobs."shop.cleanup"] # Ajustes de un trabajo, por su clave (opcional). +enabled = true # false -> no se ejecuta de forma automática. +#schedule = "*/10 * * * *" # Sustituye su programación: expresión cron, "@daily", + # "@every 5m" (cada 5 min) o "@delay 30s" (30 s tras terminar). +#timeout_secs = 600 # Sustituye su tiempo máximo por ejecución. 0 -> sin límite. + + # **< pagetop-user >******************************************************************************** [user] diff --git a/extensions/pagetop-cron/Cargo.toml b/extensions/pagetop-cron/Cargo.toml new file mode 100644 index 00000000..14e96a9e --- /dev/null +++ b/extensions/pagetop-cron/Cargo.toml @@ -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 diff --git a/extensions/pagetop-cron/LICENSE-APACHE b/extensions/pagetop-cron/LICENSE-APACHE new file mode 100644 index 00000000..56cfd2db --- /dev/null +++ b/extensions/pagetop-cron/LICENSE-APACHE @@ -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. \ No newline at end of file diff --git a/extensions/pagetop-cron/LICENSE-MIT b/extensions/pagetop-cron/LICENSE-MIT new file mode 100644 index 00000000..4227455e --- /dev/null +++ b/extensions/pagetop-cron/LICENSE-MIT @@ -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. \ No newline at end of file diff --git a/extensions/pagetop-cron/README.md b/extensions/pagetop-cron/README.md new file mode 100644 index 00000000..849b16ad --- /dev/null +++ b/extensions/pagetop-cron/README.md @@ -0,0 +1,333 @@ +
+ +

PageTop Cron

+ +

Programación de tareas para aplicaciones PageTop.

+ +[![Doc API](https://img.shields.io/docsrs/pagetop-cron?label=Doc%20API&style=for-the-badge&logo=Docs.rs)](https://docs.rs/pagetop-cron) +[![Crates.io](https://img.shields.io/crates/v/pagetop-cron.svg?style=for-the-badge&logo=ipfs)](https://crates.io/crates/pagetop-cron) +[![Descargas](https://img.shields.io/crates/d/pagetop-cron.svg?label=Descargas&style=for-the-badge&logo=transmission)](https://crates.io/crates/pagetop-cron) +[![Licencia](https://img.shields.io/badge/license-MIT%2FApache-blue.svg?label=Licencia&style=for-the-badge)](https://git.cillero.es/manuelcillero/pagetop/src/branch/main/extensions/pagetop-cron#licencia) + +
+ +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 { + vec![&pagetop_cron::Cron] + } + + fn actions(&self) -> Vec { + 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 `, 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 ". +* * * * * 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. diff --git a/extensions/pagetop-cron/config/common.toml b/extensions/pagetop-cron/config/common.toml new file mode 100644 index 00000000..92b7d285 --- /dev/null +++ b/extensions/pagetop-cron/config/common.toml @@ -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 diff --git a/extensions/pagetop-cron/src/config.rs b/extensions/pagetop-cron/src/config.rs new file mode 100644 index 00000000..981f45ca --- /dev/null +++ b/extensions/pagetop-cron/src/config.rs @@ -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 = 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 `. 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, + /// 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, +} + +/// 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, + /// Sustituye el tiempo máximo de cada ejecución, en segundos. `0` quita el límite. + pub timeout_secs: Option, +} + +#[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::(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::( + 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); + } +} diff --git a/extensions/pagetop-cron/src/declare.rs b/extensions/pagetop-cron/src/declare.rs new file mode 100644 index 00000000..146320fb --- /dev/null +++ b/extensions/pagetop-cron/src/declare.rs @@ -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, +} + +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 { + 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 { +/// vec![&pagetop_cron::Cron] +/// } +/// +/// fn actions(&self) -> Vec { +/// 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 + } +} diff --git a/extensions/pagetop-cron/src/error.rs b/extensions/pagetop-cron/src/error.rs new file mode 100644 index 00000000..fc922ddc --- /dev/null +++ b/extensions/pagetop-cron/src/error.rs @@ -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, + }, + /// 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, +} diff --git a/extensions/pagetop-cron/src/job.rs b/extensions/pagetop-cron/src/job.rs new file mode 100644 index 00000000..a952dfd3 --- /dev/null +++ b/extensions/pagetop-cron/src/job.rs @@ -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 Pin + 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, + /// Devuelve la zona horaria propia del trabajo, si la tiene. + #[getters(copy)] + timezone: Option, + /// 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(key: impl Into, schedule: Schedule, run: F) -> Self + where + F: Fn(JobContext) -> Fut + Send + Sync + 'static, + Fut: Future + 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>) -> 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>) -> 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>, + stop: watch::Receiver, +} + +impl JobContext { + pub(crate) fn new( + key: CowStr, + trigger: RunTrigger, + scheduled_at: Option>, + stop: watch::Receiver, + ) -> 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> { + 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; + } + } +} diff --git a/extensions/pagetop-cron/src/lib.rs b/extensions/pagetop-cron/src/lib.rs new file mode 100644 index 00000000..e4694b4e --- /dev/null +++ b/extensions/pagetop-cron/src/lib.rs @@ -0,0 +1,442 @@ +/*! +
+ +

PageTop Cron

+ +

Programación de tareas para aplicaciones PageTop.

+ +[![Doc API](https://img.shields.io/docsrs/pagetop-cron?label=Doc%20API&style=for-the-badge&logo=Docs.rs)](https://docs.rs/pagetop-cron) +[![Crates.io](https://img.shields.io/crates/v/pagetop-cron.svg?style=for-the-badge&logo=ipfs)](https://crates.io/crates/pagetop-cron) +[![Descargas](https://img.shields.io/crates/d/pagetop-cron.svg?label=Descargas&style=for-the-badge&logo=transmission)](https://crates.io/crates/pagetop-cron) +[![Licencia](https://img.shields.io/badge/license-MIT%2FApache-blue.svg?label=Licencia&style=for-the-badge)](https://git.cillero.es/manuelcillero/pagetop/src/branch/main/extensions/pagetop-cron#licencia) + +
+ +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 { + vec![&pagetop_cron::Cron] + } + + fn actions(&self) -> Vec { + 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 `, 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 ". +* * * * * 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)) +} diff --git a/extensions/pagetop-cron/src/locale/en-US/extension.ftl b/extensions/pagetop-cron/src/locale/en-US/extension.ftl new file mode 100644 index 00000000..00383054 --- /dev/null +++ b/extensions/pagetop-cron/src/locale/en-US/extension.ftl @@ -0,0 +1,2 @@ +extension_name = Scheduled jobs +extension_description = Runs periodic jobs with cron expressions or intervals, and on demand. diff --git a/extensions/pagetop-cron/src/locale/es-ES/extension.ftl b/extensions/pagetop-cron/src/locale/es-ES/extension.ftl new file mode 100644 index 00000000..207ee45a --- /dev/null +++ b/extensions/pagetop-cron/src/locale/es-ES/extension.ftl @@ -0,0 +1,2 @@ +extension_name = Tareas programadas +extension_description = Ejecuta tareas periódicas con expresiones cron o intervalos, y bajo demanda. diff --git a/extensions/pagetop-cron/src/run.rs b/extensions/pagetop-cron/src/run.rs new file mode 100644 index 00000000..f2f09423 --- /dev/null +++ b/extensions/pagetop-cron/src/run.rs @@ -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, + /// 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, + 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 { +/// vec![&pagetop_cron::Cron] +/// } +/// +/// fn actions(&self) -> Vec { +/// 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)); + } +} diff --git a/extensions/pagetop-cron/src/schedule.rs b/extensions/pagetop-cron/src/schedule.rs new file mode 100644 index 00000000..030e3447 --- /dev/null +++ b/extensions/pagetop-cron/src/schedule.rs @@ -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) -> 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 "` para [`fixed_rate()`](Self::fixed_rate) y `"@delay "` + /// 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 { + 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::>().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, + tz: Tz, + ) -> Result>, 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 { + 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 { + 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), + FixedRate(Duration), + FixedDelay(Duration), +} + +impl Trigger { + // Primera ejecución posterior a `after`. + pub(crate) fn next_after(&self, after: DateTime, tz: Tz) -> Option> { + 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, tz: Tz) -> Option> { + 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, + now: DateTime, + tz: Tz, + ) -> Option> { + 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 { + match self { + Trigger::FixedDelay(delay) => Some(*delay), + _ => None, + } + } +} + +// **< Funciones auxiliares >*********************************************************************** + +fn invalid(schedule: &str, reason: impl Into) -> 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 { + 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 { + 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(()) + } +} diff --git a/extensions/pagetop-cron/src/scheduler.rs b/extensions/pagetop-cron/src/scheduler.rs new file mode 100644 index 00000000..772e408b --- /dev/null +++ b/extensions/pagetop-cron/src/scheduler.rs @@ -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 = 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> = 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>, +} + +// Un trabajo con sus ajustes ya aplicados y su estado. +struct Entry { + job: Job, + schedule: Schedule, + trigger: Trigger, + timezone: Tz, + timeout: Option, + enabled: bool, + running: AtomicUsize, + state: Mutex, +} + +#[derive(AutoDefault)] +struct State { + next_run: Option>, + // Sólo en el modo externo: si falta la ejecución del arranque, y el último intervalo atendido. + pending_start: bool, + last_window: Option>, + last_run: Option, + 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, now: DateTime) -> Result { + 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 { + 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, interval: Duration) -> Option> { + 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, + ) -> Result { + 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, + interval: Duration, + ) -> Option<(RunTrigger, Option>)> { + 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>) { + 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) -> Option { + 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); + +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 { + 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) -> Option { + 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) -> Result { + 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 { + 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, 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) { + 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, trigger: RunTrigger, at: Option>) { + 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, stop: &mut watch::Receiver) -> 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>) -> 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) -> String { + match payload.downcast::() { + 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 = 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 { + text.parse().unwrap() + } + + fn build_error(jobs: Vec) -> 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")) + ); + } +} diff --git a/extensions/pagetop-cron/src/status.rs b/extensions/pagetop-cron/src/status.rs new file mode 100644 index 00000000..8539f57e --- /dev/null +++ b/extensions/pagetop-cron/src/status.rs @@ -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>, + /// Devuelve el informe de la última ejecución terminada, si la hay. + pub(crate) last_run: Option, + /// 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, +} diff --git a/extensions/pagetop-cron/tests/jobs.rs b/extensions/pagetop-cron/tests/jobs.rs new file mode 100644 index 00000000..bbc74968 --- /dev/null +++ b/extensions/pagetop-cron/tests/jobs.rs @@ -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> = Mutex::new(Vec::new()); + +struct TestApp; + +#[async_trait] +impl Extension for TestApp { + fn dependencies(&self) -> Vec { + vec![&pagetop_cron::Cron] + } + + fn actions(&self) -> Vec { + 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 { + 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); +} diff --git a/extensions/pagetop-cron/tests/schedule.rs b/extensions/pagetop-cron/tests/schedule.rs new file mode 100644 index 00000000..c9d7e9ea --- /dev/null +++ b/extensions/pagetop-cron/tests/schedule.rs @@ -0,0 +1,180 @@ +use pagetop::prelude::*; +use pagetop_cron::prelude::*; + +fn at(text: &str) -> DateTime { + 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"))); +} diff --git a/tools/changelog.sh b/tools/changelog.sh index 7996b37e..ef71bc45 100755 --- a/tools/changelog.sh +++ b/tools/changelog.sh @@ -66,6 +66,7 @@ case "$CRATE" in --exclude-path "extensions/pagetop-admin/**/*" --exclude-path "extensions/pagetop-aliner/**/*" --exclude-path "extensions/pagetop-bootsier/**/*" + --exclude-path "extensions/pagetop-cron/**/*" --exclude-path "extensions/pagetop-htmx/**/*" --exclude-path "extensions/pagetop-mail/**/*" --exclude-path "extensions/pagetop-seaorm/**/*" @@ -84,6 +85,10 @@ case "$CRATE" in CHANGELOG_FILE="extensions/pagetop-bootsier/CHANGELOG.md" PATH_FLAGS=(--include-path "extensions/pagetop-bootsier/**/*") ;; + pagetop-cron) + CHANGELOG_FILE="extensions/pagetop-cron/CHANGELOG.md" + PATH_FLAGS=(--include-path "extensions/pagetop-cron/**/*") + ;; pagetop-htmx) CHANGELOG_FILE="extensions/pagetop-htmx/CHANGELOG.md" PATH_FLAGS=(--include-path "extensions/pagetop-htmx/**/*")