Como Colocar em Cache Imagens OG

Colocar em cache imagens OG significa servir uma pré-visualização social previamente gerada a partir de uma CDN, em vez de a voltar a renderizar em cada partilha. A FastOG coloca em cache imagens idênticas no edge durante um ano — o mesmo URL devolve o PNG em cache sem contar para a sua quota e com latência praticamente nula, pelo que a maior parte do tráfego OG de um site nunca chega ao renderizador.

Porque é que a cache é importante

Uma partilha social desencadeia uma busca por parte do crawler da plataforma. Se cada partilha fosse re-renderizada, gastaria quota e latência em conteúdo idêntico. Uma cache agressiva — com chave baseada no conteúdo da imagem — transforma "cada partilha conta 1 renderização" em "a primeira partilha conta 1 renderização, todas as outras são gratuitas."

O modelo baseado no conteúdo que o torna funcional

O FastOG usa URLs assinadas por conteúdo: o URL é uma função pura dos parâmetros. Título idêntico + modelo idêntico → URL idêntico. Isso significa que:

O edge do FastOG mantém a imagem sob o URL.
O mesmo conteúdo partilhado 10.000 vezes → uma renderização, uma contagem de quota, 9.999 acertos de cache.
Altere o conteúdo → URL diferente → uma nova renderização.

GET /api/v1/og?title=Hello&template=default&key=...&s=...   → render (1 quota count), then
GET /api/v1/og?title=Hello&template=default&key=...&s=...   → cached (0 counts, instant)
GET /api/v1/og?title=Changed&template=default&key=...&s=... → render (1 quota count)

Cabeçalhos de cache do FastOG

O FastOG devolve Cache-Control: public, max-age=31536000, immutable (um ano) para imagens renderizadas. Uma capa é servida a partir da edge do FastOG em dois níveis: a cache de renderização à frente de fastog.com, e um armazenamento de objetos durável por trás dela. Pedidos repetidos são respondidos sem re-renderização, e X-FastOG-Worker-Cache na resposta indica qual nível respondeu (HIT, R2, MISS).

Como a cópia durável não depende do renderizador, as capas que foram obtidas pelo menos uma vez continuam a ser servidas enquanto o serviço de renderização do FastOG estiver brevemente indisponível — uma falha não apaga uma pré-visualização que já foi gerada. Uma capa que nunca foi renderizada antes é o único caso que precisa do renderizador, e nesse caso o FastOG responde com uma imagem em vez de um erro:

Situação	O que um crawler obtém
Capa já renderizada	a capa, a partir da edge ou do armazenamento durável
Nunca renderizada, serviço de renderização ativo	a capa, renderizada a pedido
Nunca renderizada, serviço de renderização brevemente indisponível	a imagem própria da página transportada no URL (a sua foto de produto), ou um cartão neutro — nunca uma página de erro

Se o próprio pedido for inválido (uma assinatura adulterada, um title em falta), recebe ainda o 4xx correspondente.

Alterar uma imagem que já publicou

O que alterou	O que fazer
O conteúdo (título, preço, foto)	nada: o conteúdo está no URL, pelo que o novo conteúdo é um novo URL e é renderizado de raiz
O modelo ou uma predefinição de renderização	aumente a versão de cache-bust (`FASTOG_CACHE_BUST`) para que cada URL ganhe um novo parâmetro `v`
Precisa que o mesmo URL seja re-renderizado	contacte o suporte para purgar esse URL específico — a purga por URL exato não está exposta como endpoint público

Os links que já foram partilhados continuam a funcionar e continuam a mostrar a imagem que prometiam, a menos que purge esse URL exato.

Colocar em cache a sua própria og:image (self-hosting)

Se armazenar as imagens por si em vez de utilizar a cache da FastOG, aplique as mesmas regras:

Passo	Detalhe
Chave de cache = hash do conteúdo	Armazene por um hash dos dados, não por um nome de ficheiro mutável
TTL longo	`max-age=31536000, immutable` para conteúdo estável
URLs com versão	Acrescente um hash/versão quando o conteúdo mudar
CDN à frente	Deixe a CDN absorver os pedidos repetidos

FAQ

As partilhas repetidas custam mesmo 0 renders?

Sim. URLs idênticas atingem a cache de borda (edge cache) e nunca chegam ao renderizador — não é consumida qualquer quota.

Durante quanto tempo o FastOG armazena uma imagem em cache?

Um ano (immutable). Muito depois do primeiro render, um cartão partilhado é servido a partir da cache.

E se eu quiser que uma imagem seja atualizada (ex.: preço em tempo real)?

Altere um parâmetro (o preço) → novo URL → novo render. Conteúdo estável permanece em cache; conteúdo dinâmico é atualizado quando quiser.