Documentation
¶
Overview ¶
Package config holds the outbox runtime settings, the functional options that build them, and the declarative Config struct (mapstructure/validate/default tags) for loading from files or environment.
Index ¶
- Constants
- Variables
- func ValidSchema(s string) bool
- type Config
- type Option
- func WithBatchSize(n int) Option
- func WithCleanupInterval(d time.Duration) Option
- func WithClearPayloadOnComplete(enabled bool) Option
- func WithCodec(c port.Codec) Option
- func WithConcurrency(n int) Option
- func WithConfig(c Config) Option
- func WithDeadRetention(ttl time.Duration) Option
- func WithDiscardRetention(ttl time.Duration) Option
- func WithErrorRenderer(render func(error) string) Option
- func WithFatal(f func(error) bool) Option
- func WithHooks(h port.Hooks) Option
- func WithInstanceID(id string) Option
- func WithInstrumentation(i port.Instrumentation) Option
- func WithLeaseDuration(d time.Duration) Option
- func WithListenPool(p *pgxpool.Pool) Option
- func WithLogger(l *slog.Logger) Option
- func WithMaxAttempts(n int) Option
- func WithOrdered(v bool) Option
- func WithPollInterval(d time.Duration) Option
- func WithPublishTimeout(d time.Duration) Option
- func WithRetention(ttl time.Duration) Option
- func WithRetryBackoff(b backoff.Backoff) Option
- func WithSchema(schema string) Option
- func WithSettleLinger(d time.Duration) Option
- func WithTombstoneRetention(d time.Duration) Option
- func WithWaitRecheck(d time.Duration) Option
- func WithoutNotify() Option
- type Settings
Constants ¶
const DefaultCleanupInterval = time.Minute
DefaultCleanupInterval is how often the cleaner runs when a retention is set and no WithCleanupInterval is given.
Variables ¶
var ErrInvalidSchema = errors.New("outbox: invalid schema identifier")
ErrInvalidSchema is returned when the schema is not a valid identifier.
Functions ¶
func ValidSchema ¶
ValidSchema reports whether s is a safe schema identifier.
Types ¶
type Config ¶
type Config struct {
Schema string `mapstructure:"schema" default:"public"`
PollInterval time.Duration `mapstructure:"poll_interval" default:"1s"`
BatchSize int `mapstructure:"batch_size" default:"100"`
LeaseDuration time.Duration `mapstructure:"lease_duration" default:"30s"`
Concurrency int `mapstructure:"concurrency" default:"1"`
MaxAttempts int `mapstructure:"max_attempts" default:"10"`
Retention time.Duration `mapstructure:"retention"`
DeadRetention time.Duration `mapstructure:"dead_retention"`
DiscardRetention time.Duration `mapstructure:"discard_retention"`
ClearPayloadOnComplete bool `mapstructure:"clear_payload_on_complete"`
PublishTimeout time.Duration `mapstructure:"publish_timeout"`
CleanupInterval time.Duration `mapstructure:"cleanup_interval"`
Ordered bool `mapstructure:"ordered"`
// DisableNotify turns LISTEN/NOTIFY off (poll-only). The zero value keeps
// NOTIFY enabled, so a hand-built Config does not silently disable it.
DisableNotify bool `mapstructure:"disable_notify"`
// WaitRecheck paces the shared state read behind WaitPublished.
WaitRecheck time.Duration `mapstructure:"wait_recheck" default:"1s"`
// SettleLinger is the group-commit window for early outcomes (Settle).
SettleLinger time.Duration `mapstructure:"settle_linger" default:"1ms"`
// TombstoneRetention keeps the outcome of removed dead/discarded rows.
TombstoneRetention time.Duration `mapstructure:"tombstone_retention" default:"720h"`
}
Config is the declarative outbox configuration, loaded from a file or environment (mapstructure) with validation and defaults. It mirrors the functional options; the logger is injected separately via WithLogger because it is a runtime dependency, not configuration data.
type Option ¶
type Option func(*Settings)
Option configures Settings.
func WithBatchSize ¶
WithBatchSize sets the max rows claimed per cycle (default 100).
func WithCleanupInterval ¶
WithCleanupInterval sets how often the cleaner runs (default DefaultCleanupInterval once any retention is set; no retention, no cleaner).
func WithClearPayloadOnComplete ¶ added in v1.1.0
WithClearPayloadOnComplete atomically empties payload and headers when a row becomes published or discarded. Dead rows retain data for inspection/replay. Other columns (including LastError) are retained; callers must sanitize them.
func WithConcurrency ¶
WithConcurrency sets the number of relay worker goroutines (default 1).
func WithConfig ¶
WithConfig applies a declarative Config onto the settings. Apply it before any narrower Option you want to win.
func WithDeadRetention ¶ added in v1.1.0
WithDeadRetention enables deletion of dead rows after this terminal-state age. Disabled by default. Each removed row leaves a tombstone (WithTombstoneRetention).
func WithDiscardRetention ¶ added in v1.1.0
WithDiscardRetention enables deletion of discarded rows after this age. Disabled by default. Each removed row leaves a tombstone (WithTombstoneRetention).
func WithErrorRenderer ¶ added in v1.5.3
WithErrorRenderer renders a failed publish's error before it is stored as the row's last_error (default err.Error()). Pass the renderer the service's logger and tracer use (xlog.NewErrorRenderer), so signed URLs or database values never land in the table.
func WithFatal ¶ added in v1.1.1
WithFatal sets the classifier consulted on every Publish error and every internal relay/cleaner error (claim, renew, completion, cleanup) while the context is live. When it returns true, Run stops and returns the error; the claimed batch is not completed, retried or dead-lettered and is re-claimed after its lease expires. Abort outcomes and recovered panics are always fatal. Default: nothing else is fatal.
func WithInstanceID ¶
WithInstanceID sets the lease owner id (locked_by). Required before Run. Must be unique and stable per process (e.g. the Kubernetes pod name).
func WithInstrumentation ¶ added in v1.4.0
func WithInstrumentation(i port.Instrumentation) Option
WithInstrumentation plugs telemetry into Enqueue and delivery (default NoopInstrumentation). See port.Instrumentation.
func WithLeaseDuration ¶
WithLeaseDuration sets how long a claimed row stays locked (default 30s).
func WithListenPool ¶
WithListenPool supplies the *pgxpool.Pool used for LISTEN/NOTIFY wake-ups. Without it (and unless the relay executor is itself a *pgxpool.Pool), the relay falls back to polling only.
func WithLogger ¶
WithLogger injects the slog logger from outside (default a no-op logger that discards everything).
func WithMaxAttempts ¶
WithMaxAttempts sets the default attempt ceiling before dead-lettering (default 10).
func WithOrdered ¶
WithOrdered enables strict per-partition_key ordering.
func WithPollInterval ¶
WithPollInterval sets how often the relay polls when idle (default 1s).
func WithPublishTimeout ¶ added in v1.1.0
WithPublishTimeout limits each Publish call. Zero disables the timeout. Publishers must honor the supplied context; a timeout cannot undo a side effect.
func WithRetention ¶
WithRetention enables cleanup of published rows older than ttl.
func WithRetryBackoff ¶
WithRetryBackoff overrides the retry backoff (default backoff.Default).
func WithSchema ¶
WithSchema sets the Postgres schema the table lives in (default "public").
func WithSettleLinger ¶ added in v1.5.0
WithSettleLinger sets the group-commit window for outcomes reported early with Settle (default 1ms): reports within it, or before Publish returns, commit in one statement. It bounds how much later than its report a row is released.
func WithTombstoneRetention ¶ added in v1.6.0
WithTombstoneRetention sets how long the outcome of a removed dead or discarded row is kept (default 30 days): a compact id + status, no payload. Within it Published/WaitPublished stay exact; see the outbox docs for the horizon.
func WithWaitRecheck ¶ added in v1.3.0
WithWaitRecheck sets how often WaitPublished re-reads row state when no notification settled it (default 1s): one query per interval for all waiting calls, covering a lost notification, a reconnecting listener, or a process that does not Run this Outbox or has no LISTEN pool.
func WithoutNotify ¶
func WithoutNotify() Option
WithoutNotify disables LISTEN/NOTIFY wake-ups (poll-only).
type Settings ¶
type Settings struct {
InstanceID string
Schema string
PollInterval time.Duration
BatchSize int
LeaseDuration time.Duration
Concurrency int
MaxAttempts int
Backoff backoff.Backoff
Retention time.Duration
DeadRetention time.Duration
DiscardRetention time.Duration
ClearPayloadOnComplete bool
PublishTimeout time.Duration
CleanupInterval time.Duration
Ordered bool
Notify bool
WaitRecheck time.Duration
SettleLinger time.Duration
TombstoneRetention time.Duration
ListenPool *pgxpool.Pool
Fatal func(error) bool
Hooks port.Hooks
Instrumentation port.Instrumentation
ErrorRenderer func(error) string
Codec port.Codec
Logger *slog.Logger
}
Settings is the resolved runtime configuration the engine reads. Build it with Default plus Options, or from a declarative Config via WithConfig.