queue

package
v0.20.0 Latest Latest
Warning

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

Go to latest
Published: Oct 16, 2026 License: MIT Imports: 8 Imported by: 3

Documentation

Index

Constants

View Source
const (
	// DefaultOutboxClaimLimit is used when ClaimPending receives a non-positive limit.
	DefaultOutboxClaimLimit = 100
	// DefaultOutboxLeaseTTL is used when ClaimPending receives a non-positive lease ttl.
	DefaultOutboxLeaseTTL = 30 * time.Second
)

Variables

View Source
var (
	// ErrScheduledEnqueueUnsupported is returned when an adapter cannot schedule messages.
	ErrScheduledEnqueueUnsupported = fmt.Errorf("scheduled enqueue not supported")
	// ErrLeaseExtensionUnsupported is returned when an adapter cannot extend a lease.
	ErrLeaseExtensionUnsupported = fmt.Errorf("lease extension not supported")
	// ErrDispatchStatusUnsupported is returned when an adapter cannot read dispatch status.
	ErrDispatchStatusUnsupported = fmt.Errorf("dispatch status not supported")
	// ErrDispatchNotFound is returned when no dispatch status exists for a dispatch id.
	ErrDispatchNotFound = fmt.Errorf("dispatch not found")
)

Functions

func DecodeExecutionMessage

func DecodeExecutionMessage(payload []byte) (*job.ExecutionMessage, error)

DecodeExecutionMessage unmarshals a message and restores raw payload bytes.

func EncodeExecutionMessage

func EncodeExecutionMessage(msg *job.ExecutionMessage) ([]byte, error)

EncodeExecutionMessage marshals a message while preserving raw payload bytes.

func ValidateNackOptions added in v0.17.0

func ValidateNackOptions(opts NackOptions) error

ValidateNackOptions enforces explicit nack disposition semantics.

func ValidateRequiredMessage

func ValidateRequiredMessage(msg *job.ExecutionMessage) error

ValidateRequiredMessage enforces required ExecutionMessage fields for queue usage.

Types

type ClaimedOutboxEntry added in v0.15.0

type ClaimedOutboxEntry struct {
	ID         string
	Message    *job.ExecutionMessage
	Attempts   int
	Status     string
	LeaseOwner string
	LeaseToken string
	LeaseUntil time.Time
	RetryAt    time.Time
	CreatedAt  time.Time
	LastError  string
}

ClaimedOutboxEntry is a claimed queue delivery represented with outbox semantics.

type Delivery

type Delivery interface {
	Message() *job.ExecutionMessage
	Ack(ctx context.Context) error
	Nack(ctx context.Context, opts NackOptions) error
}

Delivery represents a single queue message and its ack/nack handlers.

type Dequeuer

type Dequeuer interface {
	Dequeue(ctx context.Context) (Delivery, error)
}

Dequeuer returns the next delivery when available.

type DispatchState added in v0.16.0

type DispatchState string

DispatchState defines queue dispatch lifecycle states exposed by status readers.

const (
	DispatchStateAccepted   DispatchState = "accepted"
	DispatchStateRunning    DispatchState = "running"
	DispatchStateRetrying   DispatchState = "retrying"
	DispatchStateCanceled   DispatchState = "canceled"
	DispatchStateFailed     DispatchState = "failed"
	DispatchStateDeadLetter DispatchState = "dead_letter"
	DispatchStateSucceeded  DispatchState = "succeeded"
)

type DispatchStatus added in v0.16.0

type DispatchStatus struct {
	DispatchID     string
	State          DispatchState
	Attempt        int
	EnqueuedAt     *time.Time
	UpdatedAt      *time.Time
	NextRunAt      *time.Time
	TerminalReason string
}

DispatchStatus represents the current durable queue lifecycle state.

type DispatchStatusReader added in v0.16.0

type DispatchStatusReader interface {
	GetDispatchStatus(ctx context.Context, dispatchID string) (DispatchStatus, error)
}

DispatchStatusReader resolves queue lifecycle state by dispatch id.

type EnqueueReceipt added in v0.16.0

type EnqueueReceipt struct {
	DispatchID string
	EnqueuedAt time.Time
}

EnqueueReceipt contains queue acceptance metadata for a dispatched message.

type Enqueuer

type Enqueuer interface {
	Enqueue(ctx context.Context, msg *job.ExecutionMessage) (EnqueueReceipt, error)
}

Enqueuer accepts execution messages for durable delivery.

type LeaseExtender added in v0.15.0

type LeaseExtender interface {
	ExtendLease(ctx context.Context, ttl time.Duration) error
}

LeaseExtender allows long-running handlers to renew queue leases.

type LeaseStorage added in v0.15.0

type LeaseStorage interface {
	ExtendLease(ctx context.Context, receipt Receipt, ttl time.Duration) error
}

LeaseStorage supports lease extension/heartbeat semantics.

type NackDisposition added in v0.17.0

type NackDisposition string

NackDisposition defines terminal/retry outcomes for nacked deliveries.

const (
	NackDispositionRetry      NackDisposition = "retry"
	NackDispositionDeadLetter NackDisposition = "dead_letter"
	NackDispositionFailed     NackDisposition = "failed"
	NackDispositionCanceled   NackDisposition = "canceled"
)

type NackOptions

type NackOptions struct {
	Disposition NackDisposition
	Delay       time.Duration
	Reason      string
}

NackOptions controls retry and DLQ behavior when nacking a message.

type OutboxStore added in v0.15.0

type OutboxStore interface {
	ClaimPending(ctx context.Context, workerID string, limit int, leaseTTL time.Duration) ([]ClaimedOutboxEntry, error)
	MarkCompleted(ctx context.Context, id, leaseToken string) error
	MarkFailed(ctx context.Context, id, leaseToken string, retryAt time.Time, reason string) error
	ExtendLease(ctx context.Context, id, leaseToken string, leaseTTL time.Duration) error
}

OutboxStore mirrors durable orchestrator dispatch contracts.

type Receipt

type Receipt struct {
	ID          string
	Token       string
	Attempts    int
	LeasedAt    time.Time
	AvailableAt time.Time
	CreatedAt   time.Time
	LastError   string
}

Receipt identifies a leased delivery for ack/nack operations.

type ScheduledEnqueuer added in v0.15.0

type ScheduledEnqueuer interface {
	Enqueuer
	EnqueueAt(ctx context.Context, msg *job.ExecutionMessage, at time.Time) (EnqueueReceipt, error)
	EnqueueAfter(ctx context.Context, msg *job.ExecutionMessage, delay time.Duration) (EnqueueReceipt, error)
}

ScheduledEnqueuer supports delayed/scheduled enqueue semantics.

type ScheduledStorage added in v0.15.0

type ScheduledStorage interface {
	EnqueueAt(ctx context.Context, msg *job.ExecutionMessage, at time.Time) (EnqueueReceipt, error)
	EnqueueAfter(ctx context.Context, msg *job.ExecutionMessage, delay time.Duration) (EnqueueReceipt, error)
}

ScheduledStorage supports delayed enqueue semantics.

type Storage

type Storage interface {
	Enqueue(ctx context.Context, msg *job.ExecutionMessage) (EnqueueReceipt, error)
	Dequeue(ctx context.Context) (*job.ExecutionMessage, Receipt, error)
	Ack(ctx context.Context, receipt Receipt) error
	Nack(ctx context.Context, receipt Receipt, opts NackOptions) error
}

Storage is the backend contract for durable queue adapters.

type StorageOutboxAdapter added in v0.15.0

type StorageOutboxAdapter struct {
	// contains filtered or unexported fields
}

StorageOutboxAdapter maps queue.Storage semantics to an OutboxStore contract.

func NewStorageOutboxAdapter added in v0.15.0

func NewStorageOutboxAdapter(storage Storage, opts ...StorageOutboxOption) *StorageOutboxAdapter

NewStorageOutboxAdapter builds an outbox adapter backed by queue storage.

func (*StorageOutboxAdapter) ClaimPending added in v0.15.0

func (a *StorageOutboxAdapter) ClaimPending(ctx context.Context, workerID string, limit int, leaseTTL time.Duration) ([]ClaimedOutboxEntry, error)

ClaimPending claims pending queue messages as leased outbox entries.

func (*StorageOutboxAdapter) ExtendLease added in v0.15.0

func (a *StorageOutboxAdapter) ExtendLease(ctx context.Context, id, leaseToken string, leaseTTL time.Duration) error

ExtendLease extends one claimed entry lease when supported by storage.

func (*StorageOutboxAdapter) MarkCompleted added in v0.15.0

func (a *StorageOutboxAdapter) MarkCompleted(ctx context.Context, id, leaseToken string) error

MarkCompleted marks a claimed entry as completed (ack).

func (*StorageOutboxAdapter) MarkFailed added in v0.15.0

func (a *StorageOutboxAdapter) MarkFailed(ctx context.Context, id, leaseToken string, retryAt time.Time, reason string) error

MarkFailed marks a claimed entry as failed and requeues it for retry scheduling.

type StorageOutboxOption added in v0.15.0

type StorageOutboxOption func(*StorageOutboxAdapter)

StorageOutboxOption customizes StorageOutboxAdapter behavior.

func WithOutboxClock added in v0.15.0

func WithOutboxClock(now func() time.Time) StorageOutboxOption

WithOutboxClock overrides time source used for retry scheduling calculations.

Directories

Path Synopsis
adapters
internal

Jump to

Keyboard shortcuts

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