kaal 0.4.0 → 0.6.0

data/lib/kaal/config/configuration.rb

@@ -12,7 +12,8 @@ module Kaal
   # @example Basic configuration
   #   Kaal.configure do |config|
   #     config.tick_interval = 5
-  #     config.backend = Kaal::Backend::RedisAdapter.new(Redis.new(url: ENV["REDIS_URL"]))
+  #     config.backend_config = { url: ENV['KAAL_BACKEND_URL'] }
+  #     config.backend = :redis
   #   end
   class Configuration
     # Default values for all configuration options
@@ -23,15 +24,17 @@ module Kaal
       lease_ttl: 125, # Must be >= window_lookback + tick_interval (120 + 5 = 125)
       namespace: 'kaal',
       backend: nil,
+      backend_config: {},
       logger: nil,
       time_zone: nil,
       enable_log_dispatch_registry: false,
       enable_dispatch_recovery: true,
       recovery_window: 86_400, # 24 hours in seconds
       recovery_startup_jitter: 5, # max random delay in seconds
-      scheduler_config_path: 'config/scheduler.yml',
+      scheduler_config_path: 'config/kaal-scheduler.yml',
       scheduler_conflict_policy: :error,
-      scheduler_missing_file_policy: :warn
+      scheduler_missing_file_policy: :warn,
+      delayed_job_allowed_class_prefixes: []
     }.freeze
 
     ##
@@ -40,6 +43,8 @@ module Kaal
     # @return [Configuration] a new instance with all defaults set
     def initialize
       @values = DEFAULTS.dup
+      @backend_name = nil
+      @backend_runtime_context = nil
     end
 
     ##
@@ -69,6 +74,15 @@ module Kaal
       validation_errors
     end
 
+    # Non-fatal configuration warnings.
+    #
+    # @return [Array<String>] warning messages
+    def validation_warnings
+      warnings = []
+      add_delayed_job_security_warning(warnings)
+      warnings
+    end
+
     ##
     # Validate the configuration settings.
     # Raises errors if required settings are invalid.
@@ -79,6 +93,10 @@ module Kaal
       errors = validation_errors
       raise ConfigurationError, errors.join('; ') if errors.any?
 
+      validation_warnings.each do |warning|
+        @values[:logger]&.warn(warning)
+      end
+
       self
     end
 
@@ -97,6 +115,7 @@ module Kaal
         lease_ttl: @values[:lease_ttl],
         namespace: @values[:namespace],
         backend: backend&.class&.name,
+        backend_config: Kaal::Support::HashTools.deep_dup(@values[:backend_config]),
         logger: logger&.class&.name,
         time_zone: @values[:time_zone],
         enable_log_dispatch_registry: @values[:enable_log_dispatch_registry],
@@ -105,7 +124,8 @@ module Kaal
         recovery_startup_jitter: @values[:recovery_startup_jitter],
         scheduler_config_path: @values[:scheduler_config_path],
         scheduler_conflict_policy: @values[:scheduler_conflict_policy],
-        scheduler_missing_file_policy: @values[:scheduler_missing_file_policy]
+        scheduler_missing_file_policy: @values[:scheduler_missing_file_policy],
+        delayed_job_allowed_class_prefixes: @values[:delayed_job_allowed_class_prefixes]
       }
     end
 
@@ -118,6 +138,7 @@ module Kaal
       add_window_lookahead_error(errors)
       add_lease_ttl_error(errors)
       add_namespace_error(errors)
+      add_backend_config_error(errors)
       add_lease_ttl_window_error(errors)
       add_scheduler_config_path_error(errors)
       add_scheduler_conflict_policy_error(errors)
@@ -159,6 +180,12 @@ module Kaal
       errors << 'namespace cannot be blank'
     end
 
+    def add_backend_config_error(errors)
+      return if @values[:backend_config].is_a?(Hash)
+
+      errors << 'backend_config must be a hash'
+    end
+
     def add_lease_ttl_window_error(errors)
       lease_ttl = @values[:lease_ttl].to_i
       window_lookback = @values[:window_lookback].to_i
@@ -191,6 +218,13 @@ module Kaal
       errors << 'scheduler_missing_file_policy must be :warn or :error'
     end
 
+    def add_delayed_job_security_warning(warnings)
+      warning = Kaal::Config::DelayedJobSecurityPolicy.warning_for(self)
+      return unless warning
+
+      warnings << warning
+    end
+
     def handle_known_key(method_name)
       name = method_name.to_s
       setter = name.end_with?('=')
@@ -202,26 +236,81 @@ module Kaal
 
     def set_value(key, value)
       @values[key] = normalize_value(key, value)
+      rebuild_symbolic_backend_if_needed(key)
     end
 
     def normalize_value(key, value)
-      return value unless @values.key?(key)
-
       case key
+      when :backend
+        normalize_backend(value)
+      when :backend_config
+        value.is_a?(Hash) ? Kaal::Support::HashTools.symbolize_keys(Kaal::Support::HashTools.deep_dup(value)) : (value || {})
       when :tick_interval, :window_lookback, :window_lookahead, :lease_ttl
         value.to_i
       when :namespace, :scheduler_config_path
         value.to_s
       when :time_zone
-        value&.to_s
+        normalize_optional_string(value)
       when :enable_log_dispatch_registry
-        value ? true : false
+        !!value
       when :scheduler_conflict_policy, :scheduler_missing_file_policy
-        value&.to_sym
+        normalize_optional_symbol(value)
+      when :delayed_job_allowed_class_prefixes
+        normalize_delayed_job_allowed_class_prefixes(value)
       else
         value
       end
     end
+
+    def normalize_backend(value)
+      unless value.is_a?(String) || value.is_a?(Symbol)
+        @backend_name = nil
+        return value
+      end
+
+      normalized_backend_name = Kaal::Config::BackendFactory.normalize_name(value)
+      backend = Kaal::Config::BackendFactory.build(
+        normalized_backend_name,
+        backend_config: @values[:backend_config],
+        namespace: @values[:namespace],
+        runtime_context: @backend_runtime_context
+      )
+      @backend_name = normalized_backend_name
+      backend
+    end
+
+    def apply_backend_runtime_context(runtime_context)
+      @backend_runtime_context = runtime_context
+    end
+    public :apply_backend_runtime_context
+
+    def rebuild_symbolic_backend_if_needed(key)
+      return unless @backend_name
+      return unless %i[backend_config namespace backend].include?(key)
+      return if key == :backend
+
+      @values[:backend] = Kaal::Config::BackendFactory.build(
+        @backend_name,
+        backend_config: @values[:backend_config],
+        namespace: @values[:namespace],
+        runtime_context: @backend_runtime_context
+      )
+    end
+
+    def normalize_delayed_job_allowed_class_prefixes(value)
+      Array(value).filter_map do |entry|
+        normalized_entry = entry.to_s.strip
+        normalized_entry unless normalized_entry.empty?
+      end
+    end
+
+    def normalize_optional_string(value)
+      value&.to_s
+    end
+
+    def normalize_optional_symbol(value)
+      value&.to_sym
+    end
   end
 
   ##

data/lib/kaal/config/delayed_job_security_policy.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# Copyright Codevedas Inc. 2025-present
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+module Kaal
+  module Config
+    # Evaluates whether delayed-job class resolution is too open for the
+    # current deployment shape and returns the matching warning message.
+    module DelayedJobSecurityPolicy
+      NON_SHARED_BACKEND_CLASS_NAMES = ['NilClass', 'Kaal::Backend::MemoryAdapter', 'Kaal::Backend::NullAdapter'].freeze
+      WARNING_MESSAGE = 'Delayed jobs resolve stored job_class values at dispatch time. ' \
+                        'delayed_job_allowed_class_prefixes is empty, so class resolution is unrestricted on this shared backend. ' \
+                        'Configure a restrictive delayed_job_allowed_class_prefixes list for production deployments.'
+
+      module_function
+
+      def warning_for(configuration)
+        return unless production_like_environment?
+        return unless shared_delayed_job_backend?(configuration.backend)
+        return unless Array(configuration.delayed_job_allowed_class_prefixes).empty?
+
+        WARNING_MESSAGE
+      end
+
+      def production_like_environment?(env: ENV, rails: current_rails)
+        rails_env = rails_environment(rails)
+        return rails_env.production? if rails_env
+
+        %w[RACK_ENV HANAMI_ENV APP_ENV RAILS_ENV RUBY_ENV].any? do |key|
+          env.fetch(key, nil).to_s.strip == 'production'
+        end
+      rescue StandardError
+        false
+      end
+
+      def shared_delayed_job_backend?(backend)
+        backend_class = backend.class
+        return false if NON_SHARED_BACKEND_CLASS_NAMES.include?(backend_class.name)
+
+        backend_class.instance_method(:delayed_store).owner.name != 'Kaal::Backend::Adapter'
+      rescue StandardError
+        false
+      end
+
+      def current_rails
+        return unless defined?(::Rails)
+
+        ::Rails
+      end
+
+      def rails_environment(rails)
+        rails.env
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/kaal/config/file_loader.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+# Copyright Codevedas Inc. 2025-present
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+require 'erb'
+require 'yaml'
+
+module Kaal
+  module Config
+    # Loads Kaal runtime configuration from config/kaal.yml and KAAL_* env vars.
+    class FileLoader
+      # Normalizes a single environment variable value into the requested config type.
+      class EnvValue
+        def initialize(value)
+          @value = value.to_s.strip
+        end
+
+        def coerce(key:, env_name:)
+          case key
+          when :tick_interval, :window_lookback, :window_lookahead, :lease_ttl, :recovery_window, :recovery_startup_jitter
+            coerce_integer(env_name)
+          when :enable_log_dispatch_registry, :enable_dispatch_recovery
+            coerce_boolean(env_name)
+          when :scheduler_conflict_policy, :scheduler_missing_file_policy
+            @value.to_sym
+          when :delayed_job_allowed_class_prefixes
+            @value.split(',').map(&:strip).reject(&:empty?)
+          else
+            @value
+          end
+        end
+
+        private
+
+        def coerce_boolean(env_name)
+          normalized_value = @value.downcase
+          return true if %w[1 true yes on].include?(normalized_value)
+          return false if %w[0 false no off].include?(normalized_value)
+
+          raise Kaal::ConfigurationError, "ENV #{env_name} must be a boolean"
+        end
+
+        def coerce_integer(env_name)
+          raise Kaal::ConfigurationError, "ENV #{env_name} must be an integer" unless @value.match?(/\A-?\d+\z/)
+
+          @value.to_i
+        end
+      end
+
+      ENV_KEY_MAP = {
+        'KAAL_BACKEND' => :backend,
+        'KAAL_NAMESPACE' => :namespace,
+        'KAAL_TICK_INTERVAL' => :tick_interval,
+        'KAAL_WINDOW_LOOKBACK' => :window_lookback,
+        'KAAL_WINDOW_LOOKAHEAD' => :window_lookahead,
+        'KAAL_LEASE_TTL' => :lease_ttl,
+        'KAAL_SCHEDULER_CONFIG_PATH' => :scheduler_config_path,
+        'KAAL_ENABLE_LOG_DISPATCH_REGISTRY' => :enable_log_dispatch_registry,
+        'KAAL_ENABLE_DISPATCH_RECOVERY' => :enable_dispatch_recovery,
+        'KAAL_RECOVERY_WINDOW' => :recovery_window,
+        'KAAL_RECOVERY_STARTUP_JITTER' => :recovery_startup_jitter,
+        'KAAL_TIME_ZONE' => :time_zone,
+        'KAAL_SCHEDULER_CONFLICT_POLICY' => :scheduler_conflict_policy,
+        'KAAL_SCHEDULER_MISSING_FILE_POLICY' => :scheduler_missing_file_policy,
+        'KAAL_DELAYED_JOB_ALLOWED_CLASS_PREFIXES' => :delayed_job_allowed_class_prefixes
+      }.freeze
+      CONFIG_KEY_TO_ENV_KEY = ENV_KEY_MAP.invert.freeze
+      CONFIGURATION_ASSIGNERS = {
+        namespace: ->(config, value) { config.namespace = value },
+        tick_interval: ->(config, value) { config.tick_interval = value },
+        window_lookback: ->(config, value) { config.window_lookback = value },
+        window_lookahead: ->(config, value) { config.window_lookahead = value },
+        lease_ttl: ->(config, value) { config.lease_ttl = value },
+        scheduler_config_path: ->(config, value) { config.scheduler_config_path = value },
+        enable_log_dispatch_registry: ->(config, value) { config.enable_log_dispatch_registry = value },
+        enable_dispatch_recovery: ->(config, value) { config.enable_dispatch_recovery = value },
+        recovery_window: ->(config, value) { config.recovery_window = value },
+        recovery_startup_jitter: ->(config, value) { config.recovery_startup_jitter = value },
+        time_zone: ->(config, value) { config.time_zone = value },
+        scheduler_conflict_policy: ->(config, value) { config.scheduler_conflict_policy = value },
+        scheduler_missing_file_policy: ->(config, value) { config.scheduler_missing_file_policy = value },
+        delayed_job_allowed_class_prefixes: ->(config, value) { config.delayed_job_allowed_class_prefixes = value },
+        logger: ->(config, value) { config.logger = value }
+      }.freeze
+
+      def initialize(configuration:, runtime_context:, env: ENV)
+        @configuration = configuration
+        @runtime_context = runtime_context
+        @env = env
+        @config_key_to_env_key = CONFIG_KEY_TO_ENV_KEY
+      end
+
+      def load(path: 'config/kaal.yml')
+        absolute_path = @runtime_context.resolve_path(path)
+        payload = File.exist?(absolute_path) ? parse_yaml(absolute_path) : {}
+        merged = merge_environment_config(payload)
+        merged = apply_env_overrides(merged)
+        apply_configuration(merged)
+        @configuration.validate!
+        @configuration
+      end
+
+      private
+
+      def parse_yaml(path)
+        rendered = render_yaml(path)
+        parsed = YAML.safe_load(rendered, aliases: true) || {}
+        raise Kaal::ConfigurationError, "Expected Kaal config YAML root to be a mapping in #{path}" unless parsed.is_a?(Hash)
+
+        Kaal::Support::HashTools.stringify_keys(parsed)
+      rescue Psych::Exception => e
+        raise Kaal::ConfigurationError, "Failed to parse Kaal config YAML at #{path}: #{e.message}"
+      end
+
+      def render_yaml(path)
+        ERB.new(File.read(path), trim_mode: '-').result
+      rescue StandardError, SyntaxError => e
+        raise Kaal::ConfigurationError, "Failed to evaluate Kaal config ERB at #{path}: #{e.message}"
+      end
+
+      def merge_environment_config(payload)
+        defaults = hash_section(payload['defaults'])
+        environment = hash_section(payload[@runtime_context.environment_name])
+
+        Kaal::Support::HashTools.deep_merge(defaults, environment)
+      end
+
+      def hash_section(value)
+        case value
+        in Hash
+          Kaal::Support::HashTools.stringify_keys(Kaal::Support::HashTools.deep_dup(value))
+        in nil
+          {}
+        else
+          raise Kaal::ConfigurationError, 'Kaal config sections must be mappings'
+        end
+      end
+
+      def apply_env_overrides(config)
+        merged = Kaal::Support::HashTools.deep_dup(config)
+
+        ENV_KEY_MAP.each do |env_key, config_key|
+          next unless @env.key?(env_key)
+
+          merged[config_key.to_s] = coerce_env_value(config_key, @env.fetch(env_key))
+        end
+
+        backend_url = @env['KAAL_BACKEND_URL']&.to_s&.strip
+        if @env.key?('KAAL_BACKEND_URL')
+          backend_config = hash_section(merged['backend_config'])
+          if backend_config.key?('connection')
+            backend_config['connection'] = backend_url
+          else
+            backend_config['url'] = backend_url
+          end
+          merged['backend_config'] = backend_config
+        end
+
+        merged
+      end
+
+      def coerce_env_value(key, value)
+        EnvValue.new(value).coerce(key:, env_name: @config_key_to_env_key.fetch(key))
+      end
+
+      def apply_configuration(config)
+        normalized = Kaal::Support::HashTools.symbolize_keys(config)
+        backend_config = normalized.delete(:backend_config) || {}
+        backend_name = normalized.delete(:backend)
+        @configuration.apply_backend_runtime_context(@runtime_context)
+
+        normalized.each do |key, value|
+          apply_configuration_value(key, value)
+        end
+
+        @configuration.backend_config = backend_config
+        @configuration.backend = backend_name if backend_name
+      end
+
+      def apply_configuration_value(key, value)
+        CONFIGURATION_ASSIGNERS[key]&.call(@configuration, value)
+      end
+    end
+  end
+end

data/lib/kaal/config.rb

@@ -5,6 +5,9 @@
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
 require 'kaal/config/configuration'
+require 'kaal/config/backend_factory'
+require 'kaal/config/delayed_job_security_policy'
+require 'kaal/config/file_loader'
 require 'kaal/config/scheduler_config_error'
 require 'kaal/config/scheduler_time_zone_resolver'
 

data/lib/kaal/core/coordinator.rb

@@ -16,21 +16,12 @@ module Kaal
   #
   # The coordinator:
   # 1. Runs a background thread on tick_interval
-  # 2. For each registered cron, calculates due fire times within the window
-  # 3. Attempts to acquire a distributed lease for each due time
-  # 4. Calls the enqueue callback if the lease is acquired
-  # 5. Supports graceful shutdown and re-entrancy for testing
-  #
-  # @example Start the coordinator
-  #   coordinator = Kaal::Coordinator.new
-  #   coordinator.start!
-  #
-  # @example Manual tick execution (for testing)
-  #   coordinator.tick!
-  #
-  # @example Stop the coordinator
-  #   coordinator.stop!
+  # 2. Calculates due cron fire times and acquires distributed leases for them
+  # 3. Dispatches claimed work and supports graceful shutdown and test re-entrancy
   class Coordinator
+    DELAYED_JOB_BATCH_SIZE = 100
+    DELAYED_JOB_MAX_BATCHES_PER_TICK = 10
+    DELAYED_JOB_DELETE_CONFIRMATION_JITTER_MAX = 0.05
     ##
     # Initialize a new Coordinator instance.
     #
@@ -174,6 +165,7 @@ module Kaal
       each_enabled_entry do |entry|
         calculate_and_dispatch_due_times(entry)
       end
+      dispatch_due_delayed_jobs
     rescue ConfigurationError => e
       log_configuration_error('Kaal coordinator tick failed', e)
       raise
@@ -377,15 +369,72 @@ module Kaal
       logger&.error("Work dispatch failed for #{cron_key}: #{e.message}")
     end
 
-    def generate_idempotency_key(cron_key, fire_time)
-      Kaal::IdempotencyKeyGenerator.call(cron_key, fire_time, configuration: @configuration)
+    def dispatch_due_delayed_jobs
+      delayed_store = delayed_store_for_tick
+      return unless delayed_store
+
+      DELAYED_JOB_MAX_BATCHES_PER_TICK.times do
+        break if stop_delayed_dispatch?
+
+        apply_delayed_job_claim_jitter_if_needed(delayed_store)
+        due_jobs = delayed_store.pop_due(now: Time.now.utc, limit: DELAYED_JOB_BATCH_SIZE)
+        break if due_jobs.empty?
+
+        due_jobs.each do |job|
+          break if stop_delayed_dispatch?
+
+          dispatch_delayed_job(job, delayed_store)
+        end
+      end
+    rescue StandardError => e
+      @configuration.logger&.error("Delayed job dispatch failed: #{e.message}")
+    end
+
+    def dispatch_delayed_job(job, delayed_store)
+      if delayed_store.requires_dispatch_lock?
+        lock_key = generate_delayed_lock_key(job.fetch(:job_id))
+        return unless acquire_lock(lock_key)
+      end
+
+      job_class = Kaal::JobDispatcher.resolve_job_class(
+        job_class_name: job.fetch(:job_class),
+        key: job.fetch(:job_id),
+        queue: job[:queue]
+      )
+      Kaal::JobDispatcher.dispatch(job_class:, queue: job[:queue], args: job.fetch(:args))
+      @configuration.logger&.debug("Dispatched delayed job #{job.fetch(:job_id)} for #{job.fetch(:run_at)}")
+      true
+    rescue StandardError => e
+      Kaal::DelayedJob::DispatchFailureLogger.log_claimed_dispatch_failure(
+        logger: @configuration.logger,
+        job:,
+        error: e
+      )
+      nil
+    end
+
+    def delayed_store_for_tick
+      backend = @configuration.backend
+      backend.respond_to?(:delayed_store) ? backend.delayed_store : nil
     end
 
-    def generate_lock_key(cron_key, fire_time)
-      namespace = @configuration.namespace || 'kaal'
-      "#{namespace}:dispatch:#{cron_key}:#{fire_time.to_i}"
+    def stop_delayed_dispatch?
+      stop_requested?
     end
 
+    def apply_delayed_job_claim_jitter_if_needed(delayed_store)
+      return unless delayed_store.claim_strategy == :delete_confirmation
+
+      jitter = rand * DELAYED_JOB_DELETE_CONFIRMATION_JITTER_MAX
+      sleep(jitter) if jitter.positive?
+    end
+
+    def generate_idempotency_key(cron_key, fire_time) = Kaal::IdempotencyKeyGenerator.call(cron_key, fire_time, configuration: @configuration)
+
+    def generate_lock_key(cron_key, fire_time) = "#{@configuration.namespace || 'kaal'}:dispatch:#{cron_key}:#{fire_time.to_i}"
+
+    def generate_delayed_lock_key(job_id) = "#{@configuration.namespace || 'kaal'}:delayed_dispatch:#{job_id}"
+
     def sleep_until_next_tick
       @mutex.synchronize do
         @tick_cv.wait(@mutex, @configuration.tick_interval)

data/lib/kaal/delayed_job/database_engine.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+# Copyright Codevedas Inc. 2025-present
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+require 'json'
+require 'kaal/delayed_job/registry'
+require 'kaal/persistence/database'
+
+module Kaal
+  module DelayedJob
+    # Sequel-backed delayed-job store persisted in kaal_delayed_jobs.
+    class DatabaseEngine < Registry
+      def initialize(database:, use_skip_locked: false)
+        super()
+        @database = Kaal::Persistence::Database.new(database)
+        @use_skip_locked = use_skip_locked
+      end
+
+      def enqueue(job_id:, run_at:, job_class:, args:, queue: nil, connection: nil)
+        now = Time.now.utc
+        payload = {
+          job_id: job_id,
+          run_at: run_at,
+          job_class: job_class,
+          args: JSON.generate(args),
+          queue: queue,
+          created_at: now
+        }
+
+        dataset_for(connection).insert(payload)
+        self.class.normalize_row(payload)
+      rescue ::Sequel::UniqueConstraintViolation
+        raise DuplicateJobError, "Delayed job #{job_id.inspect} already exists"
+      end
+
+      def pop_due(now:, limit:)
+        return pop_due_with_skip_locked(now:, limit:) if @use_skip_locked
+
+        pop_due_with_delete_confirmation(now:, limit:)
+      end
+
+      def find_job(job_id, connection: @database.connection)
+        self.class.normalize_row(connection[:kaal_delayed_jobs].where(job_id: job_id).first)
+      end
+
+      def all_jobs
+        connection[:kaal_delayed_jobs].order(:run_at, :job_id).filter_map { |row| self.class.normalize_row(row) }
+      end
+
+      def claim_strategy
+        @use_skip_locked ? :skip_locked : :delete_confirmation
+      end
+
+      def self.normalize_row(row)
+        return nil unless row
+
+        {
+          job_id: row[:job_id],
+          run_at: row[:run_at],
+          job_class: row[:job_class],
+          args: parse_args(row[:args]),
+          queue: row[:queue],
+          created_at: row[:created_at]
+        }
+      rescue JSON::ParserError
+        nil
+      end
+
+      private
+
+      def pop_due_with_skip_locked(now:, limit:)
+        connection.transaction do
+          delayed_jobs_dataset = connection[:kaal_delayed_jobs]
+          due_rows = delayed_jobs_dataset.where { run_at <= now }.order(:run_at, :job_id).for_update.skip_locked.limit(limit).all
+          job_ids = due_rows.map { |row| row[:job_id] }
+          normalized_jobs = due_rows.filter_map { |row| self.class.normalize_row(row) }
+          delayed_jobs_dataset.where(job_id: job_ids).delete unless job_ids.empty?
+          normalized_jobs
+        end
+      end
+
+      def pop_due_with_delete_confirmation(now:, limit:)
+        connection.transaction do
+          delayed_jobs_dataset = connection[:kaal_delayed_jobs]
+          due_rows = delayed_jobs_dataset.where { run_at <= now }.order(:run_at, :job_id).limit(limit).all
+          due_rows.each_with_object([]) do |row, jobs|
+            deleted = delayed_jobs_dataset.where(job_id: row[:job_id]).delete
+            normalized_job = self.class.normalize_row(row)
+            jobs << normalized_job if deleted.positive? && normalized_job
+          end
+        end
+      end
+
+      def self.parse_args(args_payload)
+        JSON.parse(args_payload || '[]')
+      end
+      private_class_method :parse_args
+
+      def dataset_for(connection)
+        return dataset unless connection
+
+        Kaal::Persistence::Database.new(connection).delayed_jobs_dataset
+      end
+
+      def dataset
+        @database.delayed_jobs_dataset
+      end
+
+      def connection
+        @database.connection
+      end
+    end
+  end
+end