Referencia de ajustes de caché

Todos los ajustes de caché y de Early Hints con su valor por defecto y sus límites, la API y los límites de purga, la CLI y las herramientas MCP.

Ajustes de caché

Claves de cache en los ajustes del borde de la zona (GET/PATCH /v1/orgs/{org}/zones/{zone}/edge), que cada nombre puede sustituir en hosts.<nombre>.cache.

Clave	Valores	Por defecto
`cache.enabled`	`true`, `false`	`false`
`cache.dev_mode_until`	Fecha y hora RFC 3339, o `null` (desactivado)	desactivado
`cache.query.mode`	`all`, `ignore`, `none`, `include`, `exclude`	`all`
`cache.query.params`	Nombres de parámetro (`*` final = prefijo); obligatorio con `include`/`exclude`	`[]`
`cache.query.sort`	`true`, `false`	`false`
`cache.browser_ttl`	Segundos, de `0` a `31536000`; `0` = respetar el origen	`0`
`cache.deception_armor`	`true`, `false`	`true`
`cache.serve_stale.while_revalidate`	`true`, `false`	`true`
`cache.serve_stale.on_error_max_s`	Segundos, de `0` a `2592000`; `0` = nunca	`86400`
`cache.max_object_mb`	De `1` a `512`	`100`
`cache.rules`	Hasta 25 reglas de caché	`[]`

El cuerpo del PATCH es un JSON merge patch: los objetos se combinan campo a campo, las listas (rules, query.params) se sustituyen enteras, "dev_mode_until": null desactiva el modo desarrollo y "cache": null devuelve todos los valores por defecto.

Límites de las reglas de caché

Elemento	Límite
Reglas por zona o por nombre	25
Valores por lista de condición	32
Rangos de estado por regla	10, códigos de 100 a 599
TTL (`edge_ttl.ttl_s`, `browser_ttl.ttl_s`, TTL por estado)	De 1 segundo a 1 año; los TTL por estado admiten además `0` (revalidar siempre) y `-1` (no guardar)
`serve_stale.on_error_max_s`	Hasta 30 días
Extensión	Letras y dígitos, hasta 16 caracteres
Id de regla	Letras, dígitos, `-` y `_`; por defecto `r1`, `r2`…

Comportamiento fijo

Elemento	Valor
TTL por defecto sin cabeceras de frescura	2 h (`200`, `206`, `301`), 20 min (`302`, `303`), 3 min (`404`, `410`)
Directorios de build de frameworks	7 días
Vida máxima de un objeto	30 días
Clave de caché más larga	4 KB
Espera ante un fallo simultáneo del mismo objeto	5 segundos

Ajustes de Early Hints

Clave	Valores	Por defecto
`early_hints.enabled`	`true`, `false`	`false`
`early_hints.mode`	`origin_links`, `html_head`, `both`	`both`
`early_hints.extra_origins`	Hasta 10 orígenes `https://host[:puerto]`	`[]`

Consulta Early Hints.

API de purga

Ruta	Rol	Para qué
`POST /v1/orgs/{org}/zones/{zone}/cache/purge`	`tech` o token de solo purga	Purga. Cuerpo: exactamente uno de `purge_everything`, `files`, `prefixes`, `hosts`, `tags` (≤ 100 valores). `?dry_run=1` normaliza sin purgar.
`GET /v1/orgs/{org}/zones/{zone}/cache/purges?limit=N`	cualquiera, o token de solo purga	Purgas recientes (las más nuevas primero, como mucho 100) con `nodes` y `applied`.

Estado	Código	Cuándo
`409`	`zone_not_active`	La zona no está activa.
`429`	`rate_limited`	Más de 10 purgas por minuto (ráfaga de 30) de todo, prefijos, nombres y etiquetas, o más de 500 URL por minuto. `Retry-After` indica cuándo reintentar.
`403`	`token_scope`	Un token de solo purga llamó a otra ruta.

CLI

Orden	Para qué
`openwaf-cloud ctl zones set <zona> [--host <nombre>] cache.…=… early_hints.…=…`	Cambia los ajustes de caché y de Early Hints.
`openwaf-cloud ctl zones set <zona> --host <nombre> --unset cache`	El nombre vuelve a heredar la caché de la zona.
`openwaf-cloud ctl zones effective <zona> <nombre>`	Caché efectiva de un nombre.
`openwaf-cloud ctl cache purge <zona> --everything \| --url U… \| --prefix nombre/ruta… \| --host nombre… \| --tag t…`	Purga.
`openwaf-cloud ctl cache purges <zona> [--limit N]`	Purgas recientes y su propagación.

Herramientas MCP

Herramienta	Para qué
`update_settings`	Cambia `cache` y `early_hints` (con `host` para un nombre).
`effective_config`	Configuración efectiva de un nombre, caché incluida.
`purge_cache`	Purga (en dos pasos).

Referencia de ajustes de caché

#Ajustes de caché

#Límites de las reglas de caché

#Comportamiento fijo

#Ajustes de Early Hints

#API de purga

#CLI

#Herramientas MCP