Documentation
¶
Overview ¶
Package port defines the pluggable integration interfaces of the outbox: the transport Publisher, the value Codec, observability Hooks, and the database Executor.
Index ¶
- Variables
- func Abort(err error) error
- func Discard(reason error) error
- func PerMessage(outcomes map[string]error, others error) error
- func Permanent(err error) error
- func RetryAfter(err error, delay time.Duration) error
- type AbortError
- type BatchError
- type Codec
- type DiscardError
- type DiscardHooks
- type Executor
- type Hooks
- type NoopHooks
- type PanicError
- type PermanentError
- type Publisher
- type RetryAfterError
Constants ¶
This section is empty.
Variables ¶
var ErrLeaseLost = errors.New("outbox: lease lost")
ErrLeaseLost means the claim expired or no longer belongs to this attempt. It does not say whether the external side effect occurred.
Functions ¶
func Abort ¶ added in v1.1.1
Abort stops the relay without completing, retrying or dead-lettering the batch.
func PerMessage ¶ added in v1.2.0
PerMessage settles each message by its own outcome; messages missing from outcomes take others (nil publishes them).
Types ¶
type AbortError ¶ added in v1.1.1
type AbortError struct{ Err error }
AbortError stops the relay: Run returns it and the claimed batch is left untouched under its lease, so another instance or a restart re-claims it after expiry. It takes precedence over every other outcome. Use Abort to construct one. It supports errors.Is and errors.As.
func (*AbortError) Error ¶ added in v1.1.1
func (e *AbortError) Error() string
func (*AbortError) Unwrap ¶ added in v1.1.1
func (e *AbortError) Unwrap() error
type BatchError ¶ added in v1.2.0
BatchError gives each message of a batch its own outcome, keyed by Message.ID. A nil value means published; a non-nil value is settled exactly like a whole-batch error (Permanent, Discard, RetryAfter, or a plain error that retries with backoff). Messages without an entry take Err as their outcome, so a nil Err publishes them. IDs outside the batch are ignored. Abort anywhere in it stops the relay with the batch left claimed. Use PerMessage to construct one. It supports errors.Is and errors.As over Err and every outcome.
func (*BatchError) Error ¶ added in v1.2.0
func (e *BatchError) Error() string
func (*BatchError) Unwrap ¶ added in v1.2.0
func (e *BatchError) Unwrap() []error
type Codec ¶
type Codec interface {
Marshal(v any) (payload []byte, contentType string, err error)
Unmarshal(payload []byte, v any) error
}
Codec marshals a value to bytes for storage and back. Concrete codecs (JSON, protobuf, …) ship separately; the core only defines the interface.
type DiscardError ¶ added in v1.1.0
type DiscardError struct{ Err error }
DiscardError completes the batch without publishing or dead-lettering it. The application, not the outbox, decides when this is appropriate.
func (*DiscardError) Error ¶ added in v1.1.0
func (e *DiscardError) Error() string
func (*DiscardError) Unwrap ¶ added in v1.1.0
func (e *DiscardError) Unwrap() error
type DiscardHooks ¶ added in v1.1.0
type DiscardHooks interface {
OnDiscarded(ctx context.Context, msgs []message.Message, reason error)
}
DiscardHooks is an optional extension of Hooks. It observes a committed discard; applications can implement it without changing existing Hooks.
type Executor ¶
type Executor interface {
Exec(ctx context.Context, sql string, args ...any) (pgconn.CommandTag, error)
Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)
QueryRow(ctx context.Context, sql string, args ...any) pgx.Row
}
Executor is the pgx query surface the outbox needs. It is intentionally the common subset of *pgxpool.Pool, pgx.Tx, *pgx.Conn and pgtx's tx.DB — so any of them satisfies it, and you can plug your own implementation to control pooling, statement routing, retries or instrumentation.
Two executors are supplied to the outbox:
- the relay executor runs the background claim/mark/cleanup queries; it must NOT be bound to a business transaction.
- the enqueue executor runs the transactional INSERT; pass one that resolves the caller's transaction from the context (e.g. pgtx's tx.DB) so messages are written atomically with business data.
type Hooks ¶
type Hooks interface {
OnPublished(ctx context.Context, msgs []message.Message)
OnFailed(ctx context.Context, msg message.Message, err error)
OnDead(ctx context.Context, msg message.Message)
OnCleanup(ctx context.Context, deleted int)
}
Hooks observes relay activity. Implement it to wire metrics/tracing. All methods must be non-blocking and must not panic.
type NoopHooks ¶
type NoopHooks struct{}
NoopHooks is the default Hooks implementation; every method is a no-op.
type PanicError ¶ added in v1.1.1
PanicError is a panic recovered inside the relay (publisher, hooks, executor). It is always fatal: Run returns it like an AbortError.
func (*PanicError) Error ¶ added in v1.1.1
func (e *PanicError) Error() string
func (*PanicError) Unwrap ¶ added in v1.1.1
func (e *PanicError) Unwrap() error
Unwrap exposes a panicked error value to errors.Is and errors.As.
type PermanentError ¶ added in v1.1.0
type PermanentError struct{ Err error }
PermanentError stops retries and moves the batch to the dead state. Use Permanent to construct one. It supports errors.Is and errors.As.
func (*PermanentError) Error ¶ added in v1.1.0
func (e *PermanentError) Error() string
func (*PermanentError) Unwrap ¶ added in v1.1.0
func (e *PermanentError) Unwrap() error
type Publisher ¶
Publisher delivers a batch of claimed messages to a transport. It is the only integration point a transport adapter must implement.
A non-nil error fails the whole batch: every message is retried (or dead-lettered) per the relay's policy. Because delivery is at-least-once and a retried batch is re-published in full, consumers must deduplicate. Permanent, RetryAfter, Discard and Abort control the outcome of the entire batch; PerMessage gives each message its own outcome. A panic is recovered and stops the relay like Abort. Publish must honor context cancellation; claims are renewed while it runs.
type RetryAfterError ¶ added in v1.1.0
RetryAfterError requests a minimum delay before another attempt. The relay uses the greater of Delay and its configured backoff, subject to MaxAttempts.
func (*RetryAfterError) Error ¶ added in v1.1.0
func (e *RetryAfterError) Error() string
func (*RetryAfterError) Unwrap ¶ added in v1.1.0
func (e *RetryAfterError) Unwrap() error