Add AFTN protocol validation and serial reader health monitoring to enhance aviation telegram processing reliability and observability

Implement comprehensive AFTN/ICAO protocol compliance validation with configurable enforcement, enabling early detection of malformed telegrams and reducing downstream processing errors. Add real-time serial reader health monitoring to automatically detect message flow interruptions and sequence gaps, ensuring operational visibility into the telegram ingestion pipeline.

Key enhancements:
- AFTN validator validates priority indicators (FF/GG/QU/DD/SS/KK), ICAO addresses (4-char alphanumeric), and datetime formats (DDHHMM) with detailed error categorization
- Invalid telegrams automatically routed to DLQ with full context for offline review and correction
- Serial reader health monitoring tracks message gaps and sequence numbers to detect stalled readers or missing messages within configurable threshold (default: 2 minutes)
- Four new Prometheus metrics expose validation errors by type, message gaps, sequence gaps, and health status for operational alerting
- Pre-configured Prometheus alert rules for critical conditions (stalled reader, high error rates, consumer lag)
- Grafana dashboard provides real-time visibility into AFTN compliance and serial reader health
- Validation disabled by default for safe rollout with zero breaking changes to existing functionality

Implementation maintains clean architecture with validator in adapter layer, extends processor and consumer with health tracking, and ensures thread-safe concurrent access to tracking state. All changes fully tested with 48 validator tests, 10 processor tests, and 21 consumer tests passing.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
windyboy
2025-12-24 14:21:59 +08:00
co-authored by Claude Sonnet 4.5
parent 6eff35b56f
commit 7b6f6383ad
17 changed files with 2071 additions and 12 deletions
+23
View File
@@ -22,6 +22,7 @@ type Config struct {
Telemetry TelemetryConfig `koanf:"telemetry"`
Monitoring MonitoringConfig `koanf:"monitoring"`
DLQ DLQConfig `koanf:"dlq"`
AFTN AFTNConfig `koanf:"aftn"`
// Legacy fields for backward compatibility during migration
Subscription SubscriptionConfig `koanf:"subscription"`
Timeouts TimeoutsConfig `koanf:"timeouts"`
@@ -146,6 +147,19 @@ type DLQConfig struct {
Subject string `koanf:"subject"`
}
// AFTNConfig defines AFTN protocol validation and monitoring settings
type AFTNConfig struct {
// ValidationEnabled enables AFTN protocol validation
ValidationEnabled bool `koanf:"validation_enabled"`
// MessageGapThreshold is the duration after which the serial reader
// is considered stalled (no messages received). Default: 2 minutes.
MessageGapThreshold time.Duration `koanf:"message_gap_threshold"`
// EnableSequenceGapDetection enables monitoring for missing sequence numbers
EnableSequenceGapDetection bool `koanf:"enable_sequence_gap_detection"`
}
// MonitoringConfig controls the lightweight HTTP server that exposes health and metrics endpoints.
type MonitoringConfig struct {
Disabled bool `koanf:"disabled"`
@@ -317,6 +331,11 @@ func LoadConfig() (*Config, error) {
cfg.Monitoring.HealthTimeout = 2 * time.Second
}
// Set AFTN defaults
if cfg.AFTN.MessageGapThreshold == 0 {
cfg.AFTN.MessageGapThreshold = 2 * time.Minute
}
// Validate configuration
if err := cfg.Validate(); err != nil {
return nil, fmt.Errorf("config validation failed: %w", err)
@@ -406,6 +425,10 @@ func (c *Config) Validate() error {
if c.Monitoring.HealthTimeout < 0 {
return fmt.Errorf("monitoring.health_timeout must be >= 0")
}
// Validate AFTN configuration
if c.AFTN.MessageGapThreshold < 0 {
return fmt.Errorf("aftn.message_gap_threshold must be >= 0")
}
return nil
}