event

Documentation

Overview

Package event provides shared event types and the event bus implementation used by all Scrinium layers.

This is a leaf package in the dependency DAG: it does not import anything from the project except the standard library. Placing it here, rather than inside curator, allows the minimal stack (a single Store without Curator) to subscribe to and publish events.

The default EventBus implementation is synchronous, panic-safe, and non-persistent. Custom implementations (asynchronous, buffered, filtering) are the host application's responsibility and plug in through the Publisher interface declared in core.

Reserved type-string namespaces

Event.Type is a free-form string but the engine reserves four prefixes for its own emitters. Each prefix has a single owning package — that's where the constant set and the payload structs live. User code must not emit under these prefixes; pick a project-specific namespace ("acme.quota_monitor.tripped") instead.

"core.*"    — core/events.go (Store-level: manifest_saved,
              artifact_deleted, store_degraded, ...)
"agent.*"   — agent/events.go (background-agent lifecycle:
              started, progress, cycle, failed, ...)
"curator.*" — curator/curator.go (orchestration: drain_completed,
              host_storage_pressure, replication_lag, ...)
"index.*"   — index/events.go (StoreIndex metrics: write_latency,
              contention_error, size)

Reservations are by convention — the bus does not enforce them at runtime. Treat unknown user prefixes as opaque and forward.

Index

• type Event
• type EventBus
  • func NewEventBus() EventBus

Types

type Event

type Event struct {
	Type    string
	Payload any
}

Event is a single message on the bus. Type identifies the event (for example, "core.manifest_saved", "agent.started"); Payload carries the concrete payload whose type is determined by Type.

type EventBus

type EventBus interface {
	Publish(e Event)
	Subscribe(fn func(Event))
}

EventBus is the bus contract. The default implementation (returned by NewEventBus) is synchronous, panic-safe, and does not persist events: a subscriber registered after a Publish call does not receive that event.

func NewEventBus

func NewEventBus() EventBus

NewEventBus returns an event bus with the following guarantees:

• Delivery is synchronous: Publish returns only after every subscriber active at the moment of the call has been invoked.
• Subscribers are invoked in registration order.
• A panic from a subscriber is recovered; delivery to the remaining subscribers continues.
• Registering a new subscriber concurrently with Publish is race-free; the new subscriber starts receiving events from the next Publish onward.