Add a common notifications client & its utilities

go.mod

@@ -33,3 +33,7 @@ require (
 	golang.org/x/sys v0.26.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )
+
+tool (
+	golang.org/x/tools/cmd/stringer
+)

notifications/event/event.go

@@ -0,0 +1,55 @@
+package event
+
+import (
+	"github.com/icinga/icinga-go-library/types"
+)
+
+// Event represents an Icinga Notifications event that can be sent to the Icinga Notifications API.
+//
+// It contains all the necessary fields to fully describe an Icinga Notifications event and can be used to
+// serialize the event to JSON for transmission over HTTP as well as to deserialize it from JSON requests.
+type Event struct {
+	Name string `json:"name"` // Name is the name of the object this event is all about.
+
+	// URL represents a URL or a relative reference to the object in Icinga Web 2.
+	//
+	// If the URL field does not contain a URL, but only a reference relative to an Icinga Web URL, the Icinga
+	// Notifications daemon will create a URL. This allows a source to set this to something like
+	// "/icingadb/host?name=example.com" without having to know the Icinga Web 2 root URL by itself.
+	URL string `json:"url"`
+
+	// Tags contains additional metadata for the event that uniquely identifies the object it's referring to.
+	//
+	// It is a map of string keys to string values, allowing for flexible tagging of events if the event
+	// name alone is not sufficient to identify the object. In the case of using Icinga DB as a source, the
+	// tags will typically look like this:
+	// For hosts: {"host": "host_name"} and for services: {"host": "host_name", "service": "service_name"}.
+	Tags map[string]string `json:"tags"`
+
+	// Type indicates the type of the event.
+	Type Type `json:"type"`
+	// Severity of the event.
+	Severity Severity `json:"severity,omitempty"`
+	// Username is the name of the user who triggered the event.
+	Username string `json:"username"`
+	// Message is a human-readable message describing the event.
+	Message string `json:"message"`
+
+	// Mute indicates whether the object this event is referring to should be muted or not.
+	//
+	// If set to true, the object will be muted in Icinga Web 2, meaning that notifications for this object
+	// will not be sent out. The MuteReason field can be used to provide a reason for muting the object.
+	// If you don't set this field to anything, it will be omitted from the generated JSON.
+	Mute types.Bool `json:"mute,omitzero"`
+
+	// MuteReason provides a reason for muting the object if Mute is set to true.
+	//
+	// Setting this field to an empty string while Mute is true will cause the request to fail,
+	// as Icinga Notifications requires a reason for muting an object. Otherwise, it will be omitted
+	// from the encoded JSON.
+	MuteReason string `json:"mute_reason,omitempty"`
+
+	// RulesVersion and RuleIds are the source rules matching for this Event.
+	RulesVersion string   `json:"rules_version"`
+	RuleIds      []string `json:"rule_ids"`
+}

notifications/event/event_test.go

@@ -0,0 +1,72 @@
+package event
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestEvent(t *testing.T) {
+	t.Parallel()
+
+	t.Run("JsonEncode", func(t *testing.T) {
+		t.Parallel()
+
+		t.Run("Valid Event", func(t *testing.T) {
+			t.Parallel()
+
+			event := &Event{
+				Name:         "TestEvent",
+				URL:          "/icingadb/service?name=https%20ssl%20v3.0%20compatibility%20IE%206.0&host.name=example%20host",
+				Tags:         map[string]string{"tag1": "value1"},
+				Type:         TypeState,
+				Severity:     SeverityOK,
+				Username:     "testuser",
+				Message:      "Test",
+				RulesVersion: "0x1",
+				RuleIds:      []string{"1", "2", "3", "6"},
+			}
+
+			data, err := json.Marshal(event)
+			require.NoError(t, err)
+
+			expected := `
+				{
+					"name":"TestEvent",
+					"url":"/icingadb/service?name=https%20ssl%20v3.0%20compatibility%20IE%206.0&host.name=example%20host",
+					"tags":{"tag1":"value1"},
+					"type":"state",
+					"severity":"ok",
+					"username":"testuser",
+					"message":"Test",
+					"rules_version": "0x1",
+					"rule_ids": ["1", "2", "3", "6"]
+				}`
+			assert.JSONEq(t, expected, string(data), "JSON encoding does not match expected output")
+		})
+
+		t.Run("Empty Severity", func(t *testing.T) {
+			t.Parallel()
+
+			event := &Event{
+				Name:     "TestEvent",
+				URL:      "https://example.com/icingaweb2/icingadb/service?name=https%20ssl%20v3.0%20compatibility%20IE%206.0&host.name=example%20host",
+				Tags:     map[string]string{"tag1": "value1"},
+				Type:     TypeMute,
+				Username: "testuser",
+				Message:  "Test",
+			}
+
+			data, err := json.Marshal(event)
+			require.NoError(t, err)
+			assert.NotContains(t, string(data), "\"severity\":", "severity should be omitted when empty")
+
+			event.Severity = SeverityNone
+			data, err = json.Marshal(event)
+			require.NoError(t, err)
+			assert.NotContains(t, string(data), "\"severity\":", "severity should be omitted when set to none")
+		})
+	})
+}

notifications/event/severity.go

@@ -0,0 +1,106 @@
+//go:generate go tool stringer -linecomment -type Severity -output severity_string.go
+
+package event
+
+import (
+	"database/sql/driver"
+	"encoding/json"
+	"fmt"
+)
+
+// Severity represents the severity level of an event in Icinga notifications.
+// It is an integer type with predefined constants for different severity levels.
+type Severity uint8
+
+const (
+	SeverityNone Severity = iota // none
+
+	SeverityOK      // ok
+	SeverityDebug   // debug
+	SeverityInfo    // info
+	SeverityNotice  // notice
+	SeverityWarning // warning
+	SeverityErr     // err
+	SeverityCrit    // crit
+	SeverityAlert   // alert
+	SeverityEmerg   // emerg
+
+	severityMax // internal
+)
+
+// MarshalJSON implements the [json.Marshaler] interface for Severity.
+func (s Severity) MarshalJSON() ([]byte, error) {
+	if s != SeverityNone {
+		return json.Marshal(s.String())
+	} else {
+		return json.Marshal(nil)
+	}
+}
+
+// UnmarshalJSON implements the [json.Unmarshaler] interface for Severity.
+func (s *Severity) UnmarshalJSON(data []byte) error {
+	if string(data) == "null" {
+		*s = SeverityNone
+		return nil
+	}
+
+	var severityStr string
+	if err := json.Unmarshal(data, &severityStr); err != nil {
+		return err
+	}
+
+	severity, err := ParseSeverity(severityStr)
+	if err != nil {
+		return err
+	}
+
+	*s = severity
+	return nil
+}
+
+// Scan implements the [sql.Scanner] interface for Severity.
+// Supports SQL NULL values.
+func (s *Severity) Scan(src any) error {
+	if src == nil {
+		*s = SeverityNone
+		return nil
+	}
+
+	var severityStr string
+	switch val := src.(type) {
+	case string:
+		severityStr = val
+	case []byte:
+		severityStr = string(val)
+	default:
+		return fmt.Errorf("cannot scan severity from type %T", src)
+	}
+
+	severity, err := ParseSeverity(severityStr)
+	if err != nil {
+		return err
+	}
+
+	*s = severity
+	return nil
+}
+
+// Value implements the [driver.Valuer] interface for Severity.
+func (s Severity) Value() (driver.Value, error) {
+	if s != SeverityNone {
+		return s.String(), nil
+	}
+	return nil, nil // Return nil for SeverityNone or invalid values
+}
+
+// ParseSeverity parses a string representation of a severity level and returns the corresponding Severity value.
+// If the string does not match any known severity, it returns an error indicating the unknown severity.
+func ParseSeverity(name string) (Severity, error) {
+	for s := range severityMax {
+		if s.String() == name {
+			return s, nil
+		}
+	}
+
+	return SeverityNone, fmt.Errorf("unknown severity %q", name)
+}

notifications/event/severity_test.go

@@ -0,0 +1,109 @@
+package event
+
+import (
+	"database/sql/driver"
+	"testing"
+
+	"github.com/icinga/icinga-go-library/testutils"
+)
+
+func TestSeverity(t *testing.T) {
+	t.Parallel()
+
+	t.Run("MarshalJson", func(t *testing.T) {
+		t.Parallel()
+
+		testdata := []testutils.TestCase[string, Severity]{
+			{Name: "None", Expected: "null", Data: SeverityNone, Error: nil},
+			{Name: "Ok", Expected: `"ok"`, Data: SeverityOK, Error: nil},
+			{Name: "Debug", Expected: `"debug"`, Data: SeverityDebug, Error: nil},
+			{Name: "Info", Expected: `"info"`, Data: SeverityInfo, Error: nil},
+			{Name: "Notice", Expected: `"notice"`, Data: SeverityNotice, Error: nil},
+			{Name: "Warning", Expected: `"warning"`, Data: SeverityWarning, Error: nil},
+			{Name: "Err", Expected: `"err"`, Data: SeverityErr, Error: nil},
+			{Name: "Crit", Expected: `"crit"`, Data: SeverityCrit, Error: nil},
+			{Name: "Alert", Expected: `"alert"`, Data: SeverityAlert, Error: nil},
+			{Name: "Emerg", Expected: `"emerg"`, Data: SeverityEmerg, Error: nil},
+		}
+
+		for _, tt := range testdata {
+			t.Run(tt.Name, tt.F(func(s Severity) (string, error) {
+				data, err := s.MarshalJSON()
+				return string(data), err
+			}))
+		}
+	})
+
+	t.Run("UnmarshalJson", func(t *testing.T) {
+		t.Parallel()
+
+		testData := []testutils.TestCase[Severity, string]{
+			{Name: "None", Expected: SeverityNone, Data: `null`, Error: nil},
+			{Name: "Ok", Expected: SeverityOK, Data: `"ok"`, Error: nil},
+			{Name: "Debug", Expected: SeverityDebug, Data: `"debug"`, Error: nil},
+			{Name: "Info", Expected: SeverityInfo, Data: `"info"`, Error: nil},
+			{Name: "Notice", Expected: SeverityNotice, Data: `"notice"`, Error: nil},
+			{Name: "Warning", Expected: SeverityWarning, Data: `"warning"`, Error: nil},
+			{Name: "Err", Expected: SeverityErr, Data: `"err"`, Error: nil},
+			{Name: "Crit", Expected: SeverityCrit, Data: `"crit"`, Error: nil},
+			{Name: "Alert", Expected: SeverityAlert, Data: `"alert"`, Error: nil},
+			{Name: "Emerg", Expected: SeverityEmerg, Data: `"emerg"`, Error: nil},
+			{Name: "Invalid", Expected: SeverityNone, Data: `"invalid"`, Error: testutils.ErrorContains(`unknown severity "invalid"`)},
+		}
+
+		for _, tt := range testData {
+			t.Run(tt.Name, tt.F(func(input string) (Severity, error) {
+				var s Severity
+				return s, s.UnmarshalJSON([]byte(input))
+			}))
+		}
+	})
+
+	t.Run("Scan", func(t *testing.T) {
+		t.Parallel()
+
+		testData := []testutils.TestCase[Severity, any]{
+			{Name: "None", Expected: SeverityNone, Data: nil, Error: nil},
+			{Name: "Ok", Expected: SeverityOK, Data: `ok`, Error: nil},
+			{Name: "Debug", Expected: SeverityDebug, Data: `debug`, Error: nil},
+			{Name: "Info", Expected: SeverityInfo, Data: `info`, Error: nil},
+			{Name: "Notice", Expected: SeverityNotice, Data: `notice`, Error: nil},
+			{Name: "Warning", Expected: SeverityWarning, Data: `warning`, Error: nil},
+			{Name: "Err", Expected: SeverityErr, Data: `err`, Error: nil},
+			{Name: "Crit", Expected: SeverityCrit, Data: `crit`, Error: nil},
+			{Name: "Alert", Expected: SeverityAlert, Data: `alert`, Error: nil},
+			{Name: "Alert Bytes", Expected: SeverityAlert, Data: []byte("alert"), Error: nil},
+			{Name: "Emerg", Expected: SeverityEmerg, Data: `emerg`, Error: nil},
+			{Name: "Invalid Number", Expected: SeverityNone, Data: 150, Error: testutils.ErrorContains(`cannot scan severity from type int`)},
+			{Name: "Invalid String", Expected: SeverityNone, Data: `invalid`, Error: testutils.ErrorContains(`unknown severity "invalid"`)},
+		}
+
+		for _, tt := range testData {
+			t.Run(tt.Name, tt.F(func(input any) (Severity, error) {
+				var s Severity
+				return s, s.Scan(input)
+			}))
+		}
+	})
+
+	t.Run("Value", func(t *testing.T) {
+		t.Parallel()
+
+		testdata := []testutils.TestCase[driver.Value, Severity]{
+			{Name: "None", Expected: nil, Data: SeverityNone, Error: nil},
+			{Name: "Ok", Expected: `ok`, Data: SeverityOK, Error: nil},
+			{Name: "Debug", Expected: `debug`, Data: SeverityDebug, Error: nil},
+			{Name: "Info", Expected: `info`, Data: SeverityInfo, Error: nil},
+			{Name: "Notice", Expected: `notice`, Data: SeverityNotice, Error: nil},
+			{Name: "Warning", Expected: `warning`, Data: SeverityWarning, Error: nil},
+			{Name: "Err", Expected: `err`, Data: SeverityErr, Error: nil},
+			{Name: "Crit", Expected: `crit`, Data: SeverityCrit, Error: nil},
+			{Name: "Alert", Expected: `alert`, Data: SeverityAlert, Error: nil},
+			{Name: "Emerg", Expected: `emerg`, Data: SeverityEmerg, Error: nil},
+		}
+
+		for _, tt := range testdata {
+			t.Run(tt.Name, tt.F(func(s Severity) (driver.Value, error) { return s.Value() }))
+		}
+	})
+}