//! Servidor web y rutas de la aplicación (basado en [Axum](https://docs.rs/axum)). //! //! Define rutas y handlers: el [`Router`], las operaciones HTTP ([`get`], [`post`], [`put`], //! [`delete`], [`patch`]), los extractores ([`Path`], [`Query`], [`Form`], [`RawForm`], //! [`Multipart`], [`Request`], [`ConnectInfo`]) e [`IntoResponse`], el módulo [`middleware`] para //! *middlewares* de función, y re-exporta el módulo `http` para tipos de bajo nivel como //! `StatusCode`, `HeaderName` o `Method`. También ofrece utilidades para servir archivos estáticos, //! [`ServeDir`] y [`ServeEmbedded`], para recibir y guardar los archivos subidos en formularios, //! [`Upload`], y para servirlos después con control de acceso, [`Download`]. //! //! Los handlers son las funciones asíncronas que el servidor invoca al recibir una petición HTTP en //! una ruta concreta. use crate::{StaticFile, global}; #[doc(inline)] pub use axum::http; // Infraestructura del router. pub use axum::Router; // Extractores de petición. pub use axum::extract::{ConnectInfo, Form, Multipart, Path, Query, RawForm, Request}; // Partes y errores del extractor `Multipart`. pub use axum::extract::multipart; // Para implementar respuestas. pub use axum::response::{IntoResponse, Response}; // Operaciones HTTP para registrar rutas. pub use axum::routing::{delete, get, patch, post, put}; // Middlewares de función (`from_fn`) y tipos asociados (`Next`). pub use axum::middleware; // Guardado de los archivos subidos en formularios `multipart/form-data`. mod upload; pub(crate) use upload::push_percent_encoded; pub use upload::{Upload, UploadError, UploadedFile, UploadedForm}; // Respuestas con los archivos subidos. mod download; pub use download::Download; use axum::body::Body; use axum::extract::FromRequestParts; use std::collections::HashMap; use std::convert::Infallible; use std::net::{IpAddr, SocketAddr}; use std::sync::Arc; use std::task::{Context, Poll}; // **< HttpRequest >******************************************************************************** /// Representa una petición HTTP. /// /// Almacena los datos necesarios para negociar el idioma y renderizar las páginas de error, /// incluyendo la URI completa, las cabeceras de la petición original y las extensiones de tipo que /// los *middlewares* pueden inyectar antes de que el handler se ejecute. /// /// Puede declararse directamente como parámetro en un handler para pasarlo al /// [`Context`](crate::core::component::Context) de renderizado y a las variantes de /// [`ErrorPage`](crate::response::ErrorPage): /// /// ```rust,no_run /// # use pagetop::prelude::*; /// async fn my_handler(request: HttpRequest) -> Result { /// // ... /// # todo!() /// } /// ``` /// /// Las extensiones inyectadas por middleware son accesibles vía [`extension`](Self::extension). Por /// ejemplo, desde un handler, tras añadir `MyData` en un middleware: /// /// ```rust,ignore /// if let Some(data) = request.extension::() { /// // ... /// } /// ``` /// /// `HttpRequest` no consume las extensiones de la petición, por lo que el resto de extractores del /// handler que también las necesiten (como `Path`, `Extension`, etc.) las siguen viendo /// intactas, sea cual sea la posición en la que se declare `HttpRequest`. Por convención, se /// declara como primer parámetro del handler. El único orden que sigue siendo obligatorio es el que /// impone Axum: un extractor que consuma el cuerpo de la petición (`Form`, `RawForm`, etc.) debe /// ir siempre el último. #[derive(Clone, Debug)] pub struct HttpRequest(Arc); // Datos de la petición. Se guardan tras un `Arc` para que `HttpRequest` ocupe un puntero y clonarlo // sea una simple cuenta de referencias: viaja dentro de `ErrorPage` y de los `Result<_, ErrorPage>` // de los handlers, donde un tipo grande se copiaría en cada retorno. #[derive(Debug)] struct RequestParts { uri: http::Uri, headers: http::HeaderMap, extensions: http::Extensions, } impl HttpRequest { /// Devuelve la URI completa de la petición, incluyendo la *query string* si la hay. pub fn uri(&self) -> &str { self.0 .uri .path_and_query() .map(|pq| pq.as_str()) .unwrap_or("/") } /// Devuelve la ruta (*path*) de la petición, sin la *query string*. pub fn path(&self) -> &str { self.0.uri.path() } /// Devuelve la cadena de consulta (*query string*) de la petición, sin el carácter `?`. /// /// Devuelve una cadena vacía si la petición no tiene *query string*. pub fn query_string(&self) -> &str { self.0.uri.query().unwrap_or("") } /// Devuelve las cabeceras HTTP de la petición. pub fn headers(&self) -> &http::HeaderMap { &self.0.headers } /// Accede a un valor inyectado por middleware en las extensiones de la petición. /// /// Devuelve una referencia al tipo `T` si algún middleware lo insertó antes de que el handler /// recibiera la petición, o `None` en caso contrario. /// /// El tipo debe implementar `Send + Sync + 'static` (requisito de [`http::Extensions`]). pub fn extension(&self) -> Option<&T> { self.0.extensions.get::() } /// Devuelve la dirección IP del cliente que hace la petición, si se conoce. /// /// Por defecto es la dirección desde la que llega la conexión. Detrás de un *proxy* inverso o /// de un balanceador, esa dirección es siempre la del *proxy*: entonces hay que indicar en /// [`client_ip_header`](crate::global::ServerSettings::client_ip_header) de `[server]` la /// cabecera en la que el *proxy* escribe la dirección del cliente. /// /// Las direcciones IPv4 se devuelven siempre como tales, también las que llegan en forma IPv6 /// (`::ffff:192.0.2.1`), como ocurre al escuchar en `"::"`: así una misma dirección es siempre /// el mismo valor. /// /// Devuelve `None` si la cabecera configurada falta o no contiene una dirección válida (nunca /// la de la conexión, que sería la del *proxy*), y en las pruebas, que no abren conexiones /// (salvo que la petición incluya [`ConnectInfo`]). pub fn client_ip(&self) -> Option { let header = global::SETTINGS.server.client_ip_header.as_str(); let ip = if header.is_empty() { self.extension::>() .map(|ConnectInfo(addr)| addr.ip()) } else { ip_from_header(&self.0.headers, header) }; ip.map(|ip| ip.to_canonical()) } } // Dirección IP de la cabecera `name`. Si la cabecera se repite o tiene varias direcciones separadas // por comas (como `X-Forwarded-For`), vale la última: la que añadió el último *proxy*, el de la // propia aplicación. Las anteriores las envía el cliente y puede inventarlas. fn ip_from_header(headers: &http::HeaderMap, name: &str) -> Option { let value = headers.get_all(name).iter().next_back()?.to_str().ok()?; let last = value.rsplit(',').next()?.trim(); last.parse().ok().or_else(|| { // Una dirección IPv4 o IPv6 con puerto (`203.0.113.7:4711`, `[2001:db8::1]:4711`). last.parse::().ok().map(|addr| addr.ip()) }) } impl FromRequestParts for HttpRequest { type Rejection = Infallible; // Clona (no toma) las extensiones inyectadas por middleware, para que otros extractores del // handler (`Path`, `Extension`, etc.) las sigan viendo intactas sin importar en qué // posición se declare `HttpRequest`. Todo se guarda tras un `Arc` compartido para que // `HttpRequest` sea `Clone` a coste mínimo en el resto de su ciclo de vida. async fn from_request_parts( parts: &mut http::request::Parts, _state: &S, ) -> Result { Ok(HttpRequest(Arc::new(RequestParts { uri: parts.uri.clone(), headers: parts.headers.clone(), extensions: parts.extensions.clone(), }))) } } // **< ServeDir >*********************************************************************************** // Servicio para archivos estáticos en disco. pub use tower_http::services::ServeDir; // Valor de `Cache-Control` para los archivos estáticos: el navegador puede guardarlos, pero debe // revalidarlos antes de reutilizarlos. Las versiones de las URL (`?v=...`) no siguen el contenido // de cada archivo, así que una caché con caducidad podría servir recursos obsoletos tras desplegar. const STATIC_CACHE_CONTROL: http::HeaderValue = http::HeaderValue::from_static("no-cache"); /// Servicio para archivos estáticos en disco con la política de caché de PageTop. /// /// Lo usa la macro [`serve_static_files!`](crate::serve_static_files). [`ServeDir`] ya envía /// `Last-Modified` y `ETag`, y responde `304 Not Modified` cuando corresponde; este servicio añade /// `Cache-Control: no-cache` para que el navegador revalide los archivos en lugar de reutilizarlos /// sin preguntar. #[doc(hidden)] pub fn serve_dir( dir: impl AsRef, ) -> tower_http::set_header::SetResponseHeader { tower_http::set_header::SetResponseHeader::if_not_present( ServeDir::new(dir), http::header::CACHE_CONTROL, STATIC_CACHE_CONTROL, ) } // **< ServeEmbedded >****************************************************************************** /// Servicio para archivos estáticos embebidos en el binario. /// /// Creado por la macro [`serve_static_files!`](crate::serve_static_files) en los modos que incluyen /// recursos embebidos. Estos recursos se identifican por su ruta relativa sin la barra inicial /// (p. ej. `"css/style.css"`). Si se solicita la raíz o una ruta que termina en `/`, el servicio /// devuelve el `index.html` raíz si existe; no busca por subdirectorio. /// /// Cada respuesta incluye un `ETag` calculado sobre el contenido del recurso y /// `Cache-Control: no-cache`, de modo que el navegador guarda el recurso pero lo revalida antes de /// reutilizarlo; si no ha cambiado, el servicio responde `304 Not Modified` sin cuerpo. /// /// Implementa [`Clone`] para clonar el servicio por petición, pero internamente comparte el mapa de /// recursos con un [`Arc`] para evitar copias innecesarias. #[derive(Clone)] pub struct ServeEmbedded { files: Arc>, } // Recurso embebido con su `ETag`, calculado una sola vez al crear el servicio. struct EmbeddedFile { data: &'static [u8], mime_type: &'static str, etag: http::HeaderValue, } impl ServeEmbedded { /// Crea un nuevo servicio a partir del mapa de recursos embebidos generado por `build.rs`. pub fn new(files: HashMap<&'static str, StaticFile>) -> Self { let files = files .into_iter() .map(|(path, file)| { let embedded = EmbeddedFile { data: file.data, mime_type: file.mime_type, etag: etag_for(file.data), }; (path, embedded) }) .collect(); Self { files: Arc::new(files), } } } // `ETag` de un recurso a partir de su contenido. `DefaultHasher::new()` usa siempre las mismas // claves, así que el valor sólo cambia si cambia el contenido (o el algoritmo, al actualizar Rust, // lo que únicamente obliga a descargar de nuevo los recursos). fn etag_for(data: &[u8]) -> http::HeaderValue { use std::hash::{DefaultHasher, Hasher}; let mut hasher = DefaultHasher::new(); hasher.write(data); http::HeaderValue::try_from(format!("\"{:016x}\"", hasher.finish())) .expect("a quoted hexadecimal string is always a valid header value") } // Si alguna etiqueta de `If-None-Match` coincide con `etag`. La comparación es débil, como exige // RFC 9110 para `If-None-Match`: se ignora el prefijo `W/`. fn matches_etag(req: &http::Request, etag: &http::HeaderValue) -> bool { req.headers() .get_all(http::header::IF_NONE_MATCH) .iter() .filter_map(|value| value.to_str().ok()) .flat_map(|tags| tags.split(',')) .map(str::trim) .any(|tag| { tag == "*" || tag.strip_prefix("W/").unwrap_or(tag).as_bytes() == etag.as_bytes() }) } impl tower::Service> for ServeEmbedded { type Response = http::Response; type Error = Infallible; type Future = std::future::Ready>; fn poll_ready(&mut self, _: &mut Context<'_>) -> Poll> { Poll::Ready(Ok(())) } fn call(&mut self, req: http::Request) -> Self::Future { use axum::http::header; // Axum elimina el prefijo de montaje: la ruta restante puede o no comenzar con '/'. let path = req.uri().path().trim_start_matches('/'); // Busca la ruta exacta; si es raíz o directorio, intenta index.html. let resource = self.files.get(path).or_else(|| { if path.is_empty() || path.ends_with('/') { self.files.get("index.html") } else { None } }); let response = match resource { Some(file) if matches_etag(&req, &file.etag) => http::Response::builder() .status(http::StatusCode::NOT_MODIFIED) .header(header::ETAG, file.etag.clone()) .header(header::CACHE_CONTROL, STATIC_CACHE_CONTROL) .body(Body::empty()) .unwrap(), Some(file) => http::Response::builder() .header(header::CONTENT_TYPE, file.mime_type) .header(header::ETAG, file.etag.clone()) .header(header::CACHE_CONTROL, STATIC_CACHE_CONTROL) .body(Body::from(file.data)) .unwrap(), None => http::Response::builder() .status(http::StatusCode::NOT_FOUND) .body(Body::empty()) .unwrap(), }; std::future::ready(Ok(response)) } } // **< serve_static_files! >************************************************************************ /// Configura el servidor web para publicar archivos estáticos. /// /// Se usa normalmente en el método [`configure_static_files()`] de las extensiones, para que estas /// rutas no pasen por su middleware. /// /// La macro añade rutas al [`Router`] del primer argumento usando uno de los tres modos posibles: /// /// - **Sistema de ficheros o embebido** (`[$dir, $bundle]`): intenta servir los archivos desde el /// directorio `$dir`; si está vacío, no existe o no es un directorio, usa el conjunto de recursos /// `$bundle` embebido. /// - **Sólo embebido** (`[$bundle]`): sirve siempre desde el conjunto de recursos embebido en el /// binario. /// - **Sólo sistema de ficheros** (`$dir`): sin corchetes, sirve únicamente desde el directorio si /// existe. /// /// # Argumentos /// /// * `$router` - Variable de tipo [`Router`] donde registrar las rutas. /// * `$dir` - Ruta al directorio local con los archivos estáticos. /// * `$bundle` - Nombre del conjunto de recursos embebidos generado por `build.rs`. /// * `$path` - Prefijo URL bajo el que se publicarán los archivos. /// /// # Ejemplos /// /// ```rust,ignore /// # use pagetop::prelude::*; /// pub struct MyExtension; /// /// #[async_trait] /// impl Extension for MyExtension { /// fn configure_static_files(&self, router: Router) -> Router { /// // Forma 1) Sistema de ficheros o embebido. /// serve_static_files!(router, ["/var/www/static", assets] => "/public"); /// /// // Forma 2) Siempre embebido. /// serve_static_files!(router, [assets] => "/public"); /// /// // Forma 3) Sólo sistema de ficheros (no requiere `assets`). /// serve_static_files!(router, "/var/www/static" => "/public"); /// /// router /// } /// } /// ``` /// /// [`configure_static_files()`]: crate::core::extension::Extension::configure_static_files #[macro_export] macro_rules! serve_static_files { // Forma 1: primero intenta servir desde el sistema de ficheros; si falla, sirve embebido. ( $router:ident, [$dir:expr, $bundle:ident] => $path:expr $(,)? ) => { let $router = { let _span = $crate::trace::debug_span!( "serve_static_files", mode = "filesystem_or_embedded", route = $path, ) .entered(); let mut __r = $router; let mut served_from_fs = false; if !::std::path::Path::new(&$dir).as_os_str().is_empty() { if let Ok(absolute) = $crate::util::resolve_absolute_dir($dir) { __r = __r.nest_service($path, $crate::web::serve_dir(absolute)); served_from_fs = true; } } if !served_from_fs { $crate::util::paste! { mod [] { include!(concat!(env!("OUT_DIR"), "/", stringify!($bundle), ".rs")); } __r = __r.nest_service( $path, $crate::web::ServeEmbedded::new( []::$bundle(), ), ); } } __r }; }; // Forma 2: sirve siempre embebido. ( $router:ident, [$bundle:ident] => $path:expr $(,)? ) => { let $router = { let _span = $crate::trace::debug_span!( "serve_static_files", mode = "embedded_only", route = $path, ) .entered(); $crate::util::paste! { mod [] { include!(concat!(env!("OUT_DIR"), "/", stringify!($bundle), ".rs")); } $router.nest_service( $path, $crate::web::ServeEmbedded::new( []::$bundle(), ), ) } }; }; // Forma 3: intenta servir desde el sistema de ficheros. ( $router:ident, $dir:expr => $path:expr $(,)? ) => { let $router = { let _span = $crate::trace::debug_span!( "serve_static_files", mode = "filesystem_only", route = $path, ) .entered(); match $crate::util::resolve_absolute_dir($dir) { Ok(absolute) => $router.nest_service($path, $crate::web::serve_dir(absolute)), Err(e) => { $crate::trace::warn!( "Static dir not found or invalid for route `{}`: {} ({e})", $path, $dir, ); $router } } }; }; } // **< Utilidades de test >************************************************************************* /// Utilidades para escribir pruebas de integración con PageTop sobre Axum. #[doc(hidden)] pub mod test { use axum::Router; use axum::body::Body; use axum::http; use tower::ServiceExt; /// Devuelve el router tal como se recibe, listo para usarse en pruebas de integración. pub fn init_router(router: Router) -> Router { router } /// Constructor de peticiones HTTP para pruebas. pub struct TestRequest { method: http::Method, uri: String, headers: http::HeaderMap, extensions: http::Extensions, body: String, } impl TestRequest { /// Crea una petición GET. pub fn get() -> Self { Self::with_method(http::Method::GET) } /// Crea una petición POST. pub fn post() -> Self { Self::with_method(http::Method::POST) } /// Crea una petición PUT. pub fn put() -> Self { Self::with_method(http::Method::PUT) } /// Crea una petición PATCH. pub fn patch() -> Self { Self::with_method(http::Method::PATCH) } /// Crea una petición DELETE. pub fn delete() -> Self { Self::with_method(http::Method::DELETE) } fn with_method(method: http::Method) -> Self { Self { method, uri: "/".to_owned(), headers: http::HeaderMap::new(), extensions: http::Extensions::new(), body: String::new(), } } /// Establece la URI de la petición. pub fn uri(mut self, uri: impl Into) -> Self { self.uri = uri.into(); self } /// Añade una cabecera a la petición. /// /// Si `name` o `value` no son válidos como cabecera HTTP, se descarta en silencio en lugar /// de entrar en pánico. pub fn header(mut self, name: impl AsRef, value: impl AsRef) -> Self { if let (Ok(n), Ok(v)) = ( http::HeaderName::from_bytes(name.as_ref().as_bytes()), http::HeaderValue::from_str(value.as_ref()), ) { self.headers.insert(n, v); } self } /// Envía como cuerpo los campos de un formulario, ya codificados (p. ej. /// `"title=Plant+lettuces&done=on"`), con la cabecera /// `Content-Type: application/x-www-form-urlencoded`, como lo envía un navegador. pub fn form(mut self, fields: impl Into) -> Self { self.body = fields.into(); self.header("content-type", "application/x-www-form-urlencoded") } /// Envía como cuerpo de la petición el texto indicado, tal cual. /// /// Combinado con [`header()`](Self::header) para fijar `Content-Type`, permite probar /// cuerpos con otros formatos, como los formularios `multipart/form-data` con archivos. pub fn body(mut self, body: impl Into) -> Self { self.body = body.into(); self } /// Inserta un valor en las extensiones de la petición. /// /// Útil para simular lo que un middleware haría en producción antes de que el handler /// reciba la petición. El tipo debe implementar `Clone + Send + Sync + 'static`. pub fn with_extension(mut self, value: T) -> Self { self.extensions.insert(value); self } /// Construye la petición HTTP de Axum (para enviar al router en tests de integración). pub fn to_request(self) -> http::Request { let mut req = http::Request::builder() .method(self.method) .uri(self.uri) .body(Body::from(self.body)) .unwrap(); *req.headers_mut() = self.headers; *req.extensions_mut() = self.extensions; req } /// Construye un [`HttpRequest`](super::HttpRequest) listo para pasarlo a /// [`Context::new`](crate::core::component::Context::new) en tests unitarios de componentes. pub fn to_http_request(self) -> super::HttpRequest { let uri = self.uri.parse().unwrap(); super::HttpRequest(std::sync::Arc::new(super::RequestParts { uri, headers: self.headers, extensions: self.extensions, })) } } /// Envía una petición al router y devuelve la respuesta. pub async fn send_request(router: &Router, req: http::Request) -> http::Response { router.clone().oneshot(req).await.unwrap() } /// Devuelve el cuerpo de una respuesta como texto UTF-8, para comprobaciones en tests. pub async fn read_body_text(response: http::Response) -> String { let bytes = axum::body::to_bytes(response.into_body(), usize::MAX) .await .unwrap(); String::from_utf8(bytes.to_vec()).unwrap() } } #[cfg(test)] mod tests { use super::*; fn headers(values: &[&str]) -> http::HeaderMap { let mut headers = http::HeaderMap::new(); for value in values { headers.append("x-forwarded-for", value.parse().unwrap()); } headers } fn ip(value: &str) -> Option { Some(value.parse().unwrap()) } #[test] fn the_last_address_of_the_header_wins() { let from = |values| ip_from_header(&headers(values), "X-Forwarded-For"); assert_eq!(from(&["203.0.113.7"]), ip("203.0.113.7")); // Earlier addresses are sent by the client and may be forged. assert_eq!(from(&["10.0.0.1, 203.0.113.7"]), ip("203.0.113.7")); assert_eq!(from(&["10.0.0.1", "203.0.113.7"]), ip("203.0.113.7")); assert_eq!(from(&["2001:db8::1"]), ip("2001:db8::1")); assert_eq!(from(&["203.0.113.7:4711"]), ip("203.0.113.7")); assert_eq!(from(&["[2001:db8::1]:4711"]), ip("2001:db8::1")); } #[test] fn a_missing_or_invalid_header_gives_no_address() { assert_eq!(ip_from_header(&headers(&[]), "X-Forwarded-For"), None); assert_eq!( ip_from_header(&headers(&["203.0.113.7, unknown"]), "X-Forwarded-For"), None ); } #[test] fn without_a_header_the_connection_address_is_used() { let request = test::TestRequest::get() .with_extension(ConnectInfo(SocketAddr::from(([198, 51, 100, 2], 4711)))) .to_http_request(); assert_eq!(request.client_ip(), ip("198.51.100.2")); assert_eq!(test::TestRequest::get().to_http_request().client_ip(), None); } #[test] fn ipv4_addresses_seen_through_ipv6_are_returned_as_ipv4() { // A dual-stack socket ("::") sees IPv4 clients as IPv4-mapped IPv6 addresses. let mapped: SocketAddr = "[::ffff:198.51.100.2]:4711".parse().unwrap(); let request = test::TestRequest::get() .with_extension(ConnectInfo(mapped)) .to_http_request(); assert_eq!(request.client_ip(), ip("198.51.100.2")); let request = test::TestRequest::get() .with_extension(ConnectInfo(SocketAddr::from(( [0x2001, 0xdb8, 0, 0, 0, 0, 0, 1], 80, )))) .to_http_request(); assert_eq!(request.client_ip(), ip("2001:db8::1")); } }