✨ 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:
parent
e41e71cc78
commit
1a41a456d4
80 changed files with 14112 additions and 1218 deletions
267
doc/v0.6/es/src/how-to/middleware.md
Normal file
267
doc/v0.6/es/src/how-to/middleware.md
Normal 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue