API Reference
Complete API reference for the github.com/zoobz-io/capitan package.
Module-Level Functions
These functions operate on the default singleton instance. Optionally use Configure before any other calls to customize options.
Emit
func Emit(ctx context.Context, signal Signal, fields ...Field)
Dispatches an event with Info severity. The event is queued to the signal's worker goroutine for asynchronous processing. Events are silently dropped if emitted after Shutdown has been called.
Debug
func Debug(ctx context.Context, signal Signal, fields ...Field)
Dispatches an event with Debug severity.
Info
func Info(ctx context.Context, signal Signal, fields ...Field)
Dispatches an event with Info severity. Equivalent to Emit.
Warn
func Warn(ctx context.Context, signal Signal, fields ...Field)
Dispatches an event with Warn severity.
Error
func Error(ctx context.Context, signal Signal, fields ...Field)
Dispatches an event with Error severity.
Replay
func Replay(ctx context.Context, e *Event)
Re-emits a historical event. Replay events process synchronously in the calling goroutine, bypass worker queues, and are marked as replays (check with e.IsReplay()).
Hook
func Hook(signal Signal, callback EventCallback) *Listener
Registers a listener for a signal. Returns a *Listener that can be closed to unregister.
HookOnce
func HookOnce(signal Signal, callback EventCallback) *Listener
Registers a listener that fires only once, then automatically unregisters. Returns a *Listener that can be closed early to prevent the callback from firing.
Observe
func Observe(callback EventCallback, signals ...Signal) *Observer
Registers an observer. If signals are provided, observes only those signals. If no signals are provided, observes all signals including those created after registration.
Stats
func Stats() Stats
Returns a snapshot of runtime metrics.
Configure
func Configure(opts ...Option)
Sets options for the default instance. Must be called before any other capitan function. Configuration is locked after the default instance is created.
ApplyConfig
func ApplyConfig(cfg Config) error
Applies per-signal configuration to the default instance. Replaces any previous config entirely. See Configuration Guide for details.
Shutdown
func Shutdown()
Drains pending events and stops all worker goroutines. Safe to call multiple times.
Default
func Default() *Capitan
Returns the default singleton instance, creating it if necessary.
Capitan
The main coordinator type. Create isolated instances with New.
New
func New(opts ...Option) *Capitan
Creates a new instance with the given options. Each instance has independent workers, buffers, and registries.
Methods
Hook
func (c *Capitan) Hook(signal Signal, callback EventCallback) *Listener
Registers a listener for a signal on this instance. Returns nil if MaxListeners is configured and the limit is reached.
HookOnce
func (c *Capitan) HookOnce(signal Signal, callback EventCallback) *Listener
Registers a listener that fires only once, then automatically unregisters.
Observe
func (c *Capitan) Observe(callback EventCallback, signals ...Signal) *Observer
Registers an observer on this instance.
Emit
func (c *Capitan) Emit(ctx context.Context, signal Signal, fields ...Field)
Dispatches an event with Info severity on this instance.
Debug
func (c *Capitan) Debug(ctx context.Context, signal Signal, fields ...Field)
Dispatches an event with Debug severity on this instance.
Info
func (c *Capitan) Info(ctx context.Context, signal Signal, fields ...Field)
Dispatches an event with Info severity on this instance.
Warn
func (c *Capitan) Warn(ctx context.Context, signal Signal, fields ...Field)
Dispatches an event with Warn severity on this instance.
Error
func (c *Capitan) Error(ctx context.Context, signal Signal, fields ...Field)
Dispatches an event with Error severity on this instance.
Replay
func (c *Capitan) Replay(ctx context.Context, e *Event)
Re-emits a historical event on this instance.
Stats
func (c *Capitan) Stats() Stats
Returns runtime metrics for this instance.
Shutdown
func (c *Capitan) Shutdown()
Drains pending events and stops workers for this instance.
IsShutdown
func (c *Capitan) IsShutdown() bool
Reports whether Shutdown has been called on this instance.
Drain
func (c *Capitan) Drain(ctx context.Context) error
Blocks until all currently queued events have been processed. Unlike Shutdown, workers remain active after draining. Returns an error if the context is cancelled before drain completes.
ApplyConfig
func (c *Capitan) ApplyConfig(cfg Config) error
Applies per-signal configuration. Replaces any previous config entirely—signals not in the new config revert to defaults. Only rebuilds workers whose resolved config actually changed.
Signal
Identifies an event type for routing.
NewSignal
func NewSignal(name, description string) Signal
Creates a signal with a name (used for routing) and human-readable description.
Methods
Name
func (s Signal) Name() string
Returns the signal's identifier.
Description
func (s Signal) Description() string
Returns the signal's human-readable description.
Event
Represents a signal emission with typed fields.
NewEvent
func NewEvent(signal Signal, severity Severity, timestamp time.Time, fields ...Field) *Event
Creates an event for replay. Unlike internally emitted events, these are not pooled and can be held safely.
Methods
Signal
func (e *Event) Signal() Signal
Returns the event's signal.
Timestamp
func (e *Event) Timestamp() time.Time
Returns when the event was created.
Context
func (e *Event) Context() context.Context
Returns the context passed at emission time.
Severity
func (e *Event) Severity() Severity
Returns the event's severity level.
IsReplay
func (e *Event) IsReplay() bool
Returns true if this event was replayed from storage.
Get
func (e *Event) Get(key Key) Field
Returns the field for the given key, or nil if not present.
Fields
func (e *Event) Fields() []Field
Returns all fields as a defensive copy.
Clone
func (e *Event) Clone() *Event
Creates a deep copy of the event that is safe to retain. Use this when you need to store or pass an event beyond the listener callback, as pooled events are recycled after all listeners complete.
Listener
Active subscription to a signal.
Close
func (l *Listener) Close()
Unregisters the listener and stops receiving events. Blocks until all events queued before Close was called have been processed. When the last listener for a signal closes, the worker goroutine exits.
Drain
func (l *Listener) Drain(ctx context.Context) error
Blocks until all events queued before Drain was called have been processed. Unlike Close, the listener remains active after draining. Returns an error if the context is cancelled before drain completes.
Observer
Dynamic subscription to multiple signals.
Close
func (o *Observer) Close()
Unregisters all underlying listeners.
Drain
func (o *Observer) Drain(ctx context.Context) error
Blocks until all events queued before Drain was called have been processed across all observed signals. Unlike Close, the observer remains active after draining. Returns an error if the context is cancelled before drain completes.
Options
Configuration functions for New and Configure. See Configuration Guide for usage guidance.
WithBufferSize
func WithBufferSize(size int) Option
Sets the event queue buffer size per signal. Default: 16.
WithPanicHandler
func WithPanicHandler(handler PanicHandler) Option
Sets the callback invoked when a listener panics. Default: silent recovery.
WithSyncMode
func WithSyncMode() Option
Enables synchronous event processing. For testing only.
Callback Types
type EventCallback func(context.Context, *Event)
Handler function for events.
type PanicHandler func(signal Signal, recovered any)
Handler function for listener panics.
Severity
Event severity levels.
| Constant | Value | Description |
|---|---|---|
SeverityDebug | "DEBUG" | Development, troubleshooting |
SeverityInfo | "INFO" | Normal operations (default) |
SeverityWarn | "WARN" | Warning conditions |
SeverityError | "ERROR" | Error conditions |
Stats
Runtime metrics snapshot.
type Stats struct {
ActiveWorkers int
SignalCount int
DroppedEvents uint64
QueueDepths map[Signal]int
ListenerCounts map[Signal]int
EmitCounts map[Signal]uint64
FieldSchemas map[Signal][]Key
}
| Field | Description |
|---|---|
ActiveWorkers | Running worker goroutines |
SignalCount | Number of registered signals |
DroppedEvents | Events emitted with no listeners |
QueueDepths | Current buffer usage per signal |
ListenerCounts | Registered listeners per signal |
EmitCounts | Total emissions per signal |
FieldSchemas | Field keys from first emission per signal |
Per-Signal Configuration Types
Config
Serializable configuration for per-signal settings.
type Config struct {
Signals map[string]SignalConfig `json:"signals"`
}
The Signals map keys can be exact signal names or glob patterns (*, ?, [...]). See Configuration Guide for resolution rules.
SignalConfig
Per-signal configuration options.
type SignalConfig struct {
BufferSize int `json:"bufferSize,omitempty"`
Disabled bool `json:"disabled,omitempty"`
MinSeverity Severity `json:"minSeverity,omitempty"`
MaxListeners int `json:"maxListeners,omitempty"`
DropPolicy DropPolicy `json:"dropPolicy,omitempty"`
RateLimit float64 `json:"rateLimit,omitempty"`
BurstSize int `json:"burstSize,omitempty"`
}
| Field | Default | Description |
|---|---|---|
BufferSize | instance default | Event queue size for this signal |
Disabled | false | Drop all events for this signal |
MinSeverity | none | Filter events below this level |
MaxListeners | unlimited | Cap listener registrations |
DropPolicy | block | Behavior when buffer full |
RateLimit | unlimited | Max events per second |
BurstSize | 1 | Burst allowance above rate limit |
DropPolicy
Behavior when the event buffer is full.
| Constant | Value | Description |
|---|---|---|
DropPolicyBlock | "block" | Wait for space in buffer (default) |
DropPolicyDropNewest | "drop_newest" | Drop incoming events if buffer full |