kaal 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f078489fc2106826b98a1890f15dd5aad38a627ef9db230bd11db3785dc66f86
-  data.tar.gz: 10ec39fb62e2082d7a8191153af335950fb14d584c0ed33737298baaa2b2f270
+  metadata.gz: 0d8c12714ca483db0abe733287ae543ecd206e58c02b228983aa0fb506671542
+  data.tar.gz: 3236ad6f7721d80424a3b725542c66f0633a3a21ed42d52514a5294b75013461
 SHA512:
-  metadata.gz: 5be3591420c49e0149f58e6d76abdb3bfc7a7c10f2249754fb427f89e9ce414bad044d44fc17ed8016b4766182558a2a513598dcc212a0d899872f31007da19b
-  data.tar.gz: 60857c850fe9ca808fd198bcd8480ee63962bc1df5de69bab5953168aa7641f1a739c74d970c67b20a7f71d1858abe2a043ac004191b473a94aee7380cf8ce50
+  metadata.gz: a7213b5670154c87e4115761d62ee9e5955bd84e520ac3d3dc44dc5118c7840aeb6b6d82ad7f71aa8fe1b7fb32430abd59f636c2d14a0450054af6de7c695105
+  data.tar.gz: 790385b5f77017e8001e2c9c3e38484acdab8e733dc5cd15d1bf0a39c6c2074fa9756c7226328446bc69b9044895b0644bdb521725b6992780265d5d0a296fb0

data/README.md

@@ -2,7 +2,7 @@
 
 Distributed cron scheduling for plain Ruby.
 
-`kaal` is the core engine gem. It owns scheduler/runtime behavior, the registry APIs, the plain Ruby CLI, and the optional SQL backend surfaces.
+`kaal` is the core engine gem. It owns scheduler/runtime behavior, the registry APIs, the plain Ruby CLI, delayed-job dispatch, and the optional SQL backend surfaces.
 
 ## Installation
 
@@ -21,43 +21,43 @@ bundle exec kaal init --backend=memory
 
 `kaal init` creates:
 
-- `config/kaal.rb`
-- `config/scheduler.yml`
+- `config/kaal.yml`
+- `config/kaal-scheduler.yml`
 
 Supported backends:
 
 - `memory`
 - `redis`
 
-If you want SQL persistence instead, add the runtime libraries your app uses, such as `sequel`, `activerecord`, `sqlite3`, `pg`, or `mysql2`, then configure one of the explicit `Kaal::Backend::*` SQL backends.
+If you want SQL persistence instead, add the runtime libraries your app uses, such as `sequel`, `activerecord`, `sqlite3`, `pg`, or `mysql2`, then set `backend: sqlite/postgres/mysql` plus `backend_config` in `config/kaal.yml`.
 
 ## Configuration
 
-Generated `config/kaal.rb` is the primary entrypoint:
+Generated `config/kaal.yml` is the primary entrypoint:
 
-```ruby
-require 'kaal'
-
-Kaal.configure do |config|
-  config.backend = Kaal::Backend::MemoryAdapter.new
-  config.tick_interval = 5
-  config.window_lookback = 120
-  config.lease_ttl = 125
-  config.scheduler_config_path = 'config/scheduler.yml'
-end
+```yaml
+defaults:
+  backend: memory
+  namespace: kaal
+  tick_interval: 5
+  window_lookback: 120
+  window_lookahead: 0
+  lease_ttl: 125
+  scheduler_config_path: config/kaal-scheduler.yml
+  enable_dispatch_recovery: true
+  enable_log_dispatch_registry: false
+  delayed_job_allowed_class_prefixes: []
+  backend_config: {}
 ```
 
 Redis path:
 
-```ruby
-require 'redis'
-
-redis = Redis.new(url: ENV.fetch('REDIS_URL'))
-
-Kaal.configure do |config|
-  config.backend = Kaal::Backend::RedisAdapter.new(redis)
-  config.scheduler_config_path = 'config/scheduler.yml'
-end
+```yaml
+defaults:
+  backend: redis
+  scheduler_config_path: config/kaal-scheduler.yml
+  backend_config:
+    url: redis://127.0.0.1:6379/0
 ```
 
 Time zone behavior is explicit:
@@ -67,7 +67,7 @@ Time zone behavior is explicit:
 
 ## Scheduler File
 
-Default scheduler definitions live at `config/scheduler.yml`:
+Default scheduler definitions live at `config/kaal-scheduler.yml`:
 
 ```yaml
 defaults:
@@ -110,6 +110,8 @@ REDIS_URL=redis://127.0.0.1:6379/0 bin/rspec-e2e redis
 
 ## Runtime API
 
+Recurring jobs:
+
 ```ruby
 Kaal.register(
   key: 'reports:daily',
@@ -122,6 +124,35 @@ Kaal.register(
 Kaal.start!
 ```
 
+Delayed jobs:
+
+```ruby
+Kaal.enqueue_at(
+  at: Time.now.utc + 300,
+  job_class: "InvoiceReminderJob",
+  args: [123],
+  queue: "mailers",
+  job_id: "invoice-reminder:123"
+)
+```
+
+Rules shared by the runtime surface:
+
+- delayed jobs use `job_id` as their identity and require it to be unique while pending
+- delayed-job `args` are positional only
+- recurring and delayed jobs share the same job-class dispatch rules
+- string job classes are constantized and class or module values are used directly
+
+To restrict delayed-job class names:
+
+```ruby
+Kaal.configure do |config|
+  config.delayed_job_allowed_class_prefixes = ["Reports::", "Billing::"]
+end
+```
+
+An empty `delayed_job_allowed_class_prefixes` list leaves delayed-job class resolution unrestricted. That is reasonable for local or trusted deployments. On shared Redis or SQL backends in production, set a restrictive prefix list.
+
 ## SQL Backends
 
 Use the explicit SQL backends when you want persisted registries:
@@ -130,3 +161,7 @@ Use the explicit SQL backends when you want persisted registries:
 - `Kaal::Backend::Postgres`
 - `Kaal::Backend::MySQL`
 - `kaal-rails` for Rails-native install and auto-wiring
+
+For SQL-backed deployments, run the generated migrations so `kaal_delayed_jobs` exists alongside the recurring scheduler tables.
+
+Postgres and supported MySQL versions claim due delayed jobs with `SKIP LOCKED`. Older SQL paths still preserve correctness with delete confirmation, and Kaal adds a small pre-claim jitter there to reduce multi-node contention.

data/config/kaal.yml

@@ -0,0 +1,12 @@
+defaults:
+  backend: memory
+  namespace: kaal
+  tick_interval: 5
+  window_lookback: 120
+  window_lookahead: 0
+  lease_ttl: 125
+  scheduler_config_path: config/kaal-scheduler.yml
+  enable_dispatch_recovery: true
+  enable_log_dispatch_registry: false
+  delayed_job_allowed_class_prefixes: []
+  backend_config: {}

data/lib/kaal/active_record_support.rb

@@ -68,9 +68,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 alphanumeric?(char)

data/lib/kaal/backend/adapter.rb

@@ -94,6 +94,14 @@ module Kaal
       def definition_registry
         nil
       end
+
+      def delayed_store
+        nil
+      end
+
+      def disconnect_for_fork
+        nil
+      end
     end
 
     ##

data/lib/kaal/backend/memory_adapter.rb

@@ -6,6 +6,7 @@
 # LICENSE file in the root directory of this source tree.
 require_relative 'dispatch_logging'
 require_relative '../definition/memory_engine'
+require_relative '../delayed_job/memory_engine'
 
 module Kaal
   module Backend
@@ -50,6 +51,10 @@ module Kaal
         @definition_registry ||= Kaal::Definition::MemoryEngine.new
       end
 
+      def delayed_store
+        @delayed_store ||= Kaal::DelayedJob::MemoryEngine.new
+      end
+
       ##
       # Attempt to acquire a lock in memory.
       #

data/lib/kaal/backend/mysql.rb

@@ -8,16 +8,20 @@ module Kaal
   module Backend
     # MySQL-backed backend for either Sequel or Active Record persistence.
     class MySQL < Adapter
-      def initialize(database: nil, connection: nil, namespace: nil, **)
+      UNSET_SKIP_LOCKED_SUPPORT = Object.new.freeze
+
+      def initialize(database: nil, connection: nil, namespace: nil,
+                     use_skip_locked: UNSET_SKIP_LOCKED_SUPPORT)
         super()
+        backend_class = self.class
         @engine = if database
                     Kaal::Sequel.require_sequel!
                     require 'kaal/internal/sequel'
-                    Kaal::Internal::Sequel::MySQLBackend.new(database, namespace:)
+                    backend_class.send(:build_sequel_backend, database, namespace, use_skip_locked)
                   else
                     Kaal::ActiveRecord.require_activerecord!
                     require 'kaal/internal/active_record'
-                    Kaal::Internal::ActiveRecord::MySQLBackend.new(connection, namespace:, **)
+                    backend_class.send(:build_active_record_backend, connection, namespace, use_skip_locked)
                   end
       end
 
@@ -29,6 +33,10 @@ module Kaal
         @engine.definition_registry
       end
 
+      def delayed_store
+        @engine.delayed_store
+      end
+
       def acquire(key, ttl)
         @engine.acquire(key, ttl)
       end
@@ -36,6 +44,20 @@ module Kaal
       def release(key)
         @engine.release(key)
       end
+
+      def self.build_sequel_backend(database, namespace, use_skip_locked)
+        return Kaal::Internal::Sequel::MySQLBackend.new(database, namespace:) if use_skip_locked.equal?(UNSET_SKIP_LOCKED_SUPPORT)
+
+        Kaal::Internal::Sequel::MySQLBackend.new(database, namespace:, use_skip_locked:)
+      end
+      private_class_method :build_sequel_backend
+
+      def self.build_active_record_backend(connection, namespace, use_skip_locked)
+        return Kaal::Internal::ActiveRecord::MySQLBackend.new(connection, namespace:) if use_skip_locked.equal?(UNSET_SKIP_LOCKED_SUPPORT)
+
+        Kaal::Internal::ActiveRecord::MySQLBackend.new(connection, namespace:, use_skip_locked:)
+      end
+      private_class_method :build_active_record_backend
     end
   end
 end

data/lib/kaal/backend/postgres.rb

@@ -8,7 +8,7 @@ module Kaal
   module Backend
     # PostgreSQL-backed backend for either Sequel or Active Record persistence.
     class Postgres < Adapter
-      def initialize(database: nil, connection: nil, namespace: nil, **)
+      def initialize(database: nil, connection: nil, namespace: nil)
         super()
         @engine = if database
                     Kaal::Sequel.require_sequel!
@@ -17,7 +17,7 @@ module Kaal
                   else
                     Kaal::ActiveRecord.require_activerecord!
                     require 'kaal/internal/active_record'
-                    Kaal::Internal::ActiveRecord::PostgresBackend.new(connection, namespace:, **)
+                    Kaal::Internal::ActiveRecord::PostgresBackend.new(connection, namespace:)
                   end
       end
 
@@ -29,6 +29,10 @@ module Kaal
         @engine.definition_registry
       end
 
+      def delayed_store
+        @engine.delayed_store
+      end
+
       def acquire(key, ttl)
         @engine.acquire(key, ttl)
       end

data/lib/kaal/backend/redis_adapter.rb

@@ -7,6 +7,7 @@
 require 'securerandom'
 require_relative 'dispatch_logging'
 require_relative '../definition/redis_engine'
+require_relative '../delayed_job/redis_engine'
 
 module Kaal
   module Backend
@@ -65,6 +66,10 @@ module Kaal
         @definition_registry ||= Kaal::Definition::RedisEngine.new(@redis, namespace: @namespace)
       end
 
+      def delayed_store
+        @delayed_store ||= Kaal::DelayedJob::RedisEngine.new(@redis, namespace: @namespace)
+      end
+
       ##
       # Attempt to acquire a distributed lock in Redis.
       #

data/lib/kaal/backend/sqlite.rb

@@ -29,6 +29,10 @@ module Kaal
         @engine.definition_registry
       end
 
+      def delayed_store
+        @engine.delayed_store
+      end
+
       def acquire(key, ttl)
         @engine.acquire(key, ttl)
       end

data/lib/kaal/cli.rb

@@ -19,9 +19,10 @@ module Kaal
       def load_project!
         Kaal.reset_configuration!
         Kaal.reset_registry!
-        load config_path
         runtime_context = RuntimeContext.default(root_path: root_path)
-        Kaal.load_scheduler_file!(runtime_context: runtime_context) if File.exist?(scheduler_path)
+        Kaal.load_config_file!(path: config_path, runtime_context:)
+        Kaal.warn_on_risky_configuration!
+        Kaal.load_scheduler_file!(runtime_context: runtime_context)
       end
 
       def root_path
@@ -32,42 +33,46 @@ module Kaal
         config = options[:config]
         return File.expand_path(config) if config
 
-        File.join(root_path, 'config', 'kaal.rb')
+        File.join(root_path, 'config', 'kaal.yml')
       end
 
       def scheduler_path
-        File.join(root_path, 'config', 'scheduler.yml')
+        File.join(root_path, 'config', 'kaal-scheduler.yml')
       end
 
       def render_config_template(backend)
         case backend
         when 'memory'
-          <<~RUBY
-            require 'kaal'
-
-            Kaal.configure do |config|
-              config.backend = Kaal::Backend::MemoryAdapter.new
-              config.tick_interval = 5
-              config.window_lookback = 120
-              config.lease_ttl = 125
-              config.scheduler_config_path = 'config/scheduler.yml'
-            end
-          RUBY
+          <<~YAML
+            defaults:
+              backend: memory
+              namespace: kaal
+              tick_interval: 5
+              window_lookback: 120
+              window_lookahead: 0
+              lease_ttl: 125
+              scheduler_config_path: config/kaal-scheduler.yml
+              enable_dispatch_recovery: true
+              enable_log_dispatch_registry: false
+              delayed_job_allowed_class_prefixes: []
+              backend_config: {}
+          YAML
         when 'redis'
-          <<~RUBY
-            require 'kaal'
-            require 'redis'
-
-            redis = Redis.new(url: ENV.fetch('REDIS_URL'))
-
-            Kaal.configure do |config|
-              config.backend = Kaal::Backend::RedisAdapter.new(redis, namespace: 'kaal')
-              config.tick_interval = 5
-              config.window_lookback = 120
-              config.lease_ttl = 125
-              config.scheduler_config_path = 'config/scheduler.yml'
-            end
-          RUBY
+          <<~YAML
+            defaults:
+              backend: redis
+              namespace: kaal
+              tick_interval: 5
+              window_lookback: 120
+              window_lookahead: 0
+              lease_ttl: 125
+              scheduler_config_path: config/kaal-scheduler.yml
+              enable_dispatch_recovery: true
+              enable_log_dispatch_registry: false
+              delayed_job_allowed_class_prefixes: []
+              backend_config:
+                url: redis://127.0.0.1:6379/0
+          YAML
         else
           raise Thor::Error, "Unsupported backend '#{backend}'"
         end
@@ -94,9 +99,9 @@ module Kaal
     package_name 'kaal'
 
     class_option :root, type: :string, default: Dir.pwd, desc: 'Project root'
-    class_option :config, type: :string, desc: 'Path to config/kaal.rb'
+    class_option :config, type: :string, desc: 'Path to config/kaal.yml'
 
-    desc 'init', 'Generate config/kaal.rb and config/scheduler.yml'
+    desc 'init', 'Generate config/kaal.yml and config/kaal-scheduler.yml'
     option :backend, type: :string, default: 'memory', enum: %w[memory redis]
     def init
       root = File.expand_path(options[:root])
@@ -104,8 +109,8 @@ module Kaal
       writer = self.class
       FileUtils.mkdir_p(File.join(root, 'config'))
 
-      writer.write_file(File.join(root, 'config', 'kaal.rb'), render_config_template(backend))
-      writer.write_file(File.join(root, 'config', 'scheduler.yml'), scheduler_template)
+      writer.write_file(File.join(root, 'config', 'kaal.yml'), render_config_template(backend))
+      writer.write_file(File.join(root, 'config', 'kaal-scheduler.yml'), scheduler_template)
 
       say("Initialized Kaal project for #{backend} backend")
     end

data/lib/kaal/config/backend_factory.rb

@@ -0,0 +1,178 @@
+# 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'
+require 'pathname'
+require 'uri'
+
+module Kaal
+  module Config
+    # Builds backend adapter instances from symbolic runtime configuration.
+    module BackendFactory
+      module_function
+
+      SUPPORTED_BACKENDS = %w[memory redis sqlite postgres mysql].freeze
+
+      def normalize_name(name)
+        normalized = name.to_s.strip.downcase
+        return nil if normalized.empty?
+
+        normalized = 'postgres' if normalized == 'postgresql'
+        normalized = 'mysql' if normalized == 'trilogy'
+        return normalized if SUPPORTED_BACKENDS.include?(normalized)
+
+        raise Kaal::ConfigurationError, "Unsupported backend #{name.inspect}; use memory, redis, sqlite, postgres, or mysql"
+      end
+
+      def build(name, backend_config:, namespace:, runtime_context: nil)
+        backend_name = normalize_name(name)
+        config = normalize_backend_config(backend_config)
+
+        case backend_name
+        when 'memory'
+          Kaal::Backend::MemoryAdapter.new
+        when 'redis'
+          build_redis_backend(config, namespace)
+        when 'sqlite'
+          build_sqlite_backend(config, namespace, runtime_context)
+        when 'postgres'
+          build_postgres_backend(config, namespace)
+        when 'mysql'
+          build_mysql_backend(config, namespace)
+        end
+      end
+
+      def normalize_backend_config(backend_config)
+        hash = backend_config.is_a?(Hash) ? backend_config : {}
+        Kaal::Support::HashTools.symbolize_keys(Kaal::Support::HashTools.deep_dup(hash))
+      end
+
+      def build_redis_backend(config, namespace)
+        require_redis!
+
+        url = string_value(config[:url])
+        raise Kaal::ConfigurationError, 'redis backend requires backend_config.url or KAAL_BACKEND_URL' if url.empty?
+
+        Kaal::Backend::RedisAdapter.new(::Redis.new(url: url), namespace:)
+      end
+
+      def build_sqlite_backend(config, namespace, runtime_context)
+        return Kaal::Backend::SQLite.new(connection: build_sqlite_connection(config[:connection], runtime_context), namespace:) if config.key?(:connection)
+
+        url = string_value(config[:url])
+        database = string_value(config[:database])
+        target = url.empty? ? database : url
+        raise Kaal::ConfigurationError, 'sqlite backend requires backend_config.url, backend_config.database, or KAAL_BACKEND_URL' if target.empty?
+
+        require_sequel!
+        Kaal::Backend::SQLite.new(
+          database: sequel_sqlite_database(target, runtime_context),
+          namespace:
+        )
+      end
+
+      def build_postgres_backend(config, namespace)
+        if config.key?(:connection)
+          return Kaal::Backend::Postgres.new(connection: normalize_connection_hash(config[:connection], 'postgresql', nil),
+                                             namespace:)
+        end
+
+        url = string_value(config[:url])
+        raise Kaal::ConfigurationError, 'postgres backend requires backend_config.url or KAAL_BACKEND_URL' if url.empty?
+
+        require_sequel!
+        Kaal::Backend::Postgres.new(database: ::Sequel.connect(url), namespace:)
+      end
+
+      def build_mysql_backend(config, namespace)
+        use_skip_locked = config[:use_skip_locked]
+        skip_locked_configured = config.key?(:use_skip_locked)
+
+        if config.key?(:connection)
+          connection = normalize_connection_hash(config[:connection], 'mysql2', nil)
+          return Kaal::Backend::MySQL.new(connection:, namespace:) unless skip_locked_configured
+
+          return Kaal::Backend::MySQL.new(connection:, namespace:, use_skip_locked:)
+        end
+
+        url = string_value(config[:url])
+        raise Kaal::ConfigurationError, 'mysql backend requires backend_config.url or KAAL_BACKEND_URL' if url.empty?
+
+        require_sequel!
+        database = ::Sequel.connect(url)
+        return Kaal::Backend::MySQL.new(database:, namespace:) unless skip_locked_configured
+
+        Kaal::Backend::MySQL.new(database:, namespace:, use_skip_locked:)
+      end
+
+      def build_sqlite_connection(connection, runtime_context)
+        normalize_connection_hash(connection, 'sqlite3', runtime_context)
+      end
+
+      def normalize_connection_hash(connection, default_adapter, runtime_context)
+        case connection
+        when String
+          connection
+        when Hash
+          normalized = Kaal::Support::HashTools.symbolize_keys(Kaal::Support::HashTools.deep_dup(connection))
+          adapter = string_value(normalized[:adapter])
+          normalized_adapter = adapter.empty? ? default_adapter : adapter
+          normalized[:adapter] = normalized_adapter
+          normalized[:database] = resolve_sqlite_database_path(normalized[:database], runtime_context) if normalized_adapter == 'sqlite3'
+          normalized
+        else
+          raise Kaal::ConfigurationError, 'backend_config.connection must be a URL string or hash'
+        end
+      end
+
+      def resolve_sqlite_database_path(database, runtime_context)
+        value = string_value(database)
+        return value if value.empty?
+        return value if sqlite_uri?(value)
+        return ensure_sqlite_directory!(value) if Pathname.new(value).absolute?
+
+        resolved = runtime_context ? runtime_context.resolve_path(value) : value
+        ensure_sqlite_directory!(resolved)
+      end
+
+      def sqlite_uri?(value)
+        value.start_with?('sqlite:', 'file:')
+      end
+
+      def sequel_sqlite_database(target, runtime_context)
+        return ::Sequel.connect(target) if sqlite_uri?(target)
+
+        ::Sequel.connect(adapter: 'sqlite', database: resolve_sqlite_database_path(target, runtime_context))
+      end
+
+      def ensure_sqlite_directory!(database_path)
+        directory = File.dirname(database_path)
+        FileUtils.mkdir_p(directory) unless directory == '.' || directory.empty?
+        database_path
+      end
+
+      def adapter_name_for_error(adapter)
+        adapter == 'postgresql' ? 'postgres' : 'mysql'
+      end
+
+      def string_value(value)
+        value.to_s.strip
+      end
+
+      def require_redis!
+        require 'redis'
+      rescue LoadError => e
+        raise LoadError, "#{e.message}. Add `gem 'redis'` to your Gemfile to use the Redis-backed Kaal adapter.", cause: e
+      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
+    end
+  end
+end