kaal 0.2.1 → 0.4.0

data/lib/kaal/scheduler_file/payload_loader.rb

@@ -0,0 +1,95 @@
+# 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 'yaml'
+
+module Kaal
+  class SchedulerFileLoader
+    # Loads and validates scheduler YAML payloads from disk.
+    class PayloadLoader
+      def initialize(configuration:, runtime_context:, logger:, hash_transform:)
+        @configuration = configuration
+        @runtime_context = runtime_context
+        @logger = logger
+        @hash_transform = hash_transform
+      end
+
+      def load
+        path = scheduler_file_path
+        return [path, nil] unless File.exist?(path)
+
+        [path, parse_yaml(path)]
+      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 extract_jobs(payload)
+        environment_name = @runtime_context.environment_name
+        defaults = fetch_hash(payload, 'defaults')
+        env_payload = fetch_hash(payload, environment_name)
+        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 '#{environment_name}.jobs' to be an array" unless env_jobs.is_a?(Array)
+
+        default_jobs + env_jobs
+      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)
+
+          @hash_transform.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
+
+      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?
+
+        @runtime_context.resolve_path(configured_path)
+      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)
+
+        @hash_transform.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 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
+    end
+  end
+end

data/lib/kaal/{scheduler_placeholder_support.rb → scheduler_file/placeholder_support.rb}

@@ -4,7 +4,6 @@
 #
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
-
 module Kaal
   # Placeholder parsing/resolution for scheduler args and kwargs.
   module SchedulerPlaceholderSupport

data/lib/kaal/scheduler_file.rb

@@ -0,0 +1,18 @@
+# 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/scheduler_file/loader'
+require 'kaal/scheduler_file/hash_transform'
+require 'kaal/scheduler_file/placeholder_support'
+
+module Kaal
+  # Scheduler file loading and payload helpers.
+  module SchedulerFile
+    Loader = ::Kaal::SchedulerFileLoader
+    HashTransform = ::Kaal::SchedulerHashTransform
+    PlaceholderSupport = ::Kaal::SchedulerPlaceholderSupport
+  end
+end

data/lib/kaal/sequel_support.rb

@@ -0,0 +1,82 @@
+# 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 'fileutils'
+
+module Kaal
+  # Sequel migration/install support for SQL-backed Kaal backends.
+  module Sequel
+    module_function
+
+    def install_postgres_migration(target_dir:, migration_name: 'create_kaal_postgres_backend')
+      install_migrations(target_dir:, backend: 'postgres', migration_name:)
+    end
+
+    def install_mysql_migration(target_dir:, migration_name: 'create_kaal_mysql_backend')
+      install_migrations(target_dir:, backend: 'mysql', migration_name:)
+    end
+
+    def install_sqlite_migration(target_dir:, migration_name: 'create_kaal_sqlite_backend')
+      install_migrations(target_dir:, backend: 'sqlite', migration_name:)
+    end
+
+    def install_migrations(target_dir:, backend:, migration_name: nil)
+      require_sequel!
+
+      normalized_name = normalize_migration_name(migration_name, fallback: default_migration_name_for(backend))
+      base_path = File.expand_path(target_dir)
+      FileUtils.mkdir_p(base_path)
+
+      Kaal::Persistence::MigrationTemplates.for_backend(backend).map.with_index do |(_name, contents), index|
+        suffix = migration_suffixes_for(backend).fetch(index)
+        path = File.expand_path("#{timestamp(index)}_#{normalized_name}_#{suffix}.rb", base_path)
+        File.write(path, contents)
+        path
+      end
+    end
+
+    def require_sequel!
+      require 'sequel'
+    rescue LoadError => e
+      raise LoadError,
+            "#{e.message}. Add `gem 'sequel'` to your Gemfile to use Sequel-backed Kaal SQL support.",
+            cause: e
+    end
+
+    def normalize_migration_name(name, fallback:)
+      normalized = name.to_s.each_char.with_object(+'') do |char, buffer|
+        if letter?(char) || digit?(char)
+          buffer << char.downcase
+        elsif !buffer.empty? && !buffer.end_with?('_')
+          buffer << '_'
+        end
+      end.delete_suffix('_')
+      normalized.empty? ? fallback : normalized
+    end
+
+    def default_migration_name_for(backend)
+      "create_kaal_#{backend}_backend"
+    end
+
+    def migration_suffixes_for(backend)
+      return %w[dispatches locks definitions] if backend.to_s == 'sqlite'
+
+      %w[dispatches definitions]
+    end
+
+    def timestamp(offset = 0)
+      (Time.now.utc + offset).strftime('%Y%m%d%H%M%S')
+    end
+
+    def letter?(char)
+      char.between?('a', 'z') || char.between?('A', 'Z')
+    end
+
+    def digit?(char)
+      char.between?('0', '9')
+    end
+  end
+end

data/lib/kaal/support/hash_tools.rb

@@ -0,0 +1,93 @@
+# 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 Support
+    # Small deep-copy and key-normalization helpers used across config and scheduler loading.
+    module HashTools
+      module_function
+
+      def deep_dup(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, child), memo|
+            duplicated_pair = [deep_dup(key), deep_dup(child)]
+            memo[duplicated_pair[0]] = duplicated_pair[1]
+          end
+        when Array
+          value.map { |child| duplicate_child(child) }
+        else
+          duplicable?(value) ? value.dup : value
+        end
+      end
+
+      def stringify_keys(value)
+        transform_keys(value, &:to_s)
+      end
+
+      def symbolize_keys(value)
+        transform_keys(value) { |key| key.to_s.to_sym }
+      end
+
+      def deep_merge(left, right)
+        left.merge(right) do |_key, left_value, right_value|
+          if left_value.is_a?(Hash) && right_value.is_a?(Hash)
+            deep_merge(left_value, right_value)
+          else
+            deep_dup(right_value)
+          end
+        end
+      end
+
+      def constantize(name)
+        name.to_s.split('::').reject(&:empty?).reduce(Object) { |scope, part| scope.const_get(part) }
+      end
+
+      def duplicable?(value)
+        !value.is_a?(NilClass) &&
+          !value.is_a?(FalseClass) &&
+          !value.is_a?(TrueClass) &&
+          !value.is_a?(Symbol) &&
+          !value.is_a?(Numeric) &&
+          !value.is_a?(Method) &&
+          !value.is_a?(Proc)
+      end
+
+      def transform_keys(value, &)
+        case value
+        when Hash
+          transform_hash_keys(value, &)
+        when Array
+          transform_array_keys(value, &)
+        else
+          value
+        end
+      end
+
+      def duplicate_child(child)
+        deep_dup(child)
+      end
+
+      def transform_child_keys(child, &)
+        transform_keys(child, &)
+      end
+
+      def transform_hash_keys(value, &)
+        value.each_with_object({}) do |(key, child), memo|
+          transformed_pair = [yield(key), transform_child_keys(child, &)]
+          memo[transformed_pair[0]] = transformed_pair[1]
+        end
+      end
+
+      def transform_array_keys(value, &)
+        value.map { |child| transform_child_keys(child, &) }
+      end
+
+      private_class_method :duplicate_child, :transform_child_keys, :transform_hash_keys, :transform_array_keys
+      private_class_method :transform_keys
+    end
+  end
+end

data/lib/kaal/{cron_humanizer.rb → utils/cron_humanizer.rb}

@@ -4,14 +4,15 @@
 #
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
-
 require 'fugit'
 require 'i18n'
+require 'yaml'
 
 module Kaal
   ##
   # Human-friendly cron phrase generation with i18n support.
   module CronHumanizer
+    I18N_LOAD_MUTEX = Mutex.new
     MACRO_PHRASES = {
       '@yearly' => 'phrases.yearly',
       '@monthly' => 'phrases.monthly',
@@ -23,6 +24,8 @@ module Kaal
     module_function
 
     def to_human(expression, locale: nil)
+      ensure_i18n_loaded!
+
       normalized = CronUtils.safe_normalize_expression(expression)
       raise ArgumentError, CronUtils.invalid_expression_error_message('') unless normalized
       raise ArgumentError, CronUtils.invalid_expression_error_message(normalized) if normalized.empty?
@@ -178,5 +181,20 @@ module Kaal
       I18n.t("kaal.#{key}", **)
     end
     private_class_method :translate_phrase
+
+    def ensure_i18n_loaded!
+      locale_file = File.expand_path('../../../config/locales/en.yml', __dir__)
+      return if I18n.load_path.include?(locale_file)
+
+      I18N_LOAD_MUTEX.synchronize do
+        return if I18n.load_path.include?(locale_file)
+
+        I18n.load_path << locale_file
+        locales = YAML.safe_load_file(locale_file, aliases: true) || {}
+        I18n.available_locales = Array(I18n.available_locales) | locales.keys.map(&:to_sym)
+        I18n.backend.load_translations
+      end
+    end
+    private_class_method :ensure_i18n_loaded!
   end
 end

data/lib/kaal/{cron_utils.rb → utils/cron_utils.rb}

@@ -4,7 +4,6 @@
 #
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
-
 require 'fugit'
 
 module Kaal

data/lib/kaal/{idempotency_key_generator.rb → utils/idempotency_key_generator.rb}

@@ -4,7 +4,6 @@
 #
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
-
 module Kaal
   ##
   # Utility class for generating idempotency keys.
@@ -13,7 +12,7 @@ module Kaal
   # Format: {namespace}-{cron_key}-{fire_time_unix}
   #
   # @example Generate a key
-  #   key = Kaal::IdempotencyKeyGenerator.call('reports:daily', Time.current, configuration: config)
+  #   key = Kaal::IdempotencyKeyGenerator.call('reports:daily', Time.now.utc, configuration: config)
   #   # => "kaal-reports:daily-1708283400"
   class IdempotencyKeyGenerator
     ##
@@ -24,7 +23,8 @@ module Kaal
     # @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 = configuration.namespace.to_s.strip
+      namespace = 'kaal' if namespace.empty?
       "#{namespace}-#{cron_key}-#{fire_time.to_i}"
     end
   end

data/lib/kaal/utils.rb

@@ -0,0 +1,18 @@
+# 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/utils/cron_utils'
+require 'kaal/utils/cron_humanizer'
+require 'kaal/utils/idempotency_key_generator'
+
+module Kaal
+  # Utility functions and pure helpers.
+  module Utils
+    CronUtils = ::Kaal::CronUtils
+    CronHumanizer = ::Kaal::CronHumanizer
+    IdempotencyKeyGenerator = ::Kaal::IdempotencyKeyGenerator
+  end
+end

data/lib/kaal/version.rb

@@ -4,7 +4,6 @@
 #
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
-
 module Kaal
-  VERSION = '0.2.1'
+  VERSION = '0.4.0'
 end