✨ (cron): Añade la extensión pagetop-cron
- Trabajos programados con expresiones cron (croner), `fixed_rate()` y `fixed_delay()`, declarados con la acción `DeclareCronJobs` y ajustables por su clave en `[cron.jobs."clave"]`. - Control de solapamiento, tiempo máximo, zona horaria por trabajo, ejecución al arrancar y bajo demanda con `run_now()`. - Modo `external` sin estado, para réplicas y escalado a cero: `POST /cron` con `Authorization: Bearer`, ventanas alineadas de `trigger_interval_secs` y respuesta al terminar los trabajos. - Estado con `jobs()`/`job()`, acción `AfterJobRun` y parada ordenada con `JobContext::is_stopping()`.
This commit is contained in:
parent
4c3f4dab1b
commit
86d9f0e213
22 changed files with 3678 additions and 1 deletions
77
Cargo.lock
generated
77
Cargo.lock
generated
|
|
@ -666,6 +666,17 @@ dependencies = [
|
||||||
"cfg-if",
|
"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]]
|
[[package]]
|
||||||
name = "crossbeam-channel"
|
name = "crossbeam-channel"
|
||||||
version = "0.5.15"
|
version = "0.5.15"
|
||||||
|
|
@ -748,6 +759,7 @@ dependencies = [
|
||||||
"ident_case",
|
"ident_case",
|
||||||
"proc-macro2",
|
"proc-macro2",
|
||||||
"quote",
|
"quote",
|
||||||
|
"strsim",
|
||||||
"syn",
|
"syn",
|
||||||
]
|
]
|
||||||
|
|
||||||
|
|
@ -782,6 +794,37 @@ dependencies = [
|
||||||
"powerfmt",
|
"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]]
|
[[package]]
|
||||||
name = "derive_more"
|
name = "derive_more"
|
||||||
version = "2.1.1"
|
version = "2.1.1"
|
||||||
|
|
@ -2156,6 +2199,17 @@ dependencies = [
|
||||||
"pagetop-statics",
|
"pagetop-statics",
|
||||||
]
|
]
|
||||||
|
|
||||||
|
[[package]]
|
||||||
|
name = "pagetop-cron"
|
||||||
|
version = "0.1.0"
|
||||||
|
dependencies = [
|
||||||
|
"croner",
|
||||||
|
"pagetop",
|
||||||
|
"serde",
|
||||||
|
"thiserror",
|
||||||
|
"tokio",
|
||||||
|
]
|
||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "pagetop-htmx"
|
name = "pagetop-htmx"
|
||||||
version = "0.1.0"
|
version = "0.1.0"
|
||||||
|
|
@ -2756,7 +2810,7 @@ dependencies = [
|
||||||
"sea-query-binder",
|
"sea-query-binder",
|
||||||
"serde",
|
"serde",
|
||||||
"sqlx",
|
"sqlx",
|
||||||
"strum",
|
"strum 0.26.3",
|
||||||
"thiserror",
|
"thiserror",
|
||||||
"tracing",
|
"tracing",
|
||||||
"url",
|
"url",
|
||||||
|
|
@ -3310,6 +3364,27 @@ version = "0.26.3"
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||||
checksum = "8fec0f0aef304996cf250b31b5a10dee7980c85da9d759361292b8bca5a18f06"
|
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]]
|
[[package]]
|
||||||
name = "subtle"
|
name = "subtle"
|
||||||
version = "2.6.1"
|
version = "2.6.1"
|
||||||
|
|
|
||||||
|
|
@ -11,6 +11,7 @@ members = [
|
||||||
"extensions/pagetop-bootsier",
|
"extensions/pagetop-bootsier",
|
||||||
"extensions/pagetop-htmx",
|
"extensions/pagetop-htmx",
|
||||||
"extensions/pagetop-admin",
|
"extensions/pagetop-admin",
|
||||||
|
"extensions/pagetop-cron",
|
||||||
"extensions/pagetop-mail",
|
"extensions/pagetop-mail",
|
||||||
"extensions/pagetop-seaorm",
|
"extensions/pagetop-seaorm",
|
||||||
"extensions/pagetop-user",
|
"extensions/pagetop-user",
|
||||||
|
|
@ -34,6 +35,7 @@ chrono = "0.4"
|
||||||
chrono-tz = "0.10"
|
chrono-tz = "0.10"
|
||||||
colored = "3.1"
|
colored = "3.1"
|
||||||
config = { version = "0.15", default-features = false, features = ["toml"] }
|
config = { version = "0.15", default-features = false, features = ["toml"] }
|
||||||
|
croner = { version = "4.0", default-features = false, features = ["chrono"] }
|
||||||
figlet-rs = "1.0"
|
figlet-rs = "1.0"
|
||||||
fluent-templates = "0.14"
|
fluent-templates = "0.14"
|
||||||
getter-methods = "2.0"
|
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-admin = { version = "0.1", path = "extensions/pagetop-admin" }
|
||||||
pagetop-aliner = { version = "0.1", path = "extensions/pagetop-aliner" }
|
pagetop-aliner = { version = "0.1", path = "extensions/pagetop-aliner" }
|
||||||
pagetop-bootsier = { version = "0.1", path = "extensions/pagetop-bootsier" }
|
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-htmx = { version = "0.1", path = "extensions/pagetop-htmx" }
|
||||||
pagetop-mail = { version = "0.1", path = "extensions/pagetop-mail" }
|
pagetop-mail = { version = "0.1", path = "extensions/pagetop-mail" }
|
||||||
pagetop-seaorm = { version = "0.0", path = "extensions/pagetop-seaorm" }
|
pagetop-seaorm = { version = "0.0", path = "extensions/pagetop-seaorm" }
|
||||||
|
|
|
||||||
|
|
@ -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.
|
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 >********************************************************************************
|
# **< pagetop-user >********************************************************************************
|
||||||
|
|
||||||
[user]
|
[user]
|
||||||
|
|
|
||||||
24
extensions/pagetop-cron/Cargo.toml
Normal file
24
extensions/pagetop-cron/Cargo.toml
Normal file
|
|
@ -0,0 +1,24 @@
|
||||||
|
[package]
|
||||||
|
name = "pagetop-cron"
|
||||||
|
version = "0.1.0"
|
||||||
|
|
||||||
|
description = """
|
||||||
|
Programación de tareas para aplicaciones PageTop: expresiones cron, intervalos y ejecución bajo
|
||||||
|
demanda.
|
||||||
|
"""
|
||||||
|
categories = ["date-and-time", "web-programming"]
|
||||||
|
keywords = ["pagetop", "cron", "scheduler", "jobs", "ssr"]
|
||||||
|
|
||||||
|
repository.workspace = true
|
||||||
|
homepage.workspace = true
|
||||||
|
edition.workspace = true
|
||||||
|
rust-version.workspace = true
|
||||||
|
license.workspace = true
|
||||||
|
authors.workspace = true
|
||||||
|
|
||||||
|
[dependencies]
|
||||||
|
pagetop.workspace = true
|
||||||
|
croner.workspace = true
|
||||||
|
serde.workspace = true
|
||||||
|
thiserror.workspace = true
|
||||||
|
tokio.workspace = true
|
||||||
201
extensions/pagetop-cron/LICENSE-APACHE
Normal file
201
extensions/pagetop-cron/LICENSE-APACHE
Normal file
|
|
@ -0,0 +1,201 @@
|
||||||
|
Apache License
|
||||||
|
Version 2.0, January 2004
|
||||||
|
http://www.apache.org/licenses/
|
||||||
|
|
||||||
|
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||||
|
|
||||||
|
1. Definitions.
|
||||||
|
|
||||||
|
"License" shall mean the terms and conditions for use, reproduction,
|
||||||
|
and distribution as defined by Sections 1 through 9 of this document.
|
||||||
|
|
||||||
|
"Licensor" shall mean the copyright owner or entity authorized by
|
||||||
|
the copyright owner that is granting the License.
|
||||||
|
|
||||||
|
"Legal Entity" shall mean the union of the acting entity and all
|
||||||
|
other entities that control, are controlled by, or are under common
|
||||||
|
control with that entity. For the purposes of this definition,
|
||||||
|
"control" means (i) the power, direct or indirect, to cause the
|
||||||
|
direction or management of such entity, whether by contract or
|
||||||
|
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||||
|
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||||
|
|
||||||
|
"You" (or "Your") shall mean an individual or Legal Entity
|
||||||
|
exercising permissions granted by this License.
|
||||||
|
|
||||||
|
"Source" form shall mean the preferred form for making modifications,
|
||||||
|
including but not limited to software source code, documentation
|
||||||
|
source, and configuration files.
|
||||||
|
|
||||||
|
"Object" form shall mean any form resulting from mechanical
|
||||||
|
transformation or translation of a Source form, including but
|
||||||
|
not limited to compiled object code, generated documentation,
|
||||||
|
and conversions to other media types.
|
||||||
|
|
||||||
|
"Work" shall mean the work of authorship, whether in Source or
|
||||||
|
Object form, made available under the License, as indicated by a
|
||||||
|
copyright notice that is included in or attached to the work
|
||||||
|
(an example is provided in the Appendix below).
|
||||||
|
|
||||||
|
"Derivative Works" shall mean any work, whether in Source or Object
|
||||||
|
form, that is based on (or derived from) the Work and for which the
|
||||||
|
editorial revisions, annotations, elaborations, or other modifications
|
||||||
|
represent, as a whole, an original work of authorship. For the purposes
|
||||||
|
of this License, Derivative Works shall not include works that remain
|
||||||
|
separable from, or merely link (or bind by name) to the interfaces of,
|
||||||
|
the Work and Derivative Works thereof.
|
||||||
|
|
||||||
|
"Contribution" shall mean any work of authorship, including
|
||||||
|
the original version of the Work and any modifications or additions
|
||||||
|
to that Work or Derivative Works thereof, that is intentionally
|
||||||
|
submitted to Licensor for inclusion in the Work by the copyright owner
|
||||||
|
or by an individual or Legal Entity authorized to submit on behalf of
|
||||||
|
the copyright owner. For the purposes of this definition, "submitted"
|
||||||
|
means any form of electronic, verbal, or written communication sent
|
||||||
|
to the Licensor or its representatives, including but not limited to
|
||||||
|
communication on electronic mailing lists, source code control systems,
|
||||||
|
and issue tracking systems that are managed by, or on behalf of, the
|
||||||
|
Licensor for the purpose of discussing and improving the Work, but
|
||||||
|
excluding communication that is conspicuously marked or otherwise
|
||||||
|
designated in writing by the copyright owner as "Not a Contribution."
|
||||||
|
|
||||||
|
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||||
|
on behalf of whom a Contribution has been received by Licensor and
|
||||||
|
subsequently incorporated within the Work.
|
||||||
|
|
||||||
|
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||||
|
this License, each Contributor hereby grants to You a perpetual,
|
||||||
|
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||||
|
copyright license to reproduce, prepare Derivative Works of,
|
||||||
|
publicly display, publicly perform, sublicense, and distribute the
|
||||||
|
Work and such Derivative Works in Source or Object form.
|
||||||
|
|
||||||
|
3. Grant of Patent License. Subject to the terms and conditions of
|
||||||
|
this License, each Contributor hereby grants to You a perpetual,
|
||||||
|
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||||
|
(except as stated in this section) patent license to make, have made,
|
||||||
|
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||||
|
where such license applies only to those patent claims licensable
|
||||||
|
by such Contributor that are necessarily infringed by their
|
||||||
|
Contribution(s) alone or by combination of their Contribution(s)
|
||||||
|
with the Work to which such Contribution(s) was submitted. If You
|
||||||
|
institute patent litigation against any entity (including a
|
||||||
|
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||||
|
or a Contribution incorporated within the Work constitutes direct
|
||||||
|
or contributory patent infringement, then any patent licenses
|
||||||
|
granted to You under this License for that Work shall terminate
|
||||||
|
as of the date such litigation is filed.
|
||||||
|
|
||||||
|
4. Redistribution. You may reproduce and distribute copies of the
|
||||||
|
Work or Derivative Works thereof in any medium, with or without
|
||||||
|
modifications, and in Source or Object form, provided that You
|
||||||
|
meet the following conditions:
|
||||||
|
|
||||||
|
(a) You must give any other recipients of the Work or
|
||||||
|
Derivative Works a copy of this License; and
|
||||||
|
|
||||||
|
(b) You must cause any modified files to carry prominent notices
|
||||||
|
stating that You changed the files; and
|
||||||
|
|
||||||
|
(c) You must retain, in the Source form of any Derivative Works
|
||||||
|
that You distribute, all copyright, patent, trademark, and
|
||||||
|
attribution notices from the Source form of the Work,
|
||||||
|
excluding those notices that do not pertain to any part of
|
||||||
|
the Derivative Works; and
|
||||||
|
|
||||||
|
(d) If the Work includes a "NOTICE" text file as part of its
|
||||||
|
distribution, then any Derivative Works that You distribute must
|
||||||
|
include a readable copy of the attribution notices contained
|
||||||
|
within such NOTICE file, excluding those notices that do not
|
||||||
|
pertain to any part of the Derivative Works, in at least one
|
||||||
|
of the following places: within a NOTICE text file distributed
|
||||||
|
as part of the Derivative Works; within the Source form or
|
||||||
|
documentation, if provided along with the Derivative Works; or,
|
||||||
|
within a display generated by the Derivative Works, if and
|
||||||
|
wherever such third-party notices normally appear. The contents
|
||||||
|
of the NOTICE file are for informational purposes only and
|
||||||
|
do not modify the License. You may add Your own attribution
|
||||||
|
notices within Derivative Works that You distribute, alongside
|
||||||
|
or as an addendum to the NOTICE text from the Work, provided
|
||||||
|
that such additional attribution notices cannot be construed
|
||||||
|
as modifying the License.
|
||||||
|
|
||||||
|
You may add Your own copyright statement to Your modifications and
|
||||||
|
may provide additional or different license terms and conditions
|
||||||
|
for use, reproduction, or distribution of Your modifications, or
|
||||||
|
for any such Derivative Works as a whole, provided Your use,
|
||||||
|
reproduction, and distribution of the Work otherwise complies with
|
||||||
|
the conditions stated in this License.
|
||||||
|
|
||||||
|
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||||
|
any Contribution intentionally submitted for inclusion in the Work
|
||||||
|
by You to the Licensor shall be under the terms and conditions of
|
||||||
|
this License, without any additional terms or conditions.
|
||||||
|
Notwithstanding the above, nothing herein shall supersede or modify
|
||||||
|
the terms of any separate license agreement you may have executed
|
||||||
|
with Licensor regarding such Contributions.
|
||||||
|
|
||||||
|
6. Trademarks. This License does not grant permission to use the trade
|
||||||
|
names, trademarks, service marks, or product names of the Licensor,
|
||||||
|
except as required for reasonable and customary use in describing the
|
||||||
|
origin of the Work and reproducing the content of the NOTICE file.
|
||||||
|
|
||||||
|
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||||
|
agreed to in writing, Licensor provides the Work (and each
|
||||||
|
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||||
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||||
|
implied, including, without limitation, any warranties or conditions
|
||||||
|
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||||
|
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||||
|
appropriateness of using or redistributing the Work and assume any
|
||||||
|
risks associated with Your exercise of permissions under this License.
|
||||||
|
|
||||||
|
8. Limitation of Liability. In no event and under no legal theory,
|
||||||
|
whether in tort (including negligence), contract, or otherwise,
|
||||||
|
unless required by applicable law (such as deliberate and grossly
|
||||||
|
negligent acts) or agreed to in writing, shall any Contributor be
|
||||||
|
liable to You for damages, including any direct, indirect, special,
|
||||||
|
incidental, or consequential damages of any character arising as a
|
||||||
|
result of this License or out of the use or inability to use the
|
||||||
|
Work (including but not limited to damages for loss of goodwill,
|
||||||
|
work stoppage, computer failure or malfunction, or any and all
|
||||||
|
other commercial damages or losses), even if such Contributor
|
||||||
|
has been advised of the possibility of such damages.
|
||||||
|
|
||||||
|
9. Accepting Warranty or Additional Liability. While redistributing
|
||||||
|
the Work or Derivative Works thereof, You may choose to offer,
|
||||||
|
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||||
|
or other liability obligations and/or rights consistent with this
|
||||||
|
License. However, in accepting such obligations, You may act only
|
||||||
|
on Your own behalf and on Your sole responsibility, not on behalf
|
||||||
|
of any other Contributor, and only if You agree to indemnify,
|
||||||
|
defend, and hold each Contributor harmless for any liability
|
||||||
|
incurred by, or claims asserted against, such Contributor by reason
|
||||||
|
of your accepting any such warranty or additional liability.
|
||||||
|
|
||||||
|
END OF TERMS AND CONDITIONS
|
||||||
|
|
||||||
|
APPENDIX: How to apply the Apache License to your work.
|
||||||
|
|
||||||
|
To apply the Apache License to your work, attach the following
|
||||||
|
boilerplate notice, with the fields enclosed by brackets "[]"
|
||||||
|
replaced with your own identifying information. (Don't include
|
||||||
|
the brackets!) The text should be enclosed in the appropriate
|
||||||
|
comment syntax for the file format. We also recommend that a
|
||||||
|
file or class name and description of purpose be included on the
|
||||||
|
same "printed page" as the copyright notice for easier
|
||||||
|
identification within third-party archives.
|
||||||
|
|
||||||
|
Copyright 2026 Manuel Cillero
|
||||||
|
|
||||||
|
Licensed under the Apache License, Version 2.0 (the "License");
|
||||||
|
you may not use this file except in compliance with the License.
|
||||||
|
You may obtain a copy of the License at
|
||||||
|
|
||||||
|
http://www.apache.org/licenses/LICENSE-2.0
|
||||||
|
|
||||||
|
Unless required by applicable law or agreed to in writing, software
|
||||||
|
distributed under the License is distributed on an "AS IS" BASIS,
|
||||||
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||||
|
See the License for the specific language governing permissions and
|
||||||
|
limitations under the License.
|
||||||
21
extensions/pagetop-cron/LICENSE-MIT
Normal file
21
extensions/pagetop-cron/LICENSE-MIT
Normal file
|
|
@ -0,0 +1,21 @@
|
||||||
|
MIT License
|
||||||
|
|
||||||
|
Copyright (c) 2026 Manuel Cillero
|
||||||
|
|
||||||
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||||
|
of this software and associated documentation files (the "Software"), to deal
|
||||||
|
in the Software without restriction, including without limitation the rights
|
||||||
|
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||||
|
copies of the Software, and to permit persons to whom the Software is
|
||||||
|
furnished to do so, subject to the following conditions:
|
||||||
|
|
||||||
|
The above copyright notice and this permission notice shall be included in all
|
||||||
|
copies or substantial portions of the Software.
|
||||||
|
|
||||||
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||||
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||||
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||||
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||||
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||||
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||||
|
SOFTWARE.
|
||||||
333
extensions/pagetop-cron/README.md
Normal file
333
extensions/pagetop-cron/README.md
Normal file
|
|
@ -0,0 +1,333 @@
|
||||||
|
<div align="center">
|
||||||
|
|
||||||
|
<h1>PageTop Cron</h1>
|
||||||
|
|
||||||
|
<p>Programación de tareas para aplicaciones <strong>PageTop</strong>.</p>
|
||||||
|
|
||||||
|
[](https://docs.rs/pagetop-cron)
|
||||||
|
[](https://crates.io/crates/pagetop-cron)
|
||||||
|
[](https://crates.io/crates/pagetop-cron)
|
||||||
|
[](https://git.cillero.es/manuelcillero/pagetop/src/branch/main/extensions/pagetop-cron#licencia)
|
||||||
|
|
||||||
|
</div>
|
||||||
|
|
||||||
|
Ejecuta trabajos periódicos en segundo plano mientras la aplicación está en marcha: cada noche a
|
||||||
|
las 4:30, cada diez minutos, el último día de cada mes, o unos segundos después de terminar la
|
||||||
|
ejecución anterior. Cada extensión declara sus trabajos en el código con una acción, y quien
|
||||||
|
administra la aplicación decide en los archivos de configuración cómo se ejecutan, y puede cambiar
|
||||||
|
cuándo se ejecuta cada trabajo o desactivarlo sin recompilar.
|
||||||
|
|
||||||
|
## Sobre PageTop
|
||||||
|
|
||||||
|
[PageTop](https://docs.rs/pagetop) es un entorno de desarrollo que reivindica la esencia de la web
|
||||||
|
clásica para crear soluciones web SSR (*renderizadas en el servidor*) modulares, extensibles y
|
||||||
|
configurables, basadas en HTML, CSS y JavaScript.
|
||||||
|
|
||||||
|
## Guía rápida
|
||||||
|
|
||||||
|
**Añade la dependencia** a tu `Cargo.toml`:
|
||||||
|
|
||||||
|
```toml
|
||||||
|
[dependencies]
|
||||||
|
pagetop-cron = "..."
|
||||||
|
```
|
||||||
|
|
||||||
|
**Escribe el trabajo** como una función asíncrona que recibe un `JobContext` y devuelve un
|
||||||
|
`JobResult`. Con `?` puede propagar cualquier error, que se registra en las trazas:
|
||||||
|
|
||||||
|
```rust,no_run
|
||||||
|
use pagetop::prelude::*;
|
||||||
|
use pagetop_cron::prelude::*;
|
||||||
|
|
||||||
|
async fn cleanup(_cx: JobContext) -> JobResult {
|
||||||
|
// Borra los carritos abandonados hace más de 30 días...
|
||||||
|
Ok(())
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Declara el trabajo** con la acción `DeclareCronJobs` en la extensión que lo aporta, que depende
|
||||||
|
de `pagetop-cron`:
|
||||||
|
|
||||||
|
```rust,no_run
|
||||||
|
use pagetop::prelude::*;
|
||||||
|
use pagetop_cron::prelude::*;
|
||||||
|
|
||||||
|
fn declare_jobs(jobs: &mut CronJobs) {
|
||||||
|
jobs.add(
|
||||||
|
Job::new("shop.cleanup", Schedule::cron("30 4 * * *"), cleanup)
|
||||||
|
.with_title(Lc::n("Remove abandoned carts"))
|
||||||
|
.with_timeout(Duration::minutes(15)),
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
struct Shop;
|
||||||
|
|
||||||
|
#[async_trait]
|
||||||
|
impl Extension for Shop {
|
||||||
|
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||||
|
vec![&pagetop_cron::Cron]
|
||||||
|
}
|
||||||
|
|
||||||
|
fn actions(&self) -> Vec<ActionBox> {
|
||||||
|
actions![DeclareCronJobs::new(declare_jobs)]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Y ya está: al ejecutar la aplicación con `Application::run()`, el trabajo se ejecuta cada día a
|
||||||
|
las 4:30 en la zona horaria de la aplicación (`[app].timezone`). La clave (`"shop.cleanup"`)
|
||||||
|
identifica el trabajo en las trazas, en la configuración y al ejecutarlo bajo demanda; conviene
|
||||||
|
empezarla por el nombre de la extensión.
|
||||||
|
|
||||||
|
## Cuándo se ejecuta un trabajo
|
||||||
|
|
||||||
|
`Schedule` ofrece tres formas de programarlo:
|
||||||
|
|
||||||
|
```rust,no_run
|
||||||
|
use pagetop::prelude::*;
|
||||||
|
use pagetop_cron::prelude::*;
|
||||||
|
|
||||||
|
// Según una expresión cron: cada día a las 4:30.
|
||||||
|
Schedule::cron("30 4 * * *");
|
||||||
|
// Cada cinco minutos desde que *empieza* la ejecución anterior (ritmo fijo).
|
||||||
|
Schedule::fixed_rate(Duration::minutes(5));
|
||||||
|
// Treinta segundos después de que *termina* la ejecución anterior (nunca se solapan).
|
||||||
|
Schedule::fixed_delay(Duration::seconds(30));
|
||||||
|
```
|
||||||
|
|
||||||
|
Las expresiones cron siguen la sintaxis clásica de cinco campos, con un sexto campo opcional para
|
||||||
|
los segundos y un séptimo, también opcional, para el año, y admiten además `L`, `W` y `#` (último
|
||||||
|
día del mes, día laborable más cercano, enésimo día de la semana) y apodos como `@daily`. Se
|
||||||
|
interpretan en la zona horaria de la aplicación y respetan los cambios de hora. Todos los
|
||||||
|
detalles, con ejemplos, en `Schedule`.
|
||||||
|
|
||||||
|
Para procesar colas o tareas pendientes, `fixed_delay()` suele ser la mejor opción: cada ejecución
|
||||||
|
procesa lo que dejó la anterior y nunca coinciden dos.
|
||||||
|
|
||||||
|
## Opciones de cada trabajo
|
||||||
|
|
||||||
|
`Job` ofrece además:
|
||||||
|
|
||||||
|
| Método | Uso |
|
||||||
|
|-----------------------|------------------------------------------------------------------|
|
||||||
|
| `with_title()` | Título descriptivo, traducible, para listados y paneles. |
|
||||||
|
| `with_timeout()` | Tiempo máximo de cada ejecución; si lo supera, se cancela. |
|
||||||
|
| `with_overlap()` | Qué hacer si la ejecución anterior sigue en curso (`Overlap`). |
|
||||||
|
| `with_timezone()` | Zona horaria propia para su expresión cron. |
|
||||||
|
| `with_run_on_start()` | Se ejecuta también al arrancar la aplicación. |
|
||||||
|
|
||||||
|
Si llega la hora de un trabajo y su ejecución anterior aún no ha terminado, por defecto se omite la
|
||||||
|
nueva (`Overlap::Skip`); con `Overlap::Allow` se ejecuta a la vez.
|
||||||
|
|
||||||
|
La función del trabajo puede ser también un cierre. Accede a los ajustes y servicios de la
|
||||||
|
aplicación igual que un *handler*, p. ej. con los `SETTINGS` de cada extensión o con `dbconn()` de
|
||||||
|
`pagetop-seaorm`:
|
||||||
|
|
||||||
|
```rust,no_run
|
||||||
|
use pagetop::prelude::*;
|
||||||
|
use pagetop_cron::prelude::*;
|
||||||
|
|
||||||
|
let job = Job::new("app.heartbeat", Schedule::fixed_rate(Duration::minutes(1)), |cx| async move {
|
||||||
|
trace::info!("Heartbeat from \"{}\" ({:?})", cx.key(), cx.trigger());
|
||||||
|
Ok(())
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
Un `panic!` dentro de un trabajo no afecta a la aplicación ni a sus siguientes ejecuciones: se
|
||||||
|
registra como un fallo más.
|
||||||
|
|
||||||
|
## Modos de ejecución
|
||||||
|
|
||||||
|
Quien administra la aplicación elige cómo se ejecutan los trabajos con `mode`, en la sección
|
||||||
|
`[cron]` (todas las opciones en `config`):
|
||||||
|
|
||||||
|
| `mode` | Los trabajos se ejecutan... |
|
||||||
|
|--------------|-------------------------------------------------------------------------|
|
||||||
|
| `"internal"` | Por defecto. Con el planificador de la propia aplicación. |
|
||||||
|
| `"external"` | Cuando un programa externo llama a `POST /cron` con la clave secreta. |
|
||||||
|
| `"off"` | Nunca de forma automática; sólo bajo demanda con `run_now()`. |
|
||||||
|
|
||||||
|
### Una sola instancia: `"internal"`
|
||||||
|
|
||||||
|
Con `"internal"`, cada proceso de la aplicación lleva su propio reloj y lanza los trabajos cuando
|
||||||
|
les toca. Con un solo proceso siempre en marcha (un servidor, un servicio de *systemd*, un
|
||||||
|
contenedor) es justo lo que se necesita, y no hay que configurar nada.
|
||||||
|
|
||||||
|
### Varias instancias
|
||||||
|
|
||||||
|
Si la misma aplicación se ejecuta en varios procesos a la vez, cada uno lanza todos los trabajos
|
||||||
|
con `"internal"`:
|
||||||
|
|
||||||
|
```text
|
||||||
|
+--> instancia A (internal) --> limpieza a las 4:30
|
||||||
|
balanceador ---+--> instancia B (internal) --> limpieza a las 4:30
|
||||||
|
+--> instancia C (internal) --> limpieza a las 4:30
|
||||||
|
```
|
||||||
|
|
||||||
|
La limpieza se hace tres veces, y un boletín se enviaría tres veces. Las instancias no se ponen de
|
||||||
|
acuerdo entre sí, así que hay dos formas de evitarlo:
|
||||||
|
|
||||||
|
- **`"internal"` en una instancia y `"off"` en las demás.** Es lo más sencillo si las instancias
|
||||||
|
se configuran a mano, pero esa instancia queda distinta del resto: si se detiene, nadie ejecuta
|
||||||
|
los trabajos.
|
||||||
|
- **`"external"` en todas.** Ninguna tiene reloj propio: un único reloj fuera de la aplicación
|
||||||
|
llama periódicamente a `POST /cron`, y el balanceador entrega cada llamada a una sola instancia,
|
||||||
|
que ejecuta lo programado desde la llamada anterior:
|
||||||
|
|
||||||
|
```text
|
||||||
|
crontab (en una sola máquina) --POST /cron--> balanceador --> instancia B ejecuta lo pendiente
|
||||||
|
```
|
||||||
|
|
||||||
|
### Cuándo usar `"external"`
|
||||||
|
|
||||||
|
- **Réplicas idénticas o autoescalado** (Kubernetes, Docker Swarm, varias máquinas tras un
|
||||||
|
balanceador). Todas arrancan con la misma imagen y la misma configuración, así que no se puede
|
||||||
|
dejar una distinta. Con `"external"` todas son iguales y cualquiera puede atender la llamada.
|
||||||
|
- **Plataformas que detienen la aplicación cuando no hay tráfico** (escalado a cero). Si nadie
|
||||||
|
visita el sitio de madrugada, no queda ningún proceso vivo y el reloj interno de las 4:30 no
|
||||||
|
existe; algunas plataformas, además, sólo dan CPU mientras se atiende una petición. La llamada
|
||||||
|
externa despierta la aplicación y le da tiempo para ejecutar lo pendiente. Estas plataformas
|
||||||
|
suelen ofrecer su propio planificador para hacerla.
|
||||||
|
- **Planificar desde las herramientas de operaciones** que ya se usan, como un *CronJob* de
|
||||||
|
Kubernetes o un temporizador de *systemd*. La llamada responde `200 OK` aunque falle algún
|
||||||
|
trabajo, para que un reintento no repita los demás; el resultado de cada uno viene en el cuerpo
|
||||||
|
de la respuesta y, para avisar de los fallos, está la acción `AfterJobRun`.
|
||||||
|
|
||||||
|
Con una sola instancia siempre en marcha, `"external"` no aporta nada: añade piezas (un `crontab`,
|
||||||
|
una clave secreta, una ruta expuesta) y pierde precisión. Mejor `"internal"`.
|
||||||
|
|
||||||
|
### Configurar `"external"`
|
||||||
|
|
||||||
|
```toml
|
||||||
|
[cron]
|
||||||
|
mode = "external"
|
||||||
|
trigger_token = "..." # Clave secreta propia, mejor en config/local.toml.
|
||||||
|
trigger_interval_secs = 60 # Una llamada por minuto (el valor por defecto).
|
||||||
|
```
|
||||||
|
|
||||||
|
La clave debe tener al menos 16 caracteres (letras, dígitos, `-` o `_`), o la aplicación no
|
||||||
|
arranca; `openssl rand -hex 32` genera una adecuada. Viaja en la cabecera
|
||||||
|
`Authorization: Bearer <clave>`, no en la ruta, porque los *proxies* y los balanceadores suelen
|
||||||
|
registrar las rutas de las peticiones. Para que tampoco aparezca en la lista de procesos del
|
||||||
|
sistema, `curl` puede leer la cabecera de un archivo que sólo pueda leer el usuario del `crontab`:
|
||||||
|
|
||||||
|
```text
|
||||||
|
# crontab del sistema: comprueba los trabajos cada minuto. El archivo contiene la línea
|
||||||
|
# "Authorization: Bearer <clave>".
|
||||||
|
* * * * * curl -fsS -X POST -H @/etc/miapp/cron-header https://example.com/cron > /dev/null
|
||||||
|
```
|
||||||
|
|
||||||
|
La llamada responde cuando terminan los trabajos que ejecuta, con `200 OK` y una línea por trabajo
|
||||||
|
con su resultado (`succeeded`, `failed`, `timed out` o `panicked`); sin la clave correcta responde
|
||||||
|
`404 Not Found`, igual que una ruta que no existe. Esperar mantiene viva la aplicación en las
|
||||||
|
plataformas que sólo dan CPU mientras se atiende una petición, así que el tiempo de espera del
|
||||||
|
programa externo debe superar lo que tarde el trabajo más largo; conviene limitarlo con
|
||||||
|
`with_timeout()`. Si el programa externo corta antes, los trabajos siguen igualmente, pero en esas
|
||||||
|
plataformas pueden quedarse sin CPU.
|
||||||
|
|
||||||
|
Cada llamada ejecuta lo programado en el último minuto, sea cual sea la instancia que la recibe y
|
||||||
|
aunque acabe de arrancar: una llamada a las 4:30:20 ejecuta lo programado desde las 4:29:00
|
||||||
|
(excluido) hasta las 4:30:00. Así ninguna instancia necesita recordar qué hicieron las demás, pero
|
||||||
|
el programa externo debe llamar una vez, y sólo una, cada minuto: si falta una llamada se pierden
|
||||||
|
sus ejecuciones, y si sobra, dos instancias pueden repetirlas. Para llamar con otra frecuencia
|
||||||
|
(p. ej. cada cuarto de hora, en una plataforma que despierta la aplicación en cada llamada),
|
||||||
|
indícala en `trigger_interval_secs` (`900`) y programa los trabajos en múltiplos de ella. La
|
||||||
|
precisión es la del intervalo: con una llamada por minuto, un trabajo programado cada diez
|
||||||
|
segundos se ejecuta una vez por minuto.
|
||||||
|
|
||||||
|
Una llamada de más suele ser un reintento. La respuesta es `200 OK` aunque falle algún trabajo, así
|
||||||
|
que el programa externo sólo reintenta tras un error de red o si se agota su tiempo de espera; pero
|
||||||
|
si el reintento llega a otra instancia, ésta ejecuta de nuevo lo mismo, porque las instancias no
|
||||||
|
comparten estado. Desactiva los reintentos del programa externo (p. ej. `backoffLimit: 0` en un
|
||||||
|
*CronJob* de Kubernetes) y, si un trabajo no debe repetirse nunca, que lo compruebe él mismo (p. ej.
|
||||||
|
en la base de datos) antes de hacer nada.
|
||||||
|
|
||||||
|
## Ajustar un trabajo desde la configuración
|
||||||
|
|
||||||
|
Cada trabajo puede cambiarse por su clave, sin tocar el código, en la subsección
|
||||||
|
`[cron.jobs."clave"]` (ver `JobSettings`):
|
||||||
|
|
||||||
|
```toml
|
||||||
|
[cron.jobs."shop.cleanup"]
|
||||||
|
schedule = "0 5 * * SUN" # Sólo los domingos a las 5:00.
|
||||||
|
timeout_secs = 1800 # Tiempo máximo de 30 minutos (0 = sin límite).
|
||||||
|
|
||||||
|
[cron.jobs."shop.reminders"]
|
||||||
|
enabled = false # Desactivado: sólo se ejecuta bajo demanda.
|
||||||
|
```
|
||||||
|
|
||||||
|
La programación admite la misma sintaxis que `Schedule::parse()`, incluidos `"@every 10m"` y
|
||||||
|
`"@delay 30s"`. Una programación no válida detiene el arranque indicando el trabajo, y una clave
|
||||||
|
que no corresponde a ningún trabajo se ignora con un aviso en las trazas.
|
||||||
|
|
||||||
|
## Ejecutar y consultar los trabajos
|
||||||
|
|
||||||
|
`run_now()` ejecuta un trabajo en el acto y devuelve su `JobRun`: útil para un botón
|
||||||
|
«Ejecutar ahora» de un panel de administración, para una orden de mantenimiento o para las
|
||||||
|
pruebas. `jobs()` y `job()` devuelven su `JobStatus`: programación efectiva, próxima
|
||||||
|
ejecución, resultado de la última y número de ejecuciones, fallos y omisiones.
|
||||||
|
|
||||||
|
Para reaccionar a cada ejecución terminada (registrarla, enviar métricas, avisar cuando falla un
|
||||||
|
trabajo), registra la acción `AfterJobRun`.
|
||||||
|
|
||||||
|
## Detener la aplicación
|
||||||
|
|
||||||
|
Al detener la aplicación (Ctrl+C o `SIGTERM`), el planificador deja de lanzar ejecuciones y espera
|
||||||
|
a que terminen las que están en curso, hasta `cron.shutdown_timeout_secs` (30 s por defecto). Un
|
||||||
|
trabajo largo puede comprobar `JobContext::is_stopping()` para dejar su trabajo en un punto
|
||||||
|
seguro antes de que se agote ese tiempo.
|
||||||
|
|
||||||
|
## Pruebas
|
||||||
|
|
||||||
|
El planificador sólo se pone en marcha con `Application::run()` (ver `Extension::start()`), nunca
|
||||||
|
en las pruebas que preparan la aplicación y obtienen su servidor con `Application::test()`. En
|
||||||
|
ellas, los trabajos se ejecutan cuando la prueba quiere con `run_now()`:
|
||||||
|
|
||||||
|
```rust,no_run
|
||||||
|
use pagetop::prelude::*;
|
||||||
|
|
||||||
|
#[pagetop::test]
|
||||||
|
async fn cleanup_job_succeeds() {
|
||||||
|
Application::prepare(&Shop).await;
|
||||||
|
let run = pagetop_cron::run_now("shop.cleanup").await.unwrap();
|
||||||
|
assert!(run.outcome().is_success(), "{}", run.outcome());
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Qué no hace
|
||||||
|
|
||||||
|
Para mantenerse sencilla, la extensión no guarda nada fuera de la memoria:
|
||||||
|
|
||||||
|
- **No recupera las ejecuciones perdidas.** Si la aplicación estaba detenida cuando tocaba una
|
||||||
|
ejecución, no se hace al volver a arrancar; la siguiente llega según su programación. Para
|
||||||
|
trabajos que no deben perder ninguna, combina la programación con `with_run_on_start()`, o
|
||||||
|
guarda en la base de datos qué queda pendiente y procésalo en cada ejecución.
|
||||||
|
- **No es una cola de trabajos.** Para tareas puntuales que deben sobrevivir a un reinicio (un
|
||||||
|
correo que no se pudo enviar, una importación...), cada extensión guarda las pendientes en su
|
||||||
|
propia tabla y declara un trabajo periódico que las procesa.
|
||||||
|
- **No coordina varias instancias** por sí misma; ver «Varias instancias».
|
||||||
|
|
||||||
|
## Créditos
|
||||||
|
|
||||||
|
Las expresiones cron se interpretan con [croner](https://github.com/hexagon/croner-rust), la misma
|
||||||
|
biblioteca que usa *tokio-cron-scheduler*, distribuida bajo licencia
|
||||||
|
[MIT](https://github.com/hexagon/croner-rust/blob/master/LICENSE).
|
||||||
|
|
||||||
|
## Advertencia
|
||||||
|
|
||||||
|
**PageTop** es un proyecto personal para aprender [Rust](https://www.rust-lang.org/es) y conocer su
|
||||||
|
ecosistema. Su API está sujeta a cambios frecuentes. No se recomienda su uso en producción, al menos
|
||||||
|
hasta que se libere la versión **1.0.0**.
|
||||||
|
|
||||||
|
## Licencia
|
||||||
|
|
||||||
|
El código está disponible bajo una doble licencia:
|
||||||
|
|
||||||
|
* **Licencia MIT**
|
||||||
|
([LICENSE-MIT](LICENSE-MIT) o también https://opensource.org/licenses/MIT)
|
||||||
|
|
||||||
|
* **Licencia Apache, Versión 2.0**
|
||||||
|
([LICENSE-APACHE](LICENSE-APACHE) o también https://www.apache.org/licenses/LICENSE-2.0)
|
||||||
|
|
||||||
|
Puedes elegir la licencia que prefieras. Este enfoque de doble licencia es el estándar de facto en
|
||||||
|
el ecosistema Rust.
|
||||||
19
extensions/pagetop-cron/config/common.toml
Normal file
19
extensions/pagetop-cron/config/common.toml
Normal file
|
|
@ -0,0 +1,19 @@
|
||||||
|
# Configuración para las pruebas de este crate: zona horaria de Madrid, modo externo, para probar
|
||||||
|
# la ruta de las llamadas externas, y ajustes propios de algunos trabajos de prueba.
|
||||||
|
|
||||||
|
[app]
|
||||||
|
timezone = "Europe/Madrid"
|
||||||
|
|
||||||
|
[cron]
|
||||||
|
mode = "external"
|
||||||
|
trigger_token = "test-token-0123456789"
|
||||||
|
|
||||||
|
[cron.jobs."test.disabled"]
|
||||||
|
enabled = false
|
||||||
|
|
||||||
|
[cron.jobs."test.overridden"]
|
||||||
|
schedule = "@delay 90s"
|
||||||
|
timeout_secs = 0
|
||||||
|
|
||||||
|
[cron.jobs."test.not_declared"]
|
||||||
|
enabled = false
|
||||||
139
extensions/pagetop-cron/src/config.rs
Normal file
139
extensions/pagetop-cron/src/config.rs
Normal file
|
|
@ -0,0 +1,139 @@
|
||||||
|
//! Ajustes de configuración de `pagetop-cron`.
|
||||||
|
//!
|
||||||
|
//! Ejemplo:
|
||||||
|
//!
|
||||||
|
//! ```toml
|
||||||
|
//! [cron]
|
||||||
|
//! mode = "internal"
|
||||||
|
//!
|
||||||
|
//! # Ajustes propios de un trabajo, por su clave.
|
||||||
|
//! [cron.jobs."shop.cleanup"]
|
||||||
|
//! schedule = "30 4 * * *"
|
||||||
|
//! timeout_secs = 600
|
||||||
|
//!
|
||||||
|
//! [cron.jobs."shop.reminders"]
|
||||||
|
//! enabled = false
|
||||||
|
//! ```
|
||||||
|
//!
|
||||||
|
//! Uso:
|
||||||
|
//!
|
||||||
|
//! ```rust,no_run
|
||||||
|
//! use pagetop_cron::config::{self, CronMode};
|
||||||
|
//!
|
||||||
|
//! assert_eq!(config::SETTINGS.mode, CronMode::Internal);
|
||||||
|
//! ```
|
||||||
|
//!
|
||||||
|
//! Todas las opciones, con su valor por defecto, se documentan en [`CronSettings`] y
|
||||||
|
//! [`JobSettings`].
|
||||||
|
//!
|
||||||
|
//! Consulta [`pagetop::config`] para ver cómo PageTop lee los archivos de configuración y aplica
|
||||||
|
//! los valores a los ajustes.
|
||||||
|
|
||||||
|
use pagetop::prelude::*;
|
||||||
|
|
||||||
|
use serde::Deserialize;
|
||||||
|
|
||||||
|
use std::collections::HashMap;
|
||||||
|
|
||||||
|
/// Ajustes de la sección `[cron]`, cargados al arrancar la aplicación.
|
||||||
|
pub static SETTINGS: LazySettings<CronSettings> = LazySettings::new();
|
||||||
|
|
||||||
|
/// Sección **`[cron]`** de la configuración.
|
||||||
|
#[settings(section = "cron")]
|
||||||
|
pub struct CronSettings {
|
||||||
|
/// Cómo se ejecutan los trabajos programados. Por defecto, con el planificador de la propia
|
||||||
|
/// aplicación ([`CronMode::Internal`]).
|
||||||
|
pub mode: CronMode,
|
||||||
|
/// Clave secreta que autoriza las llamadas a `POST /cron` con [`CronMode::External`], enviada
|
||||||
|
/// en la cabecera `Authorization: Bearer <clave>`. Obligatoria en ese modo, con 16 caracteres
|
||||||
|
/// o más (letras, dígitos, `-` o `_`), o la aplicación no arranca. Conviene guardarla en
|
||||||
|
/// `config/local.toml`, que no se versiona.
|
||||||
|
pub trigger_token: Option<String>,
|
||||||
|
/// Segundos entre dos llamadas a `POST /cron` con [`CronMode::External`]. Cada llamada ejecuta
|
||||||
|
/// los trabajos programados en el último intervalo de esta duración, contado en múltiplos
|
||||||
|
/// exactos desde el 1 de enero de 1970 (UTC), así que el programa externo debe llamar una vez,
|
||||||
|
/// y sólo una, en cada intervalo.
|
||||||
|
#[default = 60]
|
||||||
|
pub trigger_interval_secs: u64,
|
||||||
|
/// Segundos que se espera, al detener la aplicación, a que terminen los trabajos en curso.
|
||||||
|
/// Pasado ese tiempo, la aplicación termina igualmente.
|
||||||
|
#[default = 30]
|
||||||
|
pub shutdown_timeout_secs: u64,
|
||||||
|
|
||||||
|
/// Ajustes de trabajos concretos, cada uno en la subsección `[cron.jobs."clave"]`. Las claves
|
||||||
|
/// que no corresponden a ningún trabajo declarado se ignoran con un aviso en las trazas.
|
||||||
|
pub jobs: HashMap<String, JobSettings>,
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Forma de ejecutar los trabajos programados. Usado en [`CronSettings::mode`].
|
||||||
|
#[derive(AutoDefault, Clone, Copy, Debug, Deserialize, Eq, PartialEq)]
|
||||||
|
#[serde(rename_all = "lowercase")]
|
||||||
|
pub enum CronMode {
|
||||||
|
/// La propia aplicación ejecuta cada trabajo según su programación mientras está en marcha. Es
|
||||||
|
/// el valor por defecto. Con varias instancias de la aplicación, **cada una** ejecuta los
|
||||||
|
/// trabajos: deja este modo en una sola y usa [`CronMode::Off`] en las demás.
|
||||||
|
#[default]
|
||||||
|
Internal,
|
||||||
|
/// Los trabajos sólo se ejecutan cuando un programa externo (`crontab`, un temporizador de
|
||||||
|
/// *systemd*, un servicio de la nube...) llama a `POST /cron` con la clave
|
||||||
|
/// [`trigger_token`](CronSettings::trigger_token), una vez cada
|
||||||
|
/// [`trigger_interval_secs`](CronSettings::trigger_interval_secs): cada llamada ejecuta los
|
||||||
|
/// trabajos programados desde la anterior. Útil para varias instancias tras un balanceador,
|
||||||
|
/// porque cada llamada sólo llega a una de ellas, y para las plataformas que detienen la
|
||||||
|
/// aplicación cuando no hay tráfico, porque no depende de lo que recuerde cada proceso.
|
||||||
|
External,
|
||||||
|
/// Ningún trabajo se ejecuta de forma automática; sólo bajo demanda con
|
||||||
|
/// [`run_now()`](crate::run_now). Útil en las instancias que no deben ejecutar trabajos y
|
||||||
|
/// para detenerlos temporalmente.
|
||||||
|
Off,
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Subsección **`[cron.jobs."clave"]`** de la configuración, con los ajustes de un trabajo.
|
||||||
|
///
|
||||||
|
/// Permite a quien administra la aplicación cambiar cuándo se ejecuta un trabajo, o desactivarlo,
|
||||||
|
/// sin modificar el código. Los ajustes que no se indican mantienen lo declarado en el código.
|
||||||
|
#[settings]
|
||||||
|
pub struct JobSettings {
|
||||||
|
/// `false` desactiva el trabajo: deja de ejecutarse de forma automática, aunque se puede
|
||||||
|
/// ejecutar bajo demanda con [`run_now()`](crate::run_now).
|
||||||
|
#[default = true]
|
||||||
|
pub enabled: bool,
|
||||||
|
/// Sustituye la programación declarada en el código, con la sintaxis de
|
||||||
|
/// [`Schedule::parse()`](crate::Schedule::parse) (p. ej. `"*/10 * * * *"` o `"@every 5m"`).
|
||||||
|
/// Una programación no válida detiene el arranque.
|
||||||
|
pub schedule: Option<String>,
|
||||||
|
/// Sustituye el tiempo máximo de cada ejecución, en segundos. `0` quita el límite.
|
||||||
|
pub timeout_secs: Option<u64>,
|
||||||
|
}
|
||||||
|
|
||||||
|
#[cfg(test)]
|
||||||
|
mod tests {
|
||||||
|
use super::{CronSettings, config};
|
||||||
|
|
||||||
|
// `reference.toml` documents every option; with unknown keys rejected, loading it proves that
|
||||||
|
// it only documents keys that exist, with values of the right type.
|
||||||
|
const REFERENCE: &str = include_str!("../../../config/reference.toml");
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn reference_toml_documents_only_existing_keys() {
|
||||||
|
config::load_from_str::<CronSettings>(REFERENCE).unwrap();
|
||||||
|
}
|
||||||
|
|
||||||
|
// Job keys usually contain dots, which TOML only accepts quoted. They must reach the map as a
|
||||||
|
// single key, not as nested tables.
|
||||||
|
#[test]
|
||||||
|
fn quoted_job_keys_with_dots_are_kept_whole() {
|
||||||
|
let settings = config::load_from_str::<CronSettings>(
|
||||||
|
r#"
|
||||||
|
[cron.jobs."shop.cleanup"]
|
||||||
|
enabled = false
|
||||||
|
schedule = "@hourly"
|
||||||
|
"#,
|
||||||
|
)
|
||||||
|
.unwrap();
|
||||||
|
let job = &settings.jobs["shop.cleanup"];
|
||||||
|
assert!(!job.enabled);
|
||||||
|
assert_eq!(job.schedule.as_deref(), Some("@hourly"));
|
||||||
|
assert_eq!(job.timeout_secs, None);
|
||||||
|
}
|
||||||
|
}
|
||||||
87
extensions/pagetop-cron/src/declare.rs
Normal file
87
extensions/pagetop-cron/src/declare.rs
Normal file
|
|
@ -0,0 +1,87 @@
|
||||||
|
use pagetop::prelude::*;
|
||||||
|
|
||||||
|
use crate::Job;
|
||||||
|
|
||||||
|
/// Tipo de función que declara trabajos en un [`CronJobs`].
|
||||||
|
pub type FnDeclareCronJobs = fn(jobs: &mut CronJobs);
|
||||||
|
|
||||||
|
/// Trabajos declarados por las extensiones. Ver [`DeclareCronJobs`].
|
||||||
|
#[derive(AutoDefault)]
|
||||||
|
pub struct CronJobs {
|
||||||
|
jobs: Vec<Job>,
|
||||||
|
}
|
||||||
|
|
||||||
|
impl CronJobs {
|
||||||
|
/// Añade un trabajo.
|
||||||
|
pub fn add(&mut self, job: Job) {
|
||||||
|
self.jobs.push(job);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Recoge los trabajos de todas las extensiones.
|
||||||
|
pub(crate) fn collect() -> Vec<Job> {
|
||||||
|
let mut jobs = CronJobs::default();
|
||||||
|
dispatch_actions(|action: &DeclareCronJobs| (action.f)(&mut jobs));
|
||||||
|
jobs.jobs
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Acción para declarar trabajos programados.
|
||||||
|
///
|
||||||
|
/// Cada extensión registra esta acción con una función que añade sus trabajos. Se despacha una
|
||||||
|
/// sola vez, al inicializar `pagetop-cron`, así que los trabajos quedan fijos durante toda la vida
|
||||||
|
/// de la aplicación, como las propias acciones.
|
||||||
|
///
|
||||||
|
/// # Ejemplo
|
||||||
|
///
|
||||||
|
/// ```rust,no_run
|
||||||
|
/// use pagetop::prelude::*;
|
||||||
|
/// use pagetop_cron::prelude::*;
|
||||||
|
///
|
||||||
|
/// async fn cleanup(_cx: JobContext) -> JobResult {
|
||||||
|
/// // Borra los carritos abandonados...
|
||||||
|
/// Ok(())
|
||||||
|
/// }
|
||||||
|
///
|
||||||
|
/// fn declare_jobs(jobs: &mut CronJobs) {
|
||||||
|
/// jobs.add(
|
||||||
|
/// Job::new("shop.cleanup", Schedule::cron("30 4 * * *"), cleanup)
|
||||||
|
/// .with_title(Lc::n("Remove abandoned carts")),
|
||||||
|
/// );
|
||||||
|
/// }
|
||||||
|
///
|
||||||
|
/// struct Shop;
|
||||||
|
///
|
||||||
|
/// #[async_trait]
|
||||||
|
/// impl Extension for Shop {
|
||||||
|
/// fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||||
|
/// vec![&pagetop_cron::Cron]
|
||||||
|
/// }
|
||||||
|
///
|
||||||
|
/// fn actions(&self) -> Vec<ActionBox> {
|
||||||
|
/// actions![DeclareCronJobs::new(declare_jobs)]
|
||||||
|
/// }
|
||||||
|
/// }
|
||||||
|
/// ```
|
||||||
|
pub struct DeclareCronJobs {
|
||||||
|
f: FnDeclareCronJobs,
|
||||||
|
weight: Weight,
|
||||||
|
}
|
||||||
|
|
||||||
|
impl ActionDispatcher for DeclareCronJobs {
|
||||||
|
fn weight(&self) -> Weight {
|
||||||
|
self.weight
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
impl DeclareCronJobs {
|
||||||
|
/// Registra una función que declara trabajos.
|
||||||
|
pub fn new(f: FnDeclareCronJobs) -> Self {
|
||||||
|
DeclareCronJobs { f, weight: 0 }
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Opcional. Las acciones de menor peso se aplican antes. Se pueden usar valores negativos.
|
||||||
|
pub fn with_weight(mut self, value: Weight) -> Self {
|
||||||
|
self.weight = value;
|
||||||
|
self
|
||||||
|
}
|
||||||
|
}
|
||||||
50
extensions/pagetop-cron/src/error.rs
Normal file
50
extensions/pagetop-cron/src/error.rs
Normal file
|
|
@ -0,0 +1,50 @@
|
||||||
|
//! Errores de `pagetop-cron`.
|
||||||
|
|
||||||
|
/// Errores al declarar, configurar o ejecutar trabajos programados.
|
||||||
|
#[derive(Debug, thiserror::Error)]
|
||||||
|
pub enum CronError {
|
||||||
|
/// Una programación no es válida (p. ej. una expresión cron mal escrita o un intervalo nulo).
|
||||||
|
#[error("invalid schedule \"{schedule}\": {reason}")]
|
||||||
|
InvalidSchedule {
|
||||||
|
/// Programación tal como se indicó.
|
||||||
|
schedule: String,
|
||||||
|
/// Motivo del error.
|
||||||
|
reason: String,
|
||||||
|
},
|
||||||
|
/// La clave de un trabajo no es válida.
|
||||||
|
#[error(
|
||||||
|
"invalid job key \"{0}\": use lowercase letters, digits, '_', '-' and '.', starting with a \
|
||||||
|
letter or digit"
|
||||||
|
)]
|
||||||
|
InvalidKey(String),
|
||||||
|
/// Dos trabajos se declaran con la misma clave.
|
||||||
|
#[error("job \"{0}\" is declared more than once")]
|
||||||
|
DuplicateJob(String),
|
||||||
|
/// Un trabajo no se puede programar, por su declaración o por sus ajustes.
|
||||||
|
#[error("invalid job \"{key}\"")]
|
||||||
|
InvalidJob {
|
||||||
|
/// Clave del trabajo.
|
||||||
|
key: String,
|
||||||
|
/// Motivo del error.
|
||||||
|
#[source]
|
||||||
|
source: Box<CronError>,
|
||||||
|
},
|
||||||
|
/// Un ajuste de la sección `[cron]` no es válido.
|
||||||
|
#[error("invalid cron setting \"{key}\": {reason}")]
|
||||||
|
InvalidSetting {
|
||||||
|
/// Clave del ajuste, p. ej. `"cron.trigger_token"`.
|
||||||
|
key: &'static str,
|
||||||
|
/// Motivo del error.
|
||||||
|
reason: String,
|
||||||
|
},
|
||||||
|
/// No hay ningún trabajo declarado con la clave indicada.
|
||||||
|
#[error("unknown job \"{0}\"")]
|
||||||
|
UnknownJob(String),
|
||||||
|
/// El trabajo ya se está ejecutando y no admite ejecuciones simultáneas
|
||||||
|
/// ([`Overlap::Skip`](crate::Overlap::Skip)).
|
||||||
|
#[error("job \"{0}\" is already running")]
|
||||||
|
AlreadyRunning(String),
|
||||||
|
/// Los trabajos aún no están disponibles: la aplicación no se ha preparado.
|
||||||
|
#[error("cron jobs are not available until the application is prepared")]
|
||||||
|
NotInitialized,
|
||||||
|
}
|
||||||
240
extensions/pagetop-cron/src/job.rs
Normal file
240
extensions/pagetop-cron/src/job.rs
Normal file
|
|
@ -0,0 +1,240 @@
|
||||||
|
use pagetop::prelude::*;
|
||||||
|
|
||||||
|
use tokio::sync::watch;
|
||||||
|
|
||||||
|
use crate::{RunTrigger, Schedule};
|
||||||
|
|
||||||
|
use std::future::Future;
|
||||||
|
use std::pin::Pin;
|
||||||
|
use std::sync::Arc;
|
||||||
|
|
||||||
|
/// Resultado de una ejecución de un trabajo.
|
||||||
|
///
|
||||||
|
/// Con [`BoxError`] el trabajo puede propagar con `?` cualquier error; el error se registra en las
|
||||||
|
/// trazas y en el estado del trabajo ([`JobStatus`](crate::JobStatus)).
|
||||||
|
pub type JobResult = Result<(), BoxError>;
|
||||||
|
|
||||||
|
// Función del trabajo, ya preparada para ejecutarse en una tarea propia.
|
||||||
|
pub(crate) type JobFn =
|
||||||
|
Arc<dyn Fn(JobContext) -> Pin<Box<dyn Future<Output = JobResult> + Send>> + Send + Sync>;
|
||||||
|
|
||||||
|
/// Qué hacer a la hora de ejecutar un trabajo si no ha terminado la ejecución anterior.
|
||||||
|
///
|
||||||
|
/// Usado en [`Job::with_overlap()`]. Las ejecuciones programadas con [`Schedule::fixed_delay()`]
|
||||||
|
/// nunca se solapan entre sí; con esa programación, sólo decide qué ocurre si se pide
|
||||||
|
/// [`run_now()`](crate::run_now) durante una de ellas.
|
||||||
|
#[derive(AutoDefault, Clone, Copy, Debug, Eq, PartialEq)]
|
||||||
|
pub enum Overlap {
|
||||||
|
/// Se omite la nueva ejecución y se registra un aviso. Es el valor por defecto, porque la
|
||||||
|
/// mayoría de los trabajos no esperan ejecutarse dos veces a la vez sobre los mismos datos.
|
||||||
|
#[default]
|
||||||
|
Skip,
|
||||||
|
/// Se ejecuta igualmente, a la vez que la anterior.
|
||||||
|
Allow,
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Un trabajo programado: una función asíncrona que se ejecuta según una [`Schedule`].
|
||||||
|
///
|
||||||
|
/// Se identifica por una clave única, que conviene empezar por el nombre de la extensión
|
||||||
|
/// (`"shop.cleanup"`), con letras minúsculas, dígitos, `_`, `-` y `.`. La clave aparece en las
|
||||||
|
/// trazas y es la que usa la configuración para cambiar o desactivar el trabajo
|
||||||
|
/// (`[cron.jobs."shop.cleanup"]`) y [`run_now()`](crate::run_now) para ejecutarlo bajo demanda.
|
||||||
|
///
|
||||||
|
/// La función recibe un [`JobContext`] y devuelve un [`JobResult`]. Accede a los ajustes y a los
|
||||||
|
/// servicios de la aplicación igual que un *handler*: con los `SETTINGS` de cada extensión, o con
|
||||||
|
/// funciones como `dbconn()` de `pagetop-seaorm`.
|
||||||
|
///
|
||||||
|
/// Los trabajos se declaran con la acción [`DeclareCronJobs`](crate::DeclareCronJobs).
|
||||||
|
///
|
||||||
|
/// # Ejemplo
|
||||||
|
///
|
||||||
|
/// ```rust,no_run
|
||||||
|
/// use pagetop::prelude::*;
|
||||||
|
/// use pagetop_cron::prelude::*;
|
||||||
|
///
|
||||||
|
/// async fn purge_sessions(_cx: JobContext) -> JobResult {
|
||||||
|
/// // Borra las sesiones caducadas...
|
||||||
|
/// Ok(())
|
||||||
|
/// }
|
||||||
|
///
|
||||||
|
/// let job = Job::new("shop.purge_sessions", Schedule::cron("0 3 * * *"), purge_sessions)
|
||||||
|
/// .with_title(Lc::n("Purge expired sessions"))
|
||||||
|
/// .with_timeout(Duration::minutes(10));
|
||||||
|
/// ```
|
||||||
|
#[derive(Clone, Getters)]
|
||||||
|
pub struct Job {
|
||||||
|
/// Devuelve la clave única del trabajo.
|
||||||
|
key: CowStr,
|
||||||
|
/// Devuelve el título descriptivo del trabajo.
|
||||||
|
title: Lc,
|
||||||
|
/// Devuelve la programación declarada en el código.
|
||||||
|
schedule: Schedule,
|
||||||
|
#[getters(skip)]
|
||||||
|
run: JobFn,
|
||||||
|
/// Devuelve qué hacer si la ejecución anterior aún no ha terminado.
|
||||||
|
#[getters(copy)]
|
||||||
|
overlap: Overlap,
|
||||||
|
/// Devuelve el tiempo máximo de cada ejecución, si lo hay.
|
||||||
|
#[getters(copy)]
|
||||||
|
timeout: Option<Duration>,
|
||||||
|
/// Devuelve la zona horaria propia del trabajo, si la tiene.
|
||||||
|
#[getters(copy)]
|
||||||
|
timezone: Option<Tz>,
|
||||||
|
/// Devuelve si el trabajo se ejecuta también al arrancar la aplicación.
|
||||||
|
#[getters(copy)]
|
||||||
|
run_on_start: bool,
|
||||||
|
}
|
||||||
|
|
||||||
|
impl Job {
|
||||||
|
/// Crea un trabajo con su clave, su programación y la función que ejecuta.
|
||||||
|
///
|
||||||
|
/// La función puede ser una `async fn` o un cierre que devuelva un *future*. El *future* debe
|
||||||
|
/// ser `Send + 'static`: si el cierre usa datos propios, los clona dentro de un bloque
|
||||||
|
/// `async move`.
|
||||||
|
pub fn new<F, Fut>(key: impl Into<CowStr>, schedule: Schedule, run: F) -> Self
|
||||||
|
where
|
||||||
|
F: Fn(JobContext) -> Fut + Send + Sync + 'static,
|
||||||
|
Fut: Future<Output = JobResult> + Send + 'static,
|
||||||
|
{
|
||||||
|
Job {
|
||||||
|
key: key.into(),
|
||||||
|
title: Lc::none(),
|
||||||
|
schedule,
|
||||||
|
run: Arc::new(move |cx| Box::pin(run(cx))),
|
||||||
|
overlap: Overlap::default(),
|
||||||
|
timeout: None,
|
||||||
|
timezone: None,
|
||||||
|
run_on_start: false,
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Título descriptivo para listados y paneles. Sin título, se muestra la clave.
|
||||||
|
pub fn with_title(mut self, title: Lc) -> Self {
|
||||||
|
self.title = title;
|
||||||
|
self
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Qué hacer cuando llega la hora de una ejecución y la anterior aún no ha terminado. Por
|
||||||
|
/// defecto, [`Overlap::Skip`].
|
||||||
|
pub fn with_overlap(mut self, overlap: Overlap) -> Self {
|
||||||
|
self.overlap = overlap;
|
||||||
|
self
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Tiempo máximo de cada ejecución. Si se supera, la ejecución se cancela (el *future* deja
|
||||||
|
/// de ejecutarse en el siguiente `.await`) y se registra como
|
||||||
|
/// [`JobOutcome::TimedOut`](crate::JobOutcome::TimedOut). Sin valor, no hay límite.
|
||||||
|
///
|
||||||
|
/// Un trabajo que no llega a ningún `.await` (un cálculo largo, una llamada bloqueante) no se
|
||||||
|
/// puede cancelar: sigue en marcha hasta terminar y, mientras tanto, cuenta como en curso.
|
||||||
|
///
|
||||||
|
/// La configuración puede cambiarlo con `timeout_secs` (ver
|
||||||
|
/// [`JobSettings`](crate::config::JobSettings)).
|
||||||
|
pub fn with_timeout(mut self, timeout: impl Into<Option<Duration>>) -> Self {
|
||||||
|
self.timeout = timeout.into();
|
||||||
|
self
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Zona horaria en la que se interpreta la expresión cron de este trabajo, p. ej.
|
||||||
|
/// `Tz::Europe__Madrid`. Sin valor, la de la aplicación (`[app].timezone`).
|
||||||
|
pub fn with_timezone(mut self, timezone: impl Into<Option<Tz>>) -> Self {
|
||||||
|
self.timezone = timezone.into();
|
||||||
|
self
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Ejecuta también el trabajo al arrancar la aplicación, además de según su programación. Útil
|
||||||
|
/// para no esperar a la primera ejecución programada, p. ej. para procesar lo que quedó
|
||||||
|
/// pendiente al detener la aplicación.
|
||||||
|
///
|
||||||
|
/// Con `mode = "external"` se ejecuta en la primera llamada a `POST /cron` que recibe cada
|
||||||
|
/// proceso de la aplicación, y con `mode = "off"` no se ejecuta.
|
||||||
|
pub fn with_run_on_start(mut self) -> Self {
|
||||||
|
self.run_on_start = true;
|
||||||
|
self
|
||||||
|
}
|
||||||
|
|
||||||
|
// Función del trabajo, para ejecutarla en una tarea propia.
|
||||||
|
pub(crate) fn runner(&self) -> JobFn {
|
||||||
|
Arc::clone(&self.run)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// **< JobContext >*********************************************************************************
|
||||||
|
|
||||||
|
/// Datos de la ejecución en curso que recibe la función de un [`Job`].
|
||||||
|
///
|
||||||
|
/// Además de indicar qué provocó la ejecución, permite a los trabajos largos saber si la aplicación
|
||||||
|
/// se está deteniendo, para dejar su trabajo en un punto seguro antes de que se agote el tiempo de
|
||||||
|
/// espera (`cron.shutdown_timeout_secs`).
|
||||||
|
///
|
||||||
|
/// # Ejemplo
|
||||||
|
///
|
||||||
|
/// ```rust,no_run
|
||||||
|
/// use pagetop::prelude::*;
|
||||||
|
/// use pagetop_cron::prelude::*;
|
||||||
|
///
|
||||||
|
/// async fn send_newsletters(cx: JobContext) -> JobResult {
|
||||||
|
/// for batch in 0..100 {
|
||||||
|
/// if cx.is_stopping() {
|
||||||
|
/// // Lo que falte se enviará en la siguiente ejecución.
|
||||||
|
/// trace::info!("Stopping \"{}\" at batch {batch}", cx.key());
|
||||||
|
/// break;
|
||||||
|
/// }
|
||||||
|
/// // Envía el lote...
|
||||||
|
/// }
|
||||||
|
/// Ok(())
|
||||||
|
/// }
|
||||||
|
/// ```
|
||||||
|
#[derive(Clone, Debug)]
|
||||||
|
pub struct JobContext {
|
||||||
|
key: CowStr,
|
||||||
|
trigger: RunTrigger,
|
||||||
|
scheduled_at: Option<DateTime<Utc>>,
|
||||||
|
stop: watch::Receiver<bool>,
|
||||||
|
}
|
||||||
|
|
||||||
|
impl JobContext {
|
||||||
|
pub(crate) fn new(
|
||||||
|
key: CowStr,
|
||||||
|
trigger: RunTrigger,
|
||||||
|
scheduled_at: Option<DateTime<Utc>>,
|
||||||
|
stop: watch::Receiver<bool>,
|
||||||
|
) -> Self {
|
||||||
|
JobContext {
|
||||||
|
key,
|
||||||
|
trigger,
|
||||||
|
scheduled_at,
|
||||||
|
stop,
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Clave del trabajo.
|
||||||
|
pub fn key(&self) -> &str {
|
||||||
|
&self.key
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Qué provocó esta ejecución.
|
||||||
|
pub fn trigger(&self) -> RunTrigger {
|
||||||
|
self.trigger
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Momento en que estaba programada esta ejecución, en UTC. Puede ser algo anterior al momento
|
||||||
|
/// real en que empieza. `None` si no se debe a la programación (al arrancar o bajo demanda).
|
||||||
|
pub fn scheduled_at(&self) -> Option<DateTime<Utc>> {
|
||||||
|
self.scheduled_at
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Devuelve `true` si la aplicación se está deteniendo.
|
||||||
|
pub fn is_stopping(&self) -> bool {
|
||||||
|
*self.stop.borrow()
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Espera hasta que la aplicación empiece a detenerse. Pensado para `tokio::select!`, junto a
|
||||||
|
/// la espera de otra operación que se quiera interrumpir.
|
||||||
|
pub async fn stopping(&self) {
|
||||||
|
let mut stop = self.stop.clone();
|
||||||
|
if stop.wait_for(|stopping| *stopping).await.is_err() {
|
||||||
|
std::future::pending::<()>().await;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
442
extensions/pagetop-cron/src/lib.rs
Normal file
442
extensions/pagetop-cron/src/lib.rs
Normal file
|
|
@ -0,0 +1,442 @@
|
||||||
|
/*!
|
||||||
|
<div align="center">
|
||||||
|
|
||||||
|
<h1>PageTop Cron</h1>
|
||||||
|
|
||||||
|
<p>Programación de tareas para aplicaciones <strong>PageTop</strong>.</p>
|
||||||
|
|
||||||
|
[](https://docs.rs/pagetop-cron)
|
||||||
|
[](https://crates.io/crates/pagetop-cron)
|
||||||
|
[](https://crates.io/crates/pagetop-cron)
|
||||||
|
[](https://git.cillero.es/manuelcillero/pagetop/src/branch/main/extensions/pagetop-cron#licencia)
|
||||||
|
|
||||||
|
</div>
|
||||||
|
|
||||||
|
Ejecuta trabajos periódicos en segundo plano mientras la aplicación está en marcha: cada noche a
|
||||||
|
las 4:30, cada diez minutos, el último día de cada mes, o unos segundos después de terminar la
|
||||||
|
ejecución anterior. Cada extensión declara sus trabajos en el código con una acción, y quien
|
||||||
|
administra la aplicación decide en los archivos de configuración cómo se ejecutan, y puede cambiar
|
||||||
|
cuándo se ejecuta cada trabajo o desactivarlo sin recompilar.
|
||||||
|
|
||||||
|
## Sobre PageTop
|
||||||
|
|
||||||
|
[PageTop](https://docs.rs/pagetop) es un entorno de desarrollo que reivindica la esencia de la web
|
||||||
|
clásica para crear soluciones web SSR (*renderizadas en el servidor*) modulares, extensibles y
|
||||||
|
configurables, basadas en HTML, CSS y JavaScript.
|
||||||
|
|
||||||
|
## Guía rápida
|
||||||
|
|
||||||
|
**Añade la dependencia** a tu `Cargo.toml`:
|
||||||
|
|
||||||
|
```toml
|
||||||
|
[dependencies]
|
||||||
|
pagetop-cron = "..."
|
||||||
|
```
|
||||||
|
|
||||||
|
**Escribe el trabajo** como una función asíncrona que recibe un [`JobContext`] y devuelve un
|
||||||
|
[`JobResult`]. Con `?` puede propagar cualquier error, que se registra en las trazas:
|
||||||
|
|
||||||
|
```rust,no_run
|
||||||
|
use pagetop::prelude::*;
|
||||||
|
use pagetop_cron::prelude::*;
|
||||||
|
|
||||||
|
async fn cleanup(_cx: JobContext) -> JobResult {
|
||||||
|
// Borra los carritos abandonados hace más de 30 días...
|
||||||
|
Ok(())
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Declara el trabajo** con la acción [`DeclareCronJobs`] en la extensión que lo aporta, que depende
|
||||||
|
de `pagetop-cron`:
|
||||||
|
|
||||||
|
```rust,no_run
|
||||||
|
# use pagetop::prelude::*;
|
||||||
|
# use pagetop_cron::prelude::*;
|
||||||
|
# async fn cleanup(_cx: JobContext) -> JobResult { Ok(()) }
|
||||||
|
fn declare_jobs(jobs: &mut CronJobs) {
|
||||||
|
jobs.add(
|
||||||
|
Job::new("shop.cleanup", Schedule::cron("30 4 * * *"), cleanup)
|
||||||
|
.with_title(Lc::n("Remove abandoned carts"))
|
||||||
|
.with_timeout(Duration::minutes(15)),
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
struct Shop;
|
||||||
|
|
||||||
|
#[async_trait]
|
||||||
|
impl Extension for Shop {
|
||||||
|
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||||
|
vec![&pagetop_cron::Cron]
|
||||||
|
}
|
||||||
|
|
||||||
|
fn actions(&self) -> Vec<ActionBox> {
|
||||||
|
actions![DeclareCronJobs::new(declare_jobs)]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Y ya está: al ejecutar la aplicación con [`Application::run()`], el trabajo se ejecuta cada día a
|
||||||
|
las 4:30 en la zona horaria de la aplicación (`[app].timezone`). La clave (`"shop.cleanup"`)
|
||||||
|
identifica el trabajo en las trazas, en la configuración y al ejecutarlo bajo demanda; conviene
|
||||||
|
empezarla por el nombre de la extensión.
|
||||||
|
|
||||||
|
## Cuándo se ejecuta un trabajo
|
||||||
|
|
||||||
|
[`Schedule`] ofrece tres formas de programarlo:
|
||||||
|
|
||||||
|
```rust,no_run
|
||||||
|
# use pagetop::prelude::*;
|
||||||
|
# use pagetop_cron::prelude::*;
|
||||||
|
// Según una expresión cron: cada día a las 4:30.
|
||||||
|
Schedule::cron("30 4 * * *");
|
||||||
|
// Cada cinco minutos desde que *empieza* la ejecución anterior (ritmo fijo).
|
||||||
|
Schedule::fixed_rate(Duration::minutes(5));
|
||||||
|
// Treinta segundos después de que *termina* la ejecución anterior (nunca se solapan).
|
||||||
|
Schedule::fixed_delay(Duration::seconds(30));
|
||||||
|
```
|
||||||
|
|
||||||
|
Las expresiones cron siguen la sintaxis clásica de cinco campos, con un sexto campo opcional para
|
||||||
|
los segundos y un séptimo, también opcional, para el año, y admiten además `L`, `W` y `#` (último
|
||||||
|
día del mes, día laborable más cercano, enésimo día de la semana) y apodos como `@daily`. Se
|
||||||
|
interpretan en la zona horaria de la aplicación y respetan los cambios de hora. Todos los
|
||||||
|
detalles, con ejemplos, en [`Schedule`].
|
||||||
|
|
||||||
|
Para procesar colas o tareas pendientes, `fixed_delay()` suele ser la mejor opción: cada ejecución
|
||||||
|
procesa lo que dejó la anterior y nunca coinciden dos.
|
||||||
|
|
||||||
|
## Opciones de cada trabajo
|
||||||
|
|
||||||
|
[`Job`] ofrece además:
|
||||||
|
|
||||||
|
| Método | Uso |
|
||||||
|
|-------------------------|---------------------------------------------------------------|
|
||||||
|
| [`with_title()`] | Título descriptivo, traducible, para listados y paneles. |
|
||||||
|
| [`with_timeout()`] | Tiempo máximo de cada ejecución; si lo supera, se cancela. |
|
||||||
|
| [`with_overlap()`] | Qué hacer si la ejecución anterior sigue en curso ([`Overlap`]). |
|
||||||
|
| [`with_timezone()`] | Zona horaria propia para su expresión cron. |
|
||||||
|
| [`with_run_on_start()`] | Se ejecuta también al arrancar la aplicación. |
|
||||||
|
|
||||||
|
Si llega la hora de un trabajo y su ejecución anterior aún no ha terminado, por defecto se omite la
|
||||||
|
nueva ([`Overlap::Skip`]); con [`Overlap::Allow`] se ejecuta a la vez.
|
||||||
|
|
||||||
|
[`with_title()`]: Job::with_title
|
||||||
|
[`with_timeout()`]: Job::with_timeout
|
||||||
|
[`with_overlap()`]: Job::with_overlap
|
||||||
|
[`with_timezone()`]: Job::with_timezone
|
||||||
|
[`with_run_on_start()`]: Job::with_run_on_start
|
||||||
|
|
||||||
|
La función del trabajo puede ser también un cierre. Accede a los ajustes y servicios de la
|
||||||
|
aplicación igual que un *handler*, p. ej. con los `SETTINGS` de cada extensión o con `dbconn()` de
|
||||||
|
`pagetop-seaorm`:
|
||||||
|
|
||||||
|
```rust,no_run
|
||||||
|
# use pagetop::prelude::*;
|
||||||
|
# use pagetop_cron::prelude::*;
|
||||||
|
let job = Job::new("app.heartbeat", Schedule::fixed_rate(Duration::minutes(1)), |cx| async move {
|
||||||
|
trace::info!("Heartbeat from \"{}\" ({:?})", cx.key(), cx.trigger());
|
||||||
|
Ok(())
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
Un `panic!` dentro de un trabajo no afecta a la aplicación ni a sus siguientes ejecuciones: se
|
||||||
|
registra como un fallo más.
|
||||||
|
|
||||||
|
## Modos de ejecución
|
||||||
|
|
||||||
|
Quien administra la aplicación elige cómo se ejecutan los trabajos con `mode`, en la sección
|
||||||
|
`[cron]` (todas las opciones en [`config`]):
|
||||||
|
|
||||||
|
| `mode` | Los trabajos se ejecutan... |
|
||||||
|
|--------------|-------------------------------------------------------------------------|
|
||||||
|
| `"internal"` | Por defecto. Con el planificador de la propia aplicación. |
|
||||||
|
| `"external"` | Cuando un programa externo llama a `POST /cron` con la clave secreta. |
|
||||||
|
| `"off"` | Nunca de forma automática; sólo bajo demanda con [`run_now()`]. |
|
||||||
|
|
||||||
|
### Una sola instancia: `"internal"`
|
||||||
|
|
||||||
|
Con `"internal"`, cada proceso de la aplicación lleva su propio reloj y lanza los trabajos cuando
|
||||||
|
les toca. Con un solo proceso siempre en marcha (un servidor, un servicio de *systemd*, un
|
||||||
|
contenedor) es justo lo que se necesita, y no hay que configurar nada.
|
||||||
|
|
||||||
|
### Varias instancias
|
||||||
|
|
||||||
|
Si la misma aplicación se ejecuta en varios procesos a la vez, cada uno lanza todos los trabajos
|
||||||
|
con `"internal"`:
|
||||||
|
|
||||||
|
```text
|
||||||
|
+--> instancia A (internal) --> limpieza a las 4:30
|
||||||
|
balanceador ---+--> instancia B (internal) --> limpieza a las 4:30
|
||||||
|
+--> instancia C (internal) --> limpieza a las 4:30
|
||||||
|
```
|
||||||
|
|
||||||
|
La limpieza se hace tres veces, y un boletín se enviaría tres veces. Las instancias no se ponen de
|
||||||
|
acuerdo entre sí, así que hay dos formas de evitarlo:
|
||||||
|
|
||||||
|
- **`"internal"` en una instancia y `"off"` en las demás.** Es lo más sencillo si las instancias
|
||||||
|
se configuran a mano, pero esa instancia queda distinta del resto: si se detiene, nadie ejecuta
|
||||||
|
los trabajos.
|
||||||
|
- **`"external"` en todas.** Ninguna tiene reloj propio: un único reloj fuera de la aplicación
|
||||||
|
llama periódicamente a `POST /cron`, y el balanceador entrega cada llamada a una sola instancia,
|
||||||
|
que ejecuta lo programado desde la llamada anterior:
|
||||||
|
|
||||||
|
```text
|
||||||
|
crontab (en una sola máquina) --POST /cron--> balanceador --> instancia B ejecuta lo pendiente
|
||||||
|
```
|
||||||
|
|
||||||
|
### Cuándo usar `"external"`
|
||||||
|
|
||||||
|
- **Réplicas idénticas o autoescalado** (Kubernetes, Docker Swarm, varias máquinas tras un
|
||||||
|
balanceador). Todas arrancan con la misma imagen y la misma configuración, así que no se puede
|
||||||
|
dejar una distinta. Con `"external"` todas son iguales y cualquiera puede atender la llamada.
|
||||||
|
- **Plataformas que detienen la aplicación cuando no hay tráfico** (escalado a cero). Si nadie
|
||||||
|
visita el sitio de madrugada, no queda ningún proceso vivo y el reloj interno de las 4:30 no
|
||||||
|
existe; algunas plataformas, además, sólo dan CPU mientras se atiende una petición. La llamada
|
||||||
|
externa despierta la aplicación y le da tiempo para ejecutar lo pendiente. Estas plataformas
|
||||||
|
suelen ofrecer su propio planificador para hacerla.
|
||||||
|
- **Planificar desde las herramientas de operaciones** que ya se usan, como un *CronJob* de
|
||||||
|
Kubernetes o un temporizador de *systemd*. La llamada responde `200 OK` aunque falle algún
|
||||||
|
trabajo, para que un reintento no repita los demás; el resultado de cada uno viene en el cuerpo
|
||||||
|
de la respuesta y, para avisar de los fallos, está la acción [`AfterJobRun`].
|
||||||
|
|
||||||
|
Con una sola instancia siempre en marcha, `"external"` no aporta nada: añade piezas (un `crontab`,
|
||||||
|
una clave secreta, una ruta expuesta) y pierde precisión. Mejor `"internal"`.
|
||||||
|
|
||||||
|
### Configurar `"external"`
|
||||||
|
|
||||||
|
```toml
|
||||||
|
[cron]
|
||||||
|
mode = "external"
|
||||||
|
trigger_token = "..." # Clave secreta propia, mejor en config/local.toml.
|
||||||
|
trigger_interval_secs = 60 # Una llamada por minuto (el valor por defecto).
|
||||||
|
```
|
||||||
|
|
||||||
|
La clave debe tener al menos 16 caracteres (letras, dígitos, `-` o `_`), o la aplicación no
|
||||||
|
arranca; `openssl rand -hex 32` genera una adecuada. Viaja en la cabecera
|
||||||
|
`Authorization: Bearer <clave>`, no en la ruta, porque los *proxies* y los balanceadores suelen
|
||||||
|
registrar las rutas de las peticiones. Para que tampoco aparezca en la lista de procesos del
|
||||||
|
sistema, `curl` puede leer la cabecera de un archivo que sólo pueda leer el usuario del `crontab`:
|
||||||
|
|
||||||
|
```text
|
||||||
|
# crontab del sistema: comprueba los trabajos cada minuto. El archivo contiene la línea
|
||||||
|
# "Authorization: Bearer <clave>".
|
||||||
|
* * * * * curl -fsS -X POST -H @/etc/miapp/cron-header https://example.com/cron > /dev/null
|
||||||
|
```
|
||||||
|
|
||||||
|
La llamada responde cuando terminan los trabajos que ejecuta, con `200 OK` y una línea por trabajo
|
||||||
|
con su resultado (`succeeded`, `failed`, `timed out` o `panicked`); sin la clave correcta responde
|
||||||
|
`404 Not Found`, igual que una ruta que no existe. Esperar mantiene viva la aplicación en las
|
||||||
|
plataformas que sólo dan CPU mientras se atiende una petición, así que el tiempo de espera del
|
||||||
|
programa externo debe superar lo que tarde el trabajo más largo; conviene limitarlo con
|
||||||
|
[`with_timeout()`]. Si el programa externo corta antes, los trabajos siguen igualmente, pero en esas
|
||||||
|
plataformas pueden quedarse sin CPU.
|
||||||
|
|
||||||
|
Cada llamada ejecuta lo programado en el último minuto, sea cual sea la instancia que la recibe y
|
||||||
|
aunque acabe de arrancar: una llamada a las 4:30:20 ejecuta lo programado desde las 4:29:00
|
||||||
|
(excluido) hasta las 4:30:00. Así ninguna instancia necesita recordar qué hicieron las demás, pero
|
||||||
|
el programa externo debe llamar una vez, y sólo una, cada minuto: si falta una llamada se pierden
|
||||||
|
sus ejecuciones, y si sobra, dos instancias pueden repetirlas. Para llamar con otra frecuencia
|
||||||
|
(p. ej. cada cuarto de hora, en una plataforma que despierta la aplicación en cada llamada),
|
||||||
|
indícala en `trigger_interval_secs` (`900`) y programa los trabajos en múltiplos de ella. La
|
||||||
|
precisión es la del intervalo: con una llamada por minuto, un trabajo programado cada diez
|
||||||
|
segundos se ejecuta una vez por minuto.
|
||||||
|
|
||||||
|
Una llamada de más suele ser un reintento. La respuesta es `200 OK` aunque falle algún trabajo, así
|
||||||
|
que el programa externo sólo reintenta tras un error de red o si se agota su tiempo de espera; pero
|
||||||
|
si el reintento llega a otra instancia, ésta ejecuta de nuevo lo mismo, porque las instancias no
|
||||||
|
comparten estado. Desactiva los reintentos del programa externo (p. ej. `backoffLimit: 0` en un
|
||||||
|
*CronJob* de Kubernetes) y, si un trabajo no debe repetirse nunca, que lo compruebe él mismo (p. ej.
|
||||||
|
en la base de datos) antes de hacer nada.
|
||||||
|
|
||||||
|
## Ajustar un trabajo desde la configuración
|
||||||
|
|
||||||
|
Cada trabajo puede cambiarse por su clave, sin tocar el código, en la subsección
|
||||||
|
`[cron.jobs."clave"]` (ver [`JobSettings`](config::JobSettings)):
|
||||||
|
|
||||||
|
```toml
|
||||||
|
[cron.jobs."shop.cleanup"]
|
||||||
|
schedule = "0 5 * * SUN" # Sólo los domingos a las 5:00.
|
||||||
|
timeout_secs = 1800 # Tiempo máximo de 30 minutos (0 = sin límite).
|
||||||
|
|
||||||
|
[cron.jobs."shop.reminders"]
|
||||||
|
enabled = false # Desactivado: sólo se ejecuta bajo demanda.
|
||||||
|
```
|
||||||
|
|
||||||
|
La programación admite la misma sintaxis que [`Schedule::parse()`], incluidos `"@every 10m"` y
|
||||||
|
`"@delay 30s"`. Una programación no válida detiene el arranque indicando el trabajo, y una clave
|
||||||
|
que no corresponde a ningún trabajo se ignora con un aviso en las trazas.
|
||||||
|
|
||||||
|
## Ejecutar y consultar los trabajos
|
||||||
|
|
||||||
|
[`run_now()`] ejecuta un trabajo en el acto y devuelve su [`JobRun`]: útil para un botón
|
||||||
|
«Ejecutar ahora» de un panel de administración, para una orden de mantenimiento o para las
|
||||||
|
pruebas. [`jobs()`] y [`job()`] devuelven su [`JobStatus`]: programación efectiva, próxima
|
||||||
|
ejecución, resultado de la última y número de ejecuciones, fallos y omisiones.
|
||||||
|
|
||||||
|
Para reaccionar a cada ejecución terminada (registrarla, enviar métricas, avisar cuando falla un
|
||||||
|
trabajo), registra la acción [`AfterJobRun`].
|
||||||
|
|
||||||
|
## Detener la aplicación
|
||||||
|
|
||||||
|
Al detener la aplicación (Ctrl+C o `SIGTERM`), el planificador deja de lanzar ejecuciones y espera
|
||||||
|
a que terminen las que están en curso, hasta `cron.shutdown_timeout_secs` (30 s por defecto). Un
|
||||||
|
trabajo largo puede comprobar [`JobContext::is_stopping()`] para dejar su trabajo en un punto
|
||||||
|
seguro antes de que se agote ese tiempo.
|
||||||
|
|
||||||
|
## Pruebas
|
||||||
|
|
||||||
|
El planificador sólo se pone en marcha con [`Application::run()`] (ver
|
||||||
|
[`Extension::start()`](pagetop::core::extension::Extension::start)), nunca en las pruebas que
|
||||||
|
preparan la aplicación y obtienen su servidor con [`Application::test()`]. En ellas, los trabajos
|
||||||
|
se ejecutan cuando la prueba quiere con [`run_now()`]:
|
||||||
|
|
||||||
|
```rust,no_run
|
||||||
|
# use pagetop::prelude::*;
|
||||||
|
# struct Shop;
|
||||||
|
# #[async_trait]
|
||||||
|
# impl Extension for Shop {}
|
||||||
|
#[pagetop::test]
|
||||||
|
async fn cleanup_job_succeeds() {
|
||||||
|
Application::prepare(&Shop).await;
|
||||||
|
let run = pagetop_cron::run_now("shop.cleanup").await.unwrap();
|
||||||
|
assert!(run.outcome().is_success(), "{}", run.outcome());
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Qué no hace
|
||||||
|
|
||||||
|
Para mantenerse sencilla, la extensión no guarda nada fuera de la memoria:
|
||||||
|
|
||||||
|
- **No recupera las ejecuciones perdidas.** Si la aplicación estaba detenida cuando tocaba una
|
||||||
|
ejecución, no se hace al volver a arrancar; la siguiente llega según su programación. Para
|
||||||
|
trabajos que no deben perder ninguna, combina la programación con
|
||||||
|
[`with_run_on_start()`](Job::with_run_on_start), o guarda en la base de datos qué queda
|
||||||
|
pendiente y procésalo en cada ejecución.
|
||||||
|
- **No es una cola de trabajos.** Para tareas puntuales que deben sobrevivir a un reinicio (un
|
||||||
|
correo que no se pudo enviar, una importación...), cada extensión guarda las pendientes en su
|
||||||
|
propia tabla y declara un trabajo periódico que las procesa.
|
||||||
|
- **No coordina varias instancias** por sí misma; ver [varias instancias](#varias-instancias).
|
||||||
|
|
||||||
|
[`Application::run()`]: pagetop::app::Application::run
|
||||||
|
[`Application::test()`]: pagetop::app::Application::test
|
||||||
|
|
||||||
|
## Créditos
|
||||||
|
|
||||||
|
Las expresiones cron se interpretan con [croner](https://github.com/hexagon/croner-rust), la misma
|
||||||
|
biblioteca que usa *tokio-cron-scheduler*, distribuida bajo licencia
|
||||||
|
[MIT](https://github.com/hexagon/croner-rust/blob/master/LICENSE).
|
||||||
|
*/
|
||||||
|
|
||||||
|
#![doc(
|
||||||
|
html_favicon_url = "https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/assets/favicon.ico"
|
||||||
|
)]
|
||||||
|
|
||||||
|
use pagetop::prelude::*;
|
||||||
|
|
||||||
|
pub mod config;
|
||||||
|
|
||||||
|
mod error;
|
||||||
|
pub use error::CronError;
|
||||||
|
|
||||||
|
mod schedule;
|
||||||
|
pub use schedule::Schedule;
|
||||||
|
|
||||||
|
mod job;
|
||||||
|
pub use job::{Job, JobContext, JobResult, Overlap};
|
||||||
|
|
||||||
|
mod run;
|
||||||
|
pub use run::{AfterJobRun, FnAfterJobRun, JobOutcome, JobRun, RunTrigger};
|
||||||
|
|
||||||
|
mod status;
|
||||||
|
pub use status::JobStatus;
|
||||||
|
|
||||||
|
mod declare;
|
||||||
|
pub use declare::{CronJobs, DeclareCronJobs, FnDeclareCronJobs};
|
||||||
|
|
||||||
|
mod scheduler;
|
||||||
|
pub use scheduler::{TRIGGER_PATH, job, jobs, run_due, run_now};
|
||||||
|
|
||||||
|
include_locales!(LOCALES_CRON);
|
||||||
|
|
||||||
|
/// Prelude de `pagetop-cron`.
|
||||||
|
pub mod prelude {
|
||||||
|
pub use crate::{AfterJobRun, CronJobs, DeclareCronJobs};
|
||||||
|
pub use crate::{CronError, Job, JobContext, JobResult, Overlap, Schedule};
|
||||||
|
pub use crate::{JobOutcome, JobRun, JobStatus, RunTrigger};
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Implementa la extensión `pagetop-cron`.
|
||||||
|
pub struct Cron;
|
||||||
|
|
||||||
|
#[async_trait]
|
||||||
|
impl Extension for Cron {
|
||||||
|
fn name(&self) -> Lc {
|
||||||
|
Lc::t("extension_name", &LOCALES_CRON)
|
||||||
|
}
|
||||||
|
|
||||||
|
fn description(&self) -> Lc {
|
||||||
|
Lc::t("extension_description", &LOCALES_CRON)
|
||||||
|
}
|
||||||
|
|
||||||
|
fn settings(&self) -> Option<&'static dyn LoadSettings> {
|
||||||
|
Some(&config::SETTINGS)
|
||||||
|
}
|
||||||
|
|
||||||
|
async fn initialize(&self) -> Result<(), BoxError> {
|
||||||
|
// Recoge y valida los trabajos de todas las extensiones: un error detiene el arranque.
|
||||||
|
scheduler::initialize()?;
|
||||||
|
Ok(())
|
||||||
|
}
|
||||||
|
|
||||||
|
async fn start(&self) -> Result<(), BoxError> {
|
||||||
|
scheduler::start();
|
||||||
|
Ok(())
|
||||||
|
}
|
||||||
|
|
||||||
|
async fn shutdown(&self) {
|
||||||
|
scheduler::shutdown().await;
|
||||||
|
}
|
||||||
|
|
||||||
|
fn configure_router(&self, router: Router) -> Router {
|
||||||
|
if config::SETTINGS.mode != config::CronMode::External {
|
||||||
|
return router;
|
||||||
|
}
|
||||||
|
router.route(TRIGGER_PATH, web::post(trigger_post).fallback(not_found))
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// POST {TRIGGER_PATH} - Lanza los trabajos pendientes (modo externo). La clave llega en la cabecera
|
||||||
|
// `Authorization` y no en la ruta, que suelen registrar los *proxies* y los balanceadores. Sin la
|
||||||
|
// clave correcta, o con otro método, responde la misma página 404 que una ruta inexistente.
|
||||||
|
async fn trigger_post(request: HttpRequest) -> Response {
|
||||||
|
let token = request
|
||||||
|
.headers()
|
||||||
|
.get(web::http::header::AUTHORIZATION)
|
||||||
|
.and_then(|value| value.to_str().ok())
|
||||||
|
.and_then(|value| value.split_once(' '))
|
||||||
|
.filter(|(scheme, _)| scheme.eq_ignore_ascii_case("Bearer"))
|
||||||
|
.map(|(_, token)| token.trim_start());
|
||||||
|
if !token.is_some_and(scheduler::token_matches) {
|
||||||
|
return ErrorPage::NotFound(Some(request)).into_response();
|
||||||
|
}
|
||||||
|
// Siempre `200 OK`, aunque falle algún trabajo: un reintento del programa externo podría
|
||||||
|
// llegar a otra instancia y repetir también los que terminaron bien. Sólo se indica el tipo de
|
||||||
|
// resultado; los mensajes de error, que pueden revelar detalles internos, van a las trazas.
|
||||||
|
let runs = run_due().await;
|
||||||
|
let mut body = util::join!("Ran ", runs.len().to_string(), " cron jobs\n");
|
||||||
|
for run in &runs {
|
||||||
|
body.push_str(run.key());
|
||||||
|
body.push_str(": ");
|
||||||
|
body.push_str(match run.outcome() {
|
||||||
|
JobOutcome::Succeeded => "succeeded",
|
||||||
|
JobOutcome::Failed(_) => "failed",
|
||||||
|
JobOutcome::TimedOut => "timed out",
|
||||||
|
JobOutcome::Panicked(_) => "panicked",
|
||||||
|
});
|
||||||
|
body.push('\n');
|
||||||
|
}
|
||||||
|
(web::http::StatusCode::OK, body).into_response()
|
||||||
|
}
|
||||||
|
|
||||||
|
async fn not_found(request: HttpRequest) -> ErrorPage {
|
||||||
|
ErrorPage::NotFound(Some(request))
|
||||||
|
}
|
||||||
2
extensions/pagetop-cron/src/locale/en-US/extension.ftl
Normal file
2
extensions/pagetop-cron/src/locale/en-US/extension.ftl
Normal file
|
|
@ -0,0 +1,2 @@
|
||||||
|
extension_name = Scheduled jobs
|
||||||
|
extension_description = Runs periodic jobs with cron expressions or intervals, and on demand.
|
||||||
2
extensions/pagetop-cron/src/locale/es-ES/extension.ftl
Normal file
2
extensions/pagetop-cron/src/locale/es-ES/extension.ftl
Normal file
|
|
@ -0,0 +1,2 @@
|
||||||
|
extension_name = Tareas programadas
|
||||||
|
extension_description = Ejecuta tareas periódicas con expresiones cron o intervalos, y bajo demanda.
|
||||||
165
extensions/pagetop-cron/src/run.rs
Normal file
165
extensions/pagetop-cron/src/run.rs
Normal file
|
|
@ -0,0 +1,165 @@
|
||||||
|
use pagetop::prelude::*;
|
||||||
|
|
||||||
|
use std::fmt;
|
||||||
|
|
||||||
|
/// Qué provocó la ejecución de un trabajo.
|
||||||
|
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
|
||||||
|
pub enum RunTrigger {
|
||||||
|
/// Su programación, con el planificador de la aplicación (`mode = "internal"`).
|
||||||
|
Schedule,
|
||||||
|
/// El arranque de la aplicación ([`Job::with_run_on_start()`](crate::Job::with_run_on_start)).
|
||||||
|
/// Con `mode = "external"`, en la primera llamada a `POST /cron` que recibe el proceso.
|
||||||
|
Startup,
|
||||||
|
/// Una llamada a [`run_now()`](crate::run_now).
|
||||||
|
Manual,
|
||||||
|
/// Su programación, con una llamada externa a `POST /cron` (`mode = "external"`).
|
||||||
|
External,
|
||||||
|
}
|
||||||
|
|
||||||
|
impl RunTrigger {
|
||||||
|
/// Nombre corto en inglés, para trazas y registros.
|
||||||
|
pub const fn as_str(&self) -> &'static str {
|
||||||
|
match self {
|
||||||
|
RunTrigger::Schedule => "schedule",
|
||||||
|
RunTrigger::Startup => "startup",
|
||||||
|
RunTrigger::Manual => "manual",
|
||||||
|
RunTrigger::External => "external",
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Resultado de una ejecución de un trabajo.
|
||||||
|
#[derive(Clone, Debug, Eq, PartialEq)]
|
||||||
|
pub enum JobOutcome {
|
||||||
|
/// Terminó sin errores.
|
||||||
|
Succeeded,
|
||||||
|
/// Devolvió un error, con su mensaje y el de sus causas.
|
||||||
|
Failed(String),
|
||||||
|
/// Superó su tiempo máximo ([`Job::with_timeout()`](crate::Job::with_timeout)) y se canceló.
|
||||||
|
TimedOut,
|
||||||
|
/// Provocó un `panic!`, con su mensaje. El `panic!` no afecta a la aplicación ni a las
|
||||||
|
/// siguientes ejecuciones.
|
||||||
|
Panicked(String),
|
||||||
|
}
|
||||||
|
|
||||||
|
impl JobOutcome {
|
||||||
|
/// Devuelve `true` si la ejecución terminó sin errores.
|
||||||
|
pub fn is_success(&self) -> bool {
|
||||||
|
matches!(self, JobOutcome::Succeeded)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
impl fmt::Display for JobOutcome {
|
||||||
|
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||||||
|
match self {
|
||||||
|
JobOutcome::Succeeded => f.write_str("succeeded"),
|
||||||
|
JobOutcome::Failed(error) => write!(f, "failed: {error}"),
|
||||||
|
JobOutcome::TimedOut => f.write_str("timed out"),
|
||||||
|
JobOutcome::Panicked(message) => write!(f, "panicked: {message}"),
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Informe de una ejecución terminada de un trabajo.
|
||||||
|
///
|
||||||
|
/// Lo devuelve [`run_now()`](crate::run_now), lo recibe la acción [`AfterJobRun`] y se guarda la
|
||||||
|
/// última de cada trabajo en su [`JobStatus`](crate::JobStatus).
|
||||||
|
#[derive(Clone, Debug, Getters)]
|
||||||
|
pub struct JobRun {
|
||||||
|
/// Devuelve la clave del trabajo.
|
||||||
|
key: CowStr,
|
||||||
|
/// Devuelve qué provocó la ejecución.
|
||||||
|
#[getters(copy)]
|
||||||
|
trigger: RunTrigger,
|
||||||
|
/// Devuelve el momento en que empezó, en UTC.
|
||||||
|
#[getters(copy)]
|
||||||
|
started_at: DateTime<Utc>,
|
||||||
|
/// Devuelve cuánto duró.
|
||||||
|
#[getters(copy)]
|
||||||
|
duration: Duration,
|
||||||
|
/// Devuelve cómo terminó.
|
||||||
|
outcome: JobOutcome,
|
||||||
|
}
|
||||||
|
|
||||||
|
impl JobRun {
|
||||||
|
pub(crate) fn new(
|
||||||
|
key: CowStr,
|
||||||
|
trigger: RunTrigger,
|
||||||
|
started_at: DateTime<Utc>,
|
||||||
|
duration: Duration,
|
||||||
|
outcome: JobOutcome,
|
||||||
|
) -> Self {
|
||||||
|
JobRun {
|
||||||
|
key,
|
||||||
|
trigger,
|
||||||
|
started_at,
|
||||||
|
duration,
|
||||||
|
outcome,
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// **< AfterJobRun >********************************************************************************
|
||||||
|
|
||||||
|
/// Tipo de función que recibe el informe de cada ejecución terminada. Ver [`AfterJobRun`].
|
||||||
|
pub type FnAfterJobRun = fn(run: &JobRun);
|
||||||
|
|
||||||
|
/// Acción que se despacha al terminar cada ejecución de cualquier trabajo, con su informe.
|
||||||
|
///
|
||||||
|
/// Sirve para vigilar los trabajos sin tocarlos: registrar las ejecuciones en una tabla, enviar
|
||||||
|
/// métricas o avisar cuando uno falla. La función es síncrona y se ejecuta en la tarea del
|
||||||
|
/// trabajo; para algo lento (p. ej. enviar un correo) lanza una tarea con `tokio::spawn()`. Un
|
||||||
|
/// `panic!` en la función se registra en las trazas y no afecta al trabajo.
|
||||||
|
///
|
||||||
|
/// # Ejemplo
|
||||||
|
///
|
||||||
|
/// ```rust,no_run
|
||||||
|
/// use pagetop::prelude::*;
|
||||||
|
/// use pagetop_cron::prelude::*;
|
||||||
|
///
|
||||||
|
/// fn alert_on_failure(run: &JobRun) {
|
||||||
|
/// if !run.outcome().is_success() {
|
||||||
|
/// trace::warn!("ALERT: job \"{}\" {}", run.key(), run.outcome());
|
||||||
|
/// }
|
||||||
|
/// }
|
||||||
|
///
|
||||||
|
/// struct Monitor;
|
||||||
|
///
|
||||||
|
/// #[async_trait]
|
||||||
|
/// impl Extension for Monitor {
|
||||||
|
/// fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||||
|
/// vec![&pagetop_cron::Cron]
|
||||||
|
/// }
|
||||||
|
///
|
||||||
|
/// fn actions(&self) -> Vec<ActionBox> {
|
||||||
|
/// actions![AfterJobRun::new(alert_on_failure)]
|
||||||
|
/// }
|
||||||
|
/// }
|
||||||
|
/// ```
|
||||||
|
pub struct AfterJobRun {
|
||||||
|
f: FnAfterJobRun,
|
||||||
|
weight: Weight,
|
||||||
|
}
|
||||||
|
|
||||||
|
impl ActionDispatcher for AfterJobRun {
|
||||||
|
fn weight(&self) -> Weight {
|
||||||
|
self.weight
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
impl AfterJobRun {
|
||||||
|
/// Registra una función que recibe el informe de cada ejecución.
|
||||||
|
pub fn new(f: FnAfterJobRun) -> Self {
|
||||||
|
AfterJobRun { f, weight: 0 }
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Opcional. Las acciones de menor peso se aplican antes. Se pueden usar valores negativos.
|
||||||
|
pub fn with_weight(mut self, value: Weight) -> Self {
|
||||||
|
self.weight = value;
|
||||||
|
self
|
||||||
|
}
|
||||||
|
|
||||||
|
pub(crate) fn dispatch(run: &JobRun) {
|
||||||
|
dispatch_actions(|action: &Self| (action.f)(run));
|
||||||
|
}
|
||||||
|
}
|
||||||
376
extensions/pagetop-cron/src/schedule.rs
Normal file
376
extensions/pagetop-cron/src/schedule.rs
Normal file
|
|
@ -0,0 +1,376 @@
|
||||||
|
use pagetop::prelude::*;
|
||||||
|
|
||||||
|
use croner::Cron;
|
||||||
|
use croner::parser::CronParser;
|
||||||
|
|
||||||
|
use crate::CronError;
|
||||||
|
|
||||||
|
use std::fmt;
|
||||||
|
use std::str::FromStr;
|
||||||
|
|
||||||
|
/// Cuándo se ejecuta un trabajo.
|
||||||
|
///
|
||||||
|
/// Hay tres formas de programar un trabajo:
|
||||||
|
///
|
||||||
|
/// | Constructor | Texto | Se ejecuta... |
|
||||||
|
/// |--------------------------------------|-----------------|-------------------------------------|
|
||||||
|
/// | [`cron()`](Self::cron) | `"*/5 * * * *"` | según una expresión cron. |
|
||||||
|
/// | [`fixed_rate()`](Self::fixed_rate) | `"@every 5m"` | 5 min tras **empezar** la anterior. |
|
||||||
|
/// | [`fixed_delay()`](Self::fixed_delay) | `"@delay 5m"` | 5 min tras **terminar** la anterior.|
|
||||||
|
///
|
||||||
|
/// Con `fixed_rate()` las ejecuciones siguen un ritmo fijo, aunque una dure más que el intervalo
|
||||||
|
/// (lo que ocurra entonces lo decide [`Overlap`](crate::Overlap)). Con `fixed_delay()` nunca se
|
||||||
|
/// solapan: es la opción natural para procesar colas o pendientes, porque cada ejecución empieza
|
||||||
|
/// con lo que dejó la anterior.
|
||||||
|
///
|
||||||
|
/// Los constructores no validan la programación: lo hace la aplicación al arrancar, que no
|
||||||
|
/// arranca si alguna no es válida e indica el trabajo afectado. Para validarla antes, por ejemplo
|
||||||
|
/// si procede de un texto que escribe alguien, usa [`parse()`](Self::parse).
|
||||||
|
///
|
||||||
|
/// # Expresiones cron
|
||||||
|
///
|
||||||
|
/// Siguen la sintaxis clásica de *cron* de cinco campos, con un sexto campo opcional al principio
|
||||||
|
/// para los segundos y un séptimo, también opcional, al final para el año:
|
||||||
|
///
|
||||||
|
/// ```text
|
||||||
|
/// ┌────────────── segundo (0-59), opcional
|
||||||
|
/// │ ┌──────────── minuto (0-59)
|
||||||
|
/// │ │ ┌────────── hora (0-23)
|
||||||
|
/// │ │ │ ┌──────── día del mes (1-31)
|
||||||
|
/// │ │ │ │ ┌────── mes (1-12 o JAN-DEC)
|
||||||
|
/// │ │ │ │ │ ┌──── día de la semana (0-7 o SUN-SAT; 0 y 7 son domingo)
|
||||||
|
/// │ │ │ │ │ │ ┌── año (p. ej. 2027), opcional
|
||||||
|
/// │ │ │ │ │ │ │
|
||||||
|
/// * * * * * * *
|
||||||
|
/// ```
|
||||||
|
///
|
||||||
|
/// Cada campo admite `*` (cualquier valor), listas (`1,15`), rangos (`1-5`) y pasos (`*/15`,
|
||||||
|
/// `0-30/10`). Además, el día del mes admite `L` (último día del mes) y `W` (día laborable más
|
||||||
|
/// cercano: `15W`), y el día de la semana admite `L` (último de ese día en el mes: `5L`, el último
|
||||||
|
/// viernes) y `#` (enésimo de ese día en el mes: `MON#1`, el primer lunes). Si se indican a la vez
|
||||||
|
/// el día del mes y el de la semana, basta con que se cumpla uno de ellos, como en *cron*.
|
||||||
|
///
|
||||||
|
/// También se aceptan los apodos `@yearly` (o `@annually`), `@monthly`, `@weekly` (el domingo),
|
||||||
|
/// `@daily` y `@hourly`, que se ejecutan al principio de cada periodo.
|
||||||
|
///
|
||||||
|
/// Algunos ejemplos:
|
||||||
|
///
|
||||||
|
/// | Expresión | Se ejecuta... |
|
||||||
|
/// |--------------------|--------------------------------------------------------|
|
||||||
|
/// | `*/10 * * * *` | cada diez minutos. |
|
||||||
|
/// | `*/30 * * * * *` | cada treinta segundos. |
|
||||||
|
/// | `30 4 * * *` | todos los días a las 4:30. |
|
||||||
|
/// | `0 8-18 * * MON-FRI` | a cada hora en punto, de 8 a 18, de lunes a viernes. |
|
||||||
|
/// | `0 0 L * *` | a medianoche del último día de cada mes. |
|
||||||
|
/// | `0 9 * * MON#1` | a las 9:00 del primer lunes de cada mes. |
|
||||||
|
///
|
||||||
|
/// Las expresiones se interpretan en la zona horaria del trabajo
|
||||||
|
/// ([`Job::with_timezone()`](crate::Job::with_timezone)) o, si no tiene, en la de la aplicación
|
||||||
|
/// (`[app].timezone`). Con el cambio de hora, una ejecución en una hora que no existe (de 2:00 a
|
||||||
|
/// 3:00 en primavera, en España) se hace al empezar la hora siguiente, y una en una hora que se
|
||||||
|
/// repite (de 2:00 a 3:00 en otoño) se hace una sola vez.
|
||||||
|
///
|
||||||
|
/// # Intervalos
|
||||||
|
///
|
||||||
|
/// En texto, un intervalo es una o varias cantidades con su unidad: `ms` (milisegundos), `s`
|
||||||
|
/// (segundos), `m` (minutos), `h` (horas) y `d` (días); p. ej. `"30s"`, `"5m"` o `"1h30m"`. No se
|
||||||
|
/// interpretan en ninguna zona horaria: un día es siempre de 24 horas.
|
||||||
|
///
|
||||||
|
/// La primera ejecución llega pasado un intervalo desde que arranca la aplicación, salvo que el
|
||||||
|
/// trabajo se ejecute también al arrancar ([`Job::with_run_on_start()`]).
|
||||||
|
///
|
||||||
|
/// Con el modo externo (`mode = "external"`) no se sabe cuándo empezó o terminó la ejecución
|
||||||
|
/// anterior, que pudo hacerla otra instancia de la aplicación. Ahí los dos intervalos se cuentan
|
||||||
|
/// igual, en múltiplos exactos desde el 1 de enero de 1970 (UTC): `"@every 10m"` se ejecuta a las
|
||||||
|
/// 10:00, 10:10, 10:20... (en UTC), y `"@delay 10m"` también.
|
||||||
|
///
|
||||||
|
/// [`Job::with_run_on_start()`]: crate::Job::with_run_on_start
|
||||||
|
///
|
||||||
|
/// # Ejemplo
|
||||||
|
///
|
||||||
|
/// Los intervalos son el [`Duration`] de las fechas de PageTop, que ya incluye su preludio.
|
||||||
|
///
|
||||||
|
/// ```rust
|
||||||
|
/// # use pagetop::prelude::*;
|
||||||
|
/// # use pagetop_cron::prelude::*;
|
||||||
|
/// let nightly = Schedule::cron("30 4 * * *");
|
||||||
|
/// let queue = Schedule::fixed_delay(Duration::seconds(10));
|
||||||
|
///
|
||||||
|
/// // Desde texto, p. ej. de la configuración, con validación.
|
||||||
|
/// assert_eq!(Schedule::parse("@delay 10s").unwrap(), queue);
|
||||||
|
/// assert!(Schedule::parse("61 * * * *").is_err());
|
||||||
|
/// assert_eq!(nightly.to_string(), "30 4 * * *");
|
||||||
|
/// ```
|
||||||
|
#[derive(Clone, Debug, Eq, PartialEq)]
|
||||||
|
pub struct Schedule(Kind);
|
||||||
|
|
||||||
|
#[derive(Clone, Debug, Eq, PartialEq)]
|
||||||
|
enum Kind {
|
||||||
|
Cron(String),
|
||||||
|
FixedRate(Duration),
|
||||||
|
FixedDelay(Duration),
|
||||||
|
}
|
||||||
|
|
||||||
|
impl Schedule {
|
||||||
|
/// Programa el trabajo con una expresión cron (ver [la sintaxis](#expresiones-cron)).
|
||||||
|
pub fn cron(expression: impl Into<String>) -> Self {
|
||||||
|
Schedule(Kind::Cron(expression.into()))
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Programa el trabajo cada `period`, contado desde que **empieza** la ejecución anterior.
|
||||||
|
pub fn fixed_rate(period: Duration) -> Self {
|
||||||
|
Schedule(Kind::FixedRate(period))
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Programa el trabajo `delay` después de que **termina** la ejecución anterior.
|
||||||
|
pub fn fixed_delay(delay: Duration) -> Self {
|
||||||
|
Schedule(Kind::FixedDelay(delay))
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Lee y valida una programación escrita como texto.
|
||||||
|
///
|
||||||
|
/// Admite una expresión cron o un apodo como `@daily` (ver [la sintaxis](#expresiones-cron)),
|
||||||
|
/// `"@every <intervalo>"` para [`fixed_rate()`](Self::fixed_rate) y `"@delay <intervalo>"`
|
||||||
|
/// para [`fixed_delay()`](Self::fixed_delay) (ver [los intervalos](#intervalos)). Es la
|
||||||
|
/// sintaxis de la clave `schedule` de los ajustes de cada trabajo, y la misma que devuelve
|
||||||
|
/// [`to_string()`](ToString::to_string).
|
||||||
|
///
|
||||||
|
/// # Ejemplo
|
||||||
|
///
|
||||||
|
/// ```rust
|
||||||
|
/// # use pagetop::prelude::*;
|
||||||
|
/// # use pagetop_cron::prelude::*;
|
||||||
|
/// let schedule = Schedule::parse("@every 1h30m").unwrap();
|
||||||
|
/// assert_eq!(schedule, Schedule::fixed_rate(Duration::minutes(90)));
|
||||||
|
/// assert_eq!(schedule.to_string(), "@every 1h30m");
|
||||||
|
/// ```
|
||||||
|
pub fn parse(text: &str) -> Result<Self, CronError> {
|
||||||
|
let text = text.trim();
|
||||||
|
let (head, rest) = text.split_once(char::is_whitespace).unwrap_or((text, ""));
|
||||||
|
let schedule = if head.eq_ignore_ascii_case("@every") {
|
||||||
|
Schedule::fixed_rate(parse_duration(rest).map_err(|reason| invalid(text, reason))?)
|
||||||
|
} else if head.eq_ignore_ascii_case("@delay") {
|
||||||
|
Schedule::fixed_delay(parse_duration(rest).map_err(|reason| invalid(text, reason))?)
|
||||||
|
} else {
|
||||||
|
Schedule::cron(text)
|
||||||
|
};
|
||||||
|
schedule.compile()?;
|
||||||
|
Ok(schedule)
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Devuelve la primera ejecución posterior a `after` según esta programación, interpretando
|
||||||
|
/// las expresiones cron en la zona horaria `tz`.
|
||||||
|
///
|
||||||
|
/// Para [`fixed_rate()`](Self::fixed_rate) y [`fixed_delay()`](Self::fixed_delay) devuelve
|
||||||
|
/// `after` más el intervalo, suponiendo que `after` es el momento en que empieza (o termina)
|
||||||
|
/// la ejecución anterior. Devuelve `None` si una expresión cron ya no se cumple nunca (p. ej.
|
||||||
|
/// la de un año ya pasado), y un error si la programación no es válida.
|
||||||
|
///
|
||||||
|
/// # Ejemplo
|
||||||
|
///
|
||||||
|
/// ```rust
|
||||||
|
/// # use pagetop::prelude::*;
|
||||||
|
/// # use pagetop_cron::prelude::*;
|
||||||
|
/// let after = "2026-01-15T00:00:00Z".parse::<DateTime<Utc>>().unwrap();
|
||||||
|
/// let next = Schedule::cron("0 9 * * *").next_after(after, Tz::Europe__Madrid).unwrap();
|
||||||
|
/// // Las 9:00 en Madrid son las 8:00 UTC en invierno.
|
||||||
|
/// assert_eq!(next.unwrap().to_rfc3339(), "2026-01-15T08:00:00+00:00");
|
||||||
|
/// ```
|
||||||
|
pub fn next_after(
|
||||||
|
&self,
|
||||||
|
after: DateTime<Utc>,
|
||||||
|
tz: Tz,
|
||||||
|
) -> Result<Option<DateTime<Utc>>, CronError> {
|
||||||
|
Ok(self.compile()?.next_after(after, tz))
|
||||||
|
}
|
||||||
|
|
||||||
|
// Valida la programación y la prepara para calcular sus ejecuciones.
|
||||||
|
pub(crate) fn compile(&self) -> Result<Trigger, CronError> {
|
||||||
|
match &self.0 {
|
||||||
|
Kind::Cron(expression) => CronParser::new()
|
||||||
|
.parse(expression)
|
||||||
|
.map(|cron| Trigger::Cron(Box::new(cron)))
|
||||||
|
.map_err(|err| invalid(expression, err.to_string())),
|
||||||
|
Kind::FixedRate(period) => Ok(Trigger::FixedRate(positive(self, *period)?)),
|
||||||
|
Kind::FixedDelay(delay) => Ok(Trigger::FixedDelay(positive(self, *delay)?)),
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
impl FromStr for Schedule {
|
||||||
|
type Err = CronError;
|
||||||
|
|
||||||
|
fn from_str(text: &str) -> Result<Self, Self::Err> {
|
||||||
|
Schedule::parse(text)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
impl fmt::Display for Schedule {
|
||||||
|
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||||||
|
match &self.0 {
|
||||||
|
Kind::Cron(expression) => f.write_str(expression),
|
||||||
|
Kind::FixedRate(period) => write!(f, "@every {}", DurationText(*period)),
|
||||||
|
Kind::FixedDelay(delay) => write!(f, "@delay {}", DurationText(*delay)),
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// **< Trigger >************************************************************************************
|
||||||
|
|
||||||
|
// Programación ya validada, lista para calcular las ejecuciones.
|
||||||
|
pub(crate) enum Trigger {
|
||||||
|
Cron(Box<Cron>),
|
||||||
|
FixedRate(Duration),
|
||||||
|
FixedDelay(Duration),
|
||||||
|
}
|
||||||
|
|
||||||
|
impl Trigger {
|
||||||
|
// Primera ejecución posterior a `after`.
|
||||||
|
pub(crate) fn next_after(&self, after: DateTime<Utc>, tz: Tz) -> Option<DateTime<Utc>> {
|
||||||
|
match self {
|
||||||
|
Trigger::Cron(cron) => cron
|
||||||
|
.find_next_occurrence(&after.with_timezone(&tz), false)
|
||||||
|
.ok()
|
||||||
|
.map(|next| next.with_timezone(&Utc)),
|
||||||
|
Trigger::FixedRate(interval) | Trigger::FixedDelay(interval) => {
|
||||||
|
after.checked_add_signed(*interval)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Primera ejecución posterior a `after` sin depender de la anterior, para el modo externo: los
|
||||||
|
// intervalos se cuentan en múltiplos exactos desde 1970 (UTC), así que todas las instancias de
|
||||||
|
// la aplicación, y cualquier proceso recién arrancado, obtienen las mismas ejecuciones.
|
||||||
|
pub(crate) fn aligned_after(&self, after: DateTime<Utc>, tz: Tz) -> Option<DateTime<Utc>> {
|
||||||
|
match self {
|
||||||
|
Trigger::Cron(_) => self.next_after(after, tz),
|
||||||
|
Trigger::FixedRate(interval) | Trigger::FixedDelay(interval) => {
|
||||||
|
let period = interval.num_milliseconds();
|
||||||
|
let next = after.timestamp_millis().div_euclid(period).checked_add(1)?;
|
||||||
|
DateTime::from_timestamp_millis(next.checked_mul(period)?)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Ejecución que sigue a la programada en `at`, ya pasada, cuando el reloj marca `now`.
|
||||||
|
//
|
||||||
|
// Con `fixed_rate()` se suma el intervalo a la ejecución programada, no al momento en que
|
||||||
|
// se despertó el planificador, para que el ritmo no se retrase un poco en cada ejecución. Si
|
||||||
|
// la siguiente también ha pasado (el equipo estuvo suspendido o el reloj saltó hacia
|
||||||
|
// delante), se omiten las perdidas y se mantiene el ritmo.
|
||||||
|
pub(crate) fn following(
|
||||||
|
&self,
|
||||||
|
at: DateTime<Utc>,
|
||||||
|
now: DateTime<Utc>,
|
||||||
|
tz: Tz,
|
||||||
|
) -> Option<DateTime<Utc>> {
|
||||||
|
match self {
|
||||||
|
Trigger::FixedRate(period) => {
|
||||||
|
let next = at.checked_add_signed(*period)?;
|
||||||
|
if next > now {
|
||||||
|
return Some(next);
|
||||||
|
}
|
||||||
|
let period = period.num_milliseconds();
|
||||||
|
let missed = (now - at).num_milliseconds() / period + 1;
|
||||||
|
at.checked_add_signed(Duration::try_milliseconds(missed.checked_mul(period)?)?)
|
||||||
|
}
|
||||||
|
_ => self.next_after(at.max(now), tz),
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Intervalo de espera tras cada ejecución, sólo con `fixed_delay()`.
|
||||||
|
pub(crate) fn delay(&self) -> Option<Duration> {
|
||||||
|
match self {
|
||||||
|
Trigger::FixedDelay(delay) => Some(*delay),
|
||||||
|
_ => None,
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// **< Funciones auxiliares >***********************************************************************
|
||||||
|
|
||||||
|
fn invalid(schedule: &str, reason: impl Into<String>) -> CronError {
|
||||||
|
CronError::InvalidSchedule {
|
||||||
|
schedule: schedule.to_owned(),
|
||||||
|
reason: reason.into(),
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// El intervalo debe ser de 1 ms a 100 años.
|
||||||
|
fn positive(schedule: &Schedule, interval: Duration) -> Result<Duration, CronError> {
|
||||||
|
if interval < Duration::milliseconds(1) || interval > Duration::days(36_500) {
|
||||||
|
return Err(invalid(
|
||||||
|
&schedule.to_string(),
|
||||||
|
"the interval must be between 1 ms and 100 years",
|
||||||
|
));
|
||||||
|
}
|
||||||
|
Ok(interval)
|
||||||
|
}
|
||||||
|
|
||||||
|
// Lee un intervalo como "30s", "5m" o "1h 30m".
|
||||||
|
fn parse_duration(text: &str) -> Result<Duration, String> {
|
||||||
|
const TOO_LARGE: &str = "interval too large";
|
||||||
|
let text = text.trim();
|
||||||
|
if text.is_empty() {
|
||||||
|
return Err("missing interval, e.g. \"5m\"".to_owned());
|
||||||
|
}
|
||||||
|
let mut total: i64 = 0;
|
||||||
|
let mut rest = text;
|
||||||
|
while !rest.is_empty() {
|
||||||
|
let digits = rest
|
||||||
|
.find(|c: char| !c.is_ascii_digit())
|
||||||
|
.unwrap_or(rest.len());
|
||||||
|
if digits == 0 {
|
||||||
|
return Err(format!("expected a number in \"{rest}\""));
|
||||||
|
}
|
||||||
|
let amount: i64 = rest[..digits].parse().map_err(|_| TOO_LARGE.to_owned())?;
|
||||||
|
rest = &rest[digits..];
|
||||||
|
let unit = rest
|
||||||
|
.find(|c: char| !c.is_ascii_alphabetic())
|
||||||
|
.unwrap_or(rest.len());
|
||||||
|
let millis = match &rest[..unit] {
|
||||||
|
"ms" => 1,
|
||||||
|
"s" => 1_000,
|
||||||
|
"m" => 60_000,
|
||||||
|
"h" => 3_600_000,
|
||||||
|
"d" => 86_400_000,
|
||||||
|
"" => return Err(format!("missing unit after {amount} (ms, s, m, h or d)")),
|
||||||
|
other => return Err(format!("unknown unit \"{other}\" (ms, s, m, h or d)")),
|
||||||
|
};
|
||||||
|
total = amount
|
||||||
|
.checked_mul(millis)
|
||||||
|
.and_then(|part| total.checked_add(part))
|
||||||
|
.ok_or_else(|| TOO_LARGE.to_owned())?;
|
||||||
|
rest = rest[unit..].trim_start();
|
||||||
|
}
|
||||||
|
Duration::try_milliseconds(total).ok_or_else(|| TOO_LARGE.to_owned())
|
||||||
|
}
|
||||||
|
|
||||||
|
// Escribe un intervalo con la sintaxis de `parse_duration()`, p. ej. "1h30m".
|
||||||
|
struct DurationText(Duration);
|
||||||
|
|
||||||
|
impl fmt::Display for DurationText {
|
||||||
|
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||||||
|
let mut millis = self.0.num_milliseconds();
|
||||||
|
if millis == 0 {
|
||||||
|
return f.write_str("0s");
|
||||||
|
}
|
||||||
|
if millis < 0 {
|
||||||
|
f.write_str("-")?;
|
||||||
|
millis = millis.saturating_abs();
|
||||||
|
}
|
||||||
|
for (unit, size) in [
|
||||||
|
("d", 86_400_000),
|
||||||
|
("h", 3_600_000),
|
||||||
|
("m", 60_000),
|
||||||
|
("s", 1_000),
|
||||||
|
("ms", 1),
|
||||||
|
] {
|
||||||
|
if millis >= size {
|
||||||
|
write!(f, "{}{unit}", millis / size)?;
|
||||||
|
millis %= size;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
Ok(())
|
||||||
|
}
|
||||||
|
}
|
||||||
956
extensions/pagetop-cron/src/scheduler.rs
Normal file
956
extensions/pagetop-cron/src/scheduler.rs
Normal file
|
|
@ -0,0 +1,956 @@
|
||||||
|
use pagetop::prelude::*;
|
||||||
|
|
||||||
|
use tokio::sync::{Notify, watch};
|
||||||
|
|
||||||
|
use crate::config::{CronMode, JobSettings, SETTINGS};
|
||||||
|
use crate::schedule::Trigger;
|
||||||
|
use crate::{AfterJobRun, CronError, CronJobs, Job, JobContext, JobOutcome, JobRun, JobStatus};
|
||||||
|
use crate::{Overlap, RunTrigger, Schedule};
|
||||||
|
|
||||||
|
use std::any::Any;
|
||||||
|
use std::collections::HashSet;
|
||||||
|
use std::panic::AssertUnwindSafe;
|
||||||
|
use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
|
||||||
|
use std::sync::{Arc, LazyLock, Mutex, MutexGuard, OnceLock, PoisonError};
|
||||||
|
use std::time::Instant;
|
||||||
|
|
||||||
|
/// Ruta de las llamadas externas que ejecutan los trabajos pendientes.
|
||||||
|
///
|
||||||
|
/// `POST /cron` con la cabecera `Authorization: Bearer {trigger_token}`, sólo para
|
||||||
|
/// `mode = "external"`.
|
||||||
|
pub const TRIGGER_PATH: &str = "/cron";
|
||||||
|
|
||||||
|
// Longitud mínima de `cron.trigger_token`.
|
||||||
|
const MIN_TOKEN_LEN: usize = 16;
|
||||||
|
|
||||||
|
// Espera máxima de una sola vez hasta la próxima ejecución. Al despertar se vuelve a calcular lo
|
||||||
|
// que falta con el reloj del sistema, así que un cambio de hora del equipo (o una suspensión, en
|
||||||
|
// la que no avanzan los temporizadores de Tokio) retrasa las ejecuciones como mucho este tiempo.
|
||||||
|
const MAX_NAP: std::time::Duration = std::time::Duration::from_secs(60);
|
||||||
|
|
||||||
|
// Trabajos declarados, construidos una sola vez al inicializar la extensión: preparar de nuevo la
|
||||||
|
// aplicación en el mismo proceso (las pruebas lo hacen) reutiliza los ya construidos.
|
||||||
|
static REGISTRY: OnceLock<Registry> = OnceLock::new();
|
||||||
|
|
||||||
|
// Evita lanzar dos veces el planificador.
|
||||||
|
static STARTED: AtomicBool = AtomicBool::new(false);
|
||||||
|
|
||||||
|
// Pasa a `true` al detener la aplicación: los bucles del planificador terminan y los trabajos lo
|
||||||
|
// ven en `JobContext::is_stopping()`.
|
||||||
|
static STOP: LazyLock<watch::Sender<bool>> = LazyLock::new(|| watch::Sender::new(false));
|
||||||
|
|
||||||
|
// Ejecuciones en curso de todos los trabajos, para esperarlas al detener la aplicación.
|
||||||
|
static ACTIVE: AtomicUsize = AtomicUsize::new(0);
|
||||||
|
static IDLE: Notify = Notify::const_new();
|
||||||
|
|
||||||
|
struct Registry {
|
||||||
|
entries: Vec<Arc<Entry>>,
|
||||||
|
}
|
||||||
|
|
||||||
|
// Un trabajo con sus ajustes ya aplicados y su estado.
|
||||||
|
struct Entry {
|
||||||
|
job: Job,
|
||||||
|
schedule: Schedule,
|
||||||
|
trigger: Trigger,
|
||||||
|
timezone: Tz,
|
||||||
|
timeout: Option<Duration>,
|
||||||
|
enabled: bool,
|
||||||
|
running: AtomicUsize,
|
||||||
|
state: Mutex<State>,
|
||||||
|
}
|
||||||
|
|
||||||
|
#[derive(AutoDefault)]
|
||||||
|
struct State {
|
||||||
|
next_run: Option<DateTime<Utc>>,
|
||||||
|
// Sólo en el modo externo: si falta la ejecución del arranque, y el último intervalo atendido.
|
||||||
|
pending_start: bool,
|
||||||
|
last_window: Option<DateTime<Utc>>,
|
||||||
|
last_run: Option<JobRun>,
|
||||||
|
runs: u64,
|
||||||
|
failures: u64,
|
||||||
|
skipped: u64,
|
||||||
|
}
|
||||||
|
|
||||||
|
// **< Construcción del registro >******************************************************************
|
||||||
|
|
||||||
|
// Recoge y valida los trabajos declarados. Un error detiene el arranque de la aplicación.
|
||||||
|
pub(crate) fn initialize() -> Result<(), CronError> {
|
||||||
|
if REGISTRY.get().is_none() {
|
||||||
|
let registry = build(CronJobs::collect(), Utc::now())?;
|
||||||
|
for entry in ®istry.entries {
|
||||||
|
trace::debug!(
|
||||||
|
"Cron job \"{}\": \"{}\" ({}){}",
|
||||||
|
entry.job.key(),
|
||||||
|
entry.schedule,
|
||||||
|
entry.timezone,
|
||||||
|
if entry.enabled { "" } else { ", disabled" }
|
||||||
|
);
|
||||||
|
}
|
||||||
|
let _ = REGISTRY.set(registry);
|
||||||
|
}
|
||||||
|
Ok(())
|
||||||
|
}
|
||||||
|
|
||||||
|
fn build(jobs: Vec<Job>, now: DateTime<Utc>) -> Result<Registry, CronError> {
|
||||||
|
check_external_settings()?;
|
||||||
|
let default_tz = Timezone::default_tz();
|
||||||
|
|
||||||
|
let mut keys = HashSet::with_capacity(jobs.len());
|
||||||
|
let mut entries = Vec::with_capacity(jobs.len());
|
||||||
|
for job in jobs {
|
||||||
|
let key = job.key().to_string();
|
||||||
|
if !is_valid_key(&key) {
|
||||||
|
return Err(CronError::InvalidKey(key));
|
||||||
|
}
|
||||||
|
let entry = Entry::new(job, SETTINGS.jobs.get(&key), default_tz, now).map_err(|err| {
|
||||||
|
CronError::InvalidJob {
|
||||||
|
key: key.clone(),
|
||||||
|
source: Box::new(err),
|
||||||
|
}
|
||||||
|
})?;
|
||||||
|
if !keys.insert(key.clone()) {
|
||||||
|
return Err(CronError::DuplicateJob(key));
|
||||||
|
}
|
||||||
|
entries.push(Arc::new(entry));
|
||||||
|
}
|
||||||
|
for key in SETTINGS.jobs.keys() {
|
||||||
|
if !keys.contains(key) {
|
||||||
|
trace::warn!("Unknown cron job \"{key}\" in [cron.jobs], ignored. Check settings");
|
||||||
|
}
|
||||||
|
}
|
||||||
|
entries.sort_by(|a, b| a.job.key().cmp(b.job.key()));
|
||||||
|
Ok(Registry { entries })
|
||||||
|
}
|
||||||
|
|
||||||
|
fn is_valid_key(key: &str) -> bool {
|
||||||
|
key.starts_with(|c: char| c.is_ascii_lowercase() || c.is_ascii_digit())
|
||||||
|
&& key
|
||||||
|
.chars()
|
||||||
|
.all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || matches!(c, '_' | '-' | '.'))
|
||||||
|
}
|
||||||
|
|
||||||
|
// El modo externo necesita una clave larga y que se pueda escribir tal cual en la cabecera, y un
|
||||||
|
// intervalo entre llamadas válido.
|
||||||
|
fn check_external_settings() -> Result<(), CronError> {
|
||||||
|
if SETTINGS.mode != CronMode::External {
|
||||||
|
return Ok(());
|
||||||
|
}
|
||||||
|
let valid = trigger_token().is_some_and(|token| {
|
||||||
|
token.len() >= MIN_TOKEN_LEN
|
||||||
|
&& token
|
||||||
|
.chars()
|
||||||
|
.all(|c| c.is_ascii_alphanumeric() || matches!(c, '-' | '_'))
|
||||||
|
});
|
||||||
|
if !valid {
|
||||||
|
return Err(CronError::InvalidSetting {
|
||||||
|
key: "cron.trigger_token",
|
||||||
|
reason: format!(
|
||||||
|
"mode \"external\" needs a secret token of at least {MIN_TOKEN_LEN} letters, \
|
||||||
|
digits, '-' or '_'"
|
||||||
|
),
|
||||||
|
});
|
||||||
|
}
|
||||||
|
if trigger_interval().is_none() {
|
||||||
|
return Err(CronError::InvalidSetting {
|
||||||
|
key: "cron.trigger_interval_secs",
|
||||||
|
reason: "must be between 1 second and 100 years".to_owned(),
|
||||||
|
});
|
||||||
|
}
|
||||||
|
Ok(())
|
||||||
|
}
|
||||||
|
|
||||||
|
fn trigger_token() -> Option<&'static str> {
|
||||||
|
SETTINGS.trigger_token.as_deref().and_then(util::non_blank)
|
||||||
|
}
|
||||||
|
|
||||||
|
fn trigger_interval() -> Option<Duration> {
|
||||||
|
let secs = i64::try_from(SETTINGS.trigger_interval_secs).ok()?;
|
||||||
|
Duration::try_seconds(secs)
|
||||||
|
.filter(|interval| *interval >= Duration::seconds(1) && *interval <= Duration::days(36_500))
|
||||||
|
}
|
||||||
|
|
||||||
|
// Final del último intervalo completo de llamadas externas, en múltiplos exactos de `interval`
|
||||||
|
// desde 1970 (UTC): una llamada a las 4:30:20, con intervalos de un minuto, atiende el que va de
|
||||||
|
// las 4:29:00 a las 4:30:00, y lo mismo haría con cualquier otra instancia de la aplicación.
|
||||||
|
fn window_end(now: DateTime<Utc>, interval: Duration) -> Option<DateTime<Utc>> {
|
||||||
|
let size = interval.num_milliseconds();
|
||||||
|
DateTime::from_timestamp_millis(now.timestamp_millis().div_euclid(size).checked_mul(size)?)
|
||||||
|
}
|
||||||
|
|
||||||
|
// Compara la clave recibida con la configurada en un tiempo que no depende de dónde difieren, para
|
||||||
|
// no dar pistas sobre la clave a quien mida los tiempos de respuesta.
|
||||||
|
pub(crate) fn token_matches(given: &str) -> bool {
|
||||||
|
let Some(expected) = trigger_token() else {
|
||||||
|
return false;
|
||||||
|
};
|
||||||
|
let (given, expected) = (given.as_bytes(), expected.as_bytes());
|
||||||
|
given.len() == expected.len()
|
||||||
|
&& given
|
||||||
|
.iter()
|
||||||
|
.zip(expected)
|
||||||
|
.fold(0, |diff, (a, b)| diff | (a ^ b))
|
||||||
|
== 0
|
||||||
|
}
|
||||||
|
|
||||||
|
impl Entry {
|
||||||
|
fn new(
|
||||||
|
job: Job,
|
||||||
|
settings: Option<&JobSettings>,
|
||||||
|
default_tz: Tz,
|
||||||
|
now: DateTime<Utc>,
|
||||||
|
) -> Result<Self, CronError> {
|
||||||
|
let schedule = match settings
|
||||||
|
.and_then(|s| s.schedule.as_deref())
|
||||||
|
.and_then(util::non_blank)
|
||||||
|
{
|
||||||
|
Some(text) => Schedule::parse(text)?,
|
||||||
|
None => job.schedule().clone(),
|
||||||
|
};
|
||||||
|
let trigger = schedule.compile()?;
|
||||||
|
let timeout = match settings.and_then(|s| s.timeout_secs) {
|
||||||
|
Some(0) => None,
|
||||||
|
Some(secs) => Some(
|
||||||
|
i64::try_from(secs)
|
||||||
|
.ok()
|
||||||
|
.and_then(Duration::try_seconds)
|
||||||
|
.ok_or_else(|| CronError::InvalidSetting {
|
||||||
|
key: "cron.jobs.timeout_secs",
|
||||||
|
reason: "too large".to_owned(),
|
||||||
|
})?,
|
||||||
|
),
|
||||||
|
None => job.timeout(),
|
||||||
|
};
|
||||||
|
if timeout.is_some_and(|timeout| timeout <= Duration::zero()) {
|
||||||
|
return Err(CronError::InvalidSetting {
|
||||||
|
key: "timeout",
|
||||||
|
reason: "must be greater than zero".to_owned(),
|
||||||
|
});
|
||||||
|
}
|
||||||
|
let enabled = settings.is_none_or(|s| s.enabled);
|
||||||
|
let timezone = job.timezone().unwrap_or(default_tz);
|
||||||
|
|
||||||
|
// Con el modo externo, la próxima ejecución se conoce desde el arranque; la del arranque,
|
||||||
|
// si la hay, la hace la primera llamada.
|
||||||
|
let external = enabled && SETTINGS.mode == CronMode::External;
|
||||||
|
let pending_start = external && job.run_on_start();
|
||||||
|
let next_run = match (external, pending_start) {
|
||||||
|
(true, true) => Some(now),
|
||||||
|
(true, false) => trigger.aligned_after(now, timezone),
|
||||||
|
(false, _) => None,
|
||||||
|
};
|
||||||
|
|
||||||
|
Ok(Entry {
|
||||||
|
job,
|
||||||
|
schedule,
|
||||||
|
trigger,
|
||||||
|
timezone,
|
||||||
|
timeout,
|
||||||
|
enabled,
|
||||||
|
running: AtomicUsize::new(0),
|
||||||
|
state: Mutex::new(State {
|
||||||
|
next_run,
|
||||||
|
pending_start,
|
||||||
|
..State::default()
|
||||||
|
}),
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
|
// Decide si una llamada externa que atiende el intervalo que termina en `end` ejecuta el
|
||||||
|
// trabajo, y con qué causa y hora programada. Se decide y se anota en un solo bloqueo, para que
|
||||||
|
// dos llamadas simultáneas no lancen la misma ejecución. Un intervalo ya atendido, o anterior
|
||||||
|
// (el reloj del sistema retrocedió), no vuelve a ejecutar nada.
|
||||||
|
fn take_due(
|
||||||
|
&self,
|
||||||
|
end: DateTime<Utc>,
|
||||||
|
interval: Duration,
|
||||||
|
) -> Option<(RunTrigger, Option<DateTime<Utc>>)> {
|
||||||
|
let mut state = self.state();
|
||||||
|
let startup = std::mem::take(&mut state.pending_start);
|
||||||
|
let mut at = None;
|
||||||
|
if state.last_window.is_none_or(|last| last < end) {
|
||||||
|
state.last_window = Some(end);
|
||||||
|
at = self
|
||||||
|
.trigger
|
||||||
|
.aligned_after(end - interval, self.timezone)
|
||||||
|
.filter(|at| *at <= end);
|
||||||
|
state.next_run = self.trigger.aligned_after(end, self.timezone);
|
||||||
|
}
|
||||||
|
match (at, startup) {
|
||||||
|
(Some(at), _) => Some((RunTrigger::External, Some(at))),
|
||||||
|
(None, true) => Some((RunTrigger::Startup, None)),
|
||||||
|
(None, false) => None,
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Un `panic!` sólo puede ocurrir fuera de la sección protegida (se ejecutan en otra tarea),
|
||||||
|
// así que el estado sigue siendo coherente aunque el `Mutex` quede envenenado.
|
||||||
|
fn state(&self) -> MutexGuard<'_, State> {
|
||||||
|
self.state.lock().unwrap_or_else(PoisonError::into_inner)
|
||||||
|
}
|
||||||
|
|
||||||
|
fn set_next_run(&self, at: Option<DateTime<Utc>>) {
|
||||||
|
self.state().next_run = at;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Reserva una ejecución, salvo que el trabajo no admita ejecuciones simultáneas y ya haya una.
|
||||||
|
fn try_begin(self: &Arc<Self>) -> Option<RunGuard> {
|
||||||
|
let began = match self.job.overlap() {
|
||||||
|
Overlap::Skip => self
|
||||||
|
.running
|
||||||
|
.compare_exchange(0, 1, Ordering::SeqCst, Ordering::SeqCst)
|
||||||
|
.is_ok(),
|
||||||
|
Overlap::Allow => {
|
||||||
|
self.running.fetch_add(1, Ordering::SeqCst);
|
||||||
|
true
|
||||||
|
}
|
||||||
|
};
|
||||||
|
if !began {
|
||||||
|
return None;
|
||||||
|
}
|
||||||
|
ACTIVE.fetch_add(1, Ordering::SeqCst);
|
||||||
|
Some(RunGuard(Arc::clone(self)))
|
||||||
|
}
|
||||||
|
|
||||||
|
fn skip(&self) {
|
||||||
|
self.state().skipped += 1;
|
||||||
|
trace::warn!(
|
||||||
|
"Cron job \"{}\" skipped: the previous run has not finished",
|
||||||
|
self.job.key()
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
fn record(&self, run: &JobRun) {
|
||||||
|
let mut state = self.state();
|
||||||
|
state.runs += 1;
|
||||||
|
if !run.outcome().is_success() {
|
||||||
|
state.failures += 1;
|
||||||
|
}
|
||||||
|
state.last_run = Some(run.clone());
|
||||||
|
}
|
||||||
|
|
||||||
|
fn status(&self) -> JobStatus {
|
||||||
|
let state = self.state();
|
||||||
|
JobStatus {
|
||||||
|
key: self.job.key().clone(),
|
||||||
|
title: self.job.title().clone(),
|
||||||
|
schedule: self.schedule.clone(),
|
||||||
|
timezone: self.timezone,
|
||||||
|
enabled: self.enabled,
|
||||||
|
running: self.running.load(Ordering::SeqCst),
|
||||||
|
next_run: state.next_run,
|
||||||
|
last_run: state.last_run.clone(),
|
||||||
|
runs: state.runs,
|
||||||
|
failures: state.failures,
|
||||||
|
skipped: state.skipped,
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Ejecución reservada; al soltarla se libera la reserva.
|
||||||
|
struct RunGuard(Arc<Entry>);
|
||||||
|
|
||||||
|
impl Drop for RunGuard {
|
||||||
|
fn drop(&mut self) {
|
||||||
|
self.0.running.fetch_sub(1, Ordering::SeqCst);
|
||||||
|
if ACTIVE.fetch_sub(1, Ordering::SeqCst) == 1 {
|
||||||
|
IDLE.notify_waiters();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// **< API pública >********************************************************************************
|
||||||
|
|
||||||
|
/// Devuelve el estado de todos los trabajos declarados, ordenados por su clave.
|
||||||
|
///
|
||||||
|
/// Vacío si la aplicación aún no se ha preparado.
|
||||||
|
pub fn jobs() -> Vec<JobStatus> {
|
||||||
|
REGISTRY
|
||||||
|
.get()
|
||||||
|
.map(|registry| registry.entries.iter().map(|e| e.status()).collect())
|
||||||
|
.unwrap_or_default()
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Devuelve el estado de un trabajo por su clave, o `None` si no existe.
|
||||||
|
pub fn job(key: impl AsRef<str>) -> Option<JobStatus> {
|
||||||
|
find(key.as_ref()).ok().map(|entry| entry.status())
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Ejecuta un trabajo ahora mismo y espera a que termine.
|
||||||
|
///
|
||||||
|
/// Funciona con cualquier modo de la sección `[cron]` y aunque la configuración desactive el
|
||||||
|
/// trabajo, y también en las pruebas, donde el planificador no se pone en marcha. Respeta el tiempo
|
||||||
|
/// máximo del trabajo, registra la ejecución en su estado y despacha [`AfterJobRun`], como
|
||||||
|
/// cualquier otra ejecución. No cambia su próxima ejecución programada.
|
||||||
|
///
|
||||||
|
/// Devuelve el informe de la ejecución, también si el trabajo falla: el error sólo indica que no se
|
||||||
|
/// ha podido ejecutar, porque no existe ([`CronError::UnknownJob`]), porque ya se está ejecutando y
|
||||||
|
/// no admite ejecuciones simultáneas ([`CronError::AlreadyRunning`]) o porque la aplicación aún no
|
||||||
|
/// se ha preparado ([`CronError::NotInitialized`]).
|
||||||
|
///
|
||||||
|
/// # Ejemplo
|
||||||
|
///
|
||||||
|
/// ```rust,no_run
|
||||||
|
/// # use pagetop::prelude::*;
|
||||||
|
/// # use pagetop_cron::prelude::*;
|
||||||
|
/// # async fn example() -> Result<(), CronError> {
|
||||||
|
/// let run = pagetop_cron::run_now("shop.cleanup").await?;
|
||||||
|
/// assert!(run.outcome().is_success());
|
||||||
|
/// # Ok(())
|
||||||
|
/// # }
|
||||||
|
/// ```
|
||||||
|
pub async fn run_now(key: impl AsRef<str>) -> Result<JobRun, CronError> {
|
||||||
|
let key = key.as_ref();
|
||||||
|
let entry = find(key)?;
|
||||||
|
let guard = entry
|
||||||
|
.try_begin()
|
||||||
|
.ok_or_else(|| CronError::AlreadyRunning(key.to_owned()))?;
|
||||||
|
// En su propia tarea: si se abandona la espera (p. ej. se cierra la conexión de la petición
|
||||||
|
// que la pidió), la ejecución sigue con su tiempo máximo y su reserva, y se registra igual.
|
||||||
|
match tokio::spawn(execute(guard, RunTrigger::Manual, None)).await {
|
||||||
|
Ok(run) => Ok(run),
|
||||||
|
Err(err) => std::panic::resume_unwind(err.into_panic()),
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Ejecuta los trabajos programados en el último intervalo de llamadas externas.
|
||||||
|
///
|
||||||
|
/// Espera a que terminen y devuelve el informe de cada ejecución. Es lo que hace la ruta
|
||||||
|
/// `POST /cron` con `mode = "external"`, disponible por si la aplicación quiere ofrecer otra forma
|
||||||
|
/// de llamarlo (p. ej. una orden de su propia línea de comandos). Sólo funciona en ese modo: en los
|
||||||
|
/// demás no hace nada y devuelve `0`, porque las ejecuciones las decide el planificador interno o
|
||||||
|
/// nadie.
|
||||||
|
///
|
||||||
|
/// Cada llamada atiende el último intervalo completo de `cron.trigger_interval_secs` (un minuto
|
||||||
|
/// por defecto), contado en múltiplos exactos desde 1970 (UTC), y ejecuta una vez cada trabajo
|
||||||
|
/// programado en él; una llamada a las 4:30:20 ejecuta lo programado de las 4:29:00 (excluido) a
|
||||||
|
/// las 4:30:00. No depende de lo que recuerde cada proceso: con varias instancias tras un
|
||||||
|
/// balanceador, cada trabajo se ejecuta una sola vez aunque cada llamada llegue a una instancia
|
||||||
|
/// distinta, y una instancia arrancada por la propia llamada ejecuta igualmente lo que toca. A
|
||||||
|
/// cambio, el programa externo debe llamar una vez, y sólo una, en cada intervalo: si falta una
|
||||||
|
/// llamada se pierden sus ejecuciones, y si sobra, dos instancias distintas pueden repetirlas.
|
||||||
|
///
|
||||||
|
/// La precisión es la del intervalo: con uno de un minuto, un trabajo de cada diez segundos se
|
||||||
|
/// ejecuta una vez por minuto. Los trabajos con
|
||||||
|
/// [`with_run_on_start()`](crate::Job::with_run_on_start) se ejecutan además en la primera llamada
|
||||||
|
/// que recibe cada proceso.
|
||||||
|
///
|
||||||
|
/// Los trabajos se ejecutan a la vez, cada uno en su propia tarea, y la función espera a que
|
||||||
|
/// terminen todos. Así una plataforma que sólo da CPU mientras se atiende una petición la mantiene
|
||||||
|
/// hasta el final. Si se abandona la espera (p. ej. el programa externo cierra la conexión), los
|
||||||
|
/// trabajos siguen igualmente hasta terminar o agotar su tiempo máximo.
|
||||||
|
pub async fn run_due() -> Vec<JobRun> {
|
||||||
|
if SETTINGS.mode != CronMode::External {
|
||||||
|
trace::warn!("Cron run_due() ignored: [cron].mode is not \"external\"");
|
||||||
|
return Vec::new();
|
||||||
|
}
|
||||||
|
let (Some(registry), Some(interval)) = (REGISTRY.get(), trigger_interval()) else {
|
||||||
|
return Vec::new();
|
||||||
|
};
|
||||||
|
let Some(end) = window_end(Utc::now(), interval) else {
|
||||||
|
return Vec::new();
|
||||||
|
};
|
||||||
|
let mut tasks = Vec::new();
|
||||||
|
for entry in registry.entries.iter().filter(|e| e.enabled) {
|
||||||
|
let Some((trigger, at)) = entry.take_due(end, interval) else {
|
||||||
|
continue;
|
||||||
|
};
|
||||||
|
let Some(guard) = entry.try_begin() else {
|
||||||
|
entry.skip();
|
||||||
|
continue;
|
||||||
|
};
|
||||||
|
tasks.push(tokio::spawn(execute(guard, trigger, at)));
|
||||||
|
}
|
||||||
|
let mut runs = Vec::with_capacity(tasks.len());
|
||||||
|
for task in tasks {
|
||||||
|
// `execute()` ya aísla los `panic!` del trabajo; sólo falla si se detiene el *runtime*.
|
||||||
|
if let Ok(run) = task.await {
|
||||||
|
runs.push(run);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
runs
|
||||||
|
}
|
||||||
|
|
||||||
|
fn find(key: &str) -> Result<&'static Arc<Entry>, CronError> {
|
||||||
|
REGISTRY
|
||||||
|
.get()
|
||||||
|
.ok_or(CronError::NotInitialized)?
|
||||||
|
.entries
|
||||||
|
.iter()
|
||||||
|
.find(|entry| entry.job.key() == key)
|
||||||
|
.ok_or_else(|| CronError::UnknownJob(key.to_owned()))
|
||||||
|
}
|
||||||
|
|
||||||
|
// **< Planificador >*******************************************************************************
|
||||||
|
|
||||||
|
// Pone en marcha el planificador según el modo configurado. Sólo una vez por proceso.
|
||||||
|
pub(crate) fn start() {
|
||||||
|
let Some(registry) = REGISTRY.get() else {
|
||||||
|
return;
|
||||||
|
};
|
||||||
|
if STARTED.swap(true, Ordering::SeqCst) {
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
let total = registry.entries.len();
|
||||||
|
let enabled = registry.entries.iter().filter(|e| e.enabled).count();
|
||||||
|
match SETTINGS.mode {
|
||||||
|
CronMode::Internal => {
|
||||||
|
for entry in registry.entries.iter().filter(|e| e.enabled) {
|
||||||
|
tokio::spawn(job_loop(Arc::clone(entry)));
|
||||||
|
}
|
||||||
|
trace::info!("Cron scheduler started with {enabled} of {total} jobs");
|
||||||
|
}
|
||||||
|
CronMode::External => trace::info!(
|
||||||
|
"Cron jobs ({enabled} of {total}) run on authorized calls to POST {TRIGGER_PATH}"
|
||||||
|
),
|
||||||
|
CronMode::Off => {
|
||||||
|
trace::info!("Cron jobs ({total}) only run on demand: [cron].mode is \"off\"");
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Ejecuta un trabajo según su programación hasta que se detiene la aplicación.
|
||||||
|
async fn job_loop(entry: Arc<Entry>) {
|
||||||
|
let mut stop = STOP.subscribe();
|
||||||
|
if entry.job.run_on_start() {
|
||||||
|
launch(&entry, RunTrigger::Startup, None).await;
|
||||||
|
}
|
||||||
|
let mut next = entry.trigger.next_after(Utc::now(), entry.timezone);
|
||||||
|
while let Some(at) = next {
|
||||||
|
entry.set_next_run(Some(at));
|
||||||
|
if !sleep_until(at, &mut stop).await {
|
||||||
|
break;
|
||||||
|
}
|
||||||
|
launch(&entry, RunTrigger::Schedule, Some(at)).await;
|
||||||
|
next = entry.trigger.following(at, Utc::now(), entry.timezone);
|
||||||
|
}
|
||||||
|
if next.is_none() {
|
||||||
|
trace::info!(
|
||||||
|
"Cron job \"{}\" has no more runs scheduled",
|
||||||
|
entry.job.key()
|
||||||
|
);
|
||||||
|
}
|
||||||
|
entry.set_next_run(None);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Lanza una ejecución. Con `fixed_delay()` espera a que termine, porque la siguiente se cuenta
|
||||||
|
// desde entonces; con el resto, la ejecución sigue en su propia tarea.
|
||||||
|
async fn launch(entry: &Arc<Entry>, trigger: RunTrigger, at: Option<DateTime<Utc>>) {
|
||||||
|
let Some(guard) = entry.try_begin() else {
|
||||||
|
entry.skip();
|
||||||
|
return;
|
||||||
|
};
|
||||||
|
if entry.trigger.delay().is_some() {
|
||||||
|
execute(guard, trigger, at).await;
|
||||||
|
} else {
|
||||||
|
tokio::spawn(execute(guard, trigger, at));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Espera hasta `at` según el reloj del sistema. Devuelve `false` si la aplicación se detiene antes.
|
||||||
|
async fn sleep_until(at: DateTime<Utc>, stop: &mut watch::Receiver<bool>) -> bool {
|
||||||
|
loop {
|
||||||
|
if *stop.borrow() {
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
let remaining = match (at - Utc::now()).to_std() {
|
||||||
|
Ok(remaining) if !remaining.is_zero() => remaining,
|
||||||
|
_ => return true,
|
||||||
|
};
|
||||||
|
tokio::select! {
|
||||||
|
() = tokio::time::sleep(remaining.min(MAX_NAP)) => {}
|
||||||
|
changed = stop.changed() => {
|
||||||
|
if changed.is_err() {
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Ejecuta el trabajo en una tarea propia, que aísla sus `panic!` y permite cancelarlo si supera su
|
||||||
|
// tiempo máximo, y registra el resultado.
|
||||||
|
async fn execute(guard: RunGuard, trigger: RunTrigger, at: Option<DateTime<Utc>>) -> JobRun {
|
||||||
|
let entry = Arc::clone(&guard.0);
|
||||||
|
let key = entry.job.key().clone();
|
||||||
|
trace::debug!("Cron job \"{key}\" started ({})", trigger.as_str());
|
||||||
|
|
||||||
|
let cx = JobContext::new(key.clone(), trigger, at, STOP.subscribe());
|
||||||
|
let run = entry.job.runner();
|
||||||
|
let started_at = Utc::now();
|
||||||
|
let clock = Instant::now();
|
||||||
|
let mut task = tokio::spawn(async move { run(cx).await });
|
||||||
|
let joined = match entry.timeout.and_then(|timeout| timeout.to_std().ok()) {
|
||||||
|
Some(limit) => match tokio::time::timeout(limit, &mut task).await {
|
||||||
|
Ok(joined) => Some(joined),
|
||||||
|
Err(_) => {
|
||||||
|
task.abort();
|
||||||
|
None
|
||||||
|
}
|
||||||
|
},
|
||||||
|
None => Some((&mut task).await),
|
||||||
|
};
|
||||||
|
let timed_out = joined.is_none();
|
||||||
|
let outcome = match joined {
|
||||||
|
None => JobOutcome::TimedOut,
|
||||||
|
Some(Ok(Ok(()))) => JobOutcome::Succeeded,
|
||||||
|
Some(Ok(Err(err))) => JobOutcome::Failed(error_chain(err.as_ref())),
|
||||||
|
Some(Err(err)) if err.is_panic() => JobOutcome::Panicked(panic_message(err.into_panic())),
|
||||||
|
Some(Err(_)) => JobOutcome::Failed("cancelled".to_owned()),
|
||||||
|
};
|
||||||
|
let duration = Duration::from_std(clock.elapsed()).unwrap_or_default();
|
||||||
|
|
||||||
|
let run = JobRun::new(key, trigger, started_at, duration, outcome);
|
||||||
|
entry.record(&run);
|
||||||
|
match run.outcome() {
|
||||||
|
JobOutcome::Succeeded => trace::debug!(
|
||||||
|
"Cron job \"{}\" succeeded in {} ms",
|
||||||
|
run.key(),
|
||||||
|
duration.num_milliseconds()
|
||||||
|
),
|
||||||
|
outcome => trace::error!(
|
||||||
|
"Cron job \"{}\" {outcome} after {} ms",
|
||||||
|
run.key(),
|
||||||
|
duration.num_milliseconds()
|
||||||
|
),
|
||||||
|
}
|
||||||
|
// Un `panic!` en una acción no debe detener el bucle del trabajo ni su reprogramación.
|
||||||
|
if let Err(payload) = std::panic::catch_unwind(AssertUnwindSafe(|| AfterJobRun::dispatch(&run)))
|
||||||
|
{
|
||||||
|
trace::error!(
|
||||||
|
"AfterJobRun action panicked for cron job \"{}\": {}",
|
||||||
|
run.key(),
|
||||||
|
panic_message(payload)
|
||||||
|
);
|
||||||
|
}
|
||||||
|
if timed_out {
|
||||||
|
// Cancelar sólo surte efecto en el siguiente `.await` del trabajo: uno que no llega a
|
||||||
|
// ninguno (un cálculo largo, una llamada bloqueante) sigue en marcha. Mientras siga, la
|
||||||
|
// ejecución cuenta como en curso, para no solaparla con la siguiente ni dejar de esperarla
|
||||||
|
// al detener la aplicación.
|
||||||
|
tokio::spawn(async move {
|
||||||
|
let _ = task.await;
|
||||||
|
drop(guard);
|
||||||
|
});
|
||||||
|
} else {
|
||||||
|
drop(guard);
|
||||||
|
}
|
||||||
|
run
|
||||||
|
}
|
||||||
|
|
||||||
|
// Mensaje del error con el de sus causas. Muchos errores terminan ya con el texto de su causa, así
|
||||||
|
// que se omite cada causa con la que ya termina el mensaje.
|
||||||
|
fn error_chain(err: &(dyn std::error::Error + 'static)) -> String {
|
||||||
|
let mut message = err.to_string();
|
||||||
|
let mut source = err.source();
|
||||||
|
while let Some(cause) = source {
|
||||||
|
let cause_text = cause.to_string();
|
||||||
|
if !message.ends_with(&cause_text) {
|
||||||
|
message.push_str(": ");
|
||||||
|
message.push_str(&cause_text);
|
||||||
|
}
|
||||||
|
source = cause.source();
|
||||||
|
}
|
||||||
|
message
|
||||||
|
}
|
||||||
|
|
||||||
|
// Se desreferencia la caja para que `downcast_ref()` sea el de `dyn Any` y no el de `AnyCast`, que
|
||||||
|
// se aplicaría a la propia `Box`.
|
||||||
|
fn panic_message(payload: Box<dyn Any + Send>) -> String {
|
||||||
|
match payload.downcast::<String>() {
|
||||||
|
Ok(message) => *message,
|
||||||
|
Err(payload) => (*payload).downcast_ref::<&str>().map_or_else(
|
||||||
|
|| "unknown panic".to_owned(),
|
||||||
|
|message| (*message).to_owned(),
|
||||||
|
),
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Avisa a los trabajos de que la aplicación se detiene y espera, con un tiempo máximo, a que
|
||||||
|
// terminen las ejecuciones en curso.
|
||||||
|
pub(crate) async fn shutdown() {
|
||||||
|
STOP.send_replace(true);
|
||||||
|
let active = ACTIVE.load(Ordering::SeqCst);
|
||||||
|
if active == 0 {
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
let limit = SETTINGS.shutdown_timeout_secs;
|
||||||
|
trace::info!("Waiting up to {limit} s for {active} running cron jobs to finish");
|
||||||
|
let idle = async {
|
||||||
|
loop {
|
||||||
|
let notified = IDLE.notified();
|
||||||
|
if ACTIVE.load(Ordering::SeqCst) == 0 {
|
||||||
|
break;
|
||||||
|
}
|
||||||
|
notified.await;
|
||||||
|
}
|
||||||
|
};
|
||||||
|
if tokio::time::timeout(std::time::Duration::from_secs(limit), idle)
|
||||||
|
.await
|
||||||
|
.is_err()
|
||||||
|
{
|
||||||
|
let running: Vec<String> = jobs()
|
||||||
|
.into_iter()
|
||||||
|
.filter(|job| job.running() > 0)
|
||||||
|
.map(|job| job.key().to_string())
|
||||||
|
.collect();
|
||||||
|
trace::warn!(
|
||||||
|
"Cron jobs still running after {limit} s, stopping anyway: {}",
|
||||||
|
running.join(", ")
|
||||||
|
);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
#[cfg(test)]
|
||||||
|
mod tests {
|
||||||
|
use super::*;
|
||||||
|
|
||||||
|
// Settings come from this crate's `config/common.toml` (external mode, Madrid timezone).
|
||||||
|
fn load_settings() {
|
||||||
|
SETTINGS.load().unwrap();
|
||||||
|
}
|
||||||
|
|
||||||
|
async fn noop(_cx: JobContext) -> crate::JobResult {
|
||||||
|
Ok(())
|
||||||
|
}
|
||||||
|
|
||||||
|
fn job(key: &'static str, schedule: &str) -> Job {
|
||||||
|
Job::new(key, Schedule::cron(schedule), noop)
|
||||||
|
}
|
||||||
|
|
||||||
|
fn at(text: &str) -> DateTime<Utc> {
|
||||||
|
text.parse().unwrap()
|
||||||
|
}
|
||||||
|
|
||||||
|
fn build_error(jobs: Vec<Job>) -> CronError {
|
||||||
|
load_settings();
|
||||||
|
match build(jobs, Utc::now()) {
|
||||||
|
Ok(_) => panic!("build should fail"),
|
||||||
|
Err(err) => err,
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
#[pagetop::test]
|
||||||
|
async fn keys_must_be_lowercase_and_simple() {
|
||||||
|
for key in ["shop.cleanup", "mail_queue", "a-b.c_d", "0job"] {
|
||||||
|
assert!(is_valid_key(key), "{key}");
|
||||||
|
}
|
||||||
|
for key in [
|
||||||
|
"",
|
||||||
|
"Shop.cleanup",
|
||||||
|
".hidden",
|
||||||
|
"-x",
|
||||||
|
"with space",
|
||||||
|
"a/b",
|
||||||
|
"a:b",
|
||||||
|
] {
|
||||||
|
assert!(!is_valid_key(key), "{key}");
|
||||||
|
}
|
||||||
|
assert!(matches!(
|
||||||
|
build_error(vec![job("Bad", "* * * * *")]),
|
||||||
|
CronError::InvalidKey(key) if key == "Bad"
|
||||||
|
));
|
||||||
|
}
|
||||||
|
|
||||||
|
#[pagetop::test]
|
||||||
|
async fn duplicated_keys_stop_the_build() {
|
||||||
|
let err = build_error(vec![job("a.job", "* * * * *"), job("a.job", "@daily")]);
|
||||||
|
assert!(matches!(err, CronError::DuplicateJob(key) if key == "a.job"));
|
||||||
|
}
|
||||||
|
|
||||||
|
#[pagetop::test]
|
||||||
|
async fn invalid_schedules_and_timeouts_name_the_job() {
|
||||||
|
let err = build_error(vec![job("a.job", "61 * * * *")]);
|
||||||
|
assert_eq!(err.to_string(), "invalid job \"a.job\"");
|
||||||
|
let CronError::InvalidJob { source, .. } = err else {
|
||||||
|
panic!("unexpected error");
|
||||||
|
};
|
||||||
|
assert!(matches!(*source, CronError::InvalidSchedule { .. }));
|
||||||
|
|
||||||
|
let err = build_error(vec![job("a.job", "@daily").with_timeout(Duration::zero())]);
|
||||||
|
assert!(matches!(err, CronError::InvalidJob { .. }));
|
||||||
|
}
|
||||||
|
|
||||||
|
#[pagetop::test]
|
||||||
|
async fn settings_override_the_declared_job() {
|
||||||
|
load_settings();
|
||||||
|
let now = at("2026-01-15T10:00:00Z");
|
||||||
|
let registry = build(
|
||||||
|
vec![
|
||||||
|
job("test.overridden", "0 * * * *").with_timeout(Duration::minutes(1)),
|
||||||
|
job("test.disabled", "* * * * *"),
|
||||||
|
job("test.plain", "0 9 * * *"),
|
||||||
|
job("test.startup", "@daily").with_run_on_start(),
|
||||||
|
],
|
||||||
|
now,
|
||||||
|
)
|
||||||
|
.unwrap();
|
||||||
|
let entry = |key: &str| {
|
||||||
|
registry
|
||||||
|
.entries
|
||||||
|
.iter()
|
||||||
|
.find(|e| e.job.key() == key)
|
||||||
|
.unwrap()
|
||||||
|
};
|
||||||
|
|
||||||
|
let overridden = entry("test.overridden");
|
||||||
|
assert_eq!(overridden.schedule.to_string(), "@delay 1m30s");
|
||||||
|
assert_eq!(overridden.timeout, None);
|
||||||
|
// External mode: the first run is computed from startup.
|
||||||
|
assert_eq!(
|
||||||
|
overridden.state().next_run,
|
||||||
|
Some(at("2026-01-15T10:01:30Z"))
|
||||||
|
);
|
||||||
|
|
||||||
|
let disabled = entry("test.disabled");
|
||||||
|
assert!(!disabled.enabled);
|
||||||
|
assert_eq!(disabled.state().next_run, None);
|
||||||
|
|
||||||
|
// 9:00 in Madrid is 8:00 UTC in winter: already past, so tomorrow.
|
||||||
|
let plain = entry("test.plain");
|
||||||
|
assert_eq!(plain.timezone, Tz::Europe__Madrid);
|
||||||
|
assert_eq!(plain.state().next_run, Some(at("2026-01-16T08:00:00Z")));
|
||||||
|
|
||||||
|
assert_eq!(entry("test.startup").state().next_run, Some(now));
|
||||||
|
|
||||||
|
// Sorted by key.
|
||||||
|
let keys: Vec<_> = registry
|
||||||
|
.entries
|
||||||
|
.iter()
|
||||||
|
.map(|e| e.job.key().to_string())
|
||||||
|
.collect();
|
||||||
|
assert_eq!(
|
||||||
|
keys,
|
||||||
|
[
|
||||||
|
"test.disabled",
|
||||||
|
"test.overridden",
|
||||||
|
"test.plain",
|
||||||
|
"test.startup"
|
||||||
|
]
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[pagetop::test]
|
||||||
|
async fn external_calls_run_each_scheduled_run_once() {
|
||||||
|
load_settings();
|
||||||
|
let minute = Duration::minutes(1);
|
||||||
|
let registry = build(
|
||||||
|
vec![
|
||||||
|
job("test.plain", "0 9 * * *"),
|
||||||
|
Job::new(
|
||||||
|
"test.rate",
|
||||||
|
Schedule::fixed_rate(Duration::minutes(10)),
|
||||||
|
noop,
|
||||||
|
),
|
||||||
|
job("test.startup", "@daily").with_run_on_start(),
|
||||||
|
],
|
||||||
|
at("2026-01-15T07:50:00Z"),
|
||||||
|
)
|
||||||
|
.unwrap();
|
||||||
|
let entry = |key: &str| {
|
||||||
|
registry
|
||||||
|
.entries
|
||||||
|
.iter()
|
||||||
|
.find(|e| e.job.key() == key)
|
||||||
|
.unwrap()
|
||||||
|
};
|
||||||
|
|
||||||
|
// A call at 8:00:20 handles the minute that ends at 8:00:00 UTC (9:00 in Madrid).
|
||||||
|
let end = window_end(at("2026-01-15T08:00:20.500Z"), minute).unwrap();
|
||||||
|
assert_eq!(end, at("2026-01-15T08:00:00Z"));
|
||||||
|
let plain = entry("test.plain");
|
||||||
|
assert_eq!(
|
||||||
|
plain.take_due(end, minute),
|
||||||
|
Some((RunTrigger::External, Some(end)))
|
||||||
|
);
|
||||||
|
// A second call for the same minute, or for an earlier one (clock set back), runs nothing.
|
||||||
|
assert_eq!(plain.take_due(end, minute), None);
|
||||||
|
assert_eq!(plain.take_due(end - minute, minute), None);
|
||||||
|
assert_eq!(plain.take_due(end + minute, minute), None);
|
||||||
|
assert_eq!(plain.state().next_run, Some(at("2026-01-16T08:00:00Z")));
|
||||||
|
|
||||||
|
// Intervals count from 1970, so every instance agrees on their runs.
|
||||||
|
let rate = entry("test.rate");
|
||||||
|
assert_eq!(rate.state().next_run, Some(end));
|
||||||
|
assert_eq!(
|
||||||
|
rate.take_due(end, minute),
|
||||||
|
Some((RunTrigger::External, Some(end)))
|
||||||
|
);
|
||||||
|
assert_eq!(rate.take_due(end + minute, minute), None);
|
||||||
|
let later = end + Duration::minutes(10);
|
||||||
|
assert_eq!(
|
||||||
|
rate.take_due(later, minute),
|
||||||
|
Some((RunTrigger::External, Some(later)))
|
||||||
|
);
|
||||||
|
|
||||||
|
// A process started by the call itself still runs what is due.
|
||||||
|
let woken = build(
|
||||||
|
vec![job("test.plain", "0 9 * * *")],
|
||||||
|
at("2026-01-15T08:00:00.300Z"),
|
||||||
|
)
|
||||||
|
.unwrap();
|
||||||
|
assert_eq!(
|
||||||
|
woken.entries[0].take_due(end, minute),
|
||||||
|
Some((RunTrigger::External, Some(end)))
|
||||||
|
);
|
||||||
|
|
||||||
|
// The startup run only happens on the first call.
|
||||||
|
let startup = entry("test.startup");
|
||||||
|
assert_eq!(
|
||||||
|
startup.take_due(end, minute),
|
||||||
|
Some((RunTrigger::Startup, None))
|
||||||
|
);
|
||||||
|
assert_eq!(startup.take_due(end + minute, minute), None);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[pagetop::test]
|
||||||
|
async fn only_the_configured_token_matches() {
|
||||||
|
load_settings();
|
||||||
|
assert!(token_matches("test-token-0123456789"));
|
||||||
|
assert!(!token_matches("test-token-012345678"));
|
||||||
|
assert!(!token_matches("test-token-0123456780"));
|
||||||
|
assert!(!token_matches(""));
|
||||||
|
}
|
||||||
|
|
||||||
|
#[pagetop::test]
|
||||||
|
async fn fixed_rate_keeps_its_pace() {
|
||||||
|
let trigger = Schedule::fixed_rate(Duration::seconds(10))
|
||||||
|
.compile()
|
||||||
|
.unwrap();
|
||||||
|
let start = at("2026-01-15T10:00:00Z");
|
||||||
|
let tz = Tz::UTC;
|
||||||
|
// Woken up a bit late: the next run keeps the pace, it does not drift.
|
||||||
|
let late = start + Duration::milliseconds(15);
|
||||||
|
assert_eq!(
|
||||||
|
trigger.following(start, late, tz),
|
||||||
|
Some(at("2026-01-15T10:00:10Z"))
|
||||||
|
);
|
||||||
|
// Several runs missed (e.g. a suspended machine): they are skipped, keeping the pace.
|
||||||
|
let much_later = start + Duration::seconds(35);
|
||||||
|
assert_eq!(
|
||||||
|
trigger.following(start, much_later, tz),
|
||||||
|
Some(at("2026-01-15T10:00:40Z"))
|
||||||
|
);
|
||||||
|
// Billions of missed runs (1 ms pace, 30 days asleep) keep the pace without overflowing.
|
||||||
|
let trigger = Schedule::fixed_rate(Duration::milliseconds(1))
|
||||||
|
.compile()
|
||||||
|
.unwrap();
|
||||||
|
let asleep = start + Duration::days(30) + Duration::microseconds(500);
|
||||||
|
assert_eq!(
|
||||||
|
trigger.following(start, asleep, tz),
|
||||||
|
Some(start + Duration::days(30) + Duration::milliseconds(1))
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[pagetop::test]
|
||||||
|
async fn fixed_delay_counts_from_the_end_of_the_run() {
|
||||||
|
let trigger = Schedule::fixed_delay(Duration::seconds(10))
|
||||||
|
.compile()
|
||||||
|
.unwrap();
|
||||||
|
let start = at("2026-01-15T10:00:00Z");
|
||||||
|
let finished = start + Duration::seconds(25);
|
||||||
|
assert_eq!(
|
||||||
|
trigger.following(start, finished, Tz::UTC),
|
||||||
|
Some(at("2026-01-15T10:00:35Z"))
|
||||||
|
);
|
||||||
|
}
|
||||||
|
}
|
||||||
42
extensions/pagetop-cron/src/status.rs
Normal file
42
extensions/pagetop-cron/src/status.rs
Normal file
|
|
@ -0,0 +1,42 @@
|
||||||
|
use pagetop::prelude::*;
|
||||||
|
|
||||||
|
use crate::{JobRun, Schedule};
|
||||||
|
|
||||||
|
/// Estado de un trabajo: programación efectiva, próxima ejecución y cómo fue la última.
|
||||||
|
///
|
||||||
|
/// Lo devuelven [`jobs()`](crate::jobs) y [`job()`](crate::job), p. ej. para mostrar los trabajos
|
||||||
|
/// en un panel de administración o comprobarlos en las pruebas. Es una copia: no cambia aunque el
|
||||||
|
/// trabajo se vuelva a ejecutar.
|
||||||
|
#[derive(Clone, Debug, Getters)]
|
||||||
|
pub struct JobStatus {
|
||||||
|
/// Devuelve la clave del trabajo.
|
||||||
|
pub(crate) key: CowStr,
|
||||||
|
/// Devuelve el título del trabajo (`Lc::none()` si no tiene).
|
||||||
|
pub(crate) title: Lc,
|
||||||
|
/// Devuelve la programación efectiva, la de la configuración si la cambia.
|
||||||
|
pub(crate) schedule: Schedule,
|
||||||
|
/// Devuelve la zona horaria en la que se interpreta la programación.
|
||||||
|
#[getters(copy)]
|
||||||
|
pub(crate) timezone: Tz,
|
||||||
|
/// Devuelve si el trabajo se ejecuta de forma automática (`false` si lo desactiva la
|
||||||
|
/// configuración).
|
||||||
|
#[getters(copy)]
|
||||||
|
pub(crate) enabled: bool,
|
||||||
|
/// Devuelve cuántas ejecuciones del trabajo están en curso.
|
||||||
|
#[getters(copy)]
|
||||||
|
pub(crate) running: usize,
|
||||||
|
/// Devuelve la próxima ejecución programada, en UTC, si la hay.
|
||||||
|
#[getters(copy)]
|
||||||
|
pub(crate) next_run: Option<DateTime<Utc>>,
|
||||||
|
/// Devuelve el informe de la última ejecución terminada, si la hay.
|
||||||
|
pub(crate) last_run: Option<JobRun>,
|
||||||
|
/// Devuelve cuántas ejecuciones han terminado desde que arrancó la aplicación.
|
||||||
|
#[getters(copy)]
|
||||||
|
pub(crate) runs: u64,
|
||||||
|
/// Devuelve cuántas de esas ejecuciones no terminaron bien (error, tiempo agotado o `panic!`).
|
||||||
|
#[getters(copy)]
|
||||||
|
pub(crate) failures: u64,
|
||||||
|
/// Devuelve cuántas ejecuciones se omitieron porque la anterior aún no había terminado.
|
||||||
|
#[getters(copy)]
|
||||||
|
pub(crate) skipped: u64,
|
||||||
|
}
|
||||||
288
extensions/pagetop-cron/tests/jobs.rs
Normal file
288
extensions/pagetop-cron/tests/jobs.rs
Normal file
|
|
@ -0,0 +1,288 @@
|
||||||
|
// `config/common.toml` uses the external mode, the Madrid timezone and job settings for some of the
|
||||||
|
// jobs declared here. The scheduler never starts in tests (`Application::run()` is not called), so
|
||||||
|
// jobs only run through `run_now()` and the external trigger route.
|
||||||
|
|
||||||
|
use pagetop::prelude::*;
|
||||||
|
use pagetop_cron::prelude::*;
|
||||||
|
|
||||||
|
use std::sync::Mutex;
|
||||||
|
use std::sync::atomic::{AtomicUsize, Ordering};
|
||||||
|
|
||||||
|
// Never due while the tests run, so the external trigger only starts the jobs a test expects.
|
||||||
|
const LATER: &str = "0 0 0 1 1 * 2099";
|
||||||
|
|
||||||
|
static OK_RUNS: AtomicUsize = AtomicUsize::new(0);
|
||||||
|
static REPORTS: Mutex<Vec<(String, bool)>> = Mutex::new(Vec::new());
|
||||||
|
|
||||||
|
struct TestApp;
|
||||||
|
|
||||||
|
#[async_trait]
|
||||||
|
impl Extension for TestApp {
|
||||||
|
fn dependencies(&self) -> Vec<ExtensionRef> {
|
||||||
|
vec![&pagetop_cron::Cron]
|
||||||
|
}
|
||||||
|
|
||||||
|
fn actions(&self) -> Vec<ActionBox> {
|
||||||
|
actions![
|
||||||
|
DeclareCronJobs::new(declare_jobs),
|
||||||
|
AfterJobRun::new(|run| {
|
||||||
|
REPORTS
|
||||||
|
.lock()
|
||||||
|
.unwrap()
|
||||||
|
.push((run.key().to_string(), run.outcome().is_success()));
|
||||||
|
}),
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
fn declare_jobs(jobs: &mut CronJobs) {
|
||||||
|
jobs.add(
|
||||||
|
Job::new("test.ok", Schedule::cron(LATER), |_| async {
|
||||||
|
OK_RUNS.fetch_add(1, Ordering::SeqCst);
|
||||||
|
Ok(())
|
||||||
|
})
|
||||||
|
.with_title(Lc::n("Works")),
|
||||||
|
);
|
||||||
|
jobs.add(Job::new("test.fails", Schedule::cron(LATER), |_| async {
|
||||||
|
Err(std::io::Error::other("boom").into())
|
||||||
|
}));
|
||||||
|
jobs.add(Job::new("test.panics", Schedule::cron(LATER), |_| async {
|
||||||
|
panic!("kaboom");
|
||||||
|
}));
|
||||||
|
jobs.add(
|
||||||
|
Job::new("test.slow", Schedule::cron(LATER), |_| async {
|
||||||
|
tokio::time::sleep(std::time::Duration::from_secs(10)).await;
|
||||||
|
Ok(())
|
||||||
|
})
|
||||||
|
.with_timeout(Duration::milliseconds(100)),
|
||||||
|
);
|
||||||
|
jobs.add(Job::new("test.busy", Schedule::cron(LATER), |_| async {
|
||||||
|
tokio::time::sleep(std::time::Duration::from_millis(300)).await;
|
||||||
|
Ok(())
|
||||||
|
}));
|
||||||
|
jobs.add(
|
||||||
|
Job::new("test.parallel", Schedule::cron(LATER), |_| async {
|
||||||
|
tokio::time::sleep(std::time::Duration::from_millis(300)).await;
|
||||||
|
Ok(())
|
||||||
|
})
|
||||||
|
.with_overlap(Overlap::Allow),
|
||||||
|
);
|
||||||
|
jobs.add(Job::new(
|
||||||
|
"test.context",
|
||||||
|
Schedule::cron(LATER),
|
||||||
|
|cx| async move {
|
||||||
|
if cx.key() != "test.context"
|
||||||
|
|| cx.trigger() != RunTrigger::Manual
|
||||||
|
|| cx.scheduled_at().is_some()
|
||||||
|
|| cx.is_stopping()
|
||||||
|
{
|
||||||
|
return Err("unexpected job context".into());
|
||||||
|
}
|
||||||
|
Ok(())
|
||||||
|
},
|
||||||
|
));
|
||||||
|
jobs.add(Job::new(
|
||||||
|
"test.disabled",
|
||||||
|
Schedule::cron("* * * * *"),
|
||||||
|
|_| async { Ok(()) },
|
||||||
|
));
|
||||||
|
jobs.add(
|
||||||
|
Job::new("test.overridden", Schedule::cron("0 * * * *"), |_| async {
|
||||||
|
Ok(())
|
||||||
|
})
|
||||||
|
.with_timeout(Duration::minutes(1)),
|
||||||
|
);
|
||||||
|
jobs.add(Job::new("test.due", Schedule::cron(LATER), |_| async { Ok(()) }).with_run_on_start());
|
||||||
|
}
|
||||||
|
|
||||||
|
async fn prepare() {
|
||||||
|
Application::prepare(&TestApp).await;
|
||||||
|
}
|
||||||
|
|
||||||
|
fn reported(key: &str) -> Vec<bool> {
|
||||||
|
REPORTS
|
||||||
|
.lock()
|
||||||
|
.unwrap()
|
||||||
|
.iter()
|
||||||
|
.filter(|(k, _)| k == key)
|
||||||
|
.map(|(_, ok)| *ok)
|
||||||
|
.collect()
|
||||||
|
}
|
||||||
|
|
||||||
|
#[pagetop::test]
|
||||||
|
async fn a_job_runs_on_demand_and_reports() {
|
||||||
|
prepare().await;
|
||||||
|
let before = OK_RUNS.load(Ordering::SeqCst);
|
||||||
|
|
||||||
|
let run = pagetop_cron::run_now("test.ok").await.unwrap();
|
||||||
|
assert_eq!(run.key(), "test.ok");
|
||||||
|
assert_eq!(run.trigger(), RunTrigger::Manual);
|
||||||
|
assert_eq!(run.outcome(), &JobOutcome::Succeeded);
|
||||||
|
assert!(run.duration() >= Duration::zero());
|
||||||
|
assert_eq!(OK_RUNS.load(Ordering::SeqCst), before + 1);
|
||||||
|
|
||||||
|
let status = pagetop_cron::job("test.ok").unwrap();
|
||||||
|
assert!(status.runs() >= 1);
|
||||||
|
assert_eq!(status.failures(), 0);
|
||||||
|
assert_eq!(status.last_run().unwrap().outcome(), &JobOutcome::Succeeded);
|
||||||
|
assert!(reported("test.ok").contains(&true));
|
||||||
|
}
|
||||||
|
|
||||||
|
#[pagetop::test]
|
||||||
|
async fn the_job_receives_its_context() {
|
||||||
|
prepare().await;
|
||||||
|
let run = pagetop_cron::run_now("test.context").await.unwrap();
|
||||||
|
assert!(run.outcome().is_success(), "{}", run.outcome());
|
||||||
|
}
|
||||||
|
|
||||||
|
#[pagetop::test]
|
||||||
|
async fn errors_and_panics_are_reported_as_failures() {
|
||||||
|
prepare().await;
|
||||||
|
|
||||||
|
let run = pagetop_cron::run_now("test.fails").await.unwrap();
|
||||||
|
assert_eq!(run.outcome(), &JobOutcome::Failed("boom".to_owned()));
|
||||||
|
assert_eq!(run.outcome().to_string(), "failed: boom");
|
||||||
|
|
||||||
|
let run = pagetop_cron::run_now("test.panics").await.unwrap();
|
||||||
|
assert_eq!(run.outcome(), &JobOutcome::Panicked("kaboom".to_owned()));
|
||||||
|
// A panic does not prevent the next run.
|
||||||
|
let run = pagetop_cron::run_now("test.panics").await.unwrap();
|
||||||
|
assert!(matches!(run.outcome(), JobOutcome::Panicked(_)));
|
||||||
|
|
||||||
|
let status = pagetop_cron::job("test.panics").unwrap();
|
||||||
|
assert_eq!(status.running(), 0);
|
||||||
|
assert!(status.failures() >= 2);
|
||||||
|
assert!(reported("test.fails").contains(&false));
|
||||||
|
}
|
||||||
|
|
||||||
|
#[pagetop::test]
|
||||||
|
async fn a_job_over_its_timeout_is_cancelled() {
|
||||||
|
prepare().await;
|
||||||
|
let clock = std::time::Instant::now();
|
||||||
|
let run = pagetop_cron::run_now("test.slow").await.unwrap();
|
||||||
|
assert_eq!(run.outcome(), &JobOutcome::TimedOut);
|
||||||
|
assert!(clock.elapsed() < std::time::Duration::from_secs(5));
|
||||||
|
// The run is released once the cancelled task has actually stopped.
|
||||||
|
let mut running = 1;
|
||||||
|
for _ in 0..50 {
|
||||||
|
running = pagetop_cron::job("test.slow").unwrap().running();
|
||||||
|
if running == 0 {
|
||||||
|
break;
|
||||||
|
}
|
||||||
|
tokio::time::sleep(std::time::Duration::from_millis(20)).await;
|
||||||
|
}
|
||||||
|
assert_eq!(running, 0);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[pagetop::test]
|
||||||
|
async fn overlapping_runs_are_refused_unless_allowed() {
|
||||||
|
prepare().await;
|
||||||
|
|
||||||
|
let (first, second) = tokio::join!(pagetop_cron::run_now("test.busy"), async {
|
||||||
|
tokio::time::sleep(std::time::Duration::from_millis(50)).await;
|
||||||
|
pagetop_cron::run_now("test.busy").await
|
||||||
|
});
|
||||||
|
assert!(first.unwrap().outcome().is_success());
|
||||||
|
assert!(matches!(second, Err(CronError::AlreadyRunning(key)) if key == "test.busy"));
|
||||||
|
|
||||||
|
let (first, second) = tokio::join!(pagetop_cron::run_now("test.parallel"), async {
|
||||||
|
tokio::time::sleep(std::time::Duration::from_millis(50)).await;
|
||||||
|
pagetop_cron::run_now("test.parallel").await
|
||||||
|
});
|
||||||
|
assert!(first.unwrap().outcome().is_success());
|
||||||
|
assert!(second.unwrap().outcome().is_success());
|
||||||
|
}
|
||||||
|
|
||||||
|
#[pagetop::test]
|
||||||
|
async fn unknown_jobs_cannot_run() {
|
||||||
|
prepare().await;
|
||||||
|
let err = pagetop_cron::run_now("test.missing").await.unwrap_err();
|
||||||
|
assert!(matches!(err, CronError::UnknownJob(key) if key == "test.missing"));
|
||||||
|
assert!(pagetop_cron::job("test.missing").is_none());
|
||||||
|
}
|
||||||
|
|
||||||
|
#[pagetop::test]
|
||||||
|
async fn statuses_show_the_effective_settings() {
|
||||||
|
prepare().await;
|
||||||
|
let jobs = pagetop_cron::jobs();
|
||||||
|
let keys: Vec<_> = jobs.iter().map(|job| job.key().to_string()).collect();
|
||||||
|
let mut sorted = keys.clone();
|
||||||
|
sorted.sort();
|
||||||
|
assert_eq!(keys, sorted);
|
||||||
|
assert_eq!(keys.len(), 10);
|
||||||
|
|
||||||
|
let ok = pagetop_cron::job("test.ok").unwrap();
|
||||||
|
assert!(!ok.title().is_none());
|
||||||
|
assert!(pagetop_cron::job("test.fails").unwrap().title().is_none());
|
||||||
|
assert_eq!(ok.schedule().to_string(), LATER);
|
||||||
|
assert_eq!(ok.timezone(), Tz::Europe__Madrid);
|
||||||
|
assert!(ok.enabled());
|
||||||
|
// External mode: the next run is known from startup.
|
||||||
|
assert!(ok.next_run().is_some_and(|next| next > Utc::now()));
|
||||||
|
|
||||||
|
let disabled = pagetop_cron::job("test.disabled").unwrap();
|
||||||
|
assert!(!disabled.enabled());
|
||||||
|
assert!(disabled.next_run().is_none());
|
||||||
|
|
||||||
|
let overridden = pagetop_cron::job("test.overridden").unwrap();
|
||||||
|
assert_eq!(overridden.schedule().to_string(), "@delay 1m30s");
|
||||||
|
|
||||||
|
// A disabled job still runs on demand.
|
||||||
|
let run = pagetop_cron::run_now("test.disabled").await.unwrap();
|
||||||
|
assert!(run.outcome().is_success());
|
||||||
|
}
|
||||||
|
|
||||||
|
async fn post(app: &Router, auth: &str) -> (web::http::StatusCode, String) {
|
||||||
|
let req = web::test::TestRequest::post()
|
||||||
|
.uri("/cron")
|
||||||
|
.header("authorization", auth)
|
||||||
|
.to_request();
|
||||||
|
let resp = web::test::send_request(app, req).await;
|
||||||
|
let status = resp.status();
|
||||||
|
(status, web::test::read_body_text(resp).await)
|
||||||
|
}
|
||||||
|
|
||||||
|
#[pagetop::test]
|
||||||
|
async fn the_external_trigger_runs_the_due_jobs() {
|
||||||
|
let app = web::test::init_router(Application::prepare(&TestApp).await.test());
|
||||||
|
|
||||||
|
for auth in [
|
||||||
|
"Bearer wrong-token-0123456789",
|
||||||
|
"Bearer test-token-012345678",
|
||||||
|
"test-token-0123456789",
|
||||||
|
"Basic test-token-0123456789",
|
||||||
|
] {
|
||||||
|
let (status, _) = post(&app, auth).await;
|
||||||
|
assert_eq!(status, web::http::StatusCode::NOT_FOUND, "{auth}");
|
||||||
|
}
|
||||||
|
// Without the header at all, with another method, or with the token in the path.
|
||||||
|
let req = web::test::TestRequest::post().uri("/cron").to_request();
|
||||||
|
let resp = web::test::send_request(&app, req).await;
|
||||||
|
assert_eq!(resp.status(), web::http::StatusCode::NOT_FOUND);
|
||||||
|
let req = web::test::TestRequest::get().uri("/cron").to_request();
|
||||||
|
let resp = web::test::send_request(&app, req).await;
|
||||||
|
assert_eq!(resp.status(), web::http::StatusCode::NOT_FOUND);
|
||||||
|
let req = web::test::TestRequest::post()
|
||||||
|
.uri("/cron/test-token-0123456789")
|
||||||
|
.to_request();
|
||||||
|
let resp = web::test::send_request(&app, req).await;
|
||||||
|
assert_eq!(resp.status(), web::http::StatusCode::NOT_FOUND);
|
||||||
|
assert_eq!(pagetop_cron::job("test.due").unwrap().runs(), 0);
|
||||||
|
|
||||||
|
// "test.due" runs on the first call because it runs on start. The scheme is case-insensitive.
|
||||||
|
// The response arrives once the jobs have finished, with one line per job.
|
||||||
|
let (status, body) = post(&app, "bearer test-token-0123456789").await;
|
||||||
|
assert_eq!(status, web::http::StatusCode::OK);
|
||||||
|
assert!(body.starts_with("Ran "), "{body}");
|
||||||
|
assert!(body.contains("\ntest.due: succeeded\n"), "{body}");
|
||||||
|
assert_eq!(pagetop_cron::job("test.due").unwrap().runs(), 1);
|
||||||
|
let due = pagetop_cron::job("test.due").unwrap();
|
||||||
|
assert_eq!(due.last_run().unwrap().trigger(), RunTrigger::Startup);
|
||||||
|
assert!(due.next_run().is_some_and(|next| next > Utc::now()));
|
||||||
|
|
||||||
|
// Not again on later calls.
|
||||||
|
let (status, body) = post(&app, "Bearer test-token-0123456789").await;
|
||||||
|
assert_eq!(status, web::http::StatusCode::OK);
|
||||||
|
assert!(!body.contains("test.due"), "{body}");
|
||||||
|
assert_eq!(pagetop_cron::job("test.due").unwrap().runs(), 1);
|
||||||
|
}
|
||||||
180
extensions/pagetop-cron/tests/schedule.rs
Normal file
180
extensions/pagetop-cron/tests/schedule.rs
Normal file
|
|
@ -0,0 +1,180 @@
|
||||||
|
use pagetop::prelude::*;
|
||||||
|
use pagetop_cron::prelude::*;
|
||||||
|
|
||||||
|
fn at(text: &str) -> DateTime<Utc> {
|
||||||
|
text.parse().unwrap()
|
||||||
|
}
|
||||||
|
|
||||||
|
fn next(schedule: &str, after: &str, tz: Tz) -> String {
|
||||||
|
Schedule::parse(schedule)
|
||||||
|
.unwrap()
|
||||||
|
.next_after(at(after), tz)
|
||||||
|
.unwrap()
|
||||||
|
.unwrap()
|
||||||
|
.to_rfc3339()
|
||||||
|
}
|
||||||
|
|
||||||
|
#[pagetop::test]
|
||||||
|
async fn cron_expressions_and_nicknames_are_accepted() {
|
||||||
|
for text in [
|
||||||
|
"*/10 * * * *",
|
||||||
|
"*/30 * * * * *",
|
||||||
|
"30 4 * * *",
|
||||||
|
"0 8-18 * * MON-FRI",
|
||||||
|
"0 0 L * *",
|
||||||
|
"0 9 15W * *",
|
||||||
|
"0 9 * * MON#1",
|
||||||
|
"0 18 * * 5L",
|
||||||
|
"@yearly",
|
||||||
|
"@annually",
|
||||||
|
"@monthly",
|
||||||
|
"@weekly",
|
||||||
|
"@daily",
|
||||||
|
"@hourly",
|
||||||
|
] {
|
||||||
|
let schedule = Schedule::parse(text).unwrap_or_else(|err| panic!("{text}: {err}"));
|
||||||
|
// The text is kept as written.
|
||||||
|
assert_eq!(schedule.to_string(), text);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
#[pagetop::test]
|
||||||
|
async fn intervals_are_parsed_and_written_back() {
|
||||||
|
let cases = [
|
||||||
|
(
|
||||||
|
"@every 30s",
|
||||||
|
"@every 30s",
|
||||||
|
Schedule::fixed_rate(Duration::seconds(30)),
|
||||||
|
),
|
||||||
|
(
|
||||||
|
"@every 1h30m",
|
||||||
|
"@every 1h30m",
|
||||||
|
Schedule::fixed_rate(Duration::minutes(90)),
|
||||||
|
),
|
||||||
|
(
|
||||||
|
"@every 1h 30m",
|
||||||
|
"@every 1h30m",
|
||||||
|
Schedule::fixed_rate(Duration::minutes(90)),
|
||||||
|
),
|
||||||
|
(
|
||||||
|
"@EVERY 2d",
|
||||||
|
"@every 2d",
|
||||||
|
Schedule::fixed_rate(Duration::days(2)),
|
||||||
|
),
|
||||||
|
(
|
||||||
|
" @delay 500ms ",
|
||||||
|
"@delay 500ms",
|
||||||
|
Schedule::fixed_delay(Duration::milliseconds(500)),
|
||||||
|
),
|
||||||
|
(
|
||||||
|
"@delay 90s",
|
||||||
|
"@delay 1m30s",
|
||||||
|
Schedule::fixed_delay(Duration::seconds(90)),
|
||||||
|
),
|
||||||
|
];
|
||||||
|
for (text, written, expected) in cases {
|
||||||
|
let schedule: Schedule = text.parse().unwrap();
|
||||||
|
assert_eq!(schedule, expected, "{text}");
|
||||||
|
assert_eq!(schedule.to_string(), written, "{text}");
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
#[pagetop::test]
|
||||||
|
async fn invalid_schedules_are_rejected() {
|
||||||
|
for text in [
|
||||||
|
"",
|
||||||
|
"61 * * * *",
|
||||||
|
"* * *",
|
||||||
|
"0 0 32 * *",
|
||||||
|
"every day",
|
||||||
|
"@every",
|
||||||
|
"@every 0s",
|
||||||
|
"@every 5",
|
||||||
|
"@every 5x",
|
||||||
|
"@every -1s",
|
||||||
|
"@delay m",
|
||||||
|
"@every 36501d",
|
||||||
|
] {
|
||||||
|
let err = Schedule::parse(text).unwrap_err();
|
||||||
|
assert!(
|
||||||
|
matches!(err, CronError::InvalidSchedule { .. }),
|
||||||
|
"{text}: {err}"
|
||||||
|
);
|
||||||
|
}
|
||||||
|
// Constructors do not validate; the first use does.
|
||||||
|
let zero = Schedule::fixed_delay(Duration::zero());
|
||||||
|
assert!(zero.next_after(Utc::now(), Tz::UTC).is_err());
|
||||||
|
}
|
||||||
|
|
||||||
|
#[pagetop::test]
|
||||||
|
async fn cron_expressions_follow_the_timezone() {
|
||||||
|
// 9:00 in Madrid: 8:00 UTC in winter, 7:00 UTC in summer.
|
||||||
|
let madrid = Tz::Europe__Madrid;
|
||||||
|
assert_eq!(
|
||||||
|
next("0 9 * * *", "2026-01-15T00:00:00Z", madrid),
|
||||||
|
"2026-01-15T08:00:00+00:00"
|
||||||
|
);
|
||||||
|
assert_eq!(
|
||||||
|
next("0 9 * * *", "2026-07-15T00:00:00Z", madrid),
|
||||||
|
"2026-07-15T07:00:00+00:00"
|
||||||
|
);
|
||||||
|
assert_eq!(
|
||||||
|
next("0 9 * * *", "2026-07-15T00:00:00Z", Tz::UTC),
|
||||||
|
"2026-07-15T09:00:00+00:00"
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[pagetop::test]
|
||||||
|
async fn special_characters_select_the_right_days() {
|
||||||
|
let madrid = Tz::Europe__Madrid;
|
||||||
|
// First Monday of November 2026 (CET, UTC+1).
|
||||||
|
assert_eq!(
|
||||||
|
next("0 9 * * MON#1", "2026-10-19T00:00:00Z", madrid),
|
||||||
|
"2026-11-02T08:00:00+00:00"
|
||||||
|
);
|
||||||
|
// Last day of February 2026.
|
||||||
|
assert_eq!(
|
||||||
|
next("0 0 L * *", "2026-02-10T00:00:00Z", madrid),
|
||||||
|
"2026-02-27T23:00:00+00:00"
|
||||||
|
);
|
||||||
|
// Last Friday of October 2026 (still CEST, UTC+2).
|
||||||
|
assert_eq!(
|
||||||
|
next("0 18 * * 5L", "2026-10-01T00:00:00Z", madrid),
|
||||||
|
"2026-10-30T17:00:00+00:00"
|
||||||
|
);
|
||||||
|
// Nearest weekday to Saturday 15 August 2026: Friday 14.
|
||||||
|
assert_eq!(
|
||||||
|
next("0 9 15W * *", "2026-08-01T00:00:00Z", madrid),
|
||||||
|
"2026-08-14T07:00:00+00:00"
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[pagetop::test]
|
||||||
|
async fn daylight_saving_changes_run_once() {
|
||||||
|
let madrid = Tz::Europe__Madrid;
|
||||||
|
// Spring forward on 29 March 2026: 2:30 does not exist; it runs when the next hour starts
|
||||||
|
// (3:00 CEST = 1:00 UTC), and the day after at 2:30 again.
|
||||||
|
assert_eq!(
|
||||||
|
next("30 2 * * *", "2026-03-28T12:00:00Z", madrid),
|
||||||
|
"2026-03-29T01:00:00+00:00"
|
||||||
|
);
|
||||||
|
assert_eq!(
|
||||||
|
next("30 2 * * *", "2026-03-29T01:00:00Z", madrid),
|
||||||
|
"2026-03-30T00:30:00+00:00"
|
||||||
|
);
|
||||||
|
// Fall back on 25 October 2026: 2:30 happens twice; it runs only once.
|
||||||
|
let first = next("30 2 * * *", "2026-10-24T12:00:00Z", madrid);
|
||||||
|
assert_eq!(first, "2026-10-25T00:30:00+00:00");
|
||||||
|
assert_eq!(
|
||||||
|
next("30 2 * * *", &first, madrid),
|
||||||
|
"2026-10-26T01:30:00+00:00"
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[pagetop::test]
|
||||||
|
async fn intervals_ignore_the_timezone() {
|
||||||
|
let after = "2026-03-29T00:30:00Z";
|
||||||
|
let every = Schedule::fixed_rate(Duration::hours(1));
|
||||||
|
let next = every.next_after(at(after), Tz::Europe__Madrid).unwrap();
|
||||||
|
assert_eq!(next, Some(at("2026-03-29T01:30:00Z")));
|
||||||
|
}
|
||||||
|
|
@ -66,6 +66,7 @@ case "$CRATE" in
|
||||||
--exclude-path "extensions/pagetop-admin/**/*"
|
--exclude-path "extensions/pagetop-admin/**/*"
|
||||||
--exclude-path "extensions/pagetop-aliner/**/*"
|
--exclude-path "extensions/pagetop-aliner/**/*"
|
||||||
--exclude-path "extensions/pagetop-bootsier/**/*"
|
--exclude-path "extensions/pagetop-bootsier/**/*"
|
||||||
|
--exclude-path "extensions/pagetop-cron/**/*"
|
||||||
--exclude-path "extensions/pagetop-htmx/**/*"
|
--exclude-path "extensions/pagetop-htmx/**/*"
|
||||||
--exclude-path "extensions/pagetop-mail/**/*"
|
--exclude-path "extensions/pagetop-mail/**/*"
|
||||||
--exclude-path "extensions/pagetop-seaorm/**/*"
|
--exclude-path "extensions/pagetop-seaorm/**/*"
|
||||||
|
|
@ -84,6 +85,10 @@ case "$CRATE" in
|
||||||
CHANGELOG_FILE="extensions/pagetop-bootsier/CHANGELOG.md"
|
CHANGELOG_FILE="extensions/pagetop-bootsier/CHANGELOG.md"
|
||||||
PATH_FLAGS=(--include-path "extensions/pagetop-bootsier/**/*")
|
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)
|
pagetop-htmx)
|
||||||
CHANGELOG_FILE="extensions/pagetop-htmx/CHANGELOG.md"
|
CHANGELOG_FILE="extensions/pagetop-htmx/CHANGELOG.md"
|
||||||
PATH_FLAGS=(--include-path "extensions/pagetop-htmx/**/*")
|
PATH_FLAGS=(--include-path "extensions/pagetop-htmx/**/*")
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue