outbox

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package outbox is the transactional outbox for any workflow.Client: an app writes a job inside its own database transaction, and a Relay enqueues it on the target client (Hatchet, memory, a middleware-wrapped client, a sqlstore client in another database) after the transaction commits. A rolled-back transaction leaves nothing to relay, so a job is enqueued if and only if the app's writes committed.

ob, _ := outbox.New(db, sqlb.PostgresDialect{})
_ = ob.Migrate(ctx)                       // explicit, versioned
tx, _ := db.BeginTx(ctx, nil)
// ... the app's own writes in tx ...
_, _ = ob.Write(ctx, tx, workflow.Job{Workflow: "ship", Payload: p})
_ = tx.Commit()

relay, _ := ob.NewRelay(hatchetClient)
_ = relay.Start(ctx)                      // nothing runs before this
relay.Notify()                            // optional: relay now, not at the next poll

An app whose queue is the same SQL database does not need this package: sqlstore.Client.EnqueueTx writes the run itself inside the transaction.

Delivery

Delivery is at least once. A relay claims a batch of due entries under a lease (FOR UPDATE SKIP LOCKED on Postgres and MySQL, one conditional UPDATE on SQLite, so any number of relays over one table never claim one entry at once), enqueues each in table order and deletes it once the target accepted it. A relay that dies after the target accepted an entry but before the delete leaves it to be enqueued again once the lease expires. Each enqueue carries an idempotency key, the job's own when it has one and the entry's ID otherwise, so a target that honours keys (CapIdempotencyKey, under a workflow policy other than IdempotencyOff) drops the second enqueue while the first run has not finished; a run that already finished runs twice. Handlers must be idempotent, as for any queue. NewRelay refuses a target without CapIdempotencyKey, because it would refuse every keyed entry; AllowDuplicates accepts one, sending only the job's own key, and names the trade-off: a redelivered entry then always runs twice.

Order is table order within one relay pass; across relays, and after a failed entry is retried, there is no order.

A failed enqueue is retried with backoff (WithBackoff, default 1s doubling to 5m). WithMaxAttempts moves an entry that keeps failing to the dead status; the default retries forever, because a failure is most often the target being down or a workflow not yet registered during a deploy. A dead entry is reported to the relay's WithOnDead hook (for an alert), listed by Outbox.ListDead (paged, oldest first, optionally per workflow) and sent again by Outbox.Requeue, which keeps its ID and so its idempotency key.

Enqueue middleware on the target runs at relay time, after the commit, which is why this is the way to combine a transactional enqueue with middleware (unique, debounce, tracing).

Time

Due times, backoff and leases come from WithClock (default clock.Real), and so does the poll timer. Times are stored as BIGINT Unix nanoseconds.

Schema

Migrate creates the outbox table through sqlb's contrib/migrate ledger, under its own owner (ubgo/workflow/sqlstore/outbox) in the ledger table <prefix>migrations: the same ledger and migration lock sqlstore uses for the same prefix, but its own list of numbered migrations, because an app relaying to Hatchet has no sqlstore tables and must not get them. A database a newer release migrated is refused (ErrSchemaTooNew). MigrationScripts returns the same migrations as SQL text for teams that apply DDL with their own tool; Write and relays need only the table.

WithTablePrefix names the table ("wf_" by default); on Postgres, WithSchema puts it in a schema of its own (the ledger then stays in the search_path, its rows owned as "<owner>@<schema>"). WithIDGenerator replaces the entry ID format ("obx_<32 hex>"); the ID is also the default idempotency key, so it must be unique.

Index

Constants

View Source
const MigrationOwner = "ubgo/workflow/sqlstore/outbox"

MigrationOwner is the ledger owner of the outbox's migrations, distinct from sqlstore's, so the two keep separate histories in one ledger table. Under WithSchema the recorded owner is "<MigrationOwner>@<schema>".

Variables

View Source
var ErrSchemaTooNew = errors.New("outbox: the database schema is newer than this code")

ErrSchemaTooNew means the ledger records an outbox migration this code does not know: a newer release migrated the database.

Functions

func DefaultIDGenerator

func DefaultIDGenerator() (string, error)

DefaultIDGenerator returns "obx_" and 16 random bytes in hex.

Types

type DeadEntry

type DeadEntry struct {
	// ID is the entry's ID, which Requeue takes.
	ID string
	// Job is the job as written. Its IdempotencyKey is the job's own; the
	// entry ID the relay adds when it has none is not filled in.
	Job workflow.Job
	// Attempts is how many enqueues failed.
	Attempts int
	// LastErr is the text of the last enqueue error.
	LastErr string
	// CreatedAt is when Write added the entry.
	CreatedAt time.Time
}

DeadEntry is an entry that failed WithMaxAttempts enqueues and is no longer relayed, as ListDead and a DeadFunc see it.

type DeadFunc

type DeadFunc func(ctx context.Context, e DeadEntry, cause error)

DeadFunc is told about an entry the moment it goes dead (WithMaxAttempts failed enqueues), with the last enqueue error, after the dead status is written. It runs on the relay's goroutine, so it should hand slow work (paging, a ticket) off rather than block the relay. ctx is not cancelled by Stop.

type DeadQuery

type DeadQuery struct {
	// Workflow keeps only entries for this workflow; empty keeps all.
	Workflow string
	// After continues a listing after the entry with this ID (the last ID
	// of the previous page); empty starts at the oldest.
	After string
	// Limit is the page size: zero means 100; it is capped at 1000.
	Limit int
}

DeadQuery selects a page of dead entries, oldest first.

type IDGenerator

type IDGenerator func() (string, error)

IDGenerator returns a new entry ID. The ID is also the idempotency key the relay sends for a job without its own, so it must be unique across every writer of the table; a duplicate fails Write. An ID is 1 to 64 bytes; Write refuses anything else, and fails when the generator returns an error, so a broken generator writes nothing.

type MigrationScript

type MigrationScript struct {
	Owner, Name string
	Statements  []string
}

MigrationScript is one outbox migration as SQL text: the exact statements Migrate runs, in order, with the table name resolved for the options' prefix and schema. Owner and Name are what Migrate records in its ledger.

func MigrationScripts

func MigrationScripts(d sqlb.Dialect, opts ...Option) ([]MigrationScript, error)

MigrationScripts returns every migration Outbox.Migrate applies, in order, as SQL text for dialect d and the table options among opts (WithTablePrefix, WithSchema), for teams whose DDL goes through goose, Atlas, Flyway, Liquibase or a DBA review. The text is frozen per release as Migrate's is, and each statement is safe to run twice. Write and relays never read the ledger, so a table applied this way works as is, and a later Migrate re-runs each script (a no-op) and records it.

type Option

type Option func(*Outbox)

Option configures an Outbox.

func WithClock

func WithClock(c clock.Clock) Option

WithClock sets the time source of due times, backoff, leases and the relay's poll timer. The default is clock.Real.

func WithIDGenerator

func WithIDGenerator(g IDGenerator) Option

WithIDGenerator sets how entry IDs are made (default DefaultIDGenerator), for time-sortable IDs (UUIDv7, ULID) or IDs that line up with the app's own. A nil generator is ignored.

func WithLogger

func WithLogger(l *slog.Logger) Option

WithLogger sets where relays report what they cannot return to a caller (a failed enqueue, a dead entry). The default discards.

func WithSchema

func WithSchema(name string) Option

WithSchema puts the outbox table in the named Postgres schema, as sqlstore.WithSchema does: the schema must exist and match the prefix pattern; New refuses it on SQLite and MySQL. The migration ledger stays in the connection's search_path, its rows owned as "<MigrationOwner>@<schema>".

func WithTablePrefix

func WithTablePrefix(p string) Option

WithTablePrefix sets the prefix of the outbox and ledger table names (default "wf_"). It must match ^[a-z][a-z0-9_]{0,30}$.

type Outbox

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

Outbox is one outbox table. Write adds entries inside the app's transactions; NewRelay builds the relays that move them to a client. It holds no state of its own: every entry is a row.

func New

func New(db *sql.DB, d sqlb.Dialect, opts ...Option) (*Outbox, error)

New returns the outbox over db, whose SQL is written for d (sqlb's Postgres, SQLite or MySQL dialect). It opens nothing and starts nothing.

func (*Outbox) ListDead

func (o *Outbox) ListDead(ctx context.Context, q DeadQuery) ([]DeadEntry, error)

ListDead returns a page of dead entries, oldest first, for an operator screen, an alert or a replay script. An After that names no dead entry returns ErrNotFound rather than restarting from the beginning.

func (*Outbox) Migrate

func (o *Outbox) Migrate(ctx context.Context) error

Migrate brings the outbox table up to this code's version, under the engine's migration lock, so concurrent calls are safe. It refuses a database a newer release migrated (ErrSchemaTooNew) and never drops anything. Write and relays never migrate: running it is the deploy's decision.

func (*Outbox) NewRelay

func (o *Outbox) NewRelay(target workflow.Client, opts ...RelayOption) (*Relay, error)

NewRelay returns a relay that enqueues this outbox's entries on target. It refuses, with an UnsupportedError, a target without CapIdempotencyKey unless AllowDuplicates is given: the relay's duplicate protection is the key it sends with every enqueue.

func (*Outbox) Requeue

func (o *Outbox) Requeue(ctx context.Context, id string) error

Requeue makes a dead entry pending again with a fresh attempt count, due at once, so the next relay pass sends it (call Relay.Notify to send it now). It keeps the entry's ID, so the idempotency key the relay sends is the same as before. An id that names no dead entry returns ErrNotFound.

func (*Outbox) Write

func (o *Outbox) Write(ctx context.Context, tx *sql.Tx, job workflow.Job) (string, error)

Write adds job to the outbox inside the app's transaction tx and returns the entry's ID, which is also the idempotency key the relay sends when the job has none. The entry exists only if tx commits. tx must be open on the database the outbox lives in. Nothing about the target is checked here (the outbox does not know it); a job the target refuses is retried with backoff, then dead after WithMaxAttempts.

type Relay

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

Relay moves committed outbox entries to a target client. Build it with Outbox.NewRelay; nothing runs until Start, and Flush relays once without starting anything (for an app that drives relaying from its own scheduler, or right after a commit). Any number of relays, in any number of processes, may share one outbox table.

func (*Relay) Flush

func (r *Relay) Flush(ctx context.Context) (int, error)

Flush relays every entry due now and returns how many the target accepted. It claims a batch at a time until a batch comes back short or delivers nothing, so entries failing with no backoff cannot keep it looping. An error is a database failure; a target failure is recorded on the entry and retried later, not returned.

func (*Relay) Notify

func (r *Relay) Notify()

Notify wakes the loop to relay now rather than at its next poll: call it after committing a transaction that wrote to the outbox. It never blocks.

func (*Relay) Start

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

Start runs the relay loop until ctx ends or Stop is called. It does not block, and it does not migrate (Outbox.Migrate does).

func (*Relay) Stop

func (r *Relay) Stop()

Stop ends the loop and waits for it. Entries it had claimed but not yet enqueued are released for any relay at once. Safe to call more than once, and before Start.

type RelayOption

type RelayOption func(*Relay)

RelayOption configures a Relay.

func AllowDuplicates

func AllowDuplicates() RelayOption

AllowDuplicates lets NewRelay accept a target without CapIdempotencyKey, accepting the trade-off it names: delivery stays at least once, but nothing drops the second enqueue of an entry, so an entry whose relay died after the target accepted it, or whose delete failed, runs twice. The relay then sends the job's own idempotency key only (none when the job has none), since such a target refuses keyed jobs. Without this option NewRelay refuses such a target, because every entry would otherwise be refused at enqueue time and go dead.

func WithBackoff

func WithBackoff(b workflow.Backoff) RelayOption

WithBackoff sets the wait before an entry is tried again after its n-th failed enqueue (Backoff.Delay(n)).

func WithBatchSize

func WithBatchSize(n int) RelayOption

WithBatchSize sets how many entries one claim takes. Values below 1 are ignored.

func WithEnqueueTimeout

func WithEnqueueTimeout(d time.Duration) RelayOption

WithEnqueueTimeout bounds one enqueue on the target. Values of zero or less are ignored.

func WithLease

func WithLease(d time.Duration) RelayOption

WithLease sets how long a claimed batch stays claimed. It must exceed the enqueue timeout: NewRelay refuses otherwise. Values of zero or less are ignored.

func WithMaxAttempts

func WithMaxAttempts(n int) RelayOption

WithMaxAttempts moves an entry to the dead status after n failed enqueues. Zero (the default) retries forever.

func WithOnDead

func WithOnDead(fn DeadFunc) RelayOption

WithOnDead sets the hook told about each entry that goes dead, for alerting or moving it elsewhere; ListDead and Requeue are the read and replay side. A nil hook is ignored; without one, dead entries are logged.

func WithPollInterval

func WithPollInterval(d time.Duration) RelayOption

WithPollInterval sets how often an idle relay looks for entries. Values of zero or less are ignored.

Jump to

Keyboard shortcuts

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