✨ Mensajes flash y Messages automático en Content

- Componentes aplazados: `Component::is_deferred()` deja una marca
  `<!-- placeholder ... -->` y `Page::render()` los renderiza al final
  del `<body>`, en su sitio. Si no generan nada, la marca se queda.
- `Region` empieza `Content` con un `Messages` aplazado, que recoge
  todos los mensajes de la página. Las aplicaciones ya no tienen que
  añadirlo.
- `Messages` retira los mensajes que muestra y admite `with_deferred()`.
- `ResponseExt::with_message()` deja mensajes para la página siguiente
  en una cookie técnica de vida corta, que sólo se crea si se usa.
- Basic y Bootsier ocultan las regiones vacías con `.region:empty`.
This commit is contained in:
Manuel Cillero 2026-11-02 13:20:36 +01:00
parent a110dd0482
commit c9fdc7afc7
18 changed files with 935 additions and 49 deletions

269
src/response/flash.rs Normal file
View file

@ -0,0 +1,269 @@
//! Mensajes para la página siguiente (mensajes *flash*).
//!
//! Viajan en una *cookie* de vida corta, sin guardar nada en el servidor ni necesitar sesión: la
//! respuesta que los añade la crea, la página siguiente los muestra y su respuesta la borra.
use crate::core::component::{Context, MessageLevel, StatusMessage};
use crate::locale::Lc;
use crate::response::ErrorPage;
use crate::trace;
use crate::web::{Request, Response, http, push_percent_encoded};
use axum::middleware::Next;
const COOKIE_NAME: &str = "pagetop_flash";
// Atributos de la *cookie*. Basta con un minuto: es el tiempo de seguir una redirección.
const COOKIE_ATTRS: &str = "; Path=/; HttpOnly; SameSite=Lax; Max-Age=60";
const EXPIRED_COOKIE: &str = "pagetop_flash=; Path=/; HttpOnly; SameSite=Lax; Max-Age=0";
// Los navegadores admiten al menos 4096 bytes por *cookie*, contando nombre y atributos.
const MAX_VALUE_LEN: usize = 3800;
// Separa los mensajes en el valor de la *cookie*: no aparece en el texto codificado.
const SEPARATOR: char = '|';
// Mensajes añadidos a una respuesta con `with_message()`, pendientes de guardar en la *cookie*.
#[derive(Clone, Default)]
struct Pending(Vec<(MessageLevel, String)>);
/// Añade a una respuesta mensajes para mostrar en la página siguiente.
///
/// Es la forma de avisar del resultado de una acción tras redirigir a otra página (cuenta creada,
/// cambios guardados...), como los mensajes *flash* de otros *frameworks*. Los mensajes viajan en
/// una *cookie* de vida corta, ya traducidos al idioma de `cx`, y la página siguiente los añade a
/// su [`Context`] como si se hubieran acumulado con [`Context::push_message()`]. Los muestra el
/// componente [`Messages`] que encabeza la región [`CoreRegions::Content`], o uno propio de la
/// página.
///
/// Si la respuesta siguiente es otra redirección, los mensajes esperan a la página posterior.
///
/// La *cookie* (`pagetop_flash`) sólo se crea cuando una respuesta usa este método; una aplicación
/// que no lo usa no envía ninguna. Es una *cookie* técnica: surge de una acción del usuario, dura
/// como mucho un minuto, se borra en cuanto se muestran los mensajes y no contiene datos que lo
/// identifiquen. Como *cookie* estrictamente necesaria para el servicio que el usuario ha pedido,
/// suele quedar exenta de consentimiento, aunque conviene declararla en la política de *cookies* de
/// la aplicación.
///
/// El texto se muestra siempre como texto plano: el marcado que tenga una traducción aparecería
/// tal cual. Cada mensaje debe ser breve; los que no quepan en la *cookie* (unos 3,8 KB entre
/// todos) se descartan con un aviso en las trazas.
///
/// # Ejemplo
///
/// ```rust,no_run
/// # use pagetop::prelude::*;
/// async fn save(request: HttpRequest) -> Response {
/// let cx = Context::new(request);
/// // ... guarda los cambios ...
/// Redirect::see_other(cx.route("/settings"))
/// .with_message(&cx, MessageLevel::Info, Lc::n("Settings saved."))
/// }
/// ```
///
/// [`Context::push_message()`]: crate::core::component::Context::push_message
/// [`CoreRegions::Content`]: crate::core::theme::CoreRegions::Content
/// [`Messages`]: crate::base::component::Messages
pub trait ResponseExt {
/// Añade un mensaje para la página siguiente, traducido con el idioma del contexto.
fn with_message(self, cx: &Context, level: MessageLevel, text: Lc) -> Response;
}
impl ResponseExt for Response {
fn with_message(mut self, cx: &Context, level: MessageLevel, text: Lc) -> Response {
if let Some(text) = text.lookup(cx).filter(|text| !text.is_empty()) {
self.extensions_mut()
.get_or_insert_default::<Pending>()
.0
.push((level, text));
}
self
}
}
// Lee los mensajes de la *cookie* de la petición, para el `Context` de la página. Con un valor
// manipulado no hace más que mostrar texto plano, que `Lc::n()` escapa al renderizarse.
pub(crate) fn read_flash_messages(headers: &http::HeaderMap) -> Vec<StatusMessage> {
let Some(value) = cookie_value(headers) else {
return Vec::new();
};
value
.split(SEPARATOR)
.filter_map(|entry| {
let level = match entry.as_bytes().first()? {
b'i' => MessageLevel::Info,
b'w' => MessageLevel::Warning,
b'e' => MessageLevel::Error,
_ => return None,
};
let text = percent_decode(&entry[1..])?;
Some(StatusMessage::new(level, Lc::n(text)))
})
.collect()
}
// Guarda en la *cookie* los mensajes que añade la respuesta y la borra cuando la página siguiente
// ya los ha mostrado. Sin *cookie* en la petición ni mensajes nuevos, no hace nada más.
pub(crate) async fn keep_flash_messages(request: Request, next: Next) -> Response {
let previous = cookie_value(request.headers()).map(str::to_owned);
let mut response = next.run(request).await;
let pending = response.extensions_mut().remove::<Pending>();
if previous.is_none() && pending.is_none() {
return response;
}
// Una página (también de error) ya ha mostrado los mensajes anteriores; una redirección, o
// algo que no sea una página (un archivo, JSON...), los conserva para la siguiente.
let shown = !is_redirect(&response) && is_page(&response);
let mut value = match previous {
Some(previous) if !shown => {
if pending.is_none() {
return response;
}
previous
}
_ => String::new(),
};
for (level, text) in pending.map(|pending| pending.0).unwrap_or_default() {
push_message(&mut value, level, &text);
}
let cookie = if value.is_empty() {
EXPIRED_COOKIE.to_owned()
} else {
crate::util::join!(COOKIE_NAME, "=", value, COOKIE_ATTRS)
};
if let Ok(cookie) = http::HeaderValue::from_str(&cookie) {
response
.headers_mut()
.append(http::header::SET_COOKIE, cookie);
}
response
}
fn is_redirect(response: &Response) -> bool {
response.status().is_redirection()
|| response.headers().contains_key("hx-redirect")
|| response.headers().contains_key("hx-location")
}
fn is_page(response: &Response) -> bool {
response.extensions().get::<ErrorPage>().is_some()
|| response
.headers()
.get(http::header::CONTENT_TYPE)
.and_then(|value| value.as_bytes().get(..9))
.is_some_and(|essence| essence.eq_ignore_ascii_case(b"text/html"))
}
// Añade un mensaje al valor de la *cookie*, si cabe.
fn push_message(value: &mut String, level: MessageLevel, text: &str) {
let mut entry = String::with_capacity(text.len() + 1);
entry.push(match level {
MessageLevel::Info => 'i',
MessageLevel::Warning => 'w',
MessageLevel::Error => 'e',
});
push_percent_encoded(&mut entry, text);
let separator = usize::from(!value.is_empty());
if value.len() + separator + entry.len() > MAX_VALUE_LEN {
trace::warn!("Flash message discarded, it does not fit in the cookie: {text:?}");
return;
}
if separator == 1 {
value.push(SEPARATOR);
}
value.push_str(&entry);
}
// Valor de la *cookie* de mensajes, si la petición la trae. Con HTTP/2 el navegador puede repartir
// las *cookies* en varias cabeceras `cookie`.
fn cookie_value(headers: &http::HeaderMap) -> Option<&str> {
headers
.get_all(http::header::COOKIE)
.iter()
.filter_map(|value| value.to_str().ok())
.flat_map(|cookies| cookies.split(';'))
.filter_map(|part| part.trim().strip_prefix(COOKIE_NAME)?.strip_prefix('='))
.find(|value| !value.is_empty())
}
// Decodifica `%XX`; devuelve `None` si la secuencia no es válida o el resultado no es UTF-8.
fn percent_decode(encoded: &str) -> Option<String> {
let mut bytes = Vec::with_capacity(encoded.len());
let mut input = encoded.bytes();
while let Some(byte) = input.next() {
if byte == b'%' {
let hex = [input.next()?, input.next()?];
bytes.push(u8::from_str_radix(std::str::from_utf8(&hex).ok()?, 16).ok()?);
} else {
bytes.push(byte);
}
}
String::from_utf8(bytes).ok()
}
#[cfg(test)]
mod tests {
use super::*;
fn headers(cookie: &str) -> http::HeaderMap {
let mut headers = http::HeaderMap::new();
headers.insert(http::header::COOKIE, cookie.parse().unwrap());
headers
}
fn texts(cookie: &str) -> Vec<(MessageLevel, String)> {
read_flash_messages(&headers(cookie))
.iter()
.map(|m| (*m.level(), m.text().get().unwrap()))
.collect()
}
#[test]
fn messages_round_trip_through_the_cookie_value() {
let mut value = String::new();
push_message(
&mut value,
MessageLevel::Info,
"Cuenta creada | ¡bienvenida!",
);
push_message(&mut value, MessageLevel::Error, "a;b=c, \"d\"");
assert!(
value
.bytes()
.all(|b| b.is_ascii_graphic() && !b"; ,\"\\".contains(&b))
);
let cookie = format!("sid=abc; {COOKIE_NAME}={value}");
assert_eq!(
texts(&cookie),
[
(
MessageLevel::Info,
"Cuenta creada | ¡bienvenida!".to_owned()
),
(MessageLevel::Error, "a;b=c, \"d\"".to_owned()),
]
);
}
#[test]
fn invalid_entries_are_skipped() {
let cookie = format!("{COOKIE_NAME}=iok|xbad|e%E2%28|w%4|i%41b");
assert_eq!(
texts(&cookie),
[
(MessageLevel::Info, "ok".to_owned()),
(MessageLevel::Info, "Ab".to_owned()),
]
);
assert!(texts("other=1").is_empty());
}
#[test]
fn messages_that_do_not_fit_are_discarded() {
let mut value = String::new();
let long = "x".repeat(MAX_VALUE_LEN - 10);
push_message(&mut value, MessageLevel::Info, &long);
push_message(&mut value, MessageLevel::Info, "does not fit");
assert_eq!(value.len(), MAX_VALUE_LEN - 9);
}
}

View file

@ -190,28 +190,40 @@ impl Page {
///
/// El proceso de renderizado de la página sigue esta secuencia:
///
/// 1. Ejecuta
/// [`Theme::before_render_page_body()`](crate::core::theme::Theme::before_render_page_body)
/// para que el tema pueda ejecutar acciones específicas antes de renderizar el `<body>`.
/// 1. Ejecuta [`Theme::before_render_page_body()`] para que el tema pueda ejecutar acciones
/// específicas antes de renderizar el `<body>`.
/// 2. Despacha [`action::page::BeforeRenderBody`] para que otras extensiones puedan realizar
/// ajustes previos sobre la página.
/// 3. **Construye el contenido del `<body>`**:
/// - Renderiza la región reservada superior ([`ReservedRegions::PageTop`]).
/// - Llama a [`Theme::render_page_body()`](crate::core::theme::Theme::render_page_body) para
/// renderizar las regiones del cuerpo principal de la página.
/// - Llama a [`Theme::render_page_body()`] para renderizar las regiones del cuerpo principal
/// de la página.
/// - Renderiza la región reservada inferior ([`ReservedRegions::PageBottom`]).
/// 4. Ejecuta
/// [`Theme::after_render_page_body()`](crate::core::theme::Theme::after_render_page_body)
/// para que el tema pueda aplicar ajustes finales.
///
/// Los componentes que se aplazan ([`Component::is_deferred()`]), como el componente
/// [`Messages`] que encabeza la región [`CoreRegions::Content`], dejan de momento una marca
/// en su lugar.
/// 4. Ejecuta [`Theme::after_render_page_body()`] para que el tema pueda aplicar ajustes
/// finales.
/// 5. Despacha [`action::page::AfterRenderBody`] para permitir que otras extensiones realicen
/// sus últimos ajustes tras generar el `<body>`.
/// 6. Renderiza el `<head>` llamando a
/// [`Theme::render_page_head()`](crate::core::theme::Theme::render_page_head).
/// 7. Obtiene el idioma y la dirección del texto a partir de
/// [`Context::langid()`](crate::core::component::Context::langid) e inserta los atributos
/// `lang` y `dir` en la etiqueta `<html>`.
/// 8. Compone el documento HTML completo (`<!DOCTYPE html>`, `<html>`, `<head>`, `<body>`) y
/// 6. Renderiza los componentes aplazados y sustituye sus marcas por el resultado; si alguno no
/// genera nada, su marca se queda. Así muestran también lo que se haya acumulado en el
/// contexto en los pasos anteriores (por ejemplo, los mensajes para el usuario).
/// 7. Renderiza el `<head>` llamando a [`Theme::render_page_head()`].
/// 8. Obtiene el idioma y la dirección del texto a partir de [`Context::langid()`] e inserta
/// los atributos `lang` y `dir` en la etiqueta `<html>`.
/// 9. Compone el documento HTML completo (`<!DOCTYPE html>`, `<html>`, `<head>`, `<body>`) y
/// devuelve un [`Result`] con el [`Markup`] final.
///
/// [`Theme::before_render_page_body()`]: crate::core::theme::Theme::before_render_page_body
/// [`Theme::render_page_body()`]: crate::core::theme::Theme::render_page_body
/// [`Theme::after_render_page_body()`]: crate::core::theme::Theme::after_render_page_body
/// [`Theme::render_page_head()`]: crate::core::theme::Theme::render_page_head
/// [`CoreRegions::Content`]: crate::core::theme::CoreRegions::Content
/// [`Component::is_deferred()`]: crate::core::component::Component::is_deferred
/// [`Context::langid()`]: crate::core::component::Context::langid
/// [`Messages`]: crate::base::component::Messages
pub async fn render(&mut self) -> Result<Markup, ErrorPage> {
// Acciones específicas del tema antes de renderizar el <body>.
self.context.theme().before_render_page_body(self);
@ -219,7 +231,8 @@ impl Page {
// Acciones de las extensiones antes de renderizar el <body>.
action::page::BeforeRenderBody::dispatch(self);
// Renderiza el <body>.
// Renderiza el <body>, aplazando los componentes que lo pidan.
self.context.start_deferring();
let body = html! {
(layout::Region::of(&ReservedRegions::PageTop).render(&mut self.context).await)
(self.context.theme().render_page_body(self).await)
@ -232,6 +245,9 @@ impl Page {
// Acciones de las extensiones después de renderizar el <body>.
action::page::AfterRenderBody::dispatch(self);
// Renderiza los componentes aplazados, antes del <head> para que lleguen sus recursos.
let body = self.context.render_deferred(body).await;
// Renderiza el <head>.
let head = self.context.theme().render_page_head(self).await;