Module HotReload  Copy item path

§Configuration Hot-Reload System

This module provides live configuration reloading capabilities with comprehensive error handling, validation, atomic updates, and rollback support for the Air daemon.

§Features

• File System Monitoring: Real-time detection of configuration file changes
• Signal Handling: SIGHUP support for manual configuration reload triggers
• Atomic Swaps: Thread-safe configuration updates without service interruption
• Automatic Rollback: Revert to previous configuration on validation failure
• Change Tracking: Detailed audit trail of all configuration changes
• Validation Pipeline: Multi-stage validation with custom validators
• Retry Logic: Automatic retry with exponential backoff on transient failures
• Notification System: Callback system for configuration change events
• Graceful Degradation: System continues operating even if hot-reload fails

§Integration with Configuration System

The hot-reload system works in tandem with the main configuration module:

• Uses same validation logic from Configuration module
• Shares configuration schema and structure
• Provides runtime updates without requiring service restart
• Scales horizontally across multiple Air instances

§Connection to Mountain and Wind Services

Configuration changes detected by hot-reload are propagated to:

• Mountain: User settings synchronized in real-time
• Wind: All background services notified of configuration updates
• VSCode: Frontend receives configuration change events

§Signal Handling

Supports the following Unix signals for manual control:

• SIGHUP: Force configuration reload from disk
• SIGUSR1: Hot-reload status information
• SIGUSR2: Disable/enable hot-reload monitoring

§Notification Flow

Config file changed → File watcher detected → Load & Validate
↓ ↓
Atomic swap ←- Validation passed ←-- Migration applied
↓
Notify subscribers → Wind services update → Mountain sync
↓
Change history logged → Rollback state updated

§Error Recovery

The system implements a robust error recovery strategy:

• Validation failures: Automatic rollback to previous valid configuration
• Parse errors: Keep existing configuration, log error, continue monitoring
• File system errors: Temporary pause in monitoring, retry with backoff
• Concurrent modifications: Use atomic file operations, retry on conflict

§Performance Considerations

• Debouncing: Multiple rapid changes trigger single reload after cooldown
• Async operations: Non-blocking file I/O and validation
• Lock-free reads: Configuration reads don’t block other operations
• Efficient diffing: Only process changed configuration sections

§Future Enhancements

The following features are planned for production deployments:

• Distributed synchronization: Configuration changes propagated across multiple Air instances via a consensus algorithm (Raft/Paxos) or centralized configuration store

• Change broadcasting: Real-time notification to connected Wind (Mountain) services via gRPC streaming or WebSocket push subscriptions

• Conflict resolution: Multi-master scenarios with automatic merge strategies and version vectors to detect and resolve concurrent modifications

These features require additional infrastructure and are not required for basic hot reload functionality.