caddyevents

Documentation

Index

• Variables
• type App
  • func (App) CaddyModule() caddy.ModuleInfo
  • func (app *App) Emit(ctx caddy.Context, eventName string, data map[string]any) Event
  • func (app *App) On(eventName string, handler Handler) error
  • func (app *App) Provision(ctx caddy.Context) error
  • func (app *App) Start() error
  • func (app *App) Stop() error
  • func (app *App) Subscribe(s *Subscription) error
• type CloudEvent
• type Event
  • func (e Event) CloudEvent() CloudEvent
• type Handler
• type Subscription

Variables

var ErrAborted = errors.New("event aborted")

ErrAborted cancels an event.

Types

type App

type App struct {
	// Subscriptions bind handlers to one or more events
	// either globally or scoped to specific modules or module
	// namespaces.
	Subscriptions []*Subscription `json:"subscriptions,omitempty"`
	// contains filtered or unexported fields
}

App implements a global eventing system within Caddy. Modules can emit and subscribe to events, providing hooks into deep parts of the code base that aren't otherwise accessible. Events provide information about what and when things are happening, and this facility allows handlers to take action when events occur, add information to the event's metadata, and even control program flow in some cases.

Events are propagated in a DOM-like fashion. An event emitted from module `a.b.c` (the "origin") will first invoke handlers listening to `a.b.c`, then `a.b`, then `a`, then those listening regardless of origin. If a handler returns the special error Aborted, then propagation immediately stops and the event is marked as aborted. Emitters may optionally choose to adjust program flow based on an abort.

Modules can subscribe to events by origin and/or name. A handler is invoked only if it is subscribed to the event by name and origin. Subscriptions should be registered during the provisioning phase, before apps are started.

Event handlers are fired synchronously as part of the regular flow of the program. This allows event handlers to control the flow of the program if the origin permits it and also allows handlers to convey new information back into the origin module before it continues. In essence, event handlers are similar to HTTP middleware handlers.

Event bindings/subscribers are unordered; i.e. event handlers are invoked in an arbitrary order. Event handlers should not rely on the logic of other handlers to succeed.

The entirety of this app module is EXPERIMENTAL and subject to change. Pay attention to release notes.

func (App) CaddyModule

func (App) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*App) Emit

func (app *App) Emit(ctx caddy.Context, eventName string, data map[string]any) Event

Emit creates and dispatches an event named eventName to all relevant handlers with the metadata data. Events are emitted and propagated synchronously. The returned Event value will have any additional information from the invoked handlers.

Note that the data map is not copied, for efficiency. After Emit() is called, the data passed in should not be changed in other goroutines.

func (*App) On

func (app *App) On(eventName string, handler Handler) error

On is syntactic sugar for Subscribe() that binds a single handler to a single event from any module. If the eventName is empty string, it counts for all events.

func (*App) Provision

func (app *App) Provision(ctx caddy.Context) error

Provision sets up the app.

func (*App) Start

func (app *App) Start() error

Start runs the app.

func (*App) Stop

func (app *App) Stop() error

Stop gracefully shuts down the app.

func (*App) Subscribe

func (app *App) Subscribe(s *Subscription) error

Subscribe binds one or more event handlers to one or more events according to the subscription s. For now, subscriptions can only be created during the provision phase; new bindings cannot be created after the events app has started.

type CloudEvent

type CloudEvent struct {
	ID              string          `json:"id"`
	Source          string          `json:"source"`
	SpecVersion     string          `json:"specversion"`
	Type            string          `json:"type"`
	Time            time.Time       `json:"time"`
	DataContentType string          `json:"datacontenttype,omitempty"`
	Data            json.RawMessage `json:"data,omitempty"`
}

CloudEvent is a JSON-serializable structure that is compatible with the CloudEvents specification. See https://cloudevents.io.

type Event

type Event struct {
	// If non-nil, the event has been aborted, meaning
	// propagation has stopped to other handlers and
	// the code should stop what it was doing. Emitters
	// may choose to use this as a signal to adjust their
	// code path appropriately.
	Aborted error

	// The data associated with the event. Usually the
	// original emitter will be the only one to set or
	// change these values, but the field is exported
	// so handlers can have full access if needed.
	// However, this map is not synchronized, so
	// handlers must not use this map directly in new
	// goroutines; instead, copy the map to use it in a
	// goroutine.
	Data map[string]any
	// contains filtered or unexported fields
}

Event represents something that has happened or is happening. An Event value is not synchronized, so it should be copied if being used in goroutines.

EXPERIMENTAL: As with the rest of this package, events are subject to change.

func (Event) CloudEvent

func (e Event) CloudEvent() CloudEvent

CloudEvent exports event e as a structure that, when serialized as JSON, is compatible with the CloudEvents spec.

type Handler

type Handler interface {
	Handle(context.Context, Event) error
}

Handler is a type that can handle events.

type Subscription

type Subscription struct {
	// The name(s) of the event(s) to bind to. Default: all events.
	Events []string `json:"events,omitempty"`

	// The ID or namespace of the module(s) from which events
	// originate to listen to for events. Default: all modules.
	//
	// Events propagate up, so events emitted by module "a.b.c"
	// will also trigger the event for "a.b" and "a". Thus, to
	// receive all events from "a.b.c" and "a.b.d", for example,
	// one can subscribe to either "a.b" or all of "a" entirely.
	Modules []caddy.ModuleID `json:"modules,omitempty"`

	// The event handler modules. These implement the actual
	// behavior to invoke when an event occurs. At least one
	// handler is required.
	HandlersRaw []json.RawMessage `json:"handlers,omitempty" caddy:"namespace=events.handlers inline_key=handler"`

	// The decoded handlers; Go code that is subscribing to
	// an event should set this field directly; HandlersRaw
	// is meant for JSON configuration to fill out this field.
	Handlers []Handler `json:"-"`
}

Subscription represents binding of one or more handlers to one or more events.