kaal 0.4.0 → 0.6.0

data/lib/kaal/delayed_job/dispatch_failure_logger.rb

@@ -0,0 +1,31 @@
+# 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 DelayedJob
+    # Shared delayed-dispatch failure logging for at-most-once dispatches.
+    module DispatchFailureLogger
+      module_function
+
+      def log_claimed_dispatch_failure(logger:, job:, error:)
+        return unless logger
+
+        message = "Delayed job #{job.fetch(:job_id)} dispatch failed after claim; " \
+                  "job_class=#{job.fetch(:job_class).inspect} " \
+                  "queue=#{job[:queue].inspect} " \
+                  "run_at=#{job.fetch(:run_at)} " \
+                  'job was already claimed and will not be retried: ' \
+                  "#{error.class}: #{error.message}"
+
+        if logger.respond_to?(:fatal)
+          logger.fatal(message)
+        else
+          logger.error(message)
+        end
+      end
+    end
+  end
+end

data/lib/kaal/delayed_job/memory_engine.rb

@@ -0,0 +1,79 @@
+# 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 'kaal/delayed_job/registry'
+require 'kaal/support/hash_tools'
+
+module Kaal
+  module DelayedJob
+    # In-memory delayed job store for single-process development and tests.
+    class MemoryEngine < Registry
+      include Kaal::Support::HashTools
+
+      def initialize
+        super
+        @jobs = {}
+        @mutex = Mutex.new
+      end
+
+      def enqueue(job_id:, run_at:, job_class:, args:, queue: nil, **)
+        @mutex.synchronize do
+          raise DuplicateJobError, "Delayed job #{job_id.inspect} already exists" if @jobs.key?(job_id)
+
+          job = build_job(job_id:, run_at:, job_class:, args:, queue:)
+          @jobs[job_id] = job
+          deep_dup(job)
+        end
+      end
+
+      def pop_due(now:, limit:)
+        @mutex.synchronize do
+          due_jobs = @jobs.values
+                          .select { |job| job[:run_at] <= now }
+                          .sort_by { |job| job.values_at(:run_at, :job_id) }
+                          .first(limit)
+
+          due_jobs.each do |job|
+            job_id = job.fetch(:job_id)
+            @jobs.delete(job_id)
+          end
+          due_jobs.map { |job| deep_dup(job) }
+        end
+      end
+
+      def find_job(job_id)
+        @mutex.synchronize { deep_dup(@jobs[job_id]) }
+      end
+
+      def all_jobs
+        @mutex.synchronize do
+          @jobs.values.sort_by { |job| [job[:run_at], job[:job_id]] }.map { |job| deep_dup(job) }
+        end
+      end
+
+      def clear
+        @mutex.synchronize { @jobs.clear }
+      end
+
+      def claim_strategy
+        :atomic_pop
+      end
+
+      private
+
+      def build_job(job_id:, run_at:, job_class:, args:, queue:)
+        {
+          job_id: job_id,
+          run_at: run_at,
+          job_class: job_class,
+          args: deep_dup(args),
+          queue: queue,
+          created_at: Time.now.utc
+        }
+      end
+    end
+  end
+end

data/lib/kaal/delayed_job/mysql_version_support.rb

@@ -0,0 +1,43 @@
+# 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 DelayedJob
+    # MySQL version helper for delayed-job claim strategy selection.
+    module MySQLVersionSupport
+      MINIMUM_SKIP_LOCKED_VERSION = 800_00
+
+      module_function
+
+      def skip_locked_supported?(version_string)
+        version_number(version_string) >= MINIMUM_SKIP_LOCKED_VERSION
+      end
+
+      def version_number(version_string)
+        major, minor, patch = version_components(version_string)
+        return 0 unless major && minor && patch
+
+        (major * 10_000) + (minor * 100) + patch
+      end
+
+      def version_components(version_string)
+        major, minor, patch = version_string.to_s.split('.', 3)
+        [
+          integer_prefix(major),
+          integer_prefix(minor),
+          integer_prefix(patch)
+        ]
+      end
+
+      def integer_prefix(value)
+        digits = value.to_s.each_char.take_while { |character| character.between?('0', '9') }.join
+        return nil if digits.empty?
+
+        digits.to_i
+      end
+    end
+  end
+end

data/lib/kaal/delayed_job/redis_engine.rb

@@ -0,0 +1,119 @@
+# 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 'time'
+require 'kaal/delayed_job/registry'
+
+module Kaal
+  module DelayedJob
+    # Redis-backed delayed-job store using a sorted set plus payload hash.
+    class RedisEngine < Registry
+      def initialize(redis, namespace: 'kaal')
+        super()
+        @redis = redis
+        @namespace = namespace
+      end
+
+      def enqueue(job_id:, run_at:, job_class:, args:, queue: nil, **)
+        payload = JSON.generate(
+          job_id: job_id,
+          run_at: run_at.iso8601,
+          job_class: job_class,
+          args: args,
+          queue: queue,
+          created_at: Time.now.utc.iso8601
+        )
+
+        script = <<~LUA
+          if redis.call('HEXISTS', KEYS[1], ARGV[1]) == 1 then
+            return 0
+          end
+
+          redis.call('HSET', KEYS[1], ARGV[1], ARGV[2])
+          redis.call('ZADD', KEYS[2], ARGV[3], ARGV[1])
+          return 1
+        LUA
+
+        result = @redis.eval(script, keys: [payloads_key, schedule_key], argv: [job_id, payload, run_at.to_f])
+        raise DuplicateJobError, "Delayed job #{job_id.inspect} already exists" unless [1, '1', true].include?(result)
+
+        find_job(job_id)
+      end
+
+      def pop_due(now:, limit:)
+        script = <<~LUA
+          local job_ids = redis.call('ZRANGEBYSCORE', KEYS[2], '-inf', ARGV[1], 'LIMIT', 0, ARGV[2])
+          local payloads = {}
+
+          for _, job_id in ipairs(job_ids) do
+            if redis.call('ZREM', KEYS[2], job_id) == 1 then
+              local payload = redis.call('HGET', KEYS[1], job_id)
+              if payload then
+                redis.call('HDEL', KEYS[1], job_id)
+                table.insert(payloads, payload)
+              end
+            end
+          end
+
+          return payloads
+        LUA
+
+        Array(@redis.eval(script, keys: [payloads_key, schedule_key], argv: [now.to_f, limit])).filter_map do |raw|
+          self.class.deserialize(raw)
+        end
+      end
+
+      def find_job(job_id)
+        self.class.deserialize(@redis.hget(payloads_key, job_id))
+      end
+
+      def all_jobs
+        Array(@redis.zrange(schedule_key, 0, -1)).filter_map { |job_id| find_job(job_id) }
+      end
+
+      def claim_strategy
+        :atomic_pop
+      end
+
+      def self.deserialize(raw)
+        return nil unless raw
+
+        parsed = JSON.parse(raw)
+        run_at = parse_time(parsed['run_at'])
+        created_at = parse_time(parsed['created_at'])
+        return nil unless run_at && created_at
+
+        {
+          job_id: parsed['job_id'],
+          run_at: run_at,
+          job_class: parsed['job_class'],
+          args: parsed['args'] || [],
+          queue: parsed['queue'],
+          created_at: created_at
+        }
+      rescue JSON::ParserError
+        nil
+      end
+
+      def self.parse_time(value)
+        Time.iso8601(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+
+      private
+
+      def payloads_key
+        "#{@namespace}:delayed_jobs:payloads"
+      end
+
+      def schedule_key
+        "#{@namespace}:delayed_jobs:schedule"
+      end
+    end
+  end
+end

data/lib/kaal/delayed_job/registry.rb

@@ -0,0 +1,39 @@
+# 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 DelayedJob
+    # Raised when a delayed job with the same identifier already exists.
+    class DuplicateJobError < StandardError; end
+
+    # Base abstraction for delayed-job persistence.
+    class Registry
+      def enqueue(**)
+        raise NotImplementedError, "#{self.class.name} must implement #enqueue"
+      end
+
+      def pop_due(**)
+        raise NotImplementedError, "#{self.class.name} must implement #pop_due"
+      end
+
+      def find_job(_job_id)
+        raise NotImplementedError, "#{self.class.name} must implement #find_job"
+      end
+
+      def all_jobs
+        raise NotImplementedError, "#{self.class.name} must implement #all_jobs"
+      end
+
+      def claim_strategy
+        raise NotImplementedError, "#{self.class.name} must implement #claim_strategy"
+      end
+
+      def requires_dispatch_lock?
+        false
+      end
+    end
+  end
+end

data/lib/kaal/internal/active_record/database_backend.rb

@@ -6,6 +6,7 @@
 # LICENSE file in the root directory of this source tree.
 require 'kaal/backend/adapter'
 require 'kaal/backend/dispatch_logging'
+require 'kaal/internal/active_record/delayed_job_registry'
 
 module Kaal
   module Internal
@@ -31,6 +32,10 @@ module Kaal
           @definition_registry ||= DefinitionRegistry.new
         end
 
+        def delayed_store
+          @delayed_store ||= DelayedJobRegistry.new
+        end
+
         def acquire(key, ttl)
           now = Time.now.utc
           expires_at = now + ttl

data/lib/kaal/internal/active_record/delayed_job_record.rb

@@ -0,0 +1,16 @@
+# 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 Internal
+    module ActiveRecord
+      # Active Record model for persisted delayed jobs.
+      class DelayedJobRecord < BaseRecord
+        self.table_name = 'kaal_delayed_jobs'
+      end
+    end
+  end
+end

data/lib/kaal/internal/active_record/delayed_job_registry.rb

@@ -0,0 +1,119 @@
+# 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'
+
+module Kaal
+  module Internal
+    module ActiveRecord
+      # Active Record-backed store for delayed jobs.
+      class DelayedJobRegistry < Kaal::DelayedJob::Registry
+        def initialize(connection: nil, model: DelayedJobRecord, use_skip_locked: false)
+          super()
+          ConnectionSupport.configure!(connection)
+          @model = model
+          @use_skip_locked = use_skip_locked
+        end
+
+        def enqueue(job_id:, run_at:, job_class:, args:, queue: nil, connection: nil)
+          now = Time.now.utc
+          attributes = {
+            job_id: job_id,
+            run_at: run_at,
+            job_class: job_class,
+            args: JSON.generate(args),
+            queue: queue,
+            created_at: now
+          }
+
+          if connection
+            insert_with_connection(connection, attributes)
+          else
+            @model.create!(attributes)
+          end
+
+          self.class.normalize(@model.new(attributes))
+        rescue ::ActiveRecord::RecordNotUnique
+          raise Kaal::DelayedJob::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
+
+        private
+
+        def pop_due_with_skip_locked(now:, limit:)
+          @model.transaction do
+            due_records = @model.where('run_at <= ?', now).order(:run_at, :job_id).lock('FOR UPDATE SKIP LOCKED').limit(limit).to_a
+            job_ids = due_records.map(&:job_id)
+            @model.where(job_id: job_ids).delete_all unless job_ids.empty?
+            due_records.filter_map { |record| self.class.normalize(record) }
+          end
+        end
+
+        def pop_due_with_delete_confirmation(now:, limit:)
+          @model.transaction do
+            @model.where('run_at <= ?', now).order(:run_at, :job_id).limit(limit).each_with_object([]) do |record, jobs|
+              normalized_job = self.class.normalize(record)
+              jobs << normalized_job if @model.where(job_id: record.job_id).delete_all.positive? && normalized_job
+            end
+          end
+        end
+
+        public
+
+        def find_job(job_id)
+          self.class.normalize(@model.find_by(job_id: job_id))
+        end
+
+        def all_jobs
+          @model.order(:run_at, :job_id).filter_map { |record| self.class.normalize(record) }
+        end
+
+        def claim_strategy
+          @use_skip_locked ? :skip_locked : :delete_confirmation
+        end
+
+        def self.normalize(record)
+          return nil unless record
+
+          {
+            job_id: record.job_id,
+            run_at: record.run_at,
+            job_class: record.job_class,
+            args: parse_args(record.args),
+            queue: record.queue,
+            created_at: record.created_at
+          }
+        rescue JSON::ParserError
+          nil
+        end
+
+        private
+
+        def insert_with_connection(connection, attributes)
+          table_name = @model.table_name
+          columns = attributes.keys
+          quoted_pairs = columns.map do |column|
+            [connection.quote_column_name(column), connection.quote(attributes.fetch(column))]
+          end
+          quoted_columns = quoted_pairs.map(&:first).join(', ')
+          quoted_values = quoted_pairs.map(&:last).join(', ')
+          connection.execute("INSERT INTO #{connection.quote_table_name(table_name)} (#{quoted_columns}) VALUES (#{quoted_values})")
+        end
+
+        def self.parse_args(args_payload)
+          JSON.parse(args_payload || '[]')
+        end
+        private_class_method :parse_args
+      end
+    end
+  end
+end

data/lib/kaal/internal/active_record/migration_templates.rb

@@ -17,17 +17,20 @@ module Kaal
             {
               '001_create_kaal_dispatches.rb' => dispatches_template,
               '002_create_kaal_locks.rb' => locks_template,
-              '003_create_kaal_definitions.rb' => definitions_template('sqlite')
+              '003_create_kaal_definitions.rb' => definitions_template('sqlite'),
+              '004_create_kaal_delayed_jobs.rb' => delayed_jobs_template('sqlite')
             }
           when 'postgres'
             {
               '001_create_kaal_dispatches.rb' => dispatches_template,
-              '002_create_kaal_definitions.rb' => definitions_template('postgres')
+              '002_create_kaal_definitions.rb' => definitions_template('postgres'),
+              '003_create_kaal_delayed_jobs.rb' => delayed_jobs_template('postgres')
             }
           when 'mysql'
             {
               '001_create_kaal_dispatches.rb' => dispatches_template,
-              '002_create_kaal_definitions.rb' => definitions_template('mysql')
+              '002_create_kaal_definitions.rb' => definitions_template('mysql'),
+              '003_create_kaal_delayed_jobs.rb' => delayed_jobs_template('mysql')
             }
           else
             {}
@@ -102,6 +105,33 @@ module Kaal
             end
           RUBY
         end
+
+        def delayed_jobs_template(backend)
+          args_definition =
+            if backend == 'mysql'
+              't.text :args, null: false'
+            else
+              "t.text :args, null: false, default: '[]'"
+            end
+
+          <<~RUBY
+            class CreateKaalDelayedJobs < ActiveRecord::Migration[7.1]
+              def change
+                create_table :kaal_delayed_jobs do |t|
+                  t.string :job_id, null: false
+                  t.datetime :run_at, null: false
+                  t.string :job_class, null: false
+                  #{args_definition}
+                  t.string :queue
+                  t.datetime :created_at, null: false
+                end
+
+                add_index :kaal_delayed_jobs, :job_id, unique: true
+                add_index :kaal_delayed_jobs, :run_at
+              end
+            end
+          RUBY
+        end
       end
     end
   end

data/lib/kaal/internal/active_record/mysql_backend.rb

@@ -5,6 +5,7 @@
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
 require 'digest'
+require 'kaal/delayed_job/mysql_version_support'
 
 module Kaal
   module Internal
@@ -14,13 +15,16 @@ module Kaal
         include Kaal::Backend::DispatchLogging
 
         MAX_LOCK_NAME_LENGTH = 64
+        UNSET_SKIP_LOCKED_SUPPORT = Object.new.freeze
 
-        def initialize(connection = nil, dispatch_registry: nil, definition_registry: nil, namespace: nil)
+        def initialize(connection = nil, dispatch_registry: nil, definition_registry: nil, namespace: nil,
+                       use_skip_locked: UNSET_SKIP_LOCKED_SUPPORT)
           super()
           ConnectionSupport.configure!(connection)
           @dispatch_registry = dispatch_registry
           @definition_registry = definition_registry
           @namespace = namespace
+          @use_skip_locked = use_skip_locked
         end
 
         def dispatch_registry
@@ -31,6 +35,10 @@ module Kaal
           @definition_registry ||= DefinitionRegistry.new
         end
 
+        def delayed_store
+          @delayed_store ||= DelayedJobRegistry.new(use_skip_locked: supports_skip_locked?)
+        end
+
         def acquire(key, _ttl)
           acquired = scalar('SELECT GET_LOCK(?, 0) AS lock_result', self.class.normalize_lock_name(key)) == 1
           log_dispatch_attempt(key) if acquired
@@ -55,16 +63,26 @@ module Kaal
 
         private
 
-        def scalar(sql, value)
-          result = BaseRecord.connection.exec_query(
-            BaseRecord.send(:sanitize_sql_array, [sql, value])
-          )
+        def scalar(sql, *binds)
+          sanitized_sql = if binds.empty?
+                            sql
+                          else
+                            BaseRecord.send(:sanitize_sql_array, [sql, *binds])
+                          end
+          result = BaseRecord.connection.exec_query(sanitized_sql)
           result.first.values.first
         end
 
         def resolved_namespace
           @namespace || Kaal.configuration.namespace
         end
+
+        def supports_skip_locked?
+          return @use_skip_locked unless @use_skip_locked.equal?(UNSET_SKIP_LOCKED_SUPPORT)
+
+          version_string = scalar('SELECT VERSION() AS version')
+          Kaal::DelayedJob::MySQLVersionSupport.skip_locked_supported?(version_string)
+        end
       end
     end
   end

data/lib/kaal/internal/active_record/postgres_backend.rb

@@ -32,6 +32,10 @@ module Kaal
           @definition_registry ||= DefinitionRegistry.new
         end
 
+        def delayed_store
+          @delayed_store ||= DelayedJobRegistry.new(use_skip_locked: true)
+        end
+
         def acquire(key, _ttl)
           acquired = scalar('SELECT pg_try_advisory_lock(?) AS acquired', self.class.calculate_lock_id(key)) == true
           log_dispatch_attempt(key) if acquired

data/lib/kaal/internal/active_record.rb

@@ -8,9 +8,11 @@ require 'kaal/internal/active_record/base_record'
 require 'kaal/internal/active_record/connection_support'
 require 'kaal/internal/active_record/definition_record'
 require 'kaal/internal/active_record/dispatch_record'
+require 'kaal/internal/active_record/delayed_job_record'
 require 'kaal/internal/active_record/lock_record'
 require 'kaal/internal/active_record/definition_registry'
 require 'kaal/internal/active_record/dispatch_registry'
+require 'kaal/internal/active_record/delayed_job_registry'
 require 'kaal/internal/active_record/database_backend'
 require 'kaal/internal/active_record/postgres_backend'
 require 'kaal/internal/active_record/mysql_backend'

data/lib/kaal/internal/sequel/database_backend.rb

@@ -5,6 +5,7 @@
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
 require 'kaal/backend/dispatch_logging'
+require 'kaal/delayed_job/database_engine'
 require 'kaal/persistence/database'
 
 module Kaal
@@ -28,6 +29,10 @@ module Kaal
           @definition_registry ||= Kaal::Definition::DatabaseEngine.new(database: @database.connection)
         end
 
+        def delayed_store
+          @delayed_store ||= Kaal::DelayedJob::DatabaseEngine.new(database: @database.connection)
+        end
+
         def acquire(key, ttl)
           now = Time.now.utc
           expires_at = now + ttl

data/lib/kaal/internal/sequel/mysql_backend.rb

@@ -6,6 +6,7 @@
 # LICENSE file in the root directory of this source tree.
 require 'digest'
 require 'kaal/backend/dispatch_logging'
+require 'kaal/delayed_job/mysql_version_support'
 require 'kaal/persistence/database'
 
 module Kaal
@@ -16,11 +17,13 @@ module Kaal
         include Kaal::Backend::DispatchLogging
 
         MAX_LOCK_NAME_LENGTH = 64
+        UNSET_SKIP_LOCKED_SUPPORT = Object.new.freeze
 
-        def initialize(database, namespace: nil)
+        def initialize(database, namespace: nil, use_skip_locked: UNSET_SKIP_LOCKED_SUPPORT)
           super()
           @database = Kaal::Persistence::Database.new(database)
           @namespace = namespace
+          @use_skip_locked = use_skip_locked
         end
 
         def dispatch_registry
@@ -31,6 +34,10 @@ module Kaal
           @definition_registry ||= Kaal::Definition::DatabaseEngine.new(database: @database.connection)
         end
 
+        def delayed_store
+          @delayed_store ||= Kaal::DelayedJob::DatabaseEngine.new(database: @database.connection, use_skip_locked: supports_skip_locked?)
+        end
+
         def acquire(key, _ttl)
           acquired = scalar('SELECT GET_LOCK(?, 0) AS lock_result', self.class.normalize_lock_name(key)) == 1
           log_dispatch_attempt(key) if acquired
@@ -63,6 +70,13 @@ module Kaal
         def resolved_namespace
           @namespace || Kaal.configuration.namespace
         end
+
+        def supports_skip_locked?
+          return @use_skip_locked unless @use_skip_locked.equal?(UNSET_SKIP_LOCKED_SUPPORT)
+
+          version_string = scalar('SELECT VERSION() AS version')
+          Kaal::DelayedJob::MySQLVersionSupport.skip_locked_supported?(version_string)
+        end
       end
     end
   end