Publish ITWorx Pulse source

internal/freshness/evaluator.go

@@ -0,0 +1,54 @@
+package freshness
+
+import (
+	"errors"
+	"time"
+
+	"github.com/itworx/pulse/internal/datasource"
+)
+
+type Input struct {
+	SourceID string
+	Required bool
+	Health   datasource.SourceHealth
+	Previous datasource.HealthState
+	Now      time.Time
+}
+type Result struct {
+	State       datasource.HealthState
+	Age         *time.Duration
+	LastKnownAt time.Time
+	Recovery    bool
+	Event       string
+	Warning     string
+}
+
+func Evaluate(input Input) (Result, error) {
+	if input.SourceID == "" {
+		return Result{}, errors.New("source id is required")
+	}
+	now := input.Now
+	if now.IsZero() {
+		now = time.Now().UTC()
+	}
+	if err := input.Health.Validate(now); err != nil {
+		return Result{}, err
+	}
+	result := Result{State: input.Health.EffectiveState(now), LastKnownAt: input.Health.ObservedAt}
+	if !input.Health.ObservedAt.IsZero() {
+		age := now.Sub(input.Health.ObservedAt)
+		if age < 0 {
+			age = 0
+		}
+		result.Age = &age
+	}
+	if input.Required && result.State != datasource.HealthHealthy && result.State != datasource.HealthDegraded {
+		result.State = datasource.HealthUnknown
+		result.Warning = "REQUIRED_SOURCE_UNKNOWN"
+	}
+	if input.Previous == datasource.HealthUnknown && (result.State == datasource.HealthHealthy || result.State == datasource.HealthDegraded) {
+		result.Recovery = true
+		result.Event = "DATASOURCE_RECOVERED"
+	}
+	return result, nil
+}

internal/freshness/evaluator_test.go

@@ -0,0 +1,40 @@
+package freshness
+
+import (
+	"github.com/itworx/pulse/internal/datasource"
+	"testing"
+	"time"
+)
+
+func TestRequiredStaleSourceIsUnknownWithAge(t *testing.T) {
+	now := time.Date(2026, 8, 1, 12, 0, 0, 0, time.UTC)
+	result, err := Evaluate(Input{SourceID: "prom", Required: true, Now: now, Health: datasource.SourceHealth{State: datasource.HealthHealthy, ObservedAt: now.Add(-2 * time.Minute), ReceivedAt: now, Policy: datasource.FreshnessPolicy{MaxAge: time.Minute}}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.State != datasource.HealthUnknown || result.Age == nil || *result.Age != 2*time.Minute {
+		t.Fatalf("unexpected stale result: %+v", result)
+	}
+}
+func TestRecoveryEventOnlyFollowsUnknown(t *testing.T) {
+	now := time.Now().UTC()
+	health := datasource.SourceHealth{State: datasource.HealthHealthy, ObservedAt: now, ReceivedAt: now, Policy: datasource.FreshnessPolicy{MaxAge: time.Minute}}
+	result, err := Evaluate(Input{SourceID: "prom", Previous: datasource.HealthUnknown, Health: health, Now: now})
+	if err != nil || !result.Recovery || result.Event != "DATASOURCE_RECOVERED" {
+		t.Fatalf("unexpected recovery: %+v %v", result, err)
+	}
+	result, err = Evaluate(Input{SourceID: "prom", Previous: datasource.HealthHealthy, Health: health, Now: now})
+	if err != nil || result.Recovery {
+		t.Fatal("false recovery event")
+	}
+}
+func TestMissingTelemetryNeverBecomesHealthy(t *testing.T) {
+	now := time.Now().UTC()
+	result, err := Evaluate(Input{SourceID: "prom", Required: true, Previous: datasource.HealthUnknown, Now: now, Health: datasource.SourceHealth{State: datasource.HealthUnknown, ReceivedAt: now, Policy: datasource.FreshnessPolicy{MaxAge: time.Minute}}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.State == datasource.HealthHealthy {
+		t.Fatal("missing telemetry became healthy")
+	}
+}