Descrição de PR: narre uma mudança da motivação ao rollout

Quatro arquivos se moveram. Aqui está cada um e por quê.

• adicionado limiter/sliding_window.go O novo algoritmo. Mantém um pequeno anel de subcontagens por segundo e soma os 60 mais recentes. Este é o coração da mudança.
• editado limiter/middleware.go Troca o limiter por trás da flag. Quando ratelimit_sliding_v2 está desligada, o antigo caminho de janela fixa fica intacto — zero mudança de comportamento por padrão.
• editado config/flags.yaml Registra a nova flag, com padrão false. Permite habilitar por ambiente sem um redeploy.
• teste limiter/sliding_window_test.go Reproduz o caso de rajada na fronteira que as janelas fixas falham, e garante que o novo limiter o bloqueia. O teste é a especificação.

O único ponto delicado que merece uma leitura cuidadosa.

// protegido por sw.mu — NÃO separe a leitura e a escrita
func (sw *SlidingWindow) Allow(now time.Time) bool {
  sw.mu.Lock()
  defer sw.mu.Unlock()

  sw.evictOlderThan(now.Add(-60 * time.Second))
  if sw.total >= sw.limit {
    return false          // acima do orçamento para os últimos 60s
  }
  sw.record(now)        // incrementa DENTRO do mesmo lock
  return true
}

Se você revisar apenas um trecho, que seja este. Todo o resto é encanamento; a corretude mora aqui.

Como entra em produção sem acordar ninguém às 3 da manhã.

1. Subir no escuro por trás de uma flag
   Faça o merge com ratelimit_sliding_v2=false em todos os lugares. Nenhum tráfego atinge o novo caminho. Seguro para dar merge hoje.
2. Canário em 5% no staging, depois em produção
   Habilite a flag para 5% das chaves de API. Observe por 1 hora antes de ampliar.
3. Monitore os sinais certos
   Dashboards: ratelimit.rejections (deve subir um pouco), payments.timeouts (deve cair a zero) e a latência limiter.allow.p99 (precisa ficar abaixo de 1ms). Alerte se o p99 dobrar.
4. Aumente 5% → 25% → 100%
   Avance um degrau só quando o passo anterior estiver limpo por uma hora inteira. Rollout completo previsto ao longo de dois dias.
5. Plano de rollback
   Mude ratelimit_sliding_v2=false — reversão instantânea para o limiter antigo, sem deploy. Mantenha a flag por duas semanas, depois remova o caminho morto num PR de acompanhamento.