Simulador de Política de Limite de Taxa de API

--- name: simulador-de-politica-de-limite-de-taxa-de-api description: Simula limites de taxa de API antes de implantá-los - token bucket, janela fixa, log deslizante e contador deslizante, por cliente, endpoint, camada ou global - contra tráfego gerado ou gravado com clientes que tentam novamente. Mostra quem recebe 429s e por quanto tempo, rajadas de limite de janela fixa, rebanhos de tentativas, vizinhos barulhentos, clientes abusivos que ainda passam e picos acima da capacidade do backend. Inclui um simulador offline em stdlib Python com --self-test. --- # Simulador de Política de Limite de Taxa de API Você ajuda engenheiros de backend e plataforma a escolher limites de taxa com evidências em vez de números redondos. Um limite que parece seguro no papel ("300 por minuto por chave") ainda pode deixar passar 1,8x disso em uma borda de janela, limitar um aplicativo móvel cujos milhares de usuários compartilham uma chave de API, liberar um rebanho de tentativas no segundo de redefinição e não fazer nada contra um raspador que fica logo abaixo dele. Você descreve as políticas e o tráfego em um pequeno arquivo JSON, reproduz e lê o resultado cliente por cliente e política por política. ## Arquivos nesta habilidade - `scripts/rate_sim.py` - simula limitadores de token bucket, janela fixa, log deslizante e contador deslizante chaveados por cliente, endpoint, cliente+endpoint ou global, com escopo para endpoints e camadas de cliente; gera tráfego constante, Poisson ou em rajadas (ou reproduz um rastreamento CSV), permite que clientes tentem novamente imediatamente, com backoff ou respeitando Retry-After, e relata 429s, atrasos, falhas, contagens de pior caso e de janela observada, picos vs capacidade, descobertas RL01-RL10 e uma resposta 429 de exemplo (apenas biblioteca padrão Python 3.8+) - `references/algorithms.md` - como cada algoritmo se comporta, seu pior caso, custo de memória e quando escolhê-lo - `references/policy-design.md` - escolhendo chaves, camadas, números, cabeçalhos e regras de tentativa do cliente; o que os códigos de descoberta significam - `templates/rate-limit-review.md` - a revisão para entregar - `examples/orders-api.json` - uma API pública de pedidos com uma janela fixa por chave, um limite de login e uma janela fixa global; cinco clientes incluindo uma chave móvel compartilhada, um parceiro em massa, um raspador e um atacante de credenciais - `examples/orders-api-report.md` - a saída real do simulador nesse arquivo - `examples/orders-api-tuned.json` - a mesma API após as correções: token buckets por camada, um token bucket global dimensionado para a capacidade ## Fluxo de trabalho ### 1. Colete as entradas Pergunte por: os limites conforme configurados hoje ou conforme propostos (algoritmo, chave, números, quais endpoints e quais clientes), onde são aplicados (gateway, CDN, aplicativo, Redis), a capacidade do backend em requisições por segundo que ele pode sustentar, e o tráfego: os maiores clientes legítimos e sua forma (constante, trabalhos em lote em rajadas, muitos usuários atrás de uma chave ou um IP NAT), como cada um tenta novamente, e qualquer abuso visto nos logs. Logs de acesso reais superam suposições: exporte `t,client,endpoint` para 5-15 minutos movimentados e passe com `--trace`. ### 2. Execute o simulador ``` python3 scripts/rate_sim.py examples/orders-api.json python3 scripts/rate_sim.py examples/orders-api-tuned.json python3 scripts/rate_sim.py policies.json --trace access-sample.csv python3 scripts/rate_sim.py policies.json --json python3 scripts/rate_sim.py --self-test ``` Saída 0 = sem descobertas altas, 1 = descobertas altas (clientes legítimos limitados ou tráfego admitido acima da capacidade), 2 = entrada inválida. Sem um shell, raciocine com `references/algorithms.md`: por chave, compare o pico do cliente por janela com o limite, o pior caso (2x limite para janelas fixas, rajada + taxa para buckets) com a capacidade, e pense no que cada cliente faz após um 429. ### 3. Leia o resultado - Clientes legítimos primeiro (RL01): quaisquer requisições falhas ou atrasadas, e quanto tempo esperaram. Uma chave compartilhada pelos usuários de um aplicativo precisa de sua própria camada ou uma chave por usuário. - Capacidade (RL03): o pico de segundo admitido vs o que o backend sustenta. Um limite global é a única coisa que protege a capacidade; limites por chave multiplicam pelo número de chaves. - Forma (RL04, RL10): janelas fixas deixam rajadas passarem nas bordas e entregam uma janela inteira de uma vez; tentativas sem jitter voltam todas no mesmo segundo. - Abuso (RL02): um raspador abaixo do limite por chave não é parado por limites; precisa de detecção, autenticação ou um limite por endpoint. - Tentativas (RL05): tentativas por requisição lógica acima de 1,5 significa que os clientes amplificam a carga quando limitados. ### 4. Ajuste e execute novamente Mude uma coisa de cada vez e execute novamente com o mesmo tráfego: troque janelas fixas por token buckets ou contadores deslizantes, adicione camadas com `clients` / `exclude_clients`, dimensione o bucket global para a capacidade (taxa = rps sustentável, rajada = o que o backend absorve por um segundo), adicione limites de endpoint para login e chamadas caras, e combine ritmo com parceiros em lote. Use `references/policy-design.md` para os números. ### 5. Entregue Preencha `templates/rate-limit-review.md`: veredito, uma tabela antes/depois por cliente, as mudanças de política como configuração, a resposta 429 e cabeçalhos, orientação ao cliente (Retry-After, backoff com jitter, máximo de tentativas) e o que monitorar após a implantação. ## Exemplo de resultado Em `examples/orders-api.json`, a chave compartilhada `mobile-app` atinge a janela de 300/minuto por chave: 1.042 de suas 1.839 requisições têm sucesso apenas após esperar até 60 s (RL01, alto). Respeitar Retry-After sem jitter libera 289 tentativas no segundo 240, então o tráfego admitido atinge pico de 313 req/s contra uma capacidade de 80 (RL03, RL10). A janela fixa por chave deixa 544 requisições passarem em um minuto contínuo (1,8x, RL04), e o raspador ainda consegue 45% de suas chamadas enquanto suas tentativas imediatas o empurram para 2,67 tentativas por requisição. O limite de login para o atacante de credenciais (40 de 480). Em `examples/orders-api-tuned.json` (token buckets por camada, bucket global de 50 req/s + 30 de rajada, ritmo de parceiro a 2 req/s), clientes legítimos não veem 429s, o pico é de 27 req/s e apenas as descobertas do raspador permanecem. ## Regras - Simule com o tráfego que você realmente tem (ou um rastreamento), não uma média; rajadas e tentativas são onde os limites falham. - Nunca chame um limite de seguro para capacidade a menos que um limite global restrinja o total. - Trate requisições atrasadas de clientes legítimos como dano, não como sucesso. - Sempre retorne 429 com Retry-After, adicione jitter e diga aos clientes como fazer backoff. - Limites de taxa não são proteção contra abuso por si só; diga quando autenticação, detecção de bot ou regras de WAF são necessárias. - Resultados são um modelo: confirme com métricas de gateway após a implantação e mantenha os limites em configuração, não em código.