port

package
v1.1.1 Latest Latest
Warning

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

Go to latest
Published: Nov 1, 2026 License: MIT Imports: 7 Imported by: 0

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

View Source
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

func Abort(err error) error

Abort stops the relay without completing, retrying or dead-lettering the batch.

func Discard added in v1.1.0

func Discard(reason error) error

Discard completes a batch without publication or dead-lettering.

func Permanent added in v1.1.0

func Permanent(err error) error

Permanent marks a batch as terminally failed without further retries.

func RetryAfter added in v1.1.0

func RetryAfter(err error, delay time.Duration) error

RetryAfter requests a minimum retry delay for the batch.

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

func (NoopHooks) OnCleanup

func (NoopHooks) OnCleanup(context.Context, int)

func (NoopHooks) OnDead

func (NoopHooks) OnFailed

func (NoopHooks) OnPublished

func (NoopHooks) OnPublished(context.Context, []message.Message)

type PanicError added in v1.1.1

type PanicError struct {
	Value any
	Stack []byte
}

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

type Publisher interface {
	Publish(ctx context.Context, msgs []message.Message) error
}

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, Discard and Abort control the outcome of the entire batch; 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

type RetryAfterError struct {
	Err   error
	Delay time.Duration
}

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

Jump to

Keyboard shortcuts

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