✨ (pagetop): Añade subida y descarga de archivos

- `web::Upload` guarda los archivos de un envío multipart en disco por
  trozos, con nombre aleatorio, extensiones y tamaño máximo por archivo.
  `receive()` deserializa además los campos de texto con serde_qs.
- `web::Download` sirve un archivo subido con rangos y peticiones
  condicionales, inline sólo para tipos pasivos y con nosniff.
- `form::File`, componente para elegir archivos, y soporte en Bootsier.
- Límite del cuerpo según el tipo de contenido: `server.max_body_size`
  baja a 2 MiB y el nuevo `upload.max_request_size` (32 MiB) se aplica
  sólo a multipart/form-data.
This commit is contained in:
Manuel Cillero 2026-10-31 15:28:58 +01:00
parent 5540c0c6a0
commit f3228d6b59
21 changed files with 2240 additions and 17 deletions

View file

@ -1,7 +1,7 @@
//! Definiciones para crear formularios ([`Form`]).
mod props;
pub use props::{Autocomplete, AutofillField, CheckboxKind, Method};
pub use props::{Autocomplete, AutofillField, CheckboxKind, Enctype, Method};
mod component;
pub use component::Form;
@ -42,5 +42,8 @@ pub use range::Range;
mod textarea;
pub use textarea::Textarea;
mod file;
pub use file::File;
mod hidden;
pub use hidden::Hidden;

View file

@ -10,6 +10,8 @@ use crate::base::component::form;
/// - `classes`: clases CSS adicionales (p. ej. utilidades CSS).
/// - `action`: URL/ruta de destino para el envío.
/// - `method`: método usado por el formulario para el envío de los datos (ver [`form::Method`]).
/// - `enctype`: codificación de los datos enviados (ver [`form::Enctype`]); los formularios con
/// archivos necesitan [`form::Enctype::Multipart`].
/// - `accept-charset`: juego de caracteres aceptado (por defecto es `"UTF-8"`).
/// - `children`: contenido del formulario.
///
@ -50,6 +52,8 @@ pub struct Form {
action: Route,
/// Devuelve el método para enviar el formulario.
method: form::Method,
/// Devuelve la codificación de los datos enviados por el formulario.
enctype: form::Enctype,
/// Devuelve el juego de caracteres aceptado por el formulario.
#[default(_code = "AttrValue::new(\"UTF-8\")")]
charset: AttrValue,
@ -76,11 +80,16 @@ impl Component for Form {
form::Method::Post => Some("post"),
form::Method::Get => None,
};
let enctype = match self.enctype() {
form::Enctype::UrlEncoded => None,
form::Enctype::Multipart => Some("multipart/form-data"),
};
Ok(html! {
form
(self.props().unpack(cx))
action=[self.action().try_resolve(cx)]
method=[method]
enctype=[enctype]
accept-charset=[self.charset().as_deref()]
{
(self.children().render(cx).await)
@ -123,6 +132,15 @@ impl Form {
self
}
/// Establece la codificación de los datos enviados por el formulario.
///
/// - `UrlEncoded`: el atributo `enctype` se omite (por defecto).
/// - `Multipart`: se establece `enctype="multipart/form-data"`, necesario para subir archivos.
pub fn with_enctype(mut self, enctype: form::Enctype) -> Self {
self.enctype = enctype;
self
}
/// Establece el juego de caracteres aceptado por el formulario.
///
/// Por defecto se utiliza `"UTF-8"`.

View file

@ -0,0 +1,181 @@
//! Definiciones para crear campos de selección de archivos en formularios.
use crate::prelude::*;
/// Componente para crear un **campo de selección de archivos** de formulario (`type="file"`).
///
/// Permite elegir uno o varios archivos del equipo para enviarlos con el formulario, con una
/// etiqueta opcional, un texto de ayuda y los tipos de archivo aceptados (`accept`).
///
/// El formulario debe usar la codificación [`form::Enctype::Multipart`]; sin ella, el navegador
/// envía sólo el nombre del archivo.
///
/// # Ejemplo
///
/// ```rust,no_run
/// use pagetop::prelude::*;
///
/// let form = Form::new()
/// .with_action("/documents")
/// .with_enctype(form::Enctype::Multipart)
/// .with_child(
/// form::File::new()
/// .with_name("attachments")
/// .with_label(Lc::n("Attachments"))
/// .with_accept(".pdf,image/*")
/// .with_multiple(true)
/// .with_help_text(Lc::n("PDF documents or images.")),
/// )
/// .with_child(Button::submit(Lc::n("Send")));
/// ```
///
/// Al enviar el formulario, cada archivo llega en una parte propia del cuerpo con el `name` del
/// campo (varias con el mismo nombre si se eligen varios archivos). Si no se elige ninguno, el
/// navegador envía igualmente una parte vacía, sin nombre de archivo. En el servidor,
/// [`web::Upload::receive()`] recibe el envío completo, guarda los archivos e ignora esa parte
/// vacía.
///
/// `accept` es sólo una ayuda para el usuario al elegir el archivo: no impide enviar otros tipos,
/// así que el servidor debe comprobarlos igualmente con [`web::Upload::with_extensions()`].
/// [`web::Upload::accept()`] devuelve esas mismas extensiones con el formato de `accept`.
#[derive(AutoDefault, Clone, Debug, Getters)]
pub struct File {
/// Devuelve identificador, clases CSS, atributos HTML y valores extra del componente.
props: Props,
/// Devuelve el nombre del campo.
name: AttrName,
/// Devuelve la etiqueta del campo.
label: Lc,
/// Devuelve el texto de ayuda del campo.
help_text: Lc,
/// Devuelve los tipos de archivo aceptados.
accept: AttrValue,
/// Devuelve si se pueden elegir varios archivos.
multiple: bool,
/// Devuelve si el campo recibe el foco automáticamente al cargar la página.
autofocus: bool,
/// Devuelve si el campo es obligatorio.
required: bool,
/// Devuelve si el campo está deshabilitado.
disabled: bool,
}
#[async_trait]
impl Component for File {
fn new() -> Self {
Self::default()
}
fn id(&self) -> Option<String> {
self.props.get_id()
}
fn setup(&mut self, _cx: &mut Context) {
if let Some(container_id) = self
.id()
.or_else(|| self.name().as_deref().map(|n| util::join!("edit-", n)))
{
self.alter_prop(PropsOp::ensure_id(container_id));
}
// Clases CSS del contenedor del campo.
self.alter_prop(PropsOp::prepend_classes("form-field form-field-file"));
}
async fn prepare(&self, cx: &mut Context) -> Result<Markup, ComponentError> {
let container_id = self.id();
let input_id = container_id.as_deref().map(|id| util::join!(id, "-file"));
let help = form::parts::Help::new(self.help_text(), input_id.as_deref());
let label = form::parts::Label::new(self.label(), input_id.as_deref())
.with_required(*self.required());
Ok(html! {
div (self.props().unpack(cx)) {
(label.render(cx))
input
type="file"
id=[input_id.as_deref()]
aria-describedby=[help.id()]
class="form-control"
name=[self.name().as_deref()]
accept=[self.accept().as_deref()]
multiple[*self.multiple()]
autofocus[*self.autofocus()]
required[*self.required()]
disabled[*self.disabled()];
(help.render(cx))
}
})
}
}
#[builder_impl]
impl File {
// **< File BUILDER >***************************************************************************
/// Establece el identificador único del componente; igual a `with_prop(PropsOp::set_id(id))`.
pub fn with_id(mut self, id: impl Into<CowStr>) -> Self {
self.props.alter_id(id);
self
}
/// Modifica identificador, clases CSS, atributos HTML o valores extra del componente.
pub fn with_prop(mut self, op: impl Into<PropsOp>) -> Self {
self.props.alter_prop(op);
self
}
/// Establece el nombre del campo (atributo `name`).
///
/// Sin él, los archivos no se transmiten al servidor al enviar el formulario. Es el nombre que
/// devuelve `name()` en cada parte recibida con [`web::Multipart`].
pub fn with_name(mut self, name: impl AsRef<str>) -> Self {
self.name.alter_name(name);
self
}
/// Establece la etiqueta visible del campo (usa [`Lc::none()`] para quitarla).
pub fn with_label(mut self, label: Lc) -> Self {
self.label = label;
self
}
/// Establece el texto de ayuda del campo (usa [`Lc::none()`] para quitarlo).
pub fn with_help_text(mut self, help_text: Lc) -> Self {
self.help_text = help_text;
self
}
/// Establece los tipos de archivo aceptados (atributo `accept`), separados por comas.
///
/// Admite extensiones (`.pdf`), tipos MIME (`application/pdf`) y familias de tipos (`image/*`),
/// p. ej. `".pdf,image/*"`. Una cadena vacía quita el atributo y se acepta cualquier archivo.
pub fn with_accept(mut self, accept: impl AsRef<str>) -> Self {
self.accept.alter_str(accept);
self
}
/// Establece si se pueden elegir varios archivos a la vez.
pub fn with_multiple(mut self, multiple: bool) -> Self {
self.multiple = multiple;
self
}
/// Establece si el campo recibe el foco automáticamente al cargar la página.
pub fn with_autofocus(mut self, autofocus: bool) -> Self {
self.autofocus = autofocus;
self
}
/// Establece si el campo es obligatorio.
pub fn with_required(mut self, required: bool) -> Self {
self.required = required;
self
}
/// Establece si el campo está deshabilitado.
pub fn with_disabled(mut self, disabled: bool) -> Self {
self.disabled = disabled;
self
}
}

View file

@ -468,8 +468,8 @@ impl AutofillField {
/// cifran** por sí mismos; por eso es esencial el uso de HTTPS.
/// - **Tamaño**: GET está limitado por la longitud máxima de URL que acepten el navegador y el
/// servidor. POST es más flexible para cargas grandes.
/// - **Ficheros**: la subida de ficheros requiere `method="post"` y un `enctype` adecuado
/// (habitualmente `multipart/form-data`).
/// - **Archivos**: la subida de archivos requiere `method="post"` y la codificación
/// [`Enctype::Multipart`].
#[derive(AutoDefault, Clone, Copy, Debug, PartialEq)]
pub enum Method {
/// Envía los datos en el cuerpo de la petición.
@ -484,3 +484,28 @@ pub enum Method {
/// Recomendado para búsquedas y operaciones que no modifican datos ni el estado del sistema.
Get,
}
// **< Enctype >************************************************************************************
/// Codificación usada por un [`Form`](super::Form) para enviar los datos con el método
/// [`Method::Post`].
///
/// Corresponde al atributo `enctype` del formulario. El navegador lo ignora con [`Method::Get`],
/// que siempre codifica los datos en la URL.
#[derive(AutoDefault, Clone, Copy, Debug, PartialEq)]
pub enum Enctype {
/// Pares `name=value` codificados como en una URL (`application/x-www-form-urlencoded`). Es la
/// **codificación por defecto**, y el atributo `enctype` se omite.
///
/// En el servidor se reciben con los extractores [`web::Form`] o [`web::RawForm`].
#[default]
UrlEncoded,
/// Cada campo en una parte propia del cuerpo (`multipart/form-data`). **Imprescindible para
/// subir archivos** con [`form::File`](super::File); sin ella, el navegador envía sólo el nombre
/// del archivo.
///
/// En el servidor se recibe con el extractor [`web::Multipart`], y los archivos se guardan con
/// [`web::Upload`].
Multipart,
}