Node Assessment & Quality Probing
Relevant source files
The following files were used as context for generating this wiki page:
Node Assessment and Quality Probing manages the lifecycle and health validation of proxy nodes within HX-ProxyGroup. The system executes URL latency tests via the Mihomo dataplane to determine node availability and performance. Assessment results directly influence the lifecycle_state of each node, which controls whether a node is included in active proxy groups.
The module provides both automated background probing and on-demand manual testing. It tracks metrics such as latency in milliseconds, consecutive failure counts, and site-specific health checks. This data allows the control plane to move nodes between states like healthy, degraded, and quarantined based on real-time network conditions.
Node Lifecycle States
The system tracks nodes through a state machine that determines their availability for routing. Nodes move between these states based on the results of quality probes.
| State | Description | Transitions |
|---|---|---|
| candidate | A newly discovered or re-enabled node waiting for its first probe. | Moves to healthy on success or degraded/quarantined on failure. |
| healthy | Node is available and has acceptable latency (typically < 1500ms). | Moves to degraded if latency increases or quarantined on failure. |
| degraded | Node is functional but suffers from high latency or sporadic failures. | Returns to healthy on good results or quarantined on persistent failure. |
| quarantined | Node has failed 3 consecutive probes and is removed from active use. | Automatically recovers to healthy upon a successful probe. |
| disabled | Administrator manually disabled the node. | Requires manual action to return to candidate state. |
| retired | Node is no longer present in any active subscription. | Final state; removed from configuration logic. |
Sources: internal/node/service.go:49-55, web/src/pages/nodes-page.tsx:23-31, internal/store/nodes.go:210-221
Probing Architecture
The Service in internal/node coordinates assessment by interacting with a Repository for persistence and a Prober for execution. The prober interfaces with the Mihomo dataplane to perform actual network requests.
The diagram shows the flow from a service-triggered check through the database query and the prober interface to the Mihomo data plane for execution. Sources: internal/node/service.go:95-103, internal/node/service.go:275-300, AGENTS.md:32-35
Probing Logic and Concurrency
Probing is performed using a worker pool to handle multiple nodes simultaneously. The system limits the number of concurrent probes to prevent resource exhaustion.
- Automation:
CheckDueidentifies nodes whose last check is older than thecheck_interval_secondssetting. - Worker Pool:
CheckManyProgresscreates a channel-based worker pool defined byProbeConcurrency. - Execution: The
ProbercallsTestProxy, which performs a URL latency test (not an ICMP ping). - Error Classification: Failures are classified into codes such as
timeout,connect_failed,node_unreachable, ordataplane_down.
Sources: internal/node/service.go:343-393, internal/node/service.go:422-440, internal/node/service.go:488-508
Quality Settings
Administrators configure probing behavior through global settings. These parameters define the thresholds for health assessment.
| Parameter | Type | Default | Description |
|---|---|---|---|
test_url | string | http://cp.cloudflare.com/generate_204 | The primary URL used to measure node latency. |
check_interval_seconds | int | 600 (10 min) | How often a node must be re-probed. |
timeout_seconds | int | 10 | The maximum time allowed for a probe request. |
batch_size | int | 200 | Maximum nodes to check in a single automated round. |
probe_concurrency | int | 1-16 | Number of simultaneous probe workers. |
Sources: internal/node/service.go:22-25, web/src/pages/settings-page.tsx:165-171
Health Targets
In addition to the primary latency test, the system supports "Health Targets." These are specific URLs (e.g., GitHub, Netflix) tested immediately after a successful primary probe to verify access to specific services.
This sequence illustrates how health targets are probed sequentially after a successful primary quality check. Sources: internal/node/service.go:303-317, internal/node/service.go:323-341
Data Persistence
The NodeRecord structure in internal/store persists assessment history. Key fields include:
LastLatencyMS: The most recent successful latency measurement.ConsecutiveProbeFailures: Count of failures since the last success; used to trigger quarantine.LastErrorCode: Classification of the last failure (e.g.,timeout).Fingerprint: Unique identifier used to de-duplicate nodes across subscriptions.
Sources: internal/store/nodes.go:21-36, internal/store/nodes.go:315-335
Conclusion
Node Assessment & Quality Probing ensures the reliability of the proxy network by continuously validating node health. By leveraging the Mihomo dataplane for real-world HTTP latency testing and maintaining a strict state machine, the system automatically isolates failing nodes and optimizes the selection of healthy exit points for user traffic.