Calculateur token bucket

Le limiteur de débit token bucket est le modèle de référence derrière le throttling d'API, les quotas de passerelle et la contre-pression côté client. Le même module pur et déterministe alimente l'outil gratuit du navigateur et le chemin API, afin que revues de conception, scripts de test de charge et simulateurs de production ne divergent jamais sur les cas limites : seau plein, recharge partielle ou requête plus grande que le plafond de rafale.

Comment l'algorithme token bucket décide d'autoriser ou de refuser

Le token bucket stocke un solde de jetons non négatif qui ne dépasse jamais la capacité. Le temps écoulé est fourni par l'appelant pour que le calcul reste déterministe—aucune horloge murale n'est lue—, ainsi les mêmes entrées produisent toujours la même décision, le même solde restant et les mêmes secondes d'attente sur les runtimes et les goldens. Entre deux contrôles, les jetons s'accumulent à refill_rate jetons par seconde pendant la durée elapsed, puis le solde est plafonné avec min(capacity, tokens + elapsed multiplié par refill_rate). Cette valeur plafonnée est tokens_available : ce que vous pouvez dépenser immédiatement. Une rafale qui coûte request_count jetons est autorisée lorsque tokens_available vaut au moins request_count ; en cas d'autorisation, tokens_remaining devient tokens_available moins request_count et tokens_consumed égale request_count. En cas de refus, aucun jeton n'est dépensé : tokens_remaining reste à tokens_available, tokens_consumed vaut zéro et deficit égale request_count moins tokens_available. Le temps d'attente est deficit divisé par refill_rate lorsque la recharge est positive et que la requête ne dépasse pas la capacité ; sinon la requête ne pourra pas non plus être satisfaite plus tard (can_satisfy est false), ce qui couvre à la fois un coût au-dessus du plafond de rafale et un seau figé avec recharge nulle. La capacité est la marge de rafale : un seau plein de dix avec une recharge lente laisse encore passer un pic de dix jetons, c'est pourquoi les passerelles choisissent capacity pour les pics et refill_rate pour le trafic moyen soutenu.

Contrat d'entrée, champs de réponse et erreurs de validation

Envoyez un corps JSON avec cinq nombres finis obligatoires. capacity doit être strictement positif et représente le maximum de jetons que le seau peut contenir après recharge. refill_rate doit être supérieur ou égal à zéro et se mesure en jetons par seconde ; zéro signifie que le seau ne se remplit plus une fois vide. tokens est le solde avant d'appliquer cet intervalle elapsed et doit être non négatif ; les valeurs au-dessus de capacity sont acceptées puis plafonnées lors du calcul de tokens_available après recharge. elapsed est le nombre de secondes depuis la dernière mise à jour et doit être non négatif. request_count est le nombre de jetons dont cette rafale a besoin et doit être strictement positif. Champs manquants, chaînes non numériques, NaN, Infinity et signes hors plage échouent avec invalid_input en nommant le champ et ne sont pas facturés. En cas de succès le corps renvoie les cinq entrées, puis tokens_available après recharge, allowed en booléen, tokens_remaining après la décision de dépense, tokens_consumed, deficit, wait_seconds (zéro si autorisé ou si la requête ne peut jamais passer), can_satisfy et une courte chaîne formula qui reformule la règle de mise à jour. Exemple : capacity dix, refill_rate deux par seconde, tokens cinq, elapsed une seconde et demie, request_count trois produit tokens_available huit (cinq plus trois de recharge, encore sous la capacité), allowed true, tokens_remaining cinq et wait_seconds zéro. Un second appel qui demande neuf jetons avec les mêmes huit disponibles est refusé avec deficit un et wait_seconds d'une demi-seconde à deux jetons par seconde.

Où un calculateur token bucket apporte une vraie valeur

Les auteurs d'edge et de passerelle utilisent le calculateur comme oracle en implémentant des seaux Redis ou en mémoire, en comparant leur machine d'états locale à ce résultat en forme fermée pour des entrées identiques. Les formateurs et les entretiens SRE s'en servent pour montrer qu'un token bucket n'est pas un leaky bucket pur : les rafales sont autorisées jusqu'à capacity, puis la recharge régulière restaure de la marge. Une validation échouée ne consomme pas de solde. Les équipes produit d'API dimensionnent capacity et recharge avant de publier un quota : elles testent des valeurs candidates et des tailles de rafale pour voir si les pics légitimes passent tandis que les inondations abusives attendent. Les bancs de test de charge et les scripts de chaos appellent le même endpoint pur pour affirmer qu'un client synthétique qui respecte wait_seconds ne dépense jamais au-delà de la limite documentée. Comme l'implémentation est pure parse de niveau A, chaque appel réussi coûte le prix de base publié $0.002 sans jetons de modèle ni réseau sortant. Gardez les requêtes compactes, figez dans les tests les champs numériques arrondis, et vous obtenez des réponses reproductibles d'autorisation et d'attente pour documents de conception, exemples de SDK et essais en production sans déployer un service complet de limitation de débit.