Documentation
¶
Overview ¶
Package engine implements the outbox background machinery: the store (enqueue/claim/mark/cleanup queries) and the relay and cleaner workers.
Index ¶
Constants ¶
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.
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 ¶
var ErrInvalidID = errors.New("outbox: message id is not a uuid")
ErrInvalidID is returned for an id that is not a uuid.
var ErrOutcomeUnknown = errors.New("outbox: delivery outcome unknown")
ErrOutcomeUnknown matches an UnknownOutcomeError through errors.Is.
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
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 ¶
NewCleaner builds a Cleaner.
type Relay ¶
type Relay struct {
// contains filtered or unexported fields
}
Relay claims ready rows, publishes them, and records the outcome.
func NewRelay ¶
NewRelay builds a Relay. Its LISTEN connection also feeds done notifications to waiters.
func (*Relay) Run ¶
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 ¶
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
DeliveryState returns the status of every listed row that exists. ids must be canonical uuids; what an absent row means is Verdict's call. It reads through the relay executor, never the caller's transaction, and only by primary key.
func (Store) Enqueue ¶
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.
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 UnknownOutcomeError ¶ added in v1.5.1
type UnknownOutcomeError struct {
IDs []string // sorted, canonical
}
UnknownOutcomeError names rows that are gone while the cleaner also removes dead or discarded rows: a missing row may have been published or refused, and nothing left tells which.
func (*UnknownOutcomeError) Error ¶ added in v1.5.1
func (e *UnknownOutcomeError) Error() string
func (*UnknownOutcomeError) Is ¶ added in v1.5.1
func (e *UnknownOutcomeError) Is(target error) bool
Is makes errors.Is(err, ErrOutcomeUnknown) 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, refusalsCollected bool) *Waiters
NewWaiters builds the waiter registry for one schema. interval paces the shared recheck; refusalsCollected tells whether the cleaner removes dead or discarded rows (see settled).