📝 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

@ -58,16 +58,21 @@ Application::prepare(&MyApp)
v
.run()
8. build the server routes + middleware + static files
9. serve requests until Ctrl+C or SIGTERM
9. start extensions every start(): background services, such as pagetop-cron
10. serve requests until Ctrl+C or SIGTERM
11. shut down extensions every shutdown(), in reverse order
```
Dos consecuencias importantes:
Tres consecuencias importantes:
- **Lo que falla, falla al arrancar.** Una clave mal escrita, un valor no válido, una base de datos
que no responde o una migración rota detienen la aplicación antes de servir una sola petición,
con un mensaje que explica la causa. Nunca hay una aplicación a medias en producción.
- **Lo costoso se hace una vez.** Las traducciones, los ajustes, las acciones y los recursos
estáticos se cargan o se registran al arrancar; en cada petición sólo se consultan.
- **Las pruebas no lanzan nada en segundo plano.** Una prueba prepara la aplicación con
`prepare()` y obtiene su servidor con `test()`, sin llamar a `run()`: hace los pasos 1 a 8, pero
ni arranca los servicios de las extensiones ni ejecuta tareas programadas por su cuenta.
## La petición
@ -78,6 +83,9 @@ request
|
v
+------------------------------------------------------------+
| cross-origin check (CSRF) -> 403 for a POST, PUT... |
| from another origin |
+------------------------------------------------------------+
| static files (/static, /htmx...) -> served directly, |
| without middleware |
+------------------------------------------------------------+
@ -95,6 +103,10 @@ request
response (complete HTML, or a fragment for HTMX)
```
- La **comprobación de origen** rechaza con `403`, antes de llegar al *middleware* de las
extensiones, las peticiones que pueden cambiar algo (`POST`, `PUT`...) y que el navegador indica
que vienen de otro origen: es la protección contra CSRF, sin *tokens* en los formularios. Ver
[Sin *tokens* contra CSRF](../how-to/forms.md#6-sin-tokens-contra-csrf).
- Los **archivos estáticos** se registran después del *middleware*, así que no pasan por él:
servir una hoja de estilos no resuelve sesiones ni consulta la base de datos.
- El **middleware** de cada extensión (`configure_middleware()`) envuelve las rutas de **todas**