Whitepaper

Ang dokumentong ito ay nagbibigay ng malalim na pagtingin sa architectural design, technology choices, at underlying implementation logic ng mga pangunahing feature sa WSL Dashboard, na inilaan para sa mga developer at advanced user na naghahanap ng teknikal na perspektibo.

1. Architecture Overview

Ang WSL Dashboard ay gumagamit ng klasikong reactive UI-driven + async backend task architecture, sinasamantala ang type system at ownership model ng Rust para garantiyahin ang memory safety at high-concurrency performance.

Mga Core Component

• Frontend (UI): Nakabase sa Slint declarative interface. Ang UI thread ay responsable sa rendering at user interaction.
• Backend (Runtime): Nakabase sa Tokio async runtime. Responsable sa dispatch at execution ng system commands (CLI), file I/O, at network listeners.
• Communication: Ang UI thread at async tasks ay mahusay at securely na nagko-communicate sa pamamagitan ng Channels (MPSC) at Shared State (Arc/Mutex/RwLock).

2. Technology Rationale

Bakit Rust?

• Performance: Zero-cost abstractions, naka-compile sa native machine code, walang GC pauses.
• Memory Safety: Inaalis ang buffer overflows at data races sa compile time — kritikal para sa tool na nag-ooperate sa system level (disk migration, network configuration).
• Binary Size: Statically links lahat ng dependencies para makabuo ng single-file portable executable.

Bakit Slint + Skia?

• Declarative Syntax: Hinihiwalay ang UI description mula sa logic, pinapanatiling malinis at maintainable ang codebase.
• Skia Rendering: Direktang sinasamantala ang GPU acceleration (sa pamamagitan ng Skia engine), nagbibigay ng sub-pixel text clarity at buttery-smooth animations.
• Low Overhead: Kumpara sa Electron o WPF, ang runtime footprint ng Slint ay minimal.

3. Mga Key Technical Implementation

3.1 WSL Instance Detection & Parsing

Kinukuha ng app ang real-time instance status sa pamamagitan ng pagtawag sa wsl.exe --list --verbose at pag-parse sa output nito (hina-handle ang UTF-16 encoding).

• Low-level decoding: Isang custom-built, efficient encoder/decoder ang tinitiyak ng tamang output parsing sa iba't ibang Windows environment na may iba't ibang regional settings.
• State synchronization: Gumagamit ng dual-sync mechanism ng timed polling na pinagsama sa operation-triggered updates.

3.2 Disk Image Migration (VHDX Move)

Ang migration feature ay sinasamantala ang WSL import/export mechanism, ngunit may mataas na antas ng abstraction at atomicity.

• Transactional guarantee: Bago magsimula ang migration, ni-lock ng app ang target distribusyon sa pamamagitan ng Mutex para maiwasan ang concurrent operations na maaaring maging sanhi ng data corruption.
• Auto-registration: Pagkatapos ng migration, awtomatikong ni-redirect ng app ang VHDX path at muling ni-register ang distribusyon — walang manual intervention na kinakailangan.

3.3 Port Forwarding & Firewall Automation

Ang networking feature ay lampas sa simpleng netsh interface portproxy call.

• Rule lifecycle management: Awtomatikong dine-detect ng app ang mga existing firewall rule. Kapag lumikha ang user ng forwarding rule, sabay nitong nililikha ang inbound exception rule sa pamamagitan ng Windows API o CLI.
• Automatic IP resolution: Sa pamamagitan ng pag-parse sa output ng wsl hostname -I, awtomatikong ni-map ang virtual network IPs sa pagitan ng host at instance.

3.4 USBIP Integration

Sinasamantala ang usbipd-win command-line interface.

• Elevation handling: Ang bind operations ay nangangailangan ng administrator privileges. Ang backend ay nagpapatupad ng graceful UAC elevation request forwarding.
• State machine: Pinapanatili ang internal USB device connection state machine para matiyak ang full traceability ng Attach/Detach operations.

3.5 Resource Monitoring & Minimal Footprint

Mino-monitor ng app ang sarili nitong resource usage sa pamamagitan ng pagtawag sa native Windows APIs (hal., GetProcessMemoryInfo).

• Extreme efficiency: Sa silent tray mode, aktibong nag-release ang app ng mga hindi kinakailangang resources. Para sa standard character sets (hal., English), ang memory usage ay maaaring bumaba sa 10MB; para sa complex character sets (hal., CJK), ito ay humigit-kumulang 38MB dahil sa mas malaking font rendering cache na kinakailangan.

4. Performance Benchmarks

Metric	Target / Na-measure	Optimization Approach
Startup Time	< 500ms	Pre-compiled Slint interface, minimizing runtime parsing.
Base Memory (tray)	~10MB	Minimized background polling frequency, on-demand release ng render cache.
CPU Usage (idle)	< 0.1%	Windows event-driven model, walang busy-loop polling.
Render Frame Rate	60 FPS	Skia GPU acceleration, sub-pixel anti-aliased rendering.

5. Backend Task Dispatch Logic

Para matiyak ang UI responsiveness, lahat ng time-consuming operations (hal., pag-export ng VHDX) ay dinidispatch bilang async tasks:

1. Request encapsulation: Ang UI thread ay naka-encapsulate ng user actions sa Command messages.
2. Message channel: Ipinapadala ang mga ito sa background task handler sa pamamagitan ng tokio::sync::mpsc.
3. State callback: Sa sandaling matapos ang background task, ina-update nito ang UI sa pamamagitan ng callback o shared state. Ang disenyo na ito ay tinitiyak na kahit habang nagpoproseso ng multi-gigabyte backup task, ang interface ay ganap na responsive sa user input.

6. Security Considerations

• Atomic operations: Ang pre-flight validation ay ipinatupad para sa mga kritikal na instance unregistration at migration operations.
• UAC elevation management: Ang elevated privileges ay hinihiling lamang kapag kinakailangan (hal., pag-bind ng USB device), sinusunod ang prinsipyo ng least privilege.
• Local storage: Ang configuration ay naka-save lamang sa local ~\.wsldashboard directory na walang anumang cloud sync, pinoprotektahan ang user privacy.