kaal 0.2.1 → 0.4.0

data/lib/kaal/runtime/scheduler_boot_loader.rb

@@ -0,0 +1,52 @@
+# 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
+  # Loads scheduler.yml at framework boot time while respecting missing-file policy.
+  class SchedulerBootLoader
+    def initialize(configuration_provider:, logger:, runtime_context:, load_scheduler_file:)
+      @configuration_provider = configuration_provider
+      @logger = logger
+      @runtime_context = runtime_context
+      @load_scheduler_file = load_scheduler_file
+    end
+
+    def load_on_boot
+      load_on_boot!
+    end
+
+    def load_on_boot!
+      configuration = fetch_configuration
+      return unless configuration
+
+      return load_scheduler_file if configuration.scheduler_missing_file_policy == :error
+
+      scheduler_path = configuration.scheduler_config_path.to_s.strip
+      return if scheduler_path.empty?
+
+      absolute_path = @runtime_context.resolve_path(scheduler_path)
+      unless File.exist?(absolute_path)
+        @logger&.warn("Scheduler file not found at #{absolute_path}")
+        return
+      end
+
+      load_scheduler_file
+    end
+
+    private
+
+    def load_scheduler_file
+      @load_scheduler_file.call
+    end
+
+    def fetch_configuration
+      @configuration_provider.call
+    rescue NameError => e
+      @logger&.debug("Skipping scheduler file boot load due to configuration error: #{e.message}")
+      nil
+    end
+  end
+end

data/lib/kaal/runtime/signal_handler_chain.rb

@@ -0,0 +1,42 @@
+# 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
+  # Invokes a previously registered signal handler when it is safe to do so.
+  class SignalHandlerChain
+    RESERVED_COMMAND_HANDLERS = %w[DEFAULT IGNORE].freeze
+
+    def initialize(signal:, previous_handler:, logger:)
+      @signal = signal
+      @previous_handler = previous_handler
+      @logger = logger
+    end
+
+    def call(...)
+      return unless @previous_handler
+
+      case @previous_handler
+      when Proc, Method
+        invoke_callable(...)
+      when String
+        return if RESERVED_COMMAND_HANDLERS.include?(@previous_handler)
+
+        @logger&.debug("Previous #{@signal} handler was a command: #{@previous_handler}")
+      end
+    end
+
+    private
+
+    def invoke_callable(*args)
+      arity = @previous_handler.arity
+      return @previous_handler.call if arity.zero?
+
+      argument_length = args.length
+      argument_count = arity.negative? ? argument_length : [arity, argument_length].min
+      @previous_handler.call(*args.first(argument_count))
+    end
+  end
+end

data/lib/kaal/runtime/signal_handler_installer.rb

@@ -0,0 +1,39 @@
+# 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
+  # Installs signal handlers while preserving the previous handlers for chaining.
+  class SignalHandlerInstaller
+    SIGNALS = %w[TERM INT].freeze
+    IGNORE_HANDLER = 'IGNORE'
+
+    def initialize(signal_module: Signal)
+      @signal_module = signal_module
+    end
+
+    def install(signals: SIGNALS)
+      signals.each_with_object({}) do |signal, previous_handlers|
+        previous_handler = capture_previous_handler(signal)
+        @signal_module.trap(signal) { yield(signal, previous_handler) }
+        previous_handlers[signal] = previous_handler
+      end
+    end
+
+    private
+
+    def capture_previous_handler(signal)
+      previous_handler = @signal_module.trap(signal, IGNORE_HANDLER)
+      restore_previous_handler(signal, previous_handler)
+      previous_handler
+    end
+
+    def restore_previous_handler(signal, previous_handler)
+      return unless previous_handler && previous_handler != IGNORE_HANDLER
+
+      @signal_module.trap(signal, previous_handler)
+    end
+  end
+end

data/lib/kaal/runtime.rb

@@ -0,0 +1,20 @@
+# 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 'kaal/runtime/runtime_context'
+require 'kaal/runtime/scheduler_boot_loader'
+require 'kaal/runtime/signal_handler_chain'
+require 'kaal/runtime/signal_handler_installer'
+
+module Kaal
+  # Runtime wiring and lifecycle helpers.
+  module Runtime
+    RuntimeContext = ::Kaal::RuntimeContext
+    SchedulerBootLoader = ::Kaal::SchedulerBootLoader
+    SignalHandlerChain = ::Kaal::SignalHandlerChain
+    SignalHandlerInstaller = ::Kaal::SignalHandlerInstaller
+  end
+end

data/lib/kaal/scheduler_file/hash_transform.rb

@@ -0,0 +1,22 @@
+# 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 'kaal/support/hash_tools'
+
+module Kaal
+  # Shared deep hash key transformation helpers for scheduler payloads.
+  module SchedulerHashTransform
+    private
+
+    def stringify_keys(object)
+      Kaal::Support::HashTools.stringify_keys(object)
+    end
+
+    def symbolize_keys_deep(object)
+      Kaal::Support::HashTools.symbolize_keys(object)
+    end
+  end
+end

data/lib/kaal/scheduler_file/helper_bundle.rb

@@ -0,0 +1,28 @@
+# 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
+  class SchedulerFileLoader
+    # Exposes hash/placeholder helpers to extracted scheduler-file collaborators.
+    class HelperBundle
+      def initialize(loader:)
+        @loader = loader
+      end
+
+      def stringify_keys(payload)
+        @loader.send(:stringify_keys, payload)
+      end
+
+      def resolve_placeholders(value, context)
+        @loader.send(:resolve_placeholders, value, context)
+      end
+
+      def validate_placeholders(value, key:)
+        @loader.send(:validate_placeholders, value, key:)
+      end
+    end
+  end
+end

data/lib/kaal/scheduler_file/job_applier.rb

@@ -0,0 +1,242 @@
+# 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 'kaal/support/hash_tools'
+
+module Kaal
+  class SchedulerFileLoader
+    # Applies normalized scheduler jobs and rolls them back on failure.
+    class JobApplier
+      include Kaal::Support::HashTools
+
+      def initialize(configuration:, definition_registry:, registry:, logger:, helper_bundle:)
+        @configuration = configuration
+        @definition_registry = definition_registry
+        @registry = registry
+        @logger = logger
+        @helper_bundle = helper_bundle
+      end
+
+      def apply(job)
+        key = job.fetch(:key)
+        cron = job.fetch(:cron)
+        job_class_name = job.fetch(:job_class_name)
+        queue = job.fetch(:queue)
+        existing_definition = @definition_registry.find_definition(key)
+        existing_registry_entry = @registry.find(key)
+        return nil if conflict?(key:, existing_definition:)
+
+        job_class = resolved_job_class(job_class_name:, key:, queue:)
+        callback = callback_for(
+          key: key,
+          job_class_name: job_class_name,
+          queue: queue,
+          args_template: job.fetch(:args),
+          kwargs_template: job.fetch(:kwargs)
+        )
+        persisted_metadata = persisted_metadata(job, job_class)
+
+        @definition_registry.upsert_definition(
+          key: key,
+          cron: cron,
+          enabled: job.fetch(:enabled),
+          source: 'file',
+          metadata: persisted_metadata
+        )
+
+        begin
+          @registry.upsert(key: key, cron: cron, enqueue: callback)
+        rescue StandardError
+          rollback_job(key:, existing_definition:, existing_registry_entry:)
+          raise
+        end
+
+        { key: key, existing_definition: existing_definition, existing_registry_entry: existing_registry_entry }
+      end
+
+      def rollback_jobs(applied_job_contexts)
+        applied_job_contexts.reverse_each do |applied_job_context|
+          rollback_job(**applied_job_context)
+        end
+      end
+
+      def callback_for(key:, job_class_name:, queue:, args_template:, kwargs_template:)
+        job_class = resolved_job_class(job_class_name:, key:, queue:)
+        build_callback(
+          {
+            key: key,
+            queue: queue,
+            args: args_template,
+            kwargs: kwargs_template
+          },
+          job_class
+        )
+      end
+
+      def resolved_job_class(job_class_name:, key:, queue: nil)
+        resolve_job_class(job_class_name:, key:, queue:)
+      end
+
+      def 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 rollback_job(key:, existing_definition:, existing_registry_entry:)
+        if existing_definition
+          @definition_registry.upsert_definition(
+            **Definition::AttributeHelpers.definition_attributes(existing_definition), enabled: existing_definition[:enabled]
+          )
+        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
+
+      private
+
+      def persisted_metadata(job, job_class)
+        metadata, job_class_name, queue, args, kwargs =
+          job.values_at(:metadata, :job_class_name, :queue, :args, :kwargs)
+        normalized_metadata = @helper_bundle.stringify_keys(deep_dup(metadata || {}))
+        Kaal::Support::HashTools.deep_merge(
+          normalized_metadata,
+          'execution' => {
+            'target' => active_job_dispatch?(job_class, queue) ? 'active_job' : 'ruby',
+            'job_class' => job_class_name,
+            'queue' => queue,
+            'args' => args,
+            'kwargs' => kwargs
+          }
+        )
+      end
+
+      def build_callback(job, job_class)
+        key = job.fetch(:key)
+        queue = job.fetch(:queue)
+        args_template = job.fetch(:args)
+        kwargs_template = job.fetch(:kwargs)
+
+        lambda do |fire_time:, idempotency_key:|
+          context = {
+            fire_time: fire_time,
+            idempotency_key: idempotency_key,
+            key: key
+          }
+          resolved_args = @helper_bundle.resolve_placeholders(deep_dup(args_template), context)
+          raw_kwargs = @helper_bundle.resolve_placeholders(deep_dup(kwargs_template), context) || {}
+          raise SchedulerConfigError, "kwargs for scheduler job '#{key}' must be a mapping, got #{raw_kwargs.class}" unless raw_kwargs.is_a?(Hash)
+
+          validate_keyword_keys(raw_kwargs, key)
+
+          resolved_kwargs = raw_kwargs.transform_keys(&:to_sym)
+          dispatch_job(job_class, queue, resolved_args, resolved_kwargs)
+        end
+      end
+
+      def validate_keyword_keys(raw_kwargs, key)
+        keys = raw_kwargs.keys
+        index = 0
+        while index < keys.length
+          kwargs_key = keys[index]
+          if kwargs_key.is_a?(String) || kwargs_key.is_a?(Symbol)
+            index += 1
+            next
+          end
+
+          raise SchedulerConfigError,
+                "Invalid keyword argument key #{kwargs_key.inspect} (#{kwargs_key.class}) for scheduler job '#{key}'"
+        end
+
+        nil
+      end
+
+      def resolve_job_class(job_class_name:, key:, queue: nil)
+        normalized_job_class_name = job_class_name.to_s.strip
+        raise SchedulerConfigError, "Job class cannot be blank for key '#{key}'" if normalized_job_class_name.empty?
+
+        error_message = "Unknown job_class #{normalized_job_class_name.inspect} for key '#{key}'"
+        job_class = begin
+          Kaal::Support::HashTools.constantize(normalized_job_class_name)
+        rescue NameError
+          nil
+        end
+
+        return validate_dispatch_interface(job_class, key, queue) if job_class
+
+        raise_unknown_job_class(error_message)
+      end
+
+      private :build_callback, :resolve_job_class
+
+      def dispatch_job(job_class, queue, args, kwargs)
+        job_class_name = job_class.name
+
+        if queue && !job_class.respond_to?(:set)
+          raise SchedulerConfigError,
+                "job_class '#{job_class_name}' must respond to .set to use queue #{queue.inspect}"
+        end
+
+        if queue
+          job_class.set(queue: queue).perform_later(*args, **kwargs)
+        elsif job_class.respond_to?(:perform_later)
+          job_class.perform_later(*args, **kwargs)
+        elsif job_class.respond_to?(:perform)
+          job_class.perform(*args, **kwargs)
+        else
+          raise SchedulerConfigError,
+                "job_class '#{job_class_name}' must respond to .perform, .perform_later, or .set(...).perform_later"
+        end
+      end
+
+      def raise_unknown_job_class(error_message)
+        raise SchedulerConfigError, error_message
+      end
+
+      def validate_dispatch_interface(job_class, key, queue)
+        queue_present = !queue.nil?
+        supports_set = job_class.respond_to?(:set)
+        supports_perform_later = job_class.respond_to?(:perform_later)
+        supports_perform = job_class.respond_to?(:perform)
+
+        return job_class if queue_present && supports_set
+        return job_class if !queue_present && supports_perform_later
+        return job_class if !queue_present && supports_perform
+
+        raise SchedulerConfigError,
+              "job_class '#{job_class.name}' for key '#{key}' must respond to .perform, .perform_later, or .set(...).perform_later"
+      end
+
+      def active_job_dispatch?(job_class, queue)
+        (queue && job_class.respond_to?(:set)) || job_class.respond_to?(:perform_later)
+      end
+    end
+  end
+end

data/lib/kaal/scheduler_file/job_normalizer.rb

@@ -0,0 +1,90 @@
+# 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 'kaal/support/hash_tools'
+
+module Kaal
+  class SchedulerFileLoader
+    # Normalizes scheduler job payloads into application-ready hashes.
+    class JobNormalizer
+      include Kaal::Support::HashTools
+
+      def initialize(hash_transform:, placeholder_support:, cron_validator:)
+        @hash_transform = hash_transform
+        @placeholder_support = placeholder_support
+        @cron_validator = cron_validator
+      end
+
+      def call(job_payload)
+        payload = @hash_transform.stringify_keys(job_payload)
+        key = payload.fetch('key', '').to_s.strip
+        raise SchedulerConfigError, 'Job key cannot be blank' if key.empty?
+
+        cron = required_string(payload, field: 'cron', error_prefix: "Job cron cannot be blank for key '#{key}'")
+        job_class_name = 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: key,
+          cron: cron,
+          job_class_name: job_class_name,
+          **options
+        }
+      end
+
+      private
+
+      def 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 @cron_validator.call(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:)
+        @placeholder_support.validate_placeholders(args, key:)
+        @placeholder_support.validate_placeholders(kwargs, key:)
+
+        {
+          queue: queue,
+          args: deep_dup(args),
+          kwargs: deep_dup(kwargs),
+          enabled: enabled,
+          metadata: metadata ? deep_dup(metadata) : {}
+        }
+      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
+    end
+  end
+end

data/lib/kaal/scheduler_file/loader.rb

@@ -0,0 +1,152 @@
+# 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 'kaal/runtime/runtime_context'
+require 'kaal/scheduler_file/hash_transform'
+require 'kaal/scheduler_file/placeholder_support'
+require 'kaal/support/hash_tools'
+require_relative 'helper_bundle'
+require_relative 'payload_loader'
+require_relative 'job_normalizer'
+require_relative 'job_applier'
+
+module Kaal
+  # Loads scheduler definitions from config/scheduler.yml and registers them.
+  class SchedulerFileLoader
+    include SchedulerHashTransform
+    include SchedulerPlaceholderSupport
+    include Kaal::Support::HashTools
+
+    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:,
+      runtime_context: RuntimeContext.default
+    )
+      @configuration = configuration
+      @definition_registry = definition_registry
+      @registry = registry
+      @logger = logger
+      @runtime_context = runtime_context
+      @placeholder_resolvers = ALLOWED_PLACEHOLDERS
+    end
+
+    def load
+      applied_job_contexts = []
+      path, payload = payload_loader.load
+      return handle_missing_file(path) unless payload
+
+      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 handle_missing_file(path)
+      payload_loader.handle_missing_file(path)
+    end
+
+    def extract_jobs(payload)
+      payload_loader.extract_jobs(payload)
+    end
+
+    def validate_unique_keys(jobs)
+      payload_loader.validate_unique_keys(jobs)
+    end
+
+    def normalize_job(job_payload)
+      job_normalizer.call(job_payload)
+    end
+
+    def extract_job_options(payload, key:)
+      job_normalizer.send(:extract_job_options, payload, key:)
+    end
+
+    def apply_job(job)
+      job_applier.apply(job)
+    end
+
+    def rollback_applied_jobs(applied_job_contexts = [])
+      job_applier.rollback_jobs(applied_job_contexts)
+    end
+
+    def rollback_applied_job(key:, existing_definition:, existing_registry_entry:)
+      job_applier.rollback_job(key:, existing_definition:, existing_registry_entry:)
+    end
+
+    def skip_due_to_conflict?(key:, existing_definition:)
+      job_applier.conflict?(key:, existing_definition:)
+    end
+
+    def build_callback(key:, job_class_name:, queue:, args_template:, kwargs_template:)
+      job_applier.callback_for(
+        key: key,
+        job_class_name: job_class_name,
+        queue: queue,
+        args_template: args_template,
+        kwargs_template: kwargs_template
+      )
+    end
+
+    def resolve_job_class(job_class_name:, key:, queue: nil)
+      job_applier.resolved_job_class(job_class_name:, key:, queue:)
+    end
+
+    def payload_loader
+      @payload_loader ||= PayloadLoader.new(
+        configuration: @configuration,
+        runtime_context: @runtime_context,
+        logger: @logger,
+        hash_transform: helper_bundle
+      )
+    end
+
+    def job_normalizer
+      @job_normalizer ||= JobNormalizer.new(
+        hash_transform: helper_bundle,
+        placeholder_support: helper_bundle,
+        cron_validator: ->(cron) { Kaal.valid?(cron) }
+      )
+    end
+
+    def job_applier
+      @job_applier ||= JobApplier.new(
+        configuration: @configuration,
+        definition_registry: @definition_registry,
+        registry: @registry,
+        logger: @logger,
+        helper_bundle: helper_bundle
+      )
+    end
+
+    def helper_bundle
+      @helper_bundle ||= HelperBundle.new(loader: self)
+    end
+  end
+end