API-Ratenlimit-Richtlinien-Simulator

--- name: api-rate-limit-policy-simulator description: Simuliert API-Rate-Limits, bevor Sie sie ausliefern - Token-Bucket, Fixed Window, Sliding Log und Sliding Counter, pro Client, Endpoint, Tier oder global - gegen generierten oder aufgezeichneten Traffic mit wiederholenden Clients. Zeigt, wer 429er erhält und wie lange, Fixed-Window-Grenzbursts, Retry-Herden, laute Nachbarn, missbräuchliche Clients, die trotzdem durchkommen, und Spitzen über der Backend-Kapazität. Enthält einen Offline-Stdlib-Python-Simulator mit --self-test. --- # API-Rate-Limit-Policy-Simulator Sie helfen Backend- und Plattform-Ingenieuren, Rate-Limits mit Beweisen statt runden Zahlen zu wählen. Ein Limit, das auf dem Papier sicher aussieht ("300 pro Minute pro Schlüssel"), kann trotzdem das 1,8-fache an einer Fenstergrenze durchlassen, eine mobile App drosseln, deren tausende Benutzer einen API-Schlüssel teilen, eine Herde von Retries in der Reset-Sekunde freigeben und nichts gegen einen Scraper tun, der knapp darunter bleibt. Sie beschreiben die Richtlinien und den Traffic in einer kleinen JSON-Datei, spielen sie ab und lesen das Ergebnis Client für Client und Richtlinie für Richtlinie. ## Dateien in diesem Skill - `scripts/rate_sim.py` - simuliert Token-Bucket-, Fixed-Window-, Sliding-Log- und Sliding-Counter-Limiter, die nach Client, Endpoint, Client+Endpoint oder global verschlüsselt sind, auf Endpoints und Client-Tiers begrenzt; generiert gleichmäßigen, Poisson- oder Burst-Traffic (oder spielt eine CSV-Spur ab), lässt Clients sofort, mit Backoff oder durch Beachtung von Retry-After wiederholen und meldet 429er, Verzögerungen, Fehler, Worst-Case- und beobachtete Fensterzahlen, Spitzen vs. Kapazität, Befunde RL01-RL10 und eine Beispiel-429-Antwort (nur Python 3.8+ Standardbibliothek) - `references/algorithms.md` - wie sich jeder Algorithmus verhält, sein Worst Case, Speicherkosten und wann man ihn wählt - `references/policy-design.md` - Wahl von Schlüsseln, Tiers, Zahlen, Headern und Client-Retry-Regeln; was die Befundcodes bedeuten - `templates/rate-limit-review.md` - die Überprüfung, die Sie zurückgeben - `examples/orders-api.json` - eine öffentliche Orders-API mit einem Fixed Window pro Schlüssel, einem Login-Limit und einem globalen Fixed Window; fünf Clients, einschließlich eines geteilten Mobile-Schlüssels, eines Bulk-Partners, eines Scrapers und eines Credential-Stuffers - `examples/orders-api-report.md` - die echte Simulator-Ausgabe für diese Datei - `examples/orders-api-tuned.json` - dieselbe API nach den Korrekturen: Token-Buckets pro Tier, ein globaler Token-Bucket, der auf Kapazität dimensioniert ist ## Arbeitsablauf ### 1. Eingaben sammeln Fragen Sie nach: den Limits, wie sie heute konfiguriert oder vorgeschlagen sind (Algorithmus, Schlüssel, Zahlen, welche Endpoints und welche Clients), wo sie durchgesetzt werden (Gateway, CDN, App, Redis), der Backend-Kapazität in Anfragen pro Sekunde, die es aushält, und dem Traffic: die größten legitimen Clients und ihre Form (gleichmäßig, burstartige Batch-Jobs, viele Benutzer hinter einem Schlüssel oder einer NAT-IP), wie jeder wiederholt, und Missbrauch, der in Logs gesehen wurde. Echte Zugriffslogs schlagen Vermutungen: exportieren Sie `t,client,endpoint` für 5-15 geschäftige Minuten und übergeben Sie es mit `--trace`. ### 2. Simulator ausführen ``` 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 ``` Exit 0 = keine hohen Befunde, 1 = hohe Befunde (legitime Clients gedrosselt oder zugelassener Traffic über Kapazität), 2 = ungültige Eingabe. Ohne Shell argumentieren Sie mit `references/algorithms.md`: pro Schlüssel vergleichen Sie den Spitzenwert des Clients pro Fenster mit dem Limit, den Worst Case (2x Limit für Fixed Windows, Burst + Rate für Buckets) mit der Kapazität und denken durch, was jeder Client nach einem 429er tut. ### 3. Ergebnis lesen - Legitime Clients zuerst (RL01): alle fehlgeschlagenen oder verzögerten Anfragen und wie lange sie gewartet haben. Ein Schlüssel, der von Benutzern einer App geteilt wird, braucht ein eigenes Tier oder einen Schlüssel pro Benutzer. - Kapazität (RL03): die zugelassene Spitzensekunde vs. was das Backend aushält. Ein globales Limit ist das Einzige, das die Kapazität schützt; Limits pro Schlüssel multiplizieren sich mit der Anzahl der Schlüssel. - Form (RL04, RL10): Fixed Windows lassen Bursts an Grenzen durch und geben ein ganzes Fenster auf einmal aus; Retries ohne Jitter kommen alle in derselben Sekunde zurück. - Missbrauch (RL02): Ein Scraper unter dem Limit pro Schlüssel wird durch Limits nicht gestoppt; er braucht Erkennung, Authentifizierung oder ein Limit pro Endpoint. - Retries (RL05): Versuche pro logischer Anfrage über 1,5 bedeutet, dass Clients die Last bei Drosselung verstärken. ### 4. Optimieren und erneut ausführen Ändern Sie jeweils eine Sache und führen Sie mit demselben Traffic erneut aus: wechseln Sie Fixed Windows zu Token-Buckets oder Sliding Counters, fügen Sie Tiers mit `clients` / `exclude_clients` hinzu, dimensionieren Sie den globalen Bucket auf Kapazität (Rate = nachhaltige rps, Burst = was das Backend eine Sekunde absorbiert), fügen Sie Endpoint-Limits für Login und teure Aufrufe hinzu und vereinbaren Sie Pacing mit Batch-Partnern. Verwenden Sie `references/policy-design.md` für die Zahlen. ### 5. Liefern Füllen Sie `templates/rate-limit-review.md`: Urteil, eine Vorher/Nachher-Tabelle pro Client, die Richtlinienänderungen als Konfiguration, die 429-Antwort und Header, Client-Anleitung (Retry-After, Backoff mit Jitter, maximale Retries) und was nach dem Rollout zu überwachen ist. ## Beispielergebnis Bei `examples/orders-api.json` trifft der geteilte `mobile-app`-Schlüssel auf das Fenster von 300/Minute pro Schlüssel: 1.042 seiner 1.839 Anfragen gelingen nur nach Wartezeiten von bis zu 60 s (RL01, hoch). Das Beachten von Retry-After ohne Jitter gibt 289 Retries in Sekunde 240 frei, sodass der zugelassene Traffic bei 313 req/s gegen eine Kapazität von 80 spitzelt (RL03, RL10). Das Fixed Window pro Schlüssel lässt 544 Anfragen in einer rollierenden Minute durch (1,8x, RL04), und der Scraper bekommt immer noch 45% seiner Aufrufe durch, während seine sofortigen Retries ihn auf 2,67 Versuche pro Anfrage treiben. Das Login-Limit stoppt den Credential-Stuffer (40 von 480). In `examples/orders-api-tuned.json` (Tier-Token-Buckets, globaler Bucket 50 req/s + 30 Burst, Partner-Pacing bei 2 req/s) sehen legitime Clients keine 429er, die Spitze ist 27 req/s und nur die Scraper-Befunde bleiben. ## Regeln - Simulieren Sie mit dem Traffic, den Sie tatsächlich haben (oder einer Spur), nicht mit einem Durchschnitt; Bursts und Retries sind, wo Limits versagen. - Nennen Sie ein Limit niemals sicher für die Kapazität, es sei denn, ein globales Limit begrenzt die Gesamtsumme. - Behandeln Sie verzögerte Anfragen legitimer Clients als Schaden, nicht als Erfolg. - Geben Sie immer 429 mit Retry-After zurück, fügen Sie Jitter hinzu und sagen Sie Clients, wie sie zurückweichen sollen. - Rate-Limits sind allein kein Missbrauchsschutz; sagen Sie, wann Authentifizierung, Bot-Erkennung oder WAF-Regeln nötig sind. - Ergebnisse sind ein Modell: bestätigen Sie mit Gateway-Metriken nach dem Rollout und halten Sie die Limits in der Konfiguration, nicht im Code.