Testen, wie Ihre App GitHub API-Ratenbeschränkungen behandelt

Auf einen Blick
Ziel: Testen, wie Ihre App GitHub REST-API-Ratenbegrenzungen behandelt
Zeit: 15 Minuten
Plugins:RateLimitingPlugin, GenericRandomErrorPlugin, RetryAfterPlugin
Voraussetzungen:Einrichten des Dev-Proxys

Ihre App ruft die GitHub-API auf. Es funktioniert auf Ihrem Computer, doch ein CI-Auftrag, eine große Organisation oder ein arbeitsreicher Tag bringen es über das Ratelimit, und es beginnt zu fehlschlagen. Um es mit der echten API zu testen, müssen Sie Ihr Anfragelimit ausschöpfen und dann bis zu einer Stunde warten, bevor Sie es erneut versuchen können. Dev Proxy simuliert GitHub Ratenbeschränkungen lokal mit einem Limit und einem von Ihnen ausgewählten Zeitfenster.

Erfahren Sie, was GitHub zurückgibt

GitHub verfügt über zwei Arten von Ratenbeschränkungen für die REST-API.

Primäre Ratenbegrenzungen begrenzen die Anzahl der Anforderungen, die Sie pro Stunde vornehmen. Beispielsweise 60 für nicht authentifizierte Anfragen und 5.000 für Anfragen mit einem persönlichen Zugriffstoken. Jede Antwort enthält Kopfzeilen, die zeigen, wo Sie sich befinden:

Wenn Sie den primären Grenzwert überschreiten, gibt GitHub zurück 403 oder 429 mit x-ratelimit-remaining festgelegt auf 0. Wiederholen Sie den Vorgang erst bis zur in x-ratelimit-reset angegebenen Zeit.

Sekundäre Ratenbegrenzungen schützen GitHub vor Lastspitzen, z. B. vor zu vielen gleichzeitigen Anfragen oder dem zu schnellen Erstellen von zu vielen Inhalten. Wenn Sie eins überschreiten, gibt GitHub 403 oder 429 mit einer Meldung über ein sekundäres Ratenlimit zurück. Wenn die Antwort einen retry-after Header hat, warten Sie entsprechend viele Sekunden. Warten Sie andernfalls mindestens eine Minute, und erhöhen Sie die Wartezeit, wenn die Anforderung fehlschlägt.

GitHub kann Integrationen verbieten, die weiterhin Anfragen senden, während sie vom Rate Limit betroffen sind. Weitere Informationen finden Sie in der GitHub Dokumentation unter "Rate limits for the REST API".

Primäre Ratenbegrenzung simulieren

Verwenden Sie "RateLimitingPlugin", um Anforderungen zu zählen und GitHub-Rate-Limit-Header zurückzugeben. Wenn Sie testen möchten, ohne eine Stunde zu warten, verwenden Sie ein kleines Limit und ein kurzes Fenster.

Datei: devproxyrc.json

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/rc.schema.json",
  "plugins": [
    {
      "name": "RetryAfterPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll"
    },
    {
      "name": "RateLimitingPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll",
      "configSection": "githubRateLimit"
    }
  ],
  "urlsToWatch": [
    "https://api.github.com/*"
  ],
  "githubRateLimit": {
    "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/ratelimitingplugin.schema.json",
    "headerLimit": "x-ratelimit-limit",
    "headerRemaining": "x-ratelimit-remaining",
    "headerReset": "x-ratelimit-reset",
    "resetFormat": "UtcEpochSeconds",
    "costPerRequest": 1,
    "rateLimit": 5,
    "resetTimeWindowSeconds": 60,
    "warningThresholdPercent": 0,
    "whenLimitExceeded": "Custom",
    "customResponseFile": "github-rate-limit-exceeded.json"
  }
}

Definieren Sie in der benutzerdefinierten Antwortdatei die Antwort, die GitHub zurückgibt, wenn Sie das primäre Ratenlimit überschreiten.

Datei: github-rate-limit-exceeded.json

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/ratelimitingplugin.customresponsefile.schema.json",
  "statusCode": 429,
  "headers": [
    {
      "name": "content-type",
      "value": "application/json; charset=utf-8"
    }
  ],
  "body": {
    "message": "API rate limit exceeded for user ID 1.",
    "documentation_url": "https://docs.github.com/rest/overview/rate-limits-for-the-rest-api"
  }
}

Starten Sie Dev Proxy, und führen Sie Ihre App aus.

devproxy --config-file devproxyrc.json

Dev Proxy leitet die ersten fünf Anfragen in jeder Minute an GitHub weiter und setzt die x-ratelimit-*-Header in den Antworten. Ab der 6. Anforderung gibt Dev Proxy die Antwort zur Ratenbegrenzung zurück, wobei x-ratelimit-remaining auf 0 und x-ratelimit-reset auf das Ende des Fensters festgelegt ist. Wenn Ihre App die API erneut aufruft, bevor das Fenster zurückgesetzt wird, meldet RetryAfterPlugin dies und drosselt die Anforderung.

Überprüfen Sie Folgendes in Ihrer App:

• Liest x-ratelimit-remaining und verlangsamt sich, bevor es 0 erreicht.
• Beendet das Aufrufen der API nach einer Rate-Limit-Antwort und wartet bis x-ratelimit-reset.
• Teilt dem Benutzer mit, was passiert, z. B. „GitHub Ratelimit erreicht, erneuter Versuch um 14:05“, anstatt im Hintergrund fehlzuschlagen.

Sekundäre Ratenbegrenzungen simulieren

Sekundäre Ratenlimits kommen schubweise und enthalten eine retry-after Kopfzeile. Verwenden Sie " GenericRandomErrorPlugin ", um sie zufällig zurückzugeben.

Datei: devproxyrc.json

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/rc.schema.json",
  "plugins": [
    {
      "name": "RetryAfterPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll"
    },
    {
      "name": "GenericRandomErrorPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll",
      "configSection": "githubSecondaryRateLimit"
    }
  ],
  "urlsToWatch": [
    "https://api.github.com/*"
  ],
  "githubSecondaryRateLimit": {
    "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/genericrandomerrorplugin.schema.json",
    "errorsFile": "github-secondary-rate-limit.json",
    "rate": 50,
    "retryAfterInSeconds": 60
  }
}

Datei: github-secondary-rate-limit.json

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/genericrandomerrorplugin.errorsfile.schema.json",
  "errors": [
    {
      "request": {
        "url": "https://api.github.com/*"
      },
      "responses": [
        {
          "statusCode": 429,
          "headers": [
            {
              "name": "content-type",
              "value": "application/json; charset=utf-8"
            },
            {
              "name": "retry-after",
              "value": "@dynamic"
            }
          ],
          "body": {
            "message": "You have exceeded a secondary rate limit. Please wait a few minutes before you try again.",
            "documentation_url": "https://docs.github.com/rest/overview/rate-limits-for-the-rest-api#about-secondary-rate-limits"
          }
        }
      ]
    }
  ]
}

Starten Sie Dev Proxy, und führen Sie Ihre App aus. Überprüfen Sie, ob Ihre App auf die Anzahl der Sekunden im retry-after Header wartet, bevor sie die API erneut aufruft. Wenn dies nicht der Fall ist, melden die RetryAfterPlugin Berichte dies.

Wenn Sie Octokit mit dem Drosselungs-Plug-In verwenden, überprüfen Sie, ob Ihre onRateLimit und onSecondaryRateLimit Handler ausgeführt werden und dass sie das erwartete Ergebnis zurückgeben.

Nächster Schritt

Erfahren Sie mehr über RateLimitingPlugin.

Siehe auch

• Simulieren von Rate-Limit-API-Antworten – Ratenbeschränkungen für jede API
• Testen, dass meine Anwendung die Drosselung ordnungsgemäß verarbeitet – Drosselung für jede API
• RetryAfterPlugin – Überprüfen des Wiederholungsverhaltens
• Verwenden von Dev Proxy in CI/CD – Automatisieren von Resilienztests in Ihrer Pipeline