# 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é](https://developers.openwaf.dev/es/cache/cache-rules/) | `[]` |

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](https://developers.openwaf.dev/es/cache/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). |