kaal 0.2.0

data/lib/kaal/backend/postgres_adapter.rb

@@ -0,0 +1,134 @@
+# 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 'digest'
+require 'socket'
+require_relative 'dispatch_logging'
+require_relative '../definition/database_engine'
+
+module Kaal
+  module Backend
+    ##
+    # Distributed backend adapter using PostgreSQL advisory locks.
+    #
+    # This adapter uses PostgreSQL's pg_try_advisory_lock function for
+    # distributed locking across multiple nodes. Locks are connection-based
+    # and automatically released when the database connection is closed.
+    #
+    # **IMPORTANT LIMITATIONS:**
+    # - The +ttl+ parameter is ignored. Locks do not auto-expire based on time;
+    #   they persist until the database connection terminates.
+    # - If a process crashes while holding a lock, the lock will remain held until
+    #   the connection timeout occurs (typically 30-60 minutes). For critical systems,
+    #   consider monitoring stale locks or using a time-based fallback mechanism.
+    # - Ensure connection pooling is properly configured to release connections
+    #   promptly when processes terminate.
+    #
+    # Optionally logs all dispatch attempts to the database when
+    # enable_log_dispatch_registry is enabled in configuration.
+    #
+    # @example Using the PostgreSQL adapter
+    #   Kaal.configure do |config|
+    #     config.backend = Kaal::Backend::PostgresAdapter.new
+    #     config.enable_log_dispatch_registry = true  # Enable dispatch logging
+    #   end
+    class PostgresAdapter < Adapter
+      include DispatchLogging
+
+      ##
+      # Initialize a new PostgreSQL adapter.
+      def initialize
+        super
+        @signed_64_max = 9_223_372_036_854_775_807
+        @unsigned_64_range = 18_446_744_073_709_551_616
+        @false_value_pattern = /\A(f|false|0|)\z/i
+      end
+
+      ##
+      # Get the dispatch registry for database logging.
+      #
+      # @return [Kaal::Dispatch::DatabaseEngine] database engine instance
+      def dispatch_registry
+        @dispatch_registry ||= Kaal::Dispatch::DatabaseEngine.new
+      end
+
+      ##
+      # Get the definition registry for database-backed definition persistence.
+      #
+      # @return [Kaal::Definition::DatabaseEngine] database definition engine instance
+      def definition_registry
+        @definition_registry ||= Kaal::Definition::DatabaseEngine.new
+      end
+
+      ##
+      # Attempt to acquire a distributed lock using PostgreSQL advisory lock.
+      #
+      # Converts the lock key to a deterministic 64-bit integer hash and attempts
+      # to acquire the advisory lock. If successful, logs the dispatch attempt
+      # when enable_log_dispatch_registry is enabled.
+      #
+      # **Note:** The +ttl+ parameter is ignored. PostgreSQL advisory locks are
+      # connection-based and do not auto-expire. The lock will be held until the
+      # database connection is closed. See class documentation for limitations.
+      #
+      # @param key [String] the lock key (format: "namespace:dispatch:cron_key:fire_time")
+      # @param ttl [Integer] time-to-live in seconds (ignored; see class docs)
+      # @return [Boolean] true if acquired, false if held by another process
+      def acquire(key, _ttl)
+        lock_id = calculate_lock_id(key)
+
+        sql = ActiveRecord::Base.sanitize_sql_array(['SELECT pg_try_advisory_lock(?)', lock_id])
+        acquired = cast_to_boolean(ActiveRecord::Base.connection.execute(sql).first['pg_try_advisory_lock'])
+
+        log_dispatch_attempt(key) if acquired
+
+        acquired
+      rescue StandardError => e
+        raise LockAdapterError, "PostgreSQL acquire failed for #{key}: #{e.message}"
+      end
+
+      ##
+      # Release a distributed lock held by PostgreSQL advisory lock.
+      #
+      # @param key [String] the lock key
+      # @return [Boolean] true if released, false if not held
+      def release(key)
+        lock_id = calculate_lock_id(key)
+
+        sql = ActiveRecord::Base.sanitize_sql_array(['SELECT pg_advisory_unlock(?)', lock_id])
+        cast_to_boolean(ActiveRecord::Base.connection.execute(sql).first['pg_advisory_unlock'])
+      rescue StandardError => e
+        raise LockAdapterError, "PostgreSQL release failed for #{key}: #{e.message}"
+      end
+
+      private
+
+      def cast_to_boolean(value)
+        # PostgreSQL's `.execute` returns "t"/"f" strings for boolean columns,
+        # not Ruby true/false. Explicitly cast to boolean for proper semantics.
+        case value
+        when 't'
+          true
+        when 'f'
+          false
+        when true, false
+          value
+        else
+          !value.to_s.match?(@false_value_pattern)
+        end
+      end
+
+      def calculate_lock_id(key)
+        # Use MD5 hash of the key and convert to 64-bit signed integer
+        # Ensure it's in the range of a signed 64-bit integer
+        hash = Digest::MD5.digest(key).unpack1('Q>')
+        # Convert to signed 64-bit integer
+        hash > @signed_64_max ? hash - @unsigned_64_range : hash
+      end
+    end
+  end
+end

data/lib/kaal/backend/redis_adapter.rb

@@ -0,0 +1,145 @@
+# 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 'securerandom'
+require_relative 'dispatch_logging'
+require_relative '../definition/redis_engine'
+
+module Kaal
+  module Backend
+    ##
+    # Distributed backend adapter using Redis.
+    #
+    # This adapter uses Redis SET command with NX (only set if not exists) and
+    # PX (expire in milliseconds) options to implement atomic lock acquisition
+    # with automatic TTL-based expiration.
+    #
+    # The lock value is a unique identifier (UUID) to allow safe release by
+    # preventing deletion of locks acquired by other processes.
+    #
+    # @example Using the Redis adapter
+    #   redis = Redis.new(url: ENV["REDIS_URL"])
+    #   Kaal.configure do |config|
+    #     config.backend = Kaal::Backend::RedisAdapter.new(redis)
+    #     config.enable_log_dispatch_registry = true  # Enable dispatch logging
+    #   end
+    class RedisAdapter < Adapter
+      include DispatchLogging
+
+      ##
+      # Initialize a new Redis adapter.
+      #
+      # @param redis [Object] a Redis-compatible client instance
+      # @param namespace [String] namespace prefix for dispatch registry keys
+      # @raise [ArgumentError] if redis is not provided or does not implement the required interface
+      def initialize(redis, namespace: 'kaal')
+        super()
+        raise ArgumentError, 'redis client must respond to :set and :eval' unless redis.respond_to?(:set) && redis.respond_to?(:eval)
+
+        @redis = redis
+        @namespace = namespace
+        @lock_value_generator = -> { SecureRandom.uuid }
+        # Store lock values with expiration timestamps to enable safe release and prevent unbounded memory growth.
+        # Since lock keys include fire_time.to_i, each dispatch creates a unique key. In the coordinator's
+        # normal flow, release is never called (TTL is relied upon), so we must expire local entries.
+        @lock_values = {}
+        @mutex = Mutex.new
+      end
+
+      ##
+      # Get the dispatch registry for Redis logging.
+      #
+      # @return [Kaal::Dispatch::RedisEngine] Redis engine instance
+      def dispatch_registry
+        @dispatch_registry ||= Kaal::Dispatch::RedisEngine.new(@redis, namespace: @namespace)
+      end
+
+      ##
+      # Get the definition registry for Redis-backed definition persistence.
+      #
+      # @return [Kaal::Definition::RedisEngine] redis definition engine instance
+      def definition_registry
+        @definition_registry ||= Kaal::Definition::RedisEngine.new(@redis, namespace: @namespace)
+      end
+
+      ##
+      # Attempt to acquire a distributed lock in Redis.
+      #
+      # Uses SET key value NX PX ttl to atomically acquire the lock with TTL.
+      # Stores the lock value locally with an expiration time to enable safe release
+      # while preventing unbounded memory growth.
+      #
+      # @param key [String] the lock key
+      # @param ttl [Integer] time-to-live in seconds
+      # @return [Boolean] true if acquired, false if held by another process
+      def acquire(key, ttl)
+        lock_value = generate_lock_value
+        ttl_ms = ttl * 1000
+
+        # SET key value NX PX ttl returns OK if set, nil if not set
+        result = @redis.set(key, lock_value, nx: true, px: ttl_ms)
+
+        if result
+          @mutex.synchronize do
+            @lock_values[key] = { value: lock_value, expires_at: Time.now + ttl }
+            prune_expired_lock_values
+          end
+        end
+
+        acquired = result.present?
+        log_dispatch_attempt(key) if acquired
+
+        acquired
+      rescue StandardError => e
+        raise LockAdapterError, "Redis acquire failed for #{key}: #{e.message}"
+      end
+
+      ##
+      # Release a distributed lock from Redis.
+      #
+      # Safely deletes the lock only if the stored value matches the value
+      # we set during acquire. This prevents releasing locks acquired by other processes.
+      #
+      # @param key [String] the lock key to release
+      # @return [Boolean] true if released (key was held with our value), false otherwise
+      def release(key)
+        lock_entry = @mutex.synchronize do
+          @lock_values.delete(key)
+        end
+
+        return false unless lock_entry
+
+        lock_value = lock_entry[:value]
+
+        # Use a Lua script to delete only if value matches
+        script = <<~LUA
+          if redis.call('get', KEYS[1]) == ARGV[1] then
+            return redis.call('del', KEYS[1])
+          else
+            return 0
+          end
+        LUA
+
+        result = @redis.eval(script, keys: [key], argv: [lock_value])
+        result.present? && result.positive?
+      rescue StandardError => e
+        raise LockAdapterError, "Redis release failed for #{key}: #{e.message}"
+      end
+
+      private
+
+      def generate_lock_value
+        @lock_value_generator.call
+      end
+
+      def prune_expired_lock_values
+        now = Time.now
+        @lock_values.delete_if { |_key, entry| entry[:expires_at] <= now }
+      end
+    end
+  end
+end

data/lib/kaal/backend/sqlite_adapter.rb

@@ -0,0 +1,116 @@
+# 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_relative 'dispatch_logging'
+require_relative '../definition/database_engine'
+
+module Kaal
+  module Backend
+    ##
+    # Distributed backend adapter using any ActiveRecord-backed SQL database.
+    #
+    # Despite the "SQLiteAdapter" name, this adapter works with any SQL database
+    # supported by Rails (SQLite, PostgreSQL, MySQL, etc.) via ActiveRecord. It stores
+    # locks in a database table with TTL-based expiration and uses a UNIQUE constraint
+    # on the key column to ensure atomicity.
+    #
+    # Suitable for single-server or development environments. For production
+    # multi-node deployments, use Redis or PostgreSQL adapters instead.
+    #
+    # @example Using the adapter with any SQL database
+    #   Kaal.configure do |config|
+    #     config.backend = Kaal::Backend::SQLiteAdapter.new
+    #     config.enable_log_dispatch_registry = true  # Enable dispatch logging
+    #   end
+    class SQLiteAdapter < Adapter
+      include DispatchLogging
+
+      ##
+      # Initialize a new database-backed adapter.
+      #
+      # @return [SQLiteAdapter] a new instance
+      #   (Note: Despite the class name, this works with any ActiveRecord SQL database)
+
+      ##
+      # Get the dispatch registry for database logging.
+      #
+      # @return [Kaal::Dispatch::DatabaseEngine] database engine instance
+      def dispatch_registry
+        @dispatch_registry ||= Kaal::Dispatch::DatabaseEngine.new
+      end
+
+      ##
+      # Get the definition registry for database-backed definition persistence.
+      #
+      # @return [Kaal::Definition::DatabaseEngine] database definition engine instance
+      def definition_registry
+        @definition_registry ||= Kaal::Definition::DatabaseEngine.new
+      end
+
+      ##
+      # Attempt to acquire a distributed lock in the database.
+      #
+      # Attempts to insert a new lock record. If the key already exists, cleans up
+      # any expired locks and retries once. This avoids unnecessary cleanup in the
+      # common case and reduces the window for race conditions.
+      #
+      # @param key [String] the lock key
+      # @param ttl [Integer] time-to-live in seconds
+      # @return [Boolean] true if acquired, false if held by another process
+      def acquire(key, ttl)
+        now = Time.current
+        expires_at = now + ttl.seconds
+        acquired = false
+        attempt_cleanup = false
+
+        2.times do
+          Kaal::CronLock.cleanup_expired if attempt_cleanup
+          begin
+            Kaal::CronLock.create!(
+              key: key,
+              acquired_at: now,
+              expires_at: expires_at
+            )
+            acquired = true
+            break
+          rescue ActiveRecord::RecordInvalid, ActiveRecord::RecordNotUnique
+            attempt_cleanup = true
+          rescue ActiveRecord::StatementInvalid => e
+            raise unless wrapped_contention_error?(e)
+
+            attempt_cleanup = true
+          end
+        end
+
+        log_dispatch_attempt(key) if acquired
+
+        acquired
+      rescue StandardError => e
+        raise LockAdapterError, "SQLite acquire failed for #{key}: #{e.message}"
+      end
+
+      ##
+      # Release a previously acquired lock.
+      #
+      # @param key [String] the lock key to release
+      # @return [Boolean] true if released (key existed and was deleted), false if not held
+      def release(key)
+        deleted = Kaal::CronLock.where(key: key).delete_all
+        deleted.positive?
+      rescue StandardError => e
+        raise LockAdapterError, "SQLite release failed for #{key}: #{e.message}"
+      end
+
+      private
+
+      def wrapped_contention_error?(error)
+        cause = error.cause
+        cause.is_a?(ActiveRecord::RecordNotUnique) || error.message.match?(/unique|duplicate/i)
+      end
+    end
+  end
+end

data/lib/kaal/configuration.rb

@@ -0,0 +1,231 @@
+# 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
+  ##
+  # Configuration class for Kaal
+  # Holds all settings for the scheduler, tick intervals, locks, and more.
+  #
+  # @example Basic configuration
+  #   Kaal.configure do |config|
+  #     config.tick_interval = 5
+  #     config.backend = Kaal::Backend::RedisAdapter.new(Redis.new(url: ENV["REDIS_URL"]))
+  #   end
+  class Configuration
+    # Default values for all configuration options
+    DEFAULTS = {
+      tick_interval: 5,
+      window_lookback: 120,
+      window_lookahead: 0,
+      lease_ttl: 125, # Must be >= window_lookback + tick_interval (120 + 5 = 125)
+      namespace: 'kaal',
+      backend: nil,
+      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_conflict_policy: :error,
+      scheduler_missing_file_policy: :warn
+    }.freeze
+
+    ##
+    # Initialize a new Configuration instance with default values.
+    #
+    # @return [Configuration] a new instance with all defaults set
+    def initialize
+      @values = DEFAULTS.dup
+    end
+
+    ##
+    # Retrieve or assign configuration values by method name.
+    def method_missing(method_name, *args)
+      handled, value = handle_known_key(method_name) do |key, setter|
+        setter ? set_value(key, args.first) : @values[key]
+      end
+
+      return value if handled
+
+      super
+    end
+
+    ##
+    # Advertise supported configuration keys for respond_to?.
+    def respond_to_missing?(method_name, include_private = false)
+      handled, value = handle_known_key(method_name) { true }
+      (handled && value) || super
+    end
+
+    ##
+    # Validate configuration without raising.
+    #
+    # @return [Array<String>] validation error messages
+    def validate
+      validation_errors
+    end
+
+    ##
+    # Validate the configuration settings.
+    # Raises errors if required settings are invalid.
+    #
+    # @raise [ConfigurationError] if validation fails
+    # @return [Configuration] self if validation passes
+    def validate!
+      errors = validation_errors
+      raise ConfigurationError, errors.join('; ') if errors.any?
+
+      self
+    end
+
+    ##
+    # Get a hash representation of the current configuration.
+    #
+    # @return [Hash] configuration as a hash
+    def to_h
+      backend = @values[:backend]
+      logger = @values[:logger]
+
+      {
+        tick_interval: @values[:tick_interval],
+        window_lookback: @values[:window_lookback],
+        window_lookahead: @values[:window_lookahead],
+        lease_ttl: @values[:lease_ttl],
+        namespace: @values[:namespace],
+        backend: backend&.class&.name,
+        logger: logger&.class&.name,
+        time_zone: @values[:time_zone],
+        enable_log_dispatch_registry: @values[:enable_log_dispatch_registry],
+        enable_dispatch_recovery: @values[:enable_dispatch_recovery],
+        recovery_window: @values[:recovery_window],
+        recovery_startup_jitter: @values[:recovery_startup_jitter],
+        scheduler_config_path: @values[:scheduler_config_path],
+        scheduler_conflict_policy: @values[:scheduler_conflict_policy],
+        scheduler_missing_file_policy: @values[:scheduler_missing_file_policy]
+      }
+    end
+
+    private
+
+    def validation_errors
+      errors = []
+      add_tick_interval_error(errors)
+      add_window_lookback_error(errors)
+      add_window_lookahead_error(errors)
+      add_lease_ttl_error(errors)
+      add_namespace_error(errors)
+      add_lease_ttl_window_error(errors)
+      add_scheduler_config_path_error(errors)
+      add_scheduler_conflict_policy_error(errors)
+      add_scheduler_missing_file_policy_error(errors)
+      errors
+    end
+
+    def add_tick_interval_error(errors)
+      value = @values[:tick_interval]
+      return unless value.to_i <= 0
+
+      errors << "tick_interval must be greater than 0, got: #{value}"
+    end
+
+    def add_window_lookback_error(errors)
+      value = @values[:window_lookback]
+      return unless value.to_i.negative?
+
+      errors << "window_lookback must be greater than or equal to 0, got: #{value}"
+    end
+
+    def add_window_lookahead_error(errors)
+      value = @values[:window_lookahead]
+      return unless value.to_i.negative?
+
+      errors << "window_lookahead must be greater than or equal to 0, got: #{value}"
+    end
+
+    def add_lease_ttl_error(errors)
+      value = @values[:lease_ttl]
+      return unless value.to_i <= 0
+
+      errors << "lease_ttl must be greater than 0, got: #{value}"
+    end
+
+    def add_namespace_error(errors)
+      return unless @values[:namespace].to_s.strip.empty?
+
+      errors << 'namespace cannot be blank'
+    end
+
+    def add_lease_ttl_window_error(errors)
+      lease_ttl = @values[:lease_ttl].to_i
+      window_lookback = @values[:window_lookback].to_i
+      tick_interval = @values[:tick_interval].to_i
+
+      # Skip if individual validations already failed
+      return if lease_ttl <= 0 || window_lookback.negative? || tick_interval <= 0
+
+      minimum_ttl = window_lookback + tick_interval
+      return unless lease_ttl < minimum_ttl
+
+      errors << "lease_ttl (#{lease_ttl}s) must be >= window_lookback + tick_interval (#{minimum_ttl}s) to prevent duplicate dispatch"
+    end
+
+    def add_scheduler_config_path_error(errors)
+      return unless @values[:scheduler_config_path].to_s.strip.empty?
+
+      errors << 'scheduler_config_path cannot be blank'
+    end
+
+    def add_scheduler_conflict_policy_error(errors)
+      return if %i[error code_wins file_wins].include?(@values[:scheduler_conflict_policy])
+
+      errors << 'scheduler_conflict_policy must be :error, :code_wins, or :file_wins'
+    end
+
+    def add_scheduler_missing_file_policy_error(errors)
+      return if %i[warn error].include?(@values[:scheduler_missing_file_policy])
+
+      errors << 'scheduler_missing_file_policy must be :warn or :error'
+    end
+
+    def handle_known_key(method_name)
+      name = method_name.to_s
+      setter = name.end_with?('=')
+      key = setter ? name.delete_suffix('=').to_sym : method_name.to_sym
+      return [false, nil] unless @values.key?(key)
+
+      [true, yield(key, setter)]
+    end
+
+    def set_value(key, value)
+      @values[key] = normalize_value(key, value)
+    end
+
+    def normalize_value(key, value)
+      return value unless @values.key?(key)
+
+      case key
+      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
+      when :enable_log_dispatch_registry
+        value ? true : false
+      when :scheduler_conflict_policy, :scheduler_missing_file_policy
+        value&.to_sym
+      else
+        value
+      end
+    end
+  end
+
+  ##
+  # Error raised when configuration is invalid.
+  class ConfigurationError < StandardError; end
+end