Add a common notifications client & its utilities #145

yhabteab · 2025-08-06T15:45:08Z

This PR introduces a new notifications package to our Icinga Go library. The package is designed to handle common
Icinga Notifications related tasks, that can be used by any Icinga Notifications source. It provides a set of functions and types that simplify and centralize the interaction with Icinga Notifications API. Within the root of this package, you will find the following files:

client.go: This file contains the actual client implementation with a custom HTTP round tripper that handles
the necessary authentication before sending the final request to the Icinga API.
config.go: This file defines the configuration structure that every Icinga Notifications source is required to provide.
xhttp_headers.go: This file contains our custom HTTP header constants only that should be used by the Icinga
Notifications sources to ensure consistency and compatibility with the Icinga API. Currently, it includes only
X-Icinga-Rules-Version header, which is used to specify the version of the rules that are being used by the source and
X-Icinga-Rules-Id header, which is used to specify the unique identifier of the rules that are being used by the source.
Of course, in order to be consistent with the HTTP header naming conventions in Icinga Web 2, both custom headers
are prefixed with X-Icinga-.

The event package within the notifications package contains common event related types and utilities that should
be used by any Icinga Notifications source as well as by the Icinga Notifications daemon itself.

The change list appears to be quite big, but don't be fooled by it :). Most of them are just unit tests and autogenerated
code. The actual code changes are quite minimal and focused on the new functionality described above.

Oops, did I say autogenerated code? Yes, I did ;)! The notifications package makes use of the Go stringer tool to implement the String() method for the event.Type and event.Severity types in an efficient manner. So, don't be surprised to see the autogenerated files in the event package.

Oh, and one more thing: most of the work was done by Alvar in the Icinga DB repository, so I just had to outsource it to the Icinga Go library with some minor adjustments. So, credit goes to him for the majority of the work.

This PR is required by

julianbrost · 2025-08-06T16:40:17Z

I'm not sure if this is the right place to add this. The reasoning probably is similar to Icinga/icinga-notifications#304. One thing to consider here: do we expect external projects using this eventually? In this case, this would create dependency updates for them even though if nothing relevant to them changed. So I think having a separate repository with independent versioning for this is also worth considering.

lippserd · 2025-08-19T11:54:15Z

I'm not sure if this is the right place to add this. The reasoning probably is similar to Icinga/icinga-notifications#304. One thing to consider here: do we expect external projects using this eventually? In this case, this would create dependency updates for them even though if nothing relevant to them changed. So I think having a separate repository with independent versioning for this is also worth considering.

I like this idea. How about a MIT licensed go-icinga-notifications project with this code, and the channel base?

oxzi · 2025-09-02T13:50:26Z

After today's discussion to keep these changes in the IGL, I have skimmed the PR once again. In general, it looks good to me. However, it should be merged together with its sibling PRs as otherwise fix-up PRs would follow here.

notifications/client.go

notifications/event/event_test.go

notifications/event/type.go

notifications/source/client.go

yhabteab · 2025-09-05T11:10:52Z

Changed the tabular test cases to use testutils.TestCase instead of a custom one!

- Bump IGL to latest changes in Icinga/icinga-go-library#145. - Allow specifying which pipeline keys are relevant, ignore others. - Allow specifying which pipeline key should be parsed in which type. - Create history.DowntimeHistoryMeta as a chimera combining history.DowntimeHistory and history.HistoryDowntime to allow access event_type, distinguishing between downtime_start and downtime_end. - Trace times for submission steps in the worker. Turns out, the single threaded worker blocks roughly two seconds for each Client.ProcessEvent method call. This might sum up to minutes if lots of events are processed at once. My current theory is that the delay results in the expensive bcrypt hash comparison on Notifications.

Synchronize codebase against latest version of Icinga/icinga-go-library#145, containing package changes.

- Bump IGL to latest changes in Icinga/icinga-go-library#145. - Allow specifying which pipeline keys are relevant, ignore others. - Allow specifying which pipeline key should be parsed in which type. - Create history.DowntimeHistoryMeta as a chimera combining history.DowntimeHistory and history.HistoryDowntime to allow access event_type, distinguishing between downtime_start and downtime_end. - Trace times for submission steps in the worker. Turns out, the single threaded worker blocks roughly two seconds for each Client.ProcessEvent method call. This might sum up to minutes if lots of events are processed at once. My current theory is that the delay results in the expensive bcrypt hash comparison on Notifications.

oxzi · 2025-09-09T09:51:15Z

Removed the custom HTTP headers and moved the rules to the Event struct to address Icinga/icinga-notifications#324 (comment).

- Bump IGL to latest changes in Icinga/icinga-go-library#145. - Allow specifying which pipeline keys are relevant, ignore others. - Allow specifying which pipeline key should be parsed in which type. - Create history.DowntimeHistoryMeta as a chimera combining history.DowntimeHistory and history.HistoryDowntime to allow access event_type, distinguishing between downtime_start and downtime_end. - Trace times for submission steps in the worker. Turns out, the single threaded worker blocks roughly two seconds for each Client.ProcessEvent method call. This might sum up to minutes if lots of events are processed at once. My current theory is that the delay results in the expensive bcrypt hash comparison on Notifications.

Synchronize codebase against latest version of Icinga/icinga-go-library#145, containing package changes.

As this is intended to be an user facing API, the API documentation was a bit extended. Furthermore, some types were simplified. For example, RulesResp was replaced by a simple string. For an implementation, this struct did not hold any further required information not already being part of the map.

…lues (name, url, etc) are moved into this struct and used accordingly

- Introduce a plugin table to store plugin related info. On daemon start the plugin table is upserted. - Each plugin defines its own required form elements for config as configOption(s). - Configured channels start and maintain there plugin.

- The Upsert() func is no longer required because Info{} contains all that properties. - Fix reciver param name of Info.TableName() method. - Remove type from GetInfo to make it non-configurable. The file name should always be used as the type.

The "Tags" and "Extra Tags" printed in the plugin.FormatMessage were directly read from their map, thus having no order. This resulted in the same NotificationRequest being represented by different messages due to the unordered map. This change was the result of investigating Go's new rangefunc experiment[0]. The utilization of this novel language feature - which can also be indirectly used in the absence of `GOEXPERIMENT=rangefunc` - ensures that the map is traversed in key order. Closes #177. [0]: https://go.dev/wiki/RangefuncExperiment

In a nutshell, the newly introduced plugin.PopulateDefaults function populates all fields of a Plugin-implementing struct with those fields from Info.ConfigAttributes where ConfigOption.Default is set. Thus, a single function call before parsing the user-submitted configuration within the Plugin.SetConfig method sets default values. As a result of the discussion between the Go and the Web team, summarized in #205, Web does not store key-value pairs to be omitted. Prior, an already JSON-encoded version of the ConfigOption slice was present in plugin.Info. Thus, this data wasn't easily available anymore. As the new code now needs to access this field, it was changed and a custom sql driver.Valuer was implemented for a slice type. While working on this, all ConfigOptions were put in the same order as the struct fields. Requires <Icinga/icinga-notifications-web#230>. Closes #205.

With a release approaching, the Channels documentation got more information about how the Channel system actually work and how to build your own channels. The internal/changes/examples JSON files were inlined to ease the readability and updated, as they contained partially outdated information. For the pkg/plugin part, some API documentation was added as this might get used by external users.

… 1.23)

With #64 and #127 being merged, most of the internal/utils package is moved to the IGL and can be removed here. This is another step to unify our Go codebase.

cla-bot bot added the cla/signed CLA is signed by all contributors of a PR label Aug 6, 2025

yhabteab force-pushed the notifications branch 2 times, most recently from 609ec3f to 82eff34 Compare August 6, 2025 16:06

yhabteab force-pushed the notifications branch 2 times, most recently from e4215c5 to 55c038b Compare August 7, 2025 15:16

oxzi added this to the 0.8.0 milestone Aug 28, 2025

yhabteab force-pushed the notifications branch from 55c038b to 641e970 Compare September 2, 2025 14:53

julianbrost reviewed Sep 3, 2025

View reviewed changes

yhabteab force-pushed the notifications branch from 641e970 to 5032573 Compare September 4, 2025 13:06

yhabteab requested a review from julianbrost September 4, 2025 13:24

oxzi reviewed Sep 5, 2025

View reviewed changes

notifications/source/client.go Outdated Show resolved Hide resolved

yhabteab force-pushed the notifications branch 2 times, most recently from 64209e7 to f54aa70 Compare September 5, 2025 11:08

oxzi added a commit to Icinga/icinga-notifications that referenced this pull request Sep 5, 2025

Update IGL for Notifications Changes

408690d

Synchronize codebase against latest version of Icinga/icinga-go-library#145, containing package changes.

oxzi self-assigned this Sep 9, 2025

oxzi force-pushed the notifications branch from f54aa70 to 41693c5 Compare September 9, 2025 09:50

oxzi force-pushed the notifications branch from 41693c5 to 20db236 Compare September 9, 2025 10:01

oxzi added a commit to Icinga/icinga-notifications that referenced this pull request Sep 9, 2025

Update IGL for Notifications Changes

8a80ed9

Synchronize codebase against latest version of Icinga/icinga-go-library#145, containing package changes.

oxzi removed their assignment Sep 9, 2025

oxzi mentioned this pull request Sep 9, 2025

Move Rule evaluation to Source Icinga/icinga-notifications#324

Draft

yhabteab self-assigned this Sep 10, 2025

oxzi requested a review from julianbrost October 2, 2025 08:04

oxzi marked this pull request as draft October 9, 2025 08:09

sukhwinder33445 and others added 26 commits October 9, 2025 11:53

Enhance channel

bf3005c

pkg/plugin/plugin.go: Introduce Object struct All object related va…

59d7294

…lues (name, url, etc) are moved into this struct and used accordingly

Handle unexpected termination of plugin

089a47b

Enhance channel plugins

31bcf6c

- Introduce a plugin table to store plugin related info. On daemon start the plugin table is upserted. - Each plugin defines its own required form elements for config as configOption(s). - Configured channels start and maintain there plugin.

Improve logs

bcf9f2e

pkg/rpc/rpc.go: Remove unused variable from RPC struct

4d7ed03

pkg/plugin/plugin.go: Plugin shutdown should wait for pending resposes

f1aa8d7

pkg/rpc/rpc.go: rpc.Close() should not cause rpc.Done()

73c8515

pkg/rpc/rpc.go: SetErr() calls rpc.Close()

06e242e

pkg/rpc/rpc.go: Remove method SetErr as it is only used once

78635f9

pkg/rpc/rpc.go: Rename err variables

4ff169b

pkg/rpc/rpc.go: Add helper function to avoid multiple unlock calls

43eda27

channels: Use incident.severity instead of event.severity

143c22a

Plugin#ConfigOptions: Remove placeholder and use default instead

a38fb77

plugin: Document ConfigOption's Help field

f4cb761

Format notification subject and message depending on event type

c50bf27

Switch to icinga-go-library

1281dc0

Use utils.IterateOrderedMap() as intended, via for:=range (require Go…

8cb0753

… 1.23)

internal/utils: Cleanup and IGL unification

599879f

With #64 and #127 being merged, most of the internal/utils package is moved to the IGL and can be removed here. This is another step to unify our Go codebase.

Drop object_extra_tags & all its references

e1d39d3

Use the newly introduced notifications event utils from igl

2097b04

notifications: Fix import after IGL import

6d45c75

oxzi marked this pull request as ready for review October 9, 2025 12:01

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add a common notifications client & its utilities #145

Add a common notifications client & its utilities #145

Uh oh!

yhabteab commented Aug 6, 2025 •

edited by oxzi

Loading

Uh oh!

julianbrost commented Aug 6, 2025

Uh oh!

lippserd commented Aug 19, 2025

Uh oh!

oxzi commented Sep 2, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yhabteab commented Sep 5, 2025

Uh oh!

oxzi commented Sep 9, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Add a common notifications client & its utilities #145

Are you sure you want to change the base?

Add a common notifications client & its utilities #145

Uh oh!

Conversation

yhabteab commented Aug 6, 2025 • edited by oxzi Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

julianbrost commented Aug 6, 2025

Uh oh!

lippserd commented Aug 19, 2025

Uh oh!

oxzi commented Sep 2, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yhabteab commented Sep 5, 2025

Uh oh!

oxzi commented Sep 9, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

yhabteab commented Aug 6, 2025 •

edited by oxzi

Loading