Ratenbegrenzungen

Chastify begrenzt den API-Datenverkehr der Erweiterung, um Sperrsitzungen, Speicher, Geräte und Benachrichtigungssysteme zu schützen.

Ratenbegrenzungen gelten sowohl für den über Chastify geleiteten iFrame-Bridge-Datenverkehr als auch für Backend-Aufrufe mit Developer-API-Schlüsseln.

Aktuelle Erweiterungs-Buckets

Bucket	Limit	Typische Endpunkte
Lesen	300/min	session.get, state.get, metadata.get, Datei gelesen, Status der regulären Aktion
Schreiben	120/min	Backend-Status schreiben, Metadaten aktualisieren, Konfiguration regulärer Aktionen, serverseitig verifizierte Lauferstellung
Hochladen	10/min	Laufzeit- und Setup-Datei-Uploads
Aktion	30/min	Sperraktionen, Gerätebefehle, benutzerdefinierte Protokolle, benutzerdefinierte Benachrichtigungen, serverseitig verifizierte Ergebnisabrechnung
Token	30/min	Generierung des iFrame-Sitzungsstart-/Authentifizierungstokens

Die Grenzwerte werden innerhalb eines einminütigen Zeitfensters ausgewertet.

hinweis

Dies sind die Standardeinstellungen der Plattform. Administratoren/Website-Betreiber von Chastify können für offizielle oder besonders häufig genutzte Erweiterungen individuelle Anpassungen konfigurieren. Diese Anpassungen werden in der Konfiguration der Erweiterungs-App gespeichert und kurzzeitig in Redis zwischengespeichert, um einen schnellen Zugriff auf den Anfragepfad zu ermöglichen.

info

Die Upload- und Aktionsbereiche sind bewusst enger gefasst als die Lese-/Statusbereiche. Uploads beanspruchen Speicherplatz und Bandbreite. Aktionen können den Sperrstatus, Geräte, Benachrichtigungen und den für den Benutzer sichtbaren Verlauf beeinflussen.

Wie Schlüssel gezählt werden

Zu den Schlüsseln für die Ratenbegrenzung gehören:

• Authentifizierte Benutzer-ID Chastify beim Aufruf eines Endpunkts durch die Benutzeroberfläche des Erstanbieters
• Entwickler-API-Schlüssel-ID, wenn Ihr Backend die Endpunkte der Erweiterungssitzung aufruft
• IP-Adresse für anonyme oder nicht authentifizierte Pfade
• das Ziel sessionId oder lockId, falls verfügbar

Dies bedeutet, dass eine einzelne ressourcenintensive Erweiterungssitzung nicht das gesamte Budget der globalen Erweiterungs-API verbrauchen sollte.

Empfohlenes Kundenverhalten

Ihr iFrame oder Backend sollte 429 Too Many Requests als normalen, wiederholbaren Fehler behandeln.

Verwenden Sie exponentielles Backoff bei wiederholten Fehlern:

async function callWithBackoff<T>(fn: () => Promise<T>, attempts = 4): Promise<T> {
  let delayMs = 500;

  for (let attempt = 1; attempt <= attempts; attempt += 1) {
    try {
      return await fn();
    } catch (error: any) {
      const status = error?.status ?? error?.response?.status;
      if (status !== 429 || attempt === attempts) throw error;

      await new Promise((resolve) => setTimeout(resolve, delayMs));
      delayMs *= 2;
    }
  }

  throw new Error("request_failed");
}

Iframe-Brücken-Leitfaden

Für iFrame-Bridge-Clients:

• Die Ergebnisse von session.get werden für die gesamte Lebensdauer der Seite zwischengespeichert, es sei denn, Sie benötigen neue Sperrdaten.
• Speichern Sie vorübergehende Änderungen der Benutzeroberfläche lokal und senden Sie vertrauenswürdige Änderungen an Ihr Backend.
• Vermeiden Sie schnelle Abfrageschleifen. Bevorzugen Sie benutzergesteuerte Lesevorgänge oder langsame Aktualisierungsintervalle.

Beispiel für einen entprellten Backend-Speichervorgang:

let saveTimer: number | undefined;

function scheduleStateSave(data: Record<string, unknown>) {
  window.clearTimeout(saveTimer);
  saveTimer = window.setTimeout(() => {
    fetch("/your-extension-backend/state", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(data),
    }).catch(console.error);
  }, 500);
}

Leitfaden für Backend-Erweiterungen

Für Backend-Aufrufe mit einem Entwickler-API-Schlüssel:

• Privilegierte Aktionen müssen serverseitig verifiziert und vom Benutzer ausgelöst werden.
• Verwenden Sie PUT/PATCH /api/extensions/sessions/:sessionId/state nur von Ihrem Backend aus mit den Zugangsdaten der Developer API.
• Wiederholen Sie Sperrvorgänge nicht blindlings, wenn der erste Versuch möglicherweise erfolgreich war.
• Die Spiel-/Herausforderungsabwicklung soll mit einer Run-ID idempotent sein.
• Dateien werden nur hochgeladen, wenn der Benutzer explizit eine Datei übermittelt.
• Speichern Sie Ihre eigenen externen Aufzeichnungen, wenn Sie Telemetriedaten mit höherer Frequenz benötigen.

warnung

Erhöhen Sie niemals Aktionslimits, um nicht verifizierte Browseraufrufe zu kompensieren. Browser-iFrame-Code ist nicht vertrauenswürdig. Sensible Änderungen sollten von Ihrem Backend validiert werden, bevor Sie Chastify aufrufen.

Welchen Eimer kann ich erwarten?

Gängige Beispiele:

• GET /api/extensions/sessions/:sessionId verwendet den Lese-Bucket.
• GET /api/extensions/sessions/:sessionId/state verwendet den Lese-Bucket.
• PUT/PATCH /api/extensions/sessions/:sessionId/state verwendet den Schreib-Bucket.
• POST /api/extensions/sessions/:sessionId/files verwendet den Upload-Bucket.
• POST /api/extensions/sessions/:sessionId/action verwendet den Aktions-Bucket.
• POST /api/extensions/sessions/:sessionId/device-command verwendet den Aktions-Bucket.
• POST /api/extensions/sessions/:sessionId/logs/custom verwendet den Aktions-Bucket.
• POST /api/extensions/sessions/:sessionId/notifications/custom verwendet den Aktions-Bucket.
• GET /api/extensions/sessions/:sessionId/auth verwendet den Token-Bucket.

Zukünftige Granulatbehälter

Die aktuellen Kategorien sind breit gefasst. Chastify kann sie im Zuge des Wachstums der Developer API weiter unterteilen, zum Beispiel:

• state.write
• metadata.write
• lock.action
• notifications.custom
• device.command
• files.upload

Die Limits pro Nebenstelle können von Administratoren/Website-Betreibern von Chastify erhöht werden, wenn eine offizielle oder genehmigte Nebenstelle mit hohem Datenaufkommen einen berechtigten Bedarf hat. Die Clients sollten so konzipiert sein, dass die Verarbeitung von 429 generisch ist und nicht von exakten Bucket-Namen oder festen Plattformstandardeinstellungen abhängt.