Calculadora token bucket

O limitador de taxa token bucket é o modelo padrão por trás do throttling de API, das cotas de gateway e da contrapressão no cliente. O mesmo módulo puro e determinístico alimenta a ferramenta gratuita do navegador e o caminho da API, de modo que revisões de design, scripts de teste de carga e simuladores de produção não discordam em casos-limite como balde cheio, recarga parcial ou requisição maior que o teto de burst.

Como o algoritmo token bucket decide permitir ou negar

O token bucket guarda um saldo de tokens não negativo que nunca ultrapassa a capacidade. O tempo decorrido é informado por quem chama para a matemática permanecer determinística—nenhum relógio de parede é lido—, assim as mesmas entradas sempre produzem a mesma decisão, o mesmo saldo restante e os mesmos segundos de espera em runtimes e goldens. Entre verificações, os tokens se acumulam a refill_rate tokens por segundo durante o intervalo elapsed e o saldo é limitado com min(capacity, tokens + elapsed vezes refill_rate). Esse valor limitado é tokens_available: o que você pode gastar agora. Um burst que custa request_count tokens é permitido quando tokens_available é pelo menos request_count; ao permitir, tokens_remaining vira tokens_available menos request_count e tokens_consumed iguala request_count. Ao negar, nenhum token é gasto: tokens_remaining permanece em tokens_available, tokens_consumed é zero e deficit é request_count menos tokens_available. O tempo de espera é deficit dividido por refill_rate quando a recarga é positiva e a requisição não é maior que a capacidade; caso contrário a requisição também não poderá ser atendida depois (can_satisfy é false), o que cobre tanto um custo acima do teto de burst quanto um balde congelado com recarga zero. A capacidade é a folga de burst: um balde cheio de dez com recarga lenta ainda deixa passar um pico de dez tokens, por isso gateways escolhem capacity para picos e refill_rate para o tráfego médio sustentado.

Contrato de entrada, campos de resposta e erros de validação

Envie um corpo JSON com cinco números finitos obrigatórios. capacity deve ser maior que zero e é o máximo de tokens que o balde pode reter após a recarga. refill_rate deve ser maior ou igual a zero e se mede em tokens por segundo; zero significa que o balde nunca se recupera depois de vazio. tokens é o saldo antes de aplicar este intervalo elapsed e deve ser não negativo; valores acima de capacity são aceitos e limitados ao calcular tokens_available após a recarga. elapsed são os segundos desde a última atualização e deve ser não negativo. request_count é quantos tokens este burst precisa e deve ser maior que zero. Campos ausentes, strings não numéricas, NaN, Infinity e sinais fora da faixa falham com invalid_input nomeando o campo e não são cobrados. Em caso de sucesso o corpo ecoa as cinco entradas e devolve tokens_available após a recarga, allowed como booleano, tokens_remaining após a decisão de gasto, tokens_consumed, deficit, wait_seconds (zero quando permitido ou quando a requisição nunca pode passar), can_satisfy e uma string formula curta que reescreve a regra de atualização. Exemplo: capacity dez, refill_rate dois por segundo, tokens cinco, elapsed um e meio, request_count três produz tokens_available oito (cinco mais três da recarga, ainda sob a capacidade), allowed true, tokens_remaining cinco e wait_seconds zero. Uma segunda chamada que pede nove tokens com os mesmos oito disponíveis é negada com deficit um e wait_seconds de meio segundo a dois tokens por segundo.

Onde uma calculadora token bucket justifica o uso

Autores de edge e de gateway usam a calculadora como oráculo ao implementar baldes em Redis ou em memória, comparando a máquina de estados local com este resultado de forma fechada para entradas idênticas. Educadores e entrevistas de SRE usam-na para mostrar que token bucket não é o mesmo que um leaky bucket puro: bursts são permitidos até capacity e depois a recarga suave restaura folga. Validação falha não consome saldo. Equipes de produto de API dimensionam capacity e recarga antes de publicar uma cota: testam números candidatos e tamanhos de burst de amostra para ver se picos legítimos passam enquanto inundações abusivas esperam. Harnesses de teste de carga e scripts de caos chamam o mesmo endpoint puro para afirmar que um cliente sintético que segue wait_seconds nunca gasta além do limite documentado. Como a implementação é parse pura de nível A, cada chamada bem-sucedida custa o preço base publicado US$ 0,002 sem tokens de modelo e sem rede de saída. Mantenha as requisições pequenas, fixe nos testes os campos numéricos arredondados e obtenha respostas reprodutíveis de permitir e esperar para docs de design, exemplos de SDK e ensaios em produção sem levantar um serviço completo de limite de taxa.