Whitepaper

Este documento explora em profundidade o design arquitetônico, a seleção tecnológica e a lógica de implementação subjacente das funcionalidades-chave do WSL Dashboard, com o objetivo de fornecer uma perspectiva técnica profunda para desenvolvedores e usuários avançados.

1. Visão geral da arquitetura

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

Componentes core

• Frontend (UI): Baseado na interface declarativa Slint. A thread da UI é responsável por renderização e interação do usuário.
• Backend (Runtime): Baseado no runtime assíncrono Tokio. Responsável por distribuição, execução de comandos do sistema (CLI), E/S 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. Motivos da seleção tecnológica

Por que Rust?

• Desempenho: abstrações de custo zero, compilado para código nativo de máquina, sem jitter de GC.
• Segurança de memória: elimina estouros de buffer e condições de corrida em tempo de compilação, o que é 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: linka estaticamente todas as dependências, produzindo um programa executável portátil de arquivo único.

Por que Slint + Skia?

• Sintaxe declarativa: separa a descrição da interface e a lógica, código fácil de manter.
• Renderização Skia: usa diretamente aceleração GPU (através do motor Skia), fornecendo texto com clareza subpixel e efeitos de animação suaves.
• Baixa sobrecarga: em comparação com Electron ou WPF, o Slint tem uma sobrecarga de runtime mínima.

3. Implementação técnica chave

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

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

• Decodificação subjacente: um decodificador de codificação eficiente desenvolvido internamente, garantindo que a saída seja analisada corretamente em ambientes Windows com diferentes configurações regionais.
• Sincronização de status: adota um mecanismo de sincronização duplo de polling agendado + ativação por operação.

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

A funcionalidade de migração aproveita o mecanismo de importação/exportação do WSL, mas com processamento altamente abstraído e atomizado.

• Garantia transacional: antes de iniciar a migração, o aplicativo bloqueará a distribuição de destino com um mutex para evitar danos aos dados causados por operações concorrentes.
• Registro automático: após completar a migração, o aplicativo redirecionará automaticamente o caminho VHDX e registrará novamente a distribuição, sem intervenção manual do usuário.

3.3 Redirecionamento de portas e automação de firewall

A funcionalidade de rede não é apenas uma chamada simples para netsh interface portproxy.

• Gerenciamento do ciclo de vida das regras: o aplicativo detectará automaticamente as regras de firewall existentes. Quando o usuário criar um redirecionamento, o aplicativo usará a API 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 o IP de rede virtual entre o host e a instância.

3.4 Integração USBIP

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

• Processamento de elevação: a operação de binding requer permissões de administrador, e a lógica backend implementa um encaminhamento elegante da solicitação de elevação UAC.
• Máquina de estado: mantém internamente uma máquina de estado de conexão de dispositivo USB, garantindo a rastreabilidade do processo Attach/Detach.

3.5 Monitoramento de recursos e leveza

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

• Leveza extrema: no modo silencioso da bandeja, o aplicativo libera ativamente recursos de UI desnecessários. Para conjuntos de caracteres padrão como o inglês, o uso de memória pode ser tão baixo quanto 10MB; para conjuntos de caracteres complexos como chinês, japonês e coreano, devido à necessidade de carregar caches de renderização de fontes maiores, o uso é de cerca de 38MB.

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

Métrica	Objetivo/Medido	Método de otimização
Velocidade de inicialização	< 500ms	Pré-compilar a interface Slint, reduzindo a análise em tempo de execução.
Memória base (bandeja)	~10MB	Minimizar a frequência de polling em segundo plano, liberando caches de renderização conforme necessário.
Uso de CPU (estático)	< 0.1%	Usar o modelo de eventos do Windows, evitando polling de loop vazio.
Taxa de renderização	60 FPS	Aceleração GPU Skia, renderização com anti-aliasing subpixel.

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

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

1. Encapsulamento da solicitação: a thread da UI encapsula a operação do usuário como uma mensagem Command.
2. Canal de mensagens: enviada por meio de tokio::sync::mpsc para o processador de tarefas em segundo plano.
3. Retransmissão de estado: após a conclusão da tarefa em segundo plano, a UI é atualizada por meio de callbacks ou compartilhamento de estado. Este design garante que a interface continue responsiva em tempo real aos cliques do usuário, mesmo ao processar tarefas de backup de vários GB.

6. Considerações de segurança

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