eventbus

Documentation

Overview

Package eventbus provides an in-process, ordered, at-most-once event bus.

Index

• Variables
• type Bus
  • func New(config Config, logger modularlog.Logger) (*Bus, error)
  • func (b *Bus) Close(ctx context.Context) error
  • func (b *Bus) Name() string
  • func (b *Bus) Publish(ctx context.Context, event Event) error
  • func (b *Bus) Setup(ctx context.Context) error
  • func (b *Bus) Stats() Stats
  • func (b *Bus) Subscribe(name string, handler Handler) error
• type Config
• type Event
• type Handler
• type Stats

Variables

var (
	ErrNotRunning = errors.New("event bus is not running")
	ErrClosed     = errors.New("event bus is closed")
	ErrFull       = errors.New("event bus queue is full")
	ErrInvalid    = errors.New("event bus argument is invalid")
)

Types

type Bus

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

Bus is a core.Resource. Setup starts one consumer and Close drains it.

func New

func New(config Config, logger modularlog.Logger) (*Bus, error)

New creates an EventBus without starting its consumer.

func (*Bus) Close

func (b *Bus) Close(ctx context.Context) error

Close rejects new events and drains all events accepted before the close.

func (*Bus) Name

func (b *Bus) Name() string

Name returns the Resource label.

func (*Bus) Publish

func (b *Bus) Publish(ctx context.Context, event Event) error

Publish enqueues one event without blocking when the queue is full.

func (*Bus) Setup

func (b *Bus) Setup(ctx context.Context) error

Setup starts the single consumer.

func (*Bus) Stats

func (b *Bus) Stats() Stats

Stats returns observable queue and handler counters.

func (*Bus) Subscribe

func (b *Bus) Subscribe(name string, handler Handler) error

Subscribe registers a handler before Setup. Handlers run in registration order.

type Config

type Config = configitem.EventBus

Config configures one process-local bus.

type Event

type Event struct {
	Name       string
	Key        string
	Payload    any
	OccurredAt time.Time
}

Event is the immutable envelope visible to handlers. Payload ownership remains with the publisher and must not be mutated after Publish returns.

type Handler

type Handler func(context.Context, Event) error

Handler consumes one local event.

type Stats

type Stats struct {
	Published     uint64
	Handled       uint64
	Dropped       uint64
	HandlerErrors uint64
	HandlerPanics uint64
	Capacity      int
	Queued        int
	HighWatermark int64
}

Stats is a point-in-time bus snapshot.