✨ (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:
parent
bd54980d0f
commit
4c3f4dab1b
4 changed files with 296 additions and 65 deletions
132
src/app.rs
132
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);
|
||||
}
|
||||
});
|
||||
|
|
|
|||
|
|
@ -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"]);
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
///
|
||||
|
|
|
|||
17
src/lib.rs
17
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<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>`.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue