Rate limit côté client : token bucket, leaky bucket et limites par hôte — le guide expert
Sommaire de l'article
- Introduction : pourquoi un client a besoin de son propre rate limit
- Les bases : qu'est-ce qu'un rate limit côté client et pourquoi le serveur ne suffit pas
- Plongée approfondie : les familles d'algorithmes et leurs mathématiques
- Méthode 1 : le token bucket en pratique — une implémentation sans pièges
- Méthode 2 : leaky bucket et gcra — quand on veut un flux régulier
- Méthode 3 : les limites par hôte — registre, hiérarchie et composition
- Méthode 4 : limiteur et rotation d'ip — comment prendre en compte le changement d'adresse dans le modèle
- Erreurs de conception typiques d'un rate limit côté client
- Outils et ressources pour l'implémentation
- Cas d'usage et scénarios d'application
- Faq : réponses aux questions difficiles
- Conclusion : que faire ensuite
Introduction : pourquoi un client a besoin de son propre rate limit
Imaginez que vous arrivez dans une banque avec un seul guichet ouvert et qu'un millier de personnes fassent la queue derrière vous. Vous pouvez pousser, crier, mais le débit du guichet ne va pas augmenter pour autant. Tout ce que vous pouvez faire, c'est soit avancer à un rythme raisonnable, soit essuyer un refus. Le rate limit côté serveur (la limitation de la fréquence des requêtes), c'est cet employé de guichet qui, un beau jour, cesse simplement de vous servir. Et le rate limit côté client, c'est votre décision personnelle de ne pas vous approcher du guichet plus souvent qu'il ne peut physiquement absorber.
Cet article est entièrement consacré aux algorithmes. Nous éviterons volontairement de répéter les contenus sur le traitement du code 429 et la mise en place d'un backoff exponentiel, et nous ne discuterons pas du nombre de threads à lancer. Ici, l'angle est différent : comment déterminer à l'avance, avant même d'envoyer une requête, si l'on peut l'envoyer maintenant, et si non, combien de temps attendre. C'est précisément cette mathématique qui sépare un client qui « essuie parfois des refus » d'un client qui travaille pendant des années avec la même API sans agacer ses propriétaires.
Voici ce que vous allez apprendre :
- comment sont conçues les quatre familles d'algorithmes — fixed window, sliding window, token bucket et leaky bucket — et en quoi elles diffèrent en termes de comportement, pas seulement de nom ;
- pourquoi le token bucket et GCRA (une variante du leaky bucket) sont devenus le standard de facto et comment les implémenter en une soirée sans erreurs d'arrondi ;
- comment construire une hiérarchie de limites : budget global, budget par hôte, par endpoint, par clé d'autorisation et par adresse IP sortante ;
- comment intégrer la rotation d'IP dans le modèle du limiteur, sans casser ni les quotas serveur ni votre propre télémétrie ;
- quelles erreurs de conception semblent inoffensives mais mènent à une attente infinie, à des « explosions » en début de minute et à des fuites de mémoire.
Nous vous parlerons sur un ton d'ingénieur-mentor : avec des formules, mais sans jargon prétentieux, avec des exemples, mais sans remplissage. Si vous écrivez un scraper, un SDK pour une API tierce, une intégration avec une marketplace ou un agrégateur qui interroge des centaines d'hôtes, ce guide mérite une place dans vos favoris.
Les bases : qu'est-ce qu'un rate limit côté client et pourquoi le serveur ne suffit pas
Deux regards sur un même problème
Le rate limit côté serveur protège l'infrastructure du propriétaire de l'API : il compte vos requêtes et répond par un refus quand le quota est épuisé. Le rate limit côté client résout un autre problème — ne pas aller jusqu'au refus. La différence est fondamentale. Le serveur réagit après coup : la requête est déjà partie, le canal est occupé, le journal est pollué, la réputation du client légèrement entachée. Le client, lui, agit de manière préventive : il connaît (ou estime) son budget et le dépense avec soin.
Pourquoi ne pas simplement se reposer sur les refus serveur et réessayer ? Parce que chaque tentative rejetée, c'est une connexion consommée, un token d'autorisation dépensé, une ligne dans le journal de sécurité d'autrui et, en règle générale, une dégradation de votre position dans les systèmes de protection adaptatifs. Un client qui respecte lui-même le rythme apparaît aux yeux du serveur comme un partenaire bien élevé. Un client qui « essaie jusqu'à ce qu'on le laisse passer » apparaît comme une source de problèmes. Devinez lequel sera le plus durement limité lors de la prochaine révision des politiques ?
Terminologie de base
- Rate (vitesse) — la fréquence de requêtes en régime établi, par exemple « dix requêtes par seconde ». C'est ce que le serveur est prêt à accepter indéfiniment.
- Burst (rafale) — le nombre de requêtes qu'on peut envoyer d'un coup, à la suite, sans attendre de rechargement. Le serveur tolère souvent de courtes rafales si la vitesse moyenne n'est pas dépassée.
- Fenêtre (window) — l'intervalle de temps sur lequel on compte les requêtes : une seconde, une minute, une heure, un jour.
- Quota — le nombre maximal de requêtes dans la fenêtre. Le quota divisé par la longueur de la fenêtre donne la vitesse moyenne.
- Clé de limite (limit key) — le critère selon lequel le serveur regroupe les requêtes : adresse IP, token, compte, paire « hôte plus endpoint ». Un même client tombe presque toujours sous plusieurs clés à la fois.
- Coût (cost) — le poids d'une requête. Certaines API comptent une recherche pour dix unités et la lecture d'une fiche pour une seule.
Le principe fondamental : le limiteur décide « quand », pas « combien »
Une confusion courante consiste à prendre le limiteur pour un sémaphore. Le sémaphore limite le nombre d'opérations simultanées et répond à la question « combien sont en vol en ce moment ». Le limiteur limite la fréquence et répond à la question « peut-on démarrer une opération de plus tout de suite, et si non, dans combien de millisecondes ». Ces deux mécanismes se complètent mais ne sont pas interchangeables. On peut garder une seule connexion et dépasser la limite si les requêtes sont courtes. On peut garder cent connexions et respecter la limite si les requêtes sont lentes.
Trois propriétés d'un bon limiteur côté client
- Prévisibilité. À entrée identique, il donne une réponse identique. Pas de « parfois il laisse passer un peu plus ».
- Coût faible. La décision se prend en temps constant et avec une mémoire constante par clé. Si vous avez des milliers d'hôtes, le limiteur ne peut pas stocker l'historique de toutes les requêtes.
- Équité. Si plusieurs tâches attendent une autorisation, elles l'obtiennent dans l'ordre de la file, et non selon « qui s'est réveillé au meilleur moment ».
Gardez ces trois critères en tête : c'est sur eux que nous comparerons les algorithmes dans la section suivante.
Plongée approfondie : les familles d'algorithmes et leurs mathématiques
Fixed window — le compteur honnête mais sournois
La variante la plus simple : on divise le temps en fenêtres de longueur fixe, on tient un compteur par fenêtre, et quand le quota est atteint, on attend le début de la fenêtre suivante. En mémoire : un nombre et un horodatage par clé. On croirait l'idéal.
Le problème s'appelle l'effet de bord de fenêtre. Si le quota est de cent requêtes par minute, le client peut envoyer cent requêtes dans la dernière seconde d'une fenêtre et cent autres dans la première seconde de la suivante. Du point de vue du client, tout est légitime : exactement cent dans chaque fenêtre. Du point de vue du serveur, deux cents requêtes sont arrivées en deux secondes — deux fois au-dessus de toute interprétation raisonnable de la limite. Si le serveur compte en fenêtre glissante (et la plupart des serveurs modernes le font), vous recevrez un refus tout en vous croyant sincèrement innocent.
Le second fléau, c'est la synchronisation des rafales. Tous vos workers se « réveillent » en même temps au début de la minute, parce que c'est à ce moment que le compteur est remis à zéro. Cela crée des pics de charge sur le réseau, sur le proxy et sur le serveur cible.
Sliding window log — précis, mais coûteux
On stocke les horodatages de toutes les requêtes du dernier intervalle. Avant l'envoi, on élimine les plus anciens et on compte ceux qui restent. Suivi absolument précis, aucun effet de bord. Mais la mémoire croît linéairement avec le quota : avec un quota de dix mille requêtes par heure, vous stockez dix mille horodatages pour chaque clé. Pour un seul hôte, c'est acceptable ; pour mille hôtes, non.
Sliding window counter — le compromis
On stocke deux compteurs : celui de la fenêtre courante et celui de la fenêtre précédente. L'estimation de la charge, c'est le compteur courant plus le compteur précédent multiplié par la fraction de la fenêtre précédente qui tombe encore dans l'intervalle glissant. Si 20 % de la minute courante sont écoulés, on prend 80 % du compteur précédent. C'est une approximation, mais elle lisse très bien la frontière et ne demande que deux variables. Beaucoup d'implémentations serveur utilisent exactement ce procédé, donc l'imiter côté client est un bon moyen de « penser comme le serveur ».
Token bucket — le seau à jetons
Imaginez un seau d'une capacité de B jetons. Chaque seconde, r jetons y tombent, les surplus débordent. Pour envoyer une requête de coût c, il faut prélever c jetons. S'il n'y en a pas — attendre qu'il s'en accumule.
Deux paramètres donnent deux propriétés indépendantes. Le paramètre r est la vitesse en régime établi : quelle que soit votre attente, le débit à long terme ne dépassera pas r requêtes par seconde. Le paramètre B est la rafale maximale : après une période d'inactivité, on peut envoyer B requêtes d'un coup. Cela correspond parfaitement à la manière dont sont formulées les politiques serveur réelles : « pas plus de cent par minute, pas plus de dix d'un coup ».
Le détail clé de l'implémentation, c'est le rechargement paresseux. Pas besoin d'un thread d'arrière-plan qui ajoute des jetons chaque seconde. Il suffit, à chaque appel, de calculer le temps écoulé depuis le dernier appel et d'ajouter la quantité correspondante : tokens = min(B, tokens + elapsed * r). Deux nombres par clé, un calcul en temps constant. Conforme à 100 % au critère de faible coût.
Leaky bucket — le seau percé
Ici la métaphore est inversée : les requêtes se déversent dans le seau et s'écoulent par le trou du fond à vitesse constante r. Le seau déborde — la nouvelle requête est rejetée ou attend. La sortie est toujours régulière : aucun pic, strictement une requête toutes les 1/r secondes. Si le serveur ne tolère pas les rafales, ou si vous voulez un profil de trafic le plus lisse possible, c'est votre choix.
Il existe deux interprétations du leaky bucket. La première, comme une file : les requêtes sont réellement placées dans un tampon, et un processus séparé les libère au rythme du minuteur. La seconde, comme un compteur : on vérifie simplement si un seau imaginaire déborderait, et on laisse passer ou non. La seconde interprétation s'appelle dans les télécommunications GCRA (Generic Cell Rate Algorithm) et elle est mathématiquement équivalente au token bucket avec une autre paramétrisation. C'est une observation importante : si vous avez déjà implémenté le token bucket, vous savez aussi faire le leaky bucket.
GCRA : un seul horodatage au lieu d'un compteur
GCRA stocke une seule valeur — TAT (theoretical arrival time, heure d'arrivée théorique) : le moment avant lequel la prochaine requête « idéale » ne devrait pas arriver. Paramètres : intervalle d'émission T = 1/r et tolérance τ, égale à (B − 1) * T. L'algorithme :
- On récupère l'heure actuelle now.
- Si TAT est inférieur à now, on considère TAT égal à now (le seau est vide depuis longtemps).
- Si TAT − τ est supérieur à now — la requête est arrivée trop tôt ; le temps d'attente vaut TAT − τ − now.
- Sinon, on autorise la requête et on avance TAT de T.
Un seul nombre par clé, pas de compteurs flottants qui dérivent progressivement. C'est pour cette raison que GCRA est l'algorithme préféré des limiteurs distribués : son état se stocke facilement dans un seul champ clé-valeur et se met à jour de manière atomique.
Tableau comparatif en mots
- Fixed window : mémoire minimale, précision faible, rafales aux frontières, ne convient que comme sécurité brute.
- Sliding log : précision absolue, mémoire linéaire en fonction du quota, adapté à quelques clés avec de petits quotas.
- Sliding counter : deux variables en mémoire, précision approximative, reproduit bien la logique serveur.
- Token bucket : deux variables en mémoire, contrôle explicite des rafales, standard des SDK clients.
- Leaky bucket / GCRA : une seule variable en mémoire, sortie parfaitement régulière, standard des systèmes distribués.
À propos des horloges : monotonie et dérive
Tous les algorithmes reposent sur « l'heure actuelle ». Utilisez une horloge monotone (monotonic clock), pas l'heure système. L'heure système peut sauter en arrière lors d'une synchronisation, et votre limiteur croira qu'un nombre négatif de secondes s'est écoulé, remettra le rechargement à zéro ou, au contraire, produira une rafale gigantesque. L'horloge monotone ne recule jamais. Seule exception : le limiteur distribué dans un stockage commun, où l'heure est prise côté stockage et non sur les clients, afin de ne pas dépendre du décalage entre machines.
Méthode 1 : le token bucket en pratique — une implémentation sans pièges
Étape 1. Choix des paramètres
Traduisez la politique serveur en paire (r, B). Si la documentation dit « cent requêtes par minute », la vitesse de base est r = 100/60 jetons par seconde. La capacité B est une décision séparée. Pour une API inconnue, un choix sûr est B entre cinq et dix pour cent du quota de la fenêtre, soit cinq à dix jetons pour un quota de cent. Cela permet d'écouler rapidement une petite salve, sans créer de pics qu'un serveur à fenêtre glissante percevrait comme une violation.
Encore mieux : calculez avec une marge — utilisez 80 à 90 % de la vitesse déclarée. Les compteurs serveur, les latences réseau et les arrondis des deux côtés introduisent inévitablement des imprécisions, que la marge absorbe.
Étape 2. Structure de l'état
Pour chaque clé, stockez : tokens (nombre réel, quantité actuelle de jetons), last (horodatage monotone du dernier recalcul), rate, capacity. Protégez l'état par un mutex ou, en asynchrone, par une tâche unique arbitre à travers laquelle passent toutes les requêtes de jetons.
Étape 3. L'algorithme acquire(cost)
- On prend le verrou.
- now = monotonic() ; elapsed = now − last ; last = now.
- tokens = min(capacity, tokens + elapsed * rate).
- Si tokens ≥ cost : tokens −= cost ; on relâche le verrou ; on renvoie « zéro attente ».
- Sinon : wait = (cost − tokens) / rate ; on débite les jetons en négatif : tokens −= cost ; on relâche le verrou ; on renvoie wait.
- L'appelant dort wait secondes puis envoie la requête.
Faites attention au point cinq. Le débit en négatif est une réservation. Elle garantit l'équité : l'appel suivant verra un solde négatif et obtiendra une attente encore plus grande, c'est-à-dire qu'il se mettra dans la file derrière le précédent. Sans réservation, on tombe sur l'erreur classique : dix tâches voient simultanément zéro jeton, calculent toutes la même attente, se réveillent toutes en même temps et déclenchent la rafale que le limiteur était justement censé éviter.
Étape 4. Limiter la profondeur de réservation
La réservation en négatif peut aller à l'infini : si les tâches arrivent plus vite que les jetons ne se rechargent, la file d'attente grandit et le temps d'attente de la dernière tâche tend vers plusieurs heures. Introduisez un délai maximal (max_delay). Si le wait calculé dépasse ce seuil, ne réservez pas et renvoyez une erreur « limiteur surchargé ». Laissez le planificateur de tâches décider quoi faire : différer, baisser la priorité, basculer vers un autre hôte. C'est précisément le point où le limiteur côté client passe de frein passif à outil de gestion de la charge.
Étape 5. Coût pondéré
Autorisez des requêtes de coût différent. Les endpoints de recherche, les sélections massives, les opérations d'écriture coûtent généralement « plus cher » au serveur, et beaucoup d'API le reflètent dans leurs politiques. Si la documentation est muette, fixez le poids d'après vos propres observations du temps de réponse : une requête que le serveur traite longtemps mérite raisonnablement d'être considérée comme plus coûteuse. La formule d'attente ne change pas — le cost y entre simplement en facteur.
Étape 6. Préchauffage et démarrage à froid
La valeur initiale de tokens est une décision à part. Un seau plein au démarrage signifie une rafale immédiate de B requêtes dès que le processus démarre. Cela peut être indésirable si des dizaines de processus démarrent simultanément après un déploiement. Plus sûr : démarrer à zéro ou à la moitié de la capacité. Et si l'on sait que le serveur compte le quota sur une fenêtre non alignée sur votre démarrage, le démarrage à zéro est même plus honnête.
Liste de contrôle token bucket
- Horloge monotone utilisée.
- Rechargement paresseux, par différence de temps, sans minuteurs d'arrière-plan.
- Réservation en négatif pour une file équitable.
- max_delay présent et refus explicite en cas de saturation.
- Vitesse définie avec marge par rapport au serveur.
- Capacité limitée à une part raisonnable du quota de la fenêtre.
- Gestion du cost pour les requêtes pondérées.
- État initial qui ne crée pas de rafale au déploiement.
Méthode 2 : leaky bucket et GCRA — quand on veut un flux régulier
Quand préférer le leaky bucket
Le token bucket autorise les rafales. C'est pratique, mais dans certaines situations la rafale nuit en elle-même : le serveur réagit agressivement aux pics brefs, le canal proxy a une bande passante limitée, vous voulez que le profil de trafic ressemble à celui d'un client ordinaire et posé. Dans tous ces cas, il faut une sortie avec un intervalle entre requêtes strictement constant. C'est le leaky bucket.
Implémentation sous forme de file
La variante classique : un tampon de capacité fixe et un consommateur unique qui, toutes les T secondes, extrait un élément et l'envoie. Avantage : simplicité et lisibilité. Inconvénients : nécessite un thread ou une tâche dédiée, et si le consommateur s'arrête, le tampon « gèle ». Cette approche convient quand vous avez un pipeline explicite : une file de tâches dans laquelle les requêtes sont justement prélevées une par une.
Implémentation sous forme de GCRA
Pour la plupart des scénarios clients, l'interprétation par compteur est plus pratique. Nous avons décrit l'algorithme plus haut ; voyons comment fixer les paramètres. Si l'on veut un intervalle strict, on pose τ = 0 : la tolérance est nulle, et les requêtes passent au plus une fois toutes les T. Si l'on veut autoriser une petite rafale, on augmente τ. Ainsi une même implémentation couvre à la fois le leaky bucket strict et le token bucket. C'est pourquoi GCRA est un bon « moteur unique » pour une bibliothèque de limitation.
Procédure pas à pas de GCRA avec réservation
- Lire TAT pour la clé ; s'il n'existe pas, considérer TAT = now.
- new_TAT = max(TAT, now) + T * cost.
- allow_at = new_TAT − τ − T * cost ; c'est le moment où une requête de ce coût aurait pu être envoyée sans attente.
- Si allow_at ≤ now : écrire new_TAT, renvoyer « zéro attente ».
- Sinon : wait = allow_at − now ; si wait dépasse max_delay — renvoyer un refus sans rien écrire ; sinon écrire new_TAT et renvoyer wait.
Dans un stockage distribué, les étapes un à cinq s'exécutent en une seule opération atomique — par exemple, un script côté stockage. Cela garantit que deux clients ne lisent pas le même TAT et ne « dupliquent » pas l'autorisation.
Équivalence et choix selon le type de charge
Il est utile de comprendre ceci : un token bucket de paramètres (r, B) et une GCRA de paramètres (T = 1/r, τ = (B − 1)/r) laissent passer exactement les mêmes séquences de requêtes. La différence ne tient qu'à la représentation de l'état. Donc la question « laquelle est la meilleure » se reformule ainsi : avez-vous besoin de rafales. Vous en avez besoin — mettez B supérieur à un. Vous n'en avez pas besoin — mettez B = 1 (τ = 0). Le reste est affaire de goût et de commodité de stockage.
Liste de contrôle leaky bucket / GCRA
- On a décidé s'il faut des rafales ou un flux strictement régulier.
- L'état est une seule valeur TAT par clé.
- L'opération lecture-vérification-écriture est atomique.
- max_delay présent et refus explicite.
- En variante distribuée, l'heure est prise côté stockage.
Méthode 3 : les limites par hôte — registre, hiérarchie et composition
Pourquoi « un limiteur pour tout » ne fonctionne pas
Si votre client ne s'adresse qu'à une seule API, un seul seau suffit. Mais les agrégateurs, les scrapers et les bus d'intégration interrogent des dizaines, voire des centaines d'hôtes, chacun avec sa propre politique. Une limite globale unique soit sous-utilise les hôtes rapides, soit surcharge les lents. Il faut un registre de limiteurs : une correspondance « clé de limite — état du seau », où la clé est construite à partir des caractéristiques de la requête.
Clé de limite : de l'hôte à l'endpoint
La clé minimale est le schéma plus l'hôte plus le port. Deux domaines d'un même propriétaire partagent souvent un quota, et les sous-domaines peuvent être comptés séparément ; il faut le savoir d'après la documentation ou le découvrir par observation. Une clé plus fine est l'hôte plus le modèle de chemin : par exemple, l'endpoint de recherche et l'endpoint de fiche produit ont des quotas différents. Plus fin encore : l'hôte plus le token d'autorisation, si le serveur compte le quota par clé d'API et que vous en avez plusieurs.
Règle pratique : construisez la clé à partir des mêmes critères que le serveur. Si le serveur compte par IP, votre IP sortante entre dans la clé. Si c'est par token — le token. Si c'est par les deux à la fois — il vous faut deux limiteurs, et la requête doit passer par les deux.
Hiérarchie des limites
Un système bien conçu dispose ses limiteurs en niveaux :
- Global — le budget commun du processus. Protège vos propres ressources : sockets, mémoire, bande passante.
- Par IP sortante — combien de requêtes partent via une adresse donnée. Niveau clé lorsqu'on travaille avec un pool d'adresses.
- Par hôte — la politique du serveur cible dans son ensemble.
- Par endpoint — des quotas distincts pour les méthodes coûteuses.
- Par identifiants — les quotas par token ou par compte.
La requête doit obtenir une autorisation à chaque niveau. C'est cela, la composition des limiteurs.
Composition sans blocage mutuel
L'approche naïve consiste à appeler acquire sur chaque limiteur en séquence et à additionner les attentes. Elle est incorrecte : le premier limiteur a déjà débité un jeton, et le second impose une attente de dix secondes, pendant lesquelles le jeton du premier « périmé » du point de vue de l'équité. Pire, deux tâches qui prennent les limiteurs dans un ordre différent peuvent se gêner indéfiniment.
Procédure correcte :
- Pour chaque limiteur, calculer l'attente sans débit (opération peek).
- Prendre le maximum des attentes — c'est le wait global.
- Si wait dépasse max_delay — refus.
- Sinon, effectuer le débit sur tous les limiteurs en leur transmettant le même moment d'arrivée now + wait, afin que chacun réserve la ressource pour ce même instant.
- Dormir wait puis envoyer.
Parcourez toujours les limiteurs dans un ordre fixe et identique (par exemple du plus global au plus étroit). Cela exclut les blocages mutuels lors d'accès concurrents.
Configuration et valeurs par défaut
Le registre doit pouvoir créer un limiteur pour un hôte encore jamais vu. Fixez un défaut conservateur : vitesse basse, rafale minimale. Pour les hôtes connus — une configuration explicite. Une bonne pratique est de stocker la politique sous forme déclarative : hôte ou modèle, rate, burst, cost par modèle de chemin, indicateur « compter par IP » et « compter par token ». Ainsi, quand la politique du serveur change, on modifie un fichier au lieu du code.
Éviction et fuites
Un registre de milliers d'hôtes est un candidat aux fuites de mémoire. Les hôtes inactifs depuis longtemps doivent être évincés. Comme l'état du seau après une longue inactivité sera de toute façon « plein » (ou le TAT dans le passé), l'éviction ne perd aucune information : au prochain appel, le limiteur sera recréé dans le même état. Utilisez un cache LRU avec une taille limitée, ou un nettoyage périodique des entrées dont le last est plus ancien que plusieurs fenêtres.
Liste de contrôle limites par hôte
- La clé de limite reprend les critères selon lesquels le serveur compte.
- Il existe des niveaux : global, IP, hôte, endpoint, identifiants.
- La composition se fait par peek — maximum — débit unique.
- Les limiteurs sont parcourus dans un ordre fixe.
- Défauts conservateurs pour les hôtes inconnus.
- Politiques externalisées dans la configuration.
- Registre borné en taille, avec éviction des clés inactives.
Méthode 4 : limiteur et rotation d'IP — comment prendre en compte le changement d'adresse dans le modèle
Pourquoi la rotation casse un limiteur naïf
Si le serveur cible compte le quota par IP, changer d'adresse change la clé de limite côté serveur. Un client naïf qui tient un seul compteur par hôte continuera de freiner après le changement d'IP, alors que le serveur voit déjà un « nouveau » visiteur. L'erreur inverse est plus dangereuse : le client remet tous les compteurs à zéro lors du changement d'IP, y compris ceux que le serveur compte par token ou par compte, et reçoit un refus pour un quota qui n'a rien à voir avec l'IP. Conclusion : la rotation ne doit affecter que le niveau « par IP sortante » de la hiérarchie, et les autres niveaux doivent vivre leur propre vie.
Deux modes de changement d'adresse
Dans l'infrastructure Proxeon, l'IP sur un port change soit par minuteur, soit par lien/API (données au 22.09.2026). Ce sont deux scénarios fondamentalement différents pour le limiteur. En changement par minuteur, le client ne maîtrise pas le moment : l'adresse change « de l'extérieur », et le limiteur par IP doit l'apprendre — via un événement, l'interrogation de l'adresse courante ou un planning si l'intervalle est connu. En changement par lien, le client déclenche lui-même le basculement et peut le synchroniser avec son propre état : attendre la fin des requêtes en vol, figer l'instant, créer une nouvelle clé « hôte plus époque d'IP ».
Quelle est la fréquence de chaque mode ? Selon les données au 14.11.2026, la part des changements d'IP par minuteur est de 51,1 %, le reste revenant au lien/API. Autrement dit, les deux stratégies se rencontrent à peu près à égalité, et un limiteur universel doit gérer les deux.
L'époque de l'adresse comme partie de la clé
Plutôt que de stocker l'IP elle-même dans la clé (on ne la connaît pas forcément à l'avance), utilisez une époque — un compteur incrémenté à chaque changement. La clé du niveau « par IP » devient la paire « port plus époque ». Au changement d'époque, l'ancienne clé n'est simplement plus utilisée et sera évincée plus tard par le registre ; la nouvelle est créée dans son état initial. Remarquez : l'état initial doit de nouveau être conservateur. Une nouvelle adresse est une inconnue pour le serveur, et la première chose qu'il verra sera votre profil de trafic.
Aligner la fenêtre du limiteur sur le minuteur de rotation
Selon les données au 14.11.2026, l'intervalle médian entre changements d'IP par minuteur est de 120 s, et 78,1 % des intervalles de minuteur sont un multiple exact d'une minute. C'est très pratique pour la conception. Si votre quota par hôte est de « N requêtes par minute par IP » et que l'adresse vit deux minutes, le budget d'une adresse vaut exactement deux fenêtres d'une minute. Le limiteur par IP peut fonctionner en token bucket à vitesse N/60, avec une capacité calculée pour ne pas dépasser 2N sur la durée de vie de l'adresse. L'important est de ne pas « rattraper » le retard : si vous avez envoyé peu pendant la première minute, vous ne pouvez pas envoyer deux fois plus pendant la seconde, car le serveur compte par fenêtre d'une minute, pas selon votre époque.
Pause pendant le basculement
Le changement d'adresse n'est pas instantané. Selon les données au 14.11.2026, la durée moyenne du changement lui-même — de la commande à la nouvelle adresse — est de 4,56 s, et 80,8 % des changements tiennent en 5 secondes. Qu'est-ce que cela signifie pour le limiteur ? Pendant le basculement, les requêtes iront soit par l'ancienne adresse, soit n'iront pas du tout. La bonne stratégie est de traiter le basculement comme un court intervalle de « drainage » : avant la commande de changement, le limiteur cesse de délivrer de nouvelles autorisations, attend la fin des requêtes en vol, effectue le changement, puis ouvre une nouvelle époque. Comme quatre basculements sur cinq se terminent en cinq secondes, il est raisonnable de prévoir un délai d'attente de la nouvelle adresse légèrement supérieur à cette valeur et de basculer sur le traitement d'exception si elle est dépassée.
Limitez aussi la fréquence de la commande de changement
Voici un point que l'on oublie souvent : la commande de changement d'IP est elle aussi une requête vers une API, et il faut aussi la limiter. Selon les données au 14.11.2026, la part des enregistrements en double pour les changements par lien (intervalle d'au plus 2 s, même IP) est de 1,2 %. Ce sont les traces de situations où le client a tiré le lien deux fois de suite : à cause d'une course entre workers, d'un retry sur timeout ou de l'absence d'un point unique de décision. La solution : un seau distinct de capacité un et d'intervalle strict (leaky bucket pur avec τ = 0) pour la commande de rotation, plus la déduplication : si un changement est déjà lancé, les autres workers attendent son résultat au lieu d'en lancer un nouveau. Le même principe que pour les hôtes cibles, appliqué cette fois à votre propre infrastructure.
Échelle et planification du budget
Pour saisir l'échelle : selon les données au 14.11.2026, sur une journée, 2 196 242 changements d'IP ont été effectués sur l'ensemble du réseau Proxeon, impliquant 7 924 ports proxy, avec une médiane de 95 IP uniques par modem et par jour. Pour le concepteur de limiteur, cela signifie qu'un port traverse des dizaines d'époques d'adresse par jour, et que l'état « par IP » doit être léger et rapidement évincé : stocker l'historique de toutes les époques n'a aucun sens, mais garantir un coût constant de création d'une nouvelle époque est indispensable.
Protocoles et adressage des ports
Un détail qui simplifie la configuration : dans Proxeon, le port SOCKS5 est égal au port HTTP plus un (données au 22.09.2026). Si vous utilisez les deux protocoles pour le même canal, le limiteur par IP doit les compter comme une seule clé, pas deux : l'adresse leur est commune, donc le budget aussi. Inscrivez dans le registre la normalisation : la clé est construite sur le port HTTP, et le port SOCKS5 y est ramené en soustrayant un.
Limiteur distribué par IP
Quand plusieurs processus ou machines passent par le même port, le seau doit être commun. Utilisez un stockage avec des opérations atomiques, stockez le TAT (GCRA) sous la clé « port plus époque plus hôte », mettez-le à jour par un script côté stockage et prenez aussi l'heure là-bas. Stockez également l'époque de manière centralisée et modifiez-la atomiquement en même temps que la commande de rotation — ainsi tous les processus basculent de manière cohérente sur la nouvelle clé.
Liste de contrôle du limiteur en cas de rotation
- La rotation n'affecte que le niveau « par IP », les autres niveaux ne sont pas réinitialisés.
- Les deux modes sont gérés : minuteur et changement par lien/API.
- La clé du niveau IP inclut l'époque de l'adresse.
- Une nouvelle époque démarre dans un état conservateur.
- La vitesse par IP est alignée sur la fenêtre serveur, pas sur la durée de l'époque.
- Pendant le basculement, la délivrance des autorisations est suspendue.
- La commande de rotation est elle-même limitée et dédupliquée.
- Les ports HTTP et SOCKS5 d'un même canal sont normalisés en une seule clé.
- Pour les scénarios multiprocessus, l'état est externalisé dans un stockage commun.
Erreurs de conception typiques d'un rate limit côté client
Erreur 1. Un sleep à la place d'un limiteur
« On mettra une pause de cent millisecondes entre les requêtes » — c'est la solution la plus fréquente et la plus fragile. Elle ne tient pas compte de la durée de la requête elle-même, ne fonctionne pas avec plusieurs workers, n'autorise pas les rafales là où elles sont permises et n'empêche pas leur apparition là où elles sont interdites. La pause n'est pas un limiteur, c'est son imitation.
Erreur 2. Compter par fenêtre quand le serveur compte en glissant
L'effet de bord de fenêtre a été décrit plus haut. Si vous n'êtes pas sûr de la méthode de comptage du serveur, supposez le pire — la fenêtre glissante — et utilisez un token bucket à capacité modeste.
Erreur 3. Course sans réservation
Plusieurs tâches calculent simultanément la même attente, s'endorment et se réveillent ensemble. Résultat : exactement la rafale que le limiteur devait empêcher. Le remède est la réservation (débit en négatif ou décalage du TAT) sous verrou.
Erreur 4. File d'attente infinie
Sans max_delay, la file grandit sans limite et les tâches attendent des minutes, voire des heures, en occupant mémoire et connexions. Un limiteur doit savoir refuser.
Erreur 5. L'horloge système
Un seul saut d'horloge lors d'une synchronisation — et le seau soit déborde, soit « gèle ». Uniquement une horloge monotone côté client ; uniquement l'heure du stockage dans la variante distribuée.
Erreur 6. Réinitialiser toutes les limites au changement d'IP
Les quotas par token et par compte ne dépendent pas de l'adresse. En les réinitialisant, vous violerez aussitôt une politique qui ne vous concernait même pas.
Erreur 7. Seau plein au démarrage
Des dizaines de processus démarrent avec des seaux pleins après un déploiement et déclenchent ensemble une rafale. Démarrez avec un seau vide ou ajoutez un délai aléatoire au démarrage.
Erreur 8. Registre sans éviction
Chaque nouvel hôte — une nouvelle entrée pour toujours. Après des semaines de fonctionnement, le processus garde en mémoire des limiteurs pour des hôtes dont il n'aura plus jamais besoin.
Erreur 9. Ignorer le coût de la requête
Si le serveur compte une recherche pour dix unités et vous pour une, votre limiteur laissera passer dix fois plus que nécessaire et sera sincèrement surpris du refus.
Erreur 10. Commande de rotation non limitée
Une répétition de la commande de changement d'adresse sur timeout ou depuis plusieurs workers entraîne des doublons et des basculements superflus. La commande est elle aussi une ressource ; donnez-lui un seau.
Outils et ressources pour l'implémentation
Bibliothèques prêtes à l'emploi par écosystème
- Go : le package golang.org/x/time/rate — implémentation de référence du token bucket avec les méthodes Allow, Reserve et Wait. La méthode Reserve renvoie un objet avec le temps d'attente et la possibilité d'annulation — exactement ce qu'il faut pour la composition.
- Python : la bibliothèque limits propose fixed window, sliding window et GCRA avec différents backends ; aiolimiter implémente le leaky bucket pour asyncio ; pyrate-limiter gère plusieurs fenêtres simultanément.
- Java/Kotlin : Bucket4j — un token bucket mature avec prise en charge des stockages distribués ; Resilience4j RateLimiter — une variante à cycles de rafraîchissement fixes.
- JavaScript/TypeScript : bottleneck sait limiter par groupes de clés et se regrouper en cluster via un stockage commun ; p-throttle — une variante minimaliste pour les cas simples.
- Rust : governor — une implémentation de GCRA avec ou sans clés, adaptée au code asynchrone.
- .NET : l'espace natif System.Threading.RateLimiting avec token bucket, sliding window et limiteurs partitionnés par clés.
Stockages pour l'état distribué
Redis et les stockages compatibles dotés de scripts côté serveur sont la référence pour une GCRA commune : une seule opération atomique, l'heure est prise par une commande du stockage, les clés avec TTL sont évincées automatiquement. Pour les scénarios au sein d'un même cluster d'applications, les mécanismes intégrés comme les caches distribués à opérations atomiques feront aussi l'affaire.
Outils d'observabilité
Un limiteur sans métriques est une boîte noire. Exportez : le nombre d'autorisations sans attente, la distribution des temps d'attente, le nombre de refus par max_delay, le remplissage actuel des seaux par clé, la fréquence des changements d'époque d'adresse. Un histogramme des attentes par hôte montrera immédiatement où la politique est trop stricte et où vous êtes à la limite.
Infrastructure d'adresses
Pour les scénarios avec rotation, il vous faudra un fournisseur offrant deux modes de changement d'adresse — par minuteur et par lien/API — et un adressage de ports prévisible. Chez Proxeon, les deux modes sont disponibles, et le port SOCKS5 est exactement à une unité du port HTTP (données au 22.09.2026), ce qui simplifie la normalisation des clés dans le registre des limiteurs.
À lire
- La description de GCRA dans les spécifications des standards télécoms — la source première pour le leaky bucket en tant que compteur.
- La documentation du package x/time/rate — une formulation exemplaire de la sémantique de Reserve et Wait.
- Les sections sur les limites dans la documentation des grandes API publiques — on y trouve toutes les modèles de comptage, et c'est le meilleur moyen d'apprendre à traduire une politique en paramètres de seau.
Cas d'usage et scénarios d'application
Scénario 1. Un agrégateur de prix sur des centaines d'hôtes
Objectif : parcourir régulièrement des fiches produit sur de nombreuses plateformes, chacune avec sa politique. Solution : un registre de limiteurs avec une clé « hôte plus modèle de chemin », un défaut conservateur pour les nouvelles plateformes, des politiques explicites pour les connues. Composition avec une limite globale sur le nombre de sockets. Le résultat visé par ces systèmes : une charge équilibrée sur tous les hôtes, sans temps morts sur les rapides et sans surcharge des lents ; quand la politique d'une plateforme change, on modifie une ligne de configuration. La grande leçon : passer d'une limite globale unique à une hiérarchie réduit fortement la part de requêtes envoyées « pour rien ».
Scénario 2. SDK pour une API partenaire avec quota par token et par IP
Objectif : une bibliothèque pour des clients qui ont plusieurs tokens et plusieurs adresses sortantes. Solution : deux niveaux de limiteurs — par token et par adresse — avec composition via peek et moment d'arrivée commun. Le planificateur choisit la paire « token plus adresse » avec la plus petite attente. Leçon : le limiteur devient un outil de routage : au lieu de « attendre », il indique « où envoyer pour ne pas attendre ».
Scénario 3. Un scraper sur des adresses mobiles avec rotation par minuteur
Objectif : parcourir des pages publiques via un pool de ports, les adresses changeant par minuteur. Solution : un limiteur par IP avec une clé « port plus époque », une vitesse alignée sur la fenêtre d'une minute de l'hôte cible. Comme, selon les données au 14.11.2026, l'intervalle médian du minuteur est de 120 s et 78,1 % des intervalles sont des multiples exacts d'une minute, le budget par époque se calcule comme un nombre entier de fenêtres d'une minute. Pendant le basculement — et 80,8 % des changements tiennent en 5 secondes (données au 14.11.2026) — la délivrance des autorisations est mise en pause avec un délai d'attente légèrement supérieur à ce seuil. Leçon : aligner la fenêtre du limiteur sur le rythme de rotation évite les rafales de « rattrapage » en début de nouvelle époque.
Scénario 4. Des workers avec rotation par lien et des commandes en double
Objectif : plusieurs workers partagent un port et chacun peut, si nécessaire, déclencher un changement d'adresse. Symptôme : des traces de commandes répétées dans les journaux. Solution : un point de rotation unique avec leaky bucket (τ = 0) et déduplication : si un changement est déjà en cours, les autres attendent sa fin. Selon les données au 14.11.2026, la part des enregistrements en double pour les changements par lien sur le réseau est de 1,2 % ; ce sont exactement les situations que supprime un point de décision unique. Leçon : il faut limiter non seulement les requêtes vers les API tierces, mais aussi les commandes vers votre propre infrastructure.
Scénario 5. Un moteur unique en GCRA pour tous les niveaux
Objectif : simplifier une base de code où coexistaient historiquement fixed window, pauses sleep et compteurs manuels. Solution : une seule implémentation GCRA de paramètres (T, τ), appliquée à tous les niveaux de la hiérarchie, avec état stocké dans un stockage commun pour les clés distribuées et en mémoire pour les locales. Leçon : une seule formule remplace un zoo de solutions et rend le comportement du système prévisible.
FAQ : réponses aux questions difficiles
En quoi le token bucket diffère-t-il fondamentalement du leaky bucket, s'ils sont équivalents ?
Ils sont équivalents comme objets mathématiques : avec la bonne correspondance des paramètres, ils laissent passer les mêmes séquences. La différence tient à l'intuition et au paramètre que l'on contrôle directement. Le token bucket raisonne en termes de « vitesse et rafale », le leaky bucket en termes d'« intervalle et tolérance ». Pour les politiques du type « N par minute, pas plus de M d'un coup », le premier est plus pratique ; pour « exactement une requête toutes les T », c'est le second. GCRA réunit les deux intuitions dans un seul état.
Comment choisir la capacité du seau si le serveur ne publie pas la rafale autorisée ?
Commencez par une petite part du quota de fenêtre — de l'ordre de cinq à dix pour cent — et observez. Si les refus sont absents et les temps d'attente élevés, augmentez prudemment. Souvenez-vous qu'un serveur à fenêtre glissante ne supporte pas les rafales dépassant le quota sur un court sous-intervalle ; la capacité ne doit donc jamais s'approcher du quota complet.
Un limiteur est-il nécessaire si je n'ai qu'un seul thread ?
Oui. Un seul thread avec des requêtes courtes dépasse facilement le quota : si la réponse arrive en vingt millisecondes, vous enverrez cinquante requêtes par seconde sans même y penser. Le limiteur est nécessaire quel que soit le nombre de threads ; il résout un autre problème que le sémaphore.
Comment limiter des requêtes de coût différent si le serveur les compte différemment ?
Transmettez cost à acquire. Les jetons sont débités proportionnellement, l'attente se calcule par la même formule. Si le coût est inconnu, estimez-le d'après le temps de réponse ou la taille de la réponse, et affinez-le au fil des observations. Mieux vaut surestimer que sous-estimer.
Que faire si une requête doit passer par cinq limiteurs donnant chacun une attente différente ?
Demandez d'abord à tous l'attente sans débit, prenez le maximum, puis débitez chez tous pour le même moment d'arrivée. Parcourez toujours les limiteurs dans le même ordre. Si le maximum dépasse le seuil — refus sans débit, sinon les ressources seront réservées « pour rien ».
Comment le limiteur doit-il réagir à un changement d'IP par minuteur si je ne connais pas le moment exact ?
Utilisez un événement ou l'interrogation de l'adresse courante, et si l'intervalle est connu — un planning avec marge. Chez Proxeon, le changement par minuteur et le changement par lien/API sont tous deux des modes standards (données au 22.09.2026), et si vous avez besoin d'une synchronisation précise, préférez le mode par lien : c'est vous qui déterminez le moment du changement et ouvrez une nouvelle époque dans votre registre précisément quand le basculement est confirmé.
Pourquoi ne peut-on pas réinitialiser toutes les limites après un changement d'adresse ?
Parce que le serveur peut compter le quota selon plusieurs critères à la fois. L'adresse a changé — le quota par IP repart de zéro, mais le quota par token, par compte ou par session continue de compter. En réinitialisant tout, vous violez les politiques qui ne dépendent pas de l'adresse. La rotation ne doit toucher que le niveau « par IP » de la hiérarchie.
Que vaut-il mieux pour un limiteur distribué — token bucket ou GCRA ?
GCRA. Il n'a qu'une seule valeur d'état, plus simple à mettre à jour de façon atomique et à stocker avec un TTL. Le token bucket nécessite deux valeurs et une logique de rechargement un peu plus complexe, ce qui complique le script atomique. Sémantiquement, les deux donnent le même résultat.
Comment vérifier que le limiteur fonctionne correctement avant la mise en production ?
Écrivez un test avec une horloge substituable : envoyez des requêtes à des moments donnés et comparez les décisions à une séquence de référence. Vérifiez les cas limites : temps nul, longue inactivité, arrivée simultanée de nombreuses requêtes, coût supérieur à la capacité (doit donner un refus explicite, et non une attente infinie). Testez séparément la composition : deux limiteurs à vitesses différentes, en vérifiant qu'aucun ne laisse passer plus que son quota.
Conclusion : que faire ensuite
Un rate limit côté client n'est pas un frein, c'est un système de gestion. Bien construit, un limiteur fait trois choses : il n'atteint pas le refus, il utilise uniformément le budget disponible et il indique au planificateur où et quand envoyer la requête suivante. Au fond, il n'y a qu'une seule formule, qu'il s'agisse de token bucket ou de GCRA, mais il faut l'entourer de discipline : horloge monotone, réservation sous verrou, délai maximal, hiérarchie des clés et éviction.
Résumé :
- Fixed window est simple mais sournois aux frontières ; préférez le token bucket ou GCRA.
- Le token bucket offre un contrôle séparé de la vitesse et de la rafale ; GCRA propose la même chose en un seul nombre d'état.
- La clé de limite reprend les critères selon lesquels le serveur compte ; les limiteurs se disposent en hiérarchie et se composent via peek — maximum — débit unique.
- La rotation d'adresse ne change que le niveau « par IP » ; la commande de rotation mérite elle aussi son propre seau.
- Les métriques d'attente et de refus sont le seul moyen honnête de savoir si votre politique correspond à celle du serveur.
Prochaines étapes pour vous : choisissez un moteur unique (nous conseillons GCRA), décrivez les politiques des hôtes connus dans la configuration, ajoutez un défaut conservateur, activez les métriques et passez les tests avec horloge substituable. Si vous travaillez via un pool d'adresses, ajoutez l'époque dans la clé et un seau distinct pour la commande de changement. Après cela, votre client apparaîtra à tout serveur comme l'invité le plus poli — celui à qui on ne refuse jamais rien.