valkeystream

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Aug 26, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Overview

Package valkeystream provides a Valkey Streams queue backend.

Index

Constants

This section is empty.

Variables

View Source
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,
	)
)
View Source
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")
)
View Source
var ErrInvalidConfiguration = errors.New("valkeystream: invalid configuration")

ErrInvalidConfiguration identifies unsafe Valkey Streams configuration.

View Source
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.

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

func WithAddress(address string) Option

WithAddress sets the standalone Valkey host and port.

func WithAuthentication

func WithAuthentication(username, password string) Option

WithAuthentication sets Valkey ACL credentials.

func WithBlockTime

func WithBlockTime(timeout time.Duration) Option

WithBlockTime bounds each consumer-group blocking read.

func WithBlockingPool

func WithBlockingPool(minimum, maximum int, cleanup time.Duration) Option

WithBlockingPool configures the bounded pool used by blocking commands.

func WithCanceledDeadLetterCodes

func WithCanceledDeadLetterCodes(codes ...string) Option

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

func WithClientName(name string) Option

WithClientName sets the name reported to Valkey for owned connections.

func WithCommandTimeout

func WithCommandTimeout(timeout time.Duration) Option

WithCommandTimeout bounds non-blocking Valkey commands.

func WithConsumer

func WithConsumer(name string) Option

WithConsumer sets the stable identity used for reads and reclaim ownership.

func WithDB

func WithDB(database int) Option

WithDB selects the standalone Valkey database.

func WithDeadLetter

func WithDeadLetter(stream string, maxAttempts int64) Option

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

func WithDialTimeout(timeout time.Duration) Option

WithDialTimeout bounds initial and reconnect dial attempts.

func WithFailureStream

func WithFailureStream(stream string) Option

WithFailureStream configures the bounded stream used to retain failed delivery attempts for management inspection.

func WithGroup

func WithGroup(name string) Option

WithGroup sets the Valkey consumer group.

func WithLogger

func WithLogger(logger queue.Logger) Option

WithLogger sets the worker logger.

func WithManagementStatus

func WithManagementStatus(metadata management.StatusMetadata) Option

WithManagementStatus enables native worker and queue status reporting.

func WithMaxLength

func WithMaxLength(length int64) Option

WithMaxLength sets the hard source-stream admission capacity. Enqueue fails with queue.ErrMaxCapacity rather than evicting accepted work.

func WithReadBatchSize

func WithReadBatchSize(size int) Option

WithReadBatchSize bounds entries returned by each XREADGROUP command.

func WithReclaim

func WithReclaim(minIdle, interval time.Duration, batchSize int) Option

WithReclaim configures stale-delivery recovery.

func WithRecordRetention

func WithRecordRetention(maxRecords int64) Option

WithRecordRetention deliberately enables exact maximum-count retention for failure and dead-letter streams. It is disabled by default.

func WithReplayDestinations

func WithReplayDestinations(destinations ...string) Option

WithReplayDestinations allowlists bounded logical streams for administrative replay. Replay remains disabled when this option is absent.

func WithRequestTimeout

func WithRequestTimeout(timeout time.Duration) Option

WithRequestTimeout bounds how long Request waits for a delivery.

func WithRunFunc

func WithRunFunc(run func(context.Context, core.TaskMessage) error) Option

WithRunFunc sets the task handler.

func WithShutdownTimeout

func WithShutdownTimeout(timeout time.Duration) Option

WithShutdownTimeout bounds graceful worker shutdown.

func WithStreamName

func WithStreamName(name string) Option

WithStreamName sets the Valkey stream key.

func WithTLSConfig

func WithTLSConfig(config *tls.Config) Option

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

func NewPublisherE(option ...Option) (*Publisher, error)

NewPublisherE constructs a producer-only Valkey Streams client and validates initial connectivity without creating or joining a consumer group.

func (*Publisher) BackendName

func (*Publisher) BackendName() string

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.

func (*Publisher) QueueName

func (publisher *Publisher) QueueName() string

QueueName returns the configured stream name.

func (*Publisher) Shutdown

func (publisher *Publisher) Shutdown() error

Shutdown closes the producer-owned Valkey connections.

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

func NewWorker(option ...Option) *Worker

NewWorker constructs a Valkey Streams worker and panics when configuration or initial connectivity is invalid.

func NewWorkerE

func NewWorkerE(option ...Option) (*Worker, error)

NewWorkerE constructs a Valkey Streams worker with a native valkey-go client and validates connectivity and consumer-group ownership.

func (*Worker) BackendName

func (*Worker) BackendName() string

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

func (w *Worker) QueueName() string

QueueName returns the configured stream name.

func (*Worker) Request

func (w *Worker) Request() (core.TaskMessage, error)

Request waits for one new or reclaimed delivery.

func (*Worker) Run

func (w *Worker) Run(ctx context.Context, task core.TaskMessage) error

Run invokes the configured task handler.

func (*Worker) Shutdown

func (w *Worker) Shutdown() error

Shutdown cancels blocking reads and reclaim scans, waits within the configured bound, and closes every native connection owned by the worker.

func (*Worker) Stats

func (w *Worker) Stats(ctx context.Context) (Stats, error)

Stats returns an honest consumer-group snapshot and this worker's monotonic lifecycle counters.

Jump to

Keyboard shortcuts

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