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 GoneRule ¶ added in v1.6.0
type GoneRule struct {
// contains filtered or unexported fields
}
GoneRule decides what an id with neither a row nor a tombstone means.
When the cleaner never removes refused rows, only a published row can be gone: delivered. When it does, a removed refusal leaves a tombstone kept for TombstoneRetention, so for a refusal to have left no trace it must have finished more than (refusal retention + tombstone retention) ago. A UUIDv7 id carries its creation time, and a message created after that horizon cannot be such a refusal: delivered, exactly. Any other gone id (older, or not a UUIDv7) is unknown.
func NewGoneRule ¶ added in v1.6.0
NewGoneRule derives the rule from the outbox settings.
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, or, for a removed dead/discarded row, its tombstone's status (a live row wins). ids must be canonical uuids; what a gone id 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
NewWaiters builds the waiter registry for one schema. interval paces the shared recheck; gone decides what an id with no trace means.