API Gateway DE

API & Gateway

🌐 English · Deutsch

Die Bot-Seite des Dashboards ist ein JSON-RPC-2.0-Gateway, bereitgestellt vom pdc_webdashboard-Cog. Der BFF ist sein einziger Client: Er verbindet sich über ${GATEWAY_URL}/rpc, authentifiziert sich mit einem geteilten Token und reicht einen verifizierten Nutzer-Kontext mit, den das Gateway bei jedem Call gegen Reds Berechtigungen neu prüft. Diese Seite dokumentiert das Auth-Modell, die Parameter-Konvention, die Methoden-Namespaces und eine repräsentative Methodentabelle. Die hier gelisteten Methoden sind aus der gateway/methods.py des Cogs bestätigt.

Transport & Authentifizierung

• Endpunkt: HTTP-POST an ${GATEWAY_URL}/rpc (ein WebSocket /rpc ist ebenfalls für Streaming definiert; die Web-App nutzt HTTP). Standard-GATEWAY_URL ist http://127.0.0.1:6970.
• Bindung: Das Gateway lauscht nur auf 127.0.0.1 – aus dem Netzwerk nicht erreichbar.
• Token: Jede Anfrage trägt X-Dashboard-Token. Der Cog vergleicht es mit compare_digest (konstante Zeit). Nur der BFF kennt das Token (GATEWAY_TOKEN).
• Nutzer-Kontext: Der BFF – der den Discord-OAuth2-Login bereits erledigt hat – reicht den verifizierten Nutzer mit. Das Gateway leitet daraus die Stufe ab und erzwingt sie.

Parameter-Konvention

Jede Methode erhält params in dieser Form:

{
  "auth": { "user_id": "123", "guild_id": "456", "locale": "de-DE" },
  "args": { /* methodenspezifische Argumente */ }
}

auth kommt vom vertrauenswürdigen BFF; args sind die eigenen Parameter des Calls.

Berechtigungs-Gating

Das Gateway leitet die Stufe des Nutzers ab (siehe Authentifizierung) und prüft die Anforderung der Methode, bevor es sie ausführt. Drei Zusatzregeln gelten:

• Gilden-Untergrenze. Jeder gildenbezogene Call erfordert mindestens guild_member, selbst wenn der Beitrag nur authenticated verlangt – das verhindert, dass ein eingeloggter Nicht-Mitglied durch Manipulation von guild_id fremde Server-Daten liest.
• Lock. Ist das Dashboard gesperrt, darf nur der Bot-Owner geschützte Calls ausführen.
• Audit. Schreibende Aktionen werden im Audit-Log erfasst (gateway.audit(...)), sichtbar auf der Seite /audit.

Methoden-Namespaces

Namespace	Zweck
core.*	Bot-/Gilden-Infos und die öffentliche Befehls-/Stats-Übersicht.
dashboard.*	Branding, Übersicht, Settings, Lock, Sessions, Custom Pages.
manifest.*	Contribution-Manifest (nach Berechtigung gefiltert).
widget.* / panel.* / page.* / list.*	Beitragsspezifische Daten, Formulare und Tabellen.
cogs.*	Cogs auflisten und laden/entladen/neu laden (Owner).
slash.*	App-Befehle auflisten, an/aus, sync (Owner).
downloader.*	Red-Downloader: Repos, Update-Check, Update/Install/Uninstall pro Cog (Owner).
settings.*	Reds Bot-Settings, global und pro Gilde.
serverstats.*	Statistiken (braucht den Cog pdc_webdashboard_stats).
announce.*	Ankündigungs-Kanäle + Senden.
system.*	Bot-Health/Ops-Info (Owner).
audit.*	Audit-Log (Owner).
pages.*	Custom Pages.

Repräsentative Methoden

Alle Namen unten sind aus gateway/methods.py bestätigt.

Methode	Min.-Stufe	Zweck
core.botinfo	authenticated	Name, ID, Avatar, Gilden-Zahl, Latenz, Is-Owner.
core.guilds	authenticated	Sichtbare Gilden des Nutzers (höchste Stufe pro Gilde).
core.guild_detail	guild_member	Mitglieder, Kanäle, Rollen, Präsenz, Daten.
core.commands	öffentlich	Aktive Text- + Slash-Befehle (ohne Login).
core.stats	öffentlich	Öffentliche Landing-Stats (ohne Login).
dashboard.branding	öffentlich	Titel/Icon/Theme + Lock-Status (ohne Login).
dashboard.overview	authenticated	Bot-/Gateway-Übersicht, Is-Owner.
dashboard.settings_get / dashboard.settings_set	bot_owner	Branding lesen/schreiben.
dashboard.lock	bot_owner	Dashboard sperren/entsperren.
dashboard.refresh_sessions	bot_owner	Session-Epoch erhöhen (alle Sessions invalidieren).
dashboard.session_epoch	öffentlich	Aktuelle Epoch (BFF-Session-Prüfung).
manifest.get	authenticated	Sichtbare Beiträge, nach Berechtigung gefiltert.
widget.data	pro Beitrag	Daten eines Widgets.
panel.schema / panel.submit	pro Beitrag	Panel-Formular laden / speichern.
list.rows / list.edit_form / list.edit / list.delete	pro Beitrag	Eine Liste verwalten.
page.schema	pro Beitrag	Komponentenbaum einer Custom Page.
cogs.list	bot_owner	Installierte Cogs mit Ladezustand + Repo.
cogs.set	bot_owner	Cog load / unload / reload.
slash.list	bot_owner	App-Befehle nach Cog gruppiert (inkl. deaktivierter).
slash.set / slash.set_cog	bot_owner	Befehl oder ganzen Cog an/aus.
slash.sync	bot_owner	Befehls-Tree zu Discord synchronisieren.
downloader.repos	bot_owner	Repos mit installierten + verfügbaren Cogs und Update-Flags.
downloader.update_check	bot_owner	Repos updaten, geänderte Cogs melden.
downloader.cog_update	bot_owner	Einen Cog updaten, dann reload + slash-sync.
downloader.cog_install / downloader.cog_uninstall	bot_owner	Cog installieren / deinstallieren.
downloader.repo_add / downloader.repo_remove	bot_owner	Repo hinzufügen / entfernen.
settings.get / settings.set	guild_admin / bot_owner	Red-Settings (Gilden-Scope braucht Admin; global braucht Owner).
serverstats.overview	guild_member	Stats-Übersicht (braucht pdc_webdashboard_stats).
serverstats.messages / .voice / .status / .invites / .activity / .commands	guild_member	Stats-Abschnitte.
serverstats.member_drilldown / .channel_drilldown	guild_member	Detail pro Mitglied / pro Kanal.
announce.channels / announce.send	guild_admin	Sendbare Kanäle auflisten / Ankündigung senden.
system.info	bot_owner	Uptime, Latenz, Versionen, Speicher, Cog-Zahlen, Gateway-Host/Port.
audit.list	bot_owner	Audit-Log-Einträge (neueste zuerst).
pages.list / pages.get	öffentlich	Custom Pages auflisten / lesen (private serverseitig erzwungen).
pages.save / pages.delete	bot_owner	Custom Page anlegen/aktualisieren / löschen.

Verwandte Seiten

• Authentifizierung – Token- + Berechtigungsmodell
• Architektur – wo das Gateway im Request-Flow sitzt
• Cog-Integration – die Contribution-Methoden (manifest/widget/panel/list)