pagetop-website/doc/v0.6/es/src/how-to/middleware.md
Manuel Cillero 345bd26974 📝 Document route access and custom authentication
Adapt the guides to the current PageTop API: Routes with the access of
each route, Layers, StaticFiles and the administration panel in the
core, with pagetop-admin reduced to the settings forms.

Add the "Connect your own authentication" guide, the mail test page and
the admin_path setting, and explain route access in the architecture
page.

Mount the books with their access through pagetop-mdbook.
2026-11-07 17:24:26 +01:00

9 KiB

Añadir middleware

Objetivo: aplicar a todas las peticiones lo que no es asunto de ningún handler concreto: medir lo que tarda cada una, comprimir las respuestas, limitar el tamaño de lo que se envía, cortar las que se eternizan o abrir una API a otros dominios con CORS.

Un middleware es una capa que envuelve las rutas: recibe la petición antes que el handler y la respuesta después. PageTop usa las capas de Axum y de Tower, así que tienes a mano todo su ecosistema. Cada extensión añade las suyas en configure_middleware(), y se aplican a las rutas de todas las extensiones.

1. Escribe una capa propia

web::middleware::from_fn() convierte una función async en una capa. La función recibe la petición y next, que ejecuta el resto de la cadena y devuelve la respuesta:

# use pagetop::prelude::*;
use std::time::Instant;

async fn timing(request: web::Request, next: web::middleware::Next) -> Response {
    let path = request.uri().path().to_owned();
    let start = Instant::now();

    let response = next.run(request).await;

    trace::info!(
        %path,
        status = response.status().as_u16(),
        elapsed_ms = start.elapsed().as_millis() as u64,
        "Request served"
    );
    response
}

pub struct Garden;

#[async_trait]
impl Extension for Garden {
    fn configure_middleware(&self, layers: Layers) -> Layers {
        layers.layer(web::middleware::from_fn(timing))
    }
}

Lo que va antes de next.run() ocurre a la ida (aquí, anotar la hora); lo que va después, a la vuelta, con la respuesta ya hecha. Una capa también puede responder ella misma sin llamar a next, por ejemplo para cerrar el sitio por mantenimiento.

2. Reutiliza las capas de tower-http

Para lo habitual no hace falta escribir nada: tower-http trae las capas hechas. Añádelo con las features de las que vayas a usar (es la misma versión que usa PageTop):

[dependencies]
tower-http = { version = "0.7", features = ["compression-gzip", "cors", "limit", "timeout"] }

Y apílalas en configure_middleware():

# use pagetop::prelude::*;
use std::time::Duration;

use tower_http::compression::CompressionLayer;
use tower_http::limit::RequestBodyLimitLayer;
use tower_http::timeout::TimeoutLayer;

# pub struct Garden;
# #[async_trait]
# impl Extension for Garden {
fn configure_middleware(&self, layers: Layers) -> Layers {
    layers
        // Requests with a body over 1 MiB get a 413 Payload Too Large.
        .layer(RequestBodyLimitLayer::new(1024 * 1024))
        // Requests that take more than 30 seconds get a 408 Request Timeout.
        .layer(TimeoutLayer::with_status_code(
            web::http::StatusCode::REQUEST_TIMEOUT,
            Duration::from_secs(30),
        ))
        // Responses go compressed with gzip to the browsers that accept it.
        .layer(CompressionLayer::new())
}
# }
Capa Para qué
CompressionLayer Comprime las respuestas si el navegador lo admite (feature compression-gzip, o compression-full para todos los formatos)
RequestBodyLimitLayer Rechaza los cuerpos demasiado grandes (feature limit)
TimeoutLayer Corta las peticiones que tardan demasiado (feature timeout)
CorsLayer Permite llamadas desde otros dominios (feature cors)
SetResponseHeaderLayer Añade una cabecera a todas las respuestas (feature set-header)

3. Ten en cuenta el orden

Cada .layer() envuelve todo lo anterior, así que la última capa añadida es la más externa: la primera que ve la petición y la última que toca la respuesta. En el ejemplo, la compresión envuelve a las demás y comprime también el 408 del tiempo máximo, y el límite de tamaño, el más interno, actúa justo antes del handler.

Lo mismo vale entre extensiones: las capas de cada una envuelven las de las extensiones que se inicializaron antes.

4. Aplica una capa sólo a tus rutas

configure_middleware() afecta a todo. Para que una capa sólo envuelva unas rutas, crea con ellas un Router propio en configure_router(), ponle la capa y anídalo bajo su prefijo con nest(), con el acceso que compartan sus rutas. Es lo natural para CORS, que sólo debe abrirse en la API:

# use pagetop::prelude::*;
# use serde::Serialize;
use tower_http::cors::CorsLayer;

# #[derive(Serialize)]
# struct Plot { code: &'static str }
# async fn home() -> &'static str { "" }
# async fn plots() -> Json<Vec<Plot>> { Json(vec![]) }
# pub struct Garden;
# #[async_trait]
# impl Extension for Garden {
fn configure_router(&self, routes: Routes) -> Routes {
    let cors = CorsLayer::new()
        .allow_origin(web::http::HeaderValue::from_static("https://garden.example.org"))
        .allow_methods([web::http::Method::GET]);

    let api = Router::new()
        .route("/plots", web::get(plots))
        .layer(cors);

    routes
        .public_route("/", web::get(home))
        .nest("/api", Access::Public, api)
}
# }

5. Lo que no pasa por el middleware

Los archivos estáticos que publicas con configure_static_files() se sirven por fuera de las capas: no se comprimen ni se miden. Es deliberado, para que servir un estilo o una imagen sea lo más barato posible. Si quieres comprimirlos, hazlo en el proxy que tengas delante (ve Desplegar en producción).

Las páginas de error se pintan después, por fuera de todas las capas. Las capas sí ven la respuesta de error (la miden, le añaden cabeceras, que se conservan), pero la página que llega al navegador no sale comprimida. Tampoco la página mínima de un panic!, que PageTop atrapa en la capa más externa de todas.

El ejemplo completo

use std::time::{Duration, Instant};

use pagetop::prelude::*;
use serde::Serialize;
use tower_http::compression::CompressionLayer;
use tower_http::cors::CorsLayer;
use tower_http::limit::RequestBodyLimitLayer;
use tower_http::timeout::TimeoutLayer;

#[derive(Serialize)]
struct Plot {
    code: &'static str,
    holder: &'static str,
}

struct Garden;

#[async_trait]
impl Extension for Garden {
    fn configure_middleware(&self, layers: Layers) -> Layers {
        layers
            .layer(web::middleware::from_fn(timing))
            .layer(RequestBodyLimitLayer::new(1024 * 1024))
            .layer(TimeoutLayer::with_status_code(
                web::http::StatusCode::REQUEST_TIMEOUT,
                Duration::from_secs(30),
            ))
            .layer(CompressionLayer::new())
    }

    fn configure_router(&self, routes: Routes) -> Routes {
        let cors = CorsLayer::new()
            .allow_origin(web::http::HeaderValue::from_static("https://garden.example.org"))
            .allow_methods([web::http::Method::GET]);

        let api = Router::new()
            .route("/plots", web::get(plots))
            .layer(cors);

        routes
            .public_route("/", web::get(home))
            .public_route("/notes", web::post(notes))
            .nest("/api", Access::Public, api)
    }
}

async fn timing(request: web::Request, next: web::middleware::Next) -> Response {
    let path = request.uri().path().to_owned();
    let start = Instant::now();

    let response = next.run(request).await;

    trace::info!(
        %path,
        status = response.status().as_u16(),
        elapsed_ms = start.elapsed().as_millis() as u64,
        "Request served"
    );
    response
}

async fn home(request: HttpRequest) -> Result<Markup, ErrorPage> {
    Page::new(request)
        .with_title(Lc::n("Community garden"))
        .with_child(Html::with(|_| html! {
            @for i in 1..=50 {
                p { "Plot " (i) ": tomatoes, lettuces and courgettes." }
            }
        }))
        .render()
        .await
}

async fn notes(body: String) -> String {
    format!("Received {} bytes", body.len())
}

async fn plots() -> Json<Vec<Plot>> {
    Json(vec![
        Plot { code: "a1", holder: "Ana" },
        Plot { code: "b2", holder: "Luke" },
    ])
}

#[pagetop::main]
async fn main() -> std::io::Result<()> {
    Application::prepare(&Garden).await.run().await
}

Comprueba

# Compressed: the answer includes content-encoding: gzip.
curl -s -o /dev/null -D - -H 'Accept-Encoding: gzip' http://localhost:8080/ | grep -i encoding

# Too big: 413 Payload Too Large.
head -c 2000000 /dev/zero | curl -s -o /dev/null -w '%{http_code}\n' --data-binary @- \
    http://localhost:8080/notes

# CORS: only the API answers to the allowed origin.
curl -s -o /dev/null -D - -H 'Origin: https://garden.example.org' \
    http://localhost:8080/api/plots | grep -i access-control

Y en el terminal, una línea Request served por petición, con su ruta, su código y lo que ha tardado.

Siguiente