Events module

Source: modules/events/.

modules/events/
├── command.go
├── router.go
├── service.go
├── models.go
└── commands/

• shc events — stream and view system events
  • CLI reference

Routes are listed in the generated route reference; request/response notes live in the API reference.

The events module is the live event fan-out for the running daemon. It takes two upstream sources of data — Docker events and audit events — and multiplexes them to two downstream consumers:

1. SSE clients (the UI, shc events, external integrations) via the SSE broker in subsystems/impl/sse_broker.go, sharded by tenant on channels like events:<tenant>.
2. Internal subscribers inside the process (e.g. the deployment tracker, live-progress logic) via channel-based subscriptions registered with the module.

The module is functional, not class-heavy:

• BroadcastDockerEvent(event) — dedups by a short hash of (ts, action, container, node), caps the seen-set at config.EventDedupCacheSize (default 10000), publishes to SSE, then pushes to every internal subscriber channel.
• BroadcastAuditEvent(event) — publishes to SSE (no dedup; audit events are assumed unique by primary key).
• FilterEvent(...) — shared filter logic used by CLI and SSE alike.
• EventStreamService owns the StartAuditPoller goroutine that periodically polls the audit table for rows the daemon didn’t see in-process (covers cross-node audit events in a cluster).

What the events module does not own: the Docker event source itself (that is subsystems/impl/docker_events.go), SSE transport (that is subsystems/impl/sse_broker.go), or persistence (audit rows are owned by the audit module). This module is a pure distribution layer sitting in front of both.

See also: architecture/events/event-bus.md for the broader real-time layer.