engine

package
v1.3.0 Latest Latest
Warning

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

Go to latest
Published: Nov 12, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package engine implements the outbox background machinery: the store (enqueue/claim/mark/cleanup queries) and the relay and cleaner workers.

Index

Constants

View Source
const DoneChannel = "outbox_messages_done"

DoneChannel is the LISTEN/NOTIFY channel on which a relay announces rows that reached a terminal status (published, dead, discarded). The payload is "<schema>:<status>:<id>,<id>,..." with at most doneChunk ids, sent inside the completing statement, so a listener sees it only after the commit.

View Source
const NotifyChannel = "outbox_messages"

NotifyChannel is the fixed LISTEN/NOTIFY channel (matches the migration trigger). It cannot be parameterized; cross-schema wake-ups are harmless because SKIP LOCKED deduplicates claims.

Variables

View Source
var ErrInvalidID = errors.New("outbox: message id is not a uuid")

ErrInvalidID is returned for an id that is not a uuid.

View Source
var ErrUndelivered = errors.New("outbox: messages will not be delivered")

ErrUndelivered matches an UndeliveredError through errors.Is.

Functions

func CanonicalIDs added in v1.3.0

func CanonicalIDs(ids []string) ([]string, error)

CanonicalIDs validates ids as uuids and returns them deduplicated in the canonical lowercase hyphenated form PostgreSQL prints, so they compare equal to ids read back from the table or a notification.

Types

type Cleaner

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

Cleaner deletes terminal rows according to their opt-in retention windows.

func NewCleaner

func NewCleaner(s Store, set config.Settings) *Cleaner

NewCleaner builds a Cleaner.

func (*Cleaner) Run

func (c *Cleaner) Run(ctx context.Context) error

Run is a no-op unless at least one retention window and the cleanup interval are set. Otherwise it blocks until ctx is cancelled and returns nil, or returns the first fatal error (see isFatal), including a recovered panic.

type Relay

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

Relay claims ready rows, publishes them, and records the outcome.

func NewRelay

func NewRelay(s Store, pub port.Publisher, set config.Settings, waiters *Waiters) *Relay

NewRelay builds a Relay. Its LISTEN connection also feeds done notifications to waiters.

func (*Relay) Run

func (r *Relay) Run(ctx context.Context) error

Run starts the relay: set.Concurrency worker goroutines plus an optional LISTEN/NOTIFY listener. It blocks until ctx is cancelled and returns nil, or until a fatal error (see isFatal) stops every worker; then it returns that error. Panics in any relay goroutine are recovered as *port.PanicError.

type Store

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

Store runs the outbox SQL. The relay/cleaner queries use exec (must not be tx-bound); enqueue uses enq (joins the caller's business tx). pool is optional and only LISTEN/NOTIFY needs it.

func NewStore

func NewStore(exec, enq port.Executor, pool *pgxpool.Pool, schema string, notifyDone bool) Store

NewStore builds a Store. schema is assumed already validated. notifyDone announces rows reaching a terminal status on DoneChannel.

func (Store) DeliveryState added in v1.3.0

func (s Store) DeliveryState(ctx context.Context, ids []string) (map[string]message.Status, error)

DeliveryState returns the status of every listed row that exists and is not published. ids must be canonical uuids; a row absent from the result is delivered (published, or already removed by the cleaner). It reads through the relay executor, never the caller's transaction, and only by primary key.

func (Store) Enqueue

func (s Store) Enqueue(ctx context.Context, msgs []message.Message) error

Enqueue inserts messages using the transactional Executor, so the rows land in the caller's business transaction. The ID is the dedupe key: a message whose ID already exists (or repeats earlier in msgs) is skipped and the first row kept, so a duplicate never aborts the caller's transaction.

func (Store) Requeue added in v1.1.0

func (s Store) Requeue(ctx context.Context, id string) (bool, error)

Requeue uses the caller's transactional executor. A locked row cannot be removed by cleanup concurrently. Notifications become visible on commit.

func (Store) Table

func (s Store) Table() string

Table returns the schema-qualified table identifier.

type UndeliveredError added in v1.3.0

type UndeliveredError struct {
	IDs []string // sorted, canonical
}

UndeliveredError names rows that ended dead or discarded: they will not be published unless requeued, so waiting for them cannot succeed.

func (*UndeliveredError) Error added in v1.3.0

func (e *UndeliveredError) Error() string

func (*UndeliveredError) Is added in v1.3.0

func (e *UndeliveredError) Is(target error) bool

Is makes errors.Is(err, ErrUndelivered) true.

type Waiters added in v1.3.0

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

Waiters resolves WaitPublished calls. A call registers its ids, then learns their outcome from done notifications (no query) or from a shared recheck. The recheck runs at most once per interval for all waiting ids together, so its load does not grow with the number of waiters; it covers notifications that never arrive (listener reconnect, no listener, LISTEN disabled).

func NewWaiters added in v1.3.0

func NewWaiters(schema string, read stateReader, interval time.Duration) *Waiters

NewWaiters builds the waiter registry for one schema. interval paces the shared recheck.

func (*Waiters) Notify added in v1.3.0

func (w *Waiters) Notify(payload string)

Notify applies one done notification. Notifications for another schema or malformed ones are ignored.

func (*Waiters) Wait added in v1.3.0

func (w *Waiters) Wait(ctx context.Context, ids []string) error

Wait blocks until every id is delivered, one ends undelivered, or ctx ends. ids must be canonical (CanonicalIDs).

Jump to

Keyboard shortcuts

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