events

Documentation

Overview

Package events provides typed event emission and subscription for the jb-mesh event bus. System events are emitted automatically by node/tool lifecycle hooks. User events are emitted by tools via the SDK.

NATS subject namespace (DESIGN.md §2.3):

events.tool.<event>   — tool lifecycle
events.node.<event>   — node lifecycle
events.user.<topic>   — user-defined (free-form)

Index

• type Bus
  • func NewBus(nc *nats.Conn, nodeName string) *Bus
  • func (b *Bus) Emit(event Event) error
  • func (b *Bus) Subscribe(pattern string, handler EventHandler) (*nats.Subscription, error)
  • func (b *Bus) SubscribeType(eventType string, handler EventHandler) (*nats.Subscription, error)
• type Event
  • func NodeHealth(node, status string, resources map[string]interface{}) Event
  • func NodeJoined(node string, capabilities map[string]interface{}) Event
  • func NodeLeft(node, reason string) Event
  • func ToolConfigured(node, tool string, config map[string]interface{}) Event
  • func ToolCrashed(node, tool string, err error, restartCount int) Event
  • func ToolInstalled(node, tool, version string) Event
  • func ToolRemoved(node, tool string) Event
  • func ToolStarted(node, tool string) Event
  • func ToolStopped(node, tool, reason string) Event
  • func UserEvent(node, topic string, data map[string]interface{}) Event
• type EventHandler
• type PersistConfig
  • func DefaultPersistConfig() PersistConfig
• type PersistentBus
  • func NewPersistentBus(nc *nats.Conn, js nats.JetStreamContext, nodeName string, cfg PersistConfig) (*PersistentBus, error)
  • func (pb *PersistentBus) History(filter string, limit int) ([]Event, error)
  • func (pb *PersistentBus) HistorySince(filter string, since time.Time, limit int) ([]Event, error)

Types

type Bus

type Bus struct {
	// contains filtered or unexported fields
}

Bus handles event emission and subscription over NATS.

func NewBus

func NewBus(nc *nats.Conn, nodeName string) *Bus

NewBus creates an event bus attached to a NATS connection.

func (*Bus) Emit

func (b *Bus) Emit(event Event) error

Emit publishes an event to the appropriate NATS subject. The subject is derived from the event type: "tool.installed" → "events.tool.installed"

func (*Bus) Subscribe

func (b *Bus) Subscribe(pattern string, handler EventHandler) (*nats.Subscription, error)

Subscribe listens for events matching a subject pattern. Pattern examples:

• "events.tool.*" — all tool events
• "events.node.*" — all node events
• "events.tool.crashed" — only crash events
• "events.>" — all events
• "events.user.>" — all user events

func (*Bus) SubscribeType

func (b *Bus) SubscribeType(eventType string, handler EventHandler) (*nats.Subscription, error)

SubscribeType is a convenience for subscribing to a specific event type. E.g., SubscribeType("tool.crashed", handler)

type Event

type Event struct {
	Type      string                 `json:"type"` // e.g. "tool.installed", "node.joined"
	Node      string                 `json:"node"` // originating node
	Timestamp time.Time              `json:"timestamp"`
	Data      map[string]interface{} `json:"data"`
}

Event is the envelope for all mesh events.

func NodeHealth

func NodeHealth(node, status string, resources map[string]interface{}) Event

NodeHealth creates a node.health event.

func NodeJoined

func NodeJoined(node string, capabilities map[string]interface{}) Event

NodeJoined creates a node.joined event.

func NodeLeft

func NodeLeft(node, reason string) Event

NodeLeft creates a node.left event.

func ToolConfigured

func ToolConfigured(node, tool string, config map[string]interface{}) Event

ToolConfigured creates a tool.configured event.

func ToolCrashed

func ToolCrashed(node, tool string, err error, restartCount int) Event

ToolCrashed creates a tool.crashed event.

func ToolInstalled

func ToolInstalled(node, tool, version string) Event

ToolInstalled creates a tool.installed event.

func ToolRemoved

func ToolRemoved(node, tool string) Event

ToolRemoved creates a tool.removed event.

func ToolStarted

func ToolStarted(node, tool string) Event

ToolStarted creates a tool.started event.

func ToolStopped

func ToolStopped(node, tool, reason string) Event

ToolStopped creates a tool.stopped event.

func UserEvent

func UserEvent(node, topic string, data map[string]interface{}) Event

UserEvent creates a user-defined event (events.user.<topic>).

type EventHandler

type EventHandler func(Event)

EventHandler is called when an event is received.

type PersistConfig

type PersistConfig struct {
	StreamName string        // default: "MESH_EVENTS"
	MaxAge     time.Duration // how long to keep events, default: 24h
	MaxMsgs    int64         // max events to keep, default: 10000 (0 = unlimited)
}

PersistConfig controls event persistence behavior.

func DefaultPersistConfig

func DefaultPersistConfig() PersistConfig

DefaultPersistConfig returns sensible defaults.

type PersistentBus

type PersistentBus struct {
	*Bus
	// contains filtered or unexported fields
}

PersistentBus extends Bus with JetStream-backed event persistence. Events are stored in a stream and can be replayed/queried.

func NewPersistentBus

func NewPersistentBus(nc *nats.Conn, js nats.JetStreamContext, nodeName string, cfg PersistConfig) (*PersistentBus, error)

NewPersistentBus creates an event bus with JetStream persistence. All events published to events.> are captured in a stream.

func (*PersistentBus) History

func (pb *PersistentBus) History(filter string, limit int) ([]Event, error)

History returns recent events matching a subject filter. Filter examples: "events.tool.crashed", "events.>", "events.node.*"

func (*PersistentBus) HistorySince

func (pb *PersistentBus) HistorySince(filter string, since time.Time, limit int) ([]Event, error)

HistorySince returns events after a given timestamp.