Whitepaper

Questo documento fornisce un approfondimento sul design architettonico, le scelte tecnologiche e la logica di implementazione sottostante delle funzionalità chiave di WSL Dashboard, destinato a sviluppatori e utenti avanzati che cercano una prospettiva tecnica.

1. Panoramica dell'architettura

WSL Dashboard adotta un'architettura classica UI reattiva guidata + task backend asincroni, sfruttando il sistema di tipi e il modello di proprietà di Rust per garantire la sicurezza della memoria e prestazioni ad alta concorrenza.

Componenti principali

• Frontend (UI): Costruito sull'interfaccia dichiarativa Slint. Il thread UI è responsabile del rendering e dell'interazione con l'utente.
• Backend (Runtime): Costruito sul runtime asincrono Tokio. Responsabile dell'invio e dell'esecuzione di comandi di sistema (CLI), I/O file e listener di rete.
• Comunicazione: Il thread UI e i task asincroni comunicano in modo efficiente e thread-safe tramite Canali (MPSC) e Stato condiviso (Arc/Mutex/RwLock).

2. Razionale tecnologico

Perché Rust?

• Prestazioni: Astrazioni a costo zero, compilato in codice macchina nativo, nessuna pausa GC.
• Sicurezza della memoria: Elimina buffer overflow e race condition in fase di compilazione — critico per uno strumento che opera a livello di sistema (migrazione disco, configurazione di rete).
• Dimensione binaria: Collega staticamente tutte le dipendenze per produrre un singolo eseguibile portatile.

Perché Slint + Skia?

• Sintassi dichiarativa: Separa la descrizione UI dalla logica, mantenendo il codebase pulito e manutenibile.
• Rendering Skia: Sfrutta direttamente l'accelerazione GPU (tramite il motore Skia), fornendo nitidezza del testo sub-pixel e animazioni fluide.
• Basso overhead: Rispetto a Electron o WPF, l'impronta runtime di Slint è minima.

3. Implementazioni tecniche chiave

3.1 Rilevamento e parsing delle istanze WSL

L'applicazione recupera lo stato delle istanze in tempo reale chiamando wsl.exe --list --verbose e analizzandone l'output (gestione della codifica UTF-16).

• Decodifica a basso livello: Un encoder/decoder personalizzato ed efficiente garantisce il corretto parsing dell'output in ambienti Windows con impostazioni regionali diverse.
• Sincronizzazione dello stato: Utilizza un meccanismo di sincronizzazione duale di polling temporizzato combinato con aggiornamenti attivati da operazioni.

3.2 Migrazione dell'immagine disco (Spostamento VHDX)

La funzione di migrazione sfrutta il meccanismo import/export di WSL, ma con un alto livello di astrazione e atomicità.

• Garanzia transazionale: Prima dell'inizio della migrazione, l'applicazione blocca la distribuzione di destinazione tramite un Mutex per prevenire che operazioni simultanee causino corruzione dei dati.
• Registrazione automatica: Al completamento della migrazione, l'applicazione reindirizza automaticamente il percorso VHDX e ri-registra la distribuzione — nessun intervento manuale necessario.

3.3 Inoltro porte e automazione del firewall

La funzione di rete va oltre una semplice chiamata netsh interface portproxy.

• Gestione del ciclo di vita delle regole: L'app rileva automaticamente le regole del firewall esistenti. Quando un utente crea una regola di inoltro, crea simultaneamente una regola di eccezione in entrata tramite Windows API o CLI.
• Risoluzione IP automatica: Analizzando l'output di wsl hostname -I, mappa automaticamente gli IP di rete virtuali tra host e istanza.

3.4 Integrazione USBIP

Sfrutta l'interfaccia a riga di comando usbipd-win.

• Gestione dell'elevazione: Le operazioni di bind richiedono privilegi di amministratore. Il backend implementa un'elegante inoltro delle richieste di elevazione UAC.
• Macchina a stati: Mantiene una macchina a stati interna per la connessione dei dispositivi USB per garantire la tracciabilità completa delle operazioni Attach/Detach.

3.5 Monitoraggio delle risorse e impronta minima

L'app monitora il proprio utilizzo delle risorse chiamando API Windows native (es. GetProcessMemoryInfo).

• Efficienza estrema: In modalità tray silenziosa, l'app rilascia proattivamente le risorse UI non necessarie. Per set di caratteri standard (es. inglese), l'uso della memoria può essere basso fino a 10MB; per set di caratteri complessi (es. CJK), è di circa 38MB a causa della cache di rendering dei font più grande.

4. Benchmark delle prestazioni

Metrica	Obiettivo / Misurato	Approccio di ottimizzazione
Tempo di avvio	< 500ms	Interfaccia Slint pre-compilata, minimizzazione del parsing a runtime.
Memoria di base (tray)	~10MB	Frequenza di polling in background minimizzata, rilascio della cache di rendering su richiesta.
Utilizzo CPU (inattivo)	< 0.1%	Modello Windows basato su eventi, nessun polling busy-loop.
Frame rate di rendering	60 FPS	Accelerazione GPU Skia, rendering anti-aliasing sub-pixel.

5. Logica di dispatch dei task backend

Per garantire la reattività dell'UI, tutte le operazioni che richiedono tempo (es. esportazione VHDX) vengono inviate come task asincroni:

1. Incapsulamento della richiesta: Il thread UI incapsula le azioni dell'utente in messaggi Command.
2. Canale dei messaggi: Li invia al gestore dei task in background tramite tokio::sync::mpsc.
3. Callback di stato: Una volta completato il task in background, aggiorna l'UI tramite callback o stato condiviso. Questo design garantisce che anche durante l'elaborazione di un task di backup multi-gigabyte, l'interfaccia rimanga completamente reattiva all'input dell'utente.

6. Considerazioni sulla sicurezza

• Operazioni atomiche: La validazione pre-volo è implementata per le operazioni critiche di deregistrazione dell'istanza e migrazione.
• Gestione elevazione UAC: I privilegi elevati vengono richiesti solo quando necessario (es. binding di un dispositivo USB), seguendo il principio del privilegio minimo.
• Archiviazione locale: La configurazione viene salvata solo nella directory locale ~\.wsldashboard senza alcuna sincronizzazione cloud, proteggendo la privacy dell'utente.