async-background 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5959a648b21b8312d1b2d8d566ade149e736b6386eff0cf1fb9acd09801ba748
-  data.tar.gz: 839fd36e05ee3ef845ba1f2afaef50a5c996edf9812240a61198cb2f203d0e9a
+  metadata.gz: 26e459d9e86a150ff8b3126ce8899ac9beb60355e3313d5510c1c0c6dec0bfd7
+  data.tar.gz: 93a52a9139f902e1acee7b58ea98dceadba2219537329b785f3a103009f72401
 SHA512:
-  metadata.gz: 408c3267a1acd854448a4dec42d0a3ab30a3ed8e40d40e5c841aca6c29cd2dc3378683ef7c5b305fa419b4fefea80292968efa67e1ff6eb8a4de5d7a5c403e00
-  data.tar.gz: 7d7af316122b5208e7adaaf681be8075821936fda225e78def6f8a9b76cf5350e50cd0bf6015888e585c149101c741de2d5f52ba82ffa4aa35734a3d86183511
+  metadata.gz: 3dcfcc9089b2bb8b5b3fb01341039fa1dea32896f6e3845f137bd9e307b366b2716208d4ecb533b266cf31c3b0466535817d7dc9d6c1a0876e113519417a0512
+  data.tar.gz: ece53f421338c16a02548754a6c1a2e8a62988659a83f4575e8ad23d01fd987958e6d3fb94360607444ff34a4dc0fb8844fdfdbca9228c2c8af09b1aec486b36

data/CHANGELOG.md

@@ -0,0 +1,160 @@
+# Changelog
+
+## 0.5.1
+
+### Testing Infrastructure
+- **Comprehensive CI setup** — full Docker-based integration testing environment with `Dockerfile.ci`, `docker-compose.ci.yml`, and `Gemfile.ci`
+- **End-to-end scenario testing** — new `ci/scenario_test.rb` validates real-world scenarios with forked workers:
+  - Normal execution of fast/slow/failing jobs across multiple workers
+  - Crash recovery after SIGKILL with automatic job pickup by remaining workers
+  - No duplicate execution guarantees under worker crashes
+  - Proper job distribution validation across worker pool
+- **Test fixtures** — dedicated `ci/fixtures/jobs.rb` and `ci/fixtures/schedule.yml` for scenario testing
+
+### Bug Fixes  
+- **SQLite busy timeout** — added `PRAGMA busy_timeout = 5000` to `Queue::Store` to prevent `SQLITE_BUSY` errors under concurrent multi-process database access
+- **Enhanced Queue::Notifier error handling** — restructured IO error handling with clearer categorization:
+  - `WRITE_DROPPED` for write failures (`IO::WaitWritable`, `Errno::EAGAIN`, `IOError`, `Errno::EPIPE`) — all non-fatal as job is already in store
+  - `READ_EXHAUSTED` for read exhaustion (`IO::WaitReadable`, `EOFError`, `IOError`) — normal drain completion
+  - Added explanatory comments for each error type and handling strategy
+
+## 0.5.0
+
+### Features
+- **Delayed jobs** — full support for scheduling jobs in the future
+  - `Queue::Client#push_in(delay, class_name, args)` — enqueue with delay in seconds
+  - `Queue::Client#push_at(time, class_name, args)` — enqueue at a specific time
+  - `Queue.enqueue_in(delay, job_class, *args)` — class-level delayed enqueue
+  - `Queue.enqueue_at(time, job_class, *args)` — class-level scheduled enqueue
+  - New `run_at` column in SQLite `jobs` table — jobs are only fetched when `run_at <= now`
+- **Job module** — Sidekiq-like `include Async::Background::Job` interface
+  - `perform_async(*args)` — immediate queue execution
+  - `perform_in(delay, *args)` — delayed execution after N seconds
+  - `perform_at(time, *args)` — scheduled execution at a specific time
+  - Instance-level `#perform` with class-level `perform_now` delegation
+- **Clock module** — shared `monotonic_now` / `realtime_now` helpers extracted into `Async::Background::Clock`, included by `Runner`, `Queue::Store`, and `Queue::Client`
+
+### Bug Fixes
+- **Runner: incorrect task in `with_timeout`** — `semaphore.async { |job_task| ... }` now correctly receives the child task instead of capturing the parent `task` from the outer scope. Previously, `with_timeout` was applied to the parent task, which could cancel unrelated work
+
+### Improvements
+- **Job API: `#perform` instead of `#perform_now`** — job classes now define `#perform` instance method. The class-level `perform_now` creates instance and calls `#perform`, aligning with ActiveJob / Sidekiq conventions
+- Updated error messages: validation failures now suggest `must include Async::Background::Job` instead of `must implement .perform_now`
+- `Queue::Client` — extracted private `ensure_configured!` and `resolve_class_name` methods for cleaner validation and class name resolution logic
+- `Queue::Notifier` — extracted `IO_ERRORS` constant (`IO::WaitReadable`, `EOFError`, `IOError`) for cleaner `rescue` in `drain`
+- `Queue::Store` — replaced index `idx_jobs_status_id(status, id)` with `idx_jobs_status_run_at_id(status, run_at, id)` for efficient delayed job lookups
+- `Queue::Store` — `fetch` SQL now uses `WHERE status = 'pending' AND run_at <= ?` with `ORDER BY run_at, id` to process jobs in scheduled order
+- Removed duplicated `monotonic_now` / `realtime_now` from `Runner` and `Store` — now provided by `Clock` module
+- Updated documentation: README (Job module examples, Queue architecture diagram, Clock section), GET_STARTED (delayed jobs guide, Job module usage, minimal queue-only example)
+
+## 0.4.5
+
+### Breaking Changes
+- `PRAGMAS` is now a frozen lambda `PRAGMAS.call(mmap_size)` instead of a static string — if you referenced this constant directly, update your code
+
+### Features
+- New `queue_mmap:` parameter on `Runner` (default: `true`) — allows disabling SQLite mmap for environments where it's unsafe (Docker overlay2)
+- New `mmap:` parameter on `Queue::Store` (default: `true`) — controls `PRAGMA mmap_size` (256 MB when enabled, 0 when disabled)
+- Public `attr_reader :queue_store` on `Runner` — eliminates need for `instance_variable_get` when sharing Store with Client
+
+### Bug Fixes
+- **CRITICAL: fetch race condition** — wrapped `UPDATE ... RETURNING` in `BEGIN IMMEDIATE` transaction to prevent two workers from picking up the same job simultaneously
+- **CRITICAL: mmap + Docker overlay2** — `overlay2` filesystem does not guarantee `write()`/`mmap()` coherence, causing SQLite WAL corruption under concurrent multi-process access. mmap is now configurable via `queue_mmap: false` instead of being hardcoded. Documented proper Docker setup with named volumes in `docs/GET_STARTED.md`
+- **`PRAGMA optimize` on shutdown** — wrapped in `rescue nil` to prevent `SQLite3::BusyException` when another process holds the write lock during graceful shutdown
+- **`PRAGMA incremental_vacuum` was a no-op** — added `PRAGMA auto_vacuum = INCREMENTAL` to schema. Without it, `incremental_vacuum` does nothing. Note: only takes effect on newly created databases; existing databases require a one-time `VACUUM`
+
+### Improvements
+- Replaced index `idx_jobs_status(status)` with composite `idx_jobs_status_id(status, id)` — eliminates sort step in `fetch` query (`ORDER BY id LIMIT 1` is now a direct B-tree lookup)
+- Fixed `finalize_statements` — changed `%i[@enqueue_stmt ...]` to `%i[enqueue_stmt ...]` with `:"@#{name}"` interpolation for idiomatic `instance_variable_get`/`set` usage
+- Added documentation: `README.md` (concise, with warning markers) and `docs/GET_STARTED.md` (step-by-step guide covering schedule config, Falcon integration, Docker setup, dynamic queue)
+
+## 0.4.0
+
+### Features
+- **Dynamic job queue** — enqueue jobs at runtime from any process (web, console, rake) with automatic execution by background workers
+  - `Queue::Store` — SQLite-backed persistent storage with WAL mode, prepared statements, and optimized pragmas
+  - `Queue::Notifier` — `IO.pipe`-based zero-cost wakeup between producer and consumer processes (no polling)
+  - `Queue::Client` — public API: `Async::Background::Queue.enqueue(JobClass, *args)`
+  - Automatic recovery of stale `running` jobs on worker restart
+  - Periodic cleanup of completed jobs (piggyback on fetch, every 5 minutes)
+  - `PRAGMA incremental_vacuum` when cleanup removes 100+ rows
+  - Worker isolation via `ISOLATION_FORKS` env variable — exclude specific workers from queue processing
+  - Custom database path via `queue_db_path` parameter
+  - Requires optional `sqlite3` gem (`~> 2.0`) — not included by default, must be added to Gemfile explicitly
+- New Runner parameters: `queue_notifier:` and `queue_db_path:`
+
+### Improvements
+- Unified `monotonic_now` usage across `run_job` and `run_queue_job` (was using direct `Process.clock_gettime` call in `run_job`)
+- `Queue::Notifier#drain` — moved `rescue` inside the loop to avoid stack unwinding on each drain cycle
+
+## 0.3.0
+
+### Features
+- Added optional metrics collection system using shared memory
+- New `Metrics` class with worker-specific performance tracking
+- Public API: `runner.metrics.enabled?`, `runner.metrics.values`, `Metrics.read_all()`
+- Tracks total runs, successes, failures, timeouts, skips, active jobs, and execution times
+- Requires optional `async-utilization` gem dependency
+- Metrics stored in `/tmp/async-background.shm` with lock-free updates per worker
+
+## 0.2.6
+
+### Improvements
+- Micro-optimization in `wait_with_shutdown` method: use passed `task` parameter instead of `Async::Task.current` for better consistency and slight performance improvement
+
+## 0.2.5
+
+### Features
+- Added graceful shutdown via signal handlers for SIGINT and SIGTERM
+- Enhanced process lifecycle management with proper signal handling using `Signal.trap` and IO.pipe for async communication
+- Improved robustness for production deployments and container orchestration
+- Updated dependencies to work with latest Async 2.x API (removed deprecated `:parent` parameter usage)
+
+## 0.2.4
+
+### Improvements
+- Removed hardcoded version warning from main module (was checking against fixed list: 0.1.0, 0.2.2, 0.2.3). Use semantic versioning with pre-release suffixes for unstable versions (e.g., 0.3.0.alpha1) instead
+- Removed hardcoded stable versions list from gemspec description — metadata should describe functionality, not versioning
+- Changed `while true` to idiomatic `loop do` in run method
+- Added `Gemfile.lock` to .gitignore (gems should not commit lockfile)
+- Updated README: clarified that job class must respond to `.perform_now` class method (removed confusing mention of instance `#perform`)
+
+## 0.2.2
+
+### Bug Fixes
+- **CRITICAL**: Removed logger parameter from Runner initialize (was unused). Fixed initialization to use Console.logger directly which now properly initializes in forked processes with correct context
+
+## 0.2.1
+
+### Bug Fixes
+- **CRITICAL**: Added missing `require 'console'` in main module. Logger was nil because Console gem was not imported, causing `undefined method 'info' for nil` errors on worker initialization
+
+## 0.2.0
+
+### Bug Fixes
+- **CRITICAL**: Removed hidden ActiveSupport dependency. Replaced `safe_constantize` with `Object.const_get` + `NameError` handling
+- **CRITICAL**: Fixed validator mismatch: now validates `.perform_now` (class method) instead of `.perform` (instance method)
+- **CRITICAL**: Fixed race condition where entry could disappear from heap during execution. `reschedule` and `heap.push` now always execute after job processing
+- Added full exception backtrace to error logs for production debugging
+- Improved YAML security by removing `Symbol` from `permitted_classes`
+- Removed Mutex from graceful shutdown (anti-pattern in Async). Boolean assignment is atomic in MRI
+
+### Features
+- Added optional `logger` parameter to Runner constructor for custom loggers (Rails.logger, etc.)
+- Added `stop()` method for graceful shutdown
+- Added `running?()` method to check scheduler status
+
+### Breaking Changes
+- Job class validation now checks for `.perform_now` class method (was checking for `.perform` instance method)
+
+## 0.1.0
+
+- Initial release
+- Single event loop with min-heap timer (O(log N) scheduling)
+- Skip overlapping execution
+- Startup jitter to prevent thundering herd
+- Monotonic clock for interval jobs, wall clock for cron jobs
+- Deterministic worker sharding via Zlib.crc32
+- Semaphore-based concurrency control
+- Per-job timeout protection
+- Structured logging via Console

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Haydarov Roman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,193 @@
+# Async::Background
+
+A lightweight, production-grade cron/interval scheduler for Ruby's [Async](https://github.com/socketry/async) ecosystem. Designed for [Falcon](https://github.com/socketry/falcon) but works with any Async-based application.
+
+## What It Does
+
+- **Cron & interval scheduling** — single event loop + min-heap, scales to hundreds of jobs
+- **Dynamic job queue** — enqueue jobs at runtime via SQLite, pick up by background workers
+- **Delayed jobs** — schedule jobs for future execution with `perform_in` / `perform_at` (Sidekiq-like API)
+- **Multi-process safe** — deterministic worker sharding via `Zlib.crc32`, no duplicate execution
+- **Skip overlapping** — if a job is still running when its next tick arrives, the tick is skipped
+- **Timeout protection** — per-job configurable timeout via `Async::Task#with_timeout`
+- **Startup jitter** — random delay to prevent thundering herd after restart
+- **Optional metrics** — shared memory performance tracking with `async-utilization`
+
+## Requirements
+
+- **Ruby >= 3.3** — Fiber Scheduler production-ready ([why?](#why-ruby-33))
+- **Async ~> 2.0** — Fiber Scheduler-based concurrency
+- **Fugit ~> 1.0** — cron expression parsing
+
+## Installation
+
+```ruby
+# Gemfile
+gem "async-background"
+
+# Optional
+gem "sqlite3", "~> 2.0"           # for dynamic job queue
+gem "async-utilization", "~> 0.3"  # for metrics
+```
+
+## ➡️ [Get Started](docs/GET_STARTED.md)
+
+Step-by-step setup guide: schedule config, Falcon integration, Docker, dynamic queue, delayed jobs.
+
+---
+
+## Quick Example: Job Module
+
+Include `Async::Background::Job` for a Sidekiq-like interface:
+
+```ruby
+class SendEmailJob
+  include Async::Background::Job
+
+  def perform(user_id, template)
+    user = User.find(user_id)
+    Mailer.send(user, template)
+  end
+end
+
+# Immediate execution in the queue
+SendEmailJob.perform_async(user_id, "welcome")
+
+# Execute after 5 minutes
+SendEmailJob.perform_in(300, user_id, "reminder")
+
+# Execute at a specific time
+SendEmailJob.perform_at(Time.new(2026, 4, 1, 9, 0, 0), user_id, "scheduled")
+```
+
+Or use the lower-level API directly:
+
+```ruby
+Async::Background::Queue.enqueue(SendEmailJob, user_id, "welcome")
+Async::Background::Queue.enqueue_in(300, SendEmailJob, user_id, "reminder")
+Async::Background::Queue.enqueue_at(Time.new(2026, 4, 1, 9, 0, 0), SendEmailJob, user_id, "scheduled")
+```
+
+---
+
+## ⚠️ Important Notes
+
+### Docker: SQLite requires a named volume
+
+The SQLite database **must not** live on Docker's `overlay2` filesystem. The `overlay2` driver breaks coherence between `write()` and `mmap()`, which corrupts SQLite WAL under concurrent access.
+
+```yaml
+# docker-compose.yml
+volumes:
+  - queue-data:/app/tmp/queue   # ← named volume, NOT overlay2
+
+volumes:
+  queue-data:
+```
+
+Without this, you will get database crashes in multi-process mode. See [Get Started → Step 3](docs/GET_STARTED.md#step-3-docker) for details.
+
+### Fork safety
+
+SQLite connections **must not** cross `fork()` boundaries. Always open connections **after** fork (inside `container.run` block), never before. The gem handles this internally via lazy `ensure_connection`, but if you create a `Queue::Store` manually for schema setup, close it before fork:
+
+```ruby
+store = Async::Background::Queue::Store.new(path: db_path)
+store.ensure_database!
+store.close  # ← before fork
+```
+
+### Clock handling
+
+The `Clock` module provides shared time helpers used across the codebase:
+
+- **`monotonic_now`** (`CLOCK_MONOTONIC`) — for in-process intervals and durations, immune to NTP drift / wall-clock jumps
+- **`realtime_now`** (`CLOCK_REALTIME`) — for persisted timestamps (SQLite `run_at`, `created_at`, `locked_at`)
+
+Interval jobs use monotonic clock. Cron jobs use `Time.now` because "every day at 3am" must respect real time. These are different clocks by design.
+
+---
+
+## Architecture
+
+```
+schedule.yml
+     │
+     ▼
+ build_heap          ← parse config, validate, assign workers
+     │
+     ▼
+ MinHeap<Entry>      ← O(log N) push/pop, sorted by next_run_at
+     │
+     ▼
+ 1 scheduler loop    ← single Async task, sleeps until next entry
+     │
+     ▼
+ Semaphore           ← limits concurrent job execution
+     │
+     ▼
+ run_job             ← timeout, logging, error handling
+```
+
+### Queue Architecture
+
+```
+Producer (web/console)          Consumer (background worker)
+     │                                │
+     ▼                                ▼
+ Queue::Client                   Queue::Store.fetch
+     │                           (WHERE run_at <= now)
+     ├─ push(class, args, run_at)     │
+     ├─ push_in(delay, class, args)   ▼
+     └─ push_at(time, class, args)  run_queue_job
+     │                                │
+     ▼                                ▼
+ Queue::Store ──── SQLite ──── Queue::Notifier
+ (INSERT job)    (jobs table)    (IO.pipe wakeup)
+```
+
+## Schedule Config
+
+| Key | Required | Description |
+|---|---|---|
+| `class` | yes | Must include `Async::Background::Job` |
+| `every` | one of | Interval in seconds between runs |
+| `cron` | one of | Cron expression (parsed by Fugit) |
+| `timeout` | no | Max execution time in seconds (default: 30) |
+| `worker` | no | Pin to specific worker index. If omitted — `crc32(name) % total_workers` |
+
+## SQLite Pragmas
+
+| Pragma | Value | Why |
+|---|---|---|
+| `journal_mode` | WAL | Concurrent reads during writes |
+| `synchronous` | NORMAL | Safe with WAL, lower fsync overhead |
+| `mmap_size` | 256 MB | Fast reads ([requires proper filesystem](#docker-sqlite-requires-a-named-volume)) |
+| `cache_size` | 16000 pages | ~64 MB page cache |
+| `busy_timeout` | 5000 ms | Wait instead of failing on lock contention |
+
+## Metrics
+
+When `async-utilization` gem is available, metrics are collected in shared memory (`/tmp/async-background.shm`) with lock-free updates per worker.
+
+```ruby
+runner.metrics.values
+# => { total_runs: 142, total_successes: 140, total_failures: 2,
+#      total_timeouts: 0, total_skips: 5, active_jobs: 1,
+#      last_run_at: 1774445243, last_duration_ms: 1250 }
+
+# Read all workers at once (no server needed)
+Async::Background::Metrics.read_all(total_workers: 2)
+```
+
+Without the gem — metrics are silently disabled, zero overhead.
+
+## Why Ruby 3.3?
+
+- Ruby 3.0 introduced Fiber Scheduler but had critical bugs
+- Ruby 3.2 is the first production-ready release (per Samuel Williams)
+- `io-event >= 1.14` (pulled by latest `async`) requires Ruby `>= 3.3`
+
+## License
+
+MIT

data/async-background.gemspec

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative 'lib/async/background/version'
+
+Gem::Specification.new do |spec|
+  spec.name    = 'async-background'
+  spec.version = Async::Background::VERSION
+  spec.authors = ['Roman Hajdarov']
+  spec.email   = ['romnhajdarov@gmail.com']
+
+  spec.summary     = 'Lightweight heap-based cron/interval scheduler for Async.'
+  spec.description = 'A production-grade lightweight scheduler built on top of Async. ' \
+                     'Single event loop with min-heap timer, skip-overlapping execution, ' \
+                     'jitter, monotonic clock intervals, semaphore concurrency control, ' \
+                     'and deterministic worker sharding. Designed for Falcon but works ' \
+                     'with any Async-based application.'
+
+  spec.homepage = 'https://github.com/roman-haidarov/async-background'
+  spec.license  = 'MIT'
+
+  spec.metadata = {
+    'source_code_uri' => 'https://github.com/roman-haidarov/async-background',
+    'changelog_uri'   => 'https://github.com/roman-haidarov/async-background/blob/main/CHANGELOG.md',
+    'bug_tracker_uri' => 'https://github.com/roman-haidarov/async-background/issues'
+  }
+
+  spec.files         = Dir.glob('lib/**/*', base: __dir__) +
+                       %w[README.md CHANGELOG.md LICENSE async-background.gemspec]
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '>= 3.3'
+
+  spec.add_dependency 'async',   '~> 2.0'
+  spec.add_dependency 'console', '~> 1.0'
+  spec.add_dependency 'fugit',   '~> 1.0'
+
+  # Optional: add to your own Gemfile if you need these features
+  #   gem 'sqlite3',          '~> 2.0'  # dynamic job queue
+  #   gem 'async-utilization', '~> 0.3' # shared-memory worker metrics
+
+  spec.add_development_dependency 'rake',  '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.12'
+end

data/lib/async/background/queue/notifier.rb

@@ -4,7 +4,19 @@ module Async
   module Background
     module Queue
       class Notifier
-        IO_ERRORS = [IO::WaitReadable, EOFError, IOError].freeze
+        #  Error groups
+        WRITE_DROPPED = [
+          IO::WaitWritable,  # buffer full — consumer is behind, skip
+          Errno::EAGAIN,     # same as above on some platforms
+          IOError,           # our own writer end has been closed
+          Errno::EPIPE       # the reader end is gone (consumer crashed) — skip
+        ].freeze
+
+        READ_EXHAUSTED = [
+          IO::WaitReadable,  # nothing left in the buffer — normal exit
+          EOFError,          # writer end closed — no more data ever
+          IOError            # our own reader end has been closed
+        ].freeze
 
         attr_reader :reader, :writer
 
@@ -16,10 +28,10 @@ module Async
 
         def notify
           @writer.write_nonblock("\x01")
-        rescue IO::WaitWritable, Errno::EAGAIN
-          # pipe buffer full — consumer is already behind, skip
-        rescue IOError
-          # pipe closed
+        rescue *WRITE_DROPPED
+          # All write failures are non-fatal: the job is already in the
+          # store, and missing one wake-up only delays pickup by at most
+          # one poll interval.
         end
 
         def wait(timeout: nil)
@@ -53,7 +65,7 @@ module Async
         def drain
           loop do
             @reader.read_nonblock(256)
-          rescue *IO_ERRORS
+          rescue *READ_EXHAUSTED
             break
           end
           nil

data/lib/async/background/queue/store.rb

@@ -53,6 +53,7 @@ module Async
         def ensure_database!
           require_sqlite3
           db = SQLite3::Database.new(@path)
+          db.execute('PRAGMA busy_timeout = 5000')
           db.execute_batch(PRAGMAS.call(@mmap ? MMAP_SIZE : 0))
           db.execute_batch(SCHEMA)
           db.execute("PRAGMA wal_checkpoint(TRUNCATE)")
@@ -128,6 +129,7 @@ module Async
           require_sqlite3
           finalize_statements
           @db = SQLite3::Database.new(@path)
+          @db.execute('PRAGMA busy_timeout = 5000')
           @db.execute_batch(PRAGMAS.call(@mmap ? MMAP_SIZE : 0))
 
           unless @schema_checked

data/lib/async/background/version.rb

@@ -2,6 +2,6 @@
 
 module Async
   module Background
-    VERSION = '0.5.0'
+    VERSION = '0.5.1'
   end
 end

data/lib/async/background.rb

@@ -12,5 +12,6 @@ require_relative 'background/min_heap'
 require_relative 'background/entry'
 require_relative 'background/metrics'
 require_relative 'background/runner'
+require_relative 'background/queue/store'
 require_relative 'background/queue/client'
 require_relative 'background/job'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: async-background
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Roman Hajdarov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-31 00:00:00.000000000 Z
+date: 2026-04-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -90,6 +90,10 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- async-background.gemspec
 - lib/async/background.rb
 - lib/async/background/clock.rb
 - lib/async/background/entry.rb