diff --git a/src/app.rs b/src/app.rs index 34374d43..813d0a0a 100644 --- a/src/app.rs +++ b/src/app.rs @@ -10,9 +10,9 @@ use crate::web::Router; use crate::{PAGETOP_VERSION, global, trace}; use tower_http::catch_panic::CatchPanicLayer; +use tracing_appender::non_blocking::WorkerGuard; use std::io::Error; -use std::sync::LazyLock; /// Punto de entrada de una aplicación PageTop. /// @@ -20,6 +20,11 @@ use std::sync::LazyLock; /// [`Application::prepare()`], y después se ejecuta usando [`run()`](Application::run). Si se está /// preparando un entorno de pruebas, se usa [`test()`](Application::test). /// +/// Hay **una aplicación por proceso**: la configuración, las extensiones habilitadas, el tema +/// predeterminado y las trazas se inician una sola vez, con la primera que se prepara. Preparar más +/// en el mismo proceso, como hacen las pruebas de integración para obtener su router, reutilizaría +/// todos estos recursos. +/// /// Los **errores controlados** (403, 404, o un fallo que un handler devuelva explícitamente como /// [`ErrorPage`](crate::response::ErrorPage)) se renderizan usando el tema activo (ver /// [`Theme::error_403()`](crate::core::theme::Theme::error_403), @@ -29,7 +34,10 @@ use std::sync::LazyLock; /// La última capa del router captura cualquier **fallo catastrófico** (`panic!`) de la aplicación /// en lugar de abortar la conexión. Devuelve una respuesta mínima HTTP 500 que es independiente del /// tema y del ciclo de renderizado de componentes. -pub struct Application; +pub struct Application { + // Vuelca las trazas pendientes al destruirse, cuando termina `run()` (ver `trace::init()`). + tracing: Option, +} impl Application { /// Crea una instancia mínima de la aplicación, sin extensión raíz. @@ -59,7 +67,7 @@ impl Application { Self::show_banner(); // Inicia gestión de trazas y registro de eventos (logging). - LazyLock::force(&trace::TRACING); + let tracing = trace::init(); // Inicializa el idioma predeterminado. Locale::init(); @@ -79,7 +87,7 @@ impl Application { // Inicializa las extensiones. extension::all::initialize_extensions().await; - Self + Self { tracing } } // Muestra la cabecera de arranque si está habilitada en la configuración. @@ -134,8 +142,14 @@ 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. El - /// patrón habitual es: + /// 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::*; @@ -164,7 +178,13 @@ impl Application { let router = Self::build_router(); let listener = tokio::net::TcpListener::from_std(std_listener)?; - axum::serve(listener, router).await + 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. @@ -172,3 +192,46 @@ impl Application { Self::build_router() } } + +// Espera la señal para detener el servidor: Ctrl+C o, en Unix, `SIGTERM`. Si no se puede escuchar +// alguna, espera sólo a la otra en lugar de detener el servidor nada más arrancar. +async fn shutdown_signal() { + let ctrl_c = async { + if let Err(err) = tokio::signal::ctrl_c().await { + trace::error!("Cannot listen for Ctrl+C: {err}"); + std::future::pending::<()>().await; + } + }; + + #[cfg(unix)] + let terminate = async { + use tokio::signal::unix::{SignalKind, signal}; + match signal(SignalKind::terminate()) { + Ok(mut sigterm) => { + sigterm.recv().await; + } + Err(err) => { + trace::error!("Cannot listen for SIGTERM: {err}"); + std::future::pending::<()>().await; + } + } + }; + #[cfg(not(unix))] + let terminate = std::future::pending::<()>(); + + tokio::select! { + () = ctrl_c => {} + () = terminate => {} + } + trace::info!("Shutting down, finishing the requests in progress"); + + // Una vez capturada, Ctrl+C ya no detiene el proceso por sí sola: una segunda lo detiene en el + // acto si alguna petición en curso no termina. El aviso va directamente a la salida de errores + // 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"); + std::process::exit(130); + } + }); +} diff --git a/src/trace.rs b/src/trace.rs index acb88641..3d8d32b9 100644 --- a/src/trace.rs +++ b/src/trace.rs @@ -23,7 +23,8 @@ use tracing_appender::non_blocking::WorkerGuard; use tracing_subscriber::EnvFilter; use std::fmt; -use std::sync::{LazyLock, Mutex, PoisonError}; +use std::sync::atomic::{AtomicBool, Ordering}; +use std::sync::{Mutex, PoisonError}; // Avisos generados antes de iniciar las trazas. La configuración se lee antes, porque las trazas // dependen de la sección `[log]`, así que sus avisos se guardan aquí y se emiten al iniciarlas. @@ -41,14 +42,26 @@ pub(crate) fn warn_invalid_setting(key: &str, raw: &str, default: default } -/// Trazado y registro de eventos de la aplicación. -/// -/// La escritura no es bloqueante: el código que genera una traza o un evento la deja en una cola y -/// sigue, y un hilo dedicado la escribe en el destino configurado en cuanto la recibe. -/// -/// El [`WorkerGuard`] vuelca las trazas pendientes al destruirse, pero un `static` no se destruye -/// nunca, así que al terminar el programa pueden perderse las últimas que quedaran en la cola. -pub(crate) static TRACING: LazyLock = LazyLock::new(|| { +// Inicia las trazas y el registro de eventos de la aplicación, sólo la primera vez que se llama. +// +// La escritura no es bloqueante: el código que genera una traza o un evento la deja en una cola y +// sigue, y un hilo dedicado la escribe en el destino configurado en cuanto la recibe. Devuelve el +// `WorkerGuard` que vuelca las trazas pendientes al destruirse, y que debe vivir mientras la +// aplicación: `Application` lo guarda y lo destruye al terminar `run()`. Devuelve `None` en las +// llamadas siguientes y si las trazas están desactivadas. +// +// Si el programa termina sin destruirlo (con `std::process::exit()`, como hace una segunda Ctrl+C, +// con `SIGKILL` o con un `panic!` compilado con `panic = "abort"`), pueden perderse las últimas +// trazas de la cola. +pub(crate) fn init() -> Option { + // Si ya se han iniciado las trazas: el *subscriber* global sólo puede instalarse una vez por + // proceso, y las pruebas pueden preparar varias aplicaciones. + static STARTED: AtomicBool = AtomicBool::new(false); + + if STARTED.swap(true, Ordering::SeqCst) { + return None; + } + let enabled = global::SETTINGS.log.enabled && !cfg!(test) && !cfg!(feature = "testing"); // Al leer `SETTINGS` en la línea anterior ya se han guardado los avisos de la configuración. let mut warnings = std::mem::take( @@ -60,12 +73,11 @@ pub(crate) static TRACING: LazyLock = LazyLock::new(|| { // Tracing desactivado, se instala un subscriber nulo. tracing::subscriber::set_global_default(tracing::subscriber::NoSubscriber::default()) .expect("Failed to install global NoSubscriber (tracing disabled)"); - let (_, guard) = tracing_appender::non_blocking(std::io::sink()); // Los avisos pendientes salen por la salida estándar para que no se pierdan. for message in warnings { println!("\n{message}"); } - return guard; + return None; } let filter = &global::SETTINGS.log.tracing; @@ -108,5 +120,6 @@ pub(crate) static TRACING: LazyLock = LazyLock::new(|| { for message in warnings { warn!(target: "pagetop::global", "{message}"); } - guard -}); + + Some(guard) +}