📝 Add mail and file upload guides

Document pagetop-mail (configuration, templates, layout, previews,
queue and tests with the outbox) and file uploads (`web::Upload`,
`form::File`, `web::Download` and the [upload] settings). doccheck
enables the mail queue, keeps mail in memory and saves uploads under
`target/`.
This commit is contained in:
Manuel Cillero 2026-11-02 17:29:37 +01:00
parent 4e007feec8
commit f42f5e9b89
13 changed files with 1118 additions and 8 deletions

View file

@ -21,6 +21,7 @@
- [Maquetar con Flex y Grid](how-to/layout.md)
- [Añadir navegación](how-to/navigation.md)
- [Crear y procesar formularios](how-to/forms.md)
- [Subir y descargar archivos](how-to/uploads.md)
- [Mostrar tablas ordenables y paginadas](how-to/tables.md)
- [Interactividad con HTMX]()
- [Añadir HTMX a una aplicación](how-to/htmx-setup.md)
@ -41,6 +42,7 @@
- [Configurar la aplicación](how-to/configuration.md)
- [Compartir un servicio entre rutas](how-to/services.md)
- [Programar tareas periódicas](how-to/cron.md)
- [Enviar correo electrónico](how-to/mail.md)
- [Añadir *middleware*](how-to/middleware.md)
- [Traducir la aplicación](how-to/localization.md)
- [Servir recursos estáticos](how-to/assets.md)

View file

@ -106,7 +106,7 @@ Con las capas de `tower-http` en `configure_middleware()`. Ver [Añadir
Sí, con dos extensiones oficiales: `pagetop-cron` ejecuta trabajos en segundo plano según una
expresión cron o a intervalos (ve [Programar tareas periódicas](how-to/cron.md)), y `pagetop-mail`
envía correo (ve [Extensiones oficiales](reference/extensions.md#correo)), con una cola opcional
envía correo (ve [Enviar correo electrónico](how-to/mail.md)), con una cola opcional
que guarda los correos en la base de datos y reintenta los que fallan. Lo que todavía no tiene
PageTop es una cola de trabajos genérica que sobreviva a un reinicio, como las de Loco (ve la
[comparación con otros *frameworks*](explanation/comparison.md)).

View file

@ -115,6 +115,9 @@ server {
# ssl_certificate ... ssl_certificate_key ...
# Allows uploads up to upload.max_request_size (nginx accepts 1 MiB by default).
client_max_body_size 32m;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;

View file

@ -0,0 +1,578 @@
# Enviar correo electrónico
**Objetivo:** enviar correos desde la aplicación, en texto y HTML, con adjuntos, traducidos al
idioma de cada destinatario y con el mismo aspecto que los de las demás extensiones, sin enviar
nunca correo real por error mientras desarrollas.
Lo aporta la extensión `pagetop-mail`. La configuración decide **cómo** se entregan los correos
(servidor SMTP, *sendmail*, archivos, trazas o memoria), así que el código que los envía es el
mismo en desarrollo, en las pruebas y en producción.
## 1. Añade la dependencia
```toml
[dependencies]
pagetop-mail = { git = "https://git.cillero.es/manuelcillero/pagetop" }
```
Y declara `pagetop_mail::Mail` en `dependencies()` de la extensión que envía correos:
```rust,no_run
# use pagetop::prelude::*;
pub struct Garden;
#[async_trait]
impl Extension for Garden {
fn dependencies(&self) -> Vec<ExtensionRef> {
vec![&pagetop_mail::Mail]
}
}
```
## 2. Configura el envío
Sin configurar nada, los correos **no se envían**: se escriben en las trazas, con el remitente, los
destinatarios, el asunto y el texto. Es lo que quieres mientras desarrollas. Para enviarlos de
verdad, configura la sección `[mail]` con el transporte, el remitente y la URL pública de la
aplicación, que forma los enlaces de los correos (ver el paso 5):
```toml
# config/production.toml
[mail]
transport = "smtp"
from = "Community garden <no-reply@example.com>"
base_url = "https://garden.example.com"
[mail.smtp]
host = "smtp.example.com"
username = "no-reply@example.com"
```
La contraseña no va en un archivo versionado: ponla en `config/local.toml` o en la variable de
entorno `PAGETOP_MAIL__SMTP__PASSWORD`. Por defecto la conexión exige `STARTTLS` en el puerto 587;
`security = "tls"` usa el 465.
Para ver los correos tal como llegan sin enviarlos a nadie, usa en desarrollo un servidor como
[Mailpit](https://mailpit.axllent.org), que los recoge y los muestra en el navegador:
```toml
# config/local.toml
[mail]
transport = "smtp"
[mail.smtp]
host = "localhost"
port = 1025
security = "none"
```
Con `transport = "file"`, cada correo se guarda como un archivo `.eml` en el directorio `mail/`,
que abre cualquier cliente de correo. Y en un entorno de pruebas con datos reales,
`redirect_to = "qa@example.com"` entrega todos los correos sólo a esa dirección. Los ajustes no
válidos detienen el arranque con un mensaje que indica el problema.
## 3. Envía un correo
Un correo se compone con `Email`:
```rust,no_run
# use pagetop::prelude::*;
use pagetop_mail::prelude::*;
async fn confirm_plot(address: String) -> Result<(), MailError> {
Email::new()
.with_to(address)
.with_subject("Your plot is booked")
.with_html(html! {
p { "Your plot " strong { "B-12" } " is booked for the whole season." }
})
.send()
.await
}
```
Las direcciones admiten la forma `"Ana Pérez <ana@example.com>"`, y `with_cc()`, `with_bcc()` y
`with_reply_to()` completan los destinatarios; el remitente es el de `mail.from` salvo que indiques
otro con `with_from()`. Si el correo sólo tiene HTML, al enviarlo se genera su versión en texto
plano; escríbela tú con `with_text()` sólo si la generada no queda bien.
Hay dos formas de enviarlo:
- **`send().await`** espera a que el correo se entregue y devuelve el error si falla. Úsalo cuando
necesitas saberlo para responder.
- **`send_later()`** lo entrega en segundo plano y vuelve enseguida; si falla, lo registra en las
trazas. Es lo indicado en una petición del usuario: la respuesta no espera al servidor de
correo, y su tiempo no revela nada (por ejemplo, si existe la cuenta para la que se pide
recuperar la contraseña).
## 4. Escribe una plantilla traducida
Para que el mismo correo llegue a cada destinatario en su idioma, defínelo como un tipo que
implementa `MailTemplate`. Sus métodos reciben un `Context` con el idioma del destinatario, y los
textos se escriben con `Lc`, igual que en un componente:
```rust,no_run
# use pagetop::prelude::*;
# use pagetop_mail::prelude::*;
include_locales!(LOCALES_APP);
struct HarvestNotice {
name: String,
}
impl MailTemplate for HarvestNotice {
fn subject(&self, cx: &Context) -> String {
Lc::t("harvest-subject", &LOCALES_APP).lookup(cx).unwrap_or_default()
}
fn html(&self, cx: &Context) -> Option<Markup> {
let greeting = Lc::t("harvest-greeting", &LOCALES_APP).with_arg("name", self.name.clone());
Some(html! {
p { (greeting.using(cx)) }
p { (Lc::t("harvest-ready", &LOCALES_APP).using(cx)) }
p {
a href=(absolute_url("/harvest")) {
(Lc::t("harvest-link", &LOCALES_APP).using(cx))
}
}
})
}
}
```
Con sus traducciones en `src/locale/en-US/app.ftl`:
```ftl
harvest-subject = The tomatoes are ready to pick
harvest-greeting = Hello, { $name }:
harvest-ready = The tomatoes in the community garden are ripe. Come and pick your share this week.
harvest-link = See the harvest calendar
```
`Email::from_template()` crea el correo con el asunto y el contenido de la plantilla. El contexto
decide el idioma. Si el destinatario es quien hace la petición (por ejemplo, al apuntarse a un
aviso), usa el de la petición. Si es otra persona, crea uno con su idioma, guardado junto a su
dirección; si no es un idioma disponible, el correo sale en el idioma por defecto de la aplicación:
```rust,no_run
# use pagetop::prelude::*;
# use pagetop_mail::prelude::*;
# struct HarvestNotice { name: String }
# impl MailTemplate for HarvestNotice {
# fn subject(&self, _cx: &Context) -> String { String::new() }
# }
async fn notify_gardener(name: String, email: String, language: String) -> Result<(), MailError> {
let cx = Context::default().with_langid(&Locale::resolve(language));
Email::from_template(&HarvestNotice { name }, &cx)
.with_to(email)
.send()
.await
}
```
## 5. Usa enlaces absolutos
Un enlace de un correo se abre fuera de la aplicación, así que debe ser absoluto. `absolute_url()`
antepone a la ruta la URL pública de `mail.base_url`, como en la plantilla anterior. Si no la
configuras, usa la dirección y el puerto de escucha (`http://localhost:8080`), que sólo sirve en
desarrollo.
La URL no se deduce de la petición: la cabecera `Host` la elige el cliente, y un atacante podría
conseguir que el enlace de un correo de recuperación de contraseña apuntara a su propio servidor.
## 6. Adjunta archivos
`Attachment` crea un adjunto con un contenido en memoria o leyendo un archivo, y deduce su tipo del
nombre. Con `with_content_id()` el adjunto se incrusta en el HTML, que lo muestra con `cid:`:
```rust,no_run
# use pagetop::prelude::*;
# use pagetop_mail::prelude::*;
async fn send_report(address: String, logo_png: Vec<u8>) -> Result<(), MailError> {
Email::new()
.with_to(address)
.with_subject("October harvest report")
.with_html(html! {
img src="cid:logo" alt="Community garden";
p { "The report of the month is attached." }
})
.with_attachment(Attachment::new("logo.png", logo_png).with_content_id("logo"))
.with_attachment(Attachment::from_path("reports/october.pdf").await?)
.send()
.await
}
```
## 7. Dale tu imagen a los correos
El HTML de un correo es sólo su contenido: al enviarlo se envuelve en un diseño común, sobrio y
neutro, con el nombre de la aplicación al pie. Para dar tu propia imagen a **todos** los correos,
también a los que envían otras extensiones como `pagetop-user`, registra la acción
`RenderMailLayout`:
```rust,no_run
# use pagetop::prelude::*;
# use pagetop_mail::prelude::*;
fn garden_layout(cx: &Context, email: &Email, content: &Markup) -> Markup {
html! {
(DOCTYPE)
html lang=(cx.langid().to_string()) {
head {
meta charset="utf-8";
title { (email.subject()) }
}
body style="margin: 0; padding: 24px; background: #f0f5ec; font-family: sans-serif;" {
div style="max-width: 600px; margin: 0 auto; padding: 24px; background: #fff;" {
(content)
}
}
}
}
}
pub struct Garden;
#[async_trait]
impl Extension for Garden {
fn dependencies(&self) -> Vec<ExtensionRef> {
vec![&pagetop_mail::Mail]
}
fn actions(&self) -> Vec<ActionBox> {
actions![RenderMailLayout::new(garden_layout)]
}
}
```
Si varias extensiones registran esta acción, se aplica sólo la de menor peso
(`RenderMailLayout::new(..).with_weight(..)`). Los clientes de correo ignoran las hojas de estilo
externas, y muchos también los estilos del `<head>`: escribe los estilos en línea, con `style`. Un
correo concreto puede saltarse el diseño con `with_html_document()`, que envía el documento tal
cual.
## 8. Revisa los correos en el navegador
Para ver cómo queda un correo sin enviarlo, declara una vista previa con datos de ejemplo:
```rust,no_run
# use pagetop::prelude::*;
# use pagetop_mail::prelude::*;
# struct HarvestNotice { name: String }
# impl MailTemplate for HarvestNotice {
# fn subject(&self, _cx: &Context) -> String { String::new() }
# }
fn harvest_preview(cx: &Context) -> Email {
let notice = HarvestNotice { name: "Ana".to_string() };
Email::from_template(&notice, cx).with_to("ana@example.com")
}
fn declare_previews(previews: &mut MailPreviews) {
previews.add("garden.harvest", Lc::n("Harvest notice"), harvest_preview);
}
pub struct Garden;
#[async_trait]
impl Extension for Garden {
fn dependencies(&self) -> Vec<ExtensionRef> {
vec![&pagetop_mail::Mail]
}
fn actions(&self) -> Vec<ActionBox> {
actions![DeclareMailPreviews::new(declare_previews)]
}
}
```
Activa las vistas previas sólo en desarrollo, porque muestran las plantillas a quien conozca la
ruta:
```toml
# config/local.toml
[mail]
previews = true
```
`/mail/preview` lista los correos declarados por todas las extensiones, y cada uno se muestra
completo, con el diseño común, las cabeceras, el texto plano y los adjuntos. Añade `?lang=es` para
verlo en otro idioma.
## 9. Guarda los correos en una cola
Sin más, un correo de `send_later()` se pierde si la aplicación se detiene antes de entregarlo, y
no se reintenta si el servidor falla. Con la *feature* `queue`, los correos se guardan en la base
de datos de `pagetop-seaorm` y se reintentan:
```toml
[dependencies]
pagetop-mail = { git = "https://git.cillero.es/manuelcillero/pagetop", features = ["queue"] }
pagetop-seaorm = { git = "https://git.cillero.es/manuelcillero/pagetop", features = ["sqlite"] }
```
La cola crea su tabla al arrancar, en la base de datos de `[database]`. Con ella:
- **`send_later()`** guarda el correo y lo intenta enseguida (salvo con `transport = "log"`, que
lo escribe directamente en las trazas). Si el fallo es temporal, queda en la cola y se reintenta
más tarde, también después de un reinicio, con una espera que se duplica en cada intento. Un
rechazo definitivo del servidor o el último intento lo dejan como fallido.
- **`queue()`** sólo lo guarda: el trabajo `mail.queue` de `pagetop-cron` envía los pendientes por
lotes, uno tras otro. Es lo indicado para los envíos masivos, que así no saturan el equipo ni el
servidor de correo:
```rust,no_run
# use pagetop::prelude::*;
# use pagetop_mail::prelude::*;
async fn announce_closure(addresses: Vec<String>) -> Result<(), MailError> {
for address in addresses {
Email::new()
.with_to(address)
.with_subject("The garden closes on Saturday")
.with_text("The garden will be closed on Saturday for the water works.")
.queue()
.await?;
}
Ok(())
}
```
El tamaño de los lotes y los reintentos se ajustan en
[`[mail.queue]`](../reference/configuration.md#mailqueue), y el ritmo en la programación del
trabajo:
```toml
[cron.jobs."mail.queue"]
schedule = "@delay 30s" # 30 s after each batch ends (1 minute by default).
```
La cola guarda los mensajes completos y sin cifrar hasta entregarlos: pueden contener datos
personales y enlaces de un solo uso, también en las copias de seguridad de la base de datos.
## El ejemplo completo
Un formulario en `/harvest` donde cada visitante pide el aviso de la cosecha, que recibe por
correo en su idioma:
```rust,no_run
use pagetop::prelude::*;
use pagetop_mail::prelude::*;
use serde::Deserialize;
include_locales!(LOCALES_APP);
struct HarvestNotice {
name: String,
}
impl MailTemplate for HarvestNotice {
fn subject(&self, cx: &Context) -> String {
Lc::t("harvest-subject", &LOCALES_APP).lookup(cx).unwrap_or_default()
}
fn html(&self, cx: &Context) -> Option<Markup> {
let greeting = Lc::t("harvest-greeting", &LOCALES_APP).with_arg("name", self.name.clone());
Some(html! {
p { (greeting.using(cx)) }
p { (Lc::t("harvest-ready", &LOCALES_APP).using(cx)) }
p {
a href=(absolute_url("/harvest")) {
(Lc::t("harvest-link", &LOCALES_APP).using(cx))
}
}
})
}
}
fn harvest_preview(cx: &Context) -> Email {
let notice = HarvestNotice { name: "Ana".to_string() };
Email::from_template(&notice, cx).with_to("ana@example.com")
}
fn declare_previews(previews: &mut MailPreviews) {
previews.add("garden.harvest", Lc::n("Harvest notice"), harvest_preview);
}
struct Garden;
#[async_trait]
impl Extension for Garden {
fn dependencies(&self) -> Vec<ExtensionRef> {
vec![&pagetop_mail::Mail]
}
fn actions(&self) -> Vec<ActionBox> {
actions![DeclareMailPreviews::new(declare_previews)]
}
fn configure_router(&self, router: Router) -> Router {
router.route("/harvest", web::get(show).post(notify))
}
}
#[derive(Deserialize)]
struct Gardener {
name: String,
email: String,
}
fn notice_form() -> Form {
Form::new()
.with_action("/harvest")
.with_method(form::Method::Post)
.with_child(
form::input::Field::text()
.with_name("name")
.with_label(Lc::n("Name"))
.with_required(true),
)
.with_child(
form::input::Field::email()
.with_name("email")
.with_label(Lc::n("Email"))
.with_required(true),
)
.with_child(Button::submit(Lc::n("Send me the notice")))
}
async fn show(request: HttpRequest) -> Result<Markup, ErrorPage> {
Page::new(request)
.with_title(Lc::n("Harvest"))
.with_child(notice_form())
.render()
.await
}
async fn notify(
request: HttpRequest,
web::Form(gardener): web::Form<Gardener>,
) -> Result<Response, ErrorPage> {
// The notice goes in the language of the visitor who asks for it.
let cx = Context::new(request.clone());
let notice = HarvestNotice { name: gardener.name };
let sent = Email::from_template(&notice, &cx)
.with_to(gardener.email)
.send()
.await;
if let Err(err) = sent {
trace::warn!("Harvest notice not sent: {err}");
let mut page = Page::new(request)
.with_title(Lc::n("Harvest"))
.with_child(notice_form());
page.context().push_message(
MessageLevel::Error,
Lc::n("The notice could not be sent. Check the address and try again."),
);
return page.render().await.map(IntoResponse::into_response);
}
Ok(Redirect::see_other(cx.route("/harvest")).with_message(
&cx,
MessageLevel::Info,
Lc::n("We have sent you the notice. Check your inbox."),
))
}
#[pagetop::main]
async fn main() -> std::io::Result<()> {
Application::prepare(&Garden).await.run().await
}
```
El ejemplo usa `send().await` para avisar en el formulario si la dirección no es válida o el
servidor la rechaza. Si prefieres no hacer esperar al visitante, cambia `send().await` por
`send_later()` y avisa siempre del envío: los fallos quedarán en las trazas.
## Comprueba
Arranca con `cargo run`, abre <http://localhost:8080/harvest> y envía el formulario: la página
confirma el envío y el terminal muestra el correo, porque sin configurar `[mail]` se escribe en las
trazas. Con `previews = true` en `config/local.toml`, <http://localhost:8080/mail/preview> lo
muestra con su diseño.
En las pruebas, el transporte `memory` guarda los correos en lugar de enviarlos, y
`pagetop_mail::outbox` los recoge. Configúralo en `config/test.toml` (ve [Usa otra configuración
para las pruebas](testing.md#5-usa-otra-configuración-para-las-pruebas)):
```toml
# config/test.toml
[mail]
transport = "memory"
from = "Community garden <garden@example.com>"
base_url = "https://garden.example.com"
```
```rust
# use pagetop::prelude::*;
# use pagetop_mail::prelude::*;
# use serde::Deserialize;
# include_locales!(LOCALES_APP);
# struct HarvestNotice { name: String }
# impl MailTemplate for HarvestNotice {
# fn subject(&self, cx: &Context) -> String {
# Lc::t("harvest-subject", &LOCALES_APP).lookup(cx).unwrap_or_default()
# }
# fn html(&self, cx: &Context) -> Option<Markup> {
# let greeting = Lc::t("harvest-greeting", &LOCALES_APP).with_arg("name", self.name.clone());
# let link = Lc::t("harvest-link", &LOCALES_APP);
# Some(html! {
# p { (greeting.using(cx)) }
# p { a href=(absolute_url("/harvest")) { (link.using(cx)) } }
# })
# }
# }
# struct Garden;
# #[async_trait]
# impl Extension for Garden {
# fn dependencies(&self) -> Vec<ExtensionRef> {
# vec![&pagetop_mail::Mail]
# }
# fn configure_router(&self, router: Router) -> Router {
# router.route("/harvest", web::post(notify))
# }
# }
# #[derive(Deserialize)]
# struct Gardener { name: String, email: String }
# async fn notify(
# request: HttpRequest,
# web::Form(gardener): web::Form<Gardener>,
# ) -> Result<Response, ErrorPage> {
# let cx = Context::new(request.clone());
# Email::from_template(&HarvestNotice { name: gardener.name }, &cx)
# .with_to(gardener.email)
# .send()
# .await
# .map_err(|_| ErrorPage::InternalError(Some(request)))?;
# Ok(Redirect::see_other(cx.route("/harvest")))
# }
use pagetop_mail::outbox;
#[pagetop::test]
async fn sends_the_harvest_notice() {
let app = web::test::init_router(Application::prepare(&Garden).await.test());
let request = web::test::TestRequest::post()
.uri("/harvest")
.form("name=Ana&email=ana%40example.com")
.to_request();
let response = web::test::send_request(&app, request).await;
assert_eq!(response.status(), web::http::StatusCode::SEE_OTHER);
let sent = outbox::take_to("ana@example.com");
assert_eq!(sent.len(), 1);
assert_eq!(sent[0].email().subject(), "The tomatoes are ready to pick");
assert!(sent[0].links().contains(&"https://garden.example.com/harvest".to_string()));
}
```
`take_to()` recoge sólo los correos de esa dirección, así que las pruebas que se ejecutan en
paralelo no se roban los correos. `links()` devuelve las direcciones de los enlaces del HTML, para
seguir en la prueba, por ejemplo, un enlace de un solo uso.
Si el correo sale con `send_later()`, llega a `outbox` en segundo plano, poco después de la
respuesta. Con la *feature* `queue`, los de `queue()` sólo llegan cuando se ejecuta el trabajo, que
en las pruebas se lanza con `pagetop_cron::run_now("mail.queue")`.
## Siguiente
- [Opciones de configuración](../reference/configuration.md#mail): todas las claves de `[mail]`.
- [Programar tareas periódicas](cron.md): el planificador que vacía la cola.
- [Añadir usuarios y permisos](users.md): `pagetop-user` envía con esta extensión sus correos de
recuperación de contraseña y de verificación.

View file

@ -0,0 +1,486 @@
# Subir y descargar archivos
**Objetivo:** recibir archivos desde un formulario, guardarlos en el servidor con límites de tamaño
y de tipo, y servirlos después sólo a quien pueda verlos.
Todo lo necesario está en el núcleo de PageTop: el campo `form::File`, `web::Upload` para recibir
y guardar los archivos, y `web::Download` para servirlos.
## 1. Define la subida
`web::Upload` describe qué se admite y dónde se guarda. Defínelo una sola vez, en una función, para
que el formulario y el servidor compartan las mismas reglas:
```rust,no_run
# use pagetop::prelude::*;
fn photo_upload() -> web::Upload {
web::Upload::new()
.with_subdir("photos")
.with_extensions(["jpg", "jpeg", "png"])
.with_file_fields(["photo"])
.with_max_size(2 * 1024 * 1024)
}
```
| Método | Para qué |
|---|---|
| `with_subdir("photos")` | Subdirectorio, dentro del de archivos subidos (`[upload] dir`) |
| `with_extensions(["jpg", "png"])` | Extensiones admitidas; un archivo con otra se rechaza |
| `with_file_fields(["photo"])` | Campos del formulario que pueden traer archivos; uno en otro campo se rechaza |
| `with_max_size(bytes)` | Tamaño máximo de cada archivo, en lugar del de la configuración |
| `with_max_files(n)` | Número máximo de archivos de un envío, en lugar del de la configuración |
Restringe siempre las extensiones: es la defensa más sencilla contra quien sube una página HTML o un
programa en lugar de una foto.
## 2. Construye el formulario
Un formulario con archivos necesita la codificación `multipart/form-data`, que se indica con
`form::Enctype::Multipart`. El campo es `form::File`, y con `accept()` ofrece al usuario los mismos
tipos que admite el servidor:
```rust,no_run
# use pagetop::prelude::*;
# fn photo_upload() -> web::Upload { web::Upload::new() }
fn photo_form() -> Form {
Form::new()
.with_action("/photos")
.with_method(form::Method::Post)
.with_enctype(form::Enctype::Multipart)
.with_child(
form::input::Field::text()
.with_name("title")
.with_label(Lc::n("Title"))
.with_required(true),
)
.with_child(
form::File::new()
.with_name("photo")
.with_label(Lc::n("Photo"))
.with_accept(photo_upload().accept())
.with_required(true),
)
.with_child(Button::submit(Lc::n("Upload")))
}
```
Para elegir varios archivos en el mismo campo, añade `with_multiple(true)`.
## 3. Recibe el envío
El *handler* recibe el cuerpo con el extractor `web::Multipart`, siempre como **último** parámetro.
`receive()` guarda los archivos según las reglas del paso 1 y deserializa los campos de texto en una
estructura, como hace `web::Form` en un formulario sin archivos:
```rust,no_run
# use pagetop::prelude::*;
# fn photo_upload() -> web::Upload { web::Upload::new() }
# async fn show_form(_request: HttpRequest, _error: Lc) -> Result<Response, ErrorPage> { todo!() }
#[derive(serde::Deserialize)]
struct PhotoData {
title: String,
}
async fn upload(request: HttpRequest, multipart: web::Multipart) -> Result<Response, ErrorPage> {
let sent = match photo_upload().receive::<PhotoData>(multipart).await {
Ok(sent) => sent,
// Too large, a type not allowed...: shows the form again with the reason.
Err(err) if err.is_client_error() => return show_form(request, err.message()).await,
Err(_) => return Err(ErrorPage::InternalError(Some(request))),
};
let Some(photo) = sent.file("photo") else {
return show_form(request, Lc::n("Choose a photo to upload.")).await;
};
// Save `sent.form().title`, `photo.path()` and `photo.original_name()`, for example in the
// database. If anything fails before `keep()`, the file is deleted.
sent.keep();
let cx = Context::new(request);
Ok(Redirect::see_other(cx.route("/photos")).with_message(
&cx,
MessageLevel::Info,
Lc::n("Photo uploaded."),
))
}
```
Fíjate en tres cosas:
- **Los errores del usuario se distinguen de los del servidor.** `is_client_error()` es cierto si
el archivo es demasiado grande, de un tipo no admitido o el envío está mal formado, y
`message()` explica el motivo, ya traducido, con el nombre del archivo y el límite superado.
- **Los archivos se borran si no llamas a `keep()`.** El envío recibido conserva sus archivos sólo
si llegas a `keep()`, cuando ya está todo guardado. Si la validación o la base de datos fallan y
sales antes, con `return` o con `?`, no quedan archivos huérfanos en el disco.
- **El nombre que envía el navegador nunca llega al disco.** Cada archivo se guarda con un nombre
aleatorio y la extensión del original, y `path()` devuelve su ruta relativa
(`photos/3f9c2a7d1b4e8a60.jpg`): es lo que se guarda en la base de datos. El nombre original,
saneado, queda en `original_name()`, sólo para mostrarlo.
`content_type()` devuelve el tipo que declara el navegador, pero no se comprueba contra el
contenido: no lo tomes como garantía de que el archivo es lo que dice.
## 4. Sirve el archivo con permisos
Los archivos subidos no se publican como estáticos. Se sirven desde un *handler*, que antes
comprueba si quien los pide puede verlos y busca su ruta, con `web::Download`:
```rust,no_run
# use pagetop::prelude::*;
# fn find_photo(_index: usize) -> Option<(String, String)> { None }
async fn photo(
request: HttpRequest,
web::Path(index): web::Path<usize>,
) -> Result<Response, ErrorPage> {
// Check the permissions here, as in any other handler...
let Some((path, original_name)) = find_photo(index) else {
return Err(ErrorPage::NotFound(Some(request)));
};
web::Download::new(path)
.with_file_name(original_name)
.serve(&request)
.await
.map_err(|err| match err {
web::UploadError::NotFound(_) => ErrorPage::NotFound(Some(request)),
_ => ErrorPage::InternalError(Some(request)),
})
}
```
`Download` envía el tipo que corresponde a la extensión del archivo guardado, y el nombre original
para guardarlo. Las imágenes (salvo SVG), el audio, el vídeo, los PDF y el texto plano se muestran
en el navegador; el resto se descarga, para que un `.html` o un `.svg` subido no se ejecute como una
página más de tu sitio. `with_attachment(true)` obliga a descargar también los primeros. Atiende
las descargas parciales (para reanudar o avanzar en un vídeo), y el navegador vuelve a preguntar
antes de reutilizar el archivo, así que cada visita pasa por tu *handler* y sus permisos.
La ruta debe salir de tu aplicación (la que guardaste en la base de datos), nunca directamente de la
petición: aunque `Download` no sale del directorio de archivos subidos, daría acceso a cualquiera de
ellos.
## 5. Borra los archivos que ya no se usan
Al borrar o sustituir el registro que apunta a un archivo, borra también el archivo:
```rust,no_run
# use pagetop::prelude::*;
async fn delete_photo_file(path: &str) -> Result<(), web::UploadError> {
web::Upload::remove(path).await
}
```
No es un error que el archivo ya no exista, y una ruta que intente salir del directorio de
archivos subidos (con `..`, por ejemplo) se rechaza.
## 6. Ajusta los límites
Los valores por defecto sirven para la mayoría de las aplicaciones:
```toml
[upload]
dir = "uploads" # Where files are saved (relative to the working directory).
max_file_size = 8388608 # 8 MiB per file (0 = only max_request_size).
max_files = 20 # Files per submission (0 = no limit).
max_request_size = 33554432 # 32 MiB for a whole multipart/form-data request (0 = no limit).
```
Las peticiones `multipart/form-data` pueden llegar a `max_request_size`, porque sus archivos se
escriben en disco según llegan. El resto de cuerpos (`web::Form`, JSON) se leen enteros en memoria
y se limitan con `max_body_size` de `[server]` (2 MiB): uno mayor se rechaza con `413`. Ese límite
acota también la suma de los campos de texto de un formulario con archivos.
Un envío con archivos que supera cualquiera de estos límites llega a `receive()` como un error del
usuario, así que el formulario vuelve con el motivo («El envío supera el tamaño máximo de 32 MiB»,
por ejemplo) en lugar de mostrar una página de error.
En producción, el directorio `dir` debe sobrevivir a los despliegues: fuera del directorio de la
aplicación, o en un volumen si usas contenedores. Y si un proxy inverso va delante, su límite de
tamaño también debe admitir los envíos: nginx rechaza por defecto los cuerpos de más de 1 MiB, así
que añade `client_max_body_size 32m;` a su configuración (ve [Detrás de un proxy
inverso](deployment.md#5-detrás-de-un-proxy-inverso)).
## 7. Con HTMX
Un formulario con `form::Enctype::Multipart` se envía igual con HTMX: HTMX respeta su `enctype`.
Sólo si la petición sale de otro elemento que no es el formulario, indícalo con el atributo
`hx::ENCODING` de `pagetop-htmx` y el valor `"multipart/form-data"`.
## El ejemplo completo
Un tablón de fotos del huerto: el formulario sube una foto con su título, y la lista enlaza cada
una, servida por su *handler*. Las fotos se guardan en memoria para no depender de una base de
datos:
```rust,no_run
use pagetop::prelude::*;
use serde::Deserialize;
use std::sync::{Mutex, MutexGuard};
struct Photo {
title: String,
path: String,
original_name: String,
}
static PHOTOS: Mutex<Vec<Photo>> = Mutex::new(Vec::new());
fn photos() -> MutexGuard<'static, Vec<Photo>> {
PHOTOS.lock().unwrap_or_else(|poisoned| poisoned.into_inner())
}
fn photo_upload() -> web::Upload {
web::Upload::new()
.with_subdir("photos")
.with_extensions(["jpg", "jpeg", "png"])
.with_file_fields(["photo"])
.with_max_size(2 * 1024 * 1024)
}
struct Garden;
#[async_trait]
impl Extension for Garden {
fn configure_router(&self, router: Router) -> Router {
router
.route("/photos", web::get(gallery).post(upload))
.route("/photos/{index}", web::get(photo))
}
}
fn photo_form() -> Form {
Form::new()
.with_action("/photos")
.with_method(form::Method::Post)
.with_enctype(form::Enctype::Multipart)
.with_child(
form::input::Field::text()
.with_name("title")
.with_label(Lc::n("Title"))
.with_required(true),
)
.with_child(
form::File::new()
.with_name("photo")
.with_label(Lc::n("Photo"))
.with_accept(photo_upload().accept())
.with_required(true),
)
.with_child(Button::submit(Lc::n("Upload")))
}
fn gallery_page(request: HttpRequest) -> Page {
let list = html! {
ul {
@for (index, photo) in photos().iter().enumerate() {
li { a href=(util::join!("/photos/", index.to_string())) { (photo.title) } }
}
}
};
Page::new(request)
.with_title(Lc::n("Garden photos"))
.with_child(photo_form())
.with_child(Html::with(move |_| list.clone()))
}
async fn gallery(request: HttpRequest) -> Result<Markup, ErrorPage> {
gallery_page(request).render().await
}
async fn show_form(request: HttpRequest, error: Lc) -> Result<Response, ErrorPage> {
let mut page = gallery_page(request);
page.context().push_message(MessageLevel::Error, error);
page.render().await.map(IntoResponse::into_response)
}
#[derive(Deserialize)]
struct PhotoData {
title: String,
}
async fn upload(request: HttpRequest, multipart: web::Multipart) -> Result<Response, ErrorPage> {
let sent = match photo_upload().receive::<PhotoData>(multipart).await {
Ok(sent) => sent,
Err(err) if err.is_client_error() => return show_form(request, err.message()).await,
Err(_) => return Err(ErrorPage::InternalError(Some(request))),
};
let Some(file) = sent.file("photo") else {
return show_form(request, Lc::n("Choose a photo to upload.")).await;
};
let photo = Photo {
title: sent.form().title.clone(),
path: file.path().to_string(),
original_name: file.original_name().to_string(),
};
photos().push(photo);
sent.keep();
let cx = Context::new(request);
Ok(Redirect::see_other(cx.route("/photos")).with_message(
&cx,
MessageLevel::Info,
Lc::n("Photo uploaded."),
))
}
async fn photo(
request: HttpRequest,
web::Path(index): web::Path<usize>,
) -> Result<Response, ErrorPage> {
let found = photos()
.get(index)
.map(|photo| (photo.path.clone(), photo.original_name.clone()));
let Some((path, original_name)) = found else {
return Err(ErrorPage::NotFound(Some(request)));
};
web::Download::new(path)
.with_file_name(original_name)
.serve(&request)
.await
.map_err(|err| match err {
web::UploadError::NotFound(_) => ErrorPage::NotFound(Some(request)),
_ => ErrorPage::InternalError(Some(request)),
})
}
#[pagetop::main]
async fn main() -> std::io::Result<()> {
Application::prepare(&Garden).await.run().await
}
```
## Comprueba
Arranca con `cargo run` y abre <http://localhost:8080/photos>:
1. Sube una foto `.jpg` o `.png` con un título: vuelves a la lista con el aviso «Photo uploaded.»,
y el archivo está en `uploads/photos/` con un nombre aleatorio.
2. Pulsa su enlace: el navegador muestra la foto.
3. Intenta subir otro tipo de archivo (el selector propone sólo fotos, pero la mayoría de los
navegadores permite elegir cualquier archivo): el formulario vuelve con el motivo del rechazo, y
no se guarda nada.
En las pruebas, un envío `multipart/form-data` se escribe a mano con `body()` y su cabecera
`Content-Type`. Para no llenar de archivos el directorio del proyecto, apunta `dir` de `[upload]` a
otro lugar en `config/test.toml` (por ejemplo, `"target/test-uploads"`):
```rust
# use pagetop::prelude::*;
# use serde::Deserialize;
# use std::sync::{Mutex, MutexGuard};
# struct Photo { path: String, original_name: String }
# static PHOTOS: Mutex<Vec<Photo>> = Mutex::new(Vec::new());
# fn photos() -> MutexGuard<'static, Vec<Photo>> {
# PHOTOS.lock().unwrap_or_else(|poisoned| poisoned.into_inner())
# }
# fn photo_upload() -> web::Upload {
# web::Upload::new()
# .with_subdir("photos")
# .with_extensions(["jpg", "jpeg", "png"])
# .with_file_fields(["photo"])
# }
# struct Garden;
# #[async_trait]
# impl Extension for Garden {
# fn configure_router(&self, router: Router) -> Router {
# router
# .route("/photos", web::post(upload))
# .route("/photos/{index}", web::get(photo))
# }
# }
# #[derive(Deserialize)]
# struct PhotoData {
# #[allow(dead_code)]
# title: String,
# }
# async fn show_form(request: HttpRequest, error: Lc) -> Result<Response, ErrorPage> {
# let mut page = Page::new(request);
# page.context().push_message(MessageLevel::Error, error);
# page.render().await.map(IntoResponse::into_response)
# }
# async fn upload(request: HttpRequest, multipart: web::Multipart) -> Result<Response, ErrorPage> {
# let sent = match photo_upload().receive::<PhotoData>(multipart).await {
# Ok(sent) => sent,
# Err(err) if err.is_client_error() => return show_form(request, err.message()).await,
# Err(_) => return Err(ErrorPage::InternalError(Some(request))),
# };
# let Some(file) = sent.file("photo") else {
# return show_form(request, Lc::n("Choose a photo to upload.")).await;
# };
# let photo = Photo {
# path: file.path().to_string(),
# original_name: file.original_name().to_string(),
# };
# photos().push(photo);
# sent.keep();
# Ok(Redirect::see_other("/photos"))
# }
# async fn photo(
# request: HttpRequest,
# web::Path(index): web::Path<usize>,
# ) -> Result<Response, ErrorPage> {
# let found = photos()
# .get(index)
# .map(|photo| (photo.path.clone(), photo.original_name.clone()));
# let Some((path, original_name)) = found else {
# return Err(ErrorPage::NotFound(Some(request)));
# };
# web::Download::new(path)
# .with_file_name(original_name)
# .serve(&request)
# .await
# .map_err(|_| ErrorPage::NotFound(Some(request)))
# }
// A submission with a title and one file, as a browser sends it.
fn photo_body(file_name: &str, content: &str) -> String {
format!(
"--boundary\r\n\
Content-Disposition: form-data; name=\"title\"\r\n\r\n\
First tomatoes\r\n\
--boundary\r\n\
Content-Disposition: form-data; name=\"photo\"; filename=\"{file_name}\"\r\n\
Content-Type: application/octet-stream\r\n\r\n\
{content}\r\n\
--boundary--\r\n"
)
}
fn send_photo(file_name: &str, content: &str) -> web::test::TestRequest {
web::test::TestRequest::post()
.uri("/photos")
.header("content-type", "multipart/form-data; boundary=boundary")
.body(photo_body(file_name, content))
}
#[pagetop::test]
async fn uploads_and_serves_a_photo() {
let app = web::test::init_router(Application::prepare(&Garden).await.test());
// A file of a type not allowed is rejected with the reason, and nothing is saved.
let request = send_photo("tomatoes.exe", "MZ").to_request();
let response = web::test::send_request(&app, request).await;
let body = web::test::read_body_text(response).await;
assert!(body.contains("is not an allowed file type"), "{body}");
assert!(photos().is_empty());
// A photo is saved under a random name and served with its original one.
let request = send_photo("tomatoes.png", "PNG data").to_request();
let response = web::test::send_request(&app, request).await;
assert_eq!(response.status(), web::http::StatusCode::SEE_OTHER);
let saved = photos()[0].path.clone();
assert!(saved.starts_with("photos/") && saved.ends_with(".png"), "{saved}");
let request = web::test::TestRequest::get().uri("/photos/0").to_request();
let response = web::test::send_request(&app, request).await;
assert_eq!(response.status(), web::http::StatusCode::OK);
assert_eq!(response.headers()["content-type"], "image/png");
assert_eq!(web::test::read_body_text(response).await, "PNG data");
web::Upload::remove(saved).await.unwrap();
}
```
## Siguiente
- [Crear y procesar formularios](forms.md): campos, validación y avisos tras redirigir.
- [Opciones de configuración](../reference/configuration.md#upload): todas las claves de
`[upload]`.
- [Desplegar en producción](deployment.md): el proxy inverso delante de la aplicación.

View file

@ -27,6 +27,8 @@ Lo esencial de PageTop en una página. Cada línea enlaza con la guía que lo ex
| [Un segmento de la URL](../how-to/routes.md#3-lee-los-datos-de-la-petición) | `web::Path(id): web::Path<u32>` |
| [Parámetros de consulta](../how-to/routes.md#3-lee-los-datos-de-la-petición) | `web::Query(q): web::Query<T>` |
| [Un formulario](../how-to/forms.md#3-recibe-y-valida-los-datos) | `web::Form(data): web::Form<T>` (el último parámetro) |
| [Un formulario con archivos](../how-to/uploads.md#3-recibe-el-envío) | `upload.receive::<T>(multipart).await` con `multipart: web::Multipart` (el último parámetro) |
| [Servir un archivo subido](../how-to/uploads.md#4-sirve-el-archivo-con-permisos) | `web::Download::new(path).with_file_name(name).serve(&request).await` |
| [Un error 404](../how-to/error-pages.md) | `Err(ErrorPage::NotFound(Some(request)))` |
| [Redirigir](../how-to/routes.md#4-elige-la-respuesta) | `Redirect::see_other("/target")` |
| [Responder JSON](../how-to/routes.md#4-elige-la-respuesta) | `Json(value)` |
@ -98,7 +100,10 @@ Lo esencial de PageTop en una página. Cada línea enlaza con la guía que lo ex
| [Comprobar un permiso](../how-to/users.md#5-protege-rutas-y-adapta-la-interfaz) | `has_permission(&request, &MyPermission::X)` |
| [Una página en el panel](../how-to/admin.md) | `DeclareAdminPages::new(declare_pages)` |
| [Leer un ajuste del panel](../how-to/admin.md#4-lee-los-ajustes-guardados) | `pagetop_admin::settings::get_or("app.key", default).await` |
| [Enviar un correo](../how-to/mail.md#3-envía-un-correo) | `Email::new().with_to(addr).with_subject("...").with_html(markup).send().await` |
| [Un correo traducido](../how-to/mail.md#4-escribe-una-plantilla-traducida) | `Email::from_template(&template, &cx)` |
| [Probar una ruta](../how-to/testing.md) | `web::test::send_request(&app, request).await` |
| [Comprobar un correo enviado](../how-to/mail.md#comprueba) | `pagetop_mail::outbox::take_to("ana@example.com")` |
## Crear un componente

View file

@ -94,9 +94,21 @@ bind_port = 8080
|---|---|---|---|
| `bind_address` | Texto | `"localhost"` | Dirección en la que escucha. `"0.0.0.0"` acepta conexiones de fuera |
| `bind_port` | Entero | `8080` | Puerto |
| `max_body_size` | Entero | `2097152` | Tamaño máximo en bytes (2 MiB) de los cuerpos que se leen enteros en memoria (`web::Form`, JSON) y de la suma de los campos de texto de un formulario con archivos; `0`, sin límite. Un cuerpo mayor se rechaza con `413`; en un formulario con archivos, `receive()` devuelve un error del usuario |
| `client_ip_header` | Texto | `""` | Cabecera con la IP del cliente detrás de un proxy inverso (`"X-Forwarded-For"`, `"X-Real-IP"`...); con varias direcciones vale la última; `"Forwarded"` no se admite. Vacía, la de la conexión. Un nombre no válido impide arrancar. Ver [Detrás de un proxy inverso](../how-to/deployment.md#5-detrás-de-un-proxy-inverso) |
| `trusted_origins` | Lista | `[]` | Orígenes de otras aplicaciones (`"https://shop.example.com"`) desde los que un navegador puede enviar peticiones que cambian estado (`POST`, `PUT`...); las demás que lleguen de otro origen se rechazan con `403` (protección CSRF). Formato `esquema://servidor[:puerto]`; uno no válido impide arrancar. Ver [Sin *tokens* contra CSRF](../how-to/forms.md#6-sin-tokens-contra-csrf) |
## `[upload]`
Archivos subidos con `web::Upload` (ver [Subir y descargar archivos](../how-to/uploads.md)).
| Clave | Tipo | Por defecto | Notas |
|---|---|---|---|
| `dir` | Texto | `"uploads"` | Directorio de los archivos subidos, absoluto o relativo al de trabajo. Se crea al guardar el primer archivo |
| `max_file_size` | Entero | `8388608` | Tamaño máximo en bytes (8 MiB) de cada archivo; `0`, sólo limita `max_request_size`. Cada subida puede cambiarlo con `with_max_size()` |
| `max_files` | Entero | `20` | Archivos de un mismo envío; `0`, sin límite. Cada subida puede cambiarlo con `with_max_files()` |
| `max_request_size` | Entero | `33554432` | Tamaño máximo en bytes (32 MiB) de una petición `multipart/form-data` completa, en lugar de `max_body_size` de `[server]`; `0`, sin límite. Si se supera, `receive()` devuelve un error del usuario con el límite |
## `[log]`
```toml

View file

@ -161,7 +161,8 @@ trazas. Con la *feature* `queue`, `send_later()` guarda antes el correo en una c
datos (con `pagetop-seaorm`), que sobrevive a un reinicio y reintenta los fallos temporales, y
`queue()` lo deja en la cola para enviarlo por lotes con `pagetop-cron` (ver
[`[mail.queue]`](configuration.md#mailqueue)). Los enlaces de un correo se construyen con
`absolute_url()`, sobre `mail.base_url`.
`absolute_url()`, sobre `mail.base_url`. Paso a paso en [Enviar correo
electrónico](../how-to/mail.md).
## Tareas programadas