Rust WASM: Portierung CLI zum Browser

Migration eines Rust-CLI-Tools zu WebAssembly mit Deployment auf GitLab Pages

Eine Konsolenanwendung zur Generierung von Textvorhersagen wurde mithilfe von Rust zu WebAssembly portiert. Die Berechnungslogik ist in einem WASM-Modul isoliert, während die Benutzeroberfläche als statische HTML-Seite mit terminalähnlicher Benutzererfahrung implementiert wurde. Das Deployment über GitLab Pages ermöglicht sofortigen Zugriff auf die Demo ohne Installation.

Das Projekt umfasst eine Rust-Bibliothek für die Kernlogik, ein Frontend mit Vanilla JavaScript und CSS sowie wasm-pack-Artefakte. Dieser Ansatz ist ideal für schlanke Utilities, die keinen Dateisystemzugriff oder plattformspezifische APIs benötigen.

Projektarchitektur

Die Struktur ist in drei Komponenten unterteilt:

• src/lib.rs — Kernlogik in Rust mit exportierten Funktionen.
• public/index.html, styles.css, app.js — Terminalartige Benutzeroberfläche.
• public/pkg/ — Kompilierte WASM-Dateien und JavaScript-Wrapper.

Das Fehlen von Betriebssystemabhängigkeiten macht den Port unkompliziert: Die Anwendung akzeptiert Befehle und gibt Text zurück.

Export von Rust zu WASM

Die Hauptfunktion wird mit #[wasm_bindgen] exportiert:

#[wasm_bindgen]
pub fn generate_reading_text() -> String {
    // Ergebnis generieren und formatieren
}

Build mit dem Befehl:

wasm-pack build --target no-modules --release --out-dir public/pkg

Ergebnis: iching_wasm.js und iching_wasm_bg.wasm. Die Option --target no-modules vereinfacht die Integration ohne Bundler.

Integration von WASM in den Browser

In app.js wird das Modul synchron mit base64-eingebettetem WASM geladen, um mit file:// zu funktionieren:

const wasmBytes = base64ToBytes(window.ICHING_WASM_BASE64);
wasm_bindgen.initSync({ module: wasmBytes });

const text = wasm_bindgen.generate_reading_text();
output.textContent = text;

In index.html sind folgende Dateien enthalten:

• ./pkg/iching_wasm.js — Laufzeitumgebung.
• ./pkg/iching_wasm_bg_base64.js — Base64-WASM.
• app.js — UI-Logik.

JavaScript ruft WASM auf, und das Ergebnis wird in das DOM gerendert.

Terminalartige Benutzeroberfläche

Frameworkfreie Benutzeroberfläche:

• Container mit Rahmen und Fenstertitel.
• Nichtproportionale Schriftart (z.B. JetBrains Mono).
• Dunkles Design mit grünem Text.
• <pre> für die Ausgabe.
• Eingabe für Befehle wie ./generate_reading.

Visuell und verhaltensmäßig imitiert sie eine Konsole. Ein Button löst den WASM-Aufruf aus.

CI/CD für Build und Deployment

.gitlab-ci.yml automatisiert den Prozess:

image: rust:slim

create-pages:
  pages:
    publish: public
  rules:
    - if: '$CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH'
  before_script:
    - rustup target add wasm32-unknown-unknown
    - cargo install wasm-pack --locked
  script:
    - wasm-pack build --target no-modules --release --out-dir public/pkg
    - b64="$(base64 public/pkg/iching_wasm_bg.wasm | tr -d '\n')"
    - printf 'window.ICHING_WASM_BASE64 = "%s";\n' "$b64" > public/pkg/iching_wasm_bg_base64.js

Schritte: Target installieren, mit wasm-pack bauen, WASM zu base64 kodieren, public/ auf Pages veröffentlichen.

Vorteile dieses Ansatzes

• Zugänglichkeit: Demo funktioniert in jedem Browser ohne Rust oder lokale Installation.
• Sicherheit: WASM-Isolierung eliminiert Risiken durch nativen Code.
• Einfachheit: Statisches Hosting, ein CI-Job.
• Portabilität: Geeignet für CLI-Tools ohne Systemaufrufe.

Wichtige Erkenntnisse

• Logik ohne Dateisystem- oder API-Abhängigkeiten passt perfekt in WASM — baut in Sekunden.
• Base64-Einbettung von WASM löst CORS- und file://-Probleme.
• GitLab Pages + wasm-pack CI bietet eine vorgefertigte Pipeline für Prototypen.
• Vanilla JavaScript/HTML für die UI minimiert Overhead.
• #[wasm_bindgen] ist der Standard für den Export von Rust zu JavaScript.

— Editorial Team