✨ Serve the PageTop guides with pagetop-mdbook

Rebuild the website on the current PageTop API, with Bootsier as its
theme and edition 2024. Add the first Spanish guide (doc/v0.6/es) as an
mdBook book, built in build.rs and served with pagetop-mdbook, and the
/doc/latest/{lang} redirect.

Add `tools/doccheck.sh` to check the links of the guides and to compile,
run and test their examples against PageTop.

Move the configuration to config/common.toml and translate the README
to English.
This commit is contained in:
Manuel Cillero 2026-10-17 08:06:02 +02:00
parent e41e71cc78
commit 1a41a456d4
80 changed files with 14112 additions and 1218 deletions

View file

@ -0,0 +1,267 @@
# 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](https://docs.rs/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:
```rust,no_run
# 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, router: Router) -> Router {
router.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`](https://docs.rs/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):
```toml
[dependencies]
tower-http = { version = "0.7", features = ["compression-gzip", "cors", "limit", "timeout"] }
```
Y apílalas en `configure_middleware()`:
```rust,no_run
# 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, router: Router) -> Router {
router
// 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 únelo al resto con `merge()`. Es lo
natural para CORS, que sólo debe abrirse en la API:
```rust,no_run
# 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, router: Router) -> Router {
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("/api/plots", web::get(plots))
.layer(cors);
router.route("/", web::get(home)).merge(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](deployment.md)).
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
```rust,no_run
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, router: Router) -> Router {
router
.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, router: Router) -> Router {
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("/api/plots", web::get(plots))
.layer(cors);
router
.route("/", web::get(home))
.route("/notes", web::post(notes))
.merge(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
```sh
# 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](extensions.md): el resto de lo que puede aportar una extensión.
- [Registrar trazas](logging.md): dónde acaban las líneas de `timing`.
- [Arquitectura: del arranque a la respuesta](../explanation/architecture.md): dónde encajan las
capas en el recorrido de una petición.