kaal 0.4.0 → 0.5.0

data/lib/kaal/job_dispatcher.rb

@@ -0,0 +1,108 @@
+# 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
+  # Shared job-class resolution and dispatch rules used by recurring and delayed jobs.
+  module JobDispatcher
+    module_function
+
+    def resolve_job_class(job_class_name:, key:, queue: nil, apply_delayed_job_allow_list: true)
+      job_class = normalize_job_class(job_class_name, key, apply_delayed_job_allow_list:)
+      validate_dispatch_interface(job_class, key, queue)
+    end
+
+    def normalized_job_class_name(job_class_name:, key:, apply_delayed_job_allow_list: true)
+      normalized_job_class_name = normalize_job_class_name(job_class_name)
+      raise SchedulerConfigError, "Job class cannot be blank for key '#{key}'" if normalized_job_class_name.empty?
+
+      return normalized_job_class_name unless apply_delayed_job_allow_list
+
+      validate_allowed_job_class_name!(job_class_name: normalized_job_class_name, key:)
+      normalized_job_class_name
+    end
+
+    def dispatch(job_class:, queue:, args:, key: nil)
+      job_class_name = job_class.name
+      scheduler_context = key ? " for scheduler job '#{key}'" : ''
+
+      if queue && !job_class.respond_to?(:set)
+        raise SchedulerConfigError,
+              "job_class '#{job_class_name}' must respond to .set to use queue #{queue.inspect}#{scheduler_context}"
+      end
+
+      if queue
+        job_class.set(queue: queue).perform_later(*args)
+      elsif job_class.respond_to?(:perform_later)
+        job_class.perform_later(*args)
+      elsif job_class.respond_to?(:perform)
+        job_class.perform(*args)
+      else
+        raise SchedulerConfigError,
+              "job_class '#{job_class_name}' must respond to .perform, .perform_later, or .set(...).perform_later#{scheduler_context}"
+      end
+    end
+
+    def active_job_dispatch?(job_class, queue)
+      (queue && job_class.respond_to?(:set)) || job_class.respond_to?(:perform_later)
+    end
+
+    def normalize_job_class_name(job_class)
+      case job_class
+      when Module
+        job_class.name.to_s.strip
+      else
+        job_class.to_s.strip
+      end
+    end
+
+    def normalize_job_class(job_class_name, key, apply_delayed_job_allow_list: true)
+      normalized_job_class_name = normalized_job_class_name(
+        job_class_name:,
+        key:,
+        apply_delayed_job_allow_list:
+      )
+
+      return job_class_name if job_class_name.is_a?(Module)
+
+      job_class = begin
+        Kaal::Support::HashTools.constantize(normalized_job_class_name)
+      rescue NameError
+        nil
+      end
+
+      return job_class if job_class
+
+      raise SchedulerConfigError, "Unknown job_class #{normalized_job_class_name.inspect} for key '#{key}'"
+    end
+    private_class_method :normalize_job_class
+
+    def validate_allowed_job_class_name!(job_class_name:, key:)
+      allowed_prefixes = Array(Kaal.configuration.delayed_job_allowed_class_prefixes)
+      return if allowed_prefixes.empty?
+      return if allowed_prefixes.any? { |prefix| job_class_name.start_with?(prefix) }
+
+      raise SchedulerConfigError,
+            "job_class '#{job_class_name}' for key '#{key}' is not allowed by delayed_job_allowed_class_prefixes"
+    end
+    private_class_method :validate_allowed_job_class_name!
+
+    def validate_dispatch_interface(job_class, key, queue)
+      queue_present = !queue.nil?
+      no_queue = !queue_present
+      supports_set = job_class.respond_to?(:set)
+      supports_perform_later = job_class.respond_to?(:perform_later)
+      supports_perform = job_class.respond_to?(:perform)
+
+      return job_class if queue_present && supports_set
+      return job_class if no_queue && supports_perform_later
+      return job_class if no_queue && supports_perform
+
+      raise SchedulerConfigError,
+            "job_class '#{job_class.name}' for key '#{key}' must respond to .perform, .perform_later, or .set(...).perform_later"
+    end
+    private_class_method :validate_dispatch_interface
+  end
+end

data/lib/kaal/persistence/database.rb

@@ -30,6 +30,10 @@ module Kaal
       def locks_dataset
         connection[:kaal_locks]
       end
+
+      def delayed_jobs_dataset
+        connection[:kaal_delayed_jobs]
+      end
     end
   end
 end

data/lib/kaal/persistence/migration_templates.rb

@@ -11,17 +11,21 @@ module Kaal
       module_function
 
       def for_backend(backend)
-        case backend.to_s
+        backend_name = backend.to_s
+
+        case backend_name
         when 'sqlite'
           {
             '001_create_kaal_dispatches.rb' => dispatches_template,
             '002_create_kaal_locks.rb' => locks_template,
-            '003_create_kaal_definitions.rb' => definitions_template
+            '003_create_kaal_definitions.rb' => definitions_template,
+            '004_create_kaal_delayed_jobs.rb' => delayed_jobs_template('sqlite')
           }
         when 'postgres', 'mysql'
           {
             '001_create_kaal_dispatches.rb' => dispatches_template,
-            '002_create_kaal_definitions.rb' => definitions_template
+            '002_create_kaal_definitions.rb' => definitions_template,
+            '003_create_kaal_delayed_jobs.rb' => delayed_jobs_template(backend_name)
           }
         else
           {}
@@ -92,6 +96,34 @@ module Kaal
           end
         RUBY
       end
+
+      def delayed_jobs_template(backend)
+        args_definition =
+          if backend == 'mysql'
+            'String :args, text: true, null: false'
+          else
+            "String :args, text: true, null: false, default: '[]'"
+          end
+
+        <<~RUBY
+          Sequel.migration do
+            change do
+              create_table?(:kaal_delayed_jobs) do
+                primary_key :id
+                String :job_id, null: false
+                Time :run_at, null: false
+                String :job_class, null: false
+                #{args_definition}
+                String :queue
+                Time :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/runtime/scheduler_boot_loader.rb

@@ -22,6 +22,8 @@ module Kaal
       configuration = fetch_configuration
       return unless configuration
 
+      Kaal.warn_on_risky_configuration!(configuration:, logger: @logger)
+
       return load_scheduler_file if configuration.scheduler_missing_file_policy == :error
 
       scheduler_path = configuration.scheduler_config_path.to_s.strip

data/lib/kaal/scheduler_file/job_applier.rb

@@ -77,7 +77,12 @@ module Kaal
       end
 
       def resolved_job_class(job_class_name:, key:, queue: nil)
-        resolve_job_class(job_class_name:, key:, queue:)
+        Kaal::JobDispatcher.resolve_job_class(
+          job_class_name:,
+          key:,
+          queue:,
+          apply_delayed_job_allow_list: false
+        )
       end
 
       def conflict?(key:, existing_definition:)
@@ -157,7 +162,7 @@ module Kaal
           validate_keyword_keys(raw_kwargs, key)
 
           resolved_kwargs = raw_kwargs.transform_keys(&:to_sym)
-          dispatch_job(job_class, queue, resolved_args, resolved_kwargs)
+          dispatch_job(job_class, queue, resolved_args, resolved_kwargs, key)
         end
       end
 
@@ -178,64 +183,34 @@ module Kaal
         nil
       end
 
-      def resolve_job_class(job_class_name:, key:, queue: nil)
-        normalized_job_class_name = job_class_name.to_s.strip
-        raise SchedulerConfigError, "Job class cannot be blank for key '#{key}'" if normalized_job_class_name.empty?
-
-        error_message = "Unknown job_class #{normalized_job_class_name.inspect} for key '#{key}'"
-        job_class = begin
-          Kaal::Support::HashTools.constantize(normalized_job_class_name)
-        rescue NameError
-          nil
-        end
-
-        return validate_dispatch_interface(job_class, key, queue) if job_class
-
-        raise_unknown_job_class(error_message)
-      end
-
-      private :build_callback, :resolve_job_class
-
-      def dispatch_job(job_class, queue, args, kwargs)
-        job_class_name = job_class.name
-
-        if queue && !job_class.respond_to?(:set)
-          raise SchedulerConfigError,
-                "job_class '#{job_class_name}' must respond to .set to use queue #{queue.inspect}"
-        end
+      private :build_callback
 
-        if queue
-          job_class.set(queue: queue).perform_later(*args, **kwargs)
-        elsif job_class.respond_to?(:perform_later)
-          job_class.perform_later(*args, **kwargs)
-        elsif job_class.respond_to?(:perform)
-          job_class.perform(*args, **kwargs)
+      def dispatch_job(job_class, queue, args, kwargs, key)
+        if kwargs.empty?
+          Kaal::JobDispatcher.dispatch(job_class:, queue:, args:, key:)
         else
-          raise SchedulerConfigError,
-                "job_class '#{job_class_name}' must respond to .perform, .perform_later, or .set(...).perform_later"
-        end
-      end
-
-      def raise_unknown_job_class(error_message)
-        raise SchedulerConfigError, error_message
-      end
-
-      def validate_dispatch_interface(job_class, key, queue)
-        queue_present = !queue.nil?
-        supports_set = job_class.respond_to?(:set)
-        supports_perform_later = job_class.respond_to?(:perform_later)
-        supports_perform = job_class.respond_to?(:perform)
+          job_class_name = job_class.name
 
-        return job_class if queue_present && supports_set
-        return job_class if !queue_present && supports_perform_later
-        return job_class if !queue_present && supports_perform
+          if queue && !job_class.respond_to?(:set)
+            raise SchedulerConfigError,
+                  "job_class '#{job_class_name}' must respond to .set to use queue #{queue.inspect} for scheduler job '#{key}'"
+          end
 
-        raise SchedulerConfigError,
-              "job_class '#{job_class.name}' for key '#{key}' must respond to .perform, .perform_later, or .set(...).perform_later"
+          if queue
+            job_class.set(queue: queue).perform_later(*args, **kwargs)
+          elsif job_class.respond_to?(:perform_later)
+            job_class.perform_later(*args, **kwargs)
+          elsif job_class.respond_to?(:perform)
+            job_class.perform(*args, **kwargs)
+          else
+            raise SchedulerConfigError,
+                  "job_class '#{job_class_name}' must respond to .perform, .perform_later, or .set(...).perform_later for scheduler job '#{key}'"
+          end
+        end
       end
 
       def active_job_dispatch?(job_class, queue)
-        (queue && job_class.respond_to?(:set)) || job_class.respond_to?(:perform_later)
+        Kaal::JobDispatcher.active_job_dispatch?(job_class, queue)
       end
     end
   end

data/lib/kaal/sequel_support.rb

@@ -62,9 +62,9 @@ module Kaal
     end
 
     def migration_suffixes_for(backend)
-      return %w[dispatches locks definitions] if backend.to_s == 'sqlite'
+      return %w[dispatches locks definitions delayed_jobs] if backend.to_s == 'sqlite'
 
-      %w[dispatches definitions]
+      %w[dispatches definitions delayed_jobs]
     end
 
     def timestamp(offset = 0)

data/lib/kaal/version.rb

@@ -5,5 +5,5 @@
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
 module Kaal
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

data/lib/kaal.rb

@@ -10,6 +10,11 @@ require 'kaal/registry'
 require 'kaal/dispatch/registry'
 require 'kaal/dispatch/memory_engine'
 require 'kaal/dispatch/redis_engine'
+require 'kaal/delayed_job/registry'
+require 'kaal/delayed_job/memory_engine'
+require 'kaal/delayed_job/redis_engine'
+require 'kaal/delayed_job/dispatch_failure_logger'
+require 'kaal/delayed_job/mysql_version_support'
 require 'kaal/definition/registry'
 require 'kaal/definition/memory_engine'
 require 'kaal/definition/redis_engine'
@@ -25,6 +30,7 @@ require 'kaal/persistence/migration_templates'
 require 'kaal/sequel_support'
 require 'kaal/active_record_support'
 require 'kaal/utils'
+require 'kaal/job_dispatcher'
 require 'kaal/register_conflict_support'
 require 'kaal/definitions/registry_accessor'
 require 'kaal/definitions/registration_service'
@@ -56,12 +62,15 @@ module Kaal
       @definition_registry = nil
       @definitions_registry_accessor = nil
       @dispatch_registry_accessor = nil
+      @risky_configuration_warnings_emitted = {}
     end
 
     def reset_registry!
       @registry = Registry.new
       definition_registry = @definition_registry
       definition_registry.clear if definition_registry.respond_to?(:clear)
+      delayed_store = configuration.backend&.delayed_store
+      delayed_store.clear if delayed_store.respond_to?(:clear)
       @coordinator = nil
     end
 
@@ -84,6 +93,7 @@ module Kaal
     end
 
     def load_scheduler_file!(runtime_context: RuntimeContext.default)
+      warn_on_risky_configuration!
       SchedulerFileLoader.new(
         configuration: configuration,
         definition_registry: definition_registry,
@@ -119,6 +129,7 @@ module Kaal
     end
 
     def start!
+      warn_on_risky_configuration!
       coordinator.start!
     end
 
@@ -138,6 +149,30 @@ module Kaal
       coordinator.tick!
     end
 
+    # Enqueue a one-off delayed job. Delivery is at-most-once after claim.
+    def enqueue_at(at:, job_class:, args:, job_id:, queue: nil, connection: nil)
+      delayed_store = delayed_store!
+      resolved_run_at = normalize_delayed_run_at(at)
+      resolved_args = normalize_delayed_args(args)
+      resolved_queue = normalize_delayed_queue(queue)
+      resolved_job_id = normalize_delayed_job_id(job_id)
+      resolved_job_class = JobDispatcher.resolve_job_class(
+        job_class_name: job_class,
+        key: resolved_job_id,
+        queue: resolved_queue
+      )
+      resolved_job_class_name = JobDispatcher.normalize_job_class_name(resolved_job_class)
+
+      delayed_store.enqueue(
+        job_id: resolved_job_id,
+        run_at: resolved_run_at,
+        job_class: resolved_job_class_name,
+        args: resolved_args,
+        queue: resolved_queue,
+        connection: connection
+      )
+    end
+
     def with_idempotency(key, fire_time)
       raise ArgumentError, 'block required' unless block_given?
 
@@ -193,6 +228,14 @@ module Kaal
       configuration.time_zone = value
     end
 
+    def delayed_job_allowed_class_prefixes
+      configuration.delayed_job_allowed_class_prefixes
+    end
+
+    def delayed_job_allowed_class_prefixes=(value)
+      configuration.delayed_job_allowed_class_prefixes = value
+    end
+
     def definition_registry
       definitions_registry_accessor.call
     end
@@ -205,6 +248,25 @@ module Kaal
       configuration.validate!
     end
 
+    def validation_warnings
+      configuration.validation_warnings
+    end
+
+    def warn_on_risky_configuration!(configuration: self.configuration, logger: configuration.logger)
+      warnings = configuration.validation_warnings
+      return [] if warnings.empty?
+
+      @risky_configuration_warnings_emitted ||= {}
+      warnings.each do |warning|
+        next if @risky_configuration_warnings_emitted[warning]
+
+        logger&.warn(warning)
+        @risky_configuration_warnings_emitted[warning] = true
+      end
+
+      warnings
+    end
+
     def valid?(expression)
       CronUtils.valid?(expression)
     end
@@ -253,5 +315,54 @@ module Kaal
     def dispatch_registry_accessor
       @dispatch_registry_accessor ||= Backend::DispatchRegistryAccessor.new(configuration: configuration)
     end
+
+    def delayed_store!
+      delayed_store = configuration.backend&.delayed_store
+      return delayed_store if delayed_store
+
+      raise ArgumentError, 'Configured backend does not support delayed jobs'
+    end
+
+    def normalize_delayed_run_at(at)
+      time = at.is_a?(Time) ? at : at&.to_time
+      ensure_delayed_time!(time)
+
+      time.utc
+    rescue NoMethodError
+      ensure_delayed_time!(nil)
+    end
+
+    def normalize_delayed_args(args)
+      raise ArgumentError, 'args must be an array' unless args.is_a?(Array)
+
+      args.dup
+    end
+
+    def normalize_delayed_queue(queue)
+      case queue
+      when nil
+        return nil
+      end
+
+      normalized_queue = queue.to_s.strip
+      raise ArgumentError, 'queue cannot be blank' if normalized_queue.empty?
+
+      normalized_queue
+    end
+
+    def normalize_delayed_job_id(job_id)
+      normalized_job_id = job_id.to_s.strip
+      raise ArgumentError, 'job_id cannot be blank' if normalized_job_id.empty?
+
+      normalized_job_id
+    end
+
+    def invalid_delayed_time_error
+      ArgumentError.new('at must be a Time or time-like value')
+    end
+
+    def ensure_delayed_time!(time)
+      raise invalid_delayed_time_error unless time
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kaal
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Nitesh Purohit
@@ -97,6 +97,7 @@ files:
 - lib/kaal/cli.rb
 - lib/kaal/config.rb
 - lib/kaal/config/configuration.rb
+- lib/kaal/config/delayed_job_security_policy.rb
 - lib/kaal/config/scheduler_config_error.rb
 - lib/kaal/config/scheduler_time_zone_resolver.rb
 - lib/kaal/core.rb
@@ -110,6 +111,12 @@ files:
 - lib/kaal/definition/registry.rb
 - lib/kaal/definitions/registration_service.rb
 - lib/kaal/definitions/registry_accessor.rb
+- lib/kaal/delayed_job/database_engine.rb
+- lib/kaal/delayed_job/dispatch_failure_logger.rb
+- lib/kaal/delayed_job/memory_engine.rb
+- lib/kaal/delayed_job/mysql_version_support.rb
+- lib/kaal/delayed_job/redis_engine.rb
+- lib/kaal/delayed_job/registry.rb
 - lib/kaal/dispatch/database_engine.rb
 - lib/kaal/dispatch/memory_engine.rb
 - lib/kaal/dispatch/redis_engine.rb
@@ -120,6 +127,8 @@ files:
 - lib/kaal/internal/active_record/database_backend.rb
 - lib/kaal/internal/active_record/definition_record.rb
 - lib/kaal/internal/active_record/definition_registry.rb
+- lib/kaal/internal/active_record/delayed_job_record.rb
+- lib/kaal/internal/active_record/delayed_job_registry.rb
 - lib/kaal/internal/active_record/dispatch_record.rb
 - lib/kaal/internal/active_record/dispatch_registry.rb
 - lib/kaal/internal/active_record/lock_record.rb
@@ -130,6 +139,7 @@ files:
 - lib/kaal/internal/sequel/database_backend.rb
 - lib/kaal/internal/sequel/mysql_backend.rb
 - lib/kaal/internal/sequel/postgres_backend.rb
+- lib/kaal/job_dispatcher.rb
 - lib/kaal/persistence/database.rb
 - lib/kaal/persistence/migration_templates.rb
 - lib/kaal/register_conflict_support.rb