kaal 0.2.1 → 0.3.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/definition/database_engine.rb

@@ -1,50 +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 'registry'
-
-module Kaal
-  module Definition
-    # ActiveRecord-backed definition registry persisted in kaal_definitions.
-    class DatabaseEngine < Registry
-      def initialize
-        super
-        @definition_model = ::Kaal::CronDefinition
-      end
-
-      def upsert_definition(key:, cron:, enabled: true, source: 'code', metadata: {})
-        @definition_model.upsert_definition!(
-          key: key,
-          cron: cron,
-          enabled: enabled,
-          source: source,
-          metadata: metadata
-        ).to_definition_hash
-      end
-
-      def remove_definition(key)
-        record = @definition_model.find_by(key: key)
-        return nil unless record
-
-        record.destroy_and_return_definition_hash
-      end
-
-      def find_definition(key)
-        record = @definition_model.find_by(key: key)
-        record&.to_definition_hash
-      end
-
-      def all_definitions
-        @definition_model.order(:key).map(&:to_definition_hash)
-      end
-
-      def enabled_definitions
-        @definition_model.where(enabled: true).order(:key).map(&:to_definition_hash)
-      end
-    end
-  end
-end

data/lib/kaal/dispatch/database_engine.rb

@@ -1,94 +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 'registry'
-
-module Kaal
-  module Dispatch
-    ##
-    # Database-backed dispatch registry using ActiveRecord.
-    #
-    # Stores dispatch records in the database using the CronDispatch model.
-    # Provides persistent, queryable audit logs across all nodes.
-    #
-    # @example Usage
-    #   registry = Kaal::Dispatch::DatabaseEngine.new
-    #   registry.log_dispatch('daily_report', Time.current, 'node-1')
-    #   registry.dispatched?('daily_report', Time.current) # => true
-    class DatabaseEngine < Registry
-      ##
-      # Log a dispatch attempt in the database.
-      #
-      # @param key [String] the cron job key
-      # @param fire_time [Time] when the job was scheduled to fire
-      # @param node_id [String] identifier for the dispatching node
-      # @param status [String] dispatch status ('dispatched', 'failed', etc.)
-      # @return [Kaal::CronDispatch] the created dispatch record
-      # @raise [ActiveRecord::RecordInvalid] if the record is invalid
-      def log_dispatch(key, fire_time, node_id, status = 'dispatched')
-        ::Kaal::CronDispatch.create!(
-          key: key,
-          fire_time: fire_time,
-          dispatched_at: Time.current,
-          node_id: node_id,
-          status: status
-        )
-      end
-
-      ##
-      # Find a dispatch record for a specific job and fire time.
-      #
-      # @param key [String] the cron job key
-      # @param fire_time [Time] when the job was scheduled to fire
-      # @return [Kaal::CronDispatch, nil] dispatch record or nil if not found
-      def find_dispatch(key, fire_time)
-        ::Kaal::CronDispatch.find_by(key: key, fire_time: fire_time)
-      end
-
-      ##
-      # Find all dispatch records for a specific job key.
-      #
-      # @param key [String] the cron job key
-      # @return [ActiveRecord::Relation] collection of dispatch records
-      def find_by_key(key)
-        ::Kaal::CronDispatch.where(key: key).order(fire_time: :desc)
-      end
-
-      ##
-      # Find all dispatch records by node ID.
-      #
-      # @param node_id [String] the node identifier
-      # @return [ActiveRecord::Relation] collection of dispatch records
-      def find_by_node(node_id)
-        ::Kaal::CronDispatch.where(node_id: node_id).order(fire_time: :desc)
-      end
-
-      ##
-      # Find all dispatch records with a specific status.
-      #
-      # @param status [String] the dispatch status
-      # @return [ActiveRecord::Relation] collection of dispatch records
-      def find_by_status(status)
-        ::Kaal::CronDispatch.where(status: status).order(fire_time: :desc)
-      end
-
-      ##
-      # Delete old dispatch records older than the specified time.
-      #
-      # This cleanup prevents unbounded database growth by removing records
-      # that are older than the recovery window, making them irrelevant for
-      # future recovery operations.
-      #
-      # @param recovery_window [Integer] seconds to keep records for (e.g., 86400 for 24h)
-      # @return [Integer] number of records deleted
-      def cleanup(recovery_window: 86_400)
-        cutoff_time = Time.current - recovery_window
-        ::Kaal::CronDispatch.where('fire_time < ?', cutoff_time).delete_all
-      end
-    end
-  end
-end