kaal 0.2.0

data/lib/generators/kaal/install/templates/create_kaal_locks.rb.tt

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Creates the lock table for database-backed lease coordination.
+class CreateKaalLocks < ActiveRecord::Migration[7.0]
+  def change
+    create_table :kaal_locks do |t|
+      t.string :key, null: false, limit: 255
+      t.datetime :acquired_at, null: false
+      t.datetime :expires_at, null: false
+
+      t.timestamps
+    end
+
+    add_index :kaal_locks, :key, unique: true
+    add_index :kaal_locks, :expires_at
+  end
+end

data/lib/generators/kaal/install/templates/kaal.rb.tt

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+Kaal.configure do |config|
+  # Select the backend that matches your deployment.
+  # See the Kaal documentation for backend-specific setup and the full
+  # configuration reference.
+  #
+  # Redis (recommended for multi-node deployments):
+  # config.backend = Kaal::Backend::RedisAdapter.new(Redis.new(url: ENV.fetch('REDIS_URL')))
+  #
+  # PostgreSQL advisory locks:
+  # config.backend = Kaal::Backend::PostgresAdapter.new
+  #
+  # MySQL / SQLite database-backed coordination:
+  # config.backend = Kaal::Backend::SQLiteAdapter.new
+
+  config.tick_interval = 5
+  config.window_lookback = 120
+  # Keep lease_ttl >= window_lookback + tick_interval to prevent duplicate dispatch.
+  config.lease_ttl = 125
+  config.recovery_window = 3600
+  config.enable_dispatch_recovery = true
+  config.enable_log_dispatch_registry = false
+
+  # Scheduler file loading
+  config.scheduler_config_path = 'config/scheduler.yml'
+  # :error, :code_wins, :file_wins
+  config.scheduler_conflict_policy = :error
+  # :warn, :error
+  config.scheduler_missing_file_policy = :warn
+end

data/lib/generators/kaal/install/templates/scheduler.yml.tt

@@ -0,0 +1,22 @@
+defaults:
+  jobs:
+    - key: "reports:weekly_summary"
+      cron: "0 9 * * 1"
+      job_class: "WeeklySummaryJob"
+      enabled: true
+      queue: "default"
+      args:
+        - "{{fire_time.iso8601}}"
+      kwargs:
+        idempotency_key: "{{idempotency_key}}"
+      metadata:
+        owner: "ops"
+
+development:
+  jobs: []
+
+test:
+  jobs: []
+
+production:
+  jobs: []

data/lib/kaal/backend/adapter.rb

@@ -0,0 +1,147 @@
+# 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
+  module Backend
+    ##
+    # Abstract base class for distributed backend adapters.
+    #
+    # Backend adapters are responsible for distributed coordination (acquire/release)
+    # and may also expose cron definition and dispatch registries for persistence.
+    #
+    # @example Implementing a backend adapter
+    #   class MyBackendAdapter < Kaal::Backend::Adapter
+    #     def acquire(key, ttl)
+    #       # Try to acquire a lock with key and TTL
+    #       # Return true if acquired, false otherwise
+    #     end
+    #
+    #     def release(key)
+    #       # Release the lock for key
+    #     end
+    #   end
+    class Adapter
+      ##
+      # Attempt to acquire a distributed lock.
+      #
+      # @param key [String] the lock key (e.g., "namespace:cron:key:timestamp")
+      # @param ttl [Integer] time-to-live in seconds before the lock auto-expires
+      # @return [Boolean] true if lock was acquired, false if already held by another process
+      #
+      # @raise [NotImplementedError] if not implemented by subclass
+      #
+      # @example
+      #   adapter = MyBackendAdapter.new
+      #   acquired = adapter.acquire("kaal:job1:1234567890", 60)
+      #   if acquired
+      #     # Do work...
+      #   end
+      def acquire(_key, _ttl)
+        raise NotImplementedError, 'Subclasses must implement #acquire'
+      end
+
+      ##
+      # Release a previously acquired lock.
+      #
+      # @param key [String] the lock key to release
+      # @return [Boolean] true if released, false if not held
+      #
+      # @raise [NotImplementedError] if not implemented by subclass
+      #
+      # @example
+      #   adapter.release("kaal:job1:1234567890")
+      def release(_key)
+        raise NotImplementedError, 'Subclasses must implement #release'
+      end
+
+      ##
+      # Acquire a lock, execute the block, then release the lock.
+      #
+      # This is a convenience method that ensures the lock is properly released
+      # even if the block raises an exception. If the lock cannot be acquired,
+      # returns nil without executing the block.
+      #
+      # @param key [String] the lock key
+      # @param ttl [Integer] time-to-live in seconds
+      # @yield executes the block if lock is acquired
+      # @return [Object] the result of the block if executed, nil if lock not acquired
+      #
+      # @example
+      #   result = adapter.with_lock("kaal:job1:1234567890", ttl: 60) do
+      #     # Do protected work
+      #     42
+      #   end
+      #   # result is 42 if lock acquired, nil otherwise
+      def with_lock(key, ttl:)
+        return nil unless acquire(key, ttl)
+
+        begin
+          yield
+        ensure
+          release(key)
+        end
+      end
+
+      ##
+      # Optional definition registry for persistent cron definitions.
+      #
+      # Backends may override this to provide a concrete implementation.
+      #
+      # @return [Kaal::Definition::Registry, nil]
+      def definition_registry
+        nil
+      end
+    end
+
+    ##
+    # Null backend adapter that always succeeds (useful for development/testing).
+    #
+    # This adapter provides a no-op implementation: it always returns true
+    # for acquire and does nothing on release. Use this when you want to run
+    # the scheduler without distributed coordination (e.g., single-node development).
+    #
+    # @example Using the null adapter
+    #   Kaal.configure do |config|
+    #     config.backend = Kaal::Backend::NullAdapter.new
+    #   end
+    class NullAdapter < Adapter
+      ##
+      # Always returns true (lock always "acquired").
+      #
+      # @param _key [String] unused
+      # @param _ttl [Integer] unused
+      # @return [Boolean] always true
+      def acquire(_key, _ttl) # rubocop:disable Naming/PredicateMethod
+        true
+      end
+
+      ##
+      # No-op implementation (nothing to release).
+      #
+      # @param _key [String] unused
+      # @return [Boolean] always true
+      def release(_key) # rubocop:disable Naming/PredicateMethod
+        true
+      end
+
+      ##
+      # Execute the block without any actual locking (always succeeds).
+      #
+      # @param key [String] unused
+      # @param ttl [Integer] unused
+      # @yield executes the block immediately
+      # @return [Object] the result of the block
+      def with_lock(_key, **)
+        yield
+      end
+    end
+
+    ##
+    # Error raised when a backend adapter operation fails.
+    class LockAdapterError < StandardError; end
+  end
+end

data/lib/kaal/backend/dispatch_logging.rb

@@ -0,0 +1,79 @@
+# 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'
+
+module Kaal
+  module Backend
+    ##
+    # Shared module for dispatch logging across backend adapters.
+    #
+    # Provides methods to log cron job dispatch attempts via the dispatch registry
+    # for audit and observability purposes. Adapters that support dispatch logging
+    # should include this module and implement a dispatch_registry method.
+    #
+    # @example Implementing in an adapter
+    #   class MyAdapter < Adapter
+    #     include DispatchLogging
+    #
+    #     def dispatch_registry
+    #       @dispatch_registry ||= Kaal::Dispatch::MemoryEngine.new
+    #     end
+    #   end
+    module DispatchLogging
+      ##
+      # Log a dispatch attempt via the dispatch registry.
+      #
+      # Only logs if Kaal.configuration.enable_log_dispatch_registry is true.
+      #
+      # @param key [String] the lock key (format: "namespace:dispatch:cron_key:fire_time")
+      # @return [void]
+      def log_dispatch_attempt(key)
+        logger = nil
+        logging_enabled = Kaal.configuration.then do |configuration|
+          logger = configuration.logger
+          configuration.enable_log_dispatch_registry
+        end
+        return unless logging_enabled
+        return unless respond_to?(:dispatch_registry)
+
+        registry = dispatch_registry
+        return unless registry
+
+        cron_key, fire_time = parse_lock_key(key)
+        node_id = Socket.gethostname
+
+        registry.log_dispatch(cron_key, fire_time, node_id, 'dispatched')
+      rescue StandardError => e
+        logger&.error("Failed to log dispatch for #{key}: #{e.message}")
+      end
+
+      ##
+      # Parse a lock key to extract cron job key and fire time.
+      #
+      # Lock key format: "namespace:dispatch:cron_key:fire_time"
+      # Parses by splitting on colon: removes namespace and "dispatch", then
+      # rejoins remaining parts as the cron key.
+      #
+      # @param key [String] the lock key to parse
+      # @return [Array<String, Time>] tuple of [cron_key, fire_time]
+      def parse_lock_key(key)
+        DispatchLogging.parse_lock_key(key)
+      end
+
+      def self.parse_lock_key(key)
+        parts = key.split(':')
+        fire_time_unix = parts.pop.to_i
+        2.times { parts.shift } # Remove namespace and "dispatch"
+        cron_key = parts.join(':')
+        fire_time = Time.at(fire_time_unix)
+
+        [cron_key, fire_time]
+      end
+    end
+  end
+end

data/lib/kaal/backend/memory_adapter.rb

@@ -0,0 +1,99 @@
+# 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/memory_engine'
+
+module Kaal
+  module Backend
+    ##
+    # In-memory backend adapter using Mutex and Hash.
+    #
+    # This adapter stores locks in memory with TTL tracking. Locks are stored
+    # with an expiration time and automatically considered released if the TTL
+    # has passed.
+    #
+    # **IMPORTANT**: This adapter is suitable only for single-node deployments
+    # (development, testing). For multi-node production systems, use Redis or
+    # PostgreSQL adapters instead.
+    #
+    # @example Using the memory adapter
+    #   Kaal.configure do |config|
+    #     config.backend = Kaal::Backend::MemoryAdapter.new
+    #     config.enable_log_dispatch_registry = true  # Enable dispatch logging
+    #   end
+    class MemoryAdapter < Adapter
+      include DispatchLogging
+
+      def initialize
+        super
+        @locks = {}
+        @mutex = Mutex.new
+      end
+
+      ##
+      # Get the dispatch registry for in-memory logging.
+      #
+      # @return [Kaal::Dispatch::MemoryEngine] memory engine instance
+      def dispatch_registry
+        @dispatch_registry ||= Kaal::Dispatch::MemoryEngine.new
+      end
+
+      ##
+      # Get the definition registry for in-memory definition persistence.
+      #
+      # @return [Kaal::Definition::MemoryEngine] memory engine instance
+      def definition_registry
+        @definition_registry ||= Kaal::Definition::MemoryEngine.new
+      end
+
+      ##
+      # Attempt to acquire a lock in memory.
+      #
+      # Opportunistically prunes expired locks to prevent unbounded memory growth.
+      # Since the coordinator generates unique keys per dispatch and relies on TTL
+      # expiration without calling release, this pruning is essential.
+      #
+      # @param key [String] the lock key
+      # @param ttl [Integer] time-to-live in seconds
+      # @return [Boolean] true if acquired (key was free or expired), false if held by another process
+      def acquire(key, ttl)
+        acquired = @mutex.synchronize do
+          prune_expired_locks
+          expiration_time = @locks[key]
+          current_time = Time.current
+          next false if expiration_time && expiration_time > current_time
+
+          @locks[key] = current_time + ttl.seconds
+          true
+        end
+
+        log_dispatch_attempt(key) if acquired
+
+        acquired
+      end
+
+      ##
+      # Release a lock from memory.
+      #
+      # @param key [String] the lock key to release
+      # @return [Boolean] true if released (key was held), false if not held
+      def release(key)
+        @mutex.synchronize do
+          @locks.delete(key).present?
+        end
+      end
+
+      private
+
+      def prune_expired_locks
+        now = Time.current
+        @locks.delete_if { |_key, expiration_time| expiration_time <= now }
+      end
+    end
+  end
+end

data/lib/kaal/backend/mysql_adapter.rb

@@ -0,0 +1,170 @@
+# 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