Rust Backend & Core Integration
Relevant source files
The following files were used as context for generating this wiki page:
Zephyr utilizes a Rust backend built on the Tauri v2 framework to manage the Mihomo proxy core and system-level integrations. This architecture separates high-performance, security-sensitive operations—such as process management, encrypted storage, and network configuration—from the JavaScript frontend. The backend handles IPC (Inter-Process Communication), manages the lifecycle of the proxy process, and implements security boundaries like SSRF protection and configuration sanitization.
The integration layer bridges the native Rust environment with the WebView frontend using a structured event bus and 166 IPC commands. This ensures that the UI remains reactive while heavy business logic, such as Prism Engine rule processing and machine-bound encryption, occurs in a memory-safe environment.
Sources: README_en.md, FEATURES.md, apps/desktop/src/integration.test.js:15-25
Architecture Overview
The system follows a four-layer architectural model that isolates the user interface from the underlying proxy engine. Rust acts as the central coordinator, managing communication between the Native JS frontend and the Mihomo Core via Tauri IPC and RESTful APIs.
The diagram shows the data flow from the UI through the Rust orchestration layer to the Mihomo core and OS subsystems.
Sources: landing.html:435-465, FEATURES.md
Core Process Management
The backend manages the Mihomo proxy engine's lifecycle, including starting, stopping, and restarting the process. It implements automated health checks and runtime detection to ensure the core remains functional and uses optimized instruction sets (AVX2/BMI) when available.
Lifecycle Control
The core_process.rs module handles the execution and supervision of the Mihomo binary. Key features include:
- Pre-check Validation: Executes
mihomo -t -fto validate configuration files before starting the core, preventing crash-restart loops. - Orphan Protection: Utilizes Windows Job Objects or Linux process groups with
PR_SET_PDEATHSIGto ensure the proxy process terminates if the main application crashes. - Architecture Detection: Automatically selects between optimized (v3), compatible, or generic binaries based on CPU runtime detection.
Sources: FEATURES.md, apps/desktop/src-tauri/src/core/core_process.rs
Process Monitoring Flow
The flow illustrates the safety checks and architectural adaptations performed during core initialization.
Sources: FEATURES.md, apps/desktop/src-tauri/src/core/core_process.rs
IPC and Event Bridging
Communication between the frontend and the Rust backend is facilitated by the core_event_bridge.rs and the main lib.rs command registration.
Command Structure
Zephyr registers 166 IPC commands across various namespaces. The frontend invokes these via the COMMANDS constant mapping.
| Namespace | Responsibility | Source Reference |
|---|---|---|
CORE | Start/stop core, versioning, log reading | integration.test.js:335 |
PRISM | Apply patches, status, stats, watching | integration.test.js:115 |
SYS_PROXY | System proxy enablement and status | integration.test.js:345 |
SUBSCRIPTION | Download, batch update, text fetching | integration.test.js:358 |
Sources: apps/desktop/src/integration.test.js:30-60, apps/desktop/src/integration.test.js:330-365
Event System
The core_event_bridge.rs transforms internal Rust events into Tauri frontend events. This allows the UI to react to asynchronous background changes without polling.
- Backend Events: Emits structured logs with 85 error codes and path redaction for privacy.
- Tray Updates: Notifies the UI of status changes in system proxy, TUN mode, or node selection.
- Network Coordination: Emits
network-state-changedwhen Wi-Fi or network transitions occur.
Sources: FEATURES.md, apps/desktop/src-tauri/src/core/core_event_bridge.rs, apps/desktop/src/integration.test.js:470-495
Security and Data Integrity
The Rust backend serves as the primary security boundary for the application. It implements native encryption and network safety filters.
Data Protection
- Machine-Bound Encryption: Uses AES-256-GCM and PBKDF2 to encrypt subscription metadata. The encryption key is derived from hardware fingerprints, preventing the use of metadata files on different machines.
- Secure I/O: The
secure_io.rsmodule ensures files are written with Unix0600permissions or specific Windows DACLs to prevent unauthorized local access.
Sources: FEATURES.md, apps/desktop/src-tauri/Cargo.toml:45-50
Network Safety
- SSRF Protection: Validates DNS for all subscription and rule URLs. While user-initiated private addresses are permitted, backend filters block redirects to private IP ranges.
- Update Integrity: Verifies assets using SHA256 hashes and Minisign Ed25519 signatures before performing atomic binary replacements.
Sources: FEATURES.md, README_en.md, apps/desktop/src-tauri/Cargo.toml:68
Configuration and Dependencies
The backend is configured via Cargo.toml, specifying a strict toolchain and workspace-wide lints for correctness and performance.
| Dependency | Purpose |
|---|---|
tauri v2 | Core framework for GUI and IPC |
clash-prism-* | Rule engine, script sandbox, and smart selector |
reqwest | HTTP client with SOCKS5 support for subscriptions |
webview2-com | Pinned to 0.39.1 for Windows crash recovery |
Sources: apps/desktop/src-tauri/Cargo.toml:25-75
Zephyr enforces 170 Clippy deny rules across four tiers, focusing on memory safety (denying unwrap_used, expect_used) and concurrency (denying await_holding_lock).
Sources: CONTRIBUTING.md, apps/desktop/src-tauri/Cargo.toml:135-140
Conclusion
The Rust Backend & Core Integration provides a secure, high-performance foundation for the Zephyr client. By centralizing Mihomo core management, rule processing, and security enforcement in Rust, the application achieves a lightweight footprint while maintaining robust protection against common vulnerabilities like SSRF and unauthorized data access.