Whitepaper

This document takes an in-depth look at WSL Dashboard's architecture design, technology choices, and the underlying implementation logic of its key features, providing a deep technical perspective for developers and advanced users.

1. Architecture Overview

WSL Dashboard uses a classic reactive UI-driven + asynchronous backend task architecture, leveraging the Rust language's type system and ownership model to ensure memory safety and high-concurrency performance.

Core Components

• Frontend (UI): A declarative interface based on Slint. The UI thread handles rendering and user interaction.
• Backend (Runtime): An asynchronous runtime based on Tokio. It handles dispatching and executing system commands (CLI), file I/O, and network listening.
• Communication: The UI thread communicates with asynchronous tasks efficiently and thread-safely through Channels (MPSC) and Shared State (Arc/Mutex/RwLock).

2. Reasons for Technology Choices

Why Rust?

• Performance: Zero-cost abstractions, compiled to native machine code, no GC pauses.
• Memory safety: Buffer overflows and data races are eliminated at compile time — crucial for a tool that deals with low-level system operations (such as disk migration and network configuration).
• Binary size: Statically links all dependencies, producing a single-file portable executable.

Why Slint + Skia?

• Declarative syntax: UI description is separated from logic, making the code easy to maintain.
• Skia rendering: Direct GPU acceleration (through the Skia engine) provides subpixel-crisp text and silky-smooth animations.
• Low overhead: Compared to Electron or WPF, Slint's runtime overhead is minimal.

3. Key Technical Implementations

3.1 WSL Instance Detection and Parsing

The app obtains instance status in real time by calling wsl.exe --list --verbose and parsing its output (handling UTF-16 encoding).

• Low-level decoding: A self-developed efficient codec ensures the output is parsed correctly on Windows systems with different locale settings.
• State synchronization: A dual synchronization mechanism of periodic polling plus operation-triggered updates.

3.2 Disk Image Migration (VHDX Move)

The migration feature leverages WSL's import/export mechanism but with a high degree of abstraction and atomic processing.

• Transactional guarantees: Before migration starts, the app locks the target distribution with a mutex (Mutex) to prevent concurrent operations from corrupting data.
• Automatic registration: After migration completes, the app automatically redirects the VHDX path and re-registers the distribution, with no manual intervention needed.

3.3 Port Forwarding and Firewall Automation

The networking feature is more than a simple netsh interface portproxy call.

• Rule lifecycle management: The app automatically detects existing firewall rules. When a user creates a forwarding rule, the app creates the matching inbound exception rule in sync via Windows APIs or the CLI.
• Automatic IP retrieval: By parsing the wsl hostname -I output, it automatically maps the virtual network IPs between the host and instances.

3.4 USBIP Integration

Leverages usbipd-win's command-line interface.

• Elevation handling: Binding requires administrator privileges; the backend implements graceful forwarding of UAC elevation requests.
• State machine: An internal USB device connection state machine ensures the traceability of the Attach/Detach process.

3.5 Resource Monitoring and Lightweight Design

The app monitors its own resource usage by calling native Windows APIs (such as GetProcessMemoryInfo).

• Extremely lightweight: In tray silent mode, the app proactively releases unnecessary UI resources. For standard character sets such as English, memory usage can be as low as 10MB; for complex character sets such as Chinese/Japanese/Korean, usage is around 38MB due to the need to load larger font rendering caches.

4. Performance Optimization Metrics

Metric	Target/Measured	Optimization
Startup speed	< 500ms	Pre-compiled Slint UI reduces runtime parsing.
Baseline memory (tray)	~10MB	Minimizes background polling frequency and releases rendering caches on demand.
CPU usage (idle)	< 0.1%	Uses the Windows event-driven model to avoid empty polling loops.
Render frame rate	60 FPS	Skia GPU acceleration with subpixel anti-aliased rendering.

5. Backend Task Dispatch Logic

To keep the UI smooth, all time-consuming operations (such as exporting VHDX) are dispatched as asynchronous tasks:

1. Request encapsulation: The UI thread encapsulates user actions into Command messages.
2. Message channel: Sent to the background task handler via tokio::sync::mpsc.
3. State feedback: After the background task completes, the UI is updated through callbacks or shared state. This design ensures the interface still responds to user clicks in real time even while processing backups of several GB.

6. Security Considerations

• Atomic operations: Pre-validation is implemented for critical instance unregister and migration operations.
• UAC elevation management: Permissions are requested only when necessary (such as binding USB devices), following the principle of least privilege.
• Local storage: Configuration is stored only locally in ~\.wsldashboard, with no cloud synchronization, protecting user privacy.