notifications: introduce Event & Type types

Author: yhabteab

notifications/event/event.go

@@ -0,0 +1,41 @@
+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  string `json:"url"`  // URL represents the fully qualified URL to the object in Icinga Web 2.
+
+	// 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     Type     `json:"type"`               // Type indicates the type of the event (see Type for possible values).
+	Severity Severity `json:"severity,omitempty"` // The severity of the event (see Severity for possible values).
+	Username string   `json:"username"`           // Username is the name of the user who triggered the event.
+	Message  string   `json:"message"`            // Message is a human-readable message describing the event.
+
+	// 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"`
+}

notifications/event/event_test.go

@@ -0,0 +1,58 @@
+package event
+
+import (
+	"encoding/json"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"testing"
+)
+
+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:      "example.com",
+				Tags:     map[string]string{"tag1": "value1"},
+				Type:     TypeState,
+				Severity: SeverityOK,
+				Username: "testuser",
+				Message:  "Test",
+			}
+
+			data, err := json.Marshal(event)
+			require.NoError(t, err)
+
+			expected := `{"name":"TestEvent","url":"example.com","tags":{"tag1":"value1"},"type":"state","severity":"ok","username":"testuser","message":"Test"}`
+			assert.Equal(t, expected, string(data))
+		})
+
+		t.Run("Empty Severity", func(t *testing.T) {
+			t.Parallel()
+
+			event := &Event{
+				Name:     "TestEvent",
+				URL:      "example.com",
+				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/type.go

@@ -0,0 +1,109 @@
+//go:generate go tool stringer -linecomment -type Type -output type_string.go
+
+package event
+
+import (
+	"database/sql/driver"
+	"encoding/json"
+	"fmt"
+)
+
+// Type represents the type of event sent to the Icinga Notifications API.
+type Type uint8
+
+const (
+	TypeUnknown Type = iota // unknown
+
+	TypeAcknowledgementCleared // acknowledgement-cleared
+	TypeAcknowledgementSet     // acknowledgement-set
+	TypeCustom                 // custom
+	TypeDowntimeEnd            // downtime-end
+	TypeDowntimeRemoved        // downtime-removed
+	TypeDowntimeStart          // downtime-start
+	TypeFlappingEnd            // flapping-end
+	TypeFlappingStart          // flapping-start
+	TypeIncidentAge            // incident-age
+	TypeMute                   // mute
+	TypeState                  // state
+	TypeUnmute                 // unmute
+
+	typeMax // internal
+)
+
+// MarshalJSON implements the [json.Marshaler] interface for Type.
+func (t Type) MarshalJSON() ([]byte, error) {
+	if t != TypeUnknown {
+		return json.Marshal(t.String())
+	} else {
+		return json.Marshal(nil)
+	}
+}
+
+// UnmarshalJSON implements the [json.Unmarshaler] interface for Type.
+func (t *Type) UnmarshalJSON(data []byte) error {
+	if string(data) == "null" {
+		*t = TypeUnknown
+		return nil
+	}
+
+	var typeString string
+	if err := json.Unmarshal(data, &typeString); err != nil {
+		return err
+	}
+
+	parsedType, err := ParseType(typeString)
+	if err != nil {
+		return err
+	}
+
+	*t = parsedType
+	return nil
+}
+
+// Scan implements the [sql.Scanner] interface for Severity.
+// Supports SQL NULL values.
+func (t *Type) Scan(src any) error {
+	if src == nil {
+		*t = TypeUnknown
+		return nil
+	}
+
+	var typeStr string
+	switch val := src.(type) {
+	case string:
+		typeStr = val
+	case []byte:
+		typeStr = string(val)
+	default:
+		return fmt.Errorf("cannot scan Type from %T", src)
+	}
+
+	parsedType, err := ParseType(typeStr)
+	if err != nil {
+		return err
+	}
+
+	*t = parsedType
+	return nil
+}
+
+// Value implements the [driver.Valuer] interface for Severity.
+func (t Type) Value() (driver.Value, error) {
+	if t != TypeUnknown {
+		return t.String(), nil
+	}
+	return nil, nil // Return nil for SeverityNone or invalid values
+}
+
+// ParseType parses a string into a Type.
+//
+// If the string does not match any known type, it returns an error indicating the unknown type.
+func ParseType(s string) (Type, error) {
+	for t := TypeUnknown + 1; t < typeMax; t++ {
+		if s == t.String() {
+			return t, nil
+		}
+	}
+
+	return TypeUnknown, fmt.Errorf("unknown type %q", s)
+}

notifications/event/type_string.go

@@ -0,0 +1,123 @@
+package event
+
+import (
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"testing"
+)
+
+func TestType(t *testing.T) {
+	t.Parallel()
+
+	t.Run("MarshalJSON", func(t *testing.T) {
+		t.Parallel()
+
+		tests := []struct {
+			name     string
+			typeVal  Type
+			expected string
+		}{
+			{"Unknown", TypeUnknown, "null"},
+			{"State", TypeState, `"state"`},
+			{"Mute", TypeMute, `"mute"`},
+			{"Unmute", TypeUnmute, `"unmute"`},
+		}
+
+		for _, tt := range tests {
+			t.Run(tt.name, func(t *testing.T) {
+				t.Parallel()
+
+				data, err := tt.typeVal.MarshalJSON()
+				require.NoError(t, err)
+				assert.Equal(t, tt.expected, string(data))
+			})
+		}
+	})
+
+	t.Run("UnmarshalJSON", func(t *testing.T) {
+		t.Parallel()
+
+		tests := []struct {
+			name     string
+			input    string
+			expected Type
+			err      bool
+		}{
+			{"Unknown", "null", TypeUnknown, false},
+			{"State", `"state"`, TypeState, false},
+			{"Mute", `"mute"`, TypeMute, false},
+			{"Unmute", `"unmute"`, TypeUnmute, false},
+			{"Invalid", `"invalid"`, TypeUnknown, true}, // Should return an error for unsupported type.
+		}
+
+		for _, tt := range tests {
+			t.Run(tt.name, func(t *testing.T) {
+				t.Parallel()
+
+				var tType Type
+				if err := tType.UnmarshalJSON([]byte(tt.input)); tt.err {
+					assert.Error(t, err)
+				} else {
+					require.NoError(t, err)
+					assert.Equal(t, tt.expected, tType)
+				}
+			})
+		}
+	})
+
+	t.Run("Scan", func(t *testing.T) {
+		t.Parallel()
+
+		tests := []struct {
+			name     string
+			input    any
+			expected Type
+			err      bool
+		}{
+			{"Unknown", nil, TypeUnknown, false},
+			{"State", "state", TypeState, false},
+			{"Mute", "mute", TypeMute, false},
+			{"Unmute", "unmute", TypeUnmute, false},
+			{"Invalid", "invalid", TypeUnknown, true}, // Should return an error for unsupported type.
+		}
+
+		for _, tt := range tests {
+			t.Run(tt.name, func(t *testing.T) {
+				t.Parallel()
+
+				var tType Type
+				if err := tType.Scan(tt.input); tt.err {
+					assert.Error(t, err)
+				} else {
+					require.NoError(t, err)
+					assert.Equal(t, tt.expected, tType)
+				}
+			})
+		}
+	})
+
+	t.Run("Value", func(t *testing.T) {
+		t.Parallel()
+
+		tests := []struct {
+			name     string
+			typeVal  Type
+			expected any
+		}{
+			{"Unknown", TypeUnknown, nil},
+			{"State", TypeState, "state"},
+			{"Mute", TypeMute, "mute"},
+			{"Unmute", TypeUnmute, "unmute"},
+		}
+
+		for _, tt := range tests {
+			t.Run(tt.name, func(t *testing.T) {
+				t.Parallel()
+
+				value, err := tt.typeVal.Value()
+				require.NoError(t, err)
+				assert.Equal(t, tt.expected, value)
+			})
+		}
+	})
+}

notifications/event/type_test.go

@@ -22,6 +22,10 @@ type Bool struct {
 	Valid bool // Valid is true if Bool is not NULL
 }
 
+// IsZero implements the json.isZeroer interface.
+// A Bool is considered zero if its Valid field is false regardless of its actual Bool value.
+func (b Bool) IsZero() bool { return !b.Valid }
+
 // MarshalJSON implements the json.Marshaler interface.
 func (b Bool) MarshalJSON() ([]byte, error) {
 	if !b.Valid {