Postream

Carregando o índice…

Documentação: Cache e ETag

Cache e ETag

A rota por site fica na borda do Cloudflare e é purgada quando o post muda; toda resposta tem ETag.

Toda resposta 200 ou 301 traz um ETag forte. Mande-o em If-None-Match e a API responde 304 Not Modified, sem corpo, quando nada mudou:

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-gerir-varios-blogs"

Rota por site: cache na borda

Na rota /public/v1/sites/{siteId}/… o conteúdo é o que já está publicado, igual para todas as chaves, então o Cloudflare guarda a resposta:

RespostaCache-Control
Post (e 301 de slug antigo)public, max-age=60, s-maxage=86400, stale-while-revalidate=604800, stale-if-error=86400
Listagens, autores, pilares, site e sitemappublic, max-age=60, s-maxage=300, stale-while-revalidate=604800, stale-if-error=86400
Erro (4xx, 5xx)no-store
  • Vary: Accept-Encoding só. Por isso essa rota não tem CORS nem cabeçalhos RateLimit-* (só Retry-After no 429).
  • A chave só é conferida quando a requisição chega ao Postream (falta no cache). Uma cópia em cache é servida a quem pedir a mesma URL: o conteúdo é o que já está no ar no blog.

Purge quando o post muda

Quando um post é publicado, despublicado, editado depois de publicado ou excluído, o Postream pede ao Cloudflare o purge das URLs afetadas: o post com e sem ?locale=, em todos os idiomas, a primeira página das listagens em que ele aparece (todas, por idioma, por tag, por idioma e tag) e o sitemap. O purge sai em segundo plano, com novas tentativas, e nunca atrasa a publicação.

O purge é por URL exata, com a query string. Para aproveitá-lo, chame as URLs na forma canônica:

  • ?locale= antes de &tag=;
  • valores com encodeURIComponent;
  • sem page=1.

Outras páginas, outro perPage, autores, pilares e site ficam com os 5 minutos de borda. O kit de SEO já monta as URLs assim.

Rota pela chave

Em /public/v1/posts… o mesmo endereço responde sites diferentes conforme a chave, então a resposta vem com Cache-Control: private, no-cache e Vary: Origin, Authorization: só o blog e o navegador guardam, sempre revalidando com o ETag. no-cache não proíbe guardar: diz que a cópia deve ser revalidada antes de cada uso.

Do lado do blog

Há três camadas, cada uma com o seu tempo:

  1. Borda do Cloudflare (Postream): purgada pelo próprio Postream quando o post muda.
  2. Cache do Next.js no blog: next: { revalidate: 300 } busca de novo no máximo a cada 5 minutos; como a borda já foi purgada, a busca seguinte traz o post novo.
  3. Navegador do visitante: max-age=60 só vale para chamadas feitas direto do navegador.
await fetch(`${process.env.POSTREAM_API_URL}/sites/${process.env.POSTREAM_SITE_ID}/posts?locale=pt-BR`, {
  headers: { Authorization: `Bearer ${process.env.POSTREAM_API_KEY}` },
  next: { revalidate: 300, tags: ["postream"] },
});

Para o post aparecer no blog logo depois de publicado, sem esperar o intervalo, use os webhooks: eles chamam o blog na hora, e o blog roda revalidatePath ou revalidateTag.