Documentation
¶
Overview ¶
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 Run starts a blocking JSON-RPC server that handles incoming requests from the Icinga Notifications process. The plugin can also implement the RPCEndpointReceiver interface to receive the internally used RPC endpoint, allowing the plugin to make RPC calls back to the Icinga Notifications process.
Examples can be found under cmd/channels in the Icinga Notifications repository.
Index ¶
- Constants
- func PopulateDefaults(typePtr Plugin) error
- func Run(p Plugin)
- type Address
- type ChildOption
- type ConfigOption
- type ConfigOptionCommon
- type ConfigOptions
- type Contact
- type DeliveryDetail
- type DeliveryResult
- type Event
- type Incident
- type Info
- type NotificationRequest
- type Object
- type PayloadV1
- type Plugin
- type RPCEndpointReceiver
- type RequestVersion
- type State
Constants ¶
const ( MethodGetInfo = "GetInfo" MethodSetConfig = "SetConfig" MethodSendNotification = "SendNotification" )
const MaxDeliveryResultSize = 1024 * 1024
MaxDeliveryResultSize is the maximum size in bytes of the serialized delivery result details a plugin can return.
Any delivery result details exceeding this limit will be dropped completely by Icinga Notifications without storing them in the database. So, plugins should ensure to only return details that are relevant and concise, avoiding unnecessary verbosity.
Variables ¶
This section is empty.
Functions ¶
func PopulateDefaults ¶
PopulateDefaults sets the struct fields from Info.ConfigAttributes where ConfigOption.Default is set.
It should be called from each channel plugin within its Plugin.SetConfig before doing any further configuration.
func Run ¶ added in v0.10.0
func Run(p Plugin)
Run starts the RPC server for a channel plugin.
The RPC server reads requests from stdin, calls the associated RPC method, and writes the responses to stdout. It blocks until either the process receives a termination signal (SIGINT or SIGTERM) or the RPC connection is closed. If the plugin implements the RPCEndpointReceiver interface, the internally used RPC endpoint will be injected into the plugin, allowing the plugin to make RPC calls back to the Icinga Notifications process.
Note that this function might also terminate the process unexpectedly if the rpcHandler fails to send a response back to Icinga Notifications. This is done to ensure that the plugin does not continue running in an inconsistent state after a failed RPC response.
This function should be called last in a channel plugin's main function.
Types ¶
type Address ¶
type Address struct {
// Type field matches the Info.Type, effectively being the channel plugin file name.
Type string `json:"type"`
// Address is the associated Type-specific address, e.g., an email address for type email.
Address string `json:"address"`
}
Address to receive this notification. Each Contact might have multiple addresses.
type ChildOption ¶ added in v0.10.0
type ChildOption struct {
ConfigOptionCommon
// ParentValues is a list of parent element values that will trigger the display of this child option.
//
// If the parent element is a select element, this list should contain the keys of the parent option that
// should trigger this child option to be displayed. If the parent element is a checkbox, this list should
// contain the boolean value (true or false). All other parent element types are not supported for child options
// and will be rejected by Icinga Notifications Web.
//
// If empty, the child option will always be displayed regardless of the parent option's value. This is useful for
// child options that should always be displayed, but are still logically grouped under a parent element.
ParentValues []any `json:"parent_values"`
}
ChildOption describes a config element that is conditionally displayed based on the value of a parent option.
This allows to create a more dynamic and user-friendly configuration interface, where certain options are only shown when relevant based on the user's previous selections. Even though the API allows for nested children, the UI will only render one level of children or even reject them entirely. Therefore, it is prohibited to define a child option with its own children.
type ConfigOption ¶
type ConfigOption struct {
ConfigOptionCommon
// Children contains a set of [ChildOption] rendered in the UI only when a specific parent option value is selected.
//
// This allows for conditional configuration options based on the user's selection in the parent option.
// For example, if a parent option is a select element with multiple choices, each choice can have its own
// set of child options that are displayed only when that choice is selected. A concrete example would be a
// parent option for selecting HTTP request method (GET, POST, PUT, DELETE), and each method could have its
// own set of child options for configuring headers, body content, etc.
//
// A child option must not have its own children, as this would create a recursive structure that is not supported.
Children []ChildOption `json:"children,omitempty"`
}
ConfigOption describes a config element.
type ConfigOptionCommon ¶ added in v0.10.0
type ConfigOptionCommon struct {
// Element name
Name string `json:"name"`
// Element type:
//
// string = text, number = number, bool = checkbox, text = textarea, option = select, options = select[multiple], secret = password
Type string `json:"type"`
// Element label map. Locale in the standard format (language_REGION) as key and corresponding label as value.
// Locale is assumed to be UTF-8 encoded (Without the suffix in the locale)
//
// e.g. {"en_US": "Save", "de_DE": "Speichern"}
// An "en_US" locale must be given as a fallback
Label map[string]string `json:"label"`
// Element description map. Locale in the standard format (language_REGION) as key and corresponding label as value.
// Locale is assumed to be UTF-8 encoded (Without the suffix in the locale)
//
// When the user moves the mouse pointer over an element in the web UI, a tooltip is displayed with a given message.
//
// e.g. {"en_US": "HTTP request method for the request.", "de_DE": "HTTP-Methode für die Anfrage."}
// An "en_US" locale must be given as a fallback
Help map[string]string `json:"help,omitempty"`
// Element default: bool for checkbox default value, string for other elements (used as placeholder)
Default any `json:"default,omitempty"`
// Set true if this element is required, omit otherwise
Required bool `json:"required,omitempty"`
// Options of a select element: key => value.
// Only required for the type option or options
//
// e.g., map[string]string{
// "1": "January",
// "2": "February",
// }
Options map[string]string `json:"options,omitempty"`
// Element's min option defines the minimum allowed number value. It can only be used for the type number.
Min types.Int `json:"min"`
// Element's max option defines the maximum allowed number value. It can only be used for the type number.
Max types.Int `json:"max"`
}
ConfigOptionCommon describes common fields.
type ConfigOptions ¶
type ConfigOptions []ConfigOption
ConfigOptions describes all ConfigOption entries.
This type became necessary to implement the database.sql.driver.Valuer to marshal it into JSON.
type Contact ¶
type Contact struct {
// FullName of a Contact as defined in Icinga Notifications.
FullName string `json:"full_name"`
// Addresses of a Contact with a type.
Addresses []*Address `json:"addresses"`
}
Contact to receive notifications for the NotificationRequest.Payload.
type DeliveryDetail ¶ added in v0.10.0
type DeliveryDetail struct {
// Type of this detail.
//
// Supported types are "number", "boolean", "severity", "text", "url", and "datetime". The type determines how
// the value is interpreted and displayed in the UI. For example, a "url" type will be rendered as a clickable
// link, while a "datetime" type will be formatted according to the user's locale.
//
// This is required and must be one of the supported types.
Type string `json:"type"`
// Label is a human-readable description of this detail, e.g., "Ticket ID" or "Delivery Time".
//
// This is required and should be concise yet descriptive enough to convey the meaning of the value.
Label string `json:"label"`
// Value is the actual content of this detail and must be of the type specified in [DeliveryDetail.Type].
//
// For example, if the type is "url", the value should be an absolute URL. If the type is "datetime", the
// value should be an ISO 8601 formatted date-time string. The interpretation of the value is entirely
// dependent on the specified type.
Value any `json:"value"`
// AnchorText is an optional human-readable text that will be displayed as the clickable link for URL types.
//
// If omitted, the URL itself will be displayed as the link text. This field is only relevant when
// [DeliveryDetail.Type] is set to "url". For other types, this field will be ignored.
AnchorText string `json:"anchor_text,omitempty"`
}
DeliveryDetail is a single piece of information about a delivery, shown in Icinga Notifications Web's history view.
func (*DeliveryDetail) MarshalJSON ¶ added in v0.10.0
func (d *DeliveryDetail) MarshalJSON() ([]byte, error)
MarshalJSON implements the json.Marshaler interface to marshal the DeliveryDetail as a JSON object.
type DeliveryResult ¶ added in v0.10.0
type DeliveryResult struct {
// If State has a valid Key, it replaces the stored state of the [NotificationRequest.Payload].
//
// Its Key must match [NotificationRequest.State.Key]. A zero State leaves the stored state unchanged.
State State `json:"state,omitzero"`
// Details are shown in the notification history of Icinga Notifications Web in the given order,
// e.g., a link to the ticket created in an external system.
//
// The total size of the serialized details must not exceed [MaxDeliveryResultSize].
Details []DeliveryDetail `json:"details,omitempty"`
}
DeliveryResult is the outcome of Plugin.SendNotification reported back to Icinga Notifications.
type Event ¶
type Event struct {
// Type of this Event; optional.
Type string `json:"type,omitzero"`
// Time when this event occurred, being encoded according to RFC 3339 when passed as JSON.
Time time.Time `json:"time"`
// Summary is a short, one-line description of this Event.
Summary string `json:"summary"`
// Message of this event, might be a check output when the related Object is an Icinga 2 object.
Message string `json:"message"`
}
Event indicating this NotificationRequest.Payload.
type Incident ¶
type Incident struct {
// Severity of this Incident.
Severity event.Severity `json:"severity"`
// IsMuted indicates whether this Incident is being muted with the ongoing event.
IsMuted bool `json:"muted"`
// IsRecovered indicates whether this Incident is going to be resolved/recovered with the ongoing event.
IsRecovered bool `json:"recovered"`
// Message is the latest human-readable message of the Event that affected this Incident.
Message string `json:"message"`
// Summary is the latest one-line Event.Summary that affected this Incident.
Summary string `json:"summary"`
// StartedAt is when this Incident was opened.
StartedAt time.Time `json:"started_at"`
// RecoveredAt is when this Incident was closed/resolved. Zero value if still open.
RecoveredAt time.Time `json:"recovered_at,omitzero"`
// MutedReason contains the reason this Incident is currently muted. Empty if not muted.
MutedReason string `json:"muted_reason,omitempty"`
// Managed indicates whether this Incident currently has an assigned manager.
Managed bool `json:"managed"`
// ManagedBy is the display name of the Incident's manager. Empty if Managed is false.
ManagedBy string `json:"managed_by,omitempty"`
// OpenedBySource is the name of the Source whose Event opened this Incident.
OpenedBySource string `json:"opened_by_source"`
}
Incident of this NotificationRequest.Payload, grouping Events for this Object.
type Info ¶
type Info struct {
// Type of the channel plugin.
//
// Not part of the JSON object. Will be set to the channel plugin file name before database insertion.
Type string `db:"type" json:"-"`
// Name of this channel plugin in a human-readable value.
Name string `db:"name" json:"name"`
// Version of this channel plugin.
Version string `db:"version" json:"version"`
// Author of this channel plugin.
Author string `db:"author" json:"author"`
// SupportedRequestVersions lists the [NotificationRequest] versions this channel plugin can handle.
//
// Plugins must always advertise all versions they support, even if they only support the latest version.
SupportedRequestVersions []RequestVersion `db:"-" json:"supported_request_versions"`
// ConfigAttributes contains multiple ConfigOption(s) as JSON-encoded list.
ConfigAttributes ConfigOptions `db:"config_attrs" json:"config_attrs"`
}
Info contains channel plugin information.
type NotificationRequest ¶
type NotificationRequest struct {
// Version of the Payload structure, set by Icinga Notifications.
//
// Valid versions start at RequestVersionV1, and all plugins are expected to support at least this version.
// The zero value is never set, and plugins should reject any request with an unsupported version.
Version RequestVersion `json:"version"`
// Payload contains the notification data in the structure defined by Version.
//
// Plugins should unmarshal this field into a compatible struct based on the Version field.
// For example, if Version is [RequestVersionV1], the Payload can be unmarshaled into [PayloadV1].
Payload json.RawMessage `json:"payload"`
}
NotificationRequest is sent to a channel plugin via Plugin.SendNotification to request a notification delivery.
func (*NotificationRequest) PayloadAs ¶ added in v0.10.0
func (nr *NotificationRequest) PayloadAs[T any]() (*T, error)
PayloadAs is a generic accessor for the Payload field of a NotificationRequest.
It unmarshals the Payload into the specified type T, which must correspond to the Version of the NotificationRequest. If the Version does not match the expected type, or if unmarshaling fails, an error is returned.
type Object ¶
type Object struct {
// Name depending on its source, may be "host!service" when from Icinga 2.
Name string `json:"name"`
// Url pointing to this Object, may be to Icinga Web.
Url string `json:"url"`
// Sources lists the names of every Source this Object has ever been observed from.
Sources []string `json:"sources"`
// Tags defining this Object, may be "host" and "service" when from Icinga 2.
Tags map[string]string `json:"tags"`
}
Object which this NotificationRequest.Payload is all about, e.g., an Icinga 2 Host or Service object.
type PayloadV1 ¶ added in v0.10.0
type PayloadV1 struct {
// Contact to receive this NotificationRequest.
Contact *Contact `json:"contact"`
// Object associated with this NotificationRequest, e.g., an Icinga 2 Service Object.
Object *Object `json:"object"`
// Incident associated with this NotificationRequest.
//
// May be nil when sending non-state notifications and no active incident exists for the given Object.
Incident *Incident `json:"incident"`
// Event being responsible for creating this NotificationRequest, e.g., a firing Icinga 2 Service Check.
Event *Event `json:"event"`
// Summary is Icinga Notifications' own pre-formatted, single-line summary of this notification.
Summary string `json:"summary"`
// Body is Icinga Notifications' own pre-formatted, multi-line notification text.
Body string `json:"body"`
// State is the plugin's state for this request's contact and incident.
//
// If no state has been stored yet, [State.Key] is filled in and [State.Value] is empty.
// The only way to change the state is to return it in [DeliveryResult.State].
//
// Icinga Notifications deletes the state itself once the incident is resolved or the channel is deleted.
State State `json:"state,omitzero"`
}
PayloadV1 represents the structure of the notification request data for version 1 of the Payload.
type Plugin ¶
type Plugin interface {
// GetInfo returns the corresponding plugin *Info.
GetInfo() *Info
// SetConfig sets the plugin config, returns an error on failure.
SetConfig(jsonStr json.RawMessage) error
// SendNotification sends the notification described by req, returning an error on failure.
//
// Before calling this method, the rpcHandler has already checked that req.Version is one of the versions the
// library supports and rejected the request otherwise. Implementations should still use the typed accessor
// for the version they handle (e.g., NotificationRequest.PayloadAs[PayloadV1]()) instead of decoding the
// payload directly.
//
// Returning a non-nil error means the delivery failed. When the plugin is started via [Run], the error is
// sent back as a JSON-RPC error response and any [DeliveryResult] returned with it is dropped. On success,
// the returned [DeliveryResult] may be nil if there is no state update and no details to report.
SendNotification(req *NotificationRequest) (*DeliveryResult, error)
}
Plugin defines necessary methods for a channel plugin.
Those methods are being called by the Icinga Notifications process via JSON-RPC. The plugin must implement this interface to be able to receive and handle those requests. The plugin can be launched via the Run function, which will start a JSON-RPC server and block until the plugin is terminated.
type RPCEndpointReceiver ¶ added in v0.10.0
RPCEndpointReceiver is an interface that can be implemented by a plugin to receive the RPC endpoint used internally.
If a channel plugin implements this interface, the Run function will inject the RPC endpoint into the plugin before starting the server. This allows the plugin to make RPC calls back to the Icinga Notifications process.
type RequestVersion ¶ added in v0.10.0
type RequestVersion uint16
RequestVersion is the version of the NotificationRequest payload structure.
const (
RequestVersionV1 RequestVersion = 1
)
type State ¶ added in v0.10.0
type State struct {
// Key identifies this state entry.
//
// It is a UUID generated by Icinga Notifications and must not be changed by the plugin.
Key types.UUID `db:"state_key" json:"state_key"`
// Value is any string of up to 4096 characters that the plugin needs in later notifications,
// e.g., the ID of a ticket created in an external system.
Value string `db:"value" json:"value"`
}
State is a plugin-defined value that Icinga Notifications stores per contact and incident.