Whitepaper

Este documento explora em profundidade o design da arquitetura, as escolhas técnicas e a lógica de implementação subjacente dos recursos principais do WSL Dashboard, com o objetivo de oferecer aos desenvolvedores e usuários avançados uma perspectiva técnica aprofundada.

1. Visão geral da arquitetura

O WSL Dashboard adota a clássica arquitetura de UI reativa + tarefas assíncronas no backend, usando o sistema de tipos e o modelo de propriedade da linguagem Rust para garantir segurança de memória e alto desempenho de concorrência.

Componentes principais

• Frontend (UI): interface declarativa baseada em Slint. A thread da UI é responsável pela renderização e interação com o usuário.
• Backend (Runtime): runtime assíncrono baseado em Tokio. Responsável por distribuir e executar comandos do sistema (CLI), I/O de arquivos e escuta de rede.
• Comunicação: a thread da UI e as tarefas assíncronas se comunicam de forma eficiente e segura entre threads por meio de Channel (MPSC) e Shared State (Arc/Mutex/RwLock).

2. Justificativa das escolhas técnicas

Por que Rust?

• Desempenho: abstrações de custo zero, compilado para código de máquina nativo, sem instabilidade de GC.
• Segurança de memória: elimina overflow de buffer e corridas de dados em tempo de compilação; isso é crucial para ferramentas que envolvem operações de baixo nível do sistema (como migração de disco, configuração de rede).
• Tamanho do binário: vincula estaticamente todas as dependências, produzindo um executável portátil de arquivo único.

Por que Slint + Skia?

• Sintaxe declarativa: separação entre descrição da interface e lógica, código fácil de manter.
• Renderização Skia: utiliza diretamente a aceleração de GPU (por meio do motor Skia), proporcionando texto com nitidez em nível subpixel e animações fluidas.
• Baixo custo: comparado ao Electron ou WPF, o custo de runtime do Slint é mínimo.

3. Implementações técnicas principais

3.1 Detecção e análise de instâncias WSL

O aplicativo obtém o estado das instâncias em tempo real chamando wsl.exe --list --verbose e analisando sua saída (lidando com a codificação UTF-16).

• Decodificação subjacente: um codificador/decodificador próprio e eficiente garante a análise correta da saída em ambientes Windows com diferentes configurações regionais.
• Sincronização de estado: adota um mecanismo duplo de sincronização por polling periódico + acionamento por operação.

3.2 Migração de imagem de disco (VHDX Move)

O recurso de migração aproveita o mecanismo de importação/exportação do WSL, mas com alto nível de abstração e tratamento atômico.

• Garantia transacional: antes de iniciar a migração, o aplicativo bloqueia a distribuição de destino com um mutex (Mutex), evitando corrupção de dados por operações concorrentes.
• Registro automático: após a migração, o aplicativo redireciona automaticamente o caminho do VHDX e registra novamente a distribuição, sem intervenção manual do usuário.

3.3 Encaminhamento de portas e automação de firewall

O recurso de rede não é apenas uma simples chamada de netsh interface portproxy.

• Gerenciamento do ciclo de vida das regras: o aplicativo detecta automaticamente as regras de firewall existentes. Quando o usuário cria um encaminhamento, o aplicativo usa APIs do Windows ou CLI para criar sincronicamente regras de exceção de entrada.
• Obtenção automática de IP: analisando o resultado de wsl hostname -I, mapeia automaticamente os IPs da rede virtual entre o host e as instâncias.

3.4 Integração USBIP

Utiliza a interface de linha de comando do usbipd-win.

• Tratamento de elevação: a operação de vinculação requer privilégios de administrador; a lógica do backend implementa um encaminhamento elegante das solicitações de elevação de UAC.
• Máquina de estados: internamente, mantém uma máquina de estados de conexão de dispositivos USB, garantindo a rastreabilidade dos processos Attach/Detach.

3.5 Monitoramento de recursos e leveza

O aplicativo monitora seu próprio consumo de recursos chamando APIs nativas do Windows (como GetProcessMemoryInfo).

• Extremamente leve: no modo silencioso da bandeja, o aplicativo libera proativamente recursos de UI desnecessários. Para conjuntos de caracteres padrão, como o inglês, o consumo de memória pode chegar a apenas 10MB; para conjuntos de caracteres complexos, como chinês, japonês e coreano, devido à necessidade de carregar caches de renderização de fontes grandes, o consumo fica em cerca de 38MB.

4. Métricas de otimização de desempenho

Métrica	Alvo/Medido	Meio de otimização
Velocidade de inicialização	< 500ms	Interface Slint pré-compilada, reduzindo a análise em runtime.
Memória base (bandeja)	~10MB	Minimizar a frequência de polling em segundo plano, liberar caches de renderização sob demanda.
Uso de CPU (em repouso)	< 0,1%	Usar o modelo orientado a eventos do Windows, evitando polling de loop vazio.
Taxa de quadros de renderização	60 FPS	Aceleração de GPU Skia, renderização com anti-aliasing em nível subpixel.

5. Lógica de distribuição de tarefas do backend

Para garantir a fluidez da UI, todas as operações demoradas (como exportação de VHDX) são distribuídas por tarefas assíncronas:

1. Encapsulamento de solicitação: a thread da UI encapsula as operações do usuário em mensagens Command.
2. Canal de mensagens: envia para o processador de tarefas do backend por meio de tokio::sync::mpsc.
3. Retorno de estado: após a conclusão da tarefa do backend, a UI é atualizada por callback ou compartilhamento de estado. Esse design garante que, mesmo durante tarefas de backup de vários GB, a interface continue respondendo em tempo real aos cliques do usuário.

6. Considerações de segurança

• Operações atômicas: para desinstalação e migração críticas de instâncias, foram implementadas validações prévias.
• Gerenciamento de elevação de UAC: solicita permissões apenas quando necessário (como ao vincular dispositivos USB), seguindo o princípio do menor privilégio.
• Armazenamento local: as configurações são salvas apenas localmente em ~\.wsldashboard, sem qualquer sincronização em nuvem, protegendo a privacidade do usuário.