✨ 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
co-authored by
Claude Sonnet 4.5
Claude Sonnet 4.5
parent
6eff35b56f
commit
7b6f6383ad
@@ -14,6 +14,7 @@ const (
|
||||
MessageStatusParsed MessageStatus = "parsed"
|
||||
MessageStatusHeaderError MessageStatus = "header_error"
|
||||
MessageStatusBodyError MessageStatus = "body_error"
|
||||
MessageStatusAFTNError MessageStatus = "aftn_error"
|
||||
)
|
||||
|
||||
// ParsedTelegram holds the parsed data from an aviation message.
|
||||
|
||||
@@ -0,0 +1,176 @@
|
||||
package validator
|
||||
|
||||
import (
|
||||
"caatsm/internal/adapter/dto"
|
||||
"fmt"
|
||||
"regexp"
|
||||
"strconv"
|
||||
"strings"
|
||||
)
|
||||
|
||||
// AFTNError represents an AFTN protocol violation
|
||||
type AFTNError struct {
|
||||
Field string // e.g., "priority_indicator", "icao_address"
|
||||
Value string
|
||||
Message string
|
||||
}
|
||||
|
||||
func (e *AFTNError) Error() string {
|
||||
return fmt.Sprintf("AFTN validation error [%s]: %s (value: %q)", e.Field, e.Message, e.Value)
|
||||
}
|
||||
|
||||
// AFTN field validators
|
||||
var (
|
||||
// Priority indicators: FF (Flash), GG (Immediate), QU (Distress), DD (Delay), SS (Service), KK (Correction)
|
||||
validPriorities = map[string]bool{
|
||||
"FF": true, "GG": true, "QU": true,
|
||||
"DD": true, "SS": true, "KK": true,
|
||||
}
|
||||
|
||||
// ICAO address: 4 uppercase alphanumeric characters
|
||||
icaoAddressPattern = regexp.MustCompile(`^[A-Z0-9]{4}$`)
|
||||
|
||||
// DateTime: DDHHMM (6 digits)
|
||||
dateTimePattern = regexp.MustCompile(`^\d{6}$`)
|
||||
)
|
||||
|
||||
// ValidatePriorityIndicator validates AFTN priority indicator
|
||||
func ValidatePriorityIndicator(priority string) error {
|
||||
priority = strings.TrimSpace(strings.ToUpper(priority))
|
||||
if priority == "" {
|
||||
return nil // Optional field
|
||||
}
|
||||
if !validPriorities[priority] {
|
||||
return &AFTNError{
|
||||
Field: "priority_indicator",
|
||||
Value: priority,
|
||||
Message: "must be one of FF, GG, QU, DD, SS, KK",
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// ValidateICAOAddress validates 4-character ICAO address
|
||||
func ValidateICAOAddress(address string) error {
|
||||
address = strings.TrimSpace(strings.ToUpper(address))
|
||||
if address == "" {
|
||||
return nil // Optional field
|
||||
}
|
||||
if !icaoAddressPattern.MatchString(address) {
|
||||
return &AFTNError{
|
||||
Field: "icao_address",
|
||||
Value: address,
|
||||
Message: "must be 4 uppercase alphanumeric characters",
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// ValidateDateTime validates DDHHMM format
|
||||
func ValidateDateTime(dt string) error {
|
||||
dt = strings.TrimSpace(dt)
|
||||
if dt == "" {
|
||||
return nil // Optional field
|
||||
}
|
||||
if !dateTimePattern.MatchString(dt) {
|
||||
return &AFTNError{
|
||||
Field: "datetime",
|
||||
Value: dt,
|
||||
Message: "must be 6 digits (DDHHMM format)",
|
||||
}
|
||||
}
|
||||
// Additional semantic validation
|
||||
if len(dt) == 6 {
|
||||
day := dt[0:2]
|
||||
hour := dt[2:4]
|
||||
minute := dt[4:6]
|
||||
// Basic range checks
|
||||
if !isValidRange(day, 1, 31) || !isValidRange(hour, 0, 23) || !isValidRange(minute, 0, 59) {
|
||||
return &AFTNError{
|
||||
Field: "datetime",
|
||||
Value: dt,
|
||||
Message: "invalid date/time ranges (DD:01-31, HH:00-23, MM:00-59)",
|
||||
}
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// ValidateTelegram validates all AFTN fields in ParsedTelegram
|
||||
func ValidateTelegram(telegram *dto.ParsedTelegram) error {
|
||||
if telegram == nil {
|
||||
return nil
|
||||
}
|
||||
|
||||
var errors []error
|
||||
|
||||
// Validate priority indicator
|
||||
if err := ValidatePriorityIndicator(telegram.PriorityIndicator); err != nil {
|
||||
errors = append(errors, err)
|
||||
}
|
||||
|
||||
// Validate primary address (ICAO)
|
||||
if err := ValidateICAOAddress(telegram.PrimaryAddress); err != nil {
|
||||
errors = append(errors, err)
|
||||
}
|
||||
|
||||
// Validate originator (ICAO)
|
||||
if err := ValidateICAOAddress(telegram.Originator); err != nil {
|
||||
errors = append(errors, err)
|
||||
}
|
||||
|
||||
// Validate datetime
|
||||
if err := ValidateDateTime(telegram.DateTime); err != nil {
|
||||
errors = append(errors, err)
|
||||
}
|
||||
|
||||
// Validate originator datetime
|
||||
if err := ValidateDateTime(telegram.OriginatorDateTime); err != nil {
|
||||
errors = append(errors, err)
|
||||
}
|
||||
|
||||
if len(errors) > 0 {
|
||||
return &AFTNValidationErrors{Errors: errors}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// AFTNValidationErrors wraps multiple validation errors
|
||||
type AFTNValidationErrors struct {
|
||||
Errors []error
|
||||
}
|
||||
|
||||
func (e *AFTNValidationErrors) Error() string {
|
||||
messages := make([]string, len(e.Errors))
|
||||
for i, err := range e.Errors {
|
||||
messages[i] = err.Error()
|
||||
}
|
||||
return fmt.Sprintf("AFTN validation failed: %s", strings.Join(messages, "; "))
|
||||
}
|
||||
|
||||
// IsAFTNError checks if error is an AFTN validation error
|
||||
func IsAFTNError(err error) bool {
|
||||
if err == nil {
|
||||
return false
|
||||
}
|
||||
_, ok1 := err.(*AFTNError)
|
||||
_, ok2 := err.(*AFTNValidationErrors)
|
||||
return ok1 || ok2
|
||||
}
|
||||
|
||||
// GetAFTNErrorType extracts the error type for metrics labeling
|
||||
func GetAFTNErrorType(err error) string {
|
||||
if aftnErr, ok := err.(*AFTNError); ok {
|
||||
return aftnErr.Field
|
||||
}
|
||||
if _, ok := err.(*AFTNValidationErrors); ok {
|
||||
return "multiple_errors"
|
||||
}
|
||||
return "unknown"
|
||||
}
|
||||
|
||||
// isValidRange checks if a numeric string is within the specified range
|
||||
func isValidRange(s string, min, max int) bool {
|
||||
val, err := strconv.Atoi(s)
|
||||
return err == nil && val >= min && val <= max
|
||||
}
|
||||
@@ -0,0 +1,341 @@
|
||||
package validator_test
|
||||
|
||||
import (
|
||||
"caatsm/internal/adapter/dto"
|
||||
"caatsm/internal/adapter/validator"
|
||||
|
||||
. "github.com/onsi/ginkgo/v2"
|
||||
. "github.com/onsi/gomega"
|
||||
)
|
||||
|
||||
var _ = Describe("AFTN Validator", func() {
|
||||
Describe("ValidatePriorityIndicator", func() {
|
||||
Context("with valid priority indicators", func() {
|
||||
It("accepts FF (Flash)", func() {
|
||||
err := validator.ValidatePriorityIndicator("FF")
|
||||
Expect(err).To(BeNil())
|
||||
})
|
||||
|
||||
It("accepts GG (Immediate)", func() {
|
||||
err := validator.ValidatePriorityIndicator("GG")
|
||||
Expect(err).To(BeNil())
|
||||
})
|
||||
|
||||
It("accepts QU (Distress)", func() {
|
||||
err := validator.ValidatePriorityIndicator("QU")
|
||||
Expect(err).To(BeNil())
|
||||
})
|
||||
|
||||
It("accepts DD (Delay)", func() {
|
||||
err := validator.ValidatePriorityIndicator("DD")
|
||||
Expect(err).To(BeNil())
|
||||
})
|
||||
|
||||
It("accepts SS (Service)", func() {
|
||||
err := validator.ValidatePriorityIndicator("SS")
|
||||
Expect(err).To(BeNil())
|
||||
})
|
||||
|
||||
It("accepts KK (Correction)", func() {
|
||||
err := validator.ValidatePriorityIndicator("KK")
|
||||
Expect(err).To(BeNil())
|
||||
})
|
||||
|
||||
It("accepts lowercase with trimming", func() {
|
||||
err := validator.ValidatePriorityIndicator(" ff ")
|
||||
Expect(err).To(BeNil())
|
||||
})
|
||||
|
||||
It("accepts empty string (optional field)", func() {
|
||||
err := validator.ValidatePriorityIndicator("")
|
||||
Expect(err).To(BeNil())
|
||||
})
|
||||
})
|
||||
|
||||
Context("with invalid priority indicators", func() {
|
||||
It("rejects invalid code XX", func() {
|
||||
err := validator.ValidatePriorityIndicator("XX")
|
||||
Expect(err).ToNot(BeNil())
|
||||
Expect(validator.IsAFTNError(err)).To(BeTrue())
|
||||
Expect(validator.GetAFTNErrorType(err)).To(Equal("priority_indicator"))
|
||||
})
|
||||
|
||||
It("rejects single character", func() {
|
||||
err := validator.ValidatePriorityIndicator("F")
|
||||
Expect(err).ToNot(BeNil())
|
||||
})
|
||||
|
||||
It("rejects three characters", func() {
|
||||
err := validator.ValidatePriorityIndicator("FFF")
|
||||
Expect(err).ToNot(BeNil())
|
||||
})
|
||||
})
|
||||
})
|
||||
|
||||
Describe("ValidateICAOAddress", func() {
|
||||
Context("with valid ICAO addresses", func() {
|
||||
It("accepts ZBTJ (Beijing)", func() {
|
||||
err := validator.ValidateICAOAddress("ZBTJ")
|
||||
Expect(err).To(BeNil())
|
||||
})
|
||||
|
||||
It("accepts KLAX (Los Angeles)", func() {
|
||||
err := validator.ValidateICAOAddress("KLAX")
|
||||
Expect(err).To(BeNil())
|
||||
})
|
||||
|
||||
It("accepts ZGGG (Guangzhou)", func() {
|
||||
err := validator.ValidateICAOAddress("ZGGG")
|
||||
Expect(err).To(BeNil())
|
||||
})
|
||||
|
||||
It("accepts alphanumeric codes like Z999", func() {
|
||||
err := validator.ValidateICAOAddress("Z999")
|
||||
Expect(err).To(BeNil())
|
||||
})
|
||||
|
||||
It("accepts 1ABC", func() {
|
||||
err := validator.ValidateICAOAddress("1ABC")
|
||||
Expect(err).To(BeNil())
|
||||
})
|
||||
|
||||
It("accepts lowercase with trimming", func() {
|
||||
err := validator.ValidateICAOAddress(" zbtj ")
|
||||
Expect(err).To(BeNil())
|
||||
})
|
||||
|
||||
It("accepts empty string (optional field)", func() {
|
||||
err := validator.ValidateICAOAddress("")
|
||||
Expect(err).To(BeNil())
|
||||
})
|
||||
})
|
||||
|
||||
Context("with invalid ICAO addresses", func() {
|
||||
It("rejects too short (3 chars)", func() {
|
||||
err := validator.ValidateICAOAddress("ZBT")
|
||||
Expect(err).ToNot(BeNil())
|
||||
Expect(validator.IsAFTNError(err)).To(BeTrue())
|
||||
Expect(validator.GetAFTNErrorType(err)).To(Equal("icao_address"))
|
||||
})
|
||||
|
||||
It("rejects too long (5 chars)", func() {
|
||||
err := validator.ValidateICAOAddress("ZBTJX")
|
||||
Expect(err).ToNot(BeNil())
|
||||
})
|
||||
|
||||
It("rejects special characters", func() {
|
||||
err := validator.ValidateICAOAddress("ZB-J")
|
||||
Expect(err).ToNot(BeNil())
|
||||
})
|
||||
|
||||
It("rejects spaces", func() {
|
||||
err := validator.ValidateICAOAddress("ZB J")
|
||||
Expect(err).ToNot(BeNil())
|
||||
})
|
||||
})
|
||||
})
|
||||
|
||||
Describe("ValidateDateTime", func() {
|
||||
Context("with valid datetime values", func() {
|
||||
It("accepts 151430 (15th day, 14:30)", func() {
|
||||
err := validator.ValidateDateTime("151430")
|
||||
Expect(err).To(BeNil())
|
||||
})
|
||||
|
||||
It("accepts 010000 (1st day, 00:00)", func() {
|
||||
err := validator.ValidateDateTime("010000")
|
||||
Expect(err).To(BeNil())
|
||||
})
|
||||
|
||||
It("accepts 312359 (31st day, 23:59)", func() {
|
||||
err := validator.ValidateDateTime("312359")
|
||||
Expect(err).To(BeNil())
|
||||
})
|
||||
|
||||
It("accepts empty string (optional field)", func() {
|
||||
err := validator.ValidateDateTime("")
|
||||
Expect(err).To(BeNil())
|
||||
})
|
||||
})
|
||||
|
||||
Context("with invalid datetime values", func() {
|
||||
It("rejects non-numeric", func() {
|
||||
err := validator.ValidateDateTime("15A430")
|
||||
Expect(err).ToNot(BeNil())
|
||||
Expect(validator.IsAFTNError(err)).To(BeTrue())
|
||||
Expect(validator.GetAFTNErrorType(err)).To(Equal("datetime"))
|
||||
})
|
||||
|
||||
It("rejects too short (5 digits)", func() {
|
||||
err := validator.ValidateDateTime("15143")
|
||||
Expect(err).ToNot(BeNil())
|
||||
})
|
||||
|
||||
It("rejects too long (7 digits)", func() {
|
||||
err := validator.ValidateDateTime("1514301")
|
||||
Expect(err).ToNot(BeNil())
|
||||
})
|
||||
|
||||
It("rejects invalid day (00)", func() {
|
||||
err := validator.ValidateDateTime("001430")
|
||||
Expect(err).ToNot(BeNil())
|
||||
})
|
||||
|
||||
It("rejects invalid day (32)", func() {
|
||||
err := validator.ValidateDateTime("321430")
|
||||
Expect(err).ToNot(BeNil())
|
||||
})
|
||||
|
||||
It("rejects invalid hour (24)", func() {
|
||||
err := validator.ValidateDateTime("152430")
|
||||
Expect(err).ToNot(BeNil())
|
||||
})
|
||||
|
||||
It("rejects invalid minute (60)", func() {
|
||||
err := validator.ValidateDateTime("151460")
|
||||
Expect(err).ToNot(BeNil())
|
||||
})
|
||||
|
||||
It("rejects invalid minute (99)", func() {
|
||||
err := validator.ValidateDateTime("151499")
|
||||
Expect(err).ToNot(BeNil())
|
||||
})
|
||||
})
|
||||
})
|
||||
|
||||
Describe("ValidateTelegram", func() {
|
||||
Context("with valid telegram", func() {
|
||||
It("accepts telegram with all valid fields", func() {
|
||||
telegram := &dto.ParsedTelegram{
|
||||
PriorityIndicator: "FF",
|
||||
PrimaryAddress: "ZBTJ",
|
||||
Originator: "KLAX",
|
||||
DateTime: "151430",
|
||||
OriginatorDateTime: "151425",
|
||||
}
|
||||
err := validator.ValidateTelegram(telegram)
|
||||
Expect(err).To(BeNil())
|
||||
})
|
||||
|
||||
It("accepts telegram with empty optional fields", func() {
|
||||
telegram := &dto.ParsedTelegram{
|
||||
PriorityIndicator: "",
|
||||
PrimaryAddress: "ZBTJ",
|
||||
Originator: "",
|
||||
DateTime: "151430",
|
||||
OriginatorDateTime: "",
|
||||
}
|
||||
err := validator.ValidateTelegram(telegram)
|
||||
Expect(err).To(BeNil())
|
||||
})
|
||||
|
||||
It("accepts nil telegram", func() {
|
||||
err := validator.ValidateTelegram(nil)
|
||||
Expect(err).To(BeNil())
|
||||
})
|
||||
})
|
||||
|
||||
Context("with invalid telegram fields", func() {
|
||||
It("reports invalid priority indicator", func() {
|
||||
telegram := &dto.ParsedTelegram{
|
||||
PriorityIndicator: "XX",
|
||||
PrimaryAddress: "ZBTJ",
|
||||
DateTime: "151430",
|
||||
}
|
||||
err := validator.ValidateTelegram(telegram)
|
||||
Expect(err).ToNot(BeNil())
|
||||
Expect(validator.IsAFTNError(err)).To(BeTrue())
|
||||
})
|
||||
|
||||
It("reports invalid primary address", func() {
|
||||
telegram := &dto.ParsedTelegram{
|
||||
PriorityIndicator: "FF",
|
||||
PrimaryAddress: "TOOLONG",
|
||||
DateTime: "151430",
|
||||
}
|
||||
err := validator.ValidateTelegram(telegram)
|
||||
Expect(err).ToNot(BeNil())
|
||||
Expect(validator.IsAFTNError(err)).To(BeTrue())
|
||||
})
|
||||
|
||||
It("reports invalid originator", func() {
|
||||
telegram := &dto.ParsedTelegram{
|
||||
PriorityIndicator: "FF",
|
||||
PrimaryAddress: "ZBTJ",
|
||||
Originator: "KL",
|
||||
DateTime: "151430",
|
||||
}
|
||||
err := validator.ValidateTelegram(telegram)
|
||||
Expect(err).ToNot(BeNil())
|
||||
Expect(validator.IsAFTNError(err)).To(BeTrue())
|
||||
})
|
||||
|
||||
It("reports invalid datetime", func() {
|
||||
telegram := &dto.ParsedTelegram{
|
||||
PriorityIndicator: "FF",
|
||||
PrimaryAddress: "ZBTJ",
|
||||
DateTime: "321430",
|
||||
}
|
||||
err := validator.ValidateTelegram(telegram)
|
||||
Expect(err).ToNot(BeNil())
|
||||
Expect(validator.IsAFTNError(err)).To(BeTrue())
|
||||
})
|
||||
|
||||
It("reports multiple errors", func() {
|
||||
telegram := &dto.ParsedTelegram{
|
||||
PriorityIndicator: "XX",
|
||||
PrimaryAddress: "TOOLONG",
|
||||
Originator: "KL",
|
||||
DateTime: "321430",
|
||||
OriginatorDateTime: "991499",
|
||||
}
|
||||
err := validator.ValidateTelegram(telegram)
|
||||
Expect(err).ToNot(BeNil())
|
||||
Expect(validator.IsAFTNError(err)).To(BeTrue())
|
||||
Expect(validator.GetAFTNErrorType(err)).To(Equal("multiple_errors"))
|
||||
Expect(err.Error()).To(ContainSubstring("AFTN validation failed"))
|
||||
})
|
||||
})
|
||||
})
|
||||
|
||||
Describe("IsAFTNError", func() {
|
||||
It("returns true for AFTNError", func() {
|
||||
err := validator.ValidatePriorityIndicator("XX")
|
||||
Expect(validator.IsAFTNError(err)).To(BeTrue())
|
||||
})
|
||||
|
||||
It("returns true for AFTNValidationErrors", func() {
|
||||
telegram := &dto.ParsedTelegram{
|
||||
PriorityIndicator: "XX",
|
||||
PrimaryAddress: "TOOLONG",
|
||||
}
|
||||
err := validator.ValidateTelegram(telegram)
|
||||
Expect(validator.IsAFTNError(err)).To(BeTrue())
|
||||
})
|
||||
|
||||
It("returns false for nil error", func() {
|
||||
Expect(validator.IsAFTNError(nil)).To(BeFalse())
|
||||
})
|
||||
})
|
||||
|
||||
Describe("GetAFTNErrorType", func() {
|
||||
It("extracts field name from AFTNError", func() {
|
||||
err := validator.ValidatePriorityIndicator("XX")
|
||||
Expect(validator.GetAFTNErrorType(err)).To(Equal("priority_indicator"))
|
||||
})
|
||||
|
||||
It("returns 'multiple_errors' for AFTNValidationErrors", func() {
|
||||
telegram := &dto.ParsedTelegram{
|
||||
PriorityIndicator: "XX",
|
||||
PrimaryAddress: "TOOLONG",
|
||||
}
|
||||
err := validator.ValidateTelegram(telegram)
|
||||
Expect(validator.GetAFTNErrorType(err)).To(Equal("multiple_errors"))
|
||||
})
|
||||
|
||||
It("returns 'unknown' for non-AFTN errors", func() {
|
||||
errorType := validator.GetAFTNErrorType(nil)
|
||||
Expect(errorType).To(Equal("unknown"))
|
||||
})
|
||||
})
|
||||
})
|
||||
@@ -0,0 +1,13 @@
|
||||
package validator_test
|
||||
|
||||
import (
|
||||
"testing"
|
||||
|
||||
. "github.com/onsi/ginkgo/v2"
|
||||
. "github.com/onsi/gomega"
|
||||
)
|
||||
|
||||
func TestValidator(t *testing.T) {
|
||||
RegisterFailHandler(Fail)
|
||||
RunSpecs(t, "Validator Suite")
|
||||
}
|
||||
Reference in New Issue
Block a user