📚 Externe Bibliotheken & Crates

Diese Dokumentation bietet einen vollständigen und detaillierten Überblick über alle externen Rust-Crates und Bibliotheken, die im Projekt MeinCMS (wissen-ahrensburg.de) verwendet werden.

MeinCMS ist als modularer Rust Workspace aufgebaut. Jedes Subsystem (meincms_parser, meincms_web, meincms_backup, meincms_admin) nutzt spezialisierte, hochperformante Open-Source-Bibliotheken für seine jeweiligen Aufgaben.

📋 Schnellübersicht aller Abhängigkeiten

🧩 Details nach Subsystemen

1. meincms_parser (Markdown & MediaWiki Compiler)

Das Crate meincms_parser ist das Herzstück der Inhaltsverarbeitung. Es wandelt Benutzereingaben (Markdown oder MediaWiki/WikiText) sicher in HTML um und führt dynamische Skripte aus.

• regex (v1.10):
  • Zweck: Auswertung und Erkennung von Wiki-Syntaxstrukturen wie Wikilinks ([[Titel]]), Kategorie-Tags ([[kategorie:Name]]), Frontmatter und Makro-Blöcken ({{#rhai: ...}}).
  • Warum gewählt: Standard-Regex-Engine für Rust, hochoptimiert und gegen ReDoS-Angriffe (Regular Expression Denial of Service) geschützt.
• html-escape (v0.2):
  • Zweck: Entschärfen potenziell gefährlicher Zeichen (<, >, &, ", ') vor der HTML-Generierung.
  • Warum gewählt: Gewährleistet strikten Schutz gegen Cross-Site-Scripting (XSS), da unsicherer Benutzercode niemals unmaskiert gerendert wird.
• rhai (v1.19):
  • Zweck: Eingebettete Skriptsprache zur Ausführung dynamischer Makros in Wiki-Artikeln (z. B. mathematische Berechnungen, Zeichenkettenoperationen).
  • Warum gewählt: Rhai wurde speziell für Rust entwickelt, kompiliert ohne externe C-Abhängigkeiten und bietet ein konfigurierbares Ausführungslimit (Sandbox), das Endlosschleifen verhindert.
• serde (v1.0) & serde_json (v1.0):
  • Zweck: Umwandlung interner AST-Metadaten (Abstract Syntax Tree) und C-FFI Export-Datenstrukturen in/aus JSON.

2. meincms_web (Axum Async Web-Backend)

Das Subsystem meincms_web stellt das eigentliche Webseiten-Backend für Besucher und Administratoren bereit.

• axum (v0.7):
  • Zweck: Asynchrones Web-Framework für Routing, Request-Handler, Extractor-Mechanismen und Server-Antworten.
  • Warum gewählt: Entwickelt vom Tokio-Team, bietet maximale Ergonomie, Typen-Sicherheit und exzellente Performance ohne Laufzeit-Overhead.
• tokio (v1.x, Feature full):
  • Zweck: Event-gesteuerte asynchrone Runtime für Multithreading, I/O-Operationen und Server-Sockets.
  • Warum gewählt: Der De-facto-Standard in der Rust-Ökosystem für performante Netzwerkanwendungen.
• sqlx (v0.8, Features: postgres, runtime-tokio-rustls, chrono, json):
  • Zweck: Asynchroner PostgreSQL-Datenbanktreiber und Query-Builder.
  • Warum gewählt: Bietet Typsicherheit beim Ausführen von Datenbankabfragen und unterstützt native Unix Domain Sockets (/var/run/postgresql/meincms) sowie JSON-Spalten.
• maud (v0.26):
  • Zweck: Schreiben von HTML-Templates direkt in Rust-Code via html! { ... } Makro.
  • Warum gewählt: Maud-Templates werden zur Compile-Zeit in hochoptimierten Rust-Code umgewandelt. Das vermeidet Parsing-Kosten zur Laufzeit und macht XSS-Escaping typsicher.
• tower-http (v0.6) & tower (v0.5):
  • Zweck: Middleware-Komponenten für Komprimierung (Brotli & Gzip), Ausliefern statischer CSS/JS-Dateien, CORS und Request-Logging.
• hyper (v1.x) & hyper-util (v0.1):
  • Zweck: Unterbau für den HTTP-Server. Ermöglicht das Binden des Webservers an TCP-Ports oder Unix-Domain-Sockets (UNIX_SOCKET).
• tracing (v0.1) & tracing-subscriber (v0.3):
  • Zweck: Strukturierte Diagnose- und Log-Ausgaben im Serverbetrieb. Steuerung der Detailtiefe über die Umgebungsvariable RUST_LOG.
• dotenvy (v0.15):
  • Zweck: Automatisches Laden von Konfigurationswerten aus einer .env-Datei beim Anwendungsstart.
• chrono (v0.4):
  • Zweck: Datums- und Zeitberechnungen für Artikel-Revisionen und HTTP-Header.

3. meincms_backup (YAML/XML Export, Import & Repair CLI)

Das CLI-Werkzeug meincms_backup dient der Datensicherung, Datenmigration und der Regenerierung beschädigter HTML-Inhalte.

• clap (v4.5, Feature derive):
  • Zweck: Verarbeiten von Befehlszeilen-Argumenten und Optionen (export, import, repair, --full).
  • Warum gewählt: Deklarative Definition von CLI-Interfaces mit automatischer Generierung von Hilfetexten (--help).
• serde_yaml (v0.9):
  • Zweck: Serialisierung und Deserialisierung von Wiki-Artikeln in gut lesbare YAML-Sicherungsdateien.
• quick-xml (v0.37):
  • Zweck: Extrem schnelles Lesen und Schreiben von XML-Sicherungen.
  • Warum gewählt: Verarbeitet selbst sehr große XML-Backups mit minimalem Speicherbedarf.
• sqlx & tokio:
  • Zweck: Direktes Einlesen und Zurückschreiben von Datensätzen in die PostgreSQL-Datenbank im CLI-Kontext.

4. meincms_admin (User- & Admin-Management CLI)

Das Werkzeug meincms_admin dient der sicheren Verwaltung von Administrator-Konten und Zugangsdaten.

• argon2 (v0.5):
  • Zweck: Hashen und Überprüfen von Administrator-Passwörtern nach dem Argon2id-Standard.
  • Warum gewählt: Sieger der Password Hashing Competition (PHC). Bietet höchstmöglichen Schutz gegen GPU- und ASIC-basierte Brute-Force-Angriffe durch konfigurierbare Speicher- und Zeitkomplexität.
• rpassword (v7.3):
  • Zweck: Sicheres Einlesen von Passwörtern im Terminal ohne Konsolenausgabe (Kein Echo des Passworts auf dem Bildschirm).
• clap (v4.5) & serde_json (v1.0):
  • Zweck: CLI-Steuerung und Speichern der Admin-Konfiguration (config/users.json).

🔒 Sicherheits- & Wartungshinweise

1. Keine veralteten Abhängigkeiten (Security Audits): Um Sicherheitslücken in externen Crates frühzeitig zu erkennen, sollte regelmäßig cargo audit ausgeführt werden:

   cargo install cargo-audit
   cargo audit
   

2. Aktualisierung der Crates: Crates innerhalb der angegebenen Minor-Versionen können mit folgendem Befehl auf den neuesten Stand gebracht werden:

   cargo update
   

3. Lizenzkonformität: Alle verwendeten Bibliotheken nutzen verträgliche Open-Source-Lizenzen (wie MIT, Apache-2.0 oder BSD), die vollständig mit der AGPL-3.0-Lizenz von MeinCMS kompatibel sind.