Unter der Haube

Dieses Dokument bietet eine detaillierte, technische Aufschlüsselung darüber, wie der CrossBan Discord-Bot funktioniert, mit Fokus auf seine Code-Struktur, Ausführungsabläufe und zentrale Komponenten. Es richtet sich an Entwickler oder Personen mit Programmierkenntnissen. Der Bot ist in TypeScript unter Verwendung von Discord.js und PostgreSQL geschrieben.

Übersicht

CrossBan synchronisiert Banns über mehrere Discord-Server hinweg. Er hört auf Bann-/Entbann-Ereignisse über Discords Audit-Logs, speichert Daten in einer PostgreSQL-Datenbank und propagiert Aktionen an verbundene Gilden basierend auf Konfigurationen. Er verwendet Docker für das Deployment und handhabt Logging über Webhooks und Nachrichten in Kanälen.

Wesentliche Technologien:

• Discord.js: Für die Interaktion mit der Discord-API.

• PostgreSQL: Für persistente Speicherung.

• Node.js/TypeScript: Laufzeit und Sprache.

• Docker: Containerisierung.

Der Kern des Bots ist ereignisgesteuert, mit Modulen, die beim Start dynamisch geladen werden.

Architektur

Der Bot ist modular:

• Haupteinstieg (index.ts): Initialisiert den Client, lädt Befehle/Komponenten/Ereignisse und startet den Bot.

• Module:

  • Befehle: Slash-Befehle (z. B. config).

  • Komponenten: Interaktive Elemente (z. B. Buttons für Entbann-Überprüfungen).

  • Ereignisse: Handler für Discord-Ereignisse (z. B. Audit-Log-Einträge).

• Hilfsfunktionen: Logger, Bann-Sync-Manager, Entbann-Logger.

• Datenbank: Manager für Abfragen und Schema-Initialisierung.

• Konfiguration: Umgebungsbasierte Einstellungen.

Dateien werden dynamisch geladen mithilfe von require() basierend auf Dateiendungen (.ts in der Entwicklung, .js in der Produktion).

Startprozess

Der Bot startet in index.ts via einer async IIFE (Immediately Invoked Function Expression).

Client-Initialisierung

const client = new Client({
  intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMembers, ...],
  // ... andere Optionen
});

• Erstellt einen Discord-Client mit Intents für Gilden, Mitglieder, Nachrichten und Moderation.

• Begrenzt den Cache für Performance (z. B. 128 Nachrichten pro Manager).

Modul-Laden

Funktionen wie loadCommands(), loadComponents(), und loadEvents() scannen Verzeichnisse und laden Dateien:

• loadCommands(): Liest commands/ Ordner, filtert nach Endung, require()t jede Datei und prüft auf data und run Eigenschaften. Speichert in einer Collection.

• loadComponents(): Ähnlich für components/, prüft auf prefix und run.

• loadEvents(): Durchsucht events/ Unterordner (passend zum Discord Events-Enum), lädt Handler.

Beispiel für Befehle:

for (const file of commandFiles) {
  try {
    const command = require(file);
    if (typeof command == "object" && "data" in command && "run" in command) {
      // Zur Collection hinzufügen
    }
  } catch (error) {
    console.error(`Error loading command file ${file}`, { error });
  }
}

Einrichtungs des Interaction-Handlers

function setupInteractionHandlers() {
  client.on("interactionCreate", new InteractionHandler(client, commands, components).handler());
}

• Hängt einen Handler für Interaktionen an (Befehle, Buttons, Selects).

Client Ready Event

client.once("clientReady", async (_client) => {
  // Befehle bereitstellen, Aktivität setzen, etc
});

• Stellt Slash-Befehle bereit mithilfe von deployCommands().

• Initialisiert den Entbann-Logger und den Bann-Sync-Manager.

• Setzt die Bot-Aktivität, um die Anzahl der Server anzuzeigen.

• Lädt Wahrheitsquellen aus der DB in die Konfiguration.

Datenbank-Initialisierung

• Ruft auf dbManager.initialize() um SQL-Schemata aus schemas/ Ordner auszuführen.

• Bereinigt veraltete Gilden/Wahrheitsquellen.

• Lädt Wahrheitsquellen in den Arbeitsspeicher.

Einloggen und Funktionen aktivieren

• client.login(config.botToken) verbindet mit Discord.

• Aktiviert den Bann-Sync-Manager.

• Im Dev-Modus aktiviert es Logging.

Ereignisbehandlung

Ereignisse werden über guildAuditLogEntryCreate in banEventHandler.ts.

Bann/Entbann-Erkennung

function shouldIgnore(entry: GuildAuditLogsEntry, guildId: string) {
  if (entry.action !== AuditLogEvent.MemberBanAdd && entry.action !== AuditLogEvent.MemberBanRemove) return true;
  if (!config.guildIds.includes(guildId)) return true;
  if (!entry.executorId || entry.executorId === config.clientId || !config.isTruthSourceFor(guildId, entry.executorId))
    return true; // Nur von Wahrheitsquellen verarbeiten
  return false;
}

• Ignoriert Nicht-Bann-Ereignisse, nicht konfigurierte Gilden, Bot-Aktionen oder Executor(en), die keine Wahrheitsquellen sind.

Verarbeitung von Banns

Für MemberBanAdd:

• Ruft auf banSyncManager.handleBan() mit Benutzer-ID, Quell-Gilde, Executor und Grund.

• Erstellt ein BanEvent in der DB.

• Synchronisiert zu Gilden mit aktiviertem Auto-Bann.

Für MemberBanRemove:

• Ruft auf banSyncManager.removeBan() um in Gilden zu entbannen.

Bann-Synchronisation

Behandelt von banSyncManager.ts.

Behandlung von Banns

async handleBan(data: BanEventInsert): Promise<void> {
  const banEvent = await dbManager.addBanEvent(data);
  await dbManager.createGuildBan({ /* Quell-Bann */ });
  await this.syncBanToGuilds(banEvent, data.sourceGuild);
}

• Fügt das Bann-Ereignis in ban_events Tabelle ein.

• Erstellt einen Gilden-Bann-Datensatz für die Quelle.

• Synchronisiert zu Zielgilden.

Synchronisation zu Gilden

private async syncBanToGuilds(event: BanEvent, sourceGuildId: string): Promise<void> {
  const autoBanGuilds = await dbManager.getGuildConfigsForAutoban();
  const targetGuilds = autoBanGuilds.filter((config) => config.guildId !== sourceGuildId);
  for (const guildConfig of targetGuilds) {
    const guild = this.client?.guilds.cache.get(guildConfig.guildId);
    if (guild) {
      await guild.bans.create(event.userId, { reason: `Synced ban...` });
      await dbManager.createGuildBan({ /* Ziel-Bann */ });
    }
  }
}

• Holt Gilden mit aktiviertem Auto-Bann.

• Bannt den Benutzer in jeder Zielgilde über die Discord-API.

• Erfasst Einträge in der DB.

Behandlung von Entbannungen

async removeBan(data: { userId: string; sourceGuild: Guild; executorId: string }): Promise<void> {
  await dbManager.removeGuildBan(data.userId, data.sourceGuild.id);
  await this.syncUnbanToGuilds(ban, data.sourceGuild, data.executorId);
}

• Kennzeichnet den Bann in der DB als inaktiv.

• Synchronisiert Entbann: Automatisches Entbannen oder sendet ein Review-Log.

Für den Review-Modus:

• Verwendet unbanLogger um eine Nachricht mit einem Auswahlmenü für Entbann/Ignore zu senden.

Datenbank-Interaktionen

Gemanagt von manager.ts unter Verwendung von pg (PostgreSQL-Client).

Initialisierung

• Liest .sql Dateien aus schemas/ und führt sie aus, um Tabellen zu erstellen (z. B. guilds, ban_events, guild_bans, truth_sources).

Wesentliche Operationen

• Gilden-Konfigurationen: CRUD für Einstellungen (aktiviert, Auto-Bann, Entbann-Modus, Logging-Kanal).

• Bann-Ereignisse: Einfügen und Abfragen globaler Banns.

• Gilden-Banns: Verfolgt Bann-Status pro Gilde.

• Wahrheitsquellen: Verwalten vertrauenswürdiger Benutzer pro Gilde.

Beispielabfrage:

async getBan(userId: string): Promise<BanEvent | null> {
  const result = await this.query("SELECT * FROM ban_events WHERE user_id = $1 ORDER BY created_at DESC LIMIT 1", [userId]);
  // ...
}

Logging und Entbann-Verarbeitung

Allgemeines Logging

logger.ts verwendet eine Warteschlange für sequentielle Webhook-Sends:

async function sendLogInternal(data: any): Promise<void> {
  if (!wh) return;
  // Formatiert Daten als JSON oder String, sendet an den Webhook.
}

• Reihenfolge der Logs, um Rate-Limits zu vermeiden.

• Aktiviert wenn LOGGING_WEBHOOK in .env.

Entban-Logging

gesetzt ist unbanLogger.ts

baut Nachrichten unter Verwendung von Discords Component-Buildern:
  public buildLogMessage<T extends UnbanMessageType>(type: T, details: UnbanDetails<T>): RESTPostAPIChannelMessageJSONBody {
  const builder = new UnbanMessageBuilder<T>();
    return {
    flags: ComponentsV2Flags,
    // ...
  };
}

• components: builder.build(details, type),

• Erstellt Container mit Text, Trennern, Thumbnails für Entbann-Details.

• Für den Review-Typ fügt es ein Auswahlmenü für Aktionen hinzu.

Sendet rohen Payload via REST-API an den Logging-Kanal.

Konfigurationsverwaltung config.ts .env lädt aus

• Dateien: Parst GUILDS

• als Array.

• Verwaltet Wahrheitsquellen im Speicher (Map von Sets).

Bietet Methoden zum Hinzufügen/Entfernen von Quellen und zum Prüfen, ob ein Benutzer eine Wahrheitsquelle ist.

Beispiel:
  addTruthSource(guildId: string, source: string) {
  const _sources = this._truthSources.get(guildId) || new Set<string>();
  _sources.add(source);
}

this._truthSources.set(guildId, _sources);

• Fehlerbehandlung und Randfälle

• Unbehandelte Rejections/Exceptions werden geloggt.

• Datenbankabfragen verwenden parametrisierte Statements, um SQL-Injection zu verhindern.

• Der Client prüft die Verfügbarkeit bevor Aktionen ausgeführt werden.