trigger

Documentation

Overview

Package trigger adds a ppacher/system-conf based trigger system that listens for events from cis/runtime/events. It provides basic debouncing and buffering of events per trigger definition. The package itself does not contain actual event handlers but supports a simple registry-style pattern to register your own trigger types.

[Match]
EventFilter=event/topic/#
DebounceUntil=12:00
DebounceUntil=17:00

[MyHandler]
SomeConfig=some value

The trigger package also registers an autodoc.File for the DefaultRegistry so documentation for available trigger types is built into the final binary.

Index

• Variables
• type ActionType
• type Definition
• type Handler
• type HandlerFunc
  • func (fn HandlerFunc) HandleEvents(ctx context.Context, event ...*event.Event) error
• type Instance
  • func NewInstance(baseCtx context.Context, instanceName string, handlers []Handler, ...) (context.Context, *Instance)
  • func (inst *Instance) Description() string
  • func (inst *Instance) Flush() bool
  • func (inst *Instance) Groups() []string
  • func (inst *Instance) Handle(ctx context.Context, evt *event.Event) error
  • func (inst *Instance) ID() string
  • func (inst *Instance) Pending() bool
  • func (inst *Instance) Wants(eventTopic string) bool
• type InstanceConfig
• type MatchConfig
• type Registry
  • func NewRegistry(baseCtx context.Context, eventReg *event.Registry, location *time.Location, ...) *Registry
  • func (reg *Registry) ActionTypes() []ActionType
  • func (reg *Registry) DeleteTrigger(ctx context.Context, defID string) error
  • func (reg *Registry) EventRegistry() *event.Registry
  • func (reg *Registry) GetTrigger(ctx context.Context, triggerID string) (Definition, error)
  • func (reg *Registry) GetType(name string) (ActionType, error)
  • func (reg *Registry) Instances() []*Instance
  • func (reg *Registry) ListTriggers(ctx context.Context) ([]Definition, error)
  • func (reg *Registry) LoadAndCreate(ctx context.Context) error
  • func (reg *Registry) OptionsForSection(sec string) (conf.OptionRegistry, bool)
  • func (reg *Registry) PutTrigger(ctx context.Context, def Definition) (string, error)
  • func (reg *Registry) RegisterType(factory ActionType) error

Variables

var (
	AddToSchema = configBuilder.AddToSchema
)

var MatchSpec = conf.SectionSpec{
	{
		Name:        "Name",
		Type:        conf.StringType,
		Required:    true,
		Description: "The name of the trigger instance.",
	},
	{
		Name:        "Description",
		Type:        conf.StringType,
		Description: "A human readable description of the trigger.",
	},
	{
		Name:        "EventFilter",
		Type:        conf.StringSliceType,
		Aliases:     []string{"Event"},
		Description: "A event subscription topic",
		Default:     "#",
		Annotations: new(conf.Annotation).With(
			runtime.OneOfRef("events", "ID", "Description", true),
		),
	},
	{
		Name:        "BufferUntil",
		Type:        conf.StringSliceType,
		Description: "Buffer events and emit then at defined times. Accepts HH:MM values.",
	},
	{
		Name:        "DebounceUntil",
		Type:        conf.StringSliceType,
		Description: "Like BufferUntil but only remembers the last event emitted.",
	},
	{
		Name:        "Group",
		Type:        conf.StringSliceType,
		Description: "A list of groups this trigger belongs to.",
		Annotations: new(conf.Annotation).With(
			runtime.OneOfRef("trigger", "Group", "Group", true),
		),
	},
	{
		Name:        "Condition",
		Type:        conf.StringType,
		Description: "A condition using maja42/goval that must evaluate to true for the trigger to fire",
		Default:     "",
	},
}

MatchSpec defines all configuration stanzas that can be used to configure event matching for trigger instances. MatchSpec is only used with file based trigger configuration. See Registry for more information on file based trigger configuration.

Types

type ActionType

type ActionType struct {
	runtime.Schema

	// CreateFunc is called when a new instance of the trigger handler should be created.
	CreateFunc func(ctx context.Context, globalSchema *runtime.ConfigSchema, sec *conf.Section) (Handler, error) `json:"-"`
}

type Definition

type Definition struct {
	ID      string
	Match   []conf.Option
	Actions []runtime.Section
}

type Handler

type Handler interface {
	// HandleEvents is called for each set of events fired. There might
	// be multiple events if the users configures BufferUntil.
	HandleEvents(ctx context.Context, event ...*event.Event) error
}

Handler is the interface that can be attached to trigger instances and can handle and react to different kinds of events. For configuration based triggers it's possible to register Handler factories and their supported configuration stanzas at the trigger registry. See Registry for more information on file based trigger configuration.

type HandlerFunc

type HandlerFunc func(ctx context.Context, event ...*event.Event) error

HandlerFunc is a convenience type for implementing Handler.

func (HandlerFunc) HandleEvents

func (fn HandlerFunc) HandleEvents(ctx context.Context, event ...*event.Event) error

HandleEvents calls through to fn.

type Instance

type Instance struct {
	// contains filtered or unexported fields
}

Instance is a dedicated trigger instance that handles a set of events and executes specified handlers for each of them. Instances may directly forward events to their handlers or buffer/debounce them until certain conditions apply. See InstanceConfig for more information on deboucing and buffering.

func NewInstance

func NewInstance(baseCtx context.Context, instanceName string, handlers []Handler, instanceCfg *InstanceConfig) (context.Context, *Instance)

NewInstance creates a new trigger instance for the set of handlers. Note that the instance does not listen for events by itself. The caller will want to make sure to call Handle(*event.Event) at appropriate places or create a event subscription.

func (*Instance) Description

func (inst *Instance) Description() string

Description returns the description of the trigger instance or an empty string.

func (*Instance) Flush

func (inst *Instance) Flush() bool

Flush forces execution of all instance handlers. It returns true if execution was trigger and false if not. Note that even if execution has been triggered it's not guaranteed that events have been pending as Flush only triggers the goroutine to check if work needs to be done. The instance must have DebounceUntil or BufferUntil configured to be flushable. Otherwise Flush will always return false.

func (*Instance) Groups

func (inst *Instance) Groups() []string

Groups returns list of trigger group names this instance belongs to.

func (*Instance) Handle

func (inst *Instance) Handle(ctx context.Context, evt *event.Event) error

Handle should be called whenever the trigger instance should handle an event. Depending on the instance configuration the event might be directly passed to the set of event handlers or might be debounced or buffered until certain points in time. Refer to the documentation of Instance and InstanceConfig for more information on buffering and debouncing of events. Note that handle does not check if the provided event matches on of the EventFilters specified for this instance. The caller should use Wants() before or otherwise make sure this instance can handle the provided event.

func (*Instance) ID

func (inst *Instance) ID() string

ID returns the name of the instance.

func (*Instance) Pending

func (inst *Instance) Pending() bool

Pending returns true if events are pending to be handled by the instance. Pending can only return true if the instance has either DebounceUntil or BufferUntil configured.

func (*Instance) Wants

func (inst *Instance) Wants(eventTopic string) bool

Wants checks if one of the instance event filters matches eventTopic.

type InstanceConfig

type InstanceConfig struct {
	// Name is the name of the instance as set by the user.
	Name string

	// EventFilters holds a topic subscription that's evaluated using
	// event.MatchSubscription. It's only used when calling Wants() on the
	// final instance returned by NewInstance. This field is not required
	// and only for convenience purpopses when manually triggering instances
	// using Handle().
	EventFilters []string
	// DebounceUntil can be set to different day-times (minute resolution)
	// until which the handling of events is debounced. A trigger instance
	// that is currently debouncing events and waiting for the next "until"
	// time returns true from Pending(). Trigger instances with DebounceUntil=
	// will never fire more than one event at the specified day times and never
	// fire in between.
	//
	// Note that DebounceUntil and BufferUntil are mutually exclusive.
	// Configuring both will cause NewInstance to return an error.
	DebounceUntil []daytime.DayTime
	// BufferUntil works similar to DebounceUntil but instead of dropping older
	// events and just keeping the latest one BufferUntil keeps track of all
	// events that occurred between the configured day times. Once a day time is
	// reached with minute resolution, the complete buffer of events is handed to
	// each handler of the instance.
	//
	// Note that DebounceUntil and BufferUntnil are mutually exclusive.
	// Configuring both will cause NewInstance to return an error.
	BufferUntil []daytime.DayTime
	// Location may defined the timezone the instance should operate in. The
	// timezone is mainly required if DebounceUntil or BufferUntil is configured.
	Location *time.Location
	// Description holds an optional, human-readable description
	Description string
	// Group is a list of group names the trigger instance belongs to.
	// Groups have no special meaning in this package but may be used
	// by package users for different purposes. I.e. in CIS the trigger
	// group is used to allow execution of multiple trigger instances via
	// the API.
	Groups []string
	// Condition holds a maja42/goval condtion that must evaluate to true for
	// the trigger to fire.
	Condition string
}

InstanceConfig holds additional configuration values for trigger instances.

type MatchConfig

type MatchConfig struct {
	// Name is the name of the trigger instance as set by the user.
	Name string
	// EventFitler may hold multiple event topic subscriptions.
	// The trigger instance created from this MatchConfig handles
	// each event that matches one of the specified filters.
	EventFilter []string
	// BufferUntil configures the day-times until which events should
	// be buffered and emitted at once. Refer to the documentation of
	// InstanceConfig for more information on event buffering.
	//
	// Note that BufferUntil and DebounceUntil are mutally exclusive.
	BufferUntil []string
	// Debounce configures the day-times until which events should
	// be debounced and only the last one should be emitted.
	// Refer to the documentation of InstanceConfig for more information
	// on event debouncing.
	//
	// Note that BufferUntil and DebounceUntil are mutally exclusive.
	DebounceUntil []string
	// Description holds an optional, human-readable description
	Description string
	// Group is a list of group names the trigger instance belongs to
	Group []string
	// Condition is a maja42/goval condition that must evaluate to true.
	Condition string
}

MatchConfig holds meta configuration for trigger instances when file-based trigger configuration is being used. MatchConfig defines the configuration that can be specified in the [Match] section of .trigger files. Refer to MatchSpec and Registry for more information about file-based trigger configuration.

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry manages trigger type factories and supports file based trigger configuration using ppacher/system-conf. It loads trigger configuration units (<name>.trigger) from the filesystem and creates a trigger instance for each file loaded. The trigger file must have a [Match] section that follows MatchSpec and one or more handler sections where the section is named after the handler type (passed to RegisterType). For example, the following .trigger file creates a new instance that will execute two different handles when a matching event is fired:

[Match]
EventFilter=events/notifications/#

[SendMail]
To=that@guy.mail
From=noc@example.com
Subject=A new notification arrived

[Exec]
StreamEventToStdin=json
Exec=/usr/local/bin/handle-event.sh $1

Registry also implements conf.SectionRegistry and may be directly used to validate .trigger files.

func NewRegistry

func NewRegistry(baseCtx context.Context, eventReg *event.Registry, location *time.Location, cs *runtime.ConfigSchema) *Registry

NewRegistry creates a new trigger registry that places and event subscriptions and eventReg. The optional timezone (location) is used for event deboucing and buffering. If location is nil it defaults to time.Local. Refer to InstanceConfig or MatchConfig for more information on debouncing and buffering of events.

func (*Registry) ActionTypes

func (reg *Registry) ActionTypes() []ActionType

ActionTypes returns all available action types.

func (*Registry) DeleteTrigger

func (reg *Registry) DeleteTrigger(ctx context.Context, defID string) error

func (*Registry) EventRegistry

func (reg *Registry) EventRegistry() *event.Registry

EventRegistry returns the event registry this trigger registry is bounded to.

func (*Registry) GetTrigger

func (reg *Registry) GetTrigger(ctx context.Context, triggerID string) (Definition, error)

func (*Registry) GetType

func (reg *Registry) GetType(name string) (ActionType, error)

func (*Registry) Instances

func (reg *Registry) Instances() []*Instance

func (*Registry) ListTriggers

func (reg *Registry) ListTriggers(ctx context.Context) ([]Definition, error)

func (*Registry) LoadAndCreate

func (reg *Registry) LoadAndCreate(ctx context.Context) error

func (*Registry) OptionsForSection

func (reg *Registry) OptionsForSection(sec string) (conf.OptionRegistry, bool)

OptionsForSection returns the option registry for the trigger file section sec. It implements the conf.SectionRegistry interface. Note that the MatchSpec is automatically added for [Match] sections.

func (*Registry) PutTrigger

func (reg *Registry) PutTrigger(ctx context.Context, def Definition) (string, error)

func (*Registry) RegisterType

func (reg *Registry) RegisterType(factory ActionType) error

RegisterType registers a new trigger factory and the respective configuration schema. The schema is registered at the runtime.ConfigSchema that has been used when creating the trigger registry.

It automatically overwrites a few properties of the schema registration like marking the schema as "multi" and "Internal".