화이트페이퍼

이 문서는 WSL Dashboard의 아키텍처 설계, 기술 선택, 핵심 기능의 구현 로직에 대한 심층 분석을 제공하며, 기술적 관점을 찾는 개발자와 고급 사용자를 대상으로 합니다.

1. 아키텍처 개요

WSL Dashboard는 Rust의 타입 시스템과 소유권 모델을 활용하여 메모리 안전성과 높은 동시성 성능을 보장하는 클래식한 반응형 UI 기반 + 비동기 백엔드 작업 아키텍처를 채택합니다.

핵심 구성 요소

• 프론트엔드 (UI): Slint 선언적 인터페이스를 기반으로 구축. UI 스레드는 렌더링과 사용자 상호작용을 담당합니다.
• 백엔드 (Runtime): Tokio 비동기 런타임을 기반으로 구축. 시스템 명령(CLI), 파일 I/O, 네트워크 리스너의 전송 및 실행을 담당합니다.
• 통신: UI 스레드와 비동기 작업은 **채널(MPSC)**과 **공유 상태(Arc/Mutex/RwLock)**를 통해 효율적이고 스레드 안전하게 통신합니다.

2. 기술적 근거

왜 Rust인가?

• 성능: 제로 비용 추상화, 네이티브 머신 코드로 컴파일, GC 일시정지 없음.
• 메모리 안전성: 컴파일 시 버퍼 오버플로와 데이터 경쟁을 제거 — 시스템 수준(디스크 마이그레이션, 네트워크 구성)에서 작동하는 도구에 필수적.
• 바이너리 크기: 모든 의존성을 정적으로 링크하여 단일 파일 이식 가능한 실행 파일을 생성.

왜 Slint + Skia인가?

• 선언적 구문: UI 설명을 로직에서 분리하여 코드베이스를 깩고 유지 관리 가능하게 유지.
• Skia 렌더링: GPU 가속을 직접 활용(Skia 엔진을 통해), 서브픽셀 텍스트 선명도와 부드러운 애니메이션을 제공.
• 낮은 오버헤드: Electron이나 WPF에 비해 Slint의 런타임 풋프린트는 최소.

3. 핵심 기술 구현

3.1 WSL 인스턴스 감지 및 파싱

앱은 wsl.exe --list --verbose를 호출하고 출력을 파싱(UTF-16 인코딩 처리)하여 실시간 인스턴스 상태를 가져옵니다.

• 저수준 디코딩: 맞춤형 효율적인 인코더/디코더가 다양한 지역 설정을 가진 Windows 환경에서 올바른 출력 파싱을 보장합니다.
• 상태 동기화: 타이밍 폴링과 작업 트리거 업데이트를 결합한 이중 동기화 메커니즘을 사용합니다.

3.2 디스크 이미지 마이그레이션 (VHDX 이동)

마이그레이션 기능은 WSL의 가져오기/내보내기 메커니즘을 활용하지만 높은 수준의 추상화와 원자성을 갖습니다.

• 트랜잭션 보장: 마이그레이션 시작 전 앱은 Mutex를 통해 대상 배포를 잠가 동시 작업으로 인한 데이터 손상을 방지합니다.
• 자동 등록: 마이그레이션 완료 후 앱은 자동으로 VHDX 경로를 리디렉션하고 배포를 재등록 — 수동 개입 불필요.

3.3 포트 포워딩 및 방화벽 자동화

네트워킹 기능은 단순한 netsh interface portproxy 호출을 넘어섭니다.

• 규칙 수명 주기 관리: 앱은 기존 방화벽 규칙을 자동으로 감지합니다. 사용자가 포워딩 규칙을 생성하면 Windows API 또는 CLI를 통해 인바운드 예외 규칙을 동시에 생성합니다.
• 자동 IP 확인: wsl hostname -I 출력을 파싱하여 호스트와 인스턴스 간 가상 네트워크 IP를 자동으로 매핑합니다.

3.4 USBIP 통합

usbipd-win 명령줄 인터페이스를 활용합니다.

• 권한 상승 처리: 바인드 작업에는 관리자 권한이 필요합니다. 백엔드는 우아한 UAC 상승 요청 전달을 구현합니다.
• 상태 머신: Attach/Detach 작업의 완전한 추적 가능성을 보장하기 위해 내부 USB 장치 연결 상태 머신을 유지합니다.

3.5 리소스 모니터링 및 최소 풋프린트

앱은 네이티브 Windows API(예: GetProcessMemoryInfo)를 호출하여 자체 리소스 사용량을 모니터링합니다.

• 극한의 효율성: 사일런트 트레이 모드에서 앱은 불필요한 UI 리소스를 능동적으로 해제합니다. 표준 문자 세트(예: 영어)의 경우 메모리 사용량이 10MB까지 낮을 수 있습니다; 복잡한 문자 세트(예: CJK)의 경우 더 큰 폰트 렌더링 캐시로 인해 약 38MB입니다.

4. 성능 벤치마크

지표	목표 / 측정值	최적화 접근 방식
시작 시간	< 500ms	사전 컴파일된 Slint 인터페이스, 런타임 파싱 최소화.
기본 메모리 (트레이)	~10MB	최소화된 백그라운드 폴링 주기, 렌더링 캐시 온디맨드 해제.
CPU 사용량 (유휴)	< 0.1%	Windows 이벤트 기반 모델, busy-loop 폴링 없음.
렌더링 프레임 속도	60 FPS	Skia GPU 가속, 서브픽셀 안티앨리어싱 렌더링.

5. 백엔드 작업 디스패치 로직

UI 반응성을 보장하기 위해 모든 시간 소모 작업(예: VHDX 내보내기)은 비동기 작업으로 전송됩니다:

1. 요청 캡슐화: UI 스레드는 사용자 작업을 Command 메시지로 캡슐화합니다.
2. 메시지 채널: tokio::sync::mpsc를 통해 백그라운드 작업 핸들러로 전송합니다.
3. 상태 콜백: 백그라운드 작업이 완료되면 콜백 또는 공유 상태를 통해 UI를 업데이트합니다. 이 설계는 수 기가바이트 백업 작업을 처리하는 동안에도 인터페이스가 사용자 입력에 완전히 반응하도록 보장합니다.

6. 보안 고려사항

• 원자적 작업: 중요한 인스턴스 해제 및 마이그레이션 작업에 대한 사전 검증이 구현되어 있습니다.
• UAC 상승 관리: 상승된 권한은 필요할 때만 요청됩니다(예: USB 장치 바인딩). 최소 권한 원칙을 따릅니다.
• 로컬 저장: 구성은 로컬 ~\.wsldashboard 디렉토리에만 저장되며任何形式의 클라우드 동기화가 없어 사용자 프라이버시를 보호합니다.