Entwicklung

Dieses Dokument beschreibt Build, Tests und den lokalen Betrieb von exchange. Bereitstellung, Protokollfelder und plattformspezifische Installation behandeln die am Ende verlinkten Fachseiten.

Toolchain

Der Workspace verwendet Rust 2021 und benötigt Rust 1.88 oder neuer. Die Version steht im Feld rust-version der Cargo.toml im Repository-Stamm.

Workspace und Programme

Der Rust-Workspace hat neun Mitglieder: acht unter crates/ und das Erweiterungs-SDK unter sdk/extend/rust. Protokolltypen werden ausschließlich in crates/proto definiert. exchange, agent und cli verwenden dieses Crate; duplizieren Sie Nachrichtenstrukturen nicht in einzelnen Komponenten.

Der Einstiegspunkt von exchange ist crates/exchange/src/main.rs. Ohne separate [[bin]]-Tabelle erzeugt cargo build -p exchange das Programm exchange. Die Cargo.toml-Dateien von agent und cli nennen ihre Programme ausdrücklich remote-agent und remote-cli.

Die Verbindungstabelle ist nach Zuständigkeit aufgeteilt:

• crates/exchange/src/hub.rs: Onlinegeräte, Ersetzung bei Wiederverbindung und Verbindungskennung (epoch)
• crates/exchange/src/hub/session_table.rs: Übersetzung zwischen Operator- und Geräte-Sitzungsnummern
• crates/exchange/src/hub/outbound.rs: Begrenzte Sendequeue je Verbindung

Bauen

Führen Sie die Befehle im Repository-Stamm aus.

Das Release-Profil (opt-level = 2, Thin-LTO, Stack-Unwinding bleibt erhalten) erzeugt Server, CLI und Agent:

cargo build --release

Die Programme liegen unter:

• target/release/exchange
• target/release/remote-cli
• target/release/remote-agent

release behält Stack-Unwinding bei, weil exchange ein langlebiger Prozess mit vielen Verbindungen ist. Bei einer Panic in einer Verbindungsaufgabe kann tokio so nur diese Aufgabe stoppen, ohne Sitzungen anderer Geräte im selben Prozess zu beenden.

Für Geräte gibt es außerdem ein größenoptimiertes Profil (opt-level = "z", LTO, panic = "abort", strip, codegen-units = 1):

cargo build -p agent --no-default-features --profile release-small

Das Ergebnis ist target/release-small/remote-agent. Nach einem Absturz starten procd, systemd oder die Aufgabenplanung den Agent erneut. Daher kann hier panic = "abort" die Größe reduzieren.

Die Datenbank wird beim Kompilieren nicht benötigt. crates/exchange/src/db.rs verwendet sqlx-Laufzeitabfragen statt query!-Makros; cargo build funktioniert ohne Datenbank.

Tests

cargo test --workspace

Unter Windows laufen Tests mit Unix-/bin/sh (beziehungsweise OpenWrt-/bin/ash) und PTY nicht. Das Testmodul in crates/agent/src/pty.rs ist durch #[cfg(all(test, unix))] geschützt und wird auf anderen Plattformen nicht kompiliert. Die PTY-Implementierung versucht zuerst /bin/ash, dann /bin/sh. Prozessgruppen und Unix-Signalpfade in exec.rs werden ebenfalls nur unter Unix kompiliert; Windows-Befehlstests verwenden PowerShell statt /bin/sh. Änderungen an Unix-Pfaden in exec.rs oder pty.rs erfordern zusätzlich cargo test --workspace unter Linux. Windows-Ergebnisse allein reichen nicht.

Einzelne Crates oder Bereiche lassen sich gezielt testen, etwa mit cargo test -p proto oder cargo test -p exchange -- hub::.

exchange lokal starten

Stellen Sie PostgreSQL bereit und setzen Sie die Verbindungszeichenfolge in DATABASE_URL. Diese Variable entspricht --database-url von exchange (siehe crates/exchange/src/config.rs). Beim Start führt db::connect die beim Kompilieren eingebetteten Migrationen aus:

sqlx::migrate!("../../migrations")

Die Migrationen liegen im Repository-Stamm unter migrations/ und laufen beim Start automatisch; sqlx-cli wird nicht benötigt.

Für Audit-Operationen ist außerdem ein Verschlüsselungsschlüssel erforderlich. Die folgenden Beispiele erzeugen einen lokalen Testschlüssel. Bewahren Sie ihn sicher auf und verwenden Sie ihn bei späteren Starts erneut. Ein neuer Schlüssel bei jedem Start verhindert die Entschlüsselung bestehender Audit-Details.

export DATABASE_URL='postgres://luci:luci@127.0.0.1:5432/luci'
export AUDIT_ENCRYPTION_KEY="$(python -c 'import base64, secrets; print(base64.b64encode(secrets.token_bytes(32)).decode())')"
cargo run -p exchange -- --listen 127.0.0.1:8080

Unter PowerShell zuerst die Umgebungsvariable setzen:

$env:DATABASE_URL = "postgres://luci:luci@127.0.0.1:5432/luci"
$env:AUDIT_ENCRYPTION_KEY = python -c "import base64, secrets; print(base64.b64encode(secrets.token_bytes(32)).decode())"
cargo run -p exchange -- --listen 127.0.0.1:8080

Bei bereits gebautem Release ersetzen Sie cargo run -p exchange -- durch ./target/release/exchange. Die Standardadresse ist 0.0.0.0:8080; zur lokalen Entwicklung empfiehlt sich die ausdrückliche Bindung an 127.0.0.1.

Enthält die Datenbank noch kein aktives Operatorkonto, erzeugt der Startvorgang einen Administrator und zeigt dessen Token einmalig im Startprotokoll. Der Klartext erscheint nur dieses eine Mal. Vollständige Hinweise zu Bereitstellung, Reverse Proxy und Konten stehen in docs/deployment.md im Repository. Die Seite enthält Serveradressen und wird auf dieser Website nicht veröffentlicht.

Prüfungen vor dem Commit

Führen Sie diese Prüfungen im Repository-Stamm aus. Beginnen Sie bei Rust-Änderungen mit gezielten Crate-Tests und prüfen Sie anschließend den Workspace. Bei bestehenden, nicht betroffenen Formatabweichungen nur geänderte Dateien formatieren. Android, Browser-Erweiterung und mobile Konsole benötigen zusätzlich eigene Builds und Tests; Rust-Tests decken diese Oberflächen nicht ab.

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

Dokumentation pflegen

Prüfen Sie das Implementierungsverhalten, bevor Sie Anleitungen in docs/ aktualisieren. Website-Themen haben eine Referenzquelle unter website/docs/<topic>.md und neun Übersetzungen unter website/docs/content/<locale>/<topic>.md. Befehle, Felder, Codebeispiele und Überschriftenebenen müssen übereinstimmen. Seiten und Suchindizes mit dem Skript erzeugen, nicht nur HTML manuell bearbeiten. Folgende Befehle im Repository-Stamm benötigen Python 3.11+, markdown-it-py und Node.js:

python -m pip install markdown-it-py
python scripts/build-docs.py
python scripts/build-docs.py --check
python scripts/test-docs.py
python scripts/test-docs-markdown.py
node scripts/test-docs-locale.js
python scripts/test-build-docs.py
python scripts/test-site-seo.py

Die Generierungsprüfung vergleicht außerdem alle erzeugten Dateien Byte für Byte. Fehlende oder veraltete Ausgaben führen ohne Schreibzugriffe zum Fehler. CI führt diese Prüfung vor einer Neugenerierung aus.

Die Prüfungen kontrollieren vollständige Übersetzungen, Codebeispiele, Überschriftenstruktur, Seitenlinks, Anker und Sprachrouting. Generierte Seiten zusammen mit den Quellen committen. Der Dokumentationsbau ändert nur lokale Dateien; Website-Deployment und Veröffentlichung von Downloads sind getrennte Vorgänge.

Weitere Dokumentation

• Technik: Ausgehende Verbindungen, Sitzungsübersetzung, epoch, begrenzte Queues und Tokenspeicherung
• Bedienung: Anmeldung, Geräte hinzufügen, Agent starten, Befehle und Shell
• Bereitstellungsanleitung im Repository unter docs/deployment.md (mit Serveradressen, auf dieser Website nicht öffentlich)
• Wire-Protokoll
• Plattformübergreifende Gerätebereitstellung