Calcolatore token bucket

Il rate limiter token bucket è il modello di riferimento dietro il throttling delle API, le quote di gateway e la contropressione lato client. Lo stesso modulo puro e deterministico alimenta lo strumento gratuito del browser e il percorso API, così revisioni di progetto, script di load test e simulatori di produzione non divergono mai su casi limite come secchio pieno, ricarica parziale o richiesta più grande del tetto di burst.

Come l'algoritmo token bucket decide se consentire o negare

Il token bucket conserva un saldo di token non negativo che non supera mai la capacità. Tra un controllo e l'altro i token si accumulano a refill_rate token al secondo per la durata elapsed, poi il saldo viene limitato con min(capacity, tokens + elapsed per refill_rate). Quel valore limitato è tokens_available: quanto può spendere adesso. Un burst che costa request_count token è consentito quando tokens_available è almeno request_count; in caso di consenso, tokens_remaining diventa tokens_available meno request_count e tokens_consumed uguaglia request_count. In caso di diniego non si spendono token: tokens_remaining resta a tokens_available, tokens_consumed è zero e deficit è request_count meno tokens_available. Il tempo di attesa è deficit diviso per refill_rate quando la ricarica è positiva e la richiesta non supera la capacità; altrimenti la richiesta non potrà essere soddisfatta nemmeno in seguito (can_satisfy è false), coprendo sia un costo oltre il tetto di burst sia un secchio congelato con ricarica zero. La capacità è il margine di burst: un secchio pieno di dieci con ricarica lenta lascia comunque passare un picco di dieci token, ed è per questo che i gateway scelgono capacity per i picchi e refill_rate per il traffico medio sostenuto.

Contratto di ingresso, campi di risposta ed errori di validazione

Invii un body JSON con cinque numeri finiti obbligatori. capacity deve essere maggiore di zero ed è il massimo di token che il secchio può trattenere dopo la ricarica. refill_rate deve essere maggiore o uguale a zero e si misura in token al secondo; zero significa che il secchio non si riprende una volta vuoto. tokens è il saldo prima di applicare questo intervallo elapsed e deve essere non negativo; valori sopra capacity sono accettati e vengono limitati nel calcolo di tokens_available dopo la ricarica. elapsed sono i secondi dall'ultimo aggiornamento e deve essere non negativo. request_count è quanti token serve questo burst e deve essere maggiore di zero. Campi mancanti, stringhe non numeriche, NaN, Infinity e segni fuori intervallo falliscono con invalid_input indicando il campo e non vengono addebitati. In caso di successo il body ripete le cinque entrate e restituisce tokens_available dopo la ricarica, allowed come booleano, tokens_remaining dopo la decisione di spesa, tokens_consumed, deficit, wait_seconds (zero se consentito o se la richiesta non può mai passare), can_satisfy e una breve stringa formula che riformula la regola di aggiornamento. Esempio: capacity dieci, refill_rate due al secondo, tokens cinque, elapsed uno e mezzo, request_count tre produce tokens_available otto (cinque più tre dalla ricarica, ancora sotto capacità), allowed true, tokens_remaining cinque e wait_seconds zero. Una seconda chiamata che chiede nove token con gli stessi otto disponibili viene negata con deficit uno e wait_seconds di mezzo secondo a due token al secondo.

Dove un calcolatore token bucket dimostra il proprio valore

Autori di edge e di gateway usano il calcolatore come oracolo mentre implementano secchi Redis o in memoria, confrontando la macchina a stati locale con questo risultato in forma chiusa per ingressi identici. Formatori e colloqui SRE lo usano per mostrare che token bucket non è uguale a un leaky bucket puro: i burst sono ammessi fino a capacity e poi la ricarica regolare ripristina margine. La validazione fallita non consuma saldo. I team di prodotto API dimensionano capacity e ricarica prima di pubblicare una quota: provano numeri candidati e dimensioni di burst campione per vedere se i picchi legittimi passano mentre le inondazioni abusive attendono. Harness di load test e script di chaos chiamano lo stesso endpoint puro per affermare che un client sintetico che rispetta wait_seconds non spende mai oltre il limite documentato. Poiché l'implementazione è parse pura di livello A, ogni chiamata riuscita costa il prezzo base pubblicato $0.002 senza token di modello e senza rete in uscita. Mantenga le richieste compatte, fissi nei test i campi numerici arrotondati e otterrà risposte riproducibili di consenso e attesa per documenti di design, esempi SDK e prove di produzione senza erigere un servizio completo di rate limit.