frank/streamertool

Watch

Fork 0

Architektur-Review: Tauri 2 Best Practices und technische Schulden #7

New issue

Closed

opened 2026-07-12 00:27:17 +02:00 by frank · 1 comment

frank commented

2026-07-12 00:27:17 +02:00

Owner

Kontext

Streamertool ist eine Tauri-2-Desktop-App (Rust + React/Vite) mit eingebettetem lokalem Overlay-Server (Axum: HTTP, WebSocket, SSE), Connector-Layer (Twitch, OBS, Streamer.Bot), Event-Bus, SQLite und ZIP-Extensions.

Die V1-Funktionalität steht; vor weiterem Ausbau (#1–#6) soll die Architektur systematisch geprüft und an etablierte Tauri-2- und Rust-Desktop-Best-Practices angeglichen werden.

Ist-Zustand (Kurzüberblick):

Bereich	Aktuell
Frontend ↔ Backend	Admin-UI spricht fast ausschließlich den lokalen HTTP-Server an; nur `get_server_info` als Tauri-Command
Setup	`block_on` im `setup`-Hook für Bootstrap
Security	`csp: null` in `tauri.conf.json`; Capability `default` mit `core:default`
State	`Arc<AppState>` via `app.manage()`; Tokio-Tasks für Server + Connector-Supervisor
Fehler	Mix aus `AppResult`/`thiserror` (Rust) und `String` in Commands

Ziel

Vollständiges Architektur-Review dokumentieren (Stärken, Risiken, Abweichungen von Best Practices).
Konkrete, priorisierte Maßnahmen ableiten und schrittweise umsetzen.
Review-Ergebnis als Referenz für künftige Features (#4 Extension-Sandbox, #6 LAN-Sync) nutzbar machen.

Review-Bereiche

A. Tauri-App-Struktur & Lifecycle

lib.rs vs. main.rs, Plugin-Registrierung, setup-Hook
Async-Bootstrap (block_on im Setup) — Alternativen: tauri::async_runtime::spawn, State-Initialisierung mit OnceCell/ManagedState
Fenster-/Webview-Konfiguration (tauri.conf.json)
Ressourcen-Bundling (overlays, extensions) — Dev vs. Release-Pfade

B. IPC & Frontend-Integration

Abgrenzung: Tauri Commands vs. lokaler HTTP-API — wann was?
Typisierte Commands + specta/tauri-specta oder gemeinsame Types (Rust ↔ TS)
Fehlerpropagierung: einheitliches Error-Format statt String in Commands
Frontend: @tauri-apps/api-Nutzung, Fallback-Port-Logik in api.ts

C. Security (Tauri 2)

CSP definieren und testen (Admin-UI + Overlay-Host)
Capabilities verfeinern — Principle of Least Privilege statt core:default
tauri.conf.json → app.security (dangerousRemoteDomainIpcAccess, assetProtocol, …)
Lokaler Server: Bind-Adresse, CORS, Auth für Admin-Endpoints
Secrets (Twitch Tokens, AI API Keys) — Speicherung, Logging, Memory

D. Rust-Backend-Architektur

Modul-Grenzen: connectors/, server/, events/, db/, extensions/
AppState-Design: Shared State, RwLock-Granularität, Testbarkeit
Event-Bus: Backpressure, Subscriber-Lifecycle, Fehlerbehandlung
Connector-Supervisor: Reconnect, Graceful Shutdown, Cancellation
Error-Handling: thiserror/anyhow-Konsistenz, keine expect/unwrap in Produktionspfaden

E. Lokaler Server (Axum)

Router-Struktur, Middleware (CORS, Tracing, Timeouts)
WebSocket/SSE: Connection-Management, Heartbeats
Port-Konfiguration und Neustart-Verhalten
Vorbereitung auf #6 (LAN/Multi-PC): Bind 0.0.0.0, TLS, Discovery

F. Persistenz & Daten

SQLite: Migrations, Connection-Pool, Transaktionen
Settings-Schema (JSON in DB) — Validierung, Versionierung
Extension-/Overlay-Pfade: User-Data vs. Bundle-Resources

G. Observability & Debugging

tracing/tracing-subscriber: strukturierte Logs, Log-Rotation
Dev vs. Release Log-Level
Optional: Crash-Reporting / Fehlerdialog in der UI

H. Build, CI & Distribution

Cargo.toml: Feature-Flags, tokio full → gezielte Features
Cross-Compile (Windows von macOS), Code-Signing-Vorbereitung
Forgejo CI: make ci vs. vollständige Integrationstests
Updater-Plugin (tauri-plugin-updater) — Bedarf und Strategie

I. Tests

Unit-Tests für kritische Module (Event-Bus, DB, Connector-Parser)
Integrationstests für HTTP-API (Axum TestClient)
Frontend: minimale Smoke-Tests oder E2E (optional, niedrige Priorität)

J. Dokumentation

Architekturdiagramm (Module, Datenfluss Admin ↔ Server ↔ OBS)
ADRs für zentrale Entscheidungen (HTTP vs. IPC, Event-Bus-Design)
AGENTS.md / README um Architektur-Sektion ergänzen

Deliverables

Review-Dokument (Markdown im Repo oder Issue-Kommentar) mit Findings nach Priorität: kritisch / hoch / mittel / niedrig
Umsetzungs-Backlog: dieses Issue oder Follow-up-Issues pro Maßnahmenblock
Mindestens die kritischen und hohen Security-/Lifecycle-Punkte umgesetzt oder bewusst dokumentiert (Won't fix + Begründung)

Akzeptanz

Alle Review-Bereiche A–J sind durchgearbeitet und dokumentiert
CSP und Capabilities sind bewusst konfiguriert (nicht mehr null / blind default)
IPC-Strategie (Commands vs. HTTP) ist festgelegt und dokumentiert
Keine block_on/expect-Hotspots mehr im Startup-Pfad ohne Begründung
Architekturdiagramm und mindestens 2 ADRs liegen vor

Bezug zu bestehendem Backlog

#4 Extension-Sandbox — baut auf Security-Review (C) auf
#6 LAN-Sync — baut auf Server-Review (E) auf

Vorgehen (Vorschlag)

Read-only Review aller Module + tauri.conf.json / Capabilities
Findings sammeln und priorisieren
Quick Wins (CSP, Capabilities, Logging) in kleinen PRs
Größere Refactors (IPC-Typisierung, Startup-Lifecycle) in separaten PRs

## Kontext Streamertool ist eine Tauri-2-Desktop-App (Rust + React/Vite) mit eingebettetem lokalem Overlay-Server (Axum: HTTP, WebSocket, SSE), Connector-Layer (Twitch, OBS, Streamer.Bot), Event-Bus, SQLite und ZIP-Extensions. Die V1-Funktionalität steht; vor weiterem Ausbau (#1–#6) soll die Architektur systematisch geprüft und an etablierte **Tauri-2- und Rust-Desktop-Best-Practices** angeglichen werden. **Ist-Zustand (Kurzüberblick):** | Bereich | Aktuell | |---------|---------| | Frontend ↔ Backend | Admin-UI spricht fast ausschließlich den lokalen HTTP-Server an; nur `get_server_info` als Tauri-Command | | Setup | `block_on` im `setup`-Hook für Bootstrap | | Security | `csp: null` in `tauri.conf.json`; Capability `default` mit `core:default` | | State | `Arc<AppState>` via `app.manage()`; Tokio-Tasks für Server + Connector-Supervisor | | Fehler | Mix aus `AppResult`/`thiserror` (Rust) und `String` in Commands | ## Ziel 1. **Vollständiges Architektur-Review** dokumentieren (Stärken, Risiken, Abweichungen von Best Practices). 2. **Konkrete, priorisierte Maßnahmen** ableiten und schrittweise umsetzen. 3. Review-Ergebnis als Referenz für künftige Features (#4 Extension-Sandbox, #6 LAN-Sync) nutzbar machen. ## Review-Bereiche ### A. Tauri-App-Struktur & Lifecycle - [ ] `lib.rs` vs. `main.rs`, Plugin-Registrierung, `setup`-Hook - [ ] Async-Bootstrap (`block_on` im Setup) — Alternativen: `tauri::async_runtime::spawn`, State-Initialisierung mit `OnceCell`/`ManagedState` - [ ] Fenster-/Webview-Konfiguration (`tauri.conf.json`) - [ ] Ressourcen-Bundling (`overlays`, `extensions`) — Dev vs. Release-Pfade ### B. IPC & Frontend-Integration - [ ] Abgrenzung: Tauri Commands vs. lokaler HTTP-API — wann was? - [ ] Typisierte Commands + `specta`/`tauri-specta` oder gemeinsame Types (Rust ↔ TS) - [ ] Fehlerpropagierung: einheitliches Error-Format statt `String` in Commands - [ ] Frontend: `@tauri-apps/api`-Nutzung, Fallback-Port-Logik in `api.ts` ### C. Security (Tauri 2) - [ ] CSP definieren und testen (Admin-UI + Overlay-Host) - [ ] Capabilities verfeinern — Principle of Least Privilege statt `core:default` - [ ] `tauri.conf.json` → `app.security` (dangerousRemoteDomainIpcAccess, assetProtocol, …) - [ ] Lokaler Server: Bind-Adresse, CORS, Auth für Admin-Endpoints - [ ] Secrets (Twitch Tokens, AI API Keys) — Speicherung, Logging, Memory ### D. Rust-Backend-Architektur - [ ] Modul-Grenzen: `connectors/`, `server/`, `events/`, `db/`, `extensions/` - [ ] `AppState`-Design: Shared State, `RwLock`-Granularität, Testbarkeit - [ ] Event-Bus: Backpressure, Subscriber-Lifecycle, Fehlerbehandlung - [ ] Connector-Supervisor: Reconnect, Graceful Shutdown, Cancellation - [ ] Error-Handling: `thiserror`/`anyhow`-Konsistenz, keine `expect`/`unwrap` in Produktionspfaden ### E. Lokaler Server (Axum) - [ ] Router-Struktur, Middleware (CORS, Tracing, Timeouts) - [ ] WebSocket/SSE: Connection-Management, Heartbeats - [ ] Port-Konfiguration und Neustart-Verhalten - [ ] Vorbereitung auf #6 (LAN/Multi-PC): Bind `0.0.0.0`, TLS, Discovery ### F. Persistenz & Daten - [ ] SQLite: Migrations, Connection-Pool, Transaktionen - [ ] Settings-Schema (JSON in DB) — Validierung, Versionierung - [ ] Extension-/Overlay-Pfade: User-Data vs. Bundle-Resources ### G. Observability & Debugging - [ ] `tracing`/`tracing-subscriber`: strukturierte Logs, Log-Rotation - [ ] Dev vs. Release Log-Level - [ ] Optional: Crash-Reporting / Fehlerdialog in der UI ### H. Build, CI & Distribution - [ ] `Cargo.toml`: Feature-Flags, `tokio` full → gezielte Features - [ ] Cross-Compile (Windows von macOS), Code-Signing-Vorbereitung - [ ] Forgejo CI: `make ci` vs. vollständige Integrationstests - [ ] Updater-Plugin (`tauri-plugin-updater`) — Bedarf und Strategie ### I. Tests - [ ] Unit-Tests für kritische Module (Event-Bus, DB, Connector-Parser) - [ ] Integrationstests für HTTP-API (Axum `TestClient`) - [ ] Frontend: minimale Smoke-Tests oder E2E (optional, niedrige Priorität) ### J. Dokumentation - [ ] Architekturdiagramm (Module, Datenfluss Admin ↔ Server ↔ OBS) - [ ] ADRs für zentrale Entscheidungen (HTTP vs. IPC, Event-Bus-Design) - [ ] `AGENTS.md` / README um Architektur-Sektion ergänzen ## Deliverables - [ ] Review-Dokument (Markdown im Repo oder Issue-Kommentar) mit Findings nach Priorität: **kritisch / hoch / mittel / niedrig** - [ ] Umsetzungs-Backlog: dieses Issue oder Follow-up-Issues pro Maßnahmenblock - [ ] Mindestens die **kritischen** und **hohen** Security-/Lifecycle-Punkte umgesetzt oder bewusst dokumentiert (Won't fix + Begründung) ## Akzeptanz - [ ] Alle Review-Bereiche A–J sind durchgearbeitet und dokumentiert - [ ] CSP und Capabilities sind bewusst konfiguriert (nicht mehr `null` / blind `default`) - [ ] IPC-Strategie (Commands vs. HTTP) ist festgelegt und dokumentiert - [ ] Keine `block_on`/`expect`-Hotspots mehr im Startup-Pfad ohne Begründung - [ ] Architekturdiagramm und mindestens 2 ADRs liegen vor ## Bezug zu bestehendem Backlog - [#4](https://repository.hildebrandt.io/frank/streamertool/issues/4) Extension-Sandbox — baut auf Security-Review (C) auf - [#6](https://repository.hildebrandt.io/frank/streamertool/issues/6) LAN-Sync — baut auf Server-Review (E) auf ## Vorgehen (Vorschlag) 1. Read-only Review aller Module + `tauri.conf.json` / Capabilities 2. Findings sammeln und priorisieren 3. Quick Wins (CSP, Capabilities, Logging) in kleinen PRs 4. Größere Refactors (IPC-Typisierung, Startup-Lifecycle) in separaten PRs

frank referenced this issue

2026-07-12 01:21:44 +02:00

Secrets in nativen Credential Stores speichern #11

frank referenced this issue

2026-07-12 01:22:26 +02:00

Graceful Shutdown und Cancellation für Server und Connectoren #12

frank referenced this issue

2026-07-12 01:22:26 +02:00

Settings-Schema versionieren und atomar validieren #13

frank referenced this issue

2026-07-12 01:22:27 +02:00

HTTP-, WebSocket- und SSE-Integrationstests #14

frank referenced this issue

2026-07-12 01:22:27 +02:00

LAN-Transport weiter härten: TLS, Discovery und Remote-Sync #15

frank referenced this issue

2026-07-12 01:22:28 +02:00

Persistente strukturierte Logs und Diagnoseoberfläche #16

frank referenced this issue

2026-07-12 01:22:32 +02:00

Release-Härtung: Signing, Updater und Plattform-Matrix #17

frank referenced this issue

2026-07-12 01:22:57 +02:00

LAN-Transport weiter härten: TLS, Discovery und Remote-Sync #15

frank referenced this issue from a commit

2026-07-12 01:24:38 +02:00

refactor: harden architecture and document review (#7)

frank commented

2026-07-12 01:24:52 +02:00

Author

Owner

Abschluss

Umgesetzt mit Commit 665520c:

vollständiges Architektur-Review A–J mit priorisierten Findings
CSP und minimale Tauri-Capabilities
typisierter IPC-Bootstrap ohne stillen Port-Fallback
Bearer-Auth für alle Admin-APIs, getrennte Router-Zonen und restriktives CORS
Startup-Fehler ohne expect, begründeter synchroner Bootstrap
Event-Bus-/SQLite-Härtung und gezielte Tokio-Features
Architekturdiagramm und ADR-0001 bis ADR-0003

Verifikation

make ci erfolgreich
40 Rust-Tests bestanden
TypeScript-Typecheck und Vite-Produktionsbuild erfolgreich
Cargo-Checks für Host und macOS-Target erfolgreich
Dev-Smoke: App und Server starten; /health → 200, /api/settings ohne Token → 401, mit Bearer-Token → 200

Folge-Backlog

#11 Secrets in nativen Credential Stores
#12 Graceful Shutdown und Cancellation
#13 versioniertes/atomares Settings-Schema
#14 HTTP-/WS-/SSE-Integrationstests
#15 TLS, Discovery und Remote-Sync
#16 persistente Logs und Diagnoseoberfläche
#17 Signing, Updater und Plattform-Matrix

Damit sind die Akzeptanzkriterien von #7 erfüllt.

## Abschluss Umgesetzt mit Commit [`665520c`](https://repository.hildebrandt.io/frank/streamertool/commit/665520c): - vollständiges Architektur-Review A–J mit priorisierten Findings - CSP und minimale Tauri-Capabilities - typisierter IPC-Bootstrap ohne stillen Port-Fallback - Bearer-Auth für alle Admin-APIs, getrennte Router-Zonen und restriktives CORS - Startup-Fehler ohne `expect`, begründeter synchroner Bootstrap - Event-Bus-/SQLite-Härtung und gezielte Tokio-Features - Architekturdiagramm und ADR-0001 bis ADR-0003 ### Verifikation - `make ci` erfolgreich - 40 Rust-Tests bestanden - TypeScript-Typecheck und Vite-Produktionsbuild erfolgreich - Cargo-Checks für Host und macOS-Target erfolgreich - Dev-Smoke: App und Server starten; `/health` → 200, `/api/settings` ohne Token → 401, mit Bearer-Token → 200 ### Folge-Backlog - #11 Secrets in nativen Credential Stores - #12 Graceful Shutdown und Cancellation - #13 versioniertes/atomares Settings-Schema - #14 HTTP-/WS-/SSE-Integrationstests - #15 TLS, Discovery und Remote-Sync - #16 persistente Logs und Diagnoseoberfläche - #17 Signing, Updater und Plattform-Matrix Damit sind die Akzeptanzkriterien von #7 erfüllt.

frank closed this issue

2026-07-12 01:24:59 +02:00

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

frank/streamertool#7

No description provided.

Rows
Columns