Documentation
¶
Index ¶
- Constants
- Variables
- func DecodeExecutionMessage(payload []byte) (*job.ExecutionMessage, error)
- func EncodeExecutionMessage(msg *job.ExecutionMessage) ([]byte, error)
- func ValidateNackOptions(opts NackOptions) error
- func ValidateRequiredMessage(msg *job.ExecutionMessage) error
- type ClaimedOutboxEntry
- type Delivery
- type Dequeuer
- type DispatchState
- type DispatchStatus
- type DispatchStatusReader
- type EnqueueReceipt
- type Enqueuer
- type LeaseExtender
- type LeaseStorage
- type NackDisposition
- type NackOptions
- type OutboxStore
- type Receipt
- type ScheduledEnqueuer
- type ScheduledStorage
- type Storage
- type StorageOutboxAdapter
- func (a *StorageOutboxAdapter) ClaimPending(ctx context.Context, workerID string, limit int, leaseTTL time.Duration) ([]ClaimedOutboxEntry, error)
- func (a *StorageOutboxAdapter) ExtendLease(ctx context.Context, id, leaseToken string, leaseTTL time.Duration) error
- func (a *StorageOutboxAdapter) MarkCompleted(ctx context.Context, id, leaseToken string) error
- func (a *StorageOutboxAdapter) MarkFailed(ctx context.Context, id, leaseToken string, retryAt time.Time, reason string) error
- type StorageOutboxOption
Constants ¶
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 ¶
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 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
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
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.