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 @@
+
+
+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