libevents

package
v0.40.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 13, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

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

View Source
const (
	FiringStatusRunning = "running"
	FiringStatusOK      = "ok"
	FiringStatusError   = "error"
	FiringStatusRefused = "refused"
)

Firing statuses recorded on firing rows.

View Source
const (
	DefaultFiringLimit = 50
	MaxFiringLimit     = 1000
)

Firing-listing bounds: unset defaults to DefaultFiringLimit, over MaxFiringLimit is clamped.

View Source
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.

View Source
const (
	DefaultListenerLimit = 50
	MaxListenerLimit     = 1000
)

Listener-listing bounds.

View Source
const (
	DefaultStagingLimit = 100
	MaxStagingLimit     = 1000
)

Staging bounds.

Variables

This section is empty.

Functions

func InitSchema

func InitSchema(ctx context.Context, exec libdb.Exec, cfg Config) error

InitSchema creates the package's tables and indexes if absent; idempotent and safe to call against an already-compatible schema.

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.

func (Config) Validate

func (c Config) Validate() error

Validate rejects identifiers that could not be safely 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.

func (*CursorStore) GetCursor

func (s *CursorStore) GetCursor(ctx context.Context, exec libdb.Exec, consumer string) (int64, error)

GetCursor returns consumer's last settled NID, 0 when none exists.

func (*CursorStore) SetCursor

func (s *CursorStore) SetCursor(ctx context.Context, exec libdb.Exec, consumer string, nid int64) error

SetCursor upserts consumer's position to nid; a lower value than stored is permitted (rewind).

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.

func (Firing) Stranded

func (f Firing) Stranded(now time.Time, staleClaim time.Duration) bool

Stranded reports whether f is a running claim older than staleClaim as of now.

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

func (s *ListenerStore) AppendListener(ctx context.Context, exec libdb.Exec, l *Listener) error

AppendListener stores l and its topic rows in the caller's transaction; l.ID and at least one type are required.

func (*ListenerStore) DeleteListener

func (s *ListenerStore) DeleteListener(ctx context.Context, exec libdb.Exec, id string) error

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL