kaal 0.2.0

data/lib/kaal/dispatch/redis_engine.rb

@@ -0,0 +1,103 @@
+# 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 'json'
+require_relative 'registry'
+
+module Kaal
+  module Dispatch
+    ##
+    # Redis-backed dispatch registry.
+    #
+    # Stores dispatch records in Redis as JSON-serialized values.
+    # Keys are automatically expired based on TTL to prevent unbounded growth.
+    #
+    # @example Usage
+    #   redis = Redis.new(url: ENV['REDIS_URL'])
+    #   registry = Kaal::Dispatch::RedisEngine.new(redis, namespace: 'myapp')
+    #   registry.log_dispatch('daily_report', Time.current, 'node-1')
+    class RedisEngine < Registry
+      # Default TTL for dispatch records (7 days in seconds)
+      DEFAULT_TTL = 7 * 24 * 60 * 60
+
+      ##
+      # Initialize a new Redis-backed registry.
+      #
+      # @param redis [Redis] Redis client instance
+      # @param namespace [String] namespace prefix for Redis keys
+      # @param ttl [Integer] TTL in seconds for dispatch records
+      def initialize(redis, namespace: 'kaal', ttl: DEFAULT_TTL)
+        super()
+        @redis = redis
+        @namespace = namespace
+        @ttl = ttl
+      end
+
+      ##
+      # Log a dispatch attempt in Redis.
+      #
+      # @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 [Hash] the stored dispatch record
+      def log_dispatch(key, fire_time, node_id, status = 'dispatched')
+        redis_key = build_redis_key(key, fire_time)
+        record = {
+          key: key,
+          fire_time: fire_time.to_i,
+          dispatched_at: Time.current.to_i,
+          node_id: node_id,
+          status: status
+        }
+
+        @redis.setex(redis_key, @ttl, JSON.generate(record))
+        record
+      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 [Hash, nil] dispatch record or nil if not found
+      def find_dispatch(key, fire_time)
+        redis_key = build_redis_key(key, fire_time)
+        value = @redis.get(redis_key)
+        return nil unless value
+
+        record = JSON.parse(value, symbolize_names: true)
+        convert_timestamps(record)
+      end
+
+      private
+
+      ##
+      # Build a Redis key from job key and fire time.
+      #
+      # Format: "namespace:cron_dispatch:key:fire_time"
+      #
+      # @param key [String] the cron job key
+      # @param fire_time [Time] the fire time
+      # @return [String] Redis key
+      def build_redis_key(key, fire_time)
+        "#{@namespace}:cron_dispatch:#{key}:#{fire_time.to_i}"
+      end
+
+      ##
+      # Convert Unix timestamps in record to Time objects.
+      #
+      # @param record [Hash] the dispatch record with Unix timestamps
+      # @return [Hash] the record with Time objects
+      def convert_timestamps(record)
+        record[:fire_time] = Time.at(record[:fire_time])
+        record[:dispatched_at] = Time.at(record[:dispatched_at])
+        record
+      end
+    end
+  end
+end

data/lib/kaal/dispatch/registry.rb

@@ -0,0 +1,62 @@
+# 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 Dispatch
+    ##
+    # Base abstraction for dispatch audit logging.
+    #
+    # Provides a pluggable interface for logging cron job dispatch attempts
+    # across different storage backends (memory, Redis, database, etc.).
+    #
+    # @example Implementing a custom registry
+    #   class MyRegistry < Kaal::Dispatch::Registry
+    #     def log_dispatch(key, fire_time, node_id, status = 'dispatched')
+    #       # Your custom implementation
+    #     end
+    #
+    #     def find_dispatch(key, fire_time)
+    #       # Your custom implementation
+    #     end
+    #   end
+    class Registry
+      ##
+      # Log a dispatch attempt for a cron job.
+      #
+      # @param key [String] the cron job key (without namespace prefix)
+      # @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.)
+      # @raise [NotImplementedError] if not overridden by a subclass
+      # @return [void]
+      def log_dispatch(_key, _fire_time, _node_id, _status = 'dispatched')
+        raise NotImplementedError, "#{self.class.name} must implement #log_dispatch"
+      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
+      # @raise [NotImplementedError] if not overridden by a subclass
+      # @return [Hash, nil] dispatch record or nil if not found
+      def find_dispatch(_key, _fire_time)
+        raise NotImplementedError, "#{self.class.name} must implement #find_dispatch"
+      end
+
+      ##
+      # Check if a dispatch has been logged 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 [Boolean] true if dispatch exists, false otherwise
+      def dispatched?(key, fire_time)
+        find_dispatch(key, fire_time) ? true : false
+      end
+    end
+  end
+end

data/lib/kaal/idempotency_key_generator.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Kaal
+  ##
+  # Utility class for generating idempotency keys.
+  #
+  # Centralizes the key format to prevent drift between public API and internal coordinator.
+  # Format: {namespace}-{cron_key}-{fire_time_unix}
+  #
+  # @example Generate a key
+  #   key = Kaal::IdempotencyKeyGenerator.call('reports:daily', Time.current, configuration: config)
+  #   # => "kaal-reports:daily-1708283400"
+  class IdempotencyKeyGenerator
+    ##
+    # Generate an idempotency key for a cron job.
+    #
+    # @param cron_key [String] the cron job key
+    # @param fire_time [Time] the fire time
+    # @param configuration [Configuration] the Kaal configuration instance
+    # @return [String] the formatted idempotency key
+    def self.call(cron_key, fire_time, configuration:)
+      namespace = configuration.namespace || 'kaal'
+      "#{namespace}-#{cron_key}-#{fire_time.to_i}"
+    end
+  end
+end

data/lib/kaal/railtie.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+# 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
+  ##
+  # 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

data/lib/kaal/rake_tasks.rb

@@ -0,0 +1,184 @@
+# 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 'rake'
+
+module Kaal
+  ##
+  # Defines Kaal rake tasks on a given Rake application.
+  module RakeTasks
+    SIGNALS = %w[TERM INT].freeze
+    SHUTDOWN_TIMEOUT = 30
+    RESERVED_SIGNAL_HANDLERS = %w[DEFAULT IGNORE SYSTEM_DEFAULT EXIT].freeze
+
+    module_function
+
+    def install(rake_application = Rake.application)
+      rake_application.extend(Rake::DSL)
+
+      rake_application.instance_eval do
+        namespace :kaal do
+          Kaal::RakeTasks.define_tick_task(self)
+          Kaal::RakeTasks.define_status_task(self)
+          Kaal::RakeTasks.define_explain_task(self)
+          Kaal::RakeTasks.define_start_task(self)
+        end
+      end
+    end
+
+    def define_tick_task(context)
+      context.instance_eval do
+        desc 'Perform a single scheduler tick'
+        task tick: :environment do
+          Kaal.tick!
+          puts 'Kaal tick completed'
+        rescue StandardError => e
+          abort("kaal:tick failed: #{e.message}")
+        end
+      end
+    end
+
+    def define_status_task(context)
+      context.instance_eval do
+        desc 'Show scheduler status, configuration, and registered cron jobs'
+        task status: :environment do
+          puts "Kaal v#{Kaal::VERSION}"
+          puts "Running: #{Kaal.running?}"
+          puts "Tick interval: #{Kaal.tick_interval}s"
+          puts "Window lookback: #{Kaal.window_lookback}s"
+          puts "Window lookahead: #{Kaal.window_lookahead}s"
+          puts "Lease TTL: #{Kaal.lease_ttl}s"
+          puts "Namespace: #{Kaal.namespace}"
+
+          entries = Kaal.registered
+          puts "Registered jobs: #{entries.length}"
+          entries.each do |entry|
+            puts "  - #{entry.key} (#{entry.cron})"
+          end
+        rescue StandardError => e
+          abort("kaal:status failed: #{e.message}")
+        end
+      end
+    end
+
+    def define_explain_task(context)
+      context.instance_eval do
+        desc 'Humanize a cron expression, e.g. rake kaal:explain["*/5 * * * *"]'
+        task :explain, [:expr] => :environment do |_task, args|
+          expression = args[:expr].to_s.strip
+          abort('kaal:explain requires expr argument') if expression.empty?
+
+          puts Kaal.to_human(expression)
+        rescue StandardError => e
+          abort("kaal:explain failed: #{e.message}")
+        end
+      end
+    end
+
+    def define_start_task(context)
+      context.instance_eval do
+        desc 'Start scheduler loop in foreground (blocks until stopped)'
+        task start: :environment do
+          signal_state = {
+            graceful_shutdown_started: false,
+            shutdown_complete: false,
+            force_exit_requested: false
+          }
+          previous_handlers = Kaal::RakeTasks.install_foreground_signal_handlers(signal_state)
+
+          begin
+            thread = Kaal.start!
+            abort('kaal:start failed: scheduler is already running') unless thread
+
+            puts 'Kaal scheduler started in foreground'
+            thread.join
+          ensure
+            Kaal::RakeTasks.restore_signal_handlers(previous_handlers)
+          end
+        rescue Interrupt
+          abort('kaal:start failed: shutdown timed out; forced exit requested') if signal_state[:force_exit_requested]
+
+          Kaal::RakeTasks.shutdown_scheduler(signal: 'INT', signal_state: signal_state)
+        rescue StandardError => e
+          abort("kaal:start failed: #{e.message}")
+        end
+      end
+    end
+
+    def install_foreground_signal_handlers(signal_state)
+      SIGNALS.each_with_object({}) do |signal, handlers|
+        previous_handler = capture_previous_signal_handler(signal)
+        Signal.trap(signal) do
+          shutdown_scheduler(signal: signal, signal_state: signal_state, previous_handler: previous_handler)
+        end
+        handlers[signal] = previous_handler
+      end
+    end
+
+    def capture_previous_signal_handler(signal)
+      previous_handler = Signal.trap(signal, 'IGNORE')
+      Signal.trap(signal, previous_handler)
+      previous_handler
+    end
+
+    def restore_signal_handlers(previous_handlers)
+      previous_handlers.each do |signal, handler|
+        Signal.trap(signal, handler)
+      rescue StandardError
+        nil
+      end
+    end
+
+    def shutdown_scheduler(signal:, signal_state:, previous_handler: nil)
+      return if signal_state[:shutdown_complete]
+
+      if signal_state[:graceful_shutdown_started]
+        signal_state[:force_exit_requested] = true
+        warn("Received #{signal} again; forcing scheduler shutdown")
+        Thread.main.raise(Interrupt)
+        return
+      end
+
+      signal_state[:graceful_shutdown_started] = true
+      puts "Received #{signal}, stopping Kaal scheduler..."
+      stopped = Kaal.stop!(timeout: SHUTDOWN_TIMEOUT)
+      if stopped
+        signal_state[:shutdown_complete] = true
+        puts 'Kaal scheduler stopped'
+      else
+        warn('Kaal scheduler stop timed out; send TERM/INT again to force exit')
+      end
+    rescue StandardError => e
+      warn("kaal:start shutdown failed: #{e.message}")
+    ensure
+      chain_previous_handler(signal, previous_handler)
+    end
+
+    def chain_previous_handler(signal, previous_handler)
+      return unless previous_handler
+
+      case previous_handler
+      when Proc, Method
+        invoke_previous_handler(previous_handler, signal)
+      when String
+        return if RESERVED_SIGNAL_HANDLERS.include?(previous_handler)
+
+        warn("kaal:start previous #{signal} handler is a command: #{previous_handler}")
+      end
+    rescue StandardError
+      nil
+    end
+
+    def invoke_previous_handler(handler, signal)
+      signal_number = Signal.list[signal]
+      callable_arity = handler.arity
+      return handler.call if callable_arity.zero?
+
+      handler.call(signal_number)
+    end
+  end
+end

data/lib/kaal/register_conflict_support.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Kaal
+  # Register conflict handling helpers shared by Kaal singleton methods.
+  module RegisterConflictSupport
+    private
+
+    def resolve_register_conflict(key:, cron:, enqueue:, existing_definition:, existing_entry:)
+      return unless existing_definition&.[](:source).to_s == 'file'
+
+      policy = configuration.scheduler_conflict_policy
+      case policy
+      when :error
+        raise RegistryError, "Key '#{key}' is already registered by scheduler file"
+      when :file_wins
+        configuration.logger&.warn("Skipping code registration for '#{key}' because scheduler_conflict_policy is :file_wins")
+        existing_entry
+      when :code_wins
+        replace_file_registered_definition(
+          key: key,
+          cron: cron,
+          enqueue: enqueue,
+          existing_definition: existing_definition
+        )
+      else
+        raise SchedulerConfigError, "Unsupported scheduler_conflict_policy '#{policy}'"
+      end
+    end
+
+    def replace_file_registered_definition(key:, cron:, enqueue:, existing_definition:)
+      persisted_attributes = {
+        enabled: existing_definition.fetch(:enabled, true),
+        source: 'code',
+        metadata: existing_definition.fetch(:metadata, {})
+      }
+      definition_registry.upsert_definition(key: key, cron: cron, **persisted_attributes)
+      with_registered_definition_rollback(key, existing_definition) do
+        registry.upsert(key: key, cron: cron, enqueue: enqueue)
+      end
+    end
+
+    def with_registered_definition_rollback(key, existing_definition)
+      yield
+    rescue StandardError
+      begin
+        rollback_registered_definition(key, existing_definition)
+      rescue StandardError => rollback_error
+        configuration.logger&.error("Failed to rollback persisted definition for #{key}: #{rollback_error.message}")
+      end
+
+      raise
+    end
+  end
+end