`configure_router()` recibe Routes, que no monta ninguna ruta sin su Access: `route()`, `public_route()` y `admin_route()`, que toma el permiso de la página del panel de la que cuelga. Una ruta del panel montada de otra forma impide arrancar. `configure_middleware()` recibe Layers y `configure_static_files()` recibe StaticFiles, siempre públicos.
365 lines
16 KiB
Rust
365 lines
16 KiB
Rust
//! Prepara y ejecuta una aplicación creada con PageTop.
|
|
|
|
mod figfont;
|
|
|
|
use crate::admin;
|
|
use crate::core::extension;
|
|
use crate::core::extension::ExtensionRef;
|
|
use crate::core::extension::all::StartupError;
|
|
use crate::core::theme;
|
|
use crate::datetime::Timezone;
|
|
use crate::locale::Locale;
|
|
use crate::response::route_not_found;
|
|
use crate::response::{keep_flash_messages, render_error_pages, response_for_panic};
|
|
use crate::web::{Request, Response, Router, http, reject_cross_origin};
|
|
use crate::{PAGETOP_VERSION, global, trace};
|
|
|
|
use axum::extract::DefaultBodyLimit;
|
|
use axum::middleware::Next;
|
|
use tower::{Layer, ServiceExt};
|
|
use tower_http::catch_panic::CatchPanicLayer;
|
|
use tracing_appender::non_blocking::WorkerGuard;
|
|
|
|
use std::io::Error;
|
|
|
|
/// Punto de entrada de una aplicación PageTop.
|
|
///
|
|
/// Orquesta el arranque de la aplicación. Primero se instancia con [`Application::new()`] o
|
|
/// [`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),
|
|
/// [`Theme::error_404()`](crate::core::theme::Theme::error_404) y
|
|
/// [`Theme::error_fatal()`](crate::core::theme::Theme::error_fatal)).
|
|
///
|
|
/// 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 {
|
|
// Vuelca las trazas pendientes al destruirse, cuando termina `run()` (ver `trace::init()`).
|
|
tracing: Option<WorkerGuard>,
|
|
}
|
|
|
|
impl Application {
|
|
/// Crea una instancia mínima de la aplicación, sin extensión raíz.
|
|
///
|
|
/// Útil para verificar que el servidor arranca correctamente. Para una aplicación real, usa
|
|
/// [`prepare()`](Application::prepare) con una extensión raíz.
|
|
pub async fn new() -> Self {
|
|
Self::internal_prepare(None).await
|
|
}
|
|
|
|
/// Prepara una instancia de la aplicación a partir de una extensión raíz.
|
|
///
|
|
/// Inicializa la aplicación habilitando las extensiones en orden de dependencia: primero las
|
|
/// que no dependen de ninguna otra, luego las que dependen de extensiones ya habilitadas, y así
|
|
/// hasta habilitar la extensión raíz.
|
|
///
|
|
/// Es `async` porque cada extensión puede realizar operaciones asíncronas en su `initialize()`
|
|
/// (conexión a base de datos, migraciones, semillas de datos, etc.).
|
|
///
|
|
/// Si los ajustes de alguna extensión no se pueden cargar o alguna extensión devuelve un error
|
|
/// al inicializarse, detiene el arranque y termina el proceso con el código de salida `1` (ver
|
|
/// [`Extension::settings()`] y [`Extension::initialize()`]).
|
|
///
|
|
/// [`Extension::settings()`]: crate::core::extension::Extension::settings
|
|
/// [`Extension::initialize()`]: crate::core::extension::Extension::initialize
|
|
pub async fn prepare(root_extension: ExtensionRef) -> Self {
|
|
Self::internal_prepare(Some(root_extension)).await
|
|
}
|
|
|
|
// Secuencia de arranque común a new() y prepare().
|
|
async fn internal_prepare(root_extension: Option<ExtensionRef>) -> Self {
|
|
// Comprueba la configuración global antes de usarla. Un error detiene aquí el arranque.
|
|
if let Err(err) = global::check_settings() {
|
|
Self::abort_startup(None, err);
|
|
}
|
|
|
|
// Al arrancar muestra una cabecera para la aplicación.
|
|
Self::show_banner();
|
|
|
|
// Inicia gestión de trazas y registro de eventos (logging).
|
|
let tracing = trace::init();
|
|
|
|
// Inicializa el idioma predeterminado.
|
|
Locale::init();
|
|
|
|
// Inicializa la zona horaria predeterminada y las regiones para elegir.
|
|
Timezone::init();
|
|
|
|
// Registra las extensiones de la aplicación.
|
|
extension::all::register_extensions(root_extension);
|
|
|
|
// Carga los ajustes de las extensiones. Un error de configuración detiene aquí el arranque.
|
|
if let Err(err) = extension::all::load_settings() {
|
|
Self::abort_startup(tracing, err);
|
|
}
|
|
|
|
// Inicializa el tema predeterminado, que ya puede ser el de una extensión.
|
|
theme::all::init_default_theme();
|
|
|
|
// Registra las acciones de las extensiones.
|
|
extension::all::register_actions();
|
|
|
|
// Inicializa las extensiones. Si alguna falla, detiene aquí el arranque.
|
|
if let Err(err) = extension::all::initialize_extensions().await {
|
|
Self::abort_startup(tracing, err);
|
|
}
|
|
|
|
Self { tracing }
|
|
}
|
|
|
|
// 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.
|
|
fn abort_startup(tracing: Option<WorkerGuard>, err: StartupError) -> ! {
|
|
let mut message = err.to_string();
|
|
let mut source = std::error::Error::source(&err);
|
|
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();
|
|
}
|
|
trace::error!("{message}");
|
|
drop(tracing);
|
|
eprintln!("{message}");
|
|
std::process::exit(1);
|
|
}
|
|
|
|
// Muestra la cabecera de arranque si está habilitada en la configuración.
|
|
fn show_banner() {
|
|
use colored::Colorize;
|
|
use terminal_size::{Width, terminal_size};
|
|
|
|
if global::SETTINGS.app.startup_banner != global::StartupBanner::Off {
|
|
// Nombre de la aplicación, ajustado al ancho del terminal si es necesario.
|
|
let mut app_ff = String::new();
|
|
let app_name = &global::SETTINGS.app.name;
|
|
if let Some((Width(term_width), _)) = terminal_size()
|
|
&& term_width >= 80
|
|
{
|
|
let maxlen: usize = ((term_width / 10) - 2).into();
|
|
let mut app: String = app_name.chars().take(maxlen).collect();
|
|
if app_name.chars().count() > maxlen {
|
|
app = format!("{app}...");
|
|
}
|
|
if let Some(ff) = figfont::FIGFONT.convert(&app) {
|
|
app_ff = ff.to_string();
|
|
}
|
|
}
|
|
if app_ff.is_empty() {
|
|
println!("\n{app_name}");
|
|
} else {
|
|
print!("\n{app_ff}");
|
|
}
|
|
|
|
// Versión de PageTop.
|
|
println!(
|
|
"{} {}\n",
|
|
"Powered by PageTop".yellow(),
|
|
PAGETOP_VERSION.yellow()
|
|
);
|
|
}
|
|
}
|
|
|
|
/// 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 = match Self::build_router() {
|
|
Ok(router) => router,
|
|
Err(err) => Self::abort_startup(self.tracing.take(), err),
|
|
};
|
|
|
|
// 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)?;
|
|
// Con la dirección de cada conexión, para `HttpRequest::client_ip()`.
|
|
let service = router.into_make_service_with_connect_info::<std::net::SocketAddr>();
|
|
let result = axum::serve(listener, service)
|
|
.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.
|
|
///
|
|
/// # Panics
|
|
///
|
|
/// Si alguna ruta del panel de administración está mal montada (ver
|
|
/// [`Routes`](crate::web::Routes)), que con [`run()`](Self::run) detendría el arranque.
|
|
pub fn test(self) -> Router {
|
|
Self::build_router().unwrap_or_else(|err| panic!("{err}"))
|
|
}
|
|
|
|
// Construye el router con las rutas, el middleware y los archivos estáticos de todas las
|
|
// extensiones habilitadas.
|
|
//
|
|
// Las capas del servidor web sólo envuelven las rutas (y el `fallback`) registradas antes de
|
|
// añadirlas, así que los archivos estáticos se registran después del middleware de las
|
|
// extensiones para no pasar por él. Una página con muchos recursos repetiría, si no, el mismo
|
|
// trabajo (resolver la sesión, etc.) por cada uno. El `fallback` de rutas inexistentes, en
|
|
// cambio, se registra antes: la página 404 debe ver lo que el middleware añade a la petición
|
|
// (p. ej. el usuario actual).
|
|
//
|
|
// Cada ruta comprueba su acceso (`web::Routes`) después de pasar por el middleware de las
|
|
// extensiones, cuando éste ya ha resuelto el usuario actual. Si alguna ruta del panel de
|
|
// administración está mal montada, se devuelve un error y la aplicación no arranca.
|
|
//
|
|
// Los mensajes *flash* (`keep_flash_messages()`) se registran junto al middleware de las
|
|
// extensiones, también antes de los archivos estáticos, que no los muestran.
|
|
//
|
|
// La protección CSRF (`web::reject_cross_origin()`) va por fuera del middleware de las
|
|
// extensiones: una petición rechazada no llega a resolver la sesión.
|
|
//
|
|
// El límite del cuerpo de las peticiones (`limit_body()`) sustituye al de Axum en todas las
|
|
// rutas.
|
|
//
|
|
// Las capas de páginas de error y `CatchPanicLayer` cubren todo, porque se añaden al final. Con
|
|
// `CatchPanicLayer` en la última capa se capturan incluso los `panic!` que se produzcan dentro
|
|
// del propio renderizado de una página de error.
|
|
fn build_router() -> Result<Router, StartupError> {
|
|
let router = extension::all::configure_routes(Router::new())?;
|
|
let router = admin::configure_routes(router).fallback(route_not_found);
|
|
let router = extension::all::configure_middleware(router)
|
|
.layer(axum::middleware::from_fn(keep_flash_messages));
|
|
let router = extension::all::configure_static_files(router);
|
|
Ok(router
|
|
.layer(axum::middleware::from_fn(reject_cross_origin))
|
|
.layer(axum::middleware::from_fn(limit_body))
|
|
.layer(axum::middleware::from_fn(render_error_pages))
|
|
.layer(CatchPanicLayer::custom(response_for_panic)))
|
|
}
|
|
}
|
|
|
|
// Fija el límite del cuerpo de la petición según su tipo de contenido. Un envío
|
|
// `multipart/form-data` escribe sus archivos en disco a medida que llegan, así que admite
|
|
// `upload.max_request_size`; el resto de cuerpos se leen enteros en memoria y se limitan con
|
|
// `server.max_body_size`. Otro tipo de contenido no se beneficia del límite mayor: el extractor
|
|
// `Multipart` exige `multipart/form-data`, y `Form` o `Json` rechazan la petición sin leer el
|
|
// cuerpo si no llega con el suyo.
|
|
async fn limit_body(request: Request, next: Next) -> Response {
|
|
let multipart = request
|
|
.headers()
|
|
.get(http::header::CONTENT_TYPE)
|
|
.and_then(|value| value.to_str().ok())
|
|
.and_then(|value| value.get(..19))
|
|
.is_some_and(|essence| essence.eq_ignore_ascii_case("multipart/form-data"));
|
|
let max = if multipart {
|
|
global::SETTINGS.upload.max_request_size
|
|
} else {
|
|
global::SETTINGS.server.max_body_size
|
|
};
|
|
let limit = match max {
|
|
0 => DefaultBodyLimit::disable(),
|
|
max => DefaultBodyLimit::max(max),
|
|
};
|
|
let Ok(response) = limit.layer(next).oneshot(request).await;
|
|
response
|
|
}
|
|
|
|
// 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, not waiting for requests or services in progress");
|
|
std::process::exit(130);
|
|
}
|
|
});
|
|
}
|