# Claves de caché

> Cómo decide el borde que dos peticiones comparten un objeto en caché, cómo entra la cadena de consulta en la clave y qué cabeceras Vary admite.

La **clave de caché** identifica un objeto en caché. Dos peticiones con la misma clave reciben la misma respuesta cacheada.

## Qué forma la clave

| Parte | Cómo se normaliza |
|---|---|
| Sitio | Cada nombre con proxy es un sitio propio, así que los nombres nunca comparten objetos. |
| Host | En minúsculas, sin puerto ni punto final. |
| Ruta | Los escapes `%XX` en mayúsculas, los escapes de caracteres no reservados decodificados y los segmentos `.` y `..` resueltos. `//` se conserva y los caracteres reservados se quedan como llegan (`%2F` y `/` son distintos). Al origen se le envía la misma ruta. |
| Cadena de consulta | Según el [nivel de caché](#query-string). |
| Variante | Solo si el origen envía un [`Vary`](#vary) admitido. |

Las cookies, la cabecera `Authorization` y las cookies del reto y de la puerta de acceso de OpenWAF nunca entran en la clave. Las claves de más de 4 KB no se cachean.

Cambiar los ajustes de consulta de un sitio o de sus reglas cambia sus claves, lo que equivale a purgar ese sitio.

## Cadena de consulta

`cache.query.mode`, que en el panel se llama **Nivel de caché**, decide qué parte de la cadena de consulta entra en la clave:

| Modo | Panel | Clave |
|---|---|---|
| `all` (por defecto) | Estándar: la cadena de consulta entera | La consulta entera, tal como llega. `?v=1` y `?v=2` son objetos distintos. |
| `ignore` | Ignorar la cadena de consulta (ficheros estáticos) | Sin consulta, pero solo en las extensiones estáticas por defecto. Las rutas que hace elegibles una regla conservan su consulta. |
| `none` | Sin cadena de consulta: solo se cachean las peticiones sin ella | Las peticiones con consulta no se cachean (`DYNAMIC`). |
| `include` | Solo estos parámetros | Solo los parámetros de `cache.query.params`. |
| `exclude` | Todos los parámetros salvo estos | Todos los parámetros salvo los de `cache.query.params`, por ejemplo `utm_*`, `fbclid`, `gclid`. |

Un `*` final en `params` casa por prefijo. Con `cache.query.sort` a `true`, los parámetros se ordenan, así que `?b=1&a=2` y `?a=2&b=1` comparten objeto. Una regla de caché puede fijar su propia política de consulta para las peticiones que casan con ella.

> **Consejo**
>
> Mantén la consulta en la clave para los recursos versionados por consulta (`style.css?ver=6.4`) y para los optimizadores de imágenes como `/_next/image?url=…&w=…`. Usa `exclude` para quitar los parámetros de marketing.


## Vary

El borde guarda como mucho una variante por valor de las cabeceras `Vary` admitidas:

| Cabecera `Vary` | Tratamiento |
|---|---|
| `Accept-Encoding` | No divide la caché: una sola copia, descomprimida al vuelo para los visitantes que lo necesitan. |
| `Accept` | Solo en respuestas `image/*`. Se normaliza a `avif`, `webp` u `other`, suficiente para los optimizadores de imágenes. |
| `Origin` | Se normaliza a `esquema://host[:puerto]`. También se aplica cuando la respuesta trae un `Access-Control-Allow-Origin` distinto de `*`, aunque no lleve `Vary: Origin`, para que nunca se sirva la respuesta CORS de un sitio a otro. |
| Cualquier otra, incluidas `*`, `Cookie` y `Authorization` | La respuesta no se guarda (`BYPASS`). |

Una regla de caché puede listar cabeceras de petición en `vary_bypass_if_present` (por ejemplo las cabeceras `RSC` y `Next-Router-*` de Next.js). Una petición que traiga alguna se salta la caché, y un `Vary` del origen que las nombre deja de impedir que se guarde la versión normal. Consulta [Reglas de caché](https://developers.openwaf.dev/es/cache/cache-rules/#vary-bypass).

## Cabeceras que se quitan antes del origen

En las peticiones elegibles, el borde quita cabeceras que no forman parte de la clave pero que un origen podría reflejar en la página, una vía habitual de envenenamiento de caché:

`X-Original-URL`, `X-Rewrite-URL`, `X-HTTP-Method-Override`, `X-HTTP-Method`, `X-Method-Override`, `X-Host`, `X-Forwarded-Scheme`, `X-Forwarded-Server` y `X-Forwarded-Port`.