Add a base Icinga Notifications Client

yhabteab · oxzi · yhabteab · commit 05e69f3f0041 · 2025-08-07T11:15:04.000+02:00
Alvar did most of the work here in the Icinga DB repo, I'm just trying
to outsource the basic functionality to this library, so that they can
also be used by other projects.

Co-Authored-By: Alvar Penning &lt;alvar.penning@icinga.com&gt;
diff --git a/notifications/client.go b/notifications/client.go
@@ -0,0 +1,214 @@
+package notifications
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strconv"
+	"strings"
+
+	"github.com/icinga/icinga-go-library/notifications/event"
+	"github.com/pkg/errors"
+)
+
+// ErrRulesOutdated implies that the rules version between Icinga DB and Icinga Notifications mismatches.
+var ErrRulesOutdated = fmt.Errorf("rules version is outdated")
+
+// BasicAuthTransport is an http.RoundTripper that adds basic authentication and a User-Agent header to HTTP requests.
+type BasicAuthTransport struct {
+	http.RoundTripper // RoundTripper is the underlying HTTP transport to use for making requests.
+
+	Username   string
+	Password   string
+	ClientName string // ClientName is used to set the User-Agent header.
+}
+
+// RoundTrip adds basic authentication headers to the request and executes the HTTP request.
+// If RoundTripper is nil, it defaults to http.DefaultTransport.
+func (b *BasicAuthTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	req.SetBasicAuth(b.Username, b.Password)
+	// As long as our round tripper is used for the client, the User-Agent header below
+	// overrides any other value set by the user.
+	req.Header.Set("User-Agent", b.ClientName)
+
+	return b.RoundTripper.RoundTrip(req)
+}
+
+// Client provides a common interface to interact with the Icinga Notifications API.
+// It holds the configuration for the API endpoint and the HTTP client used to make requests.
+type Client struct {
+	cfg Config // cfg holds base API endpoint URL and authentication details.
+
+	client http.Client // HTTP client used for making requests to the Icinga Notifications API.
+
+	IcingaWebBasUrl *url.URL // IcingaWebBaseUrl holds the base URL for Icinga Web 2.
+	Endpoints       struct {
+		EventRules   string // EventRules holds the URL for the event rules endpoint.
+		ProcessEvent string // ProcessEvent holds the URL for the process event endpoint.
+	}
+}
+
+// NewClient creates a new Client instance with the provided configuration.
+//
+// The projectName is used to set the User-Agent header in HTTP requests sent by this client and should be
+// set to the name of the project using this client (e.g., "Icinga DB").
+//
+// It may return an error if the API base URL or Icinga Web 2 base URL cannot be parsed.
+func NewClient(cfg Config, projectName string) (*Client, error) {
+	client := &Client{
+		cfg: cfg,
+		client: http.Client{
+			//Timeout: cfg.Timeout, // Uncomment once Timeout is (should be?) user configurable.
+			Transport: &BasicAuthTransport{
+				RoundTripper: http.DefaultTransport,
+				Username:     cfg.Username,
+				Password:     cfg.Password,
+				ClientName:   projectName,
+			},
+		},
+	}
+
+	baseUrl, err := url.Parse(cfg.ApiBaseUrl)
+	if err != nil {
+		return nil, errors.Wrap(err, "unable to parse API base URL")
+	}
+
+	client.Endpoints.EventRules = baseUrl.ResolveReference(&url.URL{Path: "/event-rules"}).String()
+	client.Endpoints.ProcessEvent = baseUrl.ResolveReference(&url.URL{Path: "/process-event"}).String()
+
+	client.IcingaWebBasUrl, err = url.Parse(cfg.IcingaWeb2BaseUrl)
+	if err != nil {
+		return nil, errors.Wrap(err, "unable to parse Icinga Web 2 base URL")
+	}
+
+	return client, nil
+}
+
+// GetRules retrieves the event rules from the Icinga Notifications API.
+//
+// It sends a GET request to the /event-rules endpoint and decodes the response into a RulesResult object.
+// If the request fails or the response is not as expected, it returns an error; otherwise, it returns the
+// RulesResult containing the version information and a map of rules.
+func (c *Client) GetRules(ctx context.Context) (*RulesResult, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.Endpoints.EventRules, nil)
+	if err != nil {
+		return nil, errors.Wrap(err, "cannot create HTTP request")
+	}
+
+	resp, err := c.client.Do(req)
+	if err != nil {
+		return nil, errors.Wrap(err, "cannot GET event rules")
+	}
+
+	defer func() {
+		_, _ = io.Copy(io.Discard, resp.Body)
+		_ = resp.Body.Close()
+	}()
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, errors.Errorf("unexpected status code %q (%d) for rules", resp.Status, resp.StatusCode)
+	}
+
+	var rulesResult RulesResult
+	if err := json.NewDecoder(resp.Body).Decode(&rulesResult); err != nil {
+		return nil, errors.Wrap(err, "cannot decode event rules")
+	}
+
+	return &rulesResult, nil
+}
+
+// ProcessEvent submits an event to the Icinga Notifications /process-event API endpoint.
+//
+// It serializes the event into JSON and sends it as a POST request to the process event endpoint.
+// The given ruleVersion is transmitted as [XIcingaRulesVersion] header along with the [XIcingaRulesId] header,
+// containing a comma-separated list of rule IDs. If non-empty ruleIDs are provided, ruleVersion must also be
+// provided, otherwise if either of them is empty, the event will not be sent at all, as Icinga Notifications
+// is going to reject the event anyway.
+//
+// It may return an ErrRulesOutdated error, implying that the provided ruleVersion does not match the current rules
+// version in Icinga Notifications daemon. In this case, the caller can do whatever is necessary to update the rules,
+// such as refetching the event rules via GetRules and retrying the event submission.
+//
+// If the request fails or the response is not as expected, it returns an error; otherwise, it returns nil.
+func (c *Client) ProcessEvent(ctx context.Context, ev *event.Event, ruleVersion string, ruleIDs ...int64) error {
+	// The Icinga Notifications daemon is going to reject the event anyway if ruleVersion or ruleIDs are empty.
+	// So, don't waste resources on sending the event.
+	if ruleVersion == "" || len(ruleIDs) == 0 {
+		return nil
+	}
+
+	body, err := json.Marshal(ev)
+	if err != nil {
+		return errors.Wrap(err, "cannot encode event to JSON")
+	}
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.Endpoints.ProcessEvent, bytes.NewReader(body))
+	if err != nil {
+		return errors.Wrap(err, "cannot create HTTP request")
+	}
+
+	ruleIdsStrArr := make([]string, 0, len(ruleIDs))
+	for _, ruleId := range ruleIDs {
+		ruleIdsStrArr = append(ruleIdsStrArr, strconv.FormatInt(ruleId, 10))
+	}
+
+	req.Header.Add("Content-Type", "application/json")
+	req.Header.Add("Accept", "application/json")
+	req.Header.Add(XIcingaRulesVersion, ruleVersion)
+	req.Header.Add(XIcingaRulesId, strings.Join(ruleIdsStrArr, ","))
+
+	res, err := c.client.Do(req)
+	if err != nil {
+		return errors.Wrap(err, "cannot POST HTTP request to process event")
+	}
+
+	defer func() {
+		_, _ = io.Copy(io.Discard, res.Body)
+		_ = res.Body.Close()
+	}()
+
+	if res.StatusCode == http.StatusPreconditionFailed {
+		return ErrRulesOutdated // Indicates that the rules version is outdated and needs to be refetched.
+	}
+
+	if res.StatusCode >= http.StatusOK && res.StatusCode <= 299 {
+		return nil // Successfully processed the event.
+	}
+
+	if res.StatusCode == http.StatusNotAcceptable {
+		return nil // Either superfluous state change event or empty rule IDs provided.
+	}
+
+	var buf bytes.Buffer
+	_, _ = io.Copy(&buf, &io.LimitedReader{R: res.Body, N: 1 << 20}) // Limit the error message length to avoid memory exhaustion.
+
+	return errors.Errorf("unexpected response from process event API, status %q (%d): %q",
+		res.Status, res.StatusCode, strings.TrimSpace(buf.String()))
+}
+
+// JoinIcingaWeb2Path constructs a URL by joining the Icinga Web 2 base URL with the provided relative URL.
+//
+// It is used to convert any relative URL into an absolute URL that points to the Icinga Web 2 instance.
+// A relative URL like "/icingadb/host" is transformed to e.g. "https://icinga.example.com/icingaweb2/icingadb/host"
+// after passing through this method, assuming the Icinga Web 2 base URL is "https://icinga.example.com/icingaweb2".
+func (c *Client) JoinIcingaWeb2Path(relativePath string) *url.URL {
+	return c.IcingaWebBasUrl.JoinPath(relativePath)
+}
+
+// RulesResult represents the response structure for rules fetched from the Icinga Notifications API.
+type RulesResult struct {
+	Version string             // Version of the event rules fetched from the API.
+	Rules   map[int64]RuleResp // Rules is a map of rule IDs to their corresponding RuleResp objects.
+}
+
+// RuleResp describes a rule response object from Icinga Notifications /event-rules API.
+// It contains the rule ID, name, and the object filter expression associated with the rule.
+type RuleResp struct {
+	Id               int64
+	Name             string
+	ObjectFilterExpr string
+}
diff --git a/notifications/config.go b/notifications/config.go
@@ -0,0 +1,9 @@
+package notifications
+
+// Config defines all the required configuration for the Icinga Notifications API client.
+type Config struct {
+	ApiBaseUrl        string `yaml:"api-base-url" env:"API_BASE_URL"`
+	Username          string `yaml:"username" env:"USERNAME"`
+	Password          string `yaml:"password" env:"PASSWORD,unset"`
+	IcingaWeb2BaseUrl string `yaml:"icingaweb2-base-url" env:"ICINGAWEB2_BASE_URL"`
+}
diff --git a/notifications/xhttp_headers.go b/notifications/xhttp_headers.go
@@ -0,0 +1,11 @@
+package notifications
+
+// These headers are used to pass metadata about the request made to the Icinga Notifications API.
+// Currently, they are used to convey the version of the rules and the ID of the rules being used.
+//
+// They should be set in the HTTP request headers when making requests to the Icinga Notifications API,
+// and by the Icinga Notifications daemon when processing such requests.
+const (
+	XIcingaRulesVersion = "X-Icinga-Rules-Version"
+	XIcingaRulesId      = "X-Icinga-Rules-Id"
+)
diff --git a/utils/utils.go b/utils/utils.go
@@ -11,6 +11,7 @@ import (
 	"golang.org/x/exp/utf8string"
 	"iter"
 	"net"
+	"net/url"
 	"os"
 	"path/filepath"
 	"slices"
@@ -186,3 +187,15 @@ func IterateOrderedMap[K cmp.Ordered, V any](m map[K]V) iter.Seq2[K, V] {
 		}
 	}
 }
+
+// RawUrlEncode mimics PHP's rawurlencode to be used for parameter encoding.
+//
+// Icinga Web uses rawurldecode instead of urldecode, which, as its main difference, does not honor the plus char ('+')
+// as a valid substitution for space (' '). Unfortunately, Go's url.QueryEscape does this very substitution and
+// url.PathEscape does a bit too less and has a misleading name on top.
+//
+//   - https://www.php.net/manual/en/function.rawurlencode.php
+//   - https://github.com/php/php-src/blob/php-8.2.12/ext/standard/url.c#L538
+func RawUrlEncode(s string) string {
+	return strings.ReplaceAll(url.QueryEscape(s), "+", "%20")
+}
