Purgado e invalidación: expirar, purgar o versionar

Queda el problema difícil, el que la tradición del oficio coloca junto a nombrar cosas en la lista de las dos cosas verdaderamente duras de la informática: decidir cuándo lo que guardaste deja de ser válido. No es difícil por falta de herramientas —Cloudflare ofrece expiración por tiempo, purgado por URL, purgado por etiqueta y borrado programático— sino porque cada herramienta compra inmediatez a cambio de coordinación, y la coordinación en un sistema con cientos de cachés independientes es cara y frágil. Esta lección recorre las tres estrategias reales, señala exactamente dónde falla cada una, y termina en la que los sistemas maduros acaban prefiriendo casi siempre: no invalidar nada, y en su lugar cambiar la pregunta.

Expirar: la invalidación que no cuesta nada

El TTL es la invalidación por omisión y también la más barata: no requiere ninguna acción, ninguna llamada a una API, ninguna coordinación entre nodos. Cada entrada lleva escrito su propio vencimiento en las cabeceras con las que se guardó, y cada centro de datos lo aplica localmente sin hablar con nadie. Su virtud es la ausencia total de partes móviles; su límite es evidente: no puedes invalidar antes de tiempo, así que el TTL define exactamente cuánto tiempo estás dispuesto a servir algo viejo en el peor caso.

De ahí que elegir un TTL sea en realidad responder a una pregunta de producto, no de infraestructura. ¿Cuánto puede tardar un cambio de precio en verse? ¿Y una corrección de un texto legal? ¿Y una publicación nueva en el listado? Si la respuesta es «minutos», el TTL basta y no necesitas nada más de esta lección. Si es «al instante», entras en el territorio de las dos secciones siguientes.

Merece la pena escribir esa política en la propia respuesta, con las tres cifras separadas, porque cada una habla a un consumidor distinto y mezclarlas es la causa habitual de los diagnósticos imposibles.

respuesta.headers.set(
  "cache-control",
  "public, max-age=0, s-maxage=300, stale-while-revalidate=600",
);

Traducido: el navegador no guarda nada por su cuenta, el edge sirve la copia durante cinco minutos, y durante diez minutos más puede seguir sirviéndola caducada mientras la refresca por detrás. La ventana efectiva de obsolescencia en el peor caso es la suma, quince minutos, y ese número debería aparecer en la conversación de producto tal cual, sin envolverlo en jerga.

Purgar: el botón y sus filos

Cuando la inmediatez es obligatoria, hay que purgar. El purgado total vacía la cache de la zona entera y es la opción más tentadora y más peligrosa: funciona siempre, y por eso se usa para todo, pero deja tu origen desnudo frente a la totalidad del tráfico durante los segundos o minutos que tarda la red en recalentarse. En un sitio con carga real, un purgado total en hora punta puede provocar exactamente la caída que la cache existía para evitar.

El purgado por URL es la herramienta quirúrgica: invalida entradas concretas en toda la red. Su trampa es que la URL que envías debe coincidir con la clave de cache, cadena de consulta incluida; si tus entradas están fragmentadas por parámetros de campaña, purgar la URL limpia solo purga una de las muchas variantes. Es la factura tardía de no haber normalizado la clave, y explica por qué la lección anterior venía antes que esta.

El purgado por etiqueta invierte la relación. En lugar de enumerar URL, marcas cada respuesta con una cabecera Cache-Tag que declara a qué entidades pertenece, y luego purgas por esas etiquetas. Una página de producto puede llevar la etiqueta del producto, la de su categoría y la de la plantilla que la renderiza; cuando el precio cambia, purgas la etiqueta del producto y desaparecen todas las páginas afectadas sin que nadie haya tenido que llevar una lista.

const respuesta = new Response(html, {
  headers: {
    "content-type": "text/html; charset=utf-8",
    "cache-control": "public, s-maxage=86400",
    "cache-tag": "producto-8412,categoria-teclados,plantilla-ficha",
  },
});

cache.delete no es un purgado

Dentro de un Worker existe cache.delete(clave), y su nombre invita a un malentendido serio. Borra la entrada, sí, pero solo en la cache del centro de datos donde ese Worker se está ejecutando. Los otros trescientos siguen sirviendo su copia como si nada. No es una operación global y no puede serlo: la red no propaga borrados entre nodos por iniciativa de tu código.

Eso lo convierte en una herramienta útil para casos locales —descartar una entrada que acabas de detectar como corrupta, o limpiar tras un experimento— e inútil como mecanismo de invalidación de producto. Para lo segundo, lo correcto es llamar a la API de purgado de Cloudflare, que sí coordina la red entera.

await fetch(`https://api.cloudflare.com/client/v4/zones/${env.ZONE_ID}/purge_cache`, {
  method: "POST",
  headers: {
    authorization: `Bearer ${env.CF_API_TOKEN}`,
    "content-type": "application/json",
  },
  body: JSON.stringify({ tags: ["producto-8412"] }),
});

Esa llamada tiene tres implicaciones que suelen descubrirse tarde. Necesita un token con permisos de purgado, y ese token es un secreto de zona que no debe vivir en el mismo Worker que sirve tráfico público sin más cuidado. Está sujeta a límites de frecuencia, así que un bucle que purgue una etiqueta por cada fila modificada en una importación masiva chocará contra ellos; lo correcto es agrupar. Y no es instantánea: se propaga en segundos por toda la red, tiempo durante el cual convivirán las dos versiones. Un purgado no es una transacción.

Conviene recordar aquí el detalle de la primera lección: lo que guardaste en una cache abierta con caches.open queda además fuera del alcance de ese purgado, así que en un espacio con nombre tus únicas armas son el TTL y la versión.

flowchart TD
N[Necesito dejar de servir algo viejo] --> Q[Tolero minutos de retraso]
Q -->|si| T[TTL y stale-while-revalidate]
Q -->|no| C[Controlo la clave]
C -->|si| V[Clave versionada por hash]
C -->|no| P[Purgado por etiqueta o por URL]
P --> R[Cuidado con el purgado total]
style V fill:#a6e3a1,color:#11111b
style R fill:#f38ba8,color:#11111b

La clave versionada: invalidar sin invalidar

Queda la estrategia que los sistemas maduros terminan adoptando, y su elegancia consiste en negarse a resolver el problema. Si la clave de cache incluye un identificador de versión —el hash del contenido, el identificador del despliegue, la marca de la última escritura en la base de datos—, entonces publicar algo nuevo genera claves nuevas. Las viejas no se invalidan: simplemente dejan de consultarse y se apagan solas cuando expiran. La invalidación deja de ser una operación distribuida y se convierte en un cambio de nombre.

const version = env.DEPLOY_ID; // o el hash del contenido, o una marca de tiempo
const clave = new Request(`https://cache.interno/v/${version}/articulos`, request);

const acierto = await cache.match(clave);
if (acierto) return acierto;

El coste está a la vista y hay que aceptarlo sin autoengaño: cada versión nueva empieza con la cache fría, y si versionas con demasiada granularidad pagas un camino frío permanente. Por eso el patrón brilla cuando la versión cambia con poca frecuencia y afecta a mucho contenido —un despliegue, un cambio de plantilla, una migración de esquema— y encaja mal cuando lo que cambia es un dato concreto entre millones; ahí la etiqueta es la herramienta adecuada.

La granularidad del identificador de versión es, por tanto, la única decisión de diseño que hay aquí, y se resuelve preguntando qué conjunto de entradas debe caer junto. Un identificador de despliegue invalida absolutamente todo con cada publicación, lo cual es correcto para fragmentos de plantilla y desastroso para agregaciones costosas que no dependen del código. Una marca de la última escritura en una tabla invalida solo lo derivado de esa tabla y sobrevive a los despliegues. Un hash del contenido invalida exactamente lo que cambió y nada más, al precio de tener que calcularlo antes de construir la clave.

const sello = await env.KV.get("version:catalogo"); // se actualiza al escribir
const clave = new Request(`https://cache.interno/${sello}/catalogo`, request);

Ese patrón —un sello barato de leer que se actualiza cuando cambian los datos y que forma parte de la clave— es la versión práctica de la idea, y encaja especialmente bien en el edge porque la lectura del sello es rapidísima y la invalidación consiste en una sola escritura, sin coordinación con la red de cachés.

La combinación habitual de un sistema serio usa las tres estrategias a la vez, cada una en su capa: TTL como suelo que garantiza que nada vive eternamente, etiquetas para los cambios de datos que deben verse ya, y versión en la clave para los cambios de forma que afectan a todo. No compiten entre sí; cubren regímenes distintos del mismo problema.