v1.0.0

v1.0.0

Initial stable release of gqs — a lightweight, storage-agnostic Go queue service with at-least-once delivery semantics.

This version marks the first stable API contract.

Overview

gqs provides:

• Explicit job state machine (Pending → Processing → Done/Dead)
• Visibility timeout (lease) semantics
• At-least-once delivery model
• Configurable retry with exponential backoff
• Immediate termination shortcut (ErrKill)
• Graceful worker shutdown with timeout
• Bounded worker pool
• Pluggable storage backends

The project is structured as multi-module:

• github.com/romanqed/gqs — core queue logic
• github.com/romanqed/gqs/sql — SQL backend (bun-based)

Core Features

Worker

• Periodic pull-based job acquisition
• Atomic state transitions
• Automatic lease extension while handler executes
• Retry with BackoffConfig
• Immediate permanent failure via ErrKill
• Graceful shutdown with timeout control

Delivery Semantics

• At-least-once processing
• Idempotent handlers required
• No exactly-once guarantee

Retry Model

Handler return values:

• nil → Done
• ErrKill → Dead (no retry)
• other error → retry with backoff
• retries exhausted → Dead

Clean Worker

• Periodic removal of terminal jobs
• Retention control via status and age filters

SQL Backend

• Implemented using github.com/uptrace/bun

• Atomic UPDATE ... RETURNING pull

• Visibility timeout via locked_until

• Required composite indexes:

  • (status, next_run_at)
  • (status, locked_until)
  • (status, updated_at)

• SQLite-compatible (WAL recommended)

Stability

• API stabilized for v1.x
• Fully race-safe (go test -race clean)
• Unit and integration tests included
• No global state
• Clear separation between core and backends

Notes

• Exactly-once delivery is intentionally not supported.
• Lease tokens are not used — state is enforced via status + timestamps.
• SQLite users should enable WAL and configure busy_timeout.

Installation

go get github.com/romanqed/gqs@v1.0.0
go get github.com/romanqed/gqs/sql@v1.0.0

This release establishes the stable foundation for future extensions and additional storage backends.