kaal 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c304a5d511f122e3b14d0a6dfa88153d49fbf8bf2ddec699340545831c38e0af
-  data.tar.gz: c03c7fa46c7f301d100ed38bca9e9d96e3451bd69d18b801b654f8fb97bee9a8
+  metadata.gz: 0d8c12714ca483db0abe733287ae543ecd206e58c02b228983aa0fb506671542
+  data.tar.gz: 3236ad6f7721d80424a3b725542c66f0633a3a21ed42d52514a5294b75013461
 SHA512:
-  metadata.gz: b65e18daf9353b7bdd1bf4709aa8175eb1be0e7e76b68b55f2163be96e9db800adc87c075512a7c0b0a44e34f85b56055f2f9f4db165e3187ca1067a17195775
-  data.tar.gz: 6b148d15f5f3092af565d47b8120c7bf52b28ba198fbbc14a5fcb2aad516aaf6de6d4814e5f583e494c00b1b7bdb283d7f2a8eb7dc8879eaf6bd1005c9584383
+  metadata.gz: a7213b5670154c87e4115761d62ee9e5955bd84e520ac3d3dc44dc5118c7840aeb6b6d82ad7f71aa8fe1b7fb32430abd59f636c2d14a0450054af6de7c695105
+  data.tar.gz: 790385b5f77017e8001e2c9c3e38484acdab8e733dc5cd15d1bf0a39c6c2074fa9756c7226328446bc69b9044895b0644bdb521725b6992780265d5d0a296fb0

data/README.md

@@ -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:

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/backend/adapter.rb

@@ -98,6 +98,10 @@ module Kaal
       def delayed_store
         nil
       end
+
+      def disconnect_for_fork
+        nil
+      end
     end
 
     ##

data/lib/kaal/cli.rb

@@ -19,10 +19,10 @@ module Kaal
       def load_project!
         Kaal.reset_configuration!
         Kaal.reset_registry!
-        load config_path
-        Kaal.warn_on_risky_configuration!
         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
@@ -33,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
@@ -95,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])
@@ -105,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

data/lib/kaal/config/configuration.rb

@@ -12,7 +12,8 @@ module Kaal
   # @example Basic configuration
   #   Kaal.configure do |config|
   #     config.tick_interval = 5
-  #     config.backend = Kaal::Backend::RedisAdapter.new(Redis.new(url: ENV["REDIS_URL"]))
+  #     config.backend_config = { url: ENV['KAAL_BACKEND_URL'] }
+  #     config.backend = :redis
   #   end
   class Configuration
     # Default values for all configuration options
@@ -23,13 +24,14 @@ module Kaal
       lease_ttl: 125, # Must be >= window_lookback + tick_interval (120 + 5 = 125)
       namespace: 'kaal',
       backend: nil,
+      backend_config: {},
       logger: nil,
       time_zone: nil,
       enable_log_dispatch_registry: false,
       enable_dispatch_recovery: true,
       recovery_window: 86_400, # 24 hours in seconds
       recovery_startup_jitter: 5, # max random delay in seconds
-      scheduler_config_path: 'config/scheduler.yml',
+      scheduler_config_path: 'config/kaal-scheduler.yml',
       scheduler_conflict_policy: :error,
       scheduler_missing_file_policy: :warn,
       delayed_job_allowed_class_prefixes: []
@@ -41,6 +43,8 @@ module Kaal
     # @return [Configuration] a new instance with all defaults set
     def initialize
       @values = DEFAULTS.dup
+      @backend_name = nil
+      @backend_runtime_context = nil
     end
 
     ##
@@ -111,6 +115,7 @@ module Kaal
         lease_ttl: @values[:lease_ttl],
         namespace: @values[:namespace],
         backend: backend&.class&.name,
+        backend_config: Kaal::Support::HashTools.deep_dup(@values[:backend_config]),
         logger: logger&.class&.name,
         time_zone: @values[:time_zone],
         enable_log_dispatch_registry: @values[:enable_log_dispatch_registry],
@@ -133,6 +138,7 @@ module Kaal
       add_window_lookahead_error(errors)
       add_lease_ttl_error(errors)
       add_namespace_error(errors)
+      add_backend_config_error(errors)
       add_lease_ttl_window_error(errors)
       add_scheduler_config_path_error(errors)
       add_scheduler_conflict_policy_error(errors)
@@ -174,6 +180,12 @@ module Kaal
       errors << 'namespace cannot be blank'
     end
 
+    def add_backend_config_error(errors)
+      return if @values[:backend_config].is_a?(Hash)
+
+      errors << 'backend_config must be a hash'
+    end
+
     def add_lease_ttl_window_error(errors)
       lease_ttl = @values[:lease_ttl].to_i
       window_lookback = @values[:window_lookback].to_i
@@ -224,22 +236,25 @@ module Kaal
 
     def set_value(key, value)
       @values[key] = normalize_value(key, value)
+      rebuild_symbolic_backend_if_needed(key)
     end
 
     def normalize_value(key, value)
-      return value unless @values.key?(key)
-
       case key
+      when :backend
+        normalize_backend(value)
+      when :backend_config
+        value.is_a?(Hash) ? Kaal::Support::HashTools.symbolize_keys(Kaal::Support::HashTools.deep_dup(value)) : (value || {})
       when :tick_interval, :window_lookback, :window_lookahead, :lease_ttl
         value.to_i
       when :namespace, :scheduler_config_path
         value.to_s
       when :time_zone
-        value&.to_s
+        normalize_optional_string(value)
       when :enable_log_dispatch_registry
-        value ? true : false
+        !!value
       when :scheduler_conflict_policy, :scheduler_missing_file_policy
-        value&.to_sym
+        normalize_optional_symbol(value)
       when :delayed_job_allowed_class_prefixes
         normalize_delayed_job_allowed_class_prefixes(value)
       else
@@ -247,12 +262,55 @@ module Kaal
       end
     end
 
+    def normalize_backend(value)
+      unless value.is_a?(String) || value.is_a?(Symbol)
+        @backend_name = nil
+        return value
+      end
+
+      normalized_backend_name = Kaal::Config::BackendFactory.normalize_name(value)
+      backend = Kaal::Config::BackendFactory.build(
+        normalized_backend_name,
+        backend_config: @values[:backend_config],
+        namespace: @values[:namespace],
+        runtime_context: @backend_runtime_context
+      )
+      @backend_name = normalized_backend_name
+      backend
+    end
+
+    def apply_backend_runtime_context(runtime_context)
+      @backend_runtime_context = runtime_context
+    end
+    public :apply_backend_runtime_context
+
+    def rebuild_symbolic_backend_if_needed(key)
+      return unless @backend_name
+      return unless %i[backend_config namespace backend].include?(key)
+      return if key == :backend
+
+      @values[:backend] = Kaal::Config::BackendFactory.build(
+        @backend_name,
+        backend_config: @values[:backend_config],
+        namespace: @values[:namespace],
+        runtime_context: @backend_runtime_context
+      )
+    end
+
     def normalize_delayed_job_allowed_class_prefixes(value)
       Array(value).filter_map do |entry|
         normalized_entry = entry.to_s.strip
         normalized_entry unless normalized_entry.empty?
       end
     end
+
+    def normalize_optional_string(value)
+      value&.to_s
+    end
+
+    def normalize_optional_symbol(value)
+      value&.to_sym
+    end
   end
 
   ##