async-background 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f4392db5a752c9a07da3c140fedec1ad2234950ccce48d127eb7c4de188bfee
-  data.tar.gz: 31d3c8f2cc5b303361c081e95162d13e7ed04917f7ae93187abd9c3b3c175445
+  metadata.gz: 851bdc350f52df868547200fe10a0d93b06b692b605c6e761b28262e2691a4df
+  data.tar.gz: 8eccc004e5250df5349135a979a59e52f7450ee356245e8cab17b4b6e2a9a9f6
 SHA512:
-  metadata.gz: 90225c64139b4ec18ed9bb72bf82161f9642f14f39f9031ad1d64ddf1b6a074bb2b7690722017054aac521fda6395ddcae755ed17fb264fc32620639a7a64219
-  data.tar.gz: b7ff64e05abc6e5a9a4f0122c86f4e73b2f7f170978213b307104b96bd907384a5ab16ff61db96bb50c91bb5999cf98f0cc0318601741bd3b78357b6a0302f27
+  metadata.gz: 7ce63c6e58d96670add9cbfc438ab5cb33d2472c3ef6d4484cde4682f3416749f946cadc1fe00333e1e6e68b1b861df8d6d9cb88a7e520f48f73ecc9b4c86265
+  data.tar.gz: e4f7fc4fb560dba97580f0bd1ea446ade22edb219e1fba7d725ecb4b798b2feddf76b5266f3e408516b33d880046c481ca7b0746ae08accd70a1665466143019

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.6.2
+
+### Features
+- **Configurable timeout for queue jobs** — queue jobs previously used a hardcoded 30-second timeout (`DEFAULT_TIMEOUT`). Now configurable via `options` hash at two levels:
+  ```ruby
+  # Class-level default
+  class HeavyImportJob
+    include Async::Background::Job
+    options timeout: 600
+
+    def perform(user_id) = # ...
+  end
+
+  # Call-site override (wins over class-level)
+  HeavyImportJob.perform_async(user_id, options: { timeout: 120 })
+  ```
+  Priority: call-site `options:` → class-level `options` → `DEFAULT_TIMEOUT` (30s). Options are merged at enqueue time so the runner simply reads the final value from the payload
+- **`options:` hash across the entire enqueue chain** — single extensible contract from `perform_async` through `Client` down to `Store`. Currently supports `:timeout`, designed to accommodate future keys (e.g. `:retry`) without API changes
+- **`Job::Options` schema via `Data.define`** — declares known option keys with types and defaults. Unknown keys raise `ArgumentError`, invalid types raise `TypeError`. No manual validation code
+- **`options TEXT` column in SQLite** — stores the merged options hash as JSON. Extensible without schema changes when new options are added
+
+### Improvements
+- **Queue timeout logged on failure** — `run_queue_job` error log now includes actual timeout value: `"timed out after 120s"` instead of generic `"timed out"`
+- **Idempotent schema migration** — existing databases get `ALTER TABLE jobs ADD COLUMN options TEXT` on first connection, wrapped in `rescue nil` for safe re-runs. New databases include the column in `CREATE TABLE`
+
 ## 0.6.1
 
 ### Bug Fixes

data/lib/async/background/job.rb

@@ -3,29 +3,70 @@
 module Async
   module Background
     module Job
+      DEFAULT_TIMEOUT = 120
+      BACKOFFS        = %i[fixed linear exponential].freeze
+      DEFAULT_JITTER_FOR = { fixed: 0.0, linear: 0.0, exponential: 0.5 }.freeze
+
+      Options = Data.define(:timeout, :retry, :retry_delay, :backoff, :attempt, :jitter) do
+        def initialize(timeout: DEFAULT_TIMEOUT, retry: 0, retry_delay: nil, backoff: :fixed, attempt: nil, jitter: nil)
+          timeout     = Integer(timeout)
+          retries     = Integer(binding.local_variable_get(:retry) || 0)
+          retry_delay = Float(retry_delay) unless retry_delay.nil?
+          backoff     = backoff.to_sym
+          attempt     = Integer(attempt) unless attempt.nil?
+          jitter      = Float(jitter) unless jitter.nil?
+
+          raise ArgumentError, "timeout must be > 0"                        unless timeout.positive?
+          raise ArgumentError, "retry must be >= 0"                         if     retries.negative?
+          raise ArgumentError, "attempt must be >= 0"                       if     attempt && attempt.negative?
+          raise ArgumentError, "backoff must be one of #{BACKOFFS.inspect}" unless BACKOFFS.include?(backoff)
+          if retries.positive?
+            raise ArgumentError, "retry_delay is required when retry > 0" if retry_delay.nil?
+            raise ArgumentError, "retry_delay must be > 0"                unless retry_delay.positive?
+          end
+          raise ArgumentError, "jitter must be in [0, 1]" if jitter && !(0.0..1.0).cover?(jitter)
+
+          super(timeout:, retry: retries, retry_delay:, backoff:, attempt:, jitter:)
+        end
+
+        def retry?          = self.retry.positive?
+        def attempts_made   = attempt || 0
+        def next_attempt    = attempts_made + 1
+        def with_attempt(n) = with(attempt: Integer(n))
+        def next_retry_delay(for_attempt = next_attempt, rng: Random)
+          raise ArgumentError, "attempt must be > 0" unless for_attempt.positive?
+          raise ArgumentError, "retry_delay must be configured" if retry_delay.nil?
+
+          base = case backoff
+          when :fixed       then retry_delay
+          when :linear      then retry_delay * for_attempt
+          when :exponential then retry_delay * (2**(for_attempt - 1))
+          end
+
+          factor = jitter || DEFAULT_JITTER_FOR[backoff]
+          factor.zero? ? base : base * (1 + rng.rand * factor)
+        end
+      end
+
       def self.included(base)
         base.extend(ClassMethods)
       end
 
       module ClassMethods
-        def perform_now(*args)
-          new.perform(*args)
-        end
+        def perform_now(*args) = new.perform(*args)
 
-        def perform_async(*args)
-          Async::Background::Queue.enqueue(self, *args)
-        end
+        def perform_async(*args, options: {})     = Async::Background::Queue.enqueue(self, *args, options: options)
+        def perform_in(delay, *args, options: {}) = Async::Background::Queue.enqueue_in(delay, self, *args, options: options)
+        def perform_at(time, *args, options: {})  = Async::Background::Queue.enqueue_at(time, self, *args, options: options)
 
-        def perform_in(delay, *args)
-          Async::Background::Queue.enqueue_in(delay, self, *args)
+        def options(**values)
+          @options = Options.new(**values).to_h.compact
         end
 
-        def perform_at(time, *args)
-          Async::Background::Queue.enqueue_at(time, self, *args)
-        end
+        def resolve_options = @options || {}
       end
 
-      def perform(*args)
+      def perform(*)
         raise NotImplementedError, "#{self.class} must implement #perform"
       end
     end

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

@@ -5,6 +5,8 @@ require_relative '../clock'
 module Async
   module Background
     module Queue
+      EMPTY_OPTIONS = {}.freeze
+
       class Client
         include Clock
 
@@ -13,43 +15,59 @@ module Async
           @notifier = notifier
         end
 
-        def push(class_name, args = [], run_at = nil)
-          id = @store.enqueue(class_name, args, run_at)
+        def push(class_name, args = [], run_at = nil, options: {})
+          id = @store.enqueue(class_name, args, run_at, options: options)
           @notifier&.notify_all
           id
         end
 
-        def push_in(delay, class_name, args = [])
-          run_at = realtime_now + delay.to_f
-          push(class_name, args, run_at)
+        def push_in(delay, class_name, args = [], options: {})
+          push(class_name, args, realtime_now + delay.to_f, options: options)
         end
 
-        def push_at(time, class_name, args = [])
+        def push_at(time, class_name, args = [], options: {})
           run_at = time.respond_to?(:to_f) ? time.to_f : time
-          push(class_name, args, run_at)
+          push(class_name, args, run_at, options: options)
         end
       end
 
       class << self
         attr_accessor :default_client
 
-        def enqueue(job_class, *args)
+        def enqueue(job_class, *args, options: {})
           ensure_configured!
-          default_client.push(resolve_class_name(job_class), args)
+          default_client.push(resolve_class_name(job_class), args, nil, options: build_options(job_class, options))
         end
 
-        def enqueue_in(delay, job_class, *args)
+        def enqueue_in(delay, job_class, *args, options: {})
           ensure_configured!
-          default_client.push_in(delay, resolve_class_name(job_class), args)
+          default_client.push_in(delay, resolve_class_name(job_class), args, options: build_options(job_class, options))
         end
 
-        def enqueue_at(time, job_class, *args)
+        def enqueue_at(time, job_class, *args, options: {})
           ensure_configured!
-          default_client.push_at(time, resolve_class_name(job_class), args)
+          default_client.push_at(time, resolve_class_name(job_class), args, options: build_options(job_class, options))
         end
 
         private
 
+        RETRY_KEYS = %i[retry retry_delay backoff jitter].freeze
+        private_constant :RETRY_KEYS
+
+        def build_options(job_class, call_site)
+          call_site ||= {}
+          merged = resolve_options(job_class).merge(call_site.compact)
+          apply_retry_overrides!(merged, call_site)
+
+          merged.empty? ? EMPTY_OPTIONS : Job::Options.new(**merged).to_h.compact
+        end
+
+        def apply_retry_overrides!(merged, call_site)
+          return unless RETRY_KEYS.any? { |k| call_site.key?(k) && !call_site[k].nil? }
+
+          RETRY_KEYS.each { |k| merged[k] = call_site[k] if call_site.key?(k) }
+        end
+
         def ensure_configured!
           raise "Async::Background::Queue not configured" unless default_client
         end
@@ -60,6 +78,12 @@ module Async
 
           raise ArgumentError, "#{job_class} must include Async::Background::Job"
         end
+
+        def resolve_options(job_class)
+          return {} unless job_class.respond_to?(:resolve_options)
+
+          job_class.resolve_options.dup
+        end
       end
     end
   end

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

@@ -15,6 +15,7 @@ module Async
             id         INTEGER PRIMARY KEY,
             class_name TEXT    NOT NULL,
             args       TEXT    NOT NULL DEFAULT '[]',
+            options    TEXT,
             status     TEXT    NOT NULL DEFAULT 'pending',
             created_at REAL    NOT NULL,
             run_at     REAL    NOT NULL,
@@ -43,52 +44,41 @@ module Async
         attr_reader :path
 
         def initialize(path: self.class.default_path, mmap: true)
-          @path = path
-          @mmap = mmap
-          @db   = nil
-          @schema_checked = false
+          @path            = path
+          @pragma_sql      = PRAGMAS.call(mmap ? MMAP_SIZE : 0).freeze
+          @db              = nil
+          @schema_checked  = false
           @last_cleanup_at = nil
         end
 
         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))
+          configure_database(db)
           db.execute_batch(SCHEMA)
           db.execute("PRAGMA wal_checkpoint(TRUNCATE)")
           db.close
           @schema_checked = true
         end
 
-        def enqueue(class_name, args = [], run_at = nil)
+        def enqueue(class_name, args = [], run_at = nil, options: {})
           ensure_connection
-          run_at ||= realtime_now
-          @enqueue_stmt.execute(class_name, JSON.generate(args), realtime_now, run_at)
+          now = realtime_now
+          @enqueue_stmt.execute(class_name, JSON.generate(args), dump_options(options), now, run_at || now)
           @db.last_insert_row_id
         end
 
         def fetch(worker_id)
           ensure_connection
           now = realtime_now
-          @db.execute("BEGIN IMMEDIATE")
 
-          begin
-            results = @fetch_stmt.execute(worker_id, now, now)
-            row = results.first
-          ensure
-            @fetch_stmt.reset! rescue nil
-          end
-
-          @db.execute("COMMIT")
+          row = transaction { with_stmt(@fetch_stmt) { |s| s.execute(worker_id, now, now).first } }
           return unless row
 
           maybe_cleanup
-          { id: row[0], class_name: row[1], args: JSON.parse(row[2]) }
-        rescue
-          @db.execute("ROLLBACK") rescue nil
-          raise
+          { id: row[0], class_name: row[1], args: JSON.parse(row[2]), options: load_options(row[3]) }
         end
+
         def complete(job_id)
           ensure_connection
           @complete_stmt.execute(job_id)
@@ -99,6 +89,24 @@ module Async
           @fail_stmt.execute(job_id)
         end
 
+        def retry_or_fail(job_id, fallback_options: nil)
+          ensure_connection
+
+          transaction do
+            stored = with_stmt(@retry_state_stmt) { |s| load_options(s.execute(job_id).first&.first) }
+            policy = stored.empty? ? normalize_options(fallback_options) : Job::Options.new(**stored)
+
+            if policy&.retry? && policy.next_attempt <= policy.retry
+              advanced = policy.with_attempt(policy.next_attempt)
+              @retry_stmt.execute(realtime_now + advanced.next_retry_delay(advanced.attempt), dump_options(advanced.to_h.compact), job_id)
+              :retried
+            else
+              @fail_stmt.execute(job_id)
+              :failed
+            end
+          end
+        end
+
         def recover(worker_id)
           ensure_connection
           @requeue_stmt.execute(worker_id)
@@ -134,11 +142,11 @@ 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))
+          configure_database(@db)
 
           unless @schema_checked
             @db.execute_batch(SCHEMA)
+            @db.execute("ALTER TABLE jobs ADD COLUMN options TEXT") rescue nil
             @schema_checked = true
           end
 
@@ -146,9 +154,45 @@ module Async
           @last_cleanup_at = monotonic_now
         end
 
+        def configure_database(db)
+          db.execute("PRAGMA busy_timeout = 5000")
+          db.execute_batch(@pragma_sql)
+        end
+
+        def transaction
+          @db.execute("BEGIN IMMEDIATE")
+          result = yield
+          @db.execute("COMMIT")
+          result
+        rescue
+          @db.execute("ROLLBACK") rescue nil
+          raise
+        end
+
+        def with_stmt(stmt)
+          yield stmt
+        ensure
+          stmt.reset! rescue nil
+        end
+
+        def dump_options(options)
+          options.empty? ? nil : JSON.generate(options)
+        end
+
+        def load_options(json)
+          json ? JSON.parse(json, symbolize_names: true) : {}
+        end
+
+        def normalize_options(options)
+          return if options.nil?
+          return options if options.is_a?(Job::Options)
+
+          Job::Options.new(**options)
+        end
+
         def prepare_statements
           @enqueue_stmt = @db.prepare(
-            "INSERT INTO jobs (class_name, args, created_at, run_at) VALUES (?, ?, ?, ?)"
+            "INSERT INTO jobs (class_name, args, options, created_at, run_at) VALUES (?, ?, ?, ?, ?)"
           )
 
           @fetch_stmt = @db.prepare(<<~SQL)
@@ -160,26 +204,30 @@ module Async
               ORDER BY run_at, id
               LIMIT 1
             )
-            RETURNING id, class_name, args
+            RETURNING id, class_name, args, options
           SQL
 
-          @complete_stmt = @db.prepare("UPDATE jobs SET status = 'done' WHERE id = ?")
-          @fail_stmt     = @db.prepare("UPDATE jobs SET status = 'failed' WHERE id = ?")
-
+          @complete_stmt    = @db.prepare("UPDATE jobs SET status = 'done',   locked_by = NULL, locked_at = NULL WHERE id = ?")
+          @fail_stmt        = @db.prepare("UPDATE jobs SET status = 'failed', locked_by = NULL, locked_at = NULL WHERE id = ?")
+          @retry_state_stmt = @db.prepare("SELECT options FROM jobs WHERE id = ?")
+          @retry_stmt       = @db.prepare(
+            "UPDATE jobs SET status = 'pending', locked_by = NULL, locked_at = NULL, run_at = ?, options = ? WHERE id = ?"
+          )
           @requeue_stmt = @db.prepare(
             "UPDATE jobs SET status = 'pending', locked_by = NULL, locked_at = NULL " \
             "WHERE status = 'running' AND locked_by = ?"
           )
-
           @cleanup_stmt = @db.prepare("DELETE FROM jobs WHERE status = 'done' AND created_at < ?")
         end
 
         def finalize_statements
-          %i[enqueue_stmt fetch_stmt complete_stmt fail_stmt requeue_stmt cleanup_stmt].each do |name|
-            stmt = instance_variable_get(:"@#{name}")
-            stmt&.close rescue nil
-            instance_variable_set(:"@#{name}", nil)
+          [@enqueue_stmt, @fetch_stmt, @complete_stmt, @fail_stmt,
+           @retry_state_stmt, @retry_stmt, @requeue_stmt, @cleanup_stmt].each do |stmt|
+            stmt&.close rescue next
           end
+
+          @enqueue_stmt = @fetch_stmt = @complete_stmt = @fail_stmt = nil
+          @retry_state_stmt = @retry_stmt = @requeue_stmt = @cleanup_stmt = nil
         end
 
         def maybe_cleanup
@@ -188,12 +236,8 @@ module Async
 
           @last_cleanup_at = now
           @cleanup_stmt.execute(realtime_now - CLEANUP_AGE)
-
-          if @db.changes > 100
-            @db.execute("PRAGMA incremental_vacuum")
-          end
+          @db.execute("PRAGMA incremental_vacuum") if @db.changes > 100
         end
-
       end
     end
   end

data/lib/async/background/runner.rb

@@ -69,14 +69,13 @@ module Async
         @listen_queue = false
         return unless queue_socket_dir
 
-        # Lazy require — only loaded when queue is actually used
+        isolated = ENV.fetch("ISOLATION_FORKS", "").split(",").map(&:to_i)
+        return if isolated.include?(worker_index)
+
         require_relative 'queue/store'
         require_relative 'queue/socket_waker'
         require_relative 'queue/client'
 
-        isolated = ENV.fetch("ISOLATION_FORKS", "").split(",").map(&:to_i)
-        return if isolated.include?(worker_index)
-
         @listen_queue = true
         @queue_store  = Queue::Store.new(
           path: queue_db_path || Queue::Store.default_path,
@@ -112,38 +111,55 @@ module Async
 
       def run_queue_job(job_task, job)
         class_name = job[:class_name]
-        args       = job[:args]
         klass      = resolve_job_class(class_name)
+        options    = parse_job_options(job[:options])
 
         metrics.job_started(nil)
-        t = monotonic_now
-
-        job_task.with_timeout(DEFAULT_TIMEOUT) { klass.perform_now(*args) }
+        started = monotonic_now
+        job_task.with_timeout(options.timeout) { klass.perform_now(*job[:args]) }
+        duration = monotonic_now - started
 
-        duration = monotonic_now - t
         metrics.job_finished(nil, duration)
         @queue_store.complete(job[:id])
-
-        logger.info('Async::Background') {
-          "queue(#{class_name}): completed in #{duration.round(2)}s"
-        }
+        logger.info('Async::Background') { "queue(#{class_name}): completed in #{duration.round(2)}s" }
+      rescue ConfigError => e
+        metrics.job_failed(nil, e) if options
+        @queue_store.fail(job[:id])
+        logger.error('Async::Background') { "queue(#{class_name}): #{e.class} #{e.message}" }
       rescue ::Async::TimeoutError
         metrics.job_timed_out(nil)
-        @queue_store.fail(job[:id])
-        logger.error('Async::Background') { "queue(#{class_name}): timed out" }
+        handle_queue_failure(job, options, "timed out after #{options.timeout}s", backtrace: nil)
       rescue => e
         metrics.job_failed(nil, e)
-        @queue_store.fail(job[:id])
-        logger.error('Async::Background') {
-          "queue(#{class_name}): #{e.class} #{e.message}\n#{e.backtrace.join("\n")}"
-        }
+        handle_queue_failure(job, options, "#{e.class} #{e.message}", backtrace: e.backtrace)
+      end
+
+      def parse_job_options(raw)
+        Job::Options.new(**(raw || {}))
+      rescue ArgumentError, TypeError => e
+        raise ConfigError, "invalid queue options: #{e.message}"
+      end
+
+      def handle_queue_failure(job, options, message, backtrace:)
+        result = @queue_store.retry_or_fail(job[:id], fallback_options: options)
+        class_name = job[:class_name]
+
+        if result == :retried
+          @queue_waker&.signal
+          attempt = options.next_attempt
+          logger.warn('Async::Background') do
+            "queue(#{class_name}): #{message}; retry #{attempt}/#{options.retry}"
+          end
+        else
+          tail = backtrace ? "\n#{backtrace.join("\n")}" : ''
+          logger.error('Async::Background') { "queue(#{class_name}): #{message}#{tail}" }
+        end
       end
 
       def resolve_job_class(class_name)
-        raise ConfigError, "empty class name in queue job" if class_name.nil? || class_name.strip.empty?
+        raise ConfigError, "empty class name in queue job" if class_name.nil? || class_name.to_s.strip.empty?
 
-        names = class_name.split("::")
-        klass = names.reduce(Object) do |mod, name|
+        klass = class_name.split("::").reduce(Object) do |mod, name|
           raise ConfigError, "unknown class: #{class_name}" unless mod.const_defined?(name, false)
           mod.const_get(name, false)
         end
@@ -257,14 +273,12 @@ module Async
         class_name = config&.dig('class').to_s.strip
         raise ConfigError, "[#{name}] missing class" if class_name.empty?
 
-        begin
-          job_class = Object.const_get(class_name)
-        rescue NameError
-          raise ConfigError, "[#{name}] unknown class: #{class_name}"
+        job_class = begin
+          resolve_job_class(class_name)
+        rescue ConfigError => e
+          raise ConfigError, "[#{name}] #{e.message}"
         end
 
-        raise ConfigError, "[#{name}] #{class_name} must include Async::Background::Job" unless job_class.respond_to?(:perform_now)
-
         interval = config['every']&.then { |v|
           int = v.to_i
           raise ConfigError, "[#{name}] 'every' must be > 0" unless int.positive?
@@ -277,12 +291,13 @@ module Async
 
         raise ConfigError, "[#{name}] specify 'every' or 'cron'" unless interval || cron
 
-        {
-          job_class: job_class,
-          interval: interval,
-          cron: cron,
-          timeout: config.fetch('timeout', DEFAULT_TIMEOUT).to_i
-        }
+        timeout = begin
+          Job::Options.new(timeout: config.fetch('timeout', DEFAULT_TIMEOUT)).timeout
+        rescue ArgumentError, TypeError => e
+          raise ConfigError, "[#{name}] #{e.message}"
+        end
+
+        { job_class: job_class, interval: interval, cron: cron, timeout: timeout }
       end
 
       def run_job(job_task, entry)

data/lib/async/background/version.rb

@@ -2,6 +2,6 @@
 
 module Async
   module Background
-    VERSION = '0.6.1'
+    VERSION = '0.7.0'
   end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: async-background
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Roman Hajdarov
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-08 00:00:00.000000000 Z
+date: 2026-04-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -114,7 +113,6 @@ 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
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -129,8 +127,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.27
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Lightweight heap-based cron/interval scheduler for Async.
 test_files: []