Network Change Coordinator
Relevant source files
The following files were used as context for generating this wiki page:
The Network Change Coordinator automates the detection of Wi-Fi and network transitions within the Zephyr application. It applies the correct Prism configurations and proxy rules without requiring user interaction. The system monitors for hardware-level changes and software events to maintain a consistent proxy state across different network environments.
The coordinator utilizes a single-flight state machine to prevent race conditions during rapid network switching. It implements a fail-closed protocol verification system to ensure connectivity before finalizing configuration changes.
Sources: FEATURES.md, apps/desktop/src-tauri/src/network_coordinator.rs:1-10
Architecture and Components
The Network Change Coordinator is organized into a modular structure within the Rust backend. It separates detection logic, platform-specific implementations, and high-level coordination.
Core Modules
- Coordinator: Manages the state machine and handles notification routing between the system and the proxy core.
- Detector: Performs active and passive network state inquiries, including SSID detection and connectivity checks.
- Platform: Contains OS-specific implementations, such as
NotifyAddrChangefor Windows and polling fallbacks for other systems. - Types: Defines shared data structures like
NetworkStateandNetworkChangeReason.
Sources: apps/desktop/src-tauri/src/network_coordinator.rs:3-7, FEATURES.md
Logic Flow for Network Change Detection
The diagram shows the transition from a network event trigger to the final application of proxy configurations via a verified state machine.
Sources: FEATURES.md, apps/desktop/src-tauri/src/network_coordinator.rs:50-70
Key Functions and IPC Commands
The system exposes several Tauri commands to allow the frontend to interact with the network state and trigger re-evaluations.
get_network_state
This command returns a snapshot of the current connectivity. If the coordinator has not yet completed a detection, the function performs a blocked detection with a 5-second timeout. To protect user privacy, the function masks the SSID string with *** before sending it to the frontend.
Sources: apps/desktop/src-tauri/src/network_coordinator.rs:27-46
notify_network_change
The frontend or system events call this function to trigger a manual re-evaluation. It accepts an optional source string to categorize the reason for the change.
| Source Input | Change Reason |
|---|---|
browser_online / online | NetworkChangeReason::OnlineEvent |
resume / wake | NetworkChangeReason::Resume |
manual / None | NetworkChangeReason::Manual |
| Other Strings | NetworkChangeReason::NativeEvent(sanitized) |
The coordinator truncates custom source strings to a maximum of 64 characters to prevent unbounded log writes.
Sources: apps/desktop/src-tauri/src/network_coordinator.rs:50-75
Network Detection and Verification
The coordinator ensures network stability through specific verification strategies:
- Debouncing: The system waits 2 seconds after an event to allow the network interface to stabilize.
- Verification: It performs a dual check consisting of an HTTP 2xx response and a TCP ACK.
- SSID Tracking: The system detects the current Wi-Fi SSID to determine if specific Prism DSL rule patches (e.g.,
__when__conditions) should activate. - Recovery: If a notification is dropped or the channel closes, the coordinator invalidates the
applied_stateand resets retry counters to recover the system.
Sources: FEATURES.md, apps/desktop/src-tauri/src/network_coordinator.rs:80-98
Sequence of Manual Reconciliation
This sequence illustrates how a manual trigger forces the coordinator to clear previous states and re-verify the connection before applying new configurations.
Sources: apps/desktop/src-tauri/src/network_coordinator.rs:77-100, FEATURES.md
Data Models
The coordinator relies on standardized structures to communicate state changes across the application.
NetworkState
Represents the connectivity status at a specific moment.
ssid: The name of the Wi-Fi network (masked in IPC responses).interface_type: The type of connection (e.g., Ethernet, Wi-Fi).is_connected: Boolean flag indicating internet access.
NetworkChangeReason
An enumeration defining the trigger for the coordination event.
Manual: User-initiated refresh.Resume: System wake event.OnlineEvent: Browser-level connectivity event.NativeEvent(String): Hardware/OS-level interface change.
Sources: apps/desktop/src-tauri/src/network_coordinator.rs:13-20, apps/desktop/src-tauri/src/network_coordinator.rs:60-75
Summary
The Network Change Coordinator provides a robust mechanism for adapting proxy behavior to varying network conditions. By combining hardware-level monitoring on Windows via NotifyAddrChange with a cross-platform polling fallback, it ensures that Zephyr maintains proxy integrity during Wi-Fi transitions or system resumes. Its use of debouncing and fail-closed verification prevents configuration errors during unstable network periods.