Documentation
¶
Overview ¶
Package libevents holds the consumer-side state of an event log: durable cursors, firing claims with recorded outcomes, listener subscriptions, and staged events held until a due time. It does not hold the event log itself. Every mutator takes a libdbexec.Exec so a claim or listener change can share the caller's transaction; stores are scoped at construction.
Index ¶
- Constants
- func InitSchema(ctx context.Context, exec libdb.Exec, cfg Config) error
- type Config
- type CursorStore
- type Firing
- type FiringFilter
- type FiringStore
- func (s *FiringStore) BeginFiring(ctx context.Context, exec libdb.Exec, triggerName string, nid int64, ...) (bool, error)
- func (s *FiringStore) FinishFiring(ctx context.Context, exec libdb.Exec, triggerName string, nid int64, ...) error
- func (s *FiringStore) ListFirings(ctx context.Context, exec libdb.Exec, f FiringFilter) ([]Firing, error)
- func (s *FiringStore) ResetFiring(ctx context.Context, exec libdb.Exec, triggerName string, nid int64) (bool, error)
- func (s *FiringStore) StaleClaim() time.Duration
- type FiringStoreOption
- type Listener
- type ListenerStore
- func (s *ListenerStore) AppendListener(ctx context.Context, exec libdb.Exec, l *Listener) error
- func (s *ListenerStore) DeleteListener(ctx context.Context, exec libdb.Exec, id string) error
- func (s *ListenerStore) DeleteListenersByOwner(ctx context.Context, exec libdb.Exec, owner string) ([]string, error)
- func (s *ListenerStore) GetListener(ctx context.Context, exec libdb.Exec, id string) (*Listener, error)
- func (s *ListenerStore) ListListeners(ctx context.Context, exec libdb.Exec, afterCreatedAt time.Time, afterID string, ...) ([]*Listener, error)
- func (s *ListenerStore) ListListenersByType(ctx context.Context, exec libdb.Exec, eventType string) ([]*Listener, error)
- type StagedEvent
- type StagingStore
- func (s *StagingStore) AppendStagedEvent(ctx context.Context, exec libdb.Exec, e *StagedEvent) error
- func (s *StagingStore) DeleteStagedEvents(ctx context.Context, exec libdb.Exec, ids ...string) error
- func (s *StagingStore) ListDueStagedEvents(ctx context.Context, exec libdb.Exec, now time.Time, limit int) ([]*StagedEvent, error)
Constants ¶
const ( FiringStatusRunning = "running" FiringStatusOK = "ok" FiringStatusError = "error" FiringStatusRefused = "refused" )
Firing statuses recorded on firing rows.
const ( DefaultFiringLimit = 50 MaxFiringLimit = 1000 )
Firing-listing bounds: unset defaults to DefaultFiringLimit, over MaxFiringLimit is clamped.
const ( // ListenerKindStart starts new work at the target. ListenerKindStart = "start" // ListenerKindWake resumes something already in flight that registered // this listener and is waiting on it. ListenerKindWake = "wake" )
Listener kinds: what an arriving event does to the target.
const ( DefaultListenerLimit = 50 MaxListenerLimit = 1000 )
Listener-listing bounds.
const ( DefaultStagingLimit = 100 MaxStagingLimit = 1000 )
Staging bounds.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Config ¶
type Config struct {
// TablePrefix prefixes every table this package owns:
// {prefix}cursors, {prefix}firings, {prefix}listeners,
// {prefix}listener_topics, {prefix}staging.
TablePrefix string
// ScopeColumn is the tenancy column present on every table.
ScopeColumn string
}
Config names the SQL identifiers this package interpolates; every other value in a statement is bound, not interpolated.
type CursorStore ¶
type CursorStore struct {
// contains filtered or unexported fields
}
CursorStore is a named consumer's durable position over an event log, scoped at construction.
func NewCursorStore ¶
func NewCursorStore(cfg Config, scope string) (*CursorStore, error)
NewCursorStore builds a cursor store for one scope; the empty scope is valid.
type Firing ¶
type Firing struct {
Scope string
TriggerName string
NID int64
Status string
Error string
RequestID string
CreatedAt time.Time
UpdatedAt time.Time
}
Firing is one recorded (trigger, event) execution attempt.
type FiringFilter ¶
type FiringFilter struct {
// SinceNID keeps firings whose event nid is greater than it; 0 keeps all.
SinceNID int64
// Status keeps one FiringStatus* value; "" keeps all.
Status string
// TriggerName keeps one trigger's firings; "" keeps all.
TriggerName string
// Limit caps the page: <= 0 means DefaultFiringLimit, more than
// MaxFiringLimit is clamped to it.
Limit int
}
FiringFilter narrows a ListFirings read; the zero value lists the whole scope, newest first, up to DefaultFiringLimit.
type FiringStore ¶
type FiringStore struct {
// contains filtered or unexported fields
}
FiringStore is the durable record of which (trigger, event) pairs ran and how they ended, scoped at construction.
func NewFiringStore ¶
func NewFiringStore(cfg Config, scope string, staleClaim time.Duration, opts ...FiringStoreOption) (*FiringStore, error)
NewFiringStore builds a firing store for one scope; staleClaim must be positive and bounds how long a running claim withstands takeover.
func (*FiringStore) BeginFiring ¶
func (s *FiringStore) BeginFiring(ctx context.Context, exec libdb.Exec, triggerName string, nid int64, requestID string) (bool, error)
BeginFiring claims (triggerName, nid) with status running, returning false if already claimed by a live host, or taking over a stale claim.
func (*FiringStore) FinishFiring ¶
func (s *FiringStore) FinishFiring(ctx context.Context, exec libdb.Exec, triggerName string, nid int64, status, errMsg string) error
FinishFiring records the outcome of a claimed firing.
func (*FiringStore) ListFirings ¶
func (s *FiringStore) ListFirings(ctx context.Context, exec libdb.Exec, f FiringFilter) ([]Firing, error)
ListFirings returns the scope's firings matching f, newest first; read-only, callers must not append events from within it.
func (*FiringStore) ResetFiring ¶
func (s *FiringStore) ResetFiring(ctx context.Context, exec libdb.Exec, triggerName string, nid int64) (bool, error)
ResetFiring forces a settled firing back to running, immediately reclaimable by BeginFiring; it refuses to touch a still-live running row.
func (*FiringStore) StaleClaim ¶
func (s *FiringStore) StaleClaim() time.Duration
StaleClaim returns the bound the store was constructed with.
type FiringStoreOption ¶
type FiringStoreOption func(*FiringStore)
FiringStoreOption configures a firing store at construction.
func WithClock ¶
func WithClock(now func() time.Time) FiringStoreOption
WithClock overrides the store's time source.
type Listener ¶
type Listener struct {
ID string
Scope string
// Kind is ListenerKindStart or ListenerKindWake.
Kind string
// Target is opaque to this package; the dispatcher that owns the
// listener interprets it.
Target string
// Owner keys bulk cleanup: every listener registered by one instance,
// session, or configuration unit dies with it via DeleteListenersByOwner.
Owner string
// OneShot listeners are deleted by their consumer when they fire; the
// store carries the flag, the dispatcher enforces it.
OneShot bool
// Types are the exact event types subscribed.
Types []string
// ContextFilters narrows matching beyond the type: per event type, a map
// of attribute to glob pattern, all of which must match.
ContextFilters map[string]map[string]string
// Metadata is opaque JSON for the importer's extensions.
Metadata string
CreatedAt time.Time
UpdatedAt time.Time
}
Listener is one durable subscription: which event types, filtered how, doing what to which target.
type ListenerStore ¶
type ListenerStore struct {
// contains filtered or unexported fields
}
ListenerStore is the durable subscription registry, scoped at construction; mutators take the caller's Exec to share its transaction.
func NewListenerStore ¶
func NewListenerStore(cfg Config, scope string) (*ListenerStore, error)
NewListenerStore builds a listener store for one scope.
func (*ListenerStore) AppendListener ¶
AppendListener stores l and its topic rows in the caller's transaction; l.ID and at least one type are required.
func (*ListenerStore) DeleteListener ¶
DeleteListener removes one listener and its topic rows in the caller's transaction.
func (*ListenerStore) DeleteListenersByOwner ¶
func (s *ListenerStore) DeleteListenersByOwner(ctx context.Context, exec libdb.Exec, owner string) ([]string, error)
DeleteListenersByOwner removes every listener owner registered, returning the ids removed.
func (*ListenerStore) GetListener ¶
func (s *ListenerStore) GetListener(ctx context.Context, exec libdb.Exec, id string) (*Listener, error)
GetListener returns one listener by id, or libdbexec.ErrNotFound.
func (*ListenerStore) ListListeners ¶
func (s *ListenerStore) ListListeners(ctx context.Context, exec libdb.Exec, afterCreatedAt time.Time, afterID string, limit int) ([]*Listener, error)
ListListeners returns a page of the scope's listeners, oldest first, keyset-paginated on (created_at, id): pass the previous page's last row to continue, zero values for the first page.
func (*ListenerStore) ListListenersByType ¶
func (s *ListenerStore) ListListenersByType(ctx context.Context, exec libdb.Exec, eventType string) ([]*Listener, error)
ListListenersByType returns every listener subscribed to eventType; the caller applies context filters.
type StagedEvent ¶
type StagedEvent struct {
ID string
Scope string
Payload []byte
DelayedUntil time.Time
CreatedAt time.Time
}
StagedEvent is an event payload held back until DelayedUntil.
type StagingStore ¶
type StagingStore struct {
// contains filtered or unexported fields
}
StagingStore holds staged events for one scope, fixed at construction.
func NewStagingStore ¶
func NewStagingStore(cfg Config, scope string) (*StagingStore, error)
NewStagingStore builds a staging store for one scope.
func (*StagingStore) AppendStagedEvent ¶
func (s *StagingStore) AppendStagedEvent(ctx context.Context, exec libdb.Exec, e *StagedEvent) error
AppendStagedEvent stores e in the caller's transaction; ID and Payload are required, and a zero DelayedUntil means due immediately.
func (*StagingStore) DeleteStagedEvents ¶
func (s *StagingStore) DeleteStagedEvents(ctx context.Context, exec libdb.Exec, ids ...string) error
DeleteStagedEvents removes the named staged rows in the caller's transaction.
func (*StagingStore) ListDueStagedEvents ¶
func (s *StagingStore) ListDueStagedEvents(ctx context.Context, exec libdb.Exec, now time.Time, limit int) ([]*StagedEvent, error)
ListDueStagedEvents returns staged events due at now, oldest first, up to limit; callers delete what they drain via DeleteStagedEvents in the same transaction.