📝 Doc cron, mail queue, CSRF and flash messages

Add the scheduled tasks guide, environment variable overrides, the
[mail] and [cron] references, CSRF protection without tokens, flash
messages after redirects and the username policies of pagetop-user.
Update the framework comparison with Poem and Topcoat.
This commit is contained in:
Manuel Cillero 2026-11-02 14:46:28 +01:00
parent 1a41a456d4
commit 4e007feec8
23 changed files with 946 additions and 125 deletions

View file

@ -28,9 +28,27 @@ impl Extension for Board {
}
```
`User` declara por su cuenta lo que necesita: `pagetop-seaorm`, `pagetop-htmx` y el panel
`pagetop-admin`. Al arrancar crea sus tablas y registra sus rutas, entre ellas `/user/login`,
`/user/register` y `/user` (el perfil).
`User` declara por su cuenta lo que necesita: `pagetop-seaorm`, `pagetop-htmx`, `pagetop-mail` y
el panel `pagetop-admin`. Al arrancar crea sus tablas y registra sus rutas, entre ellas
`/user/login`, `/user/register`, `/user` (el perfil), `/user/email` (cambiar el email) y
`/user/password/reset` (recuperar la contraseña).
La recuperación de contraseña envía un correo con un enlace, como el cambio de email, que no se
aplica hasta que se confirma desde la nueva dirección. Además, la cuenta recibe un aviso cuando
cambia su contraseña o se pide cambiar su dirección. Mientras no configures la sección
`[mail]`, los correos se escriben en las trazas en lugar de enviarse; para enviarlos, indica al menos
el transporte, el remitente y la URL pública de la aplicación, que forma los enlaces:
```toml
# config/production.toml
[mail]
transport = "smtp"
from = "Garden board <no-reply@example.com>"
base_url = "https://board.example.com"
[mail.smtp]
host = "smtp.example.com"
```
## 2. Configura la base de datos y el primer administrador
@ -56,8 +74,62 @@ pagetop-user: admin account created.
password: ...
```
Las demás opciones (registro abierto, bloqueo tras intentos fallidos, duración de las sesiones...)
están en la [referencia de configuración](../reference/configuration.md#user).
Las demás opciones (registro abierto, bloqueo tras intentos fallidos, límites por IP, duración de
las sesiones...) están en la [referencia de configuración](../reference/configuration.md#user).
### Elige qué nombres de usuario se aceptan
Cada cuenta tiene un nombre de usuario y un email, los dos obligatorios y únicos, y se puede
iniciar sesión con cualquiera de ellos. Qué nombres de usuario se admiten lo decide
`identity_policy`:
```toml
# config/common.toml
[user]
identity_policy = "unicode"
```
| Valor | Caracteres | Longitud |
|---|---|---|
| `"strict"` (por defecto) | Letras ASCII sin tildes, dígitos, `.`, `_` y `-` | 3 a 32 |
| `"unicode"` | Letras y dígitos de cualquier alfabeto, sin mezclarlos, `.`, `_` y `-` | 3 a 32 |
| `"permissive"` | Los de `"unicode"`, más espacios simples, `'` y `+` | 3 a 60 |
Cada nivel admite todo lo del anterior, y los tres comparten tres reglas:
- **Nunca se admite `@`**, así que un nombre de usuario no puede coincidir con el email de otra
cuenta, que también sirve para entrar.
- **No se distinguen mayúsculas**: `Ana` y `ana` son el mismo usuario. El nombre se muestra tal
como se escribió.
- **No se admiten nombres que se confunden a simple vista con otro existente**: si existe `maria`,
no se puede crear `rnaria`, ni `сосо` (escrito con letras cirílicas) si existe `coco`. Se
comprueba con la tabla de caracteres confusables de Unicode.
Para elegir, piensa en quién crea los nombres más que en dónde se publica la aplicación. Con el
registro abierto, cualquiera escoge un nombre que verán los demás y que aparecerá en el saludo de
sus correos en cuanto verifique su dirección; si las cuentas sólo las crea un administrador, el
riesgo es mucho menor.
| Situación | Política |
|---|---|
| Aplicación en Internet con registro abierto | `"strict"` |
| Comunidad en Internet cuyos usuarios escriben su nombre en su alfabeto | `"unicode"` |
| Aplicación interna con cuentas creadas por administradores | `"strict"` o `"unicode"` |
| Importar cuentas de un sistema con espacios en los nombres (Drupal...) | `"permissive"` |
`"strict"` basta casi siempre: los nombres con tildes o en otros alfabetos tienen su sitio en el
nombre visible de la cuenta. Evita `"permissive"` con el registro abierto, porque los espacios
permiten escribir frases («Soporte técnico», «Llama al 900...») que luego se muestran como nombre.
Puedes cambiar de política cuando quieras, y nadie pierde el acceso:
- **A una más abierta**, las cuentas existentes no cambian.
- **A una más estricta**, los nombres que ya no la cumplen se conservan y sus titulares pueden
seguir entrando y guardando su perfil; sólo un nombre nuevo, o uno que se cambia, debe cumplirla.
Nada se renombra automáticamente.
- **El administrador inicial** (`[user.seed] admin_username`) se comprueba en cada arranque: si no
cumple la política nueva, la aplicación no arranca hasta que pongas uno válido. Cambiarlo no
renombra al administrador que ya existe, y con el valor por defecto, `admin`, no ocurre nunca.
## 3. Pon el menú de cuenta en la cabecera
@ -111,7 +183,7 @@ enum BoardPermission {
impl Permission for BoardPermission {
fn key(&self) -> CowStr {
match self {
Self::PostNotices => "board.post_notices".into(),
Self::PostNotices => "board:post_notices".into(),
}
}
@ -136,7 +208,7 @@ Para que aparezca en la pantalla de roles, regístralo con la acción `DeclarePe
# #[derive(Clone, Copy, Debug)]
# enum BoardPermission { PostNotices }
# impl Permission for BoardPermission {
# fn key(&self) -> CowStr { "board.post_notices".into() }
# fn key(&self) -> CowStr { "board:post_notices".into() }
# }
use pagetop_user::PermissionRegistry;
use pagetop_user::prelude::*;
@ -167,7 +239,7 @@ impl Extension for Board {
# #[derive(Clone, Copy, Debug)]
# enum BoardPermission { PostNotices }
# impl Permission for BoardPermission {
# fn key(&self) -> CowStr { "board.post_notices".into() }
# fn key(&self) -> CowStr { "board:post_notices".into() }
# }
async fn new_notice(request: HttpRequest) -> Result<Markup, ErrorPage> {
require_permission(&request, &BoardPermission::PostNotices)?;
@ -185,7 +257,7 @@ async fn new_notice(request: HttpRequest) -> Result<Markup, ErrorPage> {
# #[derive(Clone, Copy, Debug)]
# enum BoardPermission { PostNotices }
# impl Permission for BoardPermission {
# fn key(&self) -> CowStr { "board.post_notices".into() }
# fn key(&self) -> CowStr { "board:post_notices".into() }
# }
async fn board(request: HttpRequest) -> Result<Markup, ErrorPage> {
let can_post = has_permission(&request, &BoardPermission::PostNotices);
@ -244,7 +316,7 @@ enum BoardPermission {
impl Permission for BoardPermission {
fn key(&self) -> CowStr {
match self {
Self::PostNotices => "board.post_notices".into(),
Self::PostNotices => "board:post_notices".into(),
}
}