Upstash Redis — Schema & Conventions

SSOT do uso de Upstash Redis no ecossistema OLP. Última atualização: 2026-05-13.

Princípios (não-negociáveis)

1. Owner único = Worker Cloudflare. Edge Functions Supabase NÃO conectam direto. Comunicam via HTTP autenticado com o Worker.
2. Sempre TTL em writes. Nenhuma chave eterna. Caller que esquece TTL = bug.
3. Proibido KEYS/SCAN em produção. Se precisa enumerar, mantém índice próprio.
4. Fail-open. Toda operação Redis tem fallback (in-memory ou no-op). Incidente Upstash NUNCA bloqueia OTP/cobrança.
5. Sem PII. Apenas session_key opaco, IDs hash, contadores. Nunca CPF/telefone/email/JID.
6. Prefixo por environment. olp: (prod), olp-stg: (staging), olp-dev: (local). Mesma DB Upstash; isolamento por namespace.
7. Constant-time auth entre Worker e clientes (shared secret HMAC-style).

Alinhado com mem://infrastructure/upstash-redis-standard e docs/architecture/WORKER_V3_REDIS_PLAN.md.

Workers consumidores

Worker	Status	Namespace	Doc
olp-msgqueue	produção (Etapa 2)	wa:*	workers/olp-msgqueue/README.md
olp-gateway v3	planejado	rl:*, m:*, bl:*	WORKER_V3_REDIS_PLAN.md

Schema reservado por namespace

wa:* — Wasender messaging queue (olp-msgqueue)

Chave	Tipo	TTL	Conteúdo
{prefix}wa:bucket:{session_key}	string (timestamp ms)	60s	Último envio da sessão Wasender
{prefix}wa:metrics:{session_key}:{YYYYMMDDHHmm}	hash	300s	Counters: wasender:ok, wasender:rate_limited, wasender:failure, twilio:*

Acesso atômico ao bucket via Lua:

local last = tonumber(redis.call('GET', KEYS[1])) or 0
local now = tonumber(ARGV[1])
local interval = tonumber(ARGV[2])
local elapsed = now - last
if elapsed >= interval then
  redis.call('SET', KEYS[1], now, 'EX', 60)
  return 0
else
  return interval - elapsed
end

rl:*, m:*, bl:* — reservados para Worker v3

Ver docs/architecture/WORKER_V3_REDIS_PLAN.md (telemetria, rate-limit, blocklist).

Adicionar novo namespace

1. Reservar prefixo no Worker dono — não compartilhar entre Workers diferentes.
2. Documentar nesta página: chave, tipo, TTL, conteúdo.
3. Atualizar mem://infrastructure/upstash-redis-standard.
4. Garantir TTL e fail-open no código.

Operação

• Conta única: uma DB Upstash compartilhada por todos os Workers (custos otimizados).
• Plano: Free (10k req/dia) — folga >10× para uso atual.
• Rotação de tokens: trocar UPSTASH_REDIS_REST_TOKEN no Upstash dashboard → atualizar secret nos Workers via wrangler secret put.
• Health: GET /health em cada Worker dono retorna redis: up|down.
• Telemetria: janelas curtas no próprio Redis (5min); agregação histórica vai pra dashboards externos (futuro).