Rate Limiting Atomico per API con Redis e Lua: Strategie per Sviluppatori

Per la maggior parte delle API pubbliche, un contatore a finestra scorrevole è la scelta predefinita corretta: offre un’accuratezza quasi esatta con memoria costante per client. Si ricorre a un token bucket quando è necessario consentire burst controllati, o a un leaky bucket quando un servizio downstream fragile richiede uno svuotamento rigoroso e costante. La scelta si basa sul budget di memoria, sulla tolleranza ai burst e sulla fragilità dei sistemi downstream, e si implementa la logica di applicazione con script Redis e Lua atomici supportati dagli header RateLimit.

---

TL;DR:

• Un contatore a finestra scorrevole bilancia accuratezza ed efficienza della memoria, rendendolo adatto per API pubbliche generiche con traffico elevato.
• L’implementazione atomica dei rate limiter con script Lua Redis previene le race condition e mantiene la coerenza tra più istanze dell’applicazione.
• Utilizzare una velocità di riempimento leggermente superiore al traffico P99 normale e impostare la capacità del bucket per gestire da 5 a 10 secondi di traffico burst senza falsi positivi.
• Informare i client dei loro limiti di velocità tramite header standardizzati e fornire risposte Retry-After chiare per aiutarli a gestire i tentativi in modo efficace.
• Applicare l’applicazione dei limiti sia a livello edge (come NGINX) che a livello applicazione, e scegliere gli algoritmi in base ai vincoli di memoria, alla tolleranza ai burst e alla fragilità dei sistemi downstream.

---

Indice

• Come si confrontano i principali algoritmi di rate limiting
• Note di implementazione per ogni algoritmo
• Costruire limiter che reggono su più istanze
• Scegliere l’algoritmo giusto per il proprio endpoint
• Comunicare i limiti ai client tramite header
• Impostare tassi di riempimento, capacità e avvisi
• Dove questi pattern si manifestano in produzione
• Equità, prevenzione degli abusi ed etica del throttling
• Perché default sensati la salvano da se stesso in seguito
• Dove leggere di più sugli standard di rate limiting
• Fonti
• FAQ

Come si confrontano i principali algoritmi di rate limiting

Cinque algoritmi coprono quasi ogni caso d’uso in produzione; ognuno si colloca in un punto diverso del compromesso tra costo della memoria, tolleranza ai burst e accuratezza.

• Finestra fissa (Fixed window): un contatore per slot temporale, il più economico da eseguire, ma consente un burst vicino al confine della finestra.
• Registro a finestra scorrevole (Sliding window log): memorizza il timestamp di ogni richiesta, fornendo conteggi esatti a costo di una memoria che cresce con il volume delle richieste.
• Contatore a finestra scorrevole (Sliding window counter): combina i conteggi della finestra corrente e di quella precedente in una stima ponderata, mantenendo la memoria costante per client.
• Token bucket: tiene traccia di un conteggio di token e di un timestamp di riempimento, permettendo ai client di spendere la capacità accumulata in brevi burst.
• Leaky bucket: processa le richieste a una velocità di uscita fissa indipendentemente da come arrivano, livellando il traffico per downstream fragili.

La finestra fissa è adatta per limiti interni a basso rischio, il registro a finestra scorrevole per endpoint ad alto rischio e basso volume come il login, il contatore a finestra scorrevole per API pubbliche generiche, il token bucket per API rivolte agli sviluppatori che necessitano di margine per i burst, e il leaky bucket per le code davanti a backend sensibili al rate.

Note di implementazione per ogni algoritmo

Ogni algoritmo richiede una forma di stato specifica e comporta un proprio costo di runtime, quindi sceglierne uno significa in realtà scegliere una struttura dati.

La finestra fissa memorizza un singolo contatore chiavato per ID client e bucket temporale, incrementato a ogni richiesta e azzerato quando il bucket scade. È semplice da ragionare, ma un client può inviare un intero quota di richieste alla fine di una finestra e un’altra quota intera all’inizio della successiva, raddoppiando il rate effettivo per un breve periodo. Questo la rende accettabile per limiti grossolani a basso rischio, ma rischiosa per qualsiasi cosa sensibile alla sicurezza.

Il registro a finestra scorrevole mantiene un insieme ordinato di timestamp delle richieste per client, rimuovendo quelli più vecchi della finestra a ogni controllo. È esatto, poiché conta richieste reali anziché stime, ma la memoria cresce con il volume delle richieste, rendendolo costoso per client ad alto traffico.

Il contatore a finestra scorrevole evita quel costo memorizzando solo due contatori, uno per la finestra corrente e uno per la precedente, e calcolando una stima ponderata in base a quanto si è addentrati nella finestra corrente. Questo è l’approccio su cui si basa il rate limiting edge di Cloudflare, che abbina controlli a livello PoP a contatori centralizzati per supportare traffico su larga scala mantenendo la memoria costante.

Il token bucket memorizza un conteggio di token e un timestamp dell’ultimo rifornimento per client. A ogni richiesta, si calcolano i token guadagnati dall’ultimo controllo, si limita il totale alla capacità del bucket, e se ne deduce uno se disponibile. Rifornimento e consumo devono avvenire atomicamente, altrimenti due richieste concorrenti potrebbero leggere lo stesso conteggio di token e avere entrambe successo quando ne dovrebbe riuscire solo una.

Il leaky bucket ha due varianti: una di policing che scarta semplicemente le richieste che superano il tasso di drenaggio, e una di shaping che le accoda per un’elaborazione successiva. Ricorra a questo quando l’endpoint si trova davanti a un database o servizio di terze parti che non può assorbire picchi.

Suggerimento Pro: Avvolga la logica di rifornimento e consumo in un unico script Lua invece di chiamate GET e SET separate; una sequenza lettura-poi-scrittura su due round trip è esattamente il tipo di race condition che gli script atomici esistono per prevenire.

Costruire limiter che reggono su più istanze

Un rate limiter che funziona in un processo ma fallisce sotto concorrenza è peggio di non averne affatto, poiché dà un falso senso di protezione.

1. Memorizzare i contatori in Redis in modo che ogni istanza dell’applicazione legga e scriva lo stesso stato invece di divergere.
2. Utilizzare gli script Redis Lua EVAL per combinare i passaggi di lettura, rifornimento e consumo in un’unica operazione atomica, come raccomandato dal tutorial sul rate limiting di Redis, poiché sia MULTI/EXEC che il locking ottimistico lasciano spazi vuoti sotto alta concorrenza.
3. Per servizi ad alto volume, aggregare i conteggi localmente per istanza o per punto di presenza prima di sincronizzarli con uno store centrale, invece di interrogare Redis a ogni singola richiesta.
4. Aggiungere un leaky bucket a livello di gateway, ad esempio in NGINX, come muro esterno contro il traffico abusivo, e mantenere limiti più fini per chiave a livello di applicazione per i client legittimi ma con traffico a burst.
5. Decidere fail-open versus fail-closed per endpoint prima che un incidente forzi la decisione: fail open sugli endpoint pubblici a prevalenza di lettura in modo che un’interruzione di Redis non abbatta l’intera API, e fail closed sugli endpoint di autenticazione o pagamento dove lasciare passare traffico illimitato è il rischio maggiore.

Pro Tip: Registrare separatamente ogni evento fail-open dal traffico normale; un’interruzione di Redis che disabilita silenziosamente i vostri rate limit è il tipo di guasto che emerge solo in una revisione post-incidente.

Scegliere l’algoritmo giusto per il proprio endpoint

Valutare quattro assi prima di scrivere qualsiasi codice: quanta memoria si può spendere per client, se i burst sono legittimi o una minaccia, quanto è fragile il sistema a valle, e se sono accettabili conteggi esatti o stime.

• API pubbliche per sviluppatori: sliding window counter o token bucket, poiché entrambi tollerano burst ragionevoli senza l’overhead del conteggio esatto.
• Endpoint di pagamento e autenticazione: sliding window log per l’esattezza, o un default fail-closed che tende a rifiutare le richieste invece di lasciare passare traffico sospetto.
• Flussi limitati a valle: leaky bucket, così la velocità di output non supera mai ciò che il sistema fragile dietro di esso può gestire.
• Traffico interno ad alto volume e basso rischio: fixed window, scambiando burst ai confini per l’implementazione più semplice possibile.

Se non si sa rispondere a cosa succede quando Redis è irraggiungibile, il design non è finito, indipendentemente dall’algoritmo scelto.

Comunicare i limiti ai client tramite header

I server dovrebbero dire ai client dove si trovano prima che questi inizino a indovinare. Una bozza IETF emergente definisce gli header RateLimit e RateLimit-Policy, con RateLimit-Limit e RateLimit-Reset marcati come obbligatori e RateLimit-Remaining raccomandato ma opzionale. Molti provider principali usano ancora i vecchi header vendor-prefixed X-RateLimit-*, che precedono la bozza, quindi supportare entrambi durante un periodo di transizione è ragionevole.

• Restituire RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset su ogni risposta, non solo sui rifiuti.
• Inviare un header Retry-After ogni volta che si rifiuta una richiesta con stato 429.
• Trattare questi header come suggerimenti piuttosto che garanzie, poiché il carico può spostarsi tra il momento in cui un header viene emesso e la richiesta successiva.
• Sul client, usare exponential backoff con full jitter invece di un ritardo fisso, che distribuisce i tentativi invece di creare storm di retry sincronizzati.

Un riferimento di produzione riporta che il contatore a finestra scorrevole di Cloudflare funziona con un tasso di errore estremamente basso su volumi di richieste molto elevati, a dimostrazione che l’approccio basato su stime regge su larga scala senza sacrificare un’accuratezza significativa.

Impostazione delle velocità di riempimento, capacità e avvisi

Estragga i valori p95 e p99 delle richieste al secondo per client dalla sua pipeline di metriche esistente, quindi imposti la velocità di riempimento (refill rate) leggermente al di sopra del p99 sostenuto in modo che l’utilizzo normale non attivi mai il limiter. Dimensioni la capacità del bucket per assorbire circa 5-10 secondi di burst p99 previsti, il che copre un client che riprova un batch job senza penalizzare tutti gli altri.

• Monitori il tasso di 429 e il rapporto di throttling come quota delle richieste totali, non solo come conteggi assoluti.
• Tracci la latenza delle richieste separatamente per il traffico throttled e non throttled, poiché un picco nel primo spesso precede un picco nel secondo.
• Imposti avvisi sui fallimenti o timeout dei comandi Redis legati al rate limiter, poiché un fallimento silenzioso lì vanifica l’intero sistema.
• Distribuisca le modifiche ai limiti prima su una piccola percentuale di traffico, per poi ampliare una volta che il tasso di 429 e la latenza appaiono entrambi stabili.

Pro Tip: Quando stringe un limite, annunci il cambiamento e i nuovi header ai consumatori dell’API prima del rilascio. Un 429 inaspettato senza contesto genera più ticket di supporto dell’abuso che voleva fermare.

Dove questi pattern si manifestano in produzione

La maggior parte degli stack di produzione suddivide l’applicazione (enforcement) su due livelli invece di affidarsi a uno solo.

• Edge: una configurazione NGINX leaky-bucket assorbe il traffico abusivo e lo scraping evidente prima che raggiunga mai i server applicativi.
• Applicazione: uno script Lua Redis che implementa token bucket o sliding window counter applica limiti per chiave (per-key), generalmente fallendo in modalità open (fail-open) sugli endpoint di sola lettura così che un’interruzione della cache non abbatta l’API.
• API pubbliche per sviluppatori: sliding window counter o token bucket, tarati sul piano tariffario (plan tier) del client.
• Endpoint di autenticazione: limiti rigorosi, a bassa capacità, spesso fail-closed, poiché lasciare passare traffico eccessivo qui è un rischio per la sicurezza piuttosto che un inconveniente.
• Processori di webhook: leaky bucket o un limiter basato su coda, poiché i retry dal servizio mittente devono essere smussati piuttosto che rifiutati tout court.

Equità, prevenzione degli abusi ed etica del throttling

Il rate limiting è un meccanismo di equità tanto quanto tecnico: decide quali richieste vengono servite quando la domanda supera la capacità, e questa decisione impatta utenti e aziende reali. Un limite impostato troppo aggressivamente può escludere clienti legittimi durante un picco di traffico, mentre un limite troppo lassista permette a un piccolo numero di client abusivi di degradare il servizio per tutti gli altri.

Pubblica i suoi limiti e il ragionamento dietro di essi nella documentazione dell’API, poiché uno throttling non documentato appare arbitrario ed erode la fiducia degli sviluppatori che costruiscono sopra la sua API. Applichi i limiti in modo coerente tra client simili invece di favorire silenziosamente alcuni account, ed sia esplicito nei suoi termini di servizio su cosa conta come traffico abusivo, come credential stuffing o scraping, rispetto al normale uso ad alto volume da parte di un cliente pagante.

Quando si limita un client, la risposta stessa ha importanza sia etica che tecnica. Un codice 429 con header chiari e un valore Retry-After rispetta il tempo del client e permette al suo sistema di riprendersi con eleganza, mentre un rifiuto silenzioso o un errore vago lo costringono a indovinare. Per le piattaforme multi-tenant, isoli i limiti per tenant in modo che un picco di traffico di un cliente, sia legittimo che malevolo, non possa esaurire la quota di un altro tenant che condivide la stessa infrastruttura. Quell’isolamento è spesso la differenza tra un incidente minore e una violazione della fiducia con i clienti paganti che non hanno fatto nulla di male.

Perché i default sensati la salvano da se stessa in seguito

L’algoritmo che sceglie importa meno che sceglierne uno e monitorarlo onestamente. Lo sliding window counter e il token bucket coprono la maggior parte dei casi con un overhead operativo minimo, ma retry ingenui del client senza backoff o consapevolezza degli header causeranno comunque interruzioni. Mantenga i team di prodotto, SDK e infrastruttura in comunicazione tra loro sui limiti prima che i clienti lo scoprano nel modo più duro.

— Bitblade

Dove leggere di più sugli standard di rate limiting

Inizi con la bozza IETF sull’header RateLimit per lo standard emergente, poi consulti il tutorial sul rate limiter di Redis per il codice di implementazione.

Fonti

• Build 5 Rate Limiters with Redis: Fixed Window, Sliding Window, Token Bucket, and Leaky Bucket
• draft-ietf-httpapi-ratelimit-headers-05
• API Rate Limiting Strategies: 2026 Engineering Reference
• Counting things: a lot of different things

Consigliati

• API Blockchain a confronto: 6 tipi e quando usarli
• Rilascio Beta API RPC — Porta il tuo viaggio crypto al livello successivo
• Casi d’uso di un’API Blockchain
• Perché le API Blockchain sono importanti nel panorama digitale