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.
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
- Crear una extensión: el resto de lo que puede aportar una extensión.
- Registrar trazas: dónde acaban las líneas de
timing. - Arquitectura: del arranque a la respuesta: dónde encajan las capas en el recorrido de una petición.