Job Scheduler & Background Tasks
Relevant source files
The following files were used as context for generating this wiki page:
Job Scheduler & Background Tasks manage recurring operations within the HX-ProxyGroup control plane. These tasks include refreshing proxy subscriptions to update node inventories and performing quality checks to monitor node latency and availability. The system uses a worker-pool architecture to handle these operations concurrently without blocking the main application flow.
The scheduling logic is decoupled from the actual task implementation through interfaces, allowing the system to claim tasks from a repository (SQLite) and execute them via specialized refresher or checker components. Background tasks are constrained by concurrency rules to prevent resource exhaustion, such as limiting worker counts and ensuring proper lifecycle management through context.Context.
Sources: internal/scheduler/subscriptions.go:17-48, AGENTS.md:52-60, internal/scheduler/nodes.go:20-35
Subscription Scheduling
The SubscriptionScheduler handles the periodic retrieval and parsing of proxy subscription data. It coordinates between a database repository that tracks when subscriptions are due and a refresher service that performs the actual network requests and parsing.
Concurrency and Execution Flow
The scheduler utilizes a worker pool to process multiple subscriptions in parallel. It claims due subscriptions in batches, applies a lease duration to prevent duplicate processing by multiple instances, and enqueues jobs into a buffered channel.
The diagram shows the polling loop that claims subscriptions and distributes them to workers for refreshing.
Sources: internal/scheduler/subscriptions.go:73-105, internal/scheduler/subscriptions.go:138-175
Subscription Configuration
The behavior of the subscription scheduler is governed by the SubscriptionConfig structure.
| Option | Type | Default | Description |
|---|---|---|---|
Workers | int | 4 | Number of concurrent refresh workers (Range: 1-64). |
BatchSize | int | 100 | Max subscriptions to claim per poll (Range: 1-1000). |
PollInterval | time.Duration | 30s | How often the scheduler checks for due tasks. |
LeaseDuration | time.Duration | 5m | Duration for which a claimed task is locked. |
Sources: internal/scheduler/subscriptions.go:24-60
Node Quality Scheduling
The NodeScheduler manages recurring health and latency checks for proxy nodes. Unlike subscriptions, node checks are driven by quality settings that define test URLs and intervals.
Execution Logic
The scheduler triggers a NodeChecker at a configured PollInterval. The checker identifies nodes requiring a re-test based on their last check time and the administrator-defined quality settings.
The sequence shows the scheduler requesting due checks and logging the resulting latency and status.
Sources: internal/scheduler/nodes.go:37-65
Key Data Structures
- NodeChecker Interface: Defines the
CheckDuemethod to retrieve results of pending quality tests. - NodeConfig: Simple configuration carrying only the
PollInterval. - CheckResult: Contains the
Nodeentity, aSuccessboolean,LatencyMS(optional), andErrorCode(optional).
Sources: internal/scheduler/nodes.go:11-20, internal/scheduler/nodes.go:68-80
Concurrent Execution Rules
Background tasks must adhere to strict concurrency and reliability constraints to maintain system stability:
- Ownership: All goroutines must have explicit owners and exit paths.
- Worker Pools: Tasks must enter bounded queues and worker pools rather than creating unlimited ticker-based goroutines.
- Context Propagation: All calls (Network, Database, Dataplane) must receive and respect
context.Contextfor cancellation. - Deduplication: Subscription refreshes and node probes must be de-duplicated or serialized if they target the same resource simultaneously.
- Stopping: During service shutdown, the scheduler stops receiving new tasks, cancels pending ones, and flushes resources.
Sources: AGENTS.md:52-60
Background Process Management
The system also manages long-running sub-processes, specifically the Mihomo data plane. The Manager component tracks the process state and handles lifecycle events.
| Component | Responsibility | Source File |
|---|---|---|
Manager | Manages Mihomo process start, stop, and hot reload. | internal/dataplane/mihomo/manager.go |
Status | Tracks PID, running state, and listener counts. | internal/dataplane/mihomo/manager.go |
SyncDirectory | Ensures atomic configuration writes to disk. | internal/dataplane/mihomo/manager.go |
Sources: internal/dataplane/mihomo/manager.go:31-70, internal/dataplane/mihomo/manager.go:217-250
Summary
The Job Scheduler and Background Task system provides a robust framework for asynchronous operations. By utilizing worker pools for subscriptions and periodic tickers for node quality, it ensures node inventories and performance metrics remain current. The architecture emphasizes safety through atomic writes, context-aware execution, and bounded concurrency, preventing background operations from impacting the performance of the core proxy control path.
Sources: internal/scheduler/subscriptions.go internal/scheduler/nodes.go AGENTS.md