Cache, zonas e purge

O deploy lida com duas camadas de cache que precisam ser invalidadas após cada publicação: o platform cache (CF Cache API + snapshot KV, gerido pelo app) e o SSR cache da edge (purge de zona Cloudflare). Este doc cobre como a política de cache é resolvida e como cf_zone controla o purge.

Camadas de cache

Camada	O que é	Como é invalidada no deploy
Platform cache	Cache API + snapshot KV por recurso (homeRows, allGames, etc.), gerido pelo @cactus-agents/platform-cache	POST <worker>/api/cache/purge?segments=... (step "Purge platform cache")
SSR cache (edge)	Respostas SSR cacheadas na edge da CF	POST /zones/{id}/purge_cache (step "Purge SSR cache")

Política de cache — precedência

A política é montada por merge, do mais geral para o mais específico:

config/cache/defaults.yml
  < config/brands/<brand>/cache.yml          (override de brand, opcional)
    < config/brands/<brand>/environments/<env>/cache.yml   (override de env, opcional)

• defaults.yml define todos os recursos (TTL, SWR, stale-if-error, storage, snapshot KV). É a base de todas as brands.
• cache.yml da brand/env sobrescreve campos pontuais (deep-merge por recurso). Hoje web-base/cache.yml não tem overrides (usa os defaults).

:::caution Sanity checks do merge O pipeline falha o deploy se a política resolvida ficar null/vazia, ou se algum recurso declarado em defaults.yml sumir após o merge. Isso evita subir um Worker em modo BYPASS silencioso ou sem um segmento. :::

KV provisioning

Se algum recurso usa storage.snapshot: kv, o pipeline provisiona o namespace KV ({worker_name}-cache por default) e injeta o binding PLATFORM_CACHE_KV no wrangler.toml. Idempotente — reutiliza o namespace se já existir.

Purge pós-deploy (platform cache)

Os segmentos purgados após o deploy vêm de postDeployPurge.segments (defaults → brand → env, com replace total quando a brand/env define a chave).

Default atual (config/cache/defaults.yml):

postDeployPurge:
  segments:
    - homeRows
    - casinoRows
    - casinoLiveRows
    - gamesBase
    - topWins
    - lastWins
    - topGames
    - brandConfig
    - paymentProviders

O purge com ?segments=... apaga tanto o tier primário quanto o snapshot KV de cada segmento. Além disso, o endpoint /api/cache/purge do Worker dispara um purge em cascata no front-service-api (proxy), filtrado por originDomain.

:::info Desabilitar purge Setar postDeployPurge.segments: [] pula o purge por segmentos (cai no purgeAll() bare) — não recomendado, pois também pula a cascata no proxy. :::

SSR cache — cf_zone

O purge SSR chama POST /zones/{id}/purge_cache. Para achar {id} o workflow consulta GET /zones?name=<zone> — que é strict-match (não faz fallback de sufixo).

• origin_domain/worker_url apex (marca.com, 7k.bet.br) resolvem naturalmente.
• origin_domain/worker_url subdomínio (cl.bet7k.com, stage-x.cactusgaming.tech) não resolvem por nome — a zona é o apex. Declare cf_zone explícito.

Quando declarar cf_zone explicitamente

Sempre que o domínio servido for subdomínio de uma zona diferente, ou quando o origin_domain aponta para um backend que não é a zona CF onde o Worker é servido.

origin_domain / worker_url	cf_zone	Motivo
cl.bet7k.com	bet7k.com	zona apex
pt.state77.com	state77.com	zona apex
fi.7k.bet	7k.bet	zona apex
stage-7k-bet-br.cactusgaming.tech	cactusgaming.tech	zona apex do staging
stage1.gli-cactus.com	c4ctus.com	origin é BFF backend; worker vive em outra zona

Fallback quando cf_zone é ausente

O workflow deriva a zona de origin_domain usando uma shortlist de TLDs compostos: bet.br, com.br, com.ar, com.mx, com.co, com.pe, co.uk, co.id, co.ve. Domínios terminando num desses mantêm os últimos 3 labels; os demais, os últimos 2.

Cobre apex e derivações simples subdomínio→apex. Fora disso (cross-zone, TLDs fora da shortlist, hostnames atípicos), declare cf_zone.

Requisitos do token CF para o purge

O FRONT_{XX}_CF_API_TOKEN precisa de:

• Zone > Zone > Read — para resolver o Zone ID
• Zone > Cache Purge > Purge — para o purge SSR
• Zone Resources incluindo cada cf_zone usado na conta

Falta de qualquer um → HTTP 401/403 no purge (warning, deploy ainda "verde", mas cache stale). Ver debug em Adicionar conta CF.

Dev local

Em dev local a política de cache fica ausente por padrão → o engine entra em bypass (chama as APIs direto), ideal para desenvolvimento. Para testar caching, descomente PLATFORM_CACHE_POLICY_JSON no .dev.vars/.env. Para sincronizar a política local com o front-ops:

pnpm check:dev-vars --write   # sync-dev-vars-cache-policy.mjs