Automatic Failover Strategy

Relevant source files

The following files were used as context for generating this wiki page:

• crates/core/src/failover.rs
• apps/desktop/src/ui/plugins-smart.js
• FEATURES.md
• README_en.md
• apps/desktop/src/main.js

Automatic Failover Strategy manages proxy node transitions when connectivity issues occur. It monitors node health and triggers switches to a backup group based on defined thresholds and cooldown periods. The system integrates with the Prism Engine to provide adaptive scheduling and stability-based node selection.

Sources: README_en.md:108-111, FEATURES.md:88-90

Failover Architecture

The failover system operates across the core business logic and the platform UI layer. The core handles data structures and policy validation, while the platform layer maintains the stateful FailoverTracker to manage cooldowns and failure counts.

Core Data Structures

The system defines the configuration and the resulting actions through the following structures:

• FailoverPolicyConfig: Defines whether failover is enabled, the error threshold, cooldown duration, and the designated fallback group.
• FailoverAction: Represents the outcome of a failure report, including the name of the failed node, the current failure count, and the target fallback node.

Sources: crates/core/src/failover.rs:13-21, crates/core/src/failover.rs:35-40

System Workflow

The following diagram illustrates the lifecycle of a failover event from failure detection to fallback execution.

The system tracks failure counts and compares them against a user-defined threshold. It prevents rapid flapping by checking the cooldown status before executing a switch.

Sources: crates/core/src/failover.rs:6-10, FEATURES.md:88-90

Configuration and Validation

Users configure failover behavior through the UI, which interacts with the failover_commands IPC layer. The backend validates these settings to ensure operational integrity.

Policy Parameters

Parameter	Type	Default	Description
enabled	boolean	true	Toggles the failover system on or off.
threshold	u32	3	Number of consecutive failures before triggering a switch.
cooldown_secs	u64	60	Time in seconds to wait before allowing another switch.
fallback_group	string	""	The name of the proxy group used as a backup.

Sources: crates/core/src/failover.rs:23-31, apps/desktop/src/ui/plugins-smart.js:336-342

Validation Logic

The validate_failover_policy function enforces the following constraints:

1. Threshold: Must be at least 1. A value of 0 returns a validation error.
2. Cooldown: Must be at least 1 second to prevent immediate repeated switches.

Sources: crates/core/src/failover.rs:43-53

UI Integration and Command Layer

The frontend provides controls for managing failover policies and resetting stateful counters. It utilizes the prism module to communicate with the Rust backend.

IPC Command Interactions

The UI facilitates the following operations:

• Set Policy: Updates the FailoverPolicyConfig in the backend.
• Get Policy: Retrieves the current active policy for display in the settings.
• Reset Counts: Clears all failure tracking and cooldown states via failoverReset.

Failover Reporting

When a node fails, the system reports the event. If the criteria are met, the UI receives notification of the FailoverAction and updates the proxy group selection accordingly. This is part of the Smart Proxy Selector's adaptive scheduling.

Sources: apps/desktop/src/ui/plugins-smart.js:298-301, FEATURES.md:85-87

Implementation Example: Policy Initialization

The default policy is derived from the clash-prism-core defaults during initialization.

impl Default for FailoverPolicyConfig {
    fn default() -> Self {
        let p = NodeFailPolicy::new();
        Self {
            enabled: p.enabled,
            threshold: p.threshold,
            cooldown_secs: p.cooldown.as_secs(),
            fallback_group: p.fallback_group,
        }
    }
}

Sources: crates/core/src/failover.rs:23-31

Conclusion

The Automatic Failover Strategy provides a resilient layer for proxy connectivity by automating node recovery. By combining core validation logic with a stateful tracking system in the platform layer, Zephyr ensures stable transitions between primary and fallback groups while preventing configuration errors through strict validation.