async-background 0.7.1 → 1.0.0

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

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'cursor'
+
+module Async
+  module Background
+    module Web
+      class Serializer
+        EMPTY_OPTIONS = {}.freeze
+        EMPTY_ARGS = [].freeze
+
+        def initialize(config)
+          @config = config
+        end
+
+        def overview(snapshot_data, metrics_data = nil)
+          payload = {
+            counts: snapshot_data.fetch(:counts),
+            next_pending_run_at: snapshot_data[:next_pending_run_at],
+            data_version: snapshot_data.fetch(:data_version),
+            generated_at: snapshot_data.fetch(:generated_at)
+          }
+          payload[:metrics] = metrics_data if metrics_data
+          payload
+        end
+
+        def executing(rows)
+          rows.map { |row| executing_item(row) }
+        end
+
+        def claimed(rows)
+          rows.map { |row| claimed_item(row) }
+        end
+
+        def done(rows)
+          page(rows.map { |row| done_item(row) }) { |item| Cursor.encode_finished(item[:finished_at], item[:id]) }
+        end
+
+        def failed(rows)
+          page(rows.map { |row| failed_item(row) }) { |item| Cursor.encode_finished(item[:finished_at], item[:id]) }
+        end
+
+        def pending(rows)
+          page(rows.map { |row| pending_item(row) }) { |item| Cursor.encode_pending(item[:run_at], item[:id]) }
+        end
+
+        private
+
+        def page(items)
+          {items: items, next_cursor: items.empty? ? nil : yield(items.last)}
+        end
+
+        def executing_item(row)
+          args, args_count = args_for(row[:args_raw])
+          {
+            id: row[:id],
+            class_name: row[:class_name],
+            args: args,
+            args_count: args_count,
+            options: parse_options(row[:options_raw]),
+            started_at: row[:started_at],
+            locked_by: row[:locked_by],
+            locked_at: row[:locked_at]
+          }
+        end
+
+        def claimed_item(row)
+          args, args_count = args_for(row[:args_raw])
+          {
+            id: row[:id],
+            class_name: row[:class_name],
+            args: args,
+            args_count: args_count,
+            options: parse_options(row[:options_raw]),
+            locked_at: row[:locked_at],
+            locked_by: row[:locked_by]
+          }
+        end
+
+        def done_item(row)
+          args, args_count = args_for(row[:args_raw])
+          {
+            id: row[:id],
+            class_name: row[:class_name],
+            args: args,
+            args_count: args_count,
+            options: parse_options(row[:options_raw]),
+            finished_at: row[:finished_at],
+            duration_ms: row[:duration_ms]
+          }
+        end
+
+        def failed_item(row)
+          args, args_count = args_for(row[:args_raw])
+          {
+            id: row[:id],
+            class_name: row[:class_name],
+            args: args,
+            args_count: args_count,
+            options: parse_options(row[:options_raw]),
+            finished_at: row[:finished_at],
+            duration_ms: row[:duration_ms],
+            last_error_class: row[:last_error_class],
+            last_error_message: row[:last_error_message]
+          }
+        end
+
+        def pending_item(row)
+          args, args_count = args_for(row[:args_raw])
+          {
+            id: row[:id],
+            class_name: row[:class_name],
+            args: args,
+            args_count: args_count,
+            options: parse_options(row[:options_raw]),
+            created_at: row[:created_at],
+            run_at: row[:run_at]
+          }
+        end
+
+        def args_for(raw)
+          if raw.nil? || raw.empty? || raw == '[]'
+            return [@config.expose_args ? redact(EMPTY_ARGS) : nil, 0]
+          end
+
+          parsed = parse_json(raw)
+          count = parsed.is_a?(Array) ? parsed.length : 0
+          return [nil, count] unless @config.expose_args
+
+          [redact(parsed), count]
+        end
+
+        def redact(args)
+          redactor = @config.redact_args
+          redactor ? redactor.call(args) : args
+        end
+
+        def parse_options(raw)
+          return EMPTY_OPTIONS if raw.nil? || raw.empty? || raw == '{}'
+
+          parsed = parse_json(raw)
+          parsed.is_a?(Hash) ? parsed : EMPTY_OPTIONS
+        end
+
+        def parse_json(raw)
+          JSON.parse(raw)
+        rescue JSON::ParserError
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+require_relative '../clock'
+require_relative '../queue/sql'
+require_relative 'sql'
+
+module Async
+  module Background
+    module Web
+      class Snapshot
+        include Clock
+
+        CacheEntry = Data.define(:value, :created_at)
+
+        def initialize(path:, counts_cache_ttl:)
+          @path = path
+          @overview_cache_ttl = counts_cache_ttl
+          @mutex = Mutex.new
+          @db = nil
+          @overview_cache = nil
+        end
+
+        def open!
+          @mutex.synchronize do
+            return self if connected?
+
+            db = open_database
+            configure_database(db)
+            @db = db
+          rescue StandardError
+            db&.close unless db&.closed?
+            raise
+          end
+          self
+        end
+
+        def close
+          @mutex.synchronize do
+            @db&.close unless @db&.closed?
+            @db = nil
+            @overview_cache = nil
+          end
+          self
+        end
+
+        def closed?
+          @mutex.synchronize { !connected? }
+        end
+
+        def data_version
+          with_database { |db| db.get_first_value(Queue::SQL::DATA_VERSION).to_i }
+        end
+
+        def overview(force: false)
+          with_database do |db|
+            now = monotonic_now
+            return @overview_cache.value if !force && overview_cache_current?(now)
+
+            value = read_transaction(db) { overview_from(db) }.freeze
+            @overview_cache = CacheEntry.new(value, now)
+            value
+          end
+        end
+
+        def executing(limit:)
+          read_rows(SQL::EXECUTING, [limit]).map { |row| executing_row(row) }
+        end
+
+        def claimed(limit:)
+          read_rows(SQL::CLAIMED, [limit]).map { |row| claimed_row(row) }
+        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) }
+        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) }
+        end
+
+        def pending(limit:, cursor: nil)
+          sql, binds = pending_query(limit, cursor)
+          read_rows(sql, binds).map { |row| pending_row(row) }
+        end
+
+        private
+
+        def connected?
+          @db && !@db.closed?
+        end
+
+        def open_database
+          require_sqlite3
+          SQLite3::Database.new(database_uri, uri: true)
+        rescue LoadError
+          raise
+        rescue StandardError => error
+          raise UnavailableError, "cannot open queue database: #{error.message}"
+        end
+
+        def database_uri
+          path = URI::DEFAULT_PARSER.escape(File.expand_path(@path)).gsub('?', '%3F')
+          "file:#{path}?mode=ro"
+        end
+
+        def configure_database(db)
+          db.execute(SQL::BUSY_TIMEOUT)
+          db.execute(SQL::QUERY_ONLY)
+        end
+
+        def with_database
+          @mutex.synchronize do
+            raise ClosedError, 'snapshot is closed' unless connected?
+
+            yield @db
+          end
+        rescue ClosedError, UnavailableError
+          raise
+        rescue StandardError
+          raise UnavailableError, 'queue database is unavailable'
+        end
+
+        def read_rows(sql, binds)
+          with_database { |db| read_transaction(db) { db.execute(sql, binds) } }
+        end
+
+        def read_transaction(db)
+          db.execute(SQL::BEGIN_READ_TRANSACTION)
+          result = yield
+          db.execute(SQL::COMMIT)
+          result
+        rescue StandardError
+          rollback(db)
+          raise
+        end
+
+        def rollback(db)
+          db.execute(SQL::ROLLBACK)
+        rescue StandardError
+          nil
+        end
+
+        def overview_cache_current?(now)
+          cache = @overview_cache
+          cache && (now - cache.created_at) < @overview_cache_ttl
+        end
+
+        def overview_from(db)
+          {
+            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
+            }.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,
+            generated_at: realtime_now
+          }
+        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]]
+        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 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]
+          }
+        end
+
+        def require_sqlite3
+          require 'sqlite3'
+        rescue LoadError
+          raise LoadError,
+                "sqlite3 gem is required for Async::Background::Web. " \
+                "Add `gem 'sqlite3', '~> 2.0'` to your Gemfile."
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+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
+
+        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
+
+        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
+
+        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
+
+        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
+
+        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
+
+        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
+
+        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
+
+        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
+
+        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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Async
+  module Background
+    module Web
+      class Stream
+        def initialize(hub, heartbeat_seconds:, retry_ms:)
+          @hub = hub
+          @heartbeat_seconds = heartbeat_seconds
+          @retry_ms = retry_ms
+        end
+
+        def each
+          subscription, initial_frame = @hub.subscribe
+          yield "retry: #{@retry_ms}\n\n"
+          yield initial_frame
+
+          loop do
+            frame = subscription.pop(timeout: @heartbeat_seconds)
+            break if frame.nil? && subscription.closed?
+
+            yield(frame || EventHub::HEARTBEAT_FRAME)
+          end
+        rescue Errno::EPIPE, IOError
+          nil
+        rescue ClosedError, UnavailableError
+          safe_yield(EventHub::UNAVAILABLE_FRAME) { |frame| yield frame }
+          nil
+        ensure
+          @hub.unsubscribe(subscription) if subscription
+        end
+
+        private
+
+        def safe_yield(frame)
+          yield frame
+        rescue Errno::EPIPE, IOError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/async/background/web.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+begin
+  require 'rack'
+rescue LoadError
+  raise LoadError,
+        "Async::Background::Web requires 'rack'. " \
+        "Add `gem 'rack', '~> 3.0'` to your Gemfile."
+end
+
+require_relative 'web/errors'
+require_relative 'web/configuration'
+require_relative 'web/sql'
+require_relative 'web/cursor'
+require_relative 'web/request'
+require_relative 'web/response'
+require_relative 'web/snapshot'
+require_relative 'web/metrics_reader'
+require_relative 'web/serializer'
+require_relative 'web/auth'
+require_relative 'web/router'
+require_relative 'web/event_hub'
+require_relative 'web/stream'
+require_relative 'web/assets'
+require_relative 'web/app'
+
+module Async
+  module Background
+    module Web
+      module_function
+
+      def configure
+        @configuration ||= Configuration.new
+        yield @configuration if block_given?
+        @configuration
+      end
+
+      def configuration
+        @configuration or raise NotConfiguredError,
+                               'Async::Background::Web is not configured. Call Async::Background::Web.configure.'
+      end
+
+      def reset!
+        @configuration = nil
+      end
+
+      def app
+        App.new(configuration)
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: async-background
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Roman Hajdarov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-02 00:00:00.000000000 Z
+date: 2026-06-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -52,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -80,6 +94,40 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: async-utilization
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.3'
+    - - "<"
+      - !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
@@ -102,11 +150,32 @@ files:
 - lib/async/background/min_heap.rb
 - lib/async/background/queue/client.rb
 - lib/async/background/queue/notifier.rb
+- lib/async/background/queue/options.rb
+- lib/async/background/queue/schema.rb
 - lib/async/background/queue/socket_notifier.rb
 - lib/async/background/queue/socket_waker.rb
+- lib/async/background/queue/sql.rb
 - lib/async/background/queue/store.rb
 - lib/async/background/runner.rb
+- lib/async/background/runner/queue_execution.rb
+- lib/async/background/runner/schedule.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/auth.rb
+- lib/async/background/web/configuration.rb
+- lib/async/background/web/cursor.rb
+- lib/async/background/web/errors.rb
+- lib/async/background/web/event_hub.rb
+- lib/async/background/web/metrics_reader.rb
+- lib/async/background/web/request.rb
+- lib/async/background/web/response.rb
+- lib/async/background/web/router.rb
+- lib/async/background/web/serializer.rb
+- lib/async/background/web/snapshot.rb
+- lib/async/background/web/sql.rb
+- lib/async/background/web/stream.rb
 homepage: https://github.com/roman-haidarov/async-background
 licenses:
 - MIT