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.

Field name	Field type	Comment
Subscriptions	[]*Subscription	Subscriptions bind handlers to one or more events either globally or scoped to specific modules or module namespaces.
subscriptions	map[string]map[caddy.ModuleID][]Handler	Map of event name to map of module ID/namespace to handlers
logger	*zap.Logger	No comment on field.
started	bool	No comment on field.

Handler is a type that can handle events.

Field name	Field type	Comment
type	any	No comment on field.

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

Field name	Field type	Comment
Events	[]string	The name(s) of the event(s) to bind to. Default: all events.
Modules	[]caddy.ModuleID	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.
HandlersRaw	[]json.RawMessage	The event handler modules. These implement the actual behavior to invoke when an event occurs. At least one handler is required.
Handlers	[]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.

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.

Uses: context.WithValue, errors.Is, strings.HasPrefix, strings.LastIndex, strings.TrimPrefix, zap.Any, zap.Bool, zap.Error, zap.String.

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.

Provision sets up the app.

Uses: fmt.Errorf.

Start runs the app.

Stop gracefully shuts down the app.

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.

Uses: fmt.Errorf.

CaddyModule returns the Caddy module information.