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 MessageContext(ctx context.Context, m message.Message) context.Context
- func PerMessage(outcomes map[string]error, others error) error
- func Permanent(err error) error
- func RetryAfter(err error, delay time.Duration) error
- func Settle(ctx context.Context, m message.Message, outcome error) error
- func WithMessageContexts(ctx context.Context, byID map[string]context.Context) context.Context
- func WithMessageTimeouts(ctx context.Context, byID map[string]context.Context, timeout time.Duration) (_ context.Context, release func())
- func WithSettler(ctx context.Context, s Settler) context.Context
- type AbortError
- type BatchError
- type Codec
- type DiscardError
- type DiscardHooks
- type Executor
- type Hooks
- type Instrumentation
- type NoopHooks
- type NoopInstrumentation
- type Outcome
- type PanicError
- type PermanentError
- type Publisher
- type RetryAfterError
- type Settler
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNotSettling is returned by Settle outside a relay Publish call, or // after that call returned. ErrNotSettling = errors.New("outbox: Settle outside a relay Publish call") // ErrUnknownMessage is returned by Settle for a message not in the batch. ErrUnknownMessage = errors.New("outbox: Settle for a message not in this batch") // ErrAlreadySettled is returned by a second Settle for the same message. ErrAlreadySettled = errors.New("outbox: message already settled") )
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 MessageContext ¶ added in v1.4.0
MessageContext returns the context Instrumentation.Deliver opened for m, with m's publish budget when the relay sets one, or ctx itself when there is none. A Publisher that sends messages one by one uses it for each message, right when it starts sending it, so the transport client continues m's delivery and m gets its own deadline.
func PerMessage ¶ added in v1.2.0
PerMessage settles each message by its own outcome; messages missing from outcomes take others (nil publishes them).
func Permanent ¶ added in v1.1.0
Permanent marks a batch as terminally failed without further retries.
func RetryAfter ¶ added in v1.1.0
RetryAfter requests a minimum retry delay for the batch.
func Settle ¶ added in v1.5.0
Settle reports the outcome of message m as soon as it is known, while the rest of the batch is still being published: nil means published; any other outcome is read exactly like a PerMessage entry (Permanent, Discard, RetryAfter, a plain error that retries). The relay commits it right away (group-committed with other early outcomes), so the row stops holding its partition and the next row of that partition can be claimed by another worker. A fatal outcome (Abort, or one WithFatal accepts) leaves the row claimed and stops the relay once Publish returns.
Messages a publisher does not settle take the outcome Publish returns, as before. ctx must be the Publish context (or derived from it, such as MessageContext); m is identified by Message.ID.
func WithMessageContexts ¶ added in v1.4.0
WithMessageContexts returns ctx carrying the per-message contexts the relay opened with Instrumentation.Deliver, keyed by message id.
func WithMessageTimeouts ¶ added in v1.7.0
func WithMessageTimeouts( ctx context.Context, byID map[string]context.Context, timeout time.Duration, ) (_ context.Context, release func())
WithMessageTimeouts is WithMessageContexts with a publish budget for each message: the context MessageContext returns for a message ends timeout after the publisher first asks for it, so a slow message never eats the budget of the ones sent after it. A zero timeout adds no deadline. release stops the timers; call it once Publish has returned.
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 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 cancellation still applies) and an end func the relay calls exactly once with the message's Outcome, on every exit path. The relay then runs Capture on that context and lays the result over the headers of the copy handed to Publish (these entries win; the stored row is unchanged), so a transport mapping Message.Headers carries the delivery on.
type NoopHooks ¶
type NoopHooks struct{}
NoopHooks is the default Hooks implementation; every method is a no-op.
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.
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
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. The Publish context has no deadline (it ends on cancellation only): a message's publish budget is on MessageContext(ctx, m), which a publisher waits on to bound one message.
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