vrds

VRDS verbindet Matrix mit Botcommands, Sprachnachrichten, Medienarchivierung, Mail und Webhooks. Benannte Matrixaccounts verwenden persistente SDK-SQLite-Stores und Ende-zu-Ende-Verschlüsselung. Die Weboberfläche verwaltet Accounts, Commands, Modelle, DAV-Ziele und Module im gemeinsamen Dracula-UI.

Die vollständige Rust-Domain mit allen 110 Funktions-IDs ist an den verbindlichen Goldstandard angeglichen: Axum, Tokio, veröffentlichte Common-Libraries und ein statisches Nonroot-Image auf scratch. Imageziel bleibt harbor.wuastbude.de/vrds/vrds. Funktionsinventar und Prüfstand samt Standardnachlauf erhalten die Image-, Daten-, Restore- und Rollbacknachweise. Die Produktionsumstellung bleibt ein separater GitOps-Schritt.

Zuständigkeit

wuast-crates ist das eigenständige Repository für wuast-common und wuast-ui. Wiederverwendbare Konfigurationsparser, Problem-Details-Antworten, Logging, Shutdown und UI-Komponenten werden dort entwickelt und veröffentlicht. Dieses Repository enthält die Service-Konfiguration, Domain-Fehler, Handler und Router-Zusammenstellung. Die verbindlichen Regeln stehen in AGENTS.md; CLAUDE.md verweist auf dieselbe Zuständigkeit.

rust-template ist die verbindliche Referenz für Grundaufbau, CI, Tooling, Justfile, Agenten-Regeln und Container/Lifecycle aller Apps. wuast-ui ist der gemeinsame UI-Baukasten: Apps wählen und arrangieren Elemente frei und verwenden dokumentierte Optionen für Schriftgröße, semantische Farben, Größen und Dichte. Der Grundstil und seine Defaults bleiben in der Library, damit zentrale Styling-Updates beim nächsten Dependency-Update übernommen werden. Fehlende Bausteine oder Optionen werden dort kompatibel ergänzt und vor der App-Integration veröffentlicht. Potenziell inkompatible Änderungen benötigen vorher die ausdrückliche Entscheidung des Users. CLAUDE.md und GEMINI.md enthalten über Symlinks denselben vollständigen Regelsatz wie AGENTS.md.

Entwicklung

Voraussetzungen: Rust über rustup (Toolchain aus rust-toolchain.toml), just, Git und Node; Docker für die isolierten Datenbanktests und Container-Checks. CI stellt die Testdienste selbst bereit. Der Nativebuild benötigt einen C/C++-Compiler, Clang/libclang, CMake, NASM, Python3 und pkg-config sowie die unterstützten Systemlibraries. scripts/install-native-tools.sh richtet diese Buildtools im Linux-CI-Host ein. just run, just test, just clippy und just build verwenden automatisch den SHA-geprüften Nativebuild unter target/native/.

just setup     # gepinnte cargo-deny/cargo-machete/git-cliff-Versionen und Hooks
just run
just gate      # Pflicht bei funktionalen Änderungen; derselbe Aufruf läuft in Forgejo
just push      # Git-Push; nach Erfolg repo-eigenes target/ vollständig aufräumen

just push origin main oder just push --set-upstream origin feature/mein-thema reichen Git-Argumente unverändert weiter. Nach einem erfolgreichen tatsächlichen Push entfernt cargo clean ausschließlich das lokale target/, einschließlich Coverage-/Browser-Ausgaben. Fehler und Dry-Runs erhalten den Ordner. just clean räumt separat auf; globale Cargo-/Rustup-/Docker-Caches und Anwendungsdaten bleiben erhalten. Der nächste lokale Build kompiliert erneut. Notwendige kompakte Nachweise vorher dokumentieren; direkter git push oder ein IDE-Push lösen die Bereinigung nicht aus. Git bietet keinen lokalen Post-Push-Hook.

just gate prüft Formatierung, Clippy ohne Warnungen, alle Tests, RustSec-Advisories/Dependency-Bans und ungenutzte Dependencies. Cargo-Builds und Tests verwenden --locked. Duplicate-Versionen werden entsprechend deny.toml als Warnungen gemeldet; Lizenzprüfungen sind nicht Teil dieses Gates. Reine Dokumentation, beschreibende Metadaten und nachweislich ungenutzte Migrationsreste benötigen nach Prüfung des Diffs keinen lokalen Gate; die genaue Abgrenzung steht in AGENTS.md.

Tests prüfen eigene Verarbeitung anhand definierter Inputs und unabhängig erwarteter Ergebnisse. Keine Quelltext-, Versionspin-, UI-Titel- oder CSS-Klassen-Prüfungen. Der verbindliche Standard und die Testebenen sind in docs/testing.md dokumentiert und gelten für alle abgeleiteten Apps.

Abgeschlossene Migration fortsetzen

VRDS besitzt keine aktiven old/-/working/-Bestände und keinen Template-Initialisierer mehr. Bei Folgearbeit den bestehenden Checkout, das Inventar, den Abschlussnachweis und den aktuellen Goldstandard abgleichen. Gültige Nachweise wiederverwenden; Prüfungen wegen tatsächlicher Änderungen, konkreter Fehler oder offener Pflichtnachweise ergänzen. Der generische Migrationsablauf beschreibt auch neue Apps; seine initialen Kopieraktionen sind für VRDS bereits abgeschlossen.

Konfiguration

Variable	Default	Verhalten
HOST	0.0.0.0	IPv4-/IPv6-Adresse, z. B. 127.0.0.1 oder ::1; keine DNS-Namen
PORT	gespeicherter Webhook-Port, initial 3000	Explizite Variable überschreibt den gespeicherten Listener-Port; u16, 0 wählt einen freien Port
SHUTDOWN_TIMEOUT_SECS	10	Positive Zahl; gemeinsames begrenztes HTTP-/Worker-Draining nach SIGTERM/SIGINT; anschließend separat begrenztes Schließen der Verbindungen
RUNTIME_CONFIG_DIR	runtime, im Image /runtime	Persistente Konfiguration und Ereignisjournal
CONFIG_PATH	—	Vorhandene Legacy-YAML einmal importieren, wenn noch kein Snapshot existiert; dabei wirken bisherige VRDS_…__…-Overrides
VRDS_WHATSAPP_DATABASE_URI	—	Optionaler, ausschließlich lesender Lookup in der fremden WhatsApp-Bridge-Datenbank; benötigt das aktivierte postgres-Feature
LOG_LEVEL	info	error, warn, info, debug, trace; abgeschlossene HTTP-Antworten mit Status, Dauer und Request-ID ab info
LOG_FORMAT	automatisch	Pretty bei TTY, JSON bei Pipe/Container; json/pretty überschreiben die Auswahl
RUST_LOG	—	Individueller Tracing-Filter, überschreibt LOG_LEVEL

Fehlende Konfigurationswerte verwenden Defaults. Ungültige oder nicht als Unicode lesbare Werte für Host, Port und Shutdown-Timeout verhindern den Start. Der Log nennt die tatsächlich gebundene Adresse, auch bei PORT=0.

Nach dem ersten Import ist der persistierte Snapshot maßgeblich. Änderungen erfolgen über UI/API mit ETag-Schutz; fachliche Module und Accountkonfigurationen werden zur Laufzeit abgeglichen. Matrix-State-Reset bleibt eine ausdrückliche Accountaktion. Die automatische Geräteverifikation akzeptiert ausschließlich die aktuell in VRDS hinterlegten Matrix-User-IDs. Erfolgreiche Spracherkennung ohne voice_summary-Prompt sendet das Transkript.

Persistente Daten und Audio

/runtime und /data benötigen schreibbare persistente Volumes mit UID/GID 65532. Die Runtime enthält config.snapshot.json und config.events.jsonl; beim ersten Lesen des alten Snapshotformats bleibt das Original zusätzlich als config.snapshot.legacy-v1.json erhalten. Base64 ist dabei eine Transportkodierung, keine Verschlüsselung. /data/matrix_store_<account> enthält SDK-SQLite/E2EE und die zugehörige session.json; /data/upload_buffer.json und /data/media_hashes.json erhalten Uploads und Duplikatschutz über Neustarts. SDK-Daten werden ausschließlich gemäß SDK-Vertrag verwendet. Die vorhandenen /runtime- und /data-Mounts bleiben erhalten; eine zusätzliche Upload-Pfadvariable ist nicht erforderlich.

Die Seite Uploads zeigt gespeicherte Medien mit Vorschau/Download, Fehlergrund, Status, Versuchszahl und nächstem Versuch. Sichere vorübergehend fehlgeschlagene WebDAV-Uploads werden mit positiver Pause dauerhaft wiederholt; die Versuchszahl löscht keine Datei. Ungewisse externe Ergebnisse bleiben mit Prüfstatus und erhaltenen Bytes gespeichert. Discard entfernt nach Bestätigung ausschließlich den gewählten lokalen Puffereintrag; laufende Transfers sind dagegen geschützt.

Audio wird innerhalb des VRDS-Prozesses mit statischem FFmpeg decodiert und für ASR in Mono-16-kHz-PCM16-WAV gewandelt. Alle Audiodecoder der bisherigen FFmpeg-Basis und die benötigten Dateidemuxer bleiben eingebunden, einschließlich OpenMPT. Das Scratchimage enthält ausschließlich VRDS als Programm. Offizielle Sourcepins, Lizenztexte und das Native-SPDX liegen im Image; die kombinierte Distribution steht unter GPL-3.0-or-later. Komponenten und Quellinformationen, Audiovertrag und Verarbeitungstests.

HTTP-Vertrag

Pfad	Antwort
GET /healthz	200, {"status":"ok"}
GET /ready	200 mit ready oder 503 mit not_ready
GET /api/v1/status	JSON mit name, version, status, uptime_secs
GET /	Dracula-Dashboard
GET /_assets/*	Eingebettete Assets aus wuast-ui

GET /health bleibt als kompatibler Livenesspfad für das bestehende Deployment erhalten.

Domain-Fehler sowie unbekannte API-Routen und nicht unterstützte API-Methoden liefern RFC-9457-Problem-Details mit application/problem+json. Interne Fehlerdetails werden ausschließlich serverseitig geloggt. Neue Handler müssen ihre Domain- und Extractor-Fehler in AppError überführen, damit dieser Vertrag erhalten bleibt.

Release-Konfiguration

Für Image-Releases erforderlich: HARBOR_USERNAME und HARBOR_PASSWORD. Die SPDX-SBOM wird ohne Signierung im eigenen Harbor mit dem Image-Digest verknüpft und zurückgeprüft; siehe SBOM-Vertrag. Der gemeinsame S3-Compiler-Cache benötigt lokal gültige Credentials und in CI AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY; Endpoint/Bucket haben gemeinsame Defaults. Einrichtung und Buildpfade. Der Release bricht bei fehlender erforderlicher Konfiguration vor dem Image-Push ab.

Releases und Container

PRs durchlaufen .forgejo/workflows/ci.yml; Pushes auf main und manuelle Releases .forgejo/workflows/release.yaml. Release-Läufe werden serialisiert und laufende Veröffentlichungen nicht abgebrochen. Fehler bei der Versionsberechnung führen zu einem fehlgeschlagenen Workflow. Wiederholungen verwenden die Notes des bereits getaggten Releases.

Ein erneuter Lauf desselben getaggten Commits darf dessen Release wiederholen. Spätere reine test:-/style:-Commits erzeugen keinen Release und überschreiben keine veröffentlichte Image-Version. Eine berechnete Version auf einer anderen Git-Historie stoppt die Veröffentlichung vor dem Build.

git-cliff bestimmt die Version aus Conventional Commits. Diese wird als APP_VERSION beim Build übergeben und erscheint identisch im Image-Tag, OCI-Label, Startup-Log, Status-Endpunkt und HTTP-User-Agent. Lokale Builds verwenden die Cargo-Paketversion. APP_VERSION akzeptiert stabile SemVer-Versionen ohne v-Präfix.

Das Image verwendet scratch, UID/GID 65532, CA-Roots, Europe/Berlin, /tmp und Cargo-Manifeste für SBOM-Scanner. Bei readOnlyRootFilesystem benötigen schreibende Anwendungen ein separates temporäres Volume. Health-Probes erfolgen per HTTP durch den Kubelet. Der Release veröffentlicht zuerst candidate-<SHA>; erst nach Veröffentlichung seiner unsignierten SPDX-SBOM im eigenen Harbor und Rückprüfung von Subject-Digest sowie tatsächlichen Bytes erhalten Version und latest denselben geprüften Digest. scratch ersetzt keine Dependency-Advisory-Prüfung.

CI-Actions sind auf Commit-SHAs gepinnt. scripts/ci-tools.lock enthält Versionen, feste Download-URLs und SHA256-Hashes der Linux/amd64-Tools. Aktualisierungen müssen URL, Version und verifizierten Hash gemeinsam ändern; der Installer führt ungeprüfte Downloads nicht aus.

Weitere Befehle: just test, just clippy, just fmt, just outdated, just build, just version, just changelog, just verify-image [tag]. Details: Architektur.

PostgreSQL-Vertrag

VRDS besitzt kein eigenes PostgreSQL-Schema und benötigt keinen Redis-Cache. Das standardmäßig aktivierte postgres-Feature ermöglicht ausschließlich den optionalen SeaORM-LID-Lookup in der fremden Bridge-Datenbank; ihre Tabellen werden nicht migriert. Ausfall oder fehlender Treffer erlaubt den bestehenden Identitätsfallback. just gate prüft den Lookup gegen einen isolierten echten PostgreSQL-Dienst; der Build benötigt keine Datenbank. Appspezifischer Datenbankvertrag.

Coverage

just gate, just test und CI führen die vollständigen echten Tests ohne Coverage-Instrumentierung aus. just coverage misst separat während der Entwicklung und zeigt Zusammenfassung sowie fehlende Zeilen im Terminal; just coverage html erzeugt HTML nur auf ausdrücklichen Bedarf. Keine LCOV-/JSON-/Summary-Dateien, Forgejo-Reportartefakte oder Screenshots. Lokale Einrichtung über just setup; Messverfahren und Grenzen.

Hintergrundprozesse und Betriebsinformationen

src/application.rs, src/workers.rs und src/modules/runtime.rs besitzen Accountsync, Module und deren Jobs über den veröffentlichten Common-Supervisor. Kritisches unerwartetes Ende löst Shutdown und einen Fehlerexit aus; Konfigurations-/Loginfehler bleiben über Setup reparierbar. /metrics liefert HTTP-/Job-Messungen; Request-IDs erscheinen in Response und JSON-Logs. Vertrag und Erweiterungspunkte, verifizierte Lifecycle-Nachweise.