Whitepaper

Questo documento esamina in profondità la progettazione architettonica di WSL Dashboard, le scelte tecnologiche e la logica di implementazione di base delle funzionalità chiave, offrendo una prospettiva tecnica approfondita per sviluppatori e utenti avanzati.

1. Panoramica dell'architettura

WSL Dashboard adotta la classica architettura UI reattiva + attività asincrone in backend, sfruttando il sistema dei tipi e il modello di ownership di Rust per garantire sicurezza della memoria e alte prestazioni concorrenti.

Componenti principali

• Frontend (UI): interfaccia dichiarativa basata su Slint. Il thread dell'UI si occupa del rendering e dell'interazione con l'utente.
• Backend (Runtime): runtime asincrono basato su Tokio. Si occupa della distribuzione e dell'esecuzione dei comandi di sistema (CLI), dell'I/O dei file e dell'ascolto di rete.
• Comunicazione: il thread dell'UI e le attività asincrone comunicano in modo efficiente e thread-safe tramite Channel (MPSC) e Stato condiviso (Arc/Mutex/RwLock).

2. Ragioni delle scelte tecnologiche

Perché Rust?

• Prestazioni: astrazioni a costo zero, compilato in codice macchina nativo, senza jitter del GC.
• Sicurezza della memoria: elimina a livello di compilazione buffer overflow e race condition, elementi cruciali per uno strumento che opera su componenti di basso livello del sistema (come migrazione dei dischi e configurazione di rete).
• Dimensione del binario: collega staticamente tutte le dipendenze, producendo un eseguibile portatile a file singolo.

Perché Slint + Skia?

• Sintassi dichiarativa: la descrizione dell'interfaccia è separata dalla logica, codice facile da mantenere.
• Rendering Skia: utilizza direttamente l'accelerazione GPU (tramite il motore Skia), offrendo testo con nitidezza a livello sub-pixel e animazioni fluide.
• Basso overhead: rispetto a Electron o WPF, l'overhead di runtime di Slint è minimo.

3. Implementazioni tecniche chiave

3.1 Rilevamento e analisi delle istanze WSL

L'applicazione ottiene in tempo reale lo stato delle istanze chiamando wsl.exe --list --verbose e analizzando il suo output (gestendo la codifica UTF-16).

• Decodifica di basso livello: un codificatore/decodificatore efficiente sviluppato internamente, che garantisce la corretta analisi dell'output su sistemi Windows con diverse impostazioni regionali.
• Sincronizzazione dello stato: doppio meccanismo di sincronizzazione tramite polling periodico + operazioni che lo innescano.

3.2 Migrazione dell'immagine disco (VHDX Move)

La funzione di migrazione sfrutta il meccanismo di importazione/esportazione di WSL, ma con un elevato livello di astrazione e atomicità.

• Garanzia transazionale: prima dell'inizio della migrazione, l'applicazione blocca la distribuzione di destinazione tramite un mutex, prevenendo danni ai dati causati da operazioni concorrenti.
• Registrazione automatica: al termine della migrazione, l'applicazione reindirizza automaticamente il percorso del VHDX e registra nuovamente la distribuzione, senza interventi manuali da parte dell'utente.

3.3 Automazione dell'inoltro delle porte e del firewall

La funzione di rete non è una semplice chiamata a netsh interface portproxy.

• Gestione del ciclo di vita delle regole: l'applicazione rileva automaticamente le regole firewall esistenti. Quando l'utente crea un inoltro, l'applicazione crea sincronicamente la regola di eccezione in ingresso tramite API Windows o CLI.
• Acquisizione automatica dell'IP: analizzando il risultato di wsl hostname -I, mappa automaticamente l'IP della rete virtuale tra host e istanza.

3.4 Integrazione USBIP

Utilizza l'interfaccia da riga di comando di usbipd-win.

• Gestione dell'elevazione dei privilegi: le operazioni di binding richiedono privilegi di amministratore; il backend implementa una richiesta di elevazione UAC elegante e inoltrata.
• Macchina a stati: internamente viene mantenuta una macchina a stati per la connessione dei dispositivi USB, garantendo la tracciabilità del processo Attach/Detach.

3.5 Monitoraggio delle risorse e leggerezza

L'applicazione monitora il proprio utilizzo delle risorse chiamando API native di Windows (come GetProcessMemoryInfo).

• Estrema leggerezza: in modalità silenziosa nella barra delle applicazioni, l'applicazione rilascia proattivamente risorse UI non necessarie. Per set di caratteri standard come l'inglese, l'occupazione di memoria può scendere fino a 10MB; per set di caratteri complessi come cinese, giapponese e coreano, a causa del caricamento di cache di rendering dei font più grandi, l'occupazione è di circa 38MB.

4. Indicatori di ottimizzazione delle prestazioni

Indicatore	Obiettivo/misurato	Mezzi di ottimizzazione
Velocità di avvio	< 500ms	Interfaccia Slint precompilata, riduce l'analisi a runtime.
Memoria di base (barra delle applicazioni)	~10MB	Riduce al minimo la frequenza del polling in background, rilascia le cache di rendering su richiesta.
Occupazione CPU (a riposo)	< 0.1%	Usa il modello di eventi di Windows, evita il polling a ciclo vuoto.
Frame rate del rendering	60 FPS	Accelerazione GPU Skia, antialiasing a livello sub-pixel.

5. Logica di distribuzione delle attività in backend

Per garantire la fluidità dell'UI, tutte le operazioni dispendiose (come l'esportazione di VHDX) vengono distribuite tramite attività asincrone:

1. Incapsulamento della richiesta: il thread dell'UI incapsula l'operazione dell'utente in un messaggio Command.
2. Canale di messaggi: inviato all'elaboratore di attività in background tramite tokio::sync::mpsc.
3. Restituzione dello stato: al termine dell'attività in background, l'UI viene aggiornata tramite callback o stato condiviso. Questo design garantisce che anche durante l'elaborazione di attività di backup di diversi GB, l'interfaccia continui a rispondere in tempo reale ai clic dell'utente.

6. Considerazioni sulla sicurezza

• Operazioni atomiche: per lo smontaggio e la migrazione critici delle istanze, sono implementate validazioni preliminari.
• Gestione dell'elevazione UAC: richiede i permessi solo quando necessario (come per il binding dei dispositivi USB), seguendo il principio dei privilegi minimi.
• Archiviazione locale: la configurazione viene salvata solo localmente in ~\.wsldashboard, senza alcuna sincronizzazione su cloud, proteggendo la privacy dell'utente.