✨ (core): Añade start() y shutdown() a Extension

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.
This commit is contained in:
Manuel Cillero 2026-10-27 20:26:09 +01:00
parent bd54980d0f
commit 4c3f4dab1b
4 changed files with 296 additions and 65 deletions

View file

@ -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);
}
});

View file

@ -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<Vec<String>>,
}
#[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<String>>) -> Vec<String> {
log.lock().unwrap().clone()
}
#[tokio::test]
async fn all_services_start_in_order_without_shutdown() {
static LOG: Mutex<Vec<String>> = 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<Vec<String>> = 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<Vec<String>> = 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"]);
}
}

View file

@ -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.
///

View file

@ -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<dyn std::error::Error + Send + Sync>`.
///
/// 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<dyn std::error::Error + Send + Sync>;
/// Alias para `Cow<'static, str>`.