kaal 0.4.0 → 0.6.0

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

@@ -32,6 +32,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: 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/sequel.rb

@@ -8,5 +8,6 @@ require 'kaal/internal/sequel/database_backend'
 require 'kaal/internal/sequel/postgres_backend'
 require 'kaal/internal/sequel/mysql_backend'
 require 'kaal/definition/database_engine'
+require 'kaal/delayed_job/database_engine'
 require 'kaal/dispatch/database_engine'
 require 'kaal/persistence/database'

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

@@ -5,7 +5,7 @@
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
 module Kaal
-  # Loads scheduler.yml at framework boot time while respecting missing-file policy.
+  # Loads kaal-scheduler.yml at framework boot time while respecting missing-file policy.
   class SchedulerBootLoader
     def initialize(configuration_provider:, logger:, runtime_context:, load_scheduler_file:)
       @configuration_provider = configuration_provider
@@ -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/scheduler_file/loader.rb

@@ -14,7 +14,7 @@ require_relative 'job_normalizer'
 require_relative 'job_applier'
 
 module Kaal
-  # Loads scheduler definitions from config/scheduler.yml and registers them.
+  # Loads scheduler definitions from config/kaal-scheduler.yml and registers them.
   class SchedulerFileLoader
     include SchedulerHashTransform
     include SchedulerPlaceholderSupport

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.6.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
 
@@ -79,11 +88,19 @@ module Kaal
       yield(configuration) if block_given?
     end
 
+    def load_config_file!(path: 'config/kaal.yml', runtime_context: RuntimeContext.default)
+      Config::FileLoader.new(
+        configuration: configuration,
+        runtime_context:
+      ).load(path:)
+    end
+
     def register(key:, cron:, enqueue:)
       registration_service.call(key:, cron:, enqueue:)
     end
 
     def load_scheduler_file!(runtime_context: RuntimeContext.default)
+      warn_on_risky_configuration!
       SchedulerFileLoader.new(
         configuration: configuration,
         definition_registry: definition_registry,
@@ -119,6 +136,7 @@ module Kaal
     end
 
     def start!
+      warn_on_risky_configuration!
       coordinator.start!
     end
 
@@ -138,6 +156,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 +235,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 +255,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 +322,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

data/sig/00_types.rbs

@@ -0,0 +1,12 @@
+module Kaal
+  interface _RBSOpaque
+  end
+
+  interface _RBSCallable
+    def call: (*rbs_any args, **rbs_any kwargs) -> rbs_any
+  end
+
+  type rbs_scalar = nil | bool | Integer | Float | Rational | String | Symbol | Time
+  type rbs_hash_key = String | Symbol | Integer
+  type rbs_any = rbs_scalar | _RBSOpaque | _RBSCallable | Array[rbs_any] | Hash[rbs_hash_key, rbs_any]
+end

data/sig/dependencies.rbs

@@ -0,0 +1,49 @@
+class Thor
+  class Error < StandardError
+  end
+
+  class Base
+    module Shell
+      def self.new: () -> Kaal::_RBSOpaque
+    end
+
+    def self.shell: () -> singleton(Shell)
+  end
+
+  def self.package_name: (String name) -> void
+  def self.class_option: (*Kaal::rbs_any args, **Kaal::rbs_any kwargs) -> void
+  def self.desc: (String usage, String description) -> void
+  def self.option: (*Kaal::rbs_any args, **Kaal::rbs_any kwargs) -> void
+  def self.no_commands: () { () -> Kaal::rbs_any } -> void
+end
+
+class Redis
+  def initialize: (*Kaal::rbs_any args, **Kaal::rbs_any kwargs) -> void
+end
+
+module Sequel
+  class Database
+    def connection: () -> Kaal::_RBSOpaque
+    def database_type: () -> String
+    def adapter_scheme: () -> String
+  end
+
+  def self.connect: (*Kaal::rbs_any args, **Kaal::rbs_any kwargs) -> Database
+end
+
+module ActiveSupport
+  module Inflector
+    def self.underscore: (String value) -> String
+  end
+end
+
+module ActiveRecord
+  class ConnectionNotEstablished < StandardError
+  end
+
+  class RecordNotUnique < StandardError
+  end
+
+  class Base
+  end
+end

data/sig/kaal/active_record_support.rbs

@@ -0,0 +1,23 @@
+module Kaal
+  module ActiveRecord
+    def self.install_postgres_migration: (target_dir: Kaal::rbs_any, ?migration_name: ::String) -> Kaal::rbs_any
+
+    def self.install_mysql_migration: (target_dir: Kaal::rbs_any, ?migration_name: ::String) -> Kaal::rbs_any
+
+    def self.install_sqlite_migration: (target_dir: Kaal::rbs_any, ?migration_name: ::String) -> Kaal::rbs_any
+
+    def self.install_migrations: (target_dir: Kaal::rbs_any, backend: Kaal::rbs_any, ?migration_name: Kaal::rbs_any?, ?time_source: Kaal::rbs_any) -> Kaal::rbs_any
+
+    def self.require_activerecord!: () -> Kaal::rbs_any
+
+    def self.normalize_migration_name: (Kaal::rbs_any name, fallback: Kaal::rbs_any) -> Kaal::rbs_any
+
+    def self.underscore: (Kaal::rbs_any value) -> Kaal::rbs_any
+
+    def self.default_migration_class_for: (Kaal::rbs_any backend) -> ::String
+
+    def self.migration_suffixes_for: (Kaal::rbs_any backend) -> (::Array["dispatches" | "locks" | "definitions" | "delayed_jobs"] | ::Array["dispatches" | "definitions" | "delayed_jobs"])
+
+    def self.alphanumeric?: (Kaal::rbs_any char) -> Kaal::rbs_any
+  end
+end

data/sig/kaal/backend/adapter.rbs

@@ -0,0 +1,26 @@
+module Kaal
+  module Backend
+    class Adapter
+      def acquire: (Kaal::rbs_any _key, Kaal::rbs_any _ttl) -> Kaal::rbs_any
+
+      def release: (Kaal::rbs_any _key) -> Kaal::rbs_any
+
+      def with_lock: (Kaal::rbs_any key, ttl: Kaal::rbs_any) { () -> Kaal::rbs_any } -> (nil | Kaal::rbs_any)
+
+      def definition_registry: () -> nil
+
+      def delayed_store: () -> nil
+    end
+
+    class NullAdapter < Adapter
+      def acquire: (Kaal::rbs_any _key, Kaal::rbs_any _ttl) -> true
+
+      def release: (Kaal::rbs_any _key) -> true
+
+      def with_lock: (Kaal::rbs_any _key, **Kaal::rbs_any) { () -> Kaal::rbs_any } -> Kaal::rbs_any
+    end
+
+    class LockAdapterError < StandardError
+    end
+  end
+end

data/sig/kaal/backend/dispatch_attempt_logger.rbs

@@ -0,0 +1,17 @@
+module Kaal
+  module Backend
+    class DispatchAttemptLogger
+      @configuration: Kaal::rbs_any
+
+      @dispatch_registry_provider: Kaal::rbs_any
+
+      @logger: Kaal::rbs_any
+
+      @node_id_provider: Kaal::rbs_any
+
+      def initialize: (configuration: Kaal::rbs_any, dispatch_registry_provider: Kaal::rbs_any, ?logger: Kaal::rbs_any?, ?node_id_provider: Kaal::rbs_any) -> void
+
+      def call: (Kaal::rbs_any lock_key) -> Kaal::rbs_any
+    end
+  end
+end