Plano de Migração: Upstash Redis via Cloudflare Worker

Status: Em implementação — Fase 0 pendente
Última revisão: 2026-04-19
Pré-requisito: Conta Upstash + database provisionado
Documentos relacionados: WORKER_V3_REDIS_PLAN · WORKER_TELEMETRY · RATE_LIMITS

---

0. Estratégia de rollout (produção vs staging)

A migração para Worker v3 + Redis acontece em duas frentes simultâneas, com regras de bloqueio diferentes em cada ambiente:

Ambiente	Modo de operação	Janela	Objetivo
Produção (olp.digital)	Observação total — telemetria ativa, zero bloqueio novo	~4 semanas contínuas	Coletar baseline real de tráfego por endpoint, escola, usuário
Staging (staging.olp.digital)	Bloqueio real ativo desde a Fase 1 + scripts de stress test	Imediato	Validar funcionamento do código, headers RFC 6585, mensagens PT-BR e os limites propostos

Após as ~4 semanas de coleta em produção, o código que está rodando em staging (já validado) é promovido para produção, substituindo os limites provisórios pelos calibrados pelos dados reais. A calibração pode (e provavelmente vai) alterar valores, mas não a estrutura do código.

Prefixo de chave Redis isola os dois ambientes no mesmo database Upstash: olp: em produção, olp-stg: em staging.

---

0.1 Rate limits por grupo

Tabela completa dos parâmetros aprovados. Coluna Modo (prod) indica como o Worker se comporta em produção durante a Fase 3a (observação) e Fase 3b (bloqueio real). Coluna Modo (staging) é o comportamento no ambiente de testes desde a Fase 1.

Grupo A — Auth crítico

Endpoint	Limite	Escopo	Modo (prod)	Modo (staging)
send-otp	5/15min	usuario_id	Observação → Bloqueio	Bloqueio
send-otp	20/hora	ip	Observação → Bloqueio	Bloqueio
verify-otp / verify-password	10/15min	ip + lockout progressivo	Observação → Bloqueio	Bloqueio
set-password / change-password / reset-password	10/hora	usuario_id	Observação → Bloqueio	Bloqueio

Grupo B — Leitura autenticada (apenas observação até calibração)

Endpoint	Limite	Escopo	Modo (prod)	Modo (staging)
/me	sem bloqueio	usuario_id	Apenas alerta (ver WORKER_TELEMETRY.md §8)	Apenas alerta
*-dashboard	120/min	usuario_id	Observação (não bloquear até calibrar)	Bloqueio
gestao-* GET, listagens	300/min	usuario_id	Observação	Bloqueio
eventos-calendario, escola-dados GET	180/min	usuario_id	Observação	Bloqueio
mural-escola GET	120/min	ip	Observação	Bloqueio

Grupo C — Escrita autenticada

Endpoint	Limite	Escopo	Modo (prod)	Modo (staging)
CRUD geral (tarefas, eventos, anotações, perfil)	60/min	usuario_id	Observação → Bloqueio	Bloqueio
controle.batch_update, importação	10/min	usuario_id	Observação → Bloqueio	Bloqueio
comunicacao-escola (broadcast)	5/min + 50/hora	escola_id	Observação → Bloqueio	Bloqueio
mural-escola POST	30/min	usuario_id	Observação → Bloqueio	Bloqueio
mural-escola POST	60/min	escola_id	Observação → Bloqueio	Bloqueio

Grupo D — Mural/Portal (já em produção v4, manter)

Endpoint	Limite	Escopo	Modo (prod)	Modo (staging)
Burst	150/5s	ip	Bloqueio (já ativo)	Bloqueio
lookup_escola	100/min	ip	Bloqueio (já ativo)	Bloqueio
lookup_escola	200/min	escola_id	Bloqueio (já ativo)	Bloqueio
login_aluno_a	400/5min	ip	Bloqueio (já ativo)	Bloqueio
login_aluno_a	200/min	escola_id	Bloqueio (já ativo)	Bloqueio
send_otp_*	50/15min	ip	Bloqueio (já ativo)	Bloqueio
send_otp_*	100/15min	escola_id	Bloqueio (já ativo)	Bloqueio
cadastro_responsavel	30/30min	ip	Bloqueio (já ativo)	Bloqueio
auto_vincular_matricula	30/60min	ip + lockout 5/8/12 falhas	Bloqueio (já ativo)	Bloqueio

Grupo E — Cron / Webhook

ISENTO — autenticação por CRON_SECRET e HMAC. Sem rate limit no Worker em qualquer ambiente.

---

0.2 Decisões arquiteturais (D1–D6) — todas aprovadas

#	Decisão	Status	Opção escolhida
D1	Backing store para rate limit	✅ Aprovada	Híbrido: Map in-memory para burst ≤10s (limitação documentada: fragmentado por PoP) + Redis para janelas ≥1min
D2	Comportamento quando Redis falha	✅ Aprovada	Fail-open no Worker + alerta ntfy crítico. Backend mantém suas próprias defesas (RLS, lockout).
D3	Quota Wasender	✅ Aprovada	200 mensagens/escola/dia como proteção de fila compartilhada (não limitação de uso). Revisitar com dados reais.
D4	Estratégia de calibração	✅ Aprovada	Limites estáticos calibrados pelo pico hipotético + alerta em 70% do threshold. Sem distinção de horário até pico real ser medido por 30 dias consecutivos.
D5	Bypass para testes E2E	✅ Aprovada	Header X-E2E-Bypass + secret — bypass total. Testes E2E precisam ser determinísticos.
D6	Retenção de métricas	✅ Aprovada	TTL natural por janela no Redis (2h) + agregação horária no Postgres via cron, retenção 90 dias.

---

0.3 Regras obrigatórias de código Redis (resumo)

Detalhes e exemplos no WORKER_V3_REDIS_PLAN.md §5. As regras invioláveis:

#	Regra	Consequência da violação
1	Toda chave Redis DEVE ter TTL — sem exceção	Memory leak no Upstash, billing surpresa
2	redis.keys() PROIBIDO — usar SCAN com cursor	Bloqueio do Redis em produção, gateway derruba
3	Telemetria sempre via ctx.waitUntil() — nunca no caminho crítico	Latência do gateway acoplada à latência do Redis
4	Fail-open obrigatório — se Redis falhar, Worker continua sem rate limit	Alerta ntfy crítico, mas site não cai
5	Prefixo de ambiente obrigatório: olp: produção, olp-stg: staging	Cross-contamination de contadores entre ambientes

---

1. Contexto e Motivação

Por que Redis?

Operação	Postgres (atual)	Upstash Redis
Rate limit check	~20-80ms (query + RLS)	~5-15ms (REST API)
Blacklist check	~15-40ms	~5-10ms
Session lookup	~20-50ms	~5-10ms
Alert cooldown	~15-30ms	~3-8ms

Latência real do Upstash

• Upstash REST API: ~5-15ms por comando (região gru1 ou us-east-1)
• Não é zero latência — ainda há hop de rede HTTP
• Latência mínima possível (~1ms) só com Redis TCP nativo, que Upstash REST não usa
• Mesmo assim, 3-8x mais rápido que queries Postgres equivalentes

---

2. Inventário de Migração

Categoria 1 — Migração Imediata (dados efêmeros)

Tabela Postgres	Chave Redis	Motivo
token_blacklist	olp:bl:{jti}	TTL natural, sem necessidade de cron cleanup
portal_alert_cooldown	olp:ac:{alert_key}	Cooldown puro, TTL 15min
portal_rate_metrics	olp:metrics:{tipo}:{escola}:{min}	Contadores efêmeros

Categoria 2 — Migração Posterior (novo recurso)

Recurso	Chave Redis	Motivo
Sessões ativas	olp:sess:{jti} + olp:user-sess:{id}	Não existe hoje, Redis é ideal
Burst limit (Worker)	olp:rl:burst:{ip}	Substitui Map in-memory do Worker

Categoria 3 — NÃO Migrar (permanecem no Postgres)

Tabela	Motivo
logs_transacoes	Compliance, auditoria, queries complexas, retenção longa
portal_login_tentativas	Analytics histórico, relatórios, JOINs
senha_historico	Segurança, bcrypt hashes, retenção permanente
login_otps	Curta vida mas precisa de atomicidade com auth flow

---

3. Arquitetura

┌─────────────┐     ┌──────────────────┐     ┌─────────────┐
│   Browser   │────▶│ Cloudflare Worker │────▶│  Supabase   │
│             │     │                  │     │  Edge Fns   │
└─────────────┘     │  ┌────────────┐  │     └──────┬──────┘
                    │  │ Burst Rate │  │            │
                    │  │ Blacklist  │  │            │
                    │  └─────┬──────┘  │            │
                    └────────┼─────────┘            │
                             │                      │
                    ┌────────▼─────────┐            │
                    │  Upstash Redis   │◀───────────┘
                    │  (REST API)      │  Rate limits
                    │                  │  Sessions
                    │  gru1 region     │  Blacklist
                    └──────────────────┘  Cooldowns

Fluxo de um request autenticado:

1. Browser → Worker: burst check via Redis (olp:rl:burst:{ip})
2. Worker: decode JWT, blacklist check via Redis (olp:bl:{jti})
3. Worker → Edge Function: proxy com headers
4. Edge Function: rate limit via Redis (olp:rl:{tipo}:{id})
5. Edge Function: lógica de negócio via Supabase Postgres
6. Edge Function: log via Postgres (logs_transacoes)

---

4. Key Schema Redis

# ── BLACKLIST ──
olp:bl:{jti}                         → "logout" | "admin_revoke"         TTL=token_expiry_remaining

# ── SESSÕES ──
olp:sess:{jti}                       → HASH {user_id, nome, papel, ip, criado_em}   TTL=8h
olp:user-sess:{usuario_id}           → SET de JTIs ativos                            TTL=8h (renovado a cada login)

# ── RATE LIMITS ──
olp:rl:burst:{ip}                    → counter                           TTL=5s
olp:rl:lookup:ip:{ip}                → counter                           TTL=1min
olp:rl:lookup:escola:{escola_id}     → counter                           TTL=1min
olp:rl:login-a:escola:{escola_id}    → counter                           TTL=1min
olp:rl:login-a:ip:{ip}              → counter                           TTL=5min
olp:rl:otp:ip:{ip}                  → counter                           TTL=15min
olp:rl:otp:escola:{escola_id}       → counter                           TTL=15min
olp:rl:cadastro:ip:{ip}             → counter                           TTL=30min
olp:rl:vinculo:ip:{ip}              → counter                           TTL=60min

# ── LOCKOUT ──
olp:lo:{identificador}               → counter (falhas consecutivas)     TTL=24h

# ── ALERT COOLDOWN ──
olp:ac:{alert_key}                   → "1"                               TTL=15min

# ── MÉTRICAS ──
olp:metrics:{tipo}:{escola_id}:{min} → counter                           TTL=48h

Índice Reverso — olp:user-sess:{usuario_id}

Resolve o problema de invalidação pós-troca-de-senha sem O(N) scan:

# Login
HSET olp:sess:{jti} user_id {id} nome {nome} papel {papel} ip {ip}
EXPIRE olp:sess:{jti} 28800
SADD olp:user-sess:{usuario_id} {jti}
EXPIRE olp:user-sess:{usuario_id} 28800

# Logout
DEL olp:sess:{jti}
SREM olp:user-sess:{usuario_id} {jti}

# Invalidação pós-senha (revogar TODAS as sessões do usuário)
jtis = SMEMBERS olp:user-sess:{usuario_id}
for jti in jtis:
    DEL olp:sess:{jti}
    SET olp:bl:{jti} "senha_alterada" EX {ttl_restante}
DEL olp:user-sess:{usuario_id}

# Complexidade: O(M) onde M = sessões do usuário (tipicamente 1-3)

---

5. Regras Obrigatórias

5.1 — redis.keys() PROIBIDO

// ❌ NUNCA — bloqueante, varre todas as chaves
const keys = await redis.keys("olp:sess:*");

// ✅ CORRETO — iterativo, não bloqueante
let cursor = 0;
const results: string[] = [];
do {
  const [nextCursor, keys] = await redis.scan(cursor, { match: "olp:sess:*", count: 100 });
  cursor = nextCursor;
  results.push(...keys);
} while (cursor !== 0);

5.2 — Dual-Write na Transição

Durante a migração, toda operação escrita deve gravar em Redis E Postgres:

// Rate limit: gravar nos dois
await redis.incr(`olp:rl:login-a:ip:${ip}`);        // Redis (leitura primária)
await supabase.from("portal_login_tentativas").insert({...}); // Postgres (backup)

Período mínimo de dual-write: 2 semanas antes de drop de qualquer tabela.

5.3 — Fallback Postgres

Se Redis falhar (timeout, erro de rede), o sistema DEVE cair para Postgres:

async function checkRateLimitRedis(key: string, max: number, ttlSeconds: number): Promise<boolean> {
  try {
    const count = await redis.incr(key);
    if (count === 1) await redis.expire(key, ttlSeconds);
    return count <= max;
  } catch (err) {
    console.error("Redis fallback para Postgres:", err);
    return await checkRateLimitPostgres(/* params */); // fallback
  }
}

5.4 — TTLs Explícitos

Toda chave Redis DEVE ter TTL. Sem exceções. Chaves sem TTL = memory leak.

---

6. Fases de Implementação

Fase A — Infra Redis no Cloudflare Worker

Pré-requisito: Conta Upstash criada, database provisionado (região gru1)

#	Tarefa	Arquivo
A.1	Criar database Upstash (gru1 ou us-east-1)	Dashboard Upstash
A.2	Adicionar secrets no Cloudflare	UPSTASH_REDIS_REST_URL, UPSTASH_REDIS_REST_TOKEN
A.3	Worker: importar @upstash/redis	cloudflare-worker/src/index.ts
A.4	Worker: burst rate limit via Redis INCR+EXPIRE	substitui Map in-memory
A.5	Worker: blacklist check — GET olp:bl:{jti}	decode JWT sem verify (jti público)

Validação: Monitorar latência de burst check no Worker por 1-2 dias antes de avançar.

Fase B — Rate Limit nas Edge Functions

#	Tarefa	Arquivo
B.1	Criar redis-client.ts wrapper	supabase/functions/_shared/redis-client.ts
B.2	Adicionar secrets Supabase	UPSTASH_REDIS_REST_URL, UPSTASH_REDIS_REST_TOKEN
B.3	checkRateLimit() → Redis INCR (fallback Postgres)	portal-security.ts
B.4	registrarTentativa() → dual-write	portal-security.ts
B.5	checkLockout() → Redis INCR + TTL 24h	portal-security.ts
B.6	shouldSendAlert() → Redis SET + TTL 15min	portal-security.ts

Nota: portal-security.ts (224 linhas) será refatorado nesta fase, separando:

• portal-security-constants.ts — constantes e thresholds
• portal-security-redis.ts — implementações Redis com fallback
• portal-security.ts — re-exports (backward compat)

Fase C — Token Blacklist em Redis

#	Tarefa	Arquivo
C.1	Logout: SET olp:bl:{jti} + Postgres INSERT	logout/index.ts
C.2	Auth check: blacklist via Redis GET (fallback Postgres)	_shared/auth-helpers.ts
C.3	Portal auth: blacklist via Redis	_shared/jwt-portal.ts
C.4	Após 2 semanas: drop tabela token_blacklist	Migration SQL
C.5	Remover cleanup de blacklist do maintenance-cron	maintenance-cron/index.ts

Fase D — Sessões Ativas em Redis

#	Tarefa	Arquivo
D.1	Login: HSET olp:sess:{jti} + SADD olp:user-sess:{id}	verify-otp/index.ts, select-role/index.ts
D.2	Logout: DEL sess + SREM user-sess	logout/index.ts
D.3	Admin list: SCAN olp:sess:* + HGETALL	Nova Edge Function
D.4	Admin revoke: DEL sess + SET bl + SREM user-sess	Nova Edge Function
D.5	Invalidação pós-senha: SMEMBERS user-sess → revoke all	change-password/index.ts
D.6	Frontend: painel de sessões ativas	src/components/admin-sessoes.tsx

Fase E — Cleanup

#	Tarefa	Condição
E.1	Drop portal_alert_cooldown	Fase B validada (2 sem)
E.2	Drop token_blacklist	Fase C validada (2 sem)
E.3	Simplificar maintenance-cron	Remover tarefas migradas
E.4	portal_login_tentativas → write-only	Manter para analytics, remover reads
E.5	Avaliar drop portal_rate_metrics	Se métricas Redis suficientes

---

7. Dívidas Técnicas — Inventário

Prioridade 1 — Resolvidas pelo Redis

ID	Dívida	Solução Redis
P1	Invalidação de sessão pós-troca-senha não revoga todas	olp:user-sess:{id} → revoke all
P2	Burst rate limit usa Map in-memory (perde entre deploys)	Redis INCR persistente
P3	Alert cooldown por isolate (não cross-instance)	Redis SET com TTL
P4	Token blacklist precisa de cron cleanup	TTL automático

Prioridade 2 — Melhorias com Redis

ID	Dívida	Benefício
P5	Rate limit queries pesadas no pico (12h BRT)	Redis ~5ms vs Postgres ~40ms
P6	Sem visibilidade de sessões ativas	Painel admin com SCAN
P7	Lockout check faz query em 24h de dados	Redis counter com TTL

Prioridade 3 — Independentes do Redis

ID	Dívida	Status
P8	Papéis bloqueados (pedagógico, professor, marketing) precisam de UI	Backlog
P9	Portal: abandonment rate alto (324 lookups vs 185 logins)	Investigar UX
P10	WhatsApp (Wasender) retry/dead-letter queue	Backlog

---

8. Estimativa de Custo Upstash

Comandos por request autenticado

Operação	Comandos
Blacklist GET	1
Rate limit (INCR + EXPIRE)	2-3
Session check	1
Métricas INCR	1-2
Total por request	5-8

Projeção de custo

Escala	Requests/dia	Comandos/dia	Custo/dia	Custo/mês
Atual (2 escolas, 93 alunos)	~500-1.5k	~2.5k-12k	Free tier	$0
10 escolas	~5k	~30k	~$0.04	~$1.20
50 escolas	~50k	~300k	~$0.60	~$18
200 escolas	~200k	~1.2M	~$2.40	~$72
Pico matrícula	~500k	~3M	~$6.00	—

Pricing Upstash: $0.2 por 100k comandos após free tier (10k/dia grátis).

---

9. Riscos e Mitigações

Risco	Impacto	Mitigação
Upstash indisponível	Rate limits e blacklist falham	Fallback Postgres (§5.3)
TTL não configurado em chave	Memory leak no Redis	Lint rule: toda chave DEVE ter EXPIRE
redis.keys() usado acidentalmente	Bloqueio em produção	Code review + grep CI
Dual-write inconsistência	Dados divergem Redis/Postgres	Monitorar contagem por 2 semanas
Custo escala inesperada	Billing surpresa	Alert no Upstash dashboard > 500k cmd/dia

---

10. Documentação a Atualizar

Documento	Mudança	Fase
docs/architecture/CLOUDFLARE_WORKER_GATEWAY.md	Seção Redis, variáveis, fluxo burst	A
docs/architecture/CLOUDFLARE_WORKER_CODE.md	Imports Upstash, burst Redis	A
docs/security/RATE_LIMITS.md	Reescrever — Redis substitui Postgres	B
docs/security/AUTHENTICATION.md	Blacklist via Redis, sessões	C
docs/operations/CRON_JOBS.md	Remover tarefas migradas	E
docs/operations/DATABASE_CLEANUP.md	Tabelas removidas	E
docs/operations/SESSION_MANAGEMENT_ALERTS.md	Substituído por Redis	D
docs/operations/ANOMALY_DETECTION.md	Dependência Redis	B
docs/README.md	Upstash no stack	A
NOVO: docs/architecture/UPSTASH_REDIS.md	Arquitetura, key schema, TTLs, fallback, SCAN policy	A

---

11. Dados Reais de Uso (Coletados 2026-03-30)

Volume

• 93 alunos únicos ativos no portal
• 2 escolas ativas
• 5-30 logins/dia (normal), 280 logins/dia (pico)
• ~5 logins/aluno/mês (re-login frequente, não sessão persistente)

Distribuição horária

08h: ░░░░░ 5%
09h: ░░░░░░ 6%
10h: ░░░░░░░ 8%
11h: ░░░░░░░░░ 10%
12h: ██████████████████████████████████████ 37%  ← PICO (almoço)
13h: ███████████████ 15%
14h: ░░░░░░░░ 8%
15h: ░░░░░ 5%
16h+: ░░░░░░ 6%

• 52% do tráfego concentrado entre 12h-13h BRT
• Uso claramente escolar (intervalo de almoço)

Implicação para Redis

• Volume atual cabe no Free Tier do Upstash
• Pico de 12h gera ~50-100 comandos/minuto — trivial para Redis
• Scaling para 50+ escolas requer tier pago (~$18/mês)

---

12. Checklist de Prontidão por Fase

Fase A — Pronto para iniciar quando:

• [ ] Conta Upstash criada
• [ ] Database provisionado (região gru1)
• [ ] Secrets adicionados no Cloudflare Dashboard
• [ ] Worker local testado com Upstash

Fase B — Pronto quando:

• [ ] Fase A validada em produção (1-2 dias)
• [ ] Secrets adicionados no Supabase Dashboard
• [ ] redis-client.ts criado e testado

Fase C — Pronto quando:

• [ ] Fase B validada (rate limits funcionando via Redis)
• [ ] Dual-write blacklist implementado

Fase D — Pronto quando:

• [ ] Fase C validada (blacklist via Redis)
• [ ] Índice reverso olp:user-sess testado

Fase E — Pronto quando:

• [ ] Todas as fases anteriores validadas por ≥2 semanas
• [ ] Zero discrepância Redis vs Postgres no período de dual-write
• [ ] Backup das tabelas antes do drop