Calculadora token bucket

El limitador de tasa token bucket es el modelo habitual detrás del throttling de API, las cuotas de puerta de enlace y la contrapresión en el cliente. El mismo módulo puro y determinista alimenta la herramienta gratuita del navegador y la ruta de la API, de modo que revisiones de diseño, scripts de prueba de carga y simuladores de producción no discrepan en casos límite como un cubo lleno, una recarga parcial o una petición mayor que el techo de ráfaga.

Cómo el algoritmo token bucket decide permitir o denegar

El token bucket almacena un saldo de tokens no negativo que nunca supera la capacidad. El tiempo transcurrido lo aporta quien llama para que la matemática sea determinista—no se lee el reloj del sistema—, de modo que las mismas entradas producen siempre la misma decisión, el mismo saldo restante y los mismos segundos de espera en runtimes y goldens. Entre comprobaciones, los tokens se acumulan a refill_rate tokens por segundo durante el intervalo elapsed y luego el saldo se acota con min(capacity, tokens + elapsed por refill_rate). Ese valor acotado es tokens_available: lo que puede gastar ahora mismo. Una ráfaga que cuesta request_count tokens se permite cuando tokens_available es al menos request_count; al permitir, tokens_remaining pasa a ser tokens_available menos request_count y tokens_consumed iguala request_count. Al denegar no se gastan tokens: tokens_remaining se mantiene en tokens_available, tokens_consumed es cero y deficit es request_count menos tokens_available. El tiempo de espera es deficit dividido entre refill_rate cuando la recarga es positiva y la petición no supera la capacidad; en caso contrario la petición tampoco podrá satisfacerse más adelante (can_satisfy es false), lo que cubre tanto un coste por encima del techo de ráfaga como un cubo congelado con recarga cero. La capacidad es el margen de ráfaga: un cubo lleno de diez con recarga lenta aún deja pasar un pico de diez tokens, por eso las puertas de enlace eligen capacity para picos y refill_rate para el tráfico medio sostenido.

Contrato de entrada, campos de respuesta y errores de validación

Envíe un cuerpo JSON con cinco números finitos obligatorios. capacity debe ser mayor que cero y es el máximo de tokens que el cubo puede retener tras la recarga. refill_rate debe ser mayor o igual que cero y se mide en tokens por segundo; cero significa que el cubo no se recupera una vez vacío. tokens es el saldo antes de aplicar este intervalo elapsed y debe ser no negativo; se aceptan valores por encima de capacity y se acotan al calcular tokens_available tras la recarga. elapsed son los segundos desde la última actualización y debe ser no negativo. request_count es cuántos tokens necesita esta ráfaga y debe ser mayor que cero. Campos ausentes, cadenas no numéricas, NaN, Infinity y signos fuera de rango fallan con invalid_input nombrando el campo y no se facturan. En caso de éxito el cuerpo repite las cinco entradas y devuelve tokens_available tras la recarga, allowed como booleano, tokens_remaining tras la decisión de gasto, tokens_consumed, deficit, wait_seconds (cero si se permite o si la petición nunca puede pasar), can_satisfy y una cadena formula breve que reescribe la regla de actualización. Ejemplo: capacity diez, refill_rate dos por segundo, tokens cinco, elapsed uno y medio, request_count tres produce tokens_available ocho (cinco más tres de recarga, aún bajo capacidad), allowed true, tokens_remaining cinco y wait_seconds cero. Una segunda llamada que pide nueve tokens con los mismos ocho disponibles se deniega con deficit uno y wait_seconds de medio segundo a dos tokens por segundo.

Dónde una calculadora token bucket aporta valor real

Autores de edge y de puerta de enlace usan la calculadora como oráculo al implementar cubos en Redis o en memoria, comparando su máquina de estados local con este resultado de forma cerrada para entradas idénticas. Educadores y entrevistas SRE la emplean para mostrar que token bucket no es lo mismo que un leaky bucket puro: se permiten ráfagas hasta capacity y luego la recarga suave restablece margen. La validación fallida no consume saldo. Los equipos de producto de API dimensionan capacity y recarga antes de publicar una cuota: prueban cifras candidatas y tamaños de ráfaga de muestra para ver si los picos legítimos pasan mientras las inundaciones abusivas esperan. Los arneses de prueba de carga y los scripts de caos llaman al mismo endpoint puro para afirmar que un cliente sintético que respeta wait_seconds nunca gasta de más respecto al límite documentado. Como la implementación es parse pura de nivel A, cada llamada exitosa cuesta el precio base publicado $0.002 sin tokens de modelo ni red saliente. Mantenga las peticiones pequeñas, fije en las pruebas los campos numéricos redondeados y obtendrá respuestas reproducibles de permitir y esperar para documentos de diseño, ejemplos de SDK y ensayos en producción sin montar un servicio completo de límite de tasa.