Postream

Cargando el índice…

Documentación: Caché y ETag

Caché y ETag

La ruta por sitio queda en el borde de Cloudflare y se purga cuando el post cambia; toda respuesta tiene ETag.

Toda respuesta 200 o 301 trae un ETag fuerte. Envíalo en If-None-Match y la API responde 304 Not Modified, sin cuerpo, cuando nada cambió:

curl -i -H "Authorization: Bearer $POSTREAM_API_KEY" \
  -H 'If-None-Match: "3f1c…"' \
  "https://api.postream.blog/public/v1/sites/$POSTREAM_SITE_ID/posts/como-gestionar-varios-blogs"

Ruta por sitio: caché en el borde

En la ruta /public/v1/sites/{siteId}/… el contenido es lo que ya está publicado, igual para todas las claves, así que Cloudflare guarda la respuesta:

RespuestaCache-Control
Post (y 301 de slug antiguo)public, max-age=60, s-maxage=86400, stale-while-revalidate=604800, stale-if-error=86400
Listados, autores, pilares, site y sitemappublic, max-age=60, s-maxage=300, stale-while-revalidate=604800, stale-if-error=86400
Error (4xx, 5xx)no-store
  • Solo Vary: Accept-Encoding. Por eso esta ruta no tiene CORS ni encabezados RateLimit-* (solo Retry-After en el 429).
  • La clave solo se verifica cuando la solicitud llega a Postream (fallo de caché). Una copia en caché se sirve a quien pida la misma URL: el contenido es lo que ya está publicado en el blog.

Purga cuando el post cambia

Cuando un post se publica, se despublica, se edita después de publicado o se elimina, Postream le pide a Cloudflare la purga de las URLs afectadas: el post con y sin ?locale=, en todos los idiomas, la primera página de los listados en los que aparece (todos, por idioma, por tag, por idioma y tag) y el sitemap. La purga sale en segundo plano, con reintentos, y nunca retrasa la publicación.

La purga es por URL exacta, con la query string. Para aprovecharla, llama a las URLs en la forma canónica:

  • ?locale= antes de &tag=;
  • valores con encodeURIComponent;
  • sin page=1.

Las otras páginas, otro perPage, autores, pilares y site se quedan con los 5 minutos de borde. El kit de SEO ya arma las URLs así.

Ruta por clave

En /public/v1/posts… la misma dirección responde sitios distintos según la clave, así que la respuesta viene con Cache-Control: private, no-cache y Vary: Origin, Authorization: solo el blog y el navegador guardan, siempre revalidando con el ETag. no-cache no prohíbe guardar: dice que la copia debe revalidarse antes de cada uso.

Del lado del blog

Hay tres capas, cada una con su tiempo:

  1. Borde de Cloudflare (Postream): la purga el propio Postream cuando el post cambia.
  2. Caché de Next.js en el blog: next: { revalidate: 300 } vuelve a buscar como máximo cada 5 minutos; como el borde ya se purgó, la búsqueda siguiente trae el post nuevo.
  3. Navegador del visitante: max-age=60 solo vale para llamadas hechas directo desde el navegador.
await fetch(`${process.env.POSTREAM_API_URL}/sites/${process.env.POSTREAM_SITE_ID}/posts?locale=es`, {
  headers: { Authorization: `Bearer ${process.env.POSTREAM_API_KEY}` },
  next: { revalidate: 300, tags: ["postream"] },
});

Para que un post aparezca en el blog justo después de publicarse, sin esperar el intervalo, usa los webhooks: llaman al blog al instante, y el blog ejecuta revalidatePath o revalidateTag.