Events

The events app is a small, in-process pub/sub bus. Module ID events, defined in modules/caddyevents/app.go.

Purpose

Let modules emit named events and let other modules (or admin code) subscribe and run handler chains in response. It is intentionally small — it has no message broker, no persistence, no fan-out across processes. Everything happens inside the running Caddy instance.

Directory layout

Path	Role
modules/caddyevents/app.go	The App and the Event/Subscription types
modules/caddyevents/eventsconfig/	Optional Caddyfile-style config helpers

Key abstractions

Type	Where	Description
App	app.go	The events app; holds the subscription list and the emit method
Event	app.go	{Name, Origin, Data} envelope passed to subscribers
Subscription	app.go	Match criteria (event name, originator module) + a list of handler modules
Handler	app.go	Module interface implemented by event-handler modules

How it works

graph LR
    Emitter[caddyevents.App.Emit]
    Sub1[Subscription 1<br/>name=tls.cert_obtained]
    Sub2[Subscription 2<br/>name=tls.cert_failed]
    Handler1[Handler module]
    Handler2[Handler module]

    Emitter --> Sub1 --> Handler1
    Emitter --> Sub2 --> Handler2

App.Emit walks the configured subscriptions, matches by event name and (optionally) originator, and invokes each subscription's handler chain in order. Handlers that return an error don't halt the chain — events are best-effort.

The events app discovers itself through caddy.Context.App("events"). Modules looking to emit do something like:

ev, _ := ctx.App("events")
if events, ok := ev.(*caddyevents.App); ok {
    events.Emit(ctx, "tls.cert_obtained", originID, data)
}

(There's a helper for this; see caddyevents.App.Emit for the signature.)

Integration points

• tls app: emits events for cert renewal results, OCSP refresh, and CA changes.
• http app: emits a small set of lifecycle events.
• Custom modules: can subscribe to those events and react (run a webhook, write a log, run a script).

Entry points for modification

• Want to define a new event source? Document the event name and Data shape, then call Emit from the appropriate spot.
• Want a new handler kind (e.g. "exec command")? Implement the caddyevents.Handler interface and register the module under the appropriate namespace; reference it in subscriptions.

Related pages

• Module system
• TLS app