async-background 0.6.1 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f4392db5a752c9a07da3c140fedec1ad2234950ccce48d127eb7c4de188bfee
-  data.tar.gz: 31d3c8f2cc5b303361c081e95162d13e7ed04917f7ae93187abd9c3b3c175445
+  metadata.gz: f1890dfac1632afedbbb20c367d4d770c3037f6201bb6fac77396f07481df477
+  data.tar.gz: 1b435f70b2fd290bd569c0c081d19ae94250a181367ada7d3b4d157c213fd5b8
 SHA512:
-  metadata.gz: 90225c64139b4ec18ed9bb72bf82161f9642f14f39f9031ad1d64ddf1b6a074bb2b7690722017054aac521fda6395ddcae755ed17fb264fc32620639a7a64219
-  data.tar.gz: b7ff64e05abc6e5a9a4f0122c86f4e73b2f7f170978213b307104b96bd907384a5ab16ff61db96bb50c91bb5999cf98f0cc0318601741bd3b78357b6a0302f27
+  metadata.gz: 0e9c2398241b48d0cc8fe66ed0b227cca3c93a5969e7f753c0a8dbb08a41462626d73709ae9eece1a254f8567f4a9044958e96a2658a77ab8f6b11bbdb6a1c14
+  data.tar.gz: 702016f46a3bbaa255735defcc2746baafe66a26400d2ad9525b80d89848970143998a706ceb4644519433cfcd558d9936c0caae4f968e335a2f8b8496afdec1

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,6 +3,12 @@
 module Async
   module Background
     module Job
+      DEFAULT_TIMEOUT = 120
+
+      Options = Data.define(:timeout) do
+        def initialize(timeout: DEFAULT_TIMEOUT) = super(timeout: Integer(timeout))
+      end
+
       def self.included(base)
         base.extend(ClassMethods)
       end
@@ -12,17 +18,23 @@ module Async
           new.perform(*args)
         end
 
-        def perform_async(*args)
-          Async::Background::Queue.enqueue(self, *args)
+        def perform_async(*args, options: {})
+          Async::Background::Queue.enqueue(self, *args, options: options)
         end
 
-        def perform_in(delay, *args)
-          Async::Background::Queue.enqueue_in(delay, self, *args)
+        def perform_in(delay, *args, options: {})
+          Async::Background::Queue.enqueue_in(delay, self, *args, options: options)
         end
 
-        def perform_at(time, *args)
-          Async::Background::Queue.enqueue_at(time, self, *args)
+        def perform_at(time, *args, options: {})
+          Async::Background::Queue.enqueue_at(time, self, *args, options: options)
         end
+
+        def options(**values)
+          @options = Options.new(**values).to_h
+        end
+
+        def resolve_options = @options || {}
       end
 
       def perform(*args)

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,53 @@ 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 = [])
+        def push_in(delay, class_name, args = [], options: {})
           run_at = realtime_now + delay.to_f
-          push(class_name, args, run_at)
+          push(class_name, args, run_at, 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)
+          merged = build_options(job_class, options)
+          default_client.push(resolve_class_name(job_class), args, nil, options: merged)
         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)
+          merged = build_options(job_class, options)
+          default_client.push_in(delay, resolve_class_name(job_class), args, options: merged)
         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)
+          merged = build_options(job_class, options)
+          default_client.push_at(time, resolve_class_name(job_class), args, options: merged)
         end
 
         private
 
+        def build_options(job_class, call_site_options)
+          merged = resolve_options(job_class).merge!(call_site_options.compact)
+          return EMPTY_OPTIONS if merged.empty?
+
+          Job::Options.new(**merged).to_h
+        end
+
         def ensure_configured!
           raise "Async::Background::Queue not configured" unless default_client
         end
@@ -60,6 +72,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,
@@ -45,6 +46,7 @@ module Async
         def initialize(path: self.class.default_path, mmap: true)
           @path = path
           @mmap = mmap
+          @pragma_sql = PRAGMAS.call(mmap ? MMAP_SIZE : 0).freeze
           @db   = nil
           @schema_checked = false
           @last_cleanup_at = nil
@@ -54,17 +56,18 @@ module Async
           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(@pragma_sql)
           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)
+          options_json = options.empty? ? nil : JSON.generate(options)
+          @enqueue_stmt.execute(class_name, JSON.generate(args), options_json, realtime_now, run_at)
           @db.last_insert_row_id
         end
 
@@ -84,7 +87,8 @@ module Async
           return unless row
 
           maybe_cleanup
-          { id: row[0], class_name: row[1], args: JSON.parse(row[2]) }
+          options = row[3] ? JSON.parse(row[3], symbolize_names: true) : {}
+          { id: row[0], class_name: row[1], args: JSON.parse(row[2]), options: options }
         rescue
           @db.execute("ROLLBACK") rescue nil
           raise
@@ -135,10 +139,11 @@ module Async
           finalize_statements
           @db = SQLite3::Database.new(@path)
           @db.execute('PRAGMA busy_timeout = 5000')
-          @db.execute_batch(PRAGMAS.call(@mmap ? MMAP_SIZE : 0))
+          @db.execute_batch(@pragma_sql)
 
           unless @schema_checked
             @db.execute_batch(SCHEMA)
+            @db.execute("ALTER TABLE jobs ADD COLUMN options TEXT") rescue nil
             @schema_checked = true
           end
 
@@ -148,7 +153,7 @@ module Async
 
         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,7 +165,7 @@ 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 = ?")
@@ -175,11 +180,11 @@ module Async
         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, @requeue_stmt, @cleanup_stmt].each do |s|
+            s&.close rescue next
           end
+
+          @enqueue_stmt = @fetch_stmt = @complete_stmt = @fail_stmt = @requeue_stmt = @cleanup_stmt = nil
         end
 
         def maybe_cleanup
@@ -193,7 +198,6 @@ module Async
             @db.execute("PRAGMA incremental_vacuum")
           end
         end
-
       end
     end
   end

data/lib/async/background/runner.rb

@@ -114,11 +114,13 @@ module Async
         class_name = job[:class_name]
         args       = job[:args]
         klass      = resolve_job_class(class_name)
+        opts       = Job::Options.new(**job[:options])
+        timeout    = opts.timeout
 
         metrics.job_started(nil)
         t = monotonic_now
 
-        job_task.with_timeout(DEFAULT_TIMEOUT) { klass.perform_now(*args) }
+        job_task.with_timeout(timeout) { klass.perform_now(*args) }
 
         duration = monotonic_now - t
         metrics.job_finished(nil, duration)
@@ -130,7 +132,7 @@ module Async
       rescue ::Async::TimeoutError
         metrics.job_timed_out(nil)
         @queue_store.fail(job[:id])
-        logger.error('Async::Background') { "queue(#{class_name}): timed out" }
+        logger.error('Async::Background') { "queue(#{class_name}): timed out after #{timeout}s" }
       rescue => e
         metrics.job_failed(nil, e)
         @queue_store.fail(job[:id])

data/lib/async/background/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: async-background
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.6.2
 platform: ruby
 authors:
 - Roman Hajdarov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-08 00:00:00.000000000 Z
+date: 2026-04-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async