README
¶
Adele Queue
A first-party queue package for the Adele Go framework. Ships as an Adele ServiceProvider with an in-memory backend for single-process workloads and a Redis-backed backend for multi-process deployments, plus worker pools, retry with backoff, failure tracking, and durable job persistence to the framework database.
Supported Backends
| Backend | Description | Use Case |
|---|---|---|
memory |
Single-process channel-based queue with sync.WaitGroup-backed worker pool. | Local development, single-node deployments, short-lived jobs. |
redis |
Distributed queue backed by Redis hashes; workers cooperatively scan the keyspace for pending jobs and atomically rename keys between pending, locked, completed, and failed states. Orphaned locked: keys from crashed workers are recovered automatically — see Stale Lock Reaping. |
Multi-process deployments, horizontal scaling, jobs that must survive process restarts. |
Requirements
Requires Go 1.25 or later. If your local toolchain is older, set GOTOOLCHAIN=auto (Go 1.21+) to let the toolchain auto-upgrade.
Quick Start
go get github.com/cidekar/adele-queue
Blank-import the package to auto-register the ServiceProvider:
import (
_ "github.com/cidekar/adele-queue"
)
The ServiceProvider loads configuration from config/queue.yml (seeded on first run from the embedded default), starts the worker pool during Boot, and wires into the framework's database session for durable job storage. The queue registers no HTTP routes.
Configuration
Configuration comes from one of two sources:
$ROOT/config/queue.yml— the YAML file, auto-seeded from the embedded default on first run.app.Provider.SetProviderConfig("queue", map[string]interface{}{...})at app bootstrap, which is forwarded to the provider'sConfiguremethod.
The provider accepts the following SetProviderConfig keys:
app.Provider.SetProviderConfig("queue", map[string]interface{}{
"backend": "redis",
"worker_count": 4,
"max_attempts": 5,
"high_water_mark": 10000,
"queue_channels": []string{"job", "email"},
"queue_channel_default": "job",
"debug": false,
"redis_prefix": "myapp",
"redis_scan_interval": 1,
"lock_timeout": 300,
"reaper_interval": 30,
})
Documentation
For complete documentation including configuration reference, backend behavior, dispatch and retry semantics, and worker lifecycle, see the full documentation.
Maintainers: run the redis-backed job harness with make bench:help.
License
Copyright 2025 Cidekar, LLC. All rights reserved.
Documentation
¶
Index ¶
- type Configuration
- type Job
- type Queue
- type Redis
- type ServiceProvider
- func (p *ServiceProvider) Boot(app interface{}) error
- func (p *ServiceProvider) Configure(config map[string]interface{}) error
- func (p *ServiceProvider) Name() string
- func (p *ServiceProvider) Priority() int
- func (p *ServiceProvider) Register(app interface{}) error
- func (p *ServiceProvider) Service() *api.Queue
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Configuration ¶
type Configuration = api.Configuration
type Queue ¶
func New ¶
New creates a new Queue instance wired to the given Adele application.
Example:
q, err := queue.New(app)
if err != nil {
return err
}
q.Listen()
func NewWithConfig ¶
func NewWithConfig(a *adele.Adele, config Configuration) (*Queue, error)
NewWithConfig creates a new Queue instance with a caller-supplied Configuration, bypassing any on-disk config/queue.yml. Intended for tests and programmatic setup.
Example:
cfg := queue.Configuration{Backend: "memory", WorkerCount: 2}
q, err := queue.NewWithConfig(app, cfg)
if err != nil {
return err
}
type ServiceProvider ¶
type ServiceProvider struct {
// contains filtered or unexported fields
}
ServiceProvider is the compiled Adele framework provider for the queue. It wires up the queue service and starts the worker pool during Boot.
Example:
// Registered automatically via init(). // Construct a queue directly inside your application: q := queue.New(app)
func (*ServiceProvider) Boot ¶
func (p *ServiceProvider) Boot(app interface{}) error
Boot starts the queue worker pool. Called after every provider has been registered so the queue can safely rely on any earlier-booted dependencies.
func (*ServiceProvider) Configure ¶
func (p *ServiceProvider) Configure(config map[string]interface{}) error
Configure maps a config map to the Configuration struct fields and stores it for use during Register.
func (*ServiceProvider) Name ¶
func (p *ServiceProvider) Name() string
Name returns the unique identifier for this provider.
func (*ServiceProvider) Priority ¶
func (p *ServiceProvider) Priority() int
Priority returns 30, placing this provider in the core-services tier per Adele conventions.
func (*ServiceProvider) Register ¶
func (p *ServiceProvider) Register(app interface{}) error
Register initializes the queue service. The queue registers no routes; it runs entirely through the worker pool started in Boot.
func (*ServiceProvider) Service ¶
func (p *ServiceProvider) Service() *api.Queue
Service returns the underlying *api.Queue after Register has been called. May be nil if the provider has not yet been registered.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
bench/benchjobs
Package jobs wires the test-job constructors (written by Wave 1 implementers #1-5) into a single one-shot dispatcher.
|
Package jobs wires the test-job constructors (written by Wave 1 implementers #1-5) into a single one-shot dispatcher. |