kaal 0.3.0 → 0.5.0

data/lib/kaal/persistence/migration_templates.rb

@@ -0,0 +1,129 @@
+# 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 Persistence
+    # Sequel migration templates emitted by `kaal init`.
+    module MigrationTemplates
+      module_function
+
+      def for_backend(backend)
+        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,
+            '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,
+            '003_create_kaal_delayed_jobs.rb' => delayed_jobs_template(backend_name)
+          }
+        else
+          {}
+        end
+      end
+
+      def dispatches_template
+        <<~RUBY
+          Sequel.migration do
+            change do
+              create_table?(:kaal_dispatches) do
+                primary_key :id
+                String :key, null: false
+                Time :fire_time, null: false
+                Time :dispatched_at, null: false
+                String :node_id, null: false
+                String :status, null: false, default: 'dispatched', size: 50
+              end
+
+              add_index :kaal_dispatches, [:key, :fire_time], unique: true
+              add_index :kaal_dispatches, :key
+              add_index :kaal_dispatches, :node_id
+              add_index :kaal_dispatches, :status
+              add_index :kaal_dispatches, :fire_time
+            end
+          end
+        RUBY
+      end
+
+      def locks_template
+        <<~RUBY
+          Sequel.migration do
+            change do
+              create_table?(:kaal_locks) do
+                primary_key :id
+                String :key, null: false
+                Time :acquired_at, null: false
+                Time :expires_at, null: false
+              end
+
+              add_index :kaal_locks, :key, unique: true
+              add_index :kaal_locks, :expires_at
+            end
+          end
+        RUBY
+      end
+
+      def definitions_template
+        <<~RUBY
+          Sequel.migration do
+            change do
+              create_table?(:kaal_definitions) do
+                primary_key :id
+                String :key, null: false
+                String :cron, null: false
+                TrueClass :enabled, null: false, default: true
+                String :source, null: false
+                String :metadata, text: true, null: false, default: '{}'
+                Time :disabled_at
+                Time :created_at, null: false
+                Time :updated_at, null: false
+              end
+
+              add_index :kaal_definitions, :key, unique: true
+              add_index :kaal_definitions, :enabled
+              add_index :kaal_definitions, :source
+            end
+          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/registry.rb

@@ -20,9 +20,7 @@ module Kaal
 
     ##
     # Entry class representing a single registered cron job
-    # rubocop:disable Style/RedundantStructKeywordInit
     Entry = Struct.new(:key, :cron, :enqueue, keyword_init: true)
-    # rubocop:enable Style/RedundantStructKeywordInit
 
     ##
     # Initialize a new Registry instance.

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

@@ -0,0 +1,82 @@
+# 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 'fileutils'
+
+module Kaal
+  # Sequel migration/install support for SQL-backed Kaal backends.
+  module Sequel
+    module_function
+
+    def install_postgres_migration(target_dir:, migration_name: 'create_kaal_postgres_backend')
+      install_migrations(target_dir:, backend: 'postgres', migration_name:)
+    end
+
+    def install_mysql_migration(target_dir:, migration_name: 'create_kaal_mysql_backend')
+      install_migrations(target_dir:, backend: 'mysql', migration_name:)
+    end
+
+    def install_sqlite_migration(target_dir:, migration_name: 'create_kaal_sqlite_backend')
+      install_migrations(target_dir:, backend: 'sqlite', migration_name:)
+    end
+
+    def install_migrations(target_dir:, backend:, migration_name: nil)
+      require_sequel!
+
+      normalized_name = normalize_migration_name(migration_name, fallback: default_migration_name_for(backend))
+      base_path = File.expand_path(target_dir)
+      FileUtils.mkdir_p(base_path)
+
+      Kaal::Persistence::MigrationTemplates.for_backend(backend).map.with_index do |(_name, contents), index|
+        suffix = migration_suffixes_for(backend).fetch(index)
+        path = File.expand_path("#{timestamp(index)}_#{normalized_name}_#{suffix}.rb", base_path)
+        File.write(path, contents)
+        path
+      end
+    end
+
+    def require_sequel!
+      require 'sequel'
+    rescue LoadError => e
+      raise LoadError,
+            "#{e.message}. Add `gem 'sequel'` to your Gemfile to use Sequel-backed Kaal SQL support.",
+            cause: e
+    end
+
+    def normalize_migration_name(name, fallback:)
+      normalized = name.to_s.each_char.with_object(+'') do |char, buffer|
+        if letter?(char) || digit?(char)
+          buffer << char.downcase
+        elsif !buffer.empty? && !buffer.end_with?('_')
+          buffer << '_'
+        end
+      end.delete_suffix('_')
+      normalized.empty? ? fallback : normalized
+    end
+
+    def default_migration_name_for(backend)
+      "create_kaal_#{backend}_backend"
+    end
+
+    def migration_suffixes_for(backend)
+      return %w[dispatches locks definitions delayed_jobs] if backend.to_s == 'sqlite'
+
+      %w[dispatches definitions delayed_jobs]
+    end
+
+    def timestamp(offset = 0)
+      (Time.now.utc + offset).strftime('%Y%m%d%H%M%S')
+    end
+
+    def letter?(char)
+      char.between?('a', 'z') || char.between?('A', 'Z')
+    end
+
+    def digit?(char)
+      char.between?('0', '9')
+    end
+  end
+end

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.3.0'
+  VERSION = '0.5.0'
 end

data/lib/kaal.rb

@@ -10,15 +10,27 @@ 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'
 require 'kaal/backend/adapter'
 require 'kaal/backend/memory_adapter'
 require 'kaal/backend/redis_adapter'
+require 'kaal/backend/sqlite'
+require 'kaal/backend/postgres'
+require 'kaal/backend/mysql'
 require 'kaal/backend/dispatch_registry_accessor'
 require 'kaal/backend/dispatch_attempt_logger'
+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'
@@ -50,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
 
@@ -78,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,
@@ -113,6 +129,7 @@ module Kaal
     end
 
     def start!
+      warn_on_risky_configuration!
       coordinator.start!
     end
 
@@ -132,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?
 
@@ -187,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
@@ -199,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
@@ -247,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.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Nitesh Purohit
@@ -84,30 +84,64 @@ files:
 - config/scheduler.yml
 - exe/kaal
 - lib/kaal.rb
+- lib/kaal/active_record_support.rb
 - lib/kaal/backend/adapter.rb
 - lib/kaal/backend/dispatch_attempt_logger.rb
 - lib/kaal/backend/dispatch_logging.rb
 - lib/kaal/backend/dispatch_registry_accessor.rb
 - lib/kaal/backend/memory_adapter.rb
+- lib/kaal/backend/mysql.rb
+- lib/kaal/backend/postgres.rb
 - lib/kaal/backend/redis_adapter.rb
+- lib/kaal/backend/sqlite.rb
 - 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
 - lib/kaal/core/coordinator.rb
 - lib/kaal/core/enabled_entry_enumerator.rb
 - lib/kaal/core/occurrence_finder.rb
+- lib/kaal/definition/database_engine.rb
 - lib/kaal/definition/memory_engine.rb
 - lib/kaal/definition/persistence_helpers.rb
 - lib/kaal/definition/redis_engine.rb
 - 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
 - lib/kaal/dispatch/registry.rb
+- lib/kaal/internal/active_record.rb
+- lib/kaal/internal/active_record/base_record.rb
+- lib/kaal/internal/active_record/connection_support.rb
+- 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
+- lib/kaal/internal/active_record/migration_templates.rb
+- lib/kaal/internal/active_record/mysql_backend.rb
+- lib/kaal/internal/active_record/postgres_backend.rb
+- lib/kaal/internal/sequel.rb
+- 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
 - lib/kaal/registry.rb
 - lib/kaal/runtime.rb
@@ -123,6 +157,7 @@ files:
 - lib/kaal/scheduler_file/loader.rb
 - lib/kaal/scheduler_file/payload_loader.rb
 - lib/kaal/scheduler_file/placeholder_support.rb
+- lib/kaal/sequel_support.rb
 - lib/kaal/support/hash_tools.rb
 - lib/kaal/utils.rb
 - lib/kaal/utils/cron_humanizer.rb