port

package
v1.4.1 Latest Latest
Warning

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

Go to latest
Published: Nov 13, 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 MessageContext added in v1.4.0

func MessageContext(ctx context.Context, m message.Message) context.Context

MessageContext returns the context Instrumentation.Deliver opened for m, or ctx itself when there is none. A Publisher that sends messages one by one uses it so the transport client continues m's delivery.

func PerMessage added in v1.2.0

func PerMessage(outcomes map[string]error, others error) error

PerMessage settles each message by its own outcome; messages missing from outcomes take others (nil publishes them).

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.

func WithMessageContexts added in v1.4.0

func WithMessageContexts(ctx context.Context, byID map[string]context.Context) context.Context

WithMessageContexts returns ctx carrying the per-message contexts the relay opened with Instrumentation.Deliver, keyed by message id.

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

type BatchError struct {
	Outcomes map[string]error
	Err      error
}

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 Instrumentation added in v1.4.0

type Instrumentation interface {
	Capture(ctx context.Context, headers map[string]string)
	Deliver(ctx context.Context, m message.Message) (context.Context, func(Outcome))
}

Instrumentation plugs telemetry into the outbox at its two ends.

Capture runs at Enqueue, in the caller's context, before the insert. It fills headers, a fresh map merged into the message's headers afterwards: they are the only state it can carry to the relay, and they travel to the transport. Entries the caller set win over entries under the same key.

Deliver runs in the relay for each claimed message just before Publish. It returns the context to publish that message with (derived from ctx, so the publish deadline and cancellation still apply) and an end func the relay calls exactly once with the message's Outcome, on every exit path.

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 NoopInstrumentation added in v1.4.0

type NoopInstrumentation struct{}

NoopInstrumentation is the default Instrumentation: it adds no headers and publishes every message with the batch context.

func (NoopInstrumentation) Capture added in v1.4.0

Capture adds nothing.

func (NoopInstrumentation) Deliver added in v1.4.0

Deliver returns ctx and an end func that does nothing.

type Outcome added in v1.4.0

type Outcome struct {
	// Status is the status the attempt committed: published, pending (a
	// retry is scheduled), dead or discarded; processing when the attempt
	// left the row claimed (abort, panic, lost lease, failed completion).
	Status message.Status
	// Err is the publish error or the cause; nil when published.
	Err error
}

Outcome is what became of one delivery attempt.

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

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