Biała księga

Niniejszy dokument szczegółowo omawia projekt architektoniczny WSL Dashboard, wybór technologii oraz logikę implementacji kluczowych funkcji, zapewniając programistom i zaawansowanym użytkownikom spojrzenie z techniczną głębią.

1. Przegląd architektury

WSL Dashboard wykorzystuje klasyczną architekturę „reaktywny UI + asynchroniczne zadania w tle”, korzystając z systemu typów i modelu własności Rust, aby zapewnić bezpieczeństwo pamięci i wysoką wydajność przy pracy współbieżnej.

Kluczowe komponenty

• Frontend (UI): deklaratywny interfejs oparty na Slint. Wątek UI odpowiada za renderowanie i interakcję z użytkownikiem.
• Backend (Runtime): asynchroniczne środowisko uruchomieniowe oparte na Tokio. Odpowiada za dystrybucję i wykonywanie poleceń systemowych (CLI), wejście/wyjście plików oraz nasłuch sieciowy.
• Komunikacja: wątek UI i zadania asynchroniczne wymieniają dane przez Channel (MPSC) i Shared State (Arc/Mutex/RwLock) — efektywnie i bezpiecznie dla wątków.

2. Uzasadnienie wyboru technologii

Dlaczego Rust?

• Wydajność: abstrakcje o zerowym koszcie, kompilacja do natywnego kodu maszynowego, bez pauz garbage collectora.
• Bezpieczeństwo pamięci: przepełnienia bufora i wyścigi danych są eliminowane na etapie kompilacji — to kluczowe dla narzędzia wykonującego niskopoziomowe operacje systemowe (migracja dysków, konfiguracja sieci).
• Rozmiar binariów: statyczne łączenie wszystkich zależności daje jeden przenośny plik wykonywalny.

Dlaczego Slint + Skia?

• Składnia deklaratywna: opis interfejsu oddzielony od logiki — kod łatwy w utrzymaniu.
• Renderowanie Skia: bezpośrednie wykorzystanie przyspieszenia GPU (przez silnik Skia) zapewnia subpikselową ostrość tekstu i płynne animacje.
• Niskie narzuty: w porównaniu z Electronem lub WPF narzut środowiska uruchomieniowego Slint jest minimalny.

3. Kluczowe implementacje techniczne

3.1 Wykrywanie i analiza instancji WSL

Aplikacja uzyskuje stan instancji w czasie rzeczywistym, wywołując wsl.exe --list --verbose i analizując jego wynik (z obsługą kodowania UTF-16).

• Niskopoziomowe dekodowanie: własny wydajny kodek gwarantuje poprawną analizę wyników w środowiskach Windows z różnymi ustawieniami regionalnymi.
• Synchronizacja stanu: podwójny mechanizm — okresowe odpytywanie + synchronizacja inicjowana operacjami.

3.2 Migracja obrazów dysków (VHDX Move)

Funkcja migracji wykorzystuje mechanizm importu/eksportu WSL, ale z wysokim stopniem abstrakcji i atomowości.

• Gwarancja transakcyjności: przed rozpoczęciem migracji aplikacja blokuje docelową dystrybucję mutexem (Mutex), zapobiegając uszkodzeniu danych przez operacje współbieżne.
• Automatyczna rejestracja: po zakończeniu migracji aplikacja automatycznie przekierowuje ścieżkę VHDX i ponownie rejestruje dystrybucję — ingerencja użytkownika nie jest potrzebna.

3.3 Przekierowanie portów i automatyzacja zapory

Funkcje sieciowe to nie tylko wywołanie netsh interface portproxy.

• Zarządzanie cyklem życia reguł: aplikacja automatycznie wykrywa istniejące reguły zapory. Podczas tworzenia przekierowania aplikacja przez Windows API lub CLI synchronizuje utworzenie reguły wyjątku dla ruchu przychodzącego.
• Automatyczne pobieranie IP: analizując wynik wsl hostname -I, automatycznie mapuje wirtualne adresy IP hosta i instancji.

3.4 Integracja USBIP

Wykorzystywany jest interfejs wiersza poleceń usbipd-win.

• Obsługa podnoszenia uprawnień: operacja powiązania wymaga uprawnień administratora; w logice zaplecza zaimplementowano poprawne przekazywanie żądania podniesienia uprawnień UAC.
• Automat stanów: wewnętrznie utrzymywany jest automat stanu połączenia urządzenia USB, zapewniający możliwość prześledzenia procesów Attach/Detach.

3.5 Monitorowanie zasobów i lekkość

Aplikacja monitoruje własne zużycie zasobów, wywołując natywne API Windows (np. GetProcessMemoryInfo).

• Ekstremalna lekkość: w cichym trybie zasobnika aplikacja aktywnie zwalnia niepotrzebne zasoby UI. Dla standardowych zestawów znaków, takich jak angielski, zużycie pamięci może wynosić zaledwie 10 MB; dla złożonych zestawów znaków (chiński, japoński, koreański) ze względu na ładowanie dużego bufora renderowania czcionek zużycie wynosi około 38 MB.

4. Wskaźniki optymalizacji wydajności

Wskaźnik	Cel/fakt	Metoda optymalizacji
Szybkość uruchamiania	< 500 ms	Wstępna kompilacja interfejsu Slint, mniej analiz w czasie wykonania.
Podstawowa pamięć (zasobnik)	~10 MB	Minimalizacja częstotliwości odpytywania w tle, zwalnianie bufora renderowania na żądanie.
Zużycie CPU (w spoczynku)	< 0,1%	Zdarzeniowy model Windows, brak pustych pętli odpytywania.
Częstotliwość klatek renderowania	60 FPS	Przyspieszenie GPU przez Skia, subpikselowe wygładzanie.

5. Logika dystrybucji zadań w tle

Aby zapewnić płynność UI, wszystkie kosztowne operacje (np. eksport VHDX) są dystrybuowane przez zadania asynchroniczne:

1. Enkapsulacja żądania: wątek UI enkapsuluje działanie użytkownika w komunikat Command.
2. Kanał komunikatów: wysyłka przez tokio::sync::mpsc do procesora zadań w tle.
3. Przekazanie stanu zwrotnego: po zakończeniu zadania w tle UI aktualizuje się przez wywołanie zwrotne lub stan współdzielony. Ta konstrukcja gwarantuje, że nawet podczas przetwarzania zadań tworzenia kopii zapasowych o rozmiarze kilku GB interfejs pozostaje responsywny na kliknięcia użytkownika.

6. Zagadnienia bezpieczeństwa

• Operacje atomowe: dla kluczowych operacji odinstalowania i migracji instancji zaimplementowano walidację wstępną.
• Zarządzanie podnoszeniem uprawnień UAC: uprawnienia są żądane tylko w razie potrzeby (np. przy powiązaniu urządzeń USB), zgodnie z zasadą najmniejszych uprawnień.
• Przechowywanie lokalne: konfiguracja jest przechowywana wyłącznie lokalnie w ~\.wsldashboard, bez żadnej synchronizacji w chmurze, co chroni prywatność użytkownika.