kaal 0.2.0

data/lib/kaal/cron_utils.rb

@@ -0,0 +1,233 @@
+# 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 'fugit'
+
+module Kaal
+  ##
+  # Utility helpers for cron expression validation, simplification, and linting.
+  module CronUtils
+    MACRO_MAP = {
+      '@yearly' => '0 0 1 1 *',
+      '@annually' => '0 0 1 1 *',
+      '@monthly' => '0 0 1 * *',
+      '@weekly' => '0 0 * * 0',
+      '@daily' => '0 0 * * *',
+      '@midnight' => '0 0 * * *',
+      '@hourly' => '0 * * * *'
+    }.freeze
+
+    CANONICAL_MACROS = {
+      '0 0 1 1 *' => '@yearly',
+      '0 0 1 * *' => '@monthly',
+      '0 0 * * 0' => '@weekly',
+      '0 0 * * 7' => '@weekly',
+      '0 0 * * *' => '@daily',
+      '0 * * * *' => '@hourly'
+    }.freeze
+
+    FIELD_SPECS = [
+      { name: 'minute', min: 0, max: 59, names: nil },
+      { name: 'hour', min: 0, max: 23, names: nil },
+      { name: 'day-of-month', min: 1, max: 31, names: nil },
+      {
+        name: 'month',
+        min: 1,
+        max: 12,
+        names: {
+          'jan' => 1, 'feb' => 2, 'mar' => 3, 'apr' => 4, 'may' => 5, 'jun' => 6,
+          'jul' => 7, 'aug' => 8, 'sep' => 9, 'oct' => 10, 'nov' => 11, 'dec' => 12
+        }
+      },
+      {
+        name: 'day-of-week',
+        min: 0,
+        max: 7,
+        names: {
+          'sun' => 0, 'mon' => 1, 'tue' => 2, 'wed' => 3, 'thu' => 4, 'fri' => 5, 'sat' => 6
+        }
+      }
+    ].freeze
+
+    module_function
+
+    def normalize_expression(expression)
+      expression.to_s.strip.gsub(/\s+/, ' ')
+    end
+
+    def safe_normalize_expression(expression)
+      normalize_expression(expression)
+    rescue StandardError
+      nil
+    end
+
+    def unsupported_macro_error_message(expression)
+      supported = MACRO_MAP.keys.sort.join(', ')
+      "Unsupported cron macro '#{expression}'. Supported macros: #{supported}."
+    end
+
+    def invalid_expression_error_message(expression)
+      shown = expression.empty? ? '<empty>' : expression
+      "Invalid cron expression '#{shown}'. Examples: '*/5 * * * *', '@daily'."
+    end
+
+    def valid?(expression)
+      normalized = normalize_expression(expression)
+      return false if normalized.empty?
+
+      return MACRO_MAP.key?(normalized.downcase) if macro?(normalized)
+
+      return false unless five_fields?(normalized)
+
+      !!Fugit.parse_cron(normalized)
+    rescue StandardError
+      false
+    end
+
+    def simplify(expression)
+      normalized = safe_normalize_expression(expression)
+      raise ArgumentError, invalid_expression_error_message('') unless normalized
+
+      downcased = normalized.downcase
+
+      if macro?(normalized)
+        return canonical_macro_for(downcased) if MACRO_MAP.key?(downcased)
+
+        raise ArgumentError, unsupported_macro_error_message(normalized)
+      end
+
+      raise ArgumentError, invalid_expression_error_message(normalized) unless valid?(normalized)
+
+      CANONICAL_MACROS.fetch(normalized, normalized)
+    end
+
+    def lint(expression)
+      normalized = safe_normalize_expression(expression)
+      return [invalid_expression_error_message('')] unless normalized
+
+      invalid_message = invalid_expression_error_message(normalized)
+      return [invalid_message] if normalized.empty?
+
+      if macro?(normalized)
+        downcased = normalized.downcase
+        return [] if MACRO_MAP.key?(downcased)
+
+        return [unsupported_macro_error_message(normalized)]
+      end
+
+      return [field_count_message(normalized)] unless five_fields?(normalized)
+
+      warnings = normalized.split.each_with_index.flat_map do |field, index|
+        lint_field(field, FIELD_SPECS[index])
+      end
+
+      warnings << invalid_message unless valid?(normalized)
+      warnings.uniq
+    end
+
+    def lint_field(field, spec)
+      field.split(',').flat_map { |segment| lint_segment(segment, spec) }
+    end
+    private_class_method :lint_field
+
+    def lint_segment(segment, spec)
+      return [] if segment == '*'
+
+      if (star_step_matches = segment.match(%r{\A\*/(\d+)\z}))
+        step = star_step_matches[1].to_i
+        return lint_step_only(step, spec)
+      end
+
+      if (range_matches = segment.match(%r{\A([^/-]+)-([^/]+)(?:/(\d+))?\z}))
+        range_start = range_matches[1]
+        range_end = range_matches[2]
+        step_token = range_matches[3]
+        start = parse_value(range_start, spec)
+        ending = parse_value(range_end, spec)
+        step = step_token&.to_i
+        return lint_range_segment(segment, start, ending, step, spec)
+      end
+
+      if (base_step_matches = segment.match(%r{\A([^/]+)/(\d+)\z}))
+        base_token = base_step_matches[1]
+        step_token = base_step_matches[2]
+        base = parse_value(base_token, spec)
+        step = step_token.to_i
+        return lint_base_step_segment(segment, base, step, spec)
+      end
+
+      value = parse_value(segment, spec)
+      return ["#{spec[:name]} value '#{segment}' is out of range (#{spec[:min]}-#{spec[:max]})."] unless value
+
+      []
+    end
+    private_class_method :lint_segment
+
+    def lint_step_only(step, spec)
+      field_size = spec[:max] - spec[:min] + 1
+      return [] if step.between?(1, field_size)
+
+      ["#{spec[:name]} step '#{step}' is out of range. Allowed step: 1-#{field_size}."]
+    end
+    private_class_method :lint_step_only
+
+    def lint_range_segment(segment, start_value, end_value, step, spec)
+      field_name = spec[:name]
+      return ["#{field_name} range '#{segment}' contains an out-of-range value."] unless start_value && end_value
+      return ["#{field_name} range '#{segment}' has start greater than end."] if start_value > end_value
+      return [] unless step
+
+      span = end_value - start_value + 1
+      return [] if step.between?(1, span)
+
+      ["#{field_name} step '#{step}' is out of range for range '#{segment}'. Allowed step: 1-#{span}."]
+    end
+    private_class_method :lint_range_segment
+
+    def lint_base_step_segment(segment, base, step, spec)
+      field_name = spec[:name]
+      return ["#{field_name} value '#{segment}' contains an out-of-range value."] unless base
+      return [] if step.positive?
+
+      ["#{field_name} step '#{step}' is out of range. Allowed step: 1 or greater."]
+    end
+    private_class_method :lint_base_step_segment
+
+    def parse_value(token, spec)
+      names = spec[:names]
+      token_key = token.downcase
+      return names[token_key] if names&.key?(token_key)
+      return nil unless token.match?(/\A\d+\z/)
+
+      value = token.to_i
+      return nil unless value.between?(spec[:min], spec[:max])
+
+      value
+    end
+    private_class_method :parse_value
+
+    def macro?(expression)
+      expression.start_with?('@')
+    end
+    private_class_method :macro?
+
+    def five_fields?(expression)
+      expression.split.length == 5
+    end
+    private_class_method :five_fields?
+
+    def canonical_macro_for(macro)
+      CANONICAL_MACROS.fetch(MACRO_MAP[macro], macro)
+    end
+    private_class_method :canonical_macro_for
+
+    def field_count_message(expression)
+      "Invalid cron expression '#{expression}'. Expected 5 fields: minute hour day-of-month month day-of-week."
+    end
+    private_class_method :field_count_message
+  end
+end

data/lib/kaal/definition/database_engine.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative 'registry'
+
+module Kaal
+  module Definition
+    # ActiveRecord-backed definition registry persisted in kaal_definitions.
+    class DatabaseEngine < Registry
+      def initialize
+        super
+        @definition_model = ::Kaal::CronDefinition
+      end
+
+      def upsert_definition(key:, cron:, enabled: true, source: 'code', metadata: {})
+        @definition_model.upsert_definition!(
+          key: key,
+          cron: cron,
+          enabled: enabled,
+          source: source,
+          metadata: metadata
+        ).to_definition_hash
+      end
+
+      def remove_definition(key)
+        record = @definition_model.find_by(key: key)
+        return nil unless record
+
+        record.destroy_and_return_definition_hash
+      end
+
+      def find_definition(key)
+        record = @definition_model.find_by(key: key)
+        record&.to_definition_hash
+      end
+
+      def all_definitions
+        @definition_model.order(:key).map(&:to_definition_hash)
+      end
+
+      def enabled_definitions
+        @definition_model.where(enabled: true).order(:key).map(&:to_definition_hash)
+      end
+    end
+  end
+end

data/lib/kaal/definition/memory_engine.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/object/deep_dup'
+require_relative 'registry'
+
+module Kaal
+  module Definition
+    # In-memory definition registry used when no persistent backend is configured.
+    class MemoryEngine < Registry
+      def initialize
+        super
+        @definitions = {}
+        @mutex = Mutex.new
+      end
+
+      def upsert_definition(key:, cron:, enabled: true, source: 'code', metadata: {})
+        @mutex.synchronize do
+          now = Time.current
+          existing = @definitions[key]
+          stored_metadata = (metadata || {}).deep_dup
+          disabled_at = if enabled
+                          nil
+                        elsif existing && existing[:enabled] == false
+                          existing[:disabled_at]
+                        else
+                          now
+                        end
+          definition = {
+            key: key,
+            cron: cron,
+            enabled: enabled,
+            source: source,
+            metadata: stored_metadata,
+            created_at: existing ? existing[:created_at] : now,
+            updated_at: now,
+            disabled_at:
+          }
+          @definitions[key] = definition
+
+          definition.deep_dup
+        end
+      end
+
+      def remove_definition(key)
+        @mutex.synchronize { @definitions.delete(key)&.deep_dup }
+      end
+
+      def find_definition(key)
+        @mutex.synchronize { @definitions[key]&.deep_dup }
+      end
+
+      def all_definitions
+        @mutex.synchronize { @definitions.values.map(&:deep_dup) }
+      end
+
+      def clear
+        @mutex.synchronize { @definitions.clear }
+      end
+    end
+  end
+end

data/lib/kaal/definition/redis_engine.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+require_relative 'registry'
+
+module Kaal
+  module Definition
+    # Redis-backed definition registry shared across processes.
+    class RedisEngine < Registry
+      def initialize(redis, namespace: 'kaal')
+        super()
+        @redis = redis
+        @namespace = namespace
+      end
+
+      def upsert_definition(key:, cron:, enabled: true, source: 'code', metadata: {})
+        now = Time.current
+        existing = find_definition(key)
+        payload = {
+          key: key,
+          cron: cron,
+          enabled: enabled,
+          source: source,
+          metadata: metadata,
+          created_at: existing ? existing[:created_at] : now,
+          updated_at: now,
+          disabled_at: enabled ? nil : now
+        }
+
+        @redis.hset(storage_key, key, JSON.generate(self.class.serialize_payload(payload)))
+        payload
+      end
+
+      def remove_definition(key)
+        raw = @redis.hget(storage_key, key)
+        @redis.hdel(storage_key, key)
+        deserialize(raw)
+      end
+
+      def find_definition(key)
+        raw = @redis.hget(storage_key, key)
+        deserialize(raw)
+      end
+
+      def all_definitions
+        @redis.hvals(storage_key).filter_map { |raw| self.class.deserialize_payload(raw) }
+      end
+
+      private
+
+      def storage_key
+        "#{@namespace}:definitions"
+      end
+
+      def deserialize(raw)
+        self.class.deserialize_payload(raw)
+      end
+
+      class << self
+        def serialize_payload(payload)
+          payload.transform_values do |value|
+            value.is_a?(Time) ? value.iso8601 : value
+          end
+        end
+
+        def deserialize_payload(raw)
+          return nil unless raw
+
+          parsed = JSON.parse(raw)
+          {
+            key: parsed['key'],
+            cron: parsed['cron'],
+            enabled: parsed['enabled'] == true,
+            source: parsed['source'],
+            metadata: parsed['metadata'] || {},
+            created_at: parse_time(parsed['created_at']),
+            updated_at: parse_time(parsed['updated_at']),
+            disabled_at: parse_time(parsed['disabled_at'])
+          }
+        rescue JSON::ParserError
+          nil
+        end
+
+        def parse_time(value)
+          Time.iso8601(value.to_s)
+        rescue ArgumentError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/kaal/definition/registry.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Kaal
+  module Definition
+    # Base abstraction for cron definition storage.
+    class Registry
+      def upsert_definition(**)
+        raise NotImplementedError, "#{self.class.name} must implement #upsert_definition"
+      end
+
+      def remove_definition(_key)
+        raise NotImplementedError, "#{self.class.name} must implement #remove_definition"
+      end
+
+      def find_definition(_key)
+        raise NotImplementedError, "#{self.class.name} must implement #find_definition"
+      end
+
+      def all_definitions
+        raise NotImplementedError, "#{self.class.name} must implement #all_definitions"
+      end
+
+      def enabled_definitions
+        all_definitions.select { |definition| definition[:enabled] }
+      end
+
+      def enable_definition(key)
+        update_definition_enabled_state(key, enabled: true)
+      end
+
+      def disable_definition(key)
+        update_definition_enabled_state(key, enabled: false)
+      end
+
+      private
+
+      def update_definition_enabled_state(key, enabled:)
+        definition = find_definition(key)
+        return nil unless definition
+
+        attributes = definition.slice(:key, :cron, :source, :metadata).merge(enabled: enabled)
+        upsert_definition(**attributes)
+      end
+    end
+  end
+end

data/lib/kaal/dispatch/database_engine.rb

@@ -0,0 +1,94 @@
+# 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 'registry'
+
+module Kaal
+  module Dispatch
+    ##
+    # Database-backed dispatch registry using ActiveRecord.
+    #
+    # Stores dispatch records in the database using the CronDispatch model.
+    # Provides persistent, queryable audit logs across all nodes.
+    #
+    # @example Usage
+    #   registry = Kaal::Dispatch::DatabaseEngine.new
+    #   registry.log_dispatch('daily_report', Time.current, 'node-1')
+    #   registry.dispatched?('daily_report', Time.current) # => true
+    class DatabaseEngine < Registry
+      ##
+      # Log a dispatch attempt in the database.
+      #
+      # @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 [Kaal::CronDispatch] the created dispatch record
+      # @raise [ActiveRecord::RecordInvalid] if the record is invalid
+      def log_dispatch(key, fire_time, node_id, status = 'dispatched')
+        ::Kaal::CronDispatch.create!(
+          key: key,
+          fire_time: fire_time,
+          dispatched_at: Time.current,
+          node_id: node_id,
+          status: status
+        )
+      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 [Kaal::CronDispatch, nil] dispatch record or nil if not found
+      def find_dispatch(key, fire_time)
+        ::Kaal::CronDispatch.find_by(key: key, fire_time: fire_time)
+      end
+
+      ##
+      # Find all dispatch records for a specific job key.
+      #
+      # @param key [String] the cron job key
+      # @return [ActiveRecord::Relation] collection of dispatch records
+      def find_by_key(key)
+        ::Kaal::CronDispatch.where(key: key).order(fire_time: :desc)
+      end
+
+      ##
+      # Find all dispatch records by node ID.
+      #
+      # @param node_id [String] the node identifier
+      # @return [ActiveRecord::Relation] collection of dispatch records
+      def find_by_node(node_id)
+        ::Kaal::CronDispatch.where(node_id: node_id).order(fire_time: :desc)
+      end
+
+      ##
+      # Find all dispatch records with a specific status.
+      #
+      # @param status [String] the dispatch status
+      # @return [ActiveRecord::Relation] collection of dispatch records
+      def find_by_status(status)
+        ::Kaal::CronDispatch.where(status: status).order(fire_time: :desc)
+      end
+
+      ##
+      # Delete old dispatch records older than the specified time.
+      #
+      # This cleanup prevents unbounded database growth by removing records
+      # that are older than the recovery window, making them irrelevant for
+      # future recovery operations.
+      #
+      # @param recovery_window [Integer] seconds to keep records for (e.g., 86400 for 24h)
+      # @return [Integer] number of records deleted
+      def cleanup(recovery_window: 86_400)
+        cutoff_time = Time.current - recovery_window
+        ::Kaal::CronDispatch.where('fire_time < ?', cutoff_time).delete_all
+      end
+    end
+  end
+end

data/lib/kaal/dispatch/memory_engine.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 'registry'
+
+module Kaal
+  module Dispatch
+    ##
+    # In-memory dispatch registry using a Hash for storage.
+    #
+    # Stores dispatch records in memory. Suitable for development, testing,
+    # or single-node deployments where persistence is not required.
+    #
+    # @example Usage
+    #   registry = Kaal::Dispatch::MemoryEngine.new
+    #   registry.log_dispatch('daily_report', Time.current, 'node-1')
+    #   registry.dispatched?('daily_report', Time.current) # => true
+    class MemoryEngine < Registry
+      ##
+      # Initialize a new in-memory registry.
+      def initialize
+        super
+        @dispatches = {}
+        @mutex = Mutex.new
+      end
+
+      ##
+      # Log a dispatch attempt in memory.
+      #
+      # @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')
+        @mutex.synchronize do
+          storage_key = build_key(key, fire_time)
+          @dispatches[storage_key] = {
+            key: key,
+            fire_time: fire_time,
+            dispatched_at: Time.current,
+            node_id: node_id,
+            status: status
+          }
+        end
+      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)
+        @mutex.synchronize do
+          storage_key = build_key(key, fire_time)
+          @dispatches[storage_key]
+        end
+      end
+
+      ##
+      # Clear all stored dispatch records.
+      # Useful for testing.
+      #
+      # @return [void]
+      def clear
+        @mutex.synchronize do
+          @dispatches.clear
+        end
+      end
+
+      ##
+      # Get the number of stored dispatch records.
+      #
+      # @return [Integer] number of dispatch records
+      def size
+        @mutex.synchronize do
+          @dispatches.size
+        end
+      end
+
+      private
+
+      ##
+      # Build a storage key from job key and fire time.
+      #
+      # @param key [String] the cron job key
+      # @param fire_time [Time] the fire time
+      # @return [String] storage key
+      def build_key(key, fire_time)
+        "#{key}:#{fire_time.to_i}"
+      end
+    end
+  end
+end