kaal 0.2.1 → 0.3.0

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

data/lib/kaal/rake_tasks.rb

@@ -1,184 +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 '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/scheduler_file_loader.rb

@@ -1,321 +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 'erb'
-require 'pathname'
-require 'yaml'
-require 'active_support/core_ext/hash/deep_merge'
-require 'active_support/core_ext/object/deep_dup'
-require 'active_support/core_ext/string/inflections'
-require_relative 'scheduler_hash_transform'
-require_relative 'scheduler_placeholder_support'
-
-module Kaal
-  # Loads scheduler definitions from config/scheduler.yml and registers them.
-  class SchedulerFileLoader
-    include SchedulerHashTransform
-    include SchedulerPlaceholderSupport
-
-    PLACEHOLDER_PATTERN = /\{\{\s*([a-zA-Z0-9_.]+)\s*\}\}/
-    ALLOWED_PLACEHOLDERS = {
-      'fire_time.iso8601' => ->(ctx) { ctx.fetch(:fire_time).iso8601 },
-      'fire_time.unix' => ->(ctx) { ctx.fetch(:fire_time).to_i },
-      'idempotency_key' => ->(ctx) { ctx.fetch(:idempotency_key) },
-      'key' => ->(ctx) { ctx.fetch(:key) }
-    }.freeze
-
-    def initialize(configuration:, definition_registry:, registry:, logger:, rails_context: Rails)
-      @configuration = configuration
-      @definition_registry = definition_registry
-      @registry = registry
-      @logger = logger
-      @rails_env = rails_context.env.to_s
-      @rails_root = rails_context.root
-      @placeholder_resolvers = ALLOWED_PLACEHOLDERS
-    end
-
-    def load
-      applied_job_contexts = []
-      path = scheduler_file_path
-      return handle_missing_file(path) unless File.exist?(path)
-
-      payload = parse_yaml(path)
-      jobs = extract_jobs(payload)
-      validate_unique_keys(jobs)
-      normalized_jobs = jobs.map { |job_payload| normalize_job(job_payload) }
-      applied_jobs = []
-      normalized_jobs.each do |job|
-        applied_job_context = apply_job(**job)
-        next unless applied_job_context
-
-        applied_jobs << job
-        applied_job_contexts << applied_job_context
-      end
-
-      applied_jobs
-    rescue StandardError
-      rollback_applied_jobs(applied_job_contexts)
-      raise
-    end
-
-    private
-
-    def scheduler_file_path
-      configured_path = @configuration.scheduler_config_path.to_s.strip
-      raise SchedulerConfigError, 'scheduler_config_path cannot be blank' if configured_path.empty?
-
-      path = Pathname.new(configured_path)
-      path.absolute? ? path.to_s : @rails_root.join(path).to_s
-    end
-
-    def handle_missing_file(path)
-      message = "Scheduler file not found at #{path}"
-      raise SchedulerConfigError, message if @configuration.scheduler_missing_file_policy == :error
-
-      @logger&.warn(message)
-      []
-    end
-
-    def parse_yaml(path)
-      rendered = render_yaml_erb(path)
-      parsed = YAML.safe_load(rendered) || {}
-      raise SchedulerConfigError, "Expected scheduler YAML root to be a mapping in #{path}" unless parsed.is_a?(Hash)
-
-      stringify_keys(parsed)
-    rescue Psych::Exception => e
-      raise SchedulerConfigError, "Failed to parse scheduler YAML at #{path}: #{e.message}"
-    end
-
-    def render_yaml_erb(path)
-      ERB.new(File.read(path), trim_mode: '-').result
-    rescue StandardError, SyntaxError => e
-      raise SchedulerConfigError, "Failed to evaluate scheduler ERB at #{path}: #{e.message}"
-    end
-
-    def extract_jobs(payload)
-      defaults = fetch_hash(payload, 'defaults')
-      env_payload = fetch_hash(payload, @rails_env)
-      default_jobs = defaults.fetch('jobs', [])
-      env_jobs = env_payload.fetch('jobs', [])
-      raise SchedulerConfigError, "Expected 'defaults.jobs' to be an array" unless default_jobs.is_a?(Array)
-      raise SchedulerConfigError, "Expected '#{@rails_env}.jobs' to be an array" unless env_jobs.is_a?(Array)
-
-      default_jobs + env_jobs
-    end
-
-    def fetch_hash(payload, key)
-      section = payload.fetch(key)
-
-      raise SchedulerConfigError, "Expected '#{key}' section to be a mapping" unless section.is_a?(Hash)
-
-      section
-    rescue KeyError
-      {}
-    end
-
-    def validate_unique_keys(jobs)
-      keys = jobs.map do |job_payload|
-        raise SchedulerConfigError, "Each jobs entry must be a mapping, got #{job_payload.class}" unless job_payload.is_a?(Hash)
-
-        stringify_keys(job_payload)['key'].to_s.strip
-      end
-      duplicates = keys.group_by(&:itself).select { |key, arr| !key.empty? && arr.size > 1 }.keys
-      return if duplicates.empty?
-
-      raise SchedulerConfigError, "Duplicate job keys in scheduler file: #{duplicates.join(', ')}"
-    end
-
-    def normalize_job(job_payload)
-      payload = stringify_keys(job_payload)
-      key = payload.fetch('key', '').to_s.strip
-      raise SchedulerConfigError, 'Job key cannot be blank' if key.empty?
-
-      cron = extract_required_string(payload, field: 'cron', error_prefix: "Job cron cannot be blank for key '#{key}'")
-      job_class_name = extract_required_string(
-        payload, field: 'job_class', error_prefix: "Job class cannot be blank for key '#{key}'"
-      )
-      validate_cron(key:, cron:)
-      options = extract_job_options(payload, key:)
-
-      {
-        key:,
-        cron:,
-        job_class_name:,
-        **options
-      }
-    end
-
-    def extract_required_string(payload, field:, error_prefix:)
-      value = payload.fetch(field, '').to_s.strip
-
-      raise SchedulerConfigError, error_prefix if value.empty?
-
-      value
-    end
-
-    def validate_cron(key:, cron:)
-      return if Kaal.valid?(cron)
-
-      raise SchedulerConfigError, "Invalid cron expression '#{cron}' for key '#{key}'"
-    end
-
-    def extract_job_options(payload, key:)
-      metadata, args, kwargs, queue, enabled_value = payload.values_at('metadata', 'args', 'kwargs', 'queue', 'enabled')
-      args ||= []
-      kwargs ||= {}
-      enabled = true
-      if payload.key?('enabled')
-        raise SchedulerConfigError, "enabled must be a boolean for key '#{key}'" unless enabled_value.is_a?(TrueClass) || enabled_value.is_a?(FalseClass)
-
-        enabled = enabled_value
-      end
-
-      raise SchedulerConfigError, "metadata must be a mapping for key '#{key}'" if metadata && !metadata.is_a?(Hash)
-
-      validate_job_option_types(key:, args:, kwargs:, queue:)
-
-      validate_placeholders(args, key:)
-      validate_placeholders(kwargs, key:)
-
-      { queue: queue, args: args.deep_dup, kwargs: kwargs.deep_dup, enabled: enabled, metadata: metadata ? metadata.deep_dup : {} }
-    end
-
-    def validate_job_option_types(key:, args:, kwargs:, queue:)
-      raise SchedulerConfigError, "args must be an array for key '#{key}'" unless args.is_a?(Array)
-      raise SchedulerConfigError, "kwargs must be a mapping for key '#{key}'" unless kwargs.is_a?(Hash)
-      raise SchedulerConfigError, "queue must be a string for key '#{key}'" if queue && !queue.is_a?(String)
-      return if kwargs.keys.all? { |kwargs_key| kwargs_key.is_a?(String) || kwargs_key.is_a?(Symbol) }
-
-      raise SchedulerConfigError, "kwargs keys must be strings or symbols for key '#{key}'"
-    end
-
-    def apply_job(key:, cron:, job_class_name:, queue:, args:, kwargs:, enabled:, metadata:)
-      existing_definition = @definition_registry.find_definition(key)
-      existing_registry_entry = @registry.find(key)
-      return if skip_due_to_conflict?(key:, existing_definition:)
-
-      callback = build_callback(
-        key: key,
-        job_class_name: job_class_name,
-        queue: queue,
-        args_template: args,
-        kwargs_template: kwargs
-      )
-      normalized_metadata = stringify_keys(metadata.deep_dup)
-      persisted_metadata = normalized_metadata.deep_merge(
-        'execution' => {
-          'target' => 'active_job',
-          'job_class' => job_class_name,
-          'queue' => queue,
-          'args' => args,
-          'kwargs' => kwargs
-        }
-      )
-
-      @definition_registry.upsert_definition(
-        key: key,
-        cron: cron,
-        enabled: enabled,
-        source: 'file',
-        metadata: persisted_metadata
-      )
-
-      begin
-        @registry.upsert(key: key, cron: cron, enqueue: callback)
-      rescue StandardError
-        rollback_applied_job(key:, existing_definition:, existing_registry_entry:)
-        raise
-      end
-
-      { key: key, existing_definition: existing_definition, existing_registry_entry: existing_registry_entry }
-    end
-
-    def rollback_applied_jobs(applied_job_contexts = [])
-      applied_job_contexts.reverse_each do |applied_job_context|
-        rollback_applied_job(**applied_job_context)
-      end
-    end
-
-    def rollback_applied_job(key:, existing_definition:, existing_registry_entry:)
-      if existing_definition
-        definition_attributes = existing_definition.slice(:key, :cron, :enabled, :source, :metadata)
-        @definition_registry.upsert_definition(**definition_attributes)
-      else
-        @definition_registry.remove_definition(key)
-      end
-
-      @registry.remove(key) if @registry.registered?(key)
-
-      return unless existing_registry_entry
-
-      @registry.upsert(
-        key: existing_registry_entry.key,
-        cron: existing_registry_entry.cron,
-        enqueue: existing_registry_entry.enqueue
-      )
-    rescue StandardError => e
-      @logger&.error("Failed to rollback scheduler file application for #{key}: #{e.message}")
-    end
-
-    def skip_due_to_conflict?(key:, existing_definition:)
-      existing_source = existing_definition&.[](:source)
-      return false unless existing_source && existing_source.to_s != 'file'
-
-      policy = @configuration.scheduler_conflict_policy
-      case policy
-      when :error
-        raise SchedulerConfigError, "Scheduler key conflict for '#{key}' with existing source '#{existing_source}'"
-      when :code_wins
-        @logger&.warn("Skipping scheduler file job '#{key}' because scheduler_conflict_policy is :code_wins")
-        true
-      when :file_wins
-        false
-      else
-        raise SchedulerConfigError, "Unsupported scheduler_conflict_policy '#{policy}'"
-      end
-    end
-
-    def build_callback(key:, job_class_name:, queue:, args_template:, kwargs_template:)
-      job_class = resolve_job_class(job_class_name:, key:)
-      lambda do |fire_time:, idempotency_key:|
-        context = {
-          fire_time: fire_time,
-          idempotency_key: idempotency_key,
-          key: key
-        }
-        resolved_args = resolve_placeholders(args_template.deep_dup, context)
-        raw_kwargs = resolve_placeholders(kwargs_template.deep_dup, context) || {}
-        raise SchedulerConfigError, "kwargs for scheduler job '#{key}' must be a mapping, got #{raw_kwargs.class}" unless raw_kwargs.is_a?(Hash)
-
-        keys = raw_kwargs.keys
-        index = 0
-        while index < keys.length
-          kwargs_key = keys[index]
-          unless kwargs_key.is_a?(String) || kwargs_key.is_a?(Symbol)
-            raise SchedulerConfigError,
-                  "Invalid keyword argument key #{kwargs_key.inspect} (#{kwargs_key.class}) for scheduler job '#{key}'"
-          end
-
-          index += 1
-        end
-
-        resolved_kwargs = raw_kwargs.transform_keys(&:to_sym)
-
-        target = queue ? job_class.set(queue: queue) : job_class
-        target.perform_later(*resolved_args, **resolved_kwargs)
-      end
-    end
-
-    def resolve_job_class(job_class_name:, key:)
-      job_class = job_class_name.safe_constantize
-      raise SchedulerConfigError, "Unknown job_class '#{job_class_name}' for key '#{key}'" unless job_class
-      raise SchedulerConfigError, "job_class '#{job_class_name}' must inherit from ActiveJob::Base for key '#{key}'" unless job_class <= ActiveJob::Base
-
-      job_class
-    end
-  end
-end