From 4c3f4dab1b861c30ea27ec8d1fcc116016450f08 Mon Sep 17 00:00:00 2001 From: Manuel Cillero Date: Tue, 27 Oct 2026 20:26:09 +0100 Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20(core):=20A=C3=B1ade=20start()=20y?= =?UTF-8?q?=20shutdown()=20a=20Extension?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Arranca los servicios en segundo plano sólo con `Application::run()`, nunca en las pruebas, y los detiene en orden inverso al parar el servidor o si falla el `start()` de una extensión posterior. --- src/app.rs | 132 ++++++++++++++------------ src/core/extension/all.rs | 153 ++++++++++++++++++++++++++++++- src/core/extension/definition.rs | 59 ++++++++++++ src/lib.rs | 17 ++-- 4 files changed, 296 insertions(+), 65 deletions(-) diff --git a/src/app.rs b/src/app.rs index 9a24f45b..de37518c 100644 --- a/src/app.rs +++ b/src/app.rs @@ -111,10 +111,11 @@ impl Application { Self { tracing } } - // Detiene el arranque cuando falla la carga de los ajustes o la inicialización de una - // extensión. Escribe el error, con todas sus causas, en las trazas y en la salida de errores, - // que es lo único que ve quien arranca la aplicación si las trazas se escriben en archivos. - // Vuelca las trazas antes de terminar, porque `process::exit()` no ejecuta los destructores. + // Detiene el arranque cuando falla la carga de los ajustes, la inicialización de una extensión + // o el arranque de sus servicios. Escribe el error, con todas sus causas, en las trazas y en la + // salida de errores, que es lo único que ve quien arranca la aplicación si las trazas se + // escriben en archivos. Vuelca las trazas antes de terminar, porque `process::exit()` no + // ejecuta los destructores. // // Muchos errores terminan ya con el texto de su causa (p. ej. los de SeaORM), así que se omite // cada causa con la que ya termina el mensaje. @@ -171,6 +172,74 @@ impl Application { } } + /// Arranca el servidor web de la aplicación. + /// + /// Enlaza el puerto del servidor web (puede fallar con [`std::io::Error`] si el puerto ya está + /// en uso o el proceso carece de permisos) y ejecuta el bucle de atención de peticiones. + /// + /// Antes de atender la primera petición arranca los servicios en segundo plano de las + /// extensiones (ver [`Extension::start()`]). Si alguna falla, detiene las que ya arrancaron y + /// termina el proceso con el código de salida `1`, igual que un error al preparar la + /// aplicación. + /// + /// Se detiene de forma ordenada con Ctrl+C o, en Unix, con la señal `SIGTERM` (la que envían + /// `systemd` o Docker al detener un servicio). En ese momento deja de aceptar conexiones, + /// termina las peticiones en curso, detiene los servicios de las extensiones (ver + /// [`Extension::shutdown()`]) y vuelca las trazas pendientes antes de volver. Una segunda + /// Ctrl+C lo detiene en el acto, sin esperar a las peticiones ni a los servicios en curso. + /// + /// El patrón habitual es: + /// + /// ```rust,no_run + /// use pagetop::prelude::*; + /// + /// struct MyApp; + /// + /// #[async_trait] + /// impl Extension for MyApp {} + /// + /// #[pagetop::main] + /// async fn main() -> std::io::Result<()> { + /// Application::prepare(&MyApp).await.run().await + /// } + /// ``` + /// + /// [`Extension::start()`]: crate::core::extension::Extension::start + /// [`Extension::shutdown()`]: crate::core::extension::Extension::shutdown + pub async fn run(mut self) -> Result<(), Error> { + let addr = format!( + "{}:{}", + global::SETTINGS.server.bind_address, + global::SETTINGS.server.bind_port + ); + + // Enlaza el puerto de forma síncrona para detectar errores. + let std_listener = std::net::TcpListener::bind(&addr)?; + std_listener.set_nonblocking(true)?; + + let router = Self::build_router(); + + // Con el puerto ya enlazado, arranca los servicios en segundo plano de las extensiones. + if let Err(err) = extension::all::start_extensions().await { + Self::abort_startup(self.tracing.take(), err); + } + + let listener = tokio::net::TcpListener::from_std(std_listener)?; + let result = axum::serve(listener, router) + .with_graceful_shutdown(shutdown_signal()) + .await; + + // Detenido el servidor, detiene los servicios de las extensiones y vuelca las trazas. + extension::all::shutdown_extensions().await; + drop(self.tracing); + result + } + + /// Devuelve el servidor web configurado para usarlo en pruebas de integración. + pub fn test(self) -> Router { + Self::build_router() + } + // Construye el router con las rutas, el middleware y los archivos estáticos de todas las // extensiones habilitadas. // @@ -192,59 +261,6 @@ impl Application { .layer(axum::middleware::from_fn(render_error_pages)) .layer(CatchPanicLayer::custom(response_for_panic)) } - - /// Arranca el servidor web de la aplicación. - /// - /// Enlaza el puerto del servidor web (puede fallar con [`std::io::Error`] si el puerto ya está - /// en uso o el proceso carece de permisos) y ejecuta el bucle de atención de peticiones. - /// - /// Se detiene de forma ordenada con Ctrl+C o, en Unix, con la señal `SIGTERM` (la que envían - /// `systemd` o Docker al detener un servicio). En ese momento deja de aceptar conexiones, - /// termina las peticiones en curso y vuelca las trazas pendientes antes de volver. Una segunda - /// Ctrl+C lo detiene en el acto, sin esperar a las peticiones en curso. - /// - /// El patrón habitual es: - /// - /// ```rust,no_run - /// use pagetop::prelude::*; - /// - /// struct MyApp; - /// - /// #[async_trait] - /// impl Extension for MyApp {} - /// - /// #[pagetop::main] - /// async fn main() -> std::io::Result<()> { - /// Application::prepare(&MyApp).await.run().await - /// } - /// ``` - pub async fn run(self) -> Result<(), Error> { - let addr = format!( - "{}:{}", - global::SETTINGS.server.bind_address, - global::SETTINGS.server.bind_port - ); - - // Enlaza el puerto de forma síncrona para detectar errores. - let std_listener = std::net::TcpListener::bind(&addr)?; - std_listener.set_nonblocking(true)?; - - let router = Self::build_router(); - - let listener = tokio::net::TcpListener::from_std(std_listener)?; - let result = axum::serve(listener, router) - .with_graceful_shutdown(shutdown_signal()) - .await; - - // Detenido el servidor, vuelca las trazas pendientes. - drop(self.tracing); - result - } - - /// Devuelve el servidor web configurado para usarlo en pruebas de integración. - pub fn test(self) -> Router { - Self::build_router() - } } // Espera la señal para detener el servidor: Ctrl+C o, en Unix, `SIGTERM`. Si no se puede escuchar @@ -284,7 +300,7 @@ async fn shutdown_signal() { // porque `process::exit()` no deja volcar las trazas. tokio::spawn(async { if tokio::signal::ctrl_c().await.is_ok() { - eprintln!("\nSecond Ctrl+C, stopping without waiting for the requests in progress"); + eprintln!("\nSecond Ctrl+C, not waiting for requests or services in progress"); std::process::exit(130); } }); diff --git a/src/core/extension/all.rs b/src/core/extension/all.rs index 641fb097..9a9b1658 100644 --- a/src/core/extension/all.rs +++ b/src/core/extension/all.rs @@ -34,6 +34,13 @@ pub enum StartupError { #[source] source: BoxError, }, + /// Una extensión ha devuelto un error en su `start()`. + #[error("Extension \"{name}\" failed to start")] + Start { + name: &'static str, + #[source] + source: BoxError, + }, } // **< REGISTRO DE LAS EXTENSIONES >**************************************************************** @@ -172,6 +179,41 @@ pub async fn initialize_extensions() -> Result<(), StartupError> { Ok(()) } +// **< ARRANCA Y DETIENE LOS SERVICIOS >************************************************************ + +/// Arranca los servicios en segundo plano de las extensiones, en el orden en que se registraron. +/// +/// Se detiene en la primera que falle, y antes de devolver el error detiene, en orden inverso, las +/// que ya habían arrancado. +pub async fn start_extensions() -> Result<(), StartupError> { + start_extensions_of(EXTENSIONS.get().map(Vec::as_slice).unwrap_or_default()).await +} + +// Separada de `start_extensions()` para poder probarla sin el registro global de extensiones. +async fn start_extensions_of(extensions: &[ExtensionRef]) -> Result<(), StartupError> { + for (i, e) in extensions.iter().enumerate() { + if let Err(source) = e.start().await { + let name = e.short_name(); + if i > 0 { + // El error completo lo registra quien lo recibe; aquí sólo se explica la espera. + trace::warn!("Extension \"{name}\" failed to start, stopping the ones started"); + for started in extensions[..i].iter().rev() { + started.shutdown().await; + } + } + return Err(StartupError::Start { name, source }); + } + } + Ok(()) +} + +/// Detiene los servicios en segundo plano de las extensiones, en orden inverso al de registro. +pub async fn shutdown_extensions() { + for e in EXTENSIONS.get().into_iter().flatten().rev() { + e.shutdown().await; + } +} + // **< CONFIGURA LAS RUTAS >************************************************************************ pub fn configure_routes(router: Router) -> Router { @@ -224,11 +266,13 @@ pub fn configure_static_files(router: Router) -> Router { #[cfg(test)] mod tests { - use super::{StartupError, load_settings_of}; + use super::{StartupError, load_settings_of, start_extensions_of}; use crate::config::LoadSettings; use crate::core::extension::Extension; use crate::{BoxError, async_trait}; + use std::sync::Mutex; + // Settings for a given section that load fine or fail, without touching the configuration. struct FakeSettings { section: &'static str, @@ -308,4 +352,111 @@ mod tests { "bad value" ); } + + // Records its `start()` and `shutdown()` calls in a log shared with the other services of the + // same test, so that parallel tests do not mix their calls. + struct Service { + name: &'static str, + fails: bool, + log: &'static Mutex>, + } + + #[async_trait] + impl Extension for Service { + async fn start(&self) -> Result<(), BoxError> { + self.log + .lock() + .unwrap() + .push(format!("start {}", self.name)); + if self.fails { + Err("cannot start".into()) + } else { + Ok(()) + } + } + + async fn shutdown(&self) { + self.log + .lock() + .unwrap() + .push(format!("shutdown {}", self.name)); + } + } + + fn calls(log: &Mutex>) -> Vec { + log.lock().unwrap().clone() + } + + #[tokio::test] + async fn all_services_start_in_order_without_shutdown() { + static LOG: Mutex> = Mutex::new(Vec::new()); + static A: Service = Service { + name: "a", + fails: false, + log: &LOG, + }; + static B: Service = Service { + name: "b", + fails: false, + log: &LOG, + }; + + assert!(start_extensions_of(&[&A, &B]).await.is_ok()); + assert_eq!(calls(&LOG), ["start a", "start b"]); + } + + #[tokio::test] + async fn a_failed_start_shuts_down_the_started_ones_in_reverse_order() { + static LOG: Mutex> = Mutex::new(Vec::new()); + static A: Service = Service { + name: "a", + fails: false, + log: &LOG, + }; + static B: Service = Service { + name: "b", + fails: false, + log: &LOG, + }; + static C: Service = Service { + name: "c", + fails: true, + log: &LOG, + }; + static D: Service = Service { + name: "d", + fails: false, + log: &LOG, + }; + + let err = start_extensions_of(&[&A, &B, &C, &D]).await.unwrap_err(); + assert!(matches!(err, StartupError::Start { .. })); + assert_eq!( + std::error::Error::source(&err).unwrap().to_string(), + "cannot start" + ); + // The failing service is not shut down, and the ones after it never start. + assert_eq!( + calls(&LOG), + ["start a", "start b", "start c", "shutdown b", "shutdown a"] + ); + } + + #[tokio::test] + async fn a_failed_first_start_shuts_down_nothing() { + static LOG: Mutex> = Mutex::new(Vec::new()); + static A: Service = Service { + name: "a", + fails: true, + log: &LOG, + }; + static B: Service = Service { + name: "b", + fails: false, + log: &LOG, + }; + + assert!(start_extensions_of(&[&A, &B]).await.is_err()); + assert_eq!(calls(&LOG), ["start a"]); + } } diff --git a/src/core/extension/definition.rs b/src/core/extension/definition.rs index bc1c67dc..ca163357 100644 --- a/src/core/extension/definition.rs +++ b/src/core/extension/definition.rs @@ -155,6 +155,65 @@ pub trait Extension: AnyInfo + Send + Sync { Ok(()) } + /// Arranca los servicios propios de la extensión cuando el servidor web empieza a atender + /// peticiones. + /// + /// La firma extendida, como en [`initialize()`], es el resultado de aplicar la macro + /// [`pagetop::async_trait`] a la declaración: + /// + /// ```text + /// async fn start(&self) -> Result<(), BoxError> { Ok(()) } + /// ``` + /// + /// A diferencia de [`initialize()`], que prepara los recursos de la extensión y se ejecuta + /// cada vez que se prepara la aplicación (también en las pruebas), este método sólo lo invoca + /// [`Application::run()`], una vez enlazado el puerto del servidor y antes de atender la + /// primera petición, en el orden en que se inicializaron las extensiones. Es el lugar para + /// lanzar tareas que deben vivir mientras la aplicación está en marcha, como un planificador + /// de tareas o un proceso que vacía una cola; así no se lanzan en las pruebas, que obtienen el + /// servidor con [`Application::test()`] sin ejecutarlo. + /// + /// Las tareas deben lanzarse con `tokio::spawn()` para que el método termine enseguida: el + /// servidor no atiende peticiones hasta que vuelven todas las extensiones. Si devuelve un + /// error, la aplicación se detiene igual que con un error en [`initialize()`], pero antes + /// llama a [`shutdown()`] de las extensiones que ya arrancaron, en orden inverso. No lo llama + /// en la extensión que falla: si había lanzado algo antes del error, debe detenerlo ella misma + /// antes de devolverlo. + /// + /// [`initialize()`]: Self::initialize + /// [`shutdown()`]: Self::shutdown + /// [`pagetop::async_trait`]: pagetop::async_trait + /// [`Application::run()`]: crate::app::Application::run + /// [`Application::test()`]: crate::app::Application::test + async fn start(&self) -> Result<(), BoxError> { + Ok(()) + } + + /// Detiene de forma ordenada los servicios que la extensión lanzó en [`start()`]. + /// + /// La firma extendida, como en [`initialize()`], es el resultado de aplicar la macro + /// [`pagetop::async_trait`] a la declaración: + /// + /// ```text + /// async fn shutdown(&self) {} + /// ``` + /// + /// [`Application::run()`] lo invoca cuando el servidor se detiene (con Ctrl+C o la señal + /// `SIGTERM`), una vez terminadas las peticiones en curso y antes de volcar las trazas + /// pendientes, en orden inverso al de inicialización: una extensión se detiene antes que las + /// extensiones de las que depende. También lo invoca, en las extensiones que ya arrancaron, si + /// falla el [`start()`] de otra posterior. + /// + /// Es el momento de avisar a las tareas en segundo plano y de esperar, con un tiempo máximo, a + /// que terminen su trabajo. No devuelve errores: si algo falla, la extensión lo registra en las + /// trazas. + /// + /// [`start()`]: Self::start + /// [`initialize()`]: Self::initialize + /// [`pagetop::async_trait`]: pagetop::async_trait + /// [`Application::run()`]: crate::app::Application::run + async fn shutdown(&self) {} + /// Devuelve los ajustes de configuración de la extensión, para cargarlos en el arranque de la /// aplicación. /// diff --git a/src/lib.rs b/src/lib.rs index 798152fa..10aa4801 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -122,8 +122,7 @@ use std::ops::Deref; /// referencia a la versión del *crate* que lo usa. pub const PAGETOP_VERSION: &str = env!("CARGO_PKG_VERSION"); -/// Re-exporta el atributo [`async_trait`](https://docs.rs/async-trait) para implementar traits con -/// métodos `async`. +/// Re-exporta el atributo [`async_trait`] para implementar traits con métodos `async`. /// /// Si en el ámbito se declara `use pagetop::prelude::*` o `use pagetop::async_trait;` basta con /// usar el nombre corto `#[async_trait]`. Otra opción es usar su forma cualificada @@ -133,8 +132,13 @@ pub const PAGETOP_VERSION: &str = env!("CARGO_PKG_VERSION"); /// `Cargo.toml` del proyecto. /// /// En proyectos que crean extensiones de PageTop, su uso es necesario cuando se sobrescribe -/// [`initialize()`](crate::core::extension::Extension::initialize) en un bloque -/// [`impl Extension`](crate::core::extension::Extension). +/// [`initialize()`], [`start()`] o [`shutdown()`] en un bloque [`impl Extension`]. +/// +/// [`async_trait`]: https://docs.rs/async-trait +/// [`initialize()`]: crate::core::extension::Extension::initialize +/// [`start()`]: crate::core::extension::Extension::start +/// [`shutdown()`]: crate::core::extension::Extension::shutdown +/// [`impl Extension`]: crate::core::extension::Extension pub use async_trait::async_trait; pub use pagetop_macros::{AutoDefault, builder_fn, builder_impl, html, main, settings, test}; @@ -172,8 +176,9 @@ impl Deref for StaticResources { /// Alias para un error cualquiera, `Box`. /// -/// Lo devuelve [`Extension::initialize()`](crate::core::extension::Extension::initialize) para que -/// cada extensión pueda propagar con `?` sus propios tipos de error sin convertirlos. +/// Lo devuelven [`Extension::initialize()`](crate::core::extension::Extension::initialize) y +/// [`Extension::start()`](crate::core::extension::Extension::start) para que cada extensión pueda +/// propagar con `?` sus propios tipos de error sin convertirlos. pub type BoxError = Box; /// Alias para `Cow<'static, str>`.