kaal 0.2.1 → 0.4.0

data/lib/kaal/backend/mysql_adapter.rb

@@ -1,170 +0,0 @@
-# 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 'socket'
-require 'digest'
-require_relative 'dispatch_logging'
-require_relative '../definition/database_engine'
-
-module Kaal
-  module Backend
-    ##
-    # Distributed backend adapter using MySQL named locks (GET_LOCK/RELEASE_LOCK).
-    #
-    # This adapter uses MySQL's GET_LOCK and RELEASE_LOCK functions for
-    # distributed locking across multiple nodes. Locks are connection-based
-    # and automatically released when the database connection is closed.
-    #
-    # **IMPORTANT LIMITATIONS:**
-    # - Locks are connection-scoped: if a process crashes, the lock persists until
-    #   the database connection timeout occurs (typically 28,800 seconds or 8 hours).
-    #   For critical systems, consider monitoring stale locks or using a time-based
-    #   fallback mechanism.
-    # - MySQL named locks have a maximum length of 64 characters. Lock keys longer than
-    #   64 characters use a deterministic hash-based shortening scheme (prefix + SHA256
-    #   digest) to avoid collisions while respecting the limit.
-    # - Uses non-blocking acquisition: GET_LOCK is called with timeout=0 for immediate
-    #   return (does not block waiting for the lock).
-    # - 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 MySQL adapter
-    #   Kaal.configure do |config|
-    #     config.backend = Kaal::Backend::MySQLAdapter.new
-    #     config.enable_log_dispatch_registry = true  # Enable dispatch logging
-    #   end
-    class MySQLAdapter < Adapter
-      include DispatchLogging
-
-      # MySQL named locks have a maximum length of 64 characters
-      MAX_LOCK_NAME_LENGTH = 64
-
-      def initialize
-        super
-        @lock_name_length_limit = MAX_LOCK_NAME_LENGTH
-        @false_value_pattern = /\A(0|f|false|)\z/i
-      end
-
-      ##
-      # Initialize a new MySQL adapter.
-
-      ##
-      # 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 MySQL GET_LOCK.
-      #
-      # Uses MySQL's GET_LOCK(name, timeout) function with a timeout of 0 seconds
-      # to perform non-blocking acquisition. If successful, logs the dispatch
-      # attempt when enable_log_dispatch_registry is enabled.
-      #
-      # **Note:** The +ttl+ parameter is ignored. MySQL named locks are connection-based
-      # and do not have automatic expiration. The lock will be held until explicitly
-      # released or 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_name = normalize_lock_name(key)
-
-        # GET_LOCK returns 1 on success, 0 on timeout, NULL on error
-        sql = ActiveRecord::Base.sanitize_sql_array(['SELECT GET_LOCK(?, 0) as lock_result', lock_name])
-        result_set = ActiveRecord::Base.connection.execute(sql)
-        # Convert result to array and get first row, then first column value
-        result_row = result_set.to_a.first
-        result_value = result_row.is_a?(Hash) ? result_row['lock_result'] : result_row&.first
-        acquired = cast_to_boolean(result_value)
-
-        log_dispatch_attempt(key) if acquired
-
-        acquired
-      rescue StandardError => e
-        raise LockAdapterError, "MySQL acquire failed for #{key}: #{e.message}"
-      end
-
-      ##
-      # Release a distributed lock held by MySQL GET_LOCK.
-      #
-      # @param key [String] the lock key
-      # @return [Boolean] true if released, false if not held
-      def release(key)
-        lock_name = normalize_lock_name(key)
-
-        # RELEASE_LOCK returns 1 if held and released, 0 if not held, NULL on error
-        sql = ActiveRecord::Base.sanitize_sql_array(['SELECT RELEASE_LOCK(?) as lock_result', lock_name])
-        result_set = ActiveRecord::Base.connection.execute(sql)
-        # Convert result to array and get first row, then first column value
-        result_row = result_set.to_a.first
-        result_value = result_row.is_a?(Hash) ? result_row['lock_result'] : result_row&.first
-        cast_to_boolean(result_value)
-      rescue StandardError => e
-        raise LockAdapterError, "MySQL release failed for #{key}: #{e.message}"
-      end
-
-      private
-
-      def cast_to_boolean(value)
-        # MySQL GET_LOCK/RELEASE_LOCK returns 1 (success), 0 (failure), or NULL (error).
-        # Cast integer/nil to boolean: 1 => true, 0 or nil => false.
-        case value
-        when 1
-          true
-        when 0
-          false
-        when true, false
-          value
-        else
-          !value.to_s.match?(@false_value_pattern)
-        end
-      end
-
-      ##
-      # Normalize lock names to fit MySQL's 64-character limit.
-      #
-      # For keys exceeding the limit, uses a deterministic hash-based scheme
-      # (prefix + SHA256 digest) to avoid collisions.
-      #
-      # @param key [String] the lock key to normalize
-      # @return [String] normalized key (max 64 characters)
-      def normalize_lock_name(key)
-        return key if key.length <= @lock_name_length_limit
-
-        # Use SHA256 digest to ensure uniqueness while respecting the 64-char limit.
-        # Format: "prefix:hash" where hash is first 16 hex chars (~8 bytes entropy)
-        digest = Digest::SHA256.hexdigest(key)
-        # Reserve 17 chars for `:` + 16 hex chars, use remainder for prefix
-        prefix_length = @lock_name_length_limit - 17
-        normalized = "#{key[0...prefix_length]}:#{digest[0...16]}"
-
-        Kaal.logger&.warn(
-          "Lock key '#{key}' exceeds MySQL named lock limit of #{@lock_name_length_limit} characters. " \
-          "Using hash-based shortening to avoid collisions: '#{normalized}'."
-        )
-
-        normalized
-      end
-    end
-  end
-end

data/lib/kaal/backend/postgres_adapter.rb

@@ -1,134 +0,0 @@
-# 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/sqlite_adapter.rb

@@ -1,116 +0,0 @@
-# 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/railtie.rb

@@ -1,183 +0,0 @@
-# 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 'pathname'
-
-module Kaal
-  ##
-  # Railtie class to integrate Kaal with Rails applications.
-  # Initializes configuration, sets up the default logger, and handles signal management.
-  class Railtie < ::Rails::Railtie
-    ##
-    # Ensure configuration logger uses Rails.logger when available.
-    def self.ensure_logger!
-      logger = Rails.logger
-      return unless logger
-
-      Kaal.configure do |config|
-        config.logger ||= logger
-      end
-    rescue NoMethodError
-      nil
-    end
-
-    ##
-    # Register signal handlers for graceful shutdown.
-    # Captures and chains any previously registered handlers to cooperate with other components.
-    def self.register_signal_handlers
-      logger = Kaal.logger
-
-      %w[TERM INT].each do |signal|
-        # Capture the previous handler by temporarily setting to IGNORE and restoring
-        old_handler = Signal.trap(signal, 'IGNORE')
-        Signal.trap(signal, old_handler) if old_handler && old_handler != 'IGNORE'
-
-        # Now install our handler that chains to the previous one
-        Signal.trap(signal) do
-          handle_shutdown_signal(signal, old_handler, logger)
-        end
-      end
-    rescue StandardError => e
-      logger&.warn("Failed to register signal handlers: #{e.full_message}")
-    end
-
-    ##
-    # Handle a shutdown signal and chain to previous handler.
-    def self.handle_shutdown_signal(signal, old_handler, logger)
-      logger&.info("Received #{signal} signal, stopping scheduler...")
-      begin
-        stopped = Kaal.stop!(timeout: 30)
-        logger&.warn('Scheduler did not stop within timeout, thread may still be running') unless stopped
-      rescue StandardError => e
-        logger&.error("Error stopping scheduler on #{signal} signal: #{e.full_message}")
-      end
-
-      chain_previous_handler(signal, old_handler, logger)
-    end
-
-    ##
-    # Chain to a previous signal handler if it exists.
-    def self.chain_previous_handler(signal, old_handler, logger)
-      if old_handler.respond_to?(:call)
-        old_handler.call
-      elsif old_handler.is_a?(String) && old_handler != 'DEFAULT' && old_handler != 'IGNORE'
-        # If previous handler was a command string, we can't easily re-invoke it
-        logger&.debug("Previous #{signal} handler was a command: #{old_handler}")
-      end
-    end
-
-    ##
-    # Load scheduler file at boot while respecting missing-file policy.
-    def self.load_scheduler_file_on_boot!
-      configuration = fetch_configuration_for_boot
-      return unless configuration
-
-      if configuration.scheduler_missing_file_policy == :error
-        load_scheduler_file_now!
-        return
-      end
-
-      scheduler_path = configuration.scheduler_config_path.to_s.strip
-      return if scheduler_path.empty?
-
-      absolute_path = resolve_scheduler_path(scheduler_path)
-      unless File.exist?(absolute_path)
-        Kaal.logger&.warn("Scheduler file not found at #{absolute_path}")
-        return
-      end
-
-      load_scheduler_file_now!
-    end
-
-    def self.resolve_scheduler_path(path)
-      candidate = Pathname.new(path)
-      candidate.absolute? ? candidate.to_s : Rails.root.join(candidate).to_s
-    end
-
-    def self.load_scheduler_file_now!
-      Kaal.load_scheduler_file!
-    end
-
-    def self.fetch_configuration_for_boot
-      Kaal.configuration
-    rescue NameError => e
-      Kaal.logger&.debug("Skipping scheduler file boot load due to configuration error: #{e.message}")
-      nil
-    end
-
-    ##
-    # Autoload paths for Kaal models and other components
-    initializer 'kaal.autoload' do |_app|
-      models_path = File.expand_path('../../app/models', __dir__)
-      Rails.autoloaders.main.push_dir(models_path)
-    end
-
-    ##
-    # Initialize Kaal when Rails boots.
-    # Sets the default logger to Rails.logger if available.
-    initializer 'kaal.configuration' do |_app|
-      # Set default logger to Rails.logger if not already configured
-      Kaal::Railtie.ensure_logger!
-    end
-
-    ##
-    # Load gem i18n files into Rails I18n load path for host applications.
-    initializer 'kaal.i18n', before: 'i18n.load_path' do |app|
-      locales = Dir[File.expand_path('../../config/locales/*.yml', __dir__)]
-      app.config.i18n.load_path |= locales
-    end
-
-    ##
-    # Load rake tasks into host Rails applications.
-    rake_tasks do
-      load File.expand_path('../tasks/kaal_tasks.rake', __dir__)
-    end
-
-    ##
-    # Load the default initializer after Rails has finished initialization.
-    # This ensures Rails.logger is fully available and sets up signal handlers.
-    config.after_initialize do
-      # Re-ensure logger is set in case it wasn't available during first initializer
-      Kaal::Railtie.ensure_logger!
-
-      # Load scheduler definitions from file when available (or required by policy)
-      Kaal::Railtie.load_scheduler_file_on_boot!
-
-      # Register signal handlers for graceful shutdown
-      Kaal::Railtie.register_signal_handlers
-    end
-
-    ##
-    # Handle graceful shutdown when Rails exits.
-    def self.handle_shutdown
-      return unless Kaal.running?
-
-      logger = Kaal.logger
-
-      logger&.info('Rails is shutting down, stopping Kaal scheduler...')
-      begin
-        stopped = Kaal.stop!(timeout: 10)
-        return if stopped
-
-        pid = Process.pid
-        message_array = [
-          'Kaal scheduler did not stop within timeout.',
-          "Process #{pid} may still be running. You may need to kill it manually with `kill -9 #{pid}`."
-        ]
-        logger&.warn(message_array.join(' '))
-      rescue StandardError => e
-        logger&.error("Error stopping scheduler during shutdown: #{e.message}")
-      end
-    end
-
-    ##
-    # Ensure graceful shutdown on Rails shutdown.
-    at_exit do
-      Kaal::Railtie.handle_shutdown
-    end
-  end
-end