Cache-Control

Sintaxis

Las directivas para almacenamiento temporal siguen las siguientes reglas de validacin:

• Insensible a maysculas, pero las minsculas son recomendadas, debido a que algunas implementaciones no reconocen las directivas en mayusculas.
• Las multipes directivas son separadas por comas.
• Algunas directivas tienen un argumento opcional.

Directivas de cache

Las directivas Cache-Control estndar estn definidas a continuacin.

Nota: Comprueba la tabla de compatibilidad para su soporte; los agentes de usuario que no las reconozcan deberan ignorarlas.

Vocabulario

Los siguientes trminos son usados en este documento; algunos provienen de la especificacin.

Cach (HTTP)

Implementacin que mantiene peticiones y respuestas para reusarlas en peticiones posteriores. Puede ser tanto una cache privada como una compartida.

Cach compartida

Cach existente entre el servidor de origen y los clientes (p. ej. Proxy, CDN). Almacena una sola respuesta para reutilizarla en multiples usuarios por tanto los desarrolladores deberan evitar que el almacenamiento de contenidos personalizados sea cacheado en la cach compartida.

Cach privada

Cach existente en el cliente. Tambin conocida como cach local, o cach del navegador. Puede almacenar y reutilizar contenido personalizado para un nico usuario.

Respuesta almacenada

Almacena una respuesta en caches cuando es cacheable. Pero no siempre es reutilizada tal cual. (Normalmente "cach" significa almacenar una respuesta).

Respuesta reutilizada

Reutiliza respuestas cacheadas para las subsiguientes peticiones.

Revalidar respuesta

Pregunta al servidor de origen si una respuesta almacenada sigue siendo reciente o no (fresh o stale). Normalmente se realiza a travs de una peticin condicionada.

Respuesta reciente

Indica que una respuesa es reciente (fresh). Esto normalmente significa que la respuesta puede ser reutilizada para las subsiguientes peticiones, dependiendo de las directivas de peticin.

Respuesta obsoleta

Indica que la respuest est obsoleta (stale). Normalmente significa que la respuesta ya no puede ser reutilizada. El almacenamiento cach no requiere que las respuestas obsoletas sean eliminadas inmediatamente, por que la revalidacin puede cambiar la respuesta de obsoleta a reciente de nuevo.

Edad

El tiempo desde que una respuesta fue generada. Es un criterio para ver si una respuesta es reciente u obsoleta (fresh o stale).

Directivas

Esta seccin lista directivas que afectan al almacenamiento cach directivas de respuestas y directivas de peticiones.

Directivas de Respuesta

max-age

La directiva de respuesta max-age=N indica que la respuesta es reciente hasta los N segundos posteriores a su generacin.

Cache-Control: max-age=604800

Indica que las cachs pueden almacenar esta respuesta y reutilizarla para las peticiones subsecuentes mientras estas son recientes.

Ten en cuenta que max-age no es el tiempo pasado desde que la respuesta fue recibida, sino el tiempo desde que la respuesta fue generada en el servidor de origen. Por tanto si otra(s) cach(s) en la ruta de red de la respuesta la almacenan por 100 segundos (indicado usando el campo de la cabecera Age en la respuesta), el navegador descontar 100 segundos del periodo de validez de la cach de respuesta.

Cache-Control: max-age=604800
Age: 100

s-maxage

La directiva de respuesta s-maxage tambin indica por cunto tiempo la respuesta es reciente (similar a max-age) pero es especfica para cachs compartidas, e ignorarn max-age cuando est presente.

Cache-Control: s-maxage=604800

no-cache

La driectiva de respuesta no-cache indica que la respuesta puede ser almacenada en cachs, pero debe ser validada con el servidor de origen antes de cada reutilizacin incluso cuando la cach est desconectada del servidor de origen.

Cache-Control: no-cache

Si quieres que las cachs siempre comprueben la actualizacin de contenido cuando resen el contenido almacenado, no-cache es la directiva a usar. Esta obliga a la cache a revalidarla con cada peticin al servidor de origen.

Ten en cuenta que no-cache no significa "no almacenar". no-cache permite almacenar una respuesta, pero les obliga a revalidarla antes de reusarla. En caso de que "no almacenar" sea lo que estabas buscando, entonces no-store es la directiva a usar.

must-revalidate

La directiva must-revalidate indica que la respuesta puede ser usada mientras sea reciente, pero que una vez el recurso se vuelve obsoleto, la cache no debe usar su copia obsoleta sin correctamente validar en el servidor de origen.

Tipicamente, must-revalidate es usada con max-age

Cache-Control: max-age=604800, must-revalidate

HTTP permite a las caches reutilizar respuesteas obsoletas cuando estn desconectados del servidor de origen. must-revalidate es una forma de prevenirlo, o la cache revalida la respuesta almacenada con el servidor de origen, o si no es posible genera una respuesta 504 (Gateway Timeout).

proxy-revalidate

proxy-revalidate es similar a must-revalidate, pero es especifico para caches compartidos.

no-store

La directiva de respuesta no-store indica que cualquier cach de cualquier tipo (privado o compartido) no debe almacenar esta respuesta.

Cache-Control: no-store

private

La directiva de respuesta private indica que la respuesta solo puede ser almacenada por cachs privadas (p. ej. cachs locales en navegadores).

Cache-Control: private

Deberas aadir la directiva private para el contenido personalizado de usuario en particular, respuestas recibidas despus del login, y sesiones administradas via cookies.

Si olvidas aadir private a una respuesta con contenido personalizado, entonces esa respuesta puede ser almacenada en una cach compartida y terminar siendo reutilizada por multiples usuarios, lo cual puede causar una fuga de informacin personal.

public

La directiva public indica que la respuesta puede ser almacenada en un cache compartido. Las respuestas para peticiones con el campo de la cabecera Authorization no debe ser almacenadas en cache compartida, pero la directiva public causar que dichas respuestas se almacenen en la cach compartida.

Cache-Control: public

En general, cuando las paginas estan bajo Basic Auth o Digest Auth, el navegador enviar peticiones con la cabecera Authorization. Esto significa que la respuesta es de acceso-controlado para usuarios restringidos (quienes tienen cuenta), y esto es no compartidamente almacenado, incluso si tiene max-age.

Puedes usar la directiva public para desbloquear esa restriccin.

Cache-Control: public, max-age=604800

Ten en cuenta que, s-maxage o must-revalidate tambin desbloquean esa restriccin.

Si una peticin no tiene la cabecera Authorization, o si ya ests usando s-maxage o must-revalidate en la respuesta, entonces no necesitas usar public.

must-understand

La directiva de respuesta must-understand indica que una cach debera de almacenar la respuesta solo si entiende los requisitos de almacenamiento basado en el codigo de estado.

must-understand debe ir emparejada con no-store, para un comportamiento como solucin alternativa.

Cache-Control: must-understand, no-store

Si una cach no soporta must-understand, ser ignorada. Si no-store est tambin presente, la respuesta no es almacenada.

Si una cach soporta must-understand, almacena la respuesta de acuerdo con los requisitos de cache basados en su cdigo de estado.

no-transform

Algunos intermediarios transforman el contenido por diversas razones. Por ejemplo, algunos convierten las imagenes para reducir el tamao de transferencia. En algunos casos, esto no es deseable para el proveedor de contenidos.

no-transform indica que cualquier intermediario (sin importar si implementa cache) no debera transformar los contenidos de la respuesta.

Nota: Web Light de Google es un intermediario de este tipo. Convirte las imagenes para minimizar los datos para almacenar en cache o para conexiones lentas, y soporta no-transform como una opcin para evitar dicha funcin.

immutable

La directiva de respuesta immutable indica que la respuesta no ser actualizada mientras sea reciente.

Cache-Control: public, max-age=604800, immutable

Una buena practica moderna para contenidos estticos es incluir versin/hashes en sus URLs, mientras nunca se modifiquen los contenidos pero en su lugar, cuando es necesario, actualizar las fuentes con nuevas versiones que tienen nuevos nmeros de versin/hashes, de forma que las URLs son diferentes. Esto es conocido como el patrn cache-busting.

<script src=https://example.com/react.0.0.0.js></script>

Cuando un usuario recarga el navegador, el navegador le mandar una peticin condicional para validar el servidor de origen. Pero no es necesario revalidar estos tipos de fuentes estticas incluso cuando un usuario recarga el navegador, porque nunca son modificados. immutable indica a una cache que una respuesta es inmutable mientras es reciente, y evita ese tipo de peticiones condicionales innecesarias al servidor.

Cuando usas un patrn de cache-busting para fuentes y les aplicas un largo max-age, puedes tambin aadir immutable para evitar la revalidacin.

stale-while-revalidate

La directiva de respuesta stale-while-revalidate indica que la cache puede reusar una respuesta antigua mientras se revalida en una cach.

Cache-Control: max-age=604800, stale-while-revalidate=86400

En el ejemplo anterior, la respuesta est actualizada durante 7 das (604800s). Despus de 7 das se vuelve obsoleto, pero la cach puede reutilizarla para cualquier solicitud que se realice al da siguiente (86400s) siempre que revalide la respuesta en segundo plano.

La revalidacin har que la memoria cach vuelva a estar actualizada, de modo que a los clientes les parezca que siempre estuvo actualizada durante ese perodo Ocultando de forma efectiva la penalizacin por latencia de la revalidacin.

Si no se produjo ninguna peticin durante ese perodo, la cach se vuelve obsoleta y la prxima solicitud se revalidar normalmente.

stale-if-error

La directiva de respuesta stale-if-error indica que la memoria cach puede reutilizar una respuesta obsoleta cuando un servidor de origen responde con un error, o el error es generado localmente. Un error es cualquier respuesta con cdigo de estado 500, 502, 503 o 504.

Cache-Control: max-age=604800, stale-if-error=86400

En el ejemplo anterior, la respuesta est actualizada durante 7 das (604800s). Despus de 7 das, se vuelve obsoleta, pero se puede usar durante 1 da adicional (86400s) si el servidor responde con un error.

Despus del perodo de tiempo de stale-if-error, la respuesta almacenada se vuelve obsoleta. Eso significa que el cliente recibir una respuesta de error tal como el servidor de origen la enva.

Directivas de Peticiones

no-cache

La directiva de peticin no-cache pide a las cachs que validen la respuesta con el servidor de origen antes de volver a usarla.

Cache-Control: no-cache

no-cache permite a los clientes solicitar la respuesta ms actualizada incluso si la cach tiene una respuesta reciente.

Los navegadores generalmente agregan no-cache a las solicitudes cuando los usuarios fuerzan la recarga de una pgina.

no-store

La directiva de peticin no-store permite a un cliente solicitar que las cachs se abstengan de almacenar la peticin y la respuesta correspondiente, incluso si la respuesta del servidor de origen pudiera almacenarse.

Cache-Control: no-store

Tenga en cuenta que los principales navegadores no admiten peticiones con no-store.

max-age

La directiva de peticin max-age=N indica que el cliente permite una respuesta almacenada que es generada en el servidor de origen dentro de N segundos, donde N puede ser cualquier nmero entero positivo (incluyendo el 0).

Cache-Control: max-age = 3600

En el caso anterior, si la respuesta con Cache-Control: max-age=604800 se almacen en las cachs hace 3 horas, la cach no podra reutilizar esa respuesta.

Muchos navegadores usan esta directiva para recargar, como se explica a continuacin.

Cache-Control: max-age=0

max-age=0 es una solucin alternativa para no-cache, porque muchas implementaciones de cach antiguas (HTTP/1.0) no son compatibles con no-cache. Los navegadores ms recientes siguen usando max-age=0 en "recargas" (por compatibilidad con versiones anteriores) y, alternativamente, usan no-cache para provocar una "recarga forzada".

Si el valor de max-age no es positivo (por ejemplo, -1) o no es entero (por ejemplo, 3599.99), el comportamiento del cache es indefinido. Sin embargo, la seccin Calculating Freshness Lifetime de las especificaciones HTTP establece:

Caches are encouraged to consider responses that have invalid freshness information to be stale.

Traduccin: Se recomienda a las caches considerar una respuesta como antigua si la informacin de edad es invlida.

En otras palabras, para cualquier valor de max-age que no es un entero positivo, el comportamiento de cache recomendado es de tratar el valor como si fuera 0.

max-stale

La directiva de solicitud max-stale=N indica que el cliente permite una respuesta almacenada que est obsoleta hasta N segundos.

Cache-Control: max-stale=3600

En el ejemplo anterior, si la respuesta con Cache-Control: max-age=604800 se almacen en cach hace 3 horas, la cach no podra reutilizar esa respuesta.

Los clientes pueden usar este encabezado cuando el servidor de origen est inactivo o es demasiado lento y pueden aceptar respuestas almacenadas en cach incluso si son un poco antiguas.

Tenga en cuenta que los principales navegadores no admiten solicitudes con max-stale.

min-fresh

La directiva de peticin min-fresh=N indica que el cliente permite una respuesta almacenada que est actualizada durante al menos N segundos.

Cache-Control: min-fresh=600

En el caso anterior, si la respuesta con Cache-Control: max-age=3600 se almacen en las cachs hace 51 minutos, la cach no podra reutilizar esa respuesta.

Los clientes pueden usar este encabezado cuando el usuario requiere que la respuesta no solo sea actualizada, sino que tambin requiere que no se actualice durante un perodo de tiempo.

Tenga en cuenta que los principales navegadores no admiten peticiones con min-fresh.

no-transform

El mismo significado que no-transform tiene para una respuesta, pero para una peticin en su lugar.

only-if-cached

El cliente indica que la cach debe obtener una respuesta ya almacenada en cach. Si una cach ha almacenado una respuesta, se reutiliza.

Casos de uso

Prevencin del almacenamiento

Si no desea que una respuesta se almacene en las cachs, use la directiva no-store.

Cache-Control: no-store

Tenga en cuenta que no-cache significa "se puede almacenar pero no reutilizar antes de validar" por lo que no es para evitar que se almacene una respuesta.

Cache-Control: no-cache

En teora, si las directivas estn en conflicto, se debe respetar la directiva ms restrictiva. As que el siguiente ejemplo bsicamente no tiene sentido, porque private, no-cache, max-age=0 y must-revalidate entran en conflicto con no-store.

# conflicto
Cache-Control: private, no-cache, no-store, max-age=0, must-revalidate

# equivalete a
Cache-Control: no-store

Almacenamiento en cach de activos estticos con "cache busting"

Cuando crea activos estticos con mecanismos de control de versiones/hashing, agregar una versin/hash al nombre de archivo o cadena de consulta es una buena manera de administrar el almacenamiento en cach.

Por ejemplo:

<!-- index.html -->
<script src="/activos/react.min.js"></script>
<img src="/assets/hero.png" width="900" height="400" />

La versin de la biblioteca de React cambiar cuando actualices la biblioteca, y hero.png tambin cambiar cuando edites la imagen. Por lo tanto, son difciles de almacenar en un cach con max-age.

En tal caso, podra abordar las necesidades de almacenamiento en cach utilizando una versin numerada especfica de la biblioteca e incluyendo el hash de la imagen en su URL.

<!-- index.html -->
<script src="/assets/react.0.0.0min.js"></script>
<img src="/assets/hero.png?hash=deadbeef" width="900" height="400" />

Puede agregar un valor grande de max-age e immutable, porque el contenido nunca cambiar.

# /assets/*
Cache-Control: max-age=31536000, immutable

Cuando actualiza la biblioteca o edita la imagen, el nuevo contenido debe tener una nueva URL y los cachs no se reutilizan. Eso se llama el patrn "cache busting".

Utilice no-cache para asegurarse de que la respuesta HTML en s misma no se almacene en cach. no-cache puede causar la revalidacin y el cliente recibir correctamente una nueva versin de la respuesta HTML y los activos estticos.

# /index.html
Cache-Control: no-cache

Nota: si index.html se accede mediante Basic Authentication o Digest Authentication, los archivos bajo /assets no se almacenarn en la memoria cach compartida. Si los archivos /assets/ son adecuados para almacenar en un cach compartido, tambin necesita uno de public, s-maxage o must-revalidate.

Contenidos siempre actualizados

Para los contenidos que se generan dinmicamente, o que son estticos pero se actualizan con frecuencia, deseas que un usuario reciba siempre la versin ms actualizada.

Si no agrega un encabezado Cache-Control porque la respuesta no est destinada para almacenarse en cach, podra causar un resultado inesperado. El almacenamiento en cach puede almacenarlo heursticamente por lo que si tienes algn requisito para el almacenamiento en cach, siempre debes indicarlo explcitamente en el encabezado Cache-Control.

Agregar no-cache a la respuesta provoca la revalidacin en el servidor, por lo que puede entregar una respuesta nueva cada vez o si el cliente ya tiene una nueva, simplemente responda 304 Not Modified.

Cache-Control: no-cache

La mayora de las cachs HTTP/1.0 no son compatibles con las directivas no-cache, por lo que histricamente se usaba max-age=0 como solucin alternativa. Pero usar solo max-age=0 podra hacer que se reutilice una respuesta obsoleta cuando los cachs se desconecten del servidor de origen. must-revalidate aborda eso. Es por eso que el siguiente ejemplo es equivalente a no-cache.

Cache-Control: max-age=0, must-revalidate

Pero hoy en da, puedes simplemente usar no-cache en su lugar.

Borrar un cach ya almacenado

Desafortunadamente, no hay directivas de cach para borrar las respuestas ya almacenadas de las cachs.

Imagine que los clientes/cachs almacenan una respuesta nueva para una ruta, sin solicitud de vuelo al servidor. No hay nada que un servidor pueda hacer en esa ruta.

Alternativamente, Clear-Site-Data puede borrar la memoria cach del navegador para un sitio. Pero tenga cuidado: eso borra todas las respuestas almacenadas para un sitio y solo en los navegadores, no para un cach compartido.

Especificaciones

Compatibilidad en navegadores

Vase tambin

• Cach en HTTP
• Tutorial de almacenamiento en cach para autores web y webmasters
• Prcticas recomendadas de almacenamiento en cach y trucos de edad mxima
• Control de cach para civiles
• RFC 9111 Cach en HTTP
• RFC 5861 Extensiones de control de cach HTTP para contenido obsoleto
• RFC 8246 Respuestas HTTP inmutables