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 ¶
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 ¶
Types ¶
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 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 partial-success batch is re-published in full, consumers must deduplicate. For strict per-message isolation, run the relay with batch size 1. Permanent, RetryAfter and Discard control the outcome of the entire batch. 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