async-background 1.0.2 → 1.1.1

data/lib/async/background/web/snapshot.rb

@@ -13,6 +13,20 @@ module Async
         include Clock
 
         CacheEntry = Data.define(:value, :created_at)
+        RAW_COLUMNS = { 'args' => :args_raw, 'options' => :options_raw }.freeze
+
+        ROW_KEYS = SQL::EXTRA_COLUMNS.to_h do |status, extra|
+          columns = SQL::BASE_COLUMNS + extra
+            [status, columns.map { |column| RAW_COLUMNS.fetch(column) { column.to_sym } }.freeze]
+        end.freeze
+
+        PAGING = {
+          executing: [SQL::EXECUTING, nil, nil].freeze,
+          claimed: [SQL::CLAIMED, nil, nil].freeze,
+          done: [SQL::DONE, SQL::DONE_AFTER, %i[finished_at id].freeze].freeze,
+          failed: [SQL::FAILED, SQL::FAILED_AFTER, %i[finished_at id].freeze].freeze,
+          pending: [SQL::PENDING, SQL::PENDING_AFTER, %i[run_at id].freeze].freeze
+        }.freeze
 
         def initialize(path:, counts_cache_ttl:)
           @path = path
@@ -65,26 +79,23 @@ module Async
         end
 
         def executing(limit:)
-          read_rows(SQL::EXECUTING, [limit]).map { |row| executing_row(row) }
+          list(:executing, limit: limit)
         end
 
         def claimed(limit:)
-          read_rows(SQL::CLAIMED, [limit]).map { |row| claimed_row(row) }
+          list(:claimed, limit: limit)
         end
 
         def recent_done(limit:, cursor: nil)
-          sql, binds = terminal_query(SQL::DONE, SQL::DONE_AFTER, limit, cursor)
-          read_rows(sql, binds).map { |row| done_row(row) }
+          list(:done, limit: limit, cursor: cursor)
         end
 
         def recent_failed(limit:, cursor: nil)
-          sql, binds = terminal_query(SQL::FAILED, SQL::FAILED_AFTER, limit, cursor)
-          read_rows(sql, binds).map { |row| failed_row(row) }
+          list(:failed, limit: limit, cursor: cursor)
         end
 
         def pending(limit:, cursor: nil)
-          sql, binds = pending_query(limit, cursor)
-          read_rows(sql, binds).map { |row| pending_row(row) }
+          list(:pending, limit: limit, cursor: cursor)
         end
 
         private
@@ -98,12 +109,12 @@ module Async
           SQLite3::Database.new(database_uri, uri: true)
         rescue LoadError
           raise
-        rescue StandardError => error
-          raise UnavailableError, "cannot open queue database: #{error.message}"
+        rescue StandardError => e
+          raise UnavailableError, "cannot open queue database: #{e.message}"
         end
 
         def database_uri
-          path = URI::DEFAULT_PARSER.escape(File.expand_path(@path)).gsub('?', '%3F')
+          path = URI::RFC2396_PARSER.escape(File.expand_path(@path)).gsub('?', '%3F')
           "file:#{path}?mode=ro"
         end
 
@@ -153,10 +164,10 @@ module Async
           {
             counts: {
               executing: db.get_first_value(SQL::OVERVIEW_EXECUTING).to_i,
-              claimed:   db.get_first_value(SQL::OVERVIEW_CLAIMED).to_i,
-              pending:   db.get_first_value(SQL::OVERVIEW_PENDING).to_i,
-              done:      db.get_first_value(SQL::OVERVIEW_DONE).to_i,
-              failed:    db.get_first_value(SQL::OVERVIEW_FAILED).to_i
+              claimed: db.get_first_value(SQL::OVERVIEW_CLAIMED).to_i,
+              pending: db.get_first_value(SQL::OVERVIEW_PENDING).to_i,
+              done: db.get_first_value(SQL::OVERVIEW_DONE).to_i,
+              failed: db.get_first_value(SQL::OVERVIEW_FAILED).to_i
             }.freeze,
             next_pending_run_at: db.get_first_value(SQL::OVERVIEW_NEXT_PENDING),
             data_version: db.get_first_value(Queue::SQL::DATA_VERSION).to_i,
@@ -164,81 +175,24 @@ module Async
           }
         end
 
-        def terminal_query(first_page_sql, next_page_sql, limit, cursor)
-          return [first_page_sql, [limit]] unless cursor
-
-          [next_page_sql, [cursor.fetch(:finished_at), cursor.fetch(:id), limit]]
-        end
-
-        def pending_query(limit, cursor)
-          return [SQL::PENDING, [limit]] unless cursor
-
-          [SQL::PENDING_AFTER, [cursor.fetch(:run_at), cursor.fetch(:id), limit]]
+        def list(status, limit:, cursor: nil)
+          sql, binds = page_query(status, limit, cursor)
+          keys = ROW_KEYS.fetch(status)
+          read_rows(sql, binds).map { |row| keys.zip(row).to_h }
         end
 
-        def executing_row(row)
-          {
-            id: row[0],
-            class_name: row[1],
-            args_raw: row[2],
-            options_raw: row[3],
-            started_at: row[4],
-            locked_by: row[5],
-            locked_at: row[6]
-          }
-        end
+        def page_query(status, limit, cursor)
+          first_sql, seek_sql, cursor_keys = PAGING.fetch(status)
+          return [first_sql, [limit]] unless cursor
 
-        def claimed_row(row)
-          {
-            id: row[0],
-            class_name: row[1],
-            args_raw: row[2],
-            options_raw: row[3],
-            locked_at: row[4],
-            locked_by: row[5]
-          }
-        end
-
-        def done_row(row)
-          {
-            id: row[0],
-            class_name: row[1],
-            args_raw: row[2],
-            options_raw: row[3],
-            finished_at: row[4],
-            duration_ms: row[5]
-          }
-        end
-
-        def failed_row(row)
-          {
-            id: row[0],
-            class_name: row[1],
-            args_raw: row[2],
-            options_raw: row[3],
-            finished_at: row[4],
-            duration_ms: row[5],
-            last_error_class: row[6],
-            last_error_message: row[7]
-          }
-        end
-
-        def pending_row(row)
-          {
-            id: row[0],
-            class_name: row[1],
-            args_raw: row[2],
-            options_raw: row[3],
-            created_at: row[4],
-            run_at: row[5]
-          }
+          [seek_sql, cursor_keys.map { |key| cursor.fetch(key) } << limit]
         end
 
         def require_sqlite3
           require 'sqlite3'
         rescue LoadError
           raise LoadError,
-                "sqlite3 gem is required for Async::Background::Web. " \
+                'sqlite3 gem is required for Async::Background::Web. ' \
                 "Add `gem 'sqlite3', '~> 2.0'` to your Gemfile."
         end
       end

data/lib/async/background/web/sql.rb

@@ -4,84 +4,78 @@ module Async
   module Background
     module Web
       module SQL
-        BEGIN_READ_TRANSACTION = 'BEGIN'.freeze
-        COMMIT = 'COMMIT'.freeze
-        ROLLBACK = 'ROLLBACK'.freeze
-        QUERY_ONLY = 'PRAGMA query_only = ON'.freeze
-        BUSY_TIMEOUT = 'PRAGMA busy_timeout = 2000'.freeze
+        BEGIN_READ_TRANSACTION = 'BEGIN'
+        COMMIT = 'COMMIT'
+        ROLLBACK = 'ROLLBACK'
+        QUERY_ONLY = 'PRAGMA query_only = ON'
+        BUSY_TIMEOUT = 'PRAGMA busy_timeout = 2000'
+        BASE_COLUMNS = %w[id class_name args options].freeze
 
-        OVERVIEW_EXECUTING = "SELECT COUNT(*) FROM jobs WHERE status = 'running' AND started_at IS NOT NULL".freeze
-        OVERVIEW_CLAIMED   = "SELECT COUNT(*) FROM jobs WHERE status = 'running' AND started_at IS NULL".freeze
-        OVERVIEW_PENDING   = "SELECT COUNT(*) FROM jobs WHERE status = 'pending'".freeze
-        OVERVIEW_DONE      = "SELECT COUNT(*) FROM jobs WHERE status = 'done'".freeze
-        OVERVIEW_FAILED    = "SELECT COUNT(*) FROM jobs WHERE status = 'failed'".freeze
-        OVERVIEW_NEXT_PENDING = "SELECT MIN(run_at) FROM jobs WHERE status = 'pending'".freeze
+        STATUS_PREDICATE = {
+          executing: "status = 'running' AND started_at IS NOT NULL",
+          claimed: "status = 'running' AND started_at IS NULL",
+          pending: "status = 'pending'",
+          done: "status = 'done'",
+          failed: "status = 'failed'"
+        }.freeze
 
-        EXECUTING = <<~SQL.freeze
-          SELECT id, class_name, args, options, started_at, locked_by, locked_at
-          FROM jobs
-          WHERE status = 'running' AND started_at IS NOT NULL
-          ORDER BY started_at, id
-          LIMIT ?
-        SQL
+        EXTRA_COLUMNS = {
+          executing: %w[started_at locked_by locked_at],
+          claimed: %w[locked_at locked_by],
+          pending: %w[created_at run_at],
+          done: %w[finished_at duration_ms],
+          failed: %w[finished_at duration_ms last_error_class last_error_message]
+        }.freeze
 
-        CLAIMED = <<~SQL.freeze
-          SELECT id, class_name, args, options, locked_at, locked_by
-          FROM jobs
-          WHERE status = 'running' AND started_at IS NULL
-          ORDER BY locked_at, id
-          LIMIT ?
-        SQL
+        KEYSET = {
+          executing: ['started_at', :asc],
+          claimed: ['locked_at', :asc],
+          pending: ['run_at', :asc],
+          done: ['finished_at', :desc],
+          failed: ['finished_at', :desc]
+        }.freeze
 
-        DONE = <<~SQL.freeze
-          SELECT id, class_name, args, options, finished_at, duration_ms
-          FROM jobs
-          WHERE status = 'done'
-          ORDER BY finished_at DESC, id DESC
-          LIMIT ?
-        SQL
+        ORDER_SQL = { asc: 'ORDER BY %<column>s, id', desc: 'ORDER BY %<column>s DESC, id DESC' }.freeze
+        SEEK_SQL = { asc: '(%<column>s, id) > (?, ?)', desc: '(%<column>s, id) < (?, ?)' }.freeze
 
-        DONE_AFTER = <<~SQL.freeze
-          SELECT id, class_name, args, options, finished_at, duration_ms
-          FROM jobs
-          WHERE status = 'done' AND (finished_at, id) < (?, ?)
-          ORDER BY finished_at DESC, id DESC
-          LIMIT ?
-        SQL
+        def self.columns_for(status)
+          (BASE_COLUMNS + EXTRA_COLUMNS.fetch(status)).join(', ')
+        end
 
-        FAILED = <<~SQL.freeze
-          SELECT id, class_name, args, options, finished_at, duration_ms,
-                 last_error_class, last_error_message
-          FROM jobs
-          WHERE status = 'failed'
-          ORDER BY finished_at DESC, id DESC
-          LIMIT ?
-        SQL
+        def self.count_query(status)
+          "SELECT COUNT(*) FROM jobs WHERE #{STATUS_PREDICATE.fetch(status)}".freeze
+        end
 
-        FAILED_AFTER = <<~SQL.freeze
-          SELECT id, class_name, args, options, finished_at, duration_ms,
-                 last_error_class, last_error_message
-          FROM jobs
-          WHERE status = 'failed' AND (finished_at, id) < (?, ?)
-          ORDER BY finished_at DESC, id DESC
-          LIMIT ?
-        SQL
+        def self.list_query(status, seek: false)
+          column, direction = KEYSET.fetch(status)
+          predicate = STATUS_PREDICATE.fetch(status)
+          predicate += " AND #{format(SEEK_SQL.fetch(direction), column: column)}" if seek
 
-        PENDING = <<~SQL.freeze
-          SELECT id, class_name, args, options, created_at, run_at
-          FROM jobs
-          WHERE status = 'pending'
-          ORDER BY run_at, id
-          LIMIT ?
-        SQL
+          <<~SQL.freeze
+            SELECT #{columns_for(status)}
+            FROM jobs
+            WHERE #{predicate}
+            #{format(ORDER_SQL.fetch(direction), column: column)}
+            LIMIT ?
+          SQL
+        end
 
-        PENDING_AFTER = <<~SQL.freeze
-          SELECT id, class_name, args, options, created_at, run_at
-          FROM jobs
-          WHERE status = 'pending' AND (run_at, id) > (?, ?)
-          ORDER BY run_at, id
-          LIMIT ?
-        SQL
+        OVERVIEW_EXECUTING = count_query(:executing)
+        OVERVIEW_CLAIMED = count_query(:claimed)
+        OVERVIEW_PENDING = count_query(:pending)
+        OVERVIEW_DONE = count_query(:done)
+        OVERVIEW_FAILED = count_query(:failed)
+        OVERVIEW_NEXT_PENDING = "SELECT MIN(run_at) FROM jobs WHERE #{STATUS_PREDICATE.fetch(:pending)}".freeze
+
+        EXECUTING = list_query(:executing)
+        CLAIMED = list_query(:claimed)
+        DONE = list_query(:done)
+        FAILED = list_query(:failed)
+        PENDING = list_query(:pending)
+
+        DONE_AFTER = list_query(:done, seek: true)
+        FAILED_AFTER = list_query(:failed, seek: true)
+        PENDING_AFTER = list_query(:pending, seek: true)
       end
     end
   end

data/lib/async/background/web/stream.rb

@@ -26,41 +26,13 @@ module Async
           end
 
           yield frame
-          last_yield = monotonic_now
-          unavailable_announced = false
-
-          loop do
-            sleep_for_poll
-
-            begin
-              new_version = @hub.current_version
-
-              if new_version != version
-                version = new_version
-                yield @hub.frame_for(version)
-                last_yield = monotonic_now
-              elsif (monotonic_now - last_yield) >= @heartbeat_seconds
-                yield EventHub::HEARTBEAT_FRAME
-                last_yield = monotonic_now
-              end
-
-              unavailable_announced = false
-            rescue ClosedError
-              break
-            rescue UnavailableError
-              unless unavailable_announced
-                yield EventHub::UNAVAILABLE_FRAME
-                unavailable_announced = true
-                last_yield = monotonic_now
-              end
-            end
-          end
+          stream_updates(version, monotonic_now) { |event| yield event }
         rescue Errno::EPIPE, Errno::ECONNRESET, IOError
           nil
-        rescue StandardError => error
+        rescue StandardError => e
           @logger&.error(
-            "[async-background-web] SSE stream terminated: " \
-            "#{error.class}: #{error.message}"
+            '[async-background-web] SSE stream terminated: ' \
+            "#{e.class}: #{e.message}"
           )
           nil
         end
@@ -76,6 +48,54 @@ module Async
         def sleep_for_poll
           sleep(@poll_seconds)
         end
+
+        def stream_updates(version, last_yield)
+          unavailable_announced = false
+          loop do
+            sleep_for_poll
+            state = next_state(version, last_yield, unavailable_announced) { |event| yield event }
+            break unless state
+
+            version, last_yield, unavailable_announced = state
+          end
+        end
+
+        def next_state(version, last_yield, unavailable_announced)
+          current_version = @hub.current_version
+          return updated_state(current_version) { |event| yield event } if current_version != version
+          return heartbeat_state(version) { |event| yield event } if heartbeat_due?(last_yield)
+
+          [version, last_yield, false]
+        rescue ClosedError
+          nil
+        rescue UnavailableError
+          announce_unavailable(version, last_yield, unavailable_announced) { |event| yield event }
+        end
+
+        def updated_state(version)
+          yield @hub.frame_for(version)
+          [version, monotonic_now, false]
+        end
+
+        def heartbeat_state(version)
+          yield EventHub::HEARTBEAT_FRAME
+          [version, monotonic_now, false]
+        end
+
+        def heartbeat_due?(last_yield)
+          (monotonic_now - last_yield) >= @heartbeat_seconds
+        end
+
+        def announce_unavailable(version, last_yield, announced)
+          return [version, last_yield, true] if announced
+
+          yield_unavailable { |event| yield event }
+          [version, monotonic_now, true]
+        end
+
+        def yield_unavailable
+          yield EventHub::UNAVAILABLE_FRAME
+        end
       end
     end
   end

data/lib/async/background/web.rb

@@ -37,7 +37,7 @@ module Async
 
       def configuration
         @configuration or raise NotConfiguredError,
-                               'Async::Background::Web is not configured. Call Async::Background::Web.configure.'
+                                'Async::Background::Web is not configured. Call Async::Background::Web.configure.'
       end
 
       def reset!

data/lib/async/background.rb

@@ -1,12 +1,11 @@
 # frozen_string_literal: true
 
-require 'async'
-require 'async/semaphore'
 require 'console'
 require 'fugit'
 require 'tmpdir'
 
 require_relative 'background/version'
+require_relative 'background/runtime'
 require_relative 'background/clock'
 require_relative 'background/min_heap'
 require_relative 'background/entry'

metadata

@@ -1,31 +1,30 @@
 --- !ruby/object:Gem::Specification
 name: async-background
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.1
 platform: ruby
 authors:
 - Roman Hajdarov
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-15 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: async
+  name: console
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
-  name: console
+  name: fugit
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
@@ -39,33 +38,33 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.0'
 - !ruby/object:Gem::Dependency
-  name: fugit
+  name: base64
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '0.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '0.2'
 - !ruby/object:Gem::Dependency
-  name: base64
+  name: async
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
-  type: :runtime
+        version: '2.0'
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -128,10 +127,11 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '0.5'
-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.
+description: 'A production-grade lightweight background job scheduler built on the
+  Fiber::Scheduler interface itself, not on any one implementation: it runs under
+  Async/Falcon, Itsi, or anything else that installs a scheduler. Single event loop
+  with min-heap timer, skip-overlapping execution, jitter, monotonic clock intervals,
+  semaphore concurrency control, and deterministic worker sharding.'
 email:
 - romnhajdarov@gmail.com
 executables: []
@@ -157,12 +157,22 @@ files:
 - lib/async/background/queue/sql.rb
 - lib/async/background/queue/store.rb
 - lib/async/background/runner.rb
+- lib/async/background/runner/lifecycle.rb
 - lib/async/background/runner/queue_execution.rb
 - lib/async/background/runner/schedule.rb
+- lib/async/background/runtime.rb
+- lib/async/background/runtime/notification.rb
+- lib/async/background/runtime/semaphore.rb
+- lib/async/background/runtime/task.rb
+- lib/async/background/runtime/task_group.rb
+- lib/async/background/scheduler.rb
 - lib/async/background/version.rb
 - lib/async/background/web.rb
 - lib/async/background/web/app.rb
 - lib/async/background/web/assets.rb
+- lib/async/background/web/assets/app.css
+- lib/async/background/web/assets/app.js
+- lib/async/background/web/assets/index.html
 - lib/async/background/web/auth.rb
 - lib/async/background/web/configuration.rb
 - lib/async/background/web/cursor.rb
@@ -183,7 +193,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
@@ -198,8 +207,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.22
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
-summary: Lightweight heap-based cron/interval scheduler for Async.
+summary: Lightweight heap-based cron/interval scheduler for any Fiber scheduler.
 test_files: []