Documentation
¶
Overview ¶
Package valkeystream provides a Valkey Streams queue backend.
Index ¶
- Variables
- type ConfigurationError
- type DeliveryAttemptLimitResolver
- type Option
- func WithAddress(address string) Option
- func WithAuthentication(username, password string) Option
- func WithBlockTime(timeout time.Duration) Option
- func WithBlockingPool(minimum, maximum int, cleanup time.Duration) Option
- func WithCanceledDeadLetterCodes(codes ...string) Option
- func WithClientName(name string) Option
- func WithCommandTimeout(timeout time.Duration) Option
- func WithConsumer(name string) Option
- func WithDB(database int) Option
- func WithDeadLetter(stream string, maxAttempts int64) Option
- func WithDeliveryAttemptLimitResolver(resolver DeliveryAttemptLimitResolver) Option
- func WithDialTimeout(timeout time.Duration) Option
- func WithFailureStream(stream string) Option
- func WithGroup(name string) Option
- func WithLogger(logger queue.Logger) Option
- func WithManagementStatus(metadata management.StatusMetadata) Option
- func WithMaxLength(length int64) Option
- func WithReadBatchSize(size int) Option
- func WithReclaim(minIdle, interval time.Duration, batchSize int) Option
- func WithRecordRetention(maxRecords int64) Option
- func WithReplayDestinations(destinations ...string) Option
- func WithRequestTimeout(timeout time.Duration) Option
- func WithRunFunc(run func(context.Context, core.TaskMessage) error) Option
- func WithShutdownTimeout(timeout time.Duration) Option
- func WithStreamName(name string) Option
- func WithTLSConfig(config *tls.Config) Option
- type Publisher
- type Stats
- type Worker
- func (*Worker) BackendName() string
- func (w *Worker) Execute(ctx context.Context, command management.Command) (management.CommandResult, error)
- func (w *Worker) Inspect(ctx context.Context, request management.InspectRequest) (management.JobRecord, error)
- func (w *Worker) ListDeadLetters(ctx context.Context, request management.PageRequest) (management.RecordPage, error)
- func (w *Worker) ListFailures(ctx context.Context, request management.PageRequest) (management.RecordPage, error)
- func (w *Worker) ObserveQueue(ctx context.Context) (management.QueueStatus, error)
- func (w *Worker) ObserveWorker(ctx context.Context) (management.WorkerStatus, error)
- func (w *Worker) Queue(task core.TaskMessage) error
- func (w *Worker) QueueName() string
- func (w *Worker) Request() (core.TaskMessage, error)
- func (w *Worker) Run(ctx context.Context, task core.TaskMessage) error
- func (w *Worker) Shutdown() error
- func (w *Worker) Stats(ctx context.Context) (Stats, error)
Constants ¶
This section is empty.
Variables ¶
var ( // ErrManagementRecordsDisabled reports a worker without a native record transport. ErrManagementRecordsDisabled = fmt.Errorf( "valkeystream: management records disabled: %w", management.ErrUnsupportedCapability, ) // ErrManagementRecordNotFound reports an unknown failure or dead-letter identifier. ErrManagementRecordNotFound = fmt.Errorf( "valkeystream: management record not found: %w", management.ErrRecordNotFound, ) )
var ( // ErrManagementStatusDisabled reports a worker without reporter metadata. ErrManagementStatusDisabled = errors.New("valkeystream: management status disabled") // ErrInvalidManagementStatus reports malformed reporter metadata or time. ErrInvalidManagementStatus = errors.New("valkeystream: invalid management status") )
var ErrInvalidConfiguration = errors.New("valkeystream: invalid configuration")
ErrInvalidConfiguration identifies unsafe Valkey Streams configuration.
var ErrInvalidDeliveryAttemptLimit = errors.New(
"valkeystream: invalid delivery attempt limit",
)
ErrInvalidDeliveryAttemptLimit reports a resolver that returned an unsafe per-message broker-delivery limit or panicked. The delivery remains pending.
var ErrManagementControlDisabled = errors.New("valkeystream: management control disabled")
Functions ¶
This section is empty.
Types ¶
type ConfigurationError ¶
type ConfigurationError struct {
// Field identifies the invalid package-owned option without its value.
Field string
// Cause retains the validation cause for errors.Is and errors.As.
Cause error
}
ConfigurationError identifies the invalid configuration field without exposing its potentially sensitive value.
func (*ConfigurationError) Error ¶
func (e *ConfigurationError) Error() string
Error returns credential-safe configuration error text.
func (*ConfigurationError) Unwrap ¶
func (e *ConfigurationError) Unwrap() []error
Unwrap retains both stable classification and the underlying cause.
type DeliveryAttemptLimitResolver ¶
type DeliveryAttemptLimitResolver func(core.TaskMessage) int64
DeliveryAttemptLimitResolver selects the terminal broker-delivery ceiling for one decoded message. It must be deterministic, side-effect-free, and return between two and 100. WithDeadLetter remains the default when no resolver is configured.
type Option ¶
type Option func(*options) error
Option configures a Valkey Streams worker without exposing native client option types.
func WithAddress ¶
WithAddress sets the standalone Valkey host and port.
func WithAuthentication ¶
WithAuthentication sets Valkey ACL credentials.
func WithBlockTime ¶
WithBlockTime bounds each consumer-group blocking read.
func WithBlockingPool ¶
WithBlockingPool configures the bounded pool used by blocking commands.
func WithCanceledDeadLetterCodes ¶
WithCanceledDeadLetterCodes allows selected canceled failure codes to become terminal at the configured maximum delivery attempt. Unlisted cancellation and every infrastructure failure remain pending for safe recovery.
func WithClientName ¶
WithClientName sets the name reported to Valkey for owned connections.
func WithCommandTimeout ¶
WithCommandTimeout bounds non-blocking Valkey commands.
func WithConsumer ¶
WithConsumer sets the stable identity used for reads and reclaim ownership.
func WithDeadLetter ¶
WithDeadLetter configures terminal delivery handling.
func WithDeliveryAttemptLimitResolver ¶
func WithDeliveryAttemptLimitResolver( resolver DeliveryAttemptLimitResolver, ) Option
WithDeliveryAttemptLimitResolver overrides the default dead-letter attempt ceiling per decoded message. Unsafe results and panics fail the delivery without acknowledging or dead-lettering it.
func WithDialTimeout ¶
WithDialTimeout bounds initial and reconnect dial attempts.
func WithFailureStream ¶
WithFailureStream configures the bounded stream used to retain failed delivery attempts for management inspection.
func WithManagementStatus ¶
func WithManagementStatus(metadata management.StatusMetadata) Option
WithManagementStatus enables native worker and queue status reporting.
func WithMaxLength ¶
WithMaxLength sets the hard source-stream admission capacity. Enqueue fails with queue.ErrMaxCapacity rather than evicting accepted work.
func WithReadBatchSize ¶
WithReadBatchSize bounds entries returned by each XREADGROUP command.
func WithReclaim ¶
WithReclaim configures stale-delivery recovery.
func WithRecordRetention ¶
WithRecordRetention deliberately enables exact maximum-count retention for failure and dead-letter streams. It is disabled by default.
func WithReplayDestinations ¶
WithReplayDestinations allowlists bounded logical streams for administrative replay. Replay remains disabled when this option is absent.
func WithRequestTimeout ¶
WithRequestTimeout bounds how long Request waits for a delivery.
func WithRunFunc ¶
WithRunFunc sets the task handler.
func WithShutdownTimeout ¶
WithShutdownTimeout bounds graceful worker shutdown.
func WithStreamName ¶
WithStreamName sets the Valkey stream key.
func WithTLSConfig ¶
WithTLSConfig enables TLS using a private clone of config.
type Publisher ¶
type Publisher struct {
// contains filtered or unexported fields
}
Publisher appends durable Valkey Stream jobs without joining a consumer group or starting worker read and reclaim loops.
func NewPublisherE ¶
NewPublisherE constructs a producer-only Valkey Streams client and validates initial connectivity without creating or joining a consumer group.
func (*Publisher) BackendName ¶
BackendName identifies this adapter in lifecycle events.
func (*Publisher) Queue ¶
func (publisher *Publisher) Queue( message core.QueuedMessage, options ...job.AllowOption, ) error
Queue validates, encodes, and appends one job to the configured stream.
type Stats ¶
type Stats struct {
// Depth is pending plus lag, or -1 when lag is unknown.
Depth int64
// Pending is the server-reported consumer-group pending count.
Pending int64
// Lag is the server-reported count not yet delivered to the group.
Lag int64
// LagKnown reports whether Depth and Lag are determinate.
LagKnown bool
// OldestPendingAge is derived from the oldest pending stream identifier.
OldestPendingAge time.Duration
// Enqueued counts successful appends observed by this worker process.
Enqueued uint64
// Delivered counts messages returned by Request in this worker process.
Delivered uint64
// Reclaimed counts delivered messages recovered through XAUTOCLAIM.
Reclaimed uint64
// Retries counts reclaimed retry deliveries observed by this worker.
Retries uint64
// Acknowledged counts successful source acknowledgements.
Acknowledged uint64
// DeadLettered counts successful terminal dead-letter transfers.
DeadLettered uint64
// SettlementFailures counts failed ack and dead-letter operations.
SettlementFailures uint64
}
Stats describes server-reported outstanding work and monotonic lifecycle counters observed by this worker. Depth is -1 when Valkey cannot report lag.
type Worker ¶
type Worker struct {
// contains filtered or unexported fields
}
Worker is a standalone Valkey Streams queue worker.
func NewWorker ¶
NewWorker constructs a Valkey Streams worker and panics when configuration or initial connectivity is invalid.
func NewWorkerE ¶
NewWorkerE constructs a Valkey Streams worker with a native valkey-go client and validates connectivity and consumer-group ownership.
func (*Worker) BackendName ¶
BackendName identifies this adapter in lifecycle events.
func (*Worker) Execute ¶
func (w *Worker) Execute( ctx context.Context, command management.Command, ) (management.CommandResult, error)
Execute applies one bounded native Valkey record mutation. Replay and queue purge remain unsupported until their durable backend semantics are proven.
func (*Worker) Inspect ¶
func (w *Worker) Inspect( ctx context.Context, request management.InspectRequest, ) (management.JobRecord, error)
Inspect returns one record with no more payload disclosure than requested.
func (*Worker) ListDeadLetters ¶
func (w *Worker) ListDeadLetters( ctx context.Context, request management.PageRequest, ) (management.RecordPage, error)
ListDeadLetters returns bounded terminal-delivery metadata without payload bytes.
func (*Worker) ListFailures ¶
func (w *Worker) ListFailures( ctx context.Context, request management.PageRequest, ) (management.RecordPage, error)
ListFailures returns bounded failed-attempt metadata without payload bytes.
func (*Worker) ObserveQueue ¶
func (w *Worker) ObserveQueue(ctx context.Context) (management.QueueStatus, error)
ObserveQueue returns honest native Valkey Streams measurements and counters.
func (*Worker) ObserveWorker ¶
func (w *Worker) ObserveWorker(ctx context.Context) (management.WorkerStatus, error)
ObserveWorker returns this worker's bounded native management observation.
func (*Worker) Queue ¶
func (w *Worker) Queue(task core.TaskMessage) error
Queue appends one bounded encoded task to the configured stream.
func (*Worker) Request ¶
func (w *Worker) Request() (core.TaskMessage, error)
Request waits for one new or reclaimed delivery.