Simulateur de Politique de Limite de Taux API

--- name: api-rate-limit-policy-simulator description: Simule les limites de débit API avant de les déployer - bucket à jetons, fenêtre fixe, journal glissant et compteur glissant, par client, endpoint, niveau ou global - contre un trafic généré ou enregistré avec des clients qui réessaient. Montre qui reçoit des 429 et pendant combien de temps, les rafales aux limites de fenêtre fixe, les troupeaux de nouvelles tentatives, les voisins bruyants, les clients abusifs qui passent encore et les pics au-delà de la capacité du backend. Inclut un simulateur Python hors ligne avec stdlib et --self-test. --- # Simulateur de politique de limite de débit API Vous aidez les ingénieurs backend et plateforme à choisir des limites de débit avec des preuves au lieu de chiffres arrondis. Une limite qui semble sûre sur le papier ("300 par minute par clé") peut encore laisser passer 1,8x cette valeur à une limite de fenêtre, limiter une application mobile dont des milliers d'utilisateurs partagent une seule clé API, libérer un troupeau de nouvelles tentatives à la seconde de réinitialisation, et ne rien faire contre un scraper qui reste juste en dessous. Vous décrivez les politiques et le trafic dans un petit fichier JSON, vous le rejouez, et vous lisez le résultat client par client et politique par politique. ## Fichiers dans cette compétence - `scripts/rate_sim.py` - simule les limiteurs à bucket à jetons, fenêtre fixe, journal glissant et compteur glissant, clés par client, endpoint, client+endpoint ou global, limités aux endpoints et aux niveaux de clients ; génère un trafic stable, de Poisson ou en rafales (ou rejoue une trace CSV), permet aux clients de réessayer immédiatement, avec backoff ou en respectant Retry-After, et rapporte les 429, les délais, les échecs, les comptages de fenêtres pires cas et observés, les pics vs capacité, les constats RL01-RL10 et un exemple de réponse 429 (Python 3.8+ bibliothèque standard uniquement) - `references/algorithms.md` - comment chaque algorithme se comporte, son pire cas, son coût mémoire et quand le choisir - `references/policy-design.md` - choisir les clés, les niveaux, les nombres, les en-têtes et les règles de nouvelle tentative des clients ; ce que signifient les codes de constat - `templates/rate-limit-review.md` - la revue à rendre - `examples/orders-api.json` - une API de commandes publique avec une fenêtre fixe par clé, une limite de connexion et une fenêtre fixe globale ; cinq clients incluant une clé mobile partagée, un partenaire en volume, un scraper et un bourreur d'identifiants - `examples/orders-api-report.md` - la sortie réelle du simulateur sur ce fichier - `examples/orders-api-tuned.json` - la même API après les corrections : buckets à jetons par niveau, un bucket à jetons global dimensionné à la capacité ## Flux de travail ### 1. Collecter les entrées Demandez : les limites telles que configurées aujourd'hui ou proposées (algorithme, clé, nombres, quels endpoints et quels clients), où elles sont appliquées (passerelle, CDN, application, Redis), la capacité du backend en requêtes par seconde qu'il peut soutenir, et le trafic : les plus grands clients légitimes et leur forme (stable, travaux par lots en rafales, nombreux utilisateurs derrière une clé ou une IP NAT), comment chacun réessaie, et tout abus vu dans les journaux. Les journaux d'accès réels valent mieux que des suppositions : exportez `t,client,endpoint` pour 5 à 15 minutes chargées et passez-le avec `--trace`. ### 2. Exécuter le simulateur ``` python3 scripts/rate_sim.py examples/orders-api.json python3 scripts/rate_sim.py examples/orders-api-tuned.json python3 scripts/rate_sim.py policies.json --trace access-sample.csv python3 scripts/rate_sim.py policies.json --json python3 scripts/rate_sim.py --self-test ``` Sortie 0 = aucun constat élevé, 1 = constats élevés (clients légitimes limités ou trafic admis au-dessus de la capacité), 2 = mauvaise entrée. Sans shell, raisonnez avec `references/algorithms.md` : par clé, comparez le pic du client par fenêtre avec la limite, le pire cas (2x la limite pour les fenêtres fixes, rafale + débit pour les buckets) avec la capacité, et réfléchissez à ce que chaque client fait après un 429. ### 3. Lire le résultat - Clients légitimes d'abord (RL01) : toute requête échouée ou retardée, et combien de temps ils ont attendu. Une clé partagée par les utilisateurs d'une application nécessite son propre niveau ou une clé par utilisateur. - Capacité (RL03) : le pic admis par seconde vs ce que le backend soutient. Une limite globale est la seule chose qui protège la capacité ; les limites par clé se multiplient par le nombre de clés. - Forme (RL04, RL10) : les fenêtres fixes laissent passer les rafales aux limites et distribuent toute une fenêtre à la fois ; les nouvelles tentatives sans gigue reviennent toutes dans la même seconde. - Abus (RL02) : un scraper sous la limite par clé n'est pas arrêté par les limites ; il nécessite une détection, une authentification ou une limite par endpoint. - Nouvelles tentatives (RL05) : des tentatives par requête logique au-dessus de 1,5 signifie que les clients amplifient la charge lorsqu'ils sont limités. ### 4. Ajuster et relancer Changez une chose à la fois et relancez avec le même trafic : passez les fenêtres fixes à des buckets à jetons ou des compteurs glissants, ajoutez des niveaux avec `clients` / `exclude_clients`, dimensionnez le bucket global à la capacité (débit = rps soutenable, rafale = ce que le backend absorbe pendant une seconde), ajoutez des limites par endpoint pour la connexion et les appels coûteux, et convenez d'un rythme avec les partenaires par lots. Utilisez `references/policy-design.md` pour les nombres. ### 5. Livrer Remplissez `templates/rate-limit-review.md` : verdict, un tableau avant/après par client, les changements de politique en configuration, la réponse 429 et les en-têtes, les conseils aux clients (Retry-After, backoff avec gigue, nombre maximal de nouvelles tentatives) et ce qu'il faut surveiller après le déploiement. ## Exemple de résultat Sur `examples/orders-api.json`, la clé partagée `mobile-app` atteint la fenêtre de 300/minute par clé : 1 042 de ses 1 839 requêtes réussissent seulement après avoir attendu jusqu'à 60 s (RL01, élevé). Respecter Retry-After sans gigue libère 289 nouvelles tentatives à la seconde 240, donc le trafic admis atteint un pic de 313 req/s contre une capacité de 80 (RL03, RL10). La fenêtre fixe par clé laisse passer 544 requêtes en une minute glissante (1,8x, RL04), et le scraper obtient encore 45 % de ses appels réussis tandis que ses nouvelles tentatives immédiates le poussent à 2,67 tentatives par requête. La limite de connexion arrête le bourreur d'identifiants (40 sur 480). Dans `examples/orders-api-tuned.json` (buckets à jetons par niveau, bucket global 50 req/s + 30 de rafale, rythme partenaire à 2 req/s), les clients légitimes ne voient aucun 429, le pic est de 27 req/s et seuls les constats du scraper restent. ## Règles - Simulez avec le trafic que vous avez réellement (ou une trace), pas une moyenne ; les rafales et les nouvelles tentatives sont là où les limites échouent. - Ne qualifiez jamais une limite de sûre pour la capacité à moins qu'une limite globale ne borne le total. - Traitez les requêtes retardées des clients légitimes comme un préjudice, pas comme un succès. - Retournez toujours 429 avec Retry-After, ajoutez de la gigue, et dites aux clients comment reculer. - Les limites de débit ne sont pas une protection contre les abus à elles seules ; dites quand une authentification, une détection de bot ou des règles WAF sont nécessaires. - Les résultats sont un modèle : confirmez avec les métriques de la passerelle après le déploiement et gardez les limites dans la configuration, pas dans le code.