diff --git a/README.md b/README.md new file mode 100644 index 0000000..337fbff --- /dev/null +++ b/README.md @@ -0,0 +1,14 @@ +# Icinga Go Library + +The Icinga Go Library is a collection of Go packages used for common tasks in Icinga's Go applications. + +While some of these packages are only useful internally, others might be useful for extending Icinga applications. +For example, the `notifications` package is designed for interoperability with [Icinga Notifications](https://github.com/Icinga/icinga-notifications). + +## Documentation + +The Go package documentation is available online at [pkg.go.dev/github.com/icinga/icinga-go-library](https://pkg.go.dev/github.com/icinga/icinga-go-library). + +## License + +Icinga Go Library and its documentation are licensed under the terms of the [MIT License](LICENSE). diff --git a/notifications/event/event.go b/notifications/event/event.go index bd3f20e..2ac57ae 100644 --- a/notifications/event/event.go +++ b/notifications/event/event.go @@ -1,3 +1,4 @@ +// Package event describes the central Icinga Notifications Event type. package event import ( diff --git a/notifications/notifications.go b/notifications/notifications.go new file mode 100644 index 0000000..2e88241 --- /dev/null +++ b/notifications/notifications.go @@ -0,0 +1,14 @@ +// Package notifications contains subpackages related to Icinga Notifications. +// +// The event package describes the central Event type used to describe Icinga Notifications events. +// +// When implementing a new Icinga Notifications [Channel Plugins] to allow notifications be sent over a new way, take a +// look at the plugin package. Internally, this uses the rpc package, which, however, should not be relevant for +// mere channel plugin implementations. +// +// When implementing a new Icinga Notifications Source to submit events to Icinga Notifications' [HTTP API], consider +// the source package. +// +// [Channel Plugins]: https://icinga.com/docs/icinga-notifications/latest/doc/10-Channels/ +// [HTTP API]: https://icinga.com/docs/icinga-notifications/latest/doc/20-HTTP-API/ +package notifications diff --git a/notifications/plugin/plugin.go b/notifications/plugin/plugin.go index a31a312..84c84e0 100644 --- a/notifications/plugin/plugin.go +++ b/notifications/plugin/plugin.go @@ -1,3 +1,11 @@ +// Package plugin implements a high-level Icinga Notifications Channel Plugin API. +// +// For own plugins, the [Plugin] interface must be implemented. After configuring your plugin, calling RunPlugin starts +// a blocking RPC client, utilizing the underlying [rpc] package. +// +// Examples can be found under [cmd/channels] in the Icinga Notifications repository. +// +// [cmd/channels]: https://github.com/Icinga/icinga-notifications/tree/main/cmd/channels package plugin import ( diff --git a/notifications/rpc/rpc.go b/notifications/rpc/rpc.go index 5503063..32d3b40 100644 --- a/notifications/rpc/rpc.go +++ b/notifications/rpc/rpc.go @@ -1,3 +1,7 @@ +// Package rpc implements the low-level JSON RPC connection between a channel plugin and Icinga Notifications. +// +// This package is used by the plugin package and internally in Icinga Notifications. When aiming to implement a new +// channel plugin, please consider using the plugin package. package rpc import ( diff --git a/notifications/source/source.go b/notifications/source/source.go new file mode 100644 index 0000000..97bd845 --- /dev/null +++ b/notifications/source/source.go @@ -0,0 +1,4 @@ +// Package source implements an Icinga Notifications source to send events to the Icinga Notifications API. +// +// Start by creating a new Client, which can then submit events to this API. +package source