Events Module

Global eventing system for emitting and handling events across Caddy modules

The events module is EXPERIMENTAL and subject to change. Pay close attention to release notes when upgrading.

The events module implements a global eventing system within Caddy. Modules can emit and subscribe to events, providing hooks into deep parts of the codebase that aren’t otherwise accessible.

Overview

Module ID: events

The events system enables:

• Event emission - Modules can broadcast events when important actions occur
• Event subscription - Handlers can react to events from specific modules
• Event propagation - Events bubble up the module tree (DOM-like)
• Flow control - Handlers can abort event propagation
• Metadata passing - Events carry data between emitters and handlers

Event Propagation

Events propagate in a DOM-like fashion:

Event from module "a.b.c" triggers handlers listening to:
1. "a.b.c" (origin)
2. "a.b" (parent)
3. "a" (grandparent)
4. "" (all events)

This allows handlers to:

• Listen to specific modules
• Listen to entire namespaces
• Catch all events globally

Configuration

Basic Structure

JSON

{
  "apps": {
    "events": {
      "subscriptions": [
        {
          "events": ["cert_obtained"],
          "modules": ["tls"],
          "handlers": [
            {
              "handler": "exec",
              "command": "reload-service.sh"
            }
          ]
        }
      ]
    }
  }
}

Subscriptions

Subscriptions bind handlers to events.

events · array of strings

Event name(s) to listen for. If empty or omitted, matches all events.

Examples:

• ["cert_obtained"] - Listen for certificate obtained events
• ["cert_obtained", "cert_renewed"] - Multiple specific events
• [] - All events

modules · array of module IDs

Module ID(s) or namespaces from which to receive events. If empty or omitted, matches all modules.

Examples:

• ["tls"] - All TLS events
• ["http.handlers.file_server"] - Specific module
• ["http.handlers"] - All HTTP handlers
• [] - All modules

handlers · array of objects · required

Event handler modules that execute when events match. At least one handler is required.

Handlers are invoked in an arbitrary order.

Subscription Examples

Listen to All TLS Events

{
  "subscriptions": [
    {
      "modules": ["tls"],
      "handlers": [
        {
          "handler": "exec",
          "command": "log-tls-event.sh"
        }
      ]
    }
  ]
}

Listen to Specific Event from Any Module

{
  "subscriptions": [
    {
      "events": ["cert_obtained"],
      "handlers": [
        {
          "handler": "exec",
          "command": "notify-cert-obtained.sh"
        }
      ]
    }
  ]
}

Listen to All HTTP Handler Events

{
  "subscriptions": [
    {
      "modules": ["http.handlers"],
      "events": ["request_received"],
      "handlers": [
        {
          "handler": "log",
          "level": "info"
        }
      ]
    }
  ]
}

Catch-All Subscription

{
  "subscriptions": [
    {
      "handlers": [
        {
          "handler": "exec",
          "command": "log-all-events.sh"
        }
      ]
    }
  ]
}

Event Handlers

Event handlers implement the action to take when an event occurs.

Handler Interface

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

Handlers receive:

• Context - Request context with cancellation
• Event - Event data including name, origin, timestamp, and metadata

Handlers can:

• Read event data
• Add metadata to the event
• Return caddy.ErrEventAborted to stop propagation
• Return other errors (logged but don’t stop propagation)

Event Object

Events contain:

id · UUID

Unique identifier for this event occurrence

name · string

Event name (e.g., cert_obtained)

timestamp · time.Time

When the event was created

origin · Module

The module that emitted the event

data · map[string]any

Event-specific metadata. Not copied for efficiency; don’t modify in other goroutines after emission.

aborted · error

Set to caddy.ErrEventAborted if a handler aborted the event

Event Data in Replacer

Event information is automatically available in the Caddy replacer:

• {event} - The full event object
• {event.id} - Event UUID
• {event.name} - Event name
• {event.time} - Event timestamp
• {event.time_unix} - Unix timestamp in milliseconds
• {event.module} - Origin module ID
• {event.data} - Full data map
• {event.data.field_name} - Specific field from event data

Useful in handler configurations:

{
  "handler": "exec",
  "command": "notify.sh",
  "args": ["{event.name}", "{event.time}", "{event.data.domain}"]
}

Aborting Events

Handlers can abort event propagation by returning caddy.ErrEventAborted:

func (h MyHandler) Handle(ctx context.Context, e caddy.Event) error {
    if shouldAbort(e) {
        return caddy.ErrEventAborted
    }
    return nil
}

When aborted:

1. Event propagation stops immediately
2. Event is marked as aborted
3. Emitter receives the aborted event
4. Emitter may choose to adjust program flow

Not all event emitters support aborting. Check module documentation to see if aborting an event affects behavior.

Synchronous Execution

Event handlers are fired synchronously as part of the regular program flow. This means:

✅ Benefits:

• Handlers can control program flow
• Handlers can add data back to the origin module
• Predictable execution order (within a subscription level)

⚠️ Cautions:

• Slow handlers block the emitter
• Handlers should complete quickly
• Long-running tasks should spawn goroutines

Handler Ordering

Event handlers are invoked in arbitrary order within each subscription level. Do not rely on handler execution order.

Handlers should:

• Be independent of each other
• Not rely on other handlers’ logic
• Be idempotent when possible

Programmatic Subscriptions

Go code can subscribe to events during provisioning:

func (m *MyModule) Provision(ctx caddy.Context) error {
    eventsApp, err := ctx.App("events")
    if err != nil {
        return err
    }
    
    events := eventsApp.(*caddyevents.App)
    return events.On("cert_obtained", &myHandler{})
}

On() Method

Syntactic sugar for simple subscriptions:

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

• eventName - Event to listen for (empty string = all events)
• handler - Handler to invoke
• Listens to events from all modules

Emitting Events

Modules emit events using:

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

Example Emission

func (m *MyModule) DoSomething(ctx caddy.Context) error {
    // Do work...
    
    // Emit event
    eventsApp, _ := ctx.App("events")
    if eventsApp != nil {
        events := eventsApp.(*caddyevents.App)
        e := events.Emit(ctx, "something_happened", map[string]any{
            "status": "success",
            "details": "Work completed",
            "count": 42,
        })
        
        // Check if aborted
        if e.Aborted != nil {
            // Adjust program flow
            return e.Aborted
        }
    }
    
    return nil
}

Common Event Names

While event names are module-specific, some common patterns:

• cert_obtained - Certificate was obtained
• cert_renewed - Certificate was renewed
• cert_failed - Certificate operation failed
• config_loaded - Configuration loaded
• server_started - Server started
• server_stopped - Server stopped
• request_received - HTTP request received
• response_sent - HTTP response sent

Check specific module documentation for available events.

Use Cases

Certificate Lifecycle Hooks

{
  "subscriptions": [
    {
      "events": ["cert_obtained", "cert_renewed"],
      "modules": ["tls"],
      "handlers": [
        {
          "handler": "exec",
          "command": "systemctl",
          "args": ["reload", "nginx"]
        }
      ]
    }
  ]
}

Logging Events

{
  "subscriptions": [
    {
      "events": ["cert_failed"],
      "handlers": [
        {
          "handler": "log",
          "level": "error",
          "message": "Certificate operation failed for {event.data.domain}"
        }
      ]
    }
  ]
}

Webhooks

{
  "subscriptions": [
    {
      "events": ["cert_obtained"],
      "handlers": [
        {
          "handler": "webhook",
          "url": "https://hooks.example.com/cert-obtained",
          "method": "POST"
        }
      ]
    }
  ]
}

Metrics Collection

{
  "subscriptions": [
    {
      "modules": ["http"],
      "handlers": [
        {
          "handler": "metrics",
          "prometheus_endpoint": "localhost:9090"
        }
      ]
    }
  ]
}

Best Practices

1. Keep handlers fast - Spawn goroutines for long-running work
2. Handle errors gracefully - Don’t crash on event handling errors
3. Be specific - Subscribe to specific events/modules when possible
4. Don’t modify shared state - Event data map is shared; don’t mutate it
5. Test abort behavior - Ensure aborting events works as expected
6. Log appropriately - Use structured logging in handlers

Troubleshooting

Handlers Not Firing

Problem: Event handlers aren’t being invoked

Solutions:

• Verify event name matches exactly
• Check module ID is correct
• Ensure subscription is in apps.events.subscriptions
• Enable debug logging to see event emissions

Event Storms

Problem: Too many events causing performance issues

Solutions:

• Be more specific in subscriptions
• Add filtering in handlers
• Avoid emitting events in tight loops

Context Cancellation

Problem: context canceled errors in handlers

Solutions:

• Check for context cancellation in long-running handlers
• Respect context deadlines
• Don’t block indefinitely

Security Considerations

• Handler execution is synchronous - Malicious handlers can block operations
• Event data is shared - Don’t include secrets in event data
• Handlers run with Caddy’s privileges - Be cautious with exec handlers
• No sandboxing - Handlers have full access to Caddy’s internals

Future Development

As an experimental feature, the events module may change significantly. Possible future additions:

• Asynchronous event handling
• Event filtering/transformation
• Event persistence
• Remote event emission
• Event replay