OmniRoute/docs/TASKS.md

Rate Limiting & Flow Control Overhaul — Tasks

Referência: Relatório de Análise · Fase docs em /docs/phases/

---

Fase 1 — Error Classification & Provider Profiles

Backend Core

• constants.ts — Substituir COOLDOWN_MS.transient por transientInitial (5s) + transientMax (60s)
• constants.ts — Adicionar PROVIDER_PROFILES (oauth / apikey) com cooldowns diferenciados
• constants.ts — Adicionar DEFAULT_API_LIMITS (100 RPM, 200ms minTime)
• providerRegistry.ts — Criar helper getProviderCategory(providerId) → "oauth" | "apikey"
• accountFallback.ts — Aceitar provider como parâmetro em checkFallbackError
• accountFallback.ts — Implementar backoff exponencial para 502/503/504 transientes
• accountFallback.ts — Calcular cooldown baseado no perfil do provedor
• accountFallback.ts — Adicionar helper getProviderProfile(provider)

Callers (propagar provider)

• auth.ts → markAccountUnavailable — Passar provider para checkFallbackError
• combo.ts → handleComboChat / handleRoundRobinCombo — Passar provider nos erros

Testes

• Atualizar rate-limit-enhanced.test.mjs — Teste "transient errors don't increase backoff" → newBackoffLevel = 1
• Criar error-classification.test.mjs — Cooldown exponencial 502, perfis OAuth/API, helper getProviderCategory

---

Fase 2 — Circuit Breaker no Combo Pipeline

Backend

• combo.ts — Importar getCircuitBreaker e CircuitBreakerOpenError
• combo.ts — handleComboChat — Verificar breaker.canExecute() antes de cada modelo
• combo.ts — handleRoundRobinCombo — Integrar breaker per-model
• combo.ts — Marcar semaphore.markRateLimited para 502/503/504 (não só 429)
• combo.ts — Implementar early exit quando todos os modelos têm breaker OPEN

Testes

• Criar combo-circuit-breaker.test.mjs — Combo skip breaker OPEN, early exit, semáforo 502

---

Fase 3 — Anti-Thundering Herd & Auto Rate Limit

Backend

• rateLimitManager.ts — Auto-enable para apikey providers com limites elevados
• rateLimitManager.ts — Criar limiter com defaults (100 RPM) quando não configurado
• auth.ts — Adicionar mutex na markAccountUnavailable para evitar marcação paralela

Testes

• Criar thundering-herd.test.mjs — Mutex, auto-enable, limites não restritivos

---

Fase 4 — Frontend Resilience UI

Settings Page

• settings/page.tsx — Adicionar tab "Resilience" (icon: health_and_safety) entre Routing e Pricing

Novos Componentes

• Criar ResilienceTab.tsx — Layout com 4 cards (Provider Profiles → Rate Limiting → Circuit Breakers → Policies)
• Criar ProviderProfilesCard.tsx — Toggle OAuth/API Key, inputs para cooldowns
• Criar CircuitBreakerCard.tsx — Status real-time per-provider, auto-refresh 5s, botão reset
• Criar RateLimitOverviewCard.tsx — Tabela providers × accounts × cooldown — agora editável com RPM, Min Gap, Max Concurrent

API Routes

• Criar api/resilience/route.ts — GET (estado completo + defaults mesclados) + PATCH (salvar perfis + defaults)
• Criar api/resilience/reset/route.ts — POST (resetar breakers + cooldowns)

Migração

• PoliciesPanel.tsx movido de Security para Resilience tab

---

Fase 5 — Settings Page Restructure (v0.9.0)

Tab Reorganization

• Security — Simplificado para Login/Password + IP Access Control
• Routing — Expandido para 6 estratégias globais com descrições
• Resilience — Reordenado: Provider Profiles → Rate Limiting (editável) → Circuit Breakers → Policies
• AI — Thinking Budget + System Prompt + Prompt Cache (movido do Advanced)
• Advanced — Simplificado para apenas Global Proxy

Backend Routing Strategies

• auth.ts — Implementar random (Fisher-Yates shuffle)
• auth.ts — Implementar least-used (sorted by lastUsedAt)
• auth.ts — Implementar cost-optimized (sorted by priority)
• auth.ts — Corrigir p2c (power-of-two-choices com health scoring)
• settings.ts — Expandir tipo fallbackStrategy para 6 valores

---

Verificação Final

• Rodar todos os testes unitários: node --test tests/unit/*.test.mjs
• Build do Next.js: npm run build
• Verificar aba Resilience no browser
• Testar persistência dos perfis (salvar → reload)
• Testar Reset All Breakers
• Verificar todas as 5 tabs reestruturadas