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 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 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 ¶
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 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.