kaal 0.2.1 → 0.4.0

data/lib/kaal/{coordinator.rb → core/coordinator.rb}

@@ -4,8 +4,10 @@
 #
 # 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_relative 'enabled_entry_enumerator'
+require_relative 'occurrence_finder'
+require 'kaal/config/scheduler_time_zone_resolver'
 
 module Kaal
   ##
@@ -172,13 +174,15 @@ module Kaal
       each_enabled_entry do |entry|
         calculate_and_dispatch_due_times(entry)
       end
+    rescue ConfigurationError => e
+      log_configuration_error('Kaal coordinator tick failed', e)
+      raise
     rescue StandardError => e
-      # Log error but continue the loop
-      @configuration.logger&.error("Kaal coordinator tick failed: #{e.message}")
+      log_runtime_error('Kaal coordinator tick failed', e)
     end
 
     def calculate_and_dispatch_due_times(entry)
-      now = Time.current
+      now = Time.now.utc
       window_start = now - @configuration.window_lookback
       window_end = now + @configuration.window_lookahead
 
@@ -197,7 +201,7 @@ module Kaal
     end
 
     def parse_cron(cron_expression)
-      result = Fugit.parse_cron(cron_expression)
+      result = Fugit.parse_cron("#{cron_expression} #{scheduler_time_zone_resolver.time_zone_identifier}")
       raise ArgumentError, "Invalid cron expression: #{cron_expression}" unless result
 
       result
@@ -207,24 +211,7 @@ module Kaal
     end
 
     def find_occurrences(cron, start_time, end_time)
-      # Use fugit to find all occurrences between start and end times
-      occurrences = []
-      current_time = start_time
-
-      while current_time <= end_time
-        next_occurrence = cron.next_time(current_time)
-        break unless next_occurrence
-
-        break if next_occurrence > end_time
-
-        occurrences << next_occurrence
-        current_time = next_occurrence + 1.second # Move past this occurrence to find the next
-      end
-
-      occurrences
-    rescue StandardError => e
-      @configuration.logger&.error("Failed to calculate occurrences: #{e.message}")
-      []
+      occurrence_finder.call(cron:, start_time:, end_time:)
     end
 
     def dispatch_if_due(entry, fire_time, now)
@@ -233,6 +220,7 @@ module Kaal
 
       logger = @configuration.logger
       cron_key = entry.key
+      return if Kaal.configuration.enable_log_dispatch_registry && already_dispatched?(cron_key, fire_time)
 
       # Generate a unique backend coordination key for this fire time
       lock_key = generate_lock_key(cron_key, fire_time)
@@ -240,8 +228,8 @@ module Kaal
       # Try to acquire the coordination lease
       if acquire_lock(lock_key)
         dispatch_work(entry, fire_time)
-      else
-        logger&.debug("Failed to acquire lock for #{lock_key}")
+      elsif logger
+        logger.debug("Failed to acquire lock for #{lock_key}")
       end
     rescue StandardError => e
       cron_key ||= 'unknown'
@@ -263,7 +251,7 @@ module Kaal
       jitter = rand(0..@configuration.recovery_startup_jitter)
       sleep(jitter) if jitter.positive?
 
-      current_time = Time.current
+      current_time = Time.now.utc
       recovery_window = @configuration.recovery_window
       recovery_start = current_time - recovery_window
       recovery_end = current_time
@@ -281,8 +269,11 @@ module Kaal
 
       # Clean up old dispatch records after recovery completes
       cleanup_old_dispatch_records(recovery_window)
+    rescue ConfigurationError => e
+      log_configuration_error('Kaal missed-run recovery failed', e, logger:)
+      raise
     rescue StandardError => e
-      logger&.error("Error during missed-run recovery: #{e.message}")
+      log_runtime_error('Error during missed-run recovery', e, logger:)
     end
 
     ##
@@ -307,12 +298,15 @@ module Kaal
 
       # Attempt to dispatch each missed occurrence
       occurrences.each do |fire_time|
-        dispatch_if_due(entry, fire_time, Time.current)
+        dispatch_if_due(entry, fire_time, Time.now.utc)
       end
 
       occurrences_size
+    rescue ConfigurationError => e
+      log_configuration_error("Error recovering entry #{entry_key}", e, logger:)
+      raise
     rescue StandardError => e
-      logger&.error("Error recovering entry #{entry_key}: #{e.message}")
+      log_runtime_error("Error recovering entry #{entry_key}", e, logger:)
       0
     end
 
@@ -368,37 +362,7 @@ module Kaal
     end
 
     def each_enabled_entry(&)
-      use_registry_entries = false
-      logger = @configuration.logger
-      warn_iteration_failure = ->(target, error) { logger&.warn("Failed to iterate #{target}: #{error.message}") }
-
-      begin
-        definition_registry = Kaal.definition_registry
-        return each_registry_entry(&) unless definition_registry
-
-        definitions = definition_registry.enabled_definitions || []
-        use_registry_entries = definitions.empty? && definition_registry.all_definitions.to_a.empty?
-
-        definitions
-          .filter_map { |definition| build_entry_from_definition(definition) }
-          .each(&)
-      rescue StandardError => e
-        warn_iteration_failure.call('enabled definitions', e)
-        use_registry_entries = true
-      end
-
-      each_registry_entry(&) if use_registry_entries
-    end
-
-    def build_entry_from_definition(definition)
-      key = definition[:key]
-      callback_entry = @registry.find(key)
-      unless callback_entry&.enqueue
-        @configuration.logger&.warn("No enqueue callback registered for definition '#{key}', skipping")
-        return nil
-      end
-
-      Registry::Entry.new(key: key, cron: definition[:cron], enqueue: callback_entry.enqueue).freeze
+      enabled_entry_enumerator.each(&)
     end
 
     def dispatch_work(entry, fire_time)
@@ -430,8 +394,24 @@ module Kaal
       @configuration.logger&.error("Sleep interrupted: #{e.message}")
     end
 
-    def each_registry_entry(&)
-      @registry.each(&)
+    def scheduler_time_zone_resolver
+      @scheduler_time_zone_resolver ||= SchedulerTimeZoneResolver.new(configuration: @configuration)
+    end
+
+    def occurrence_finder
+      @occurrence_finder ||= OccurrenceFinder.new(configuration: @configuration)
+    end
+
+    def enabled_entry_enumerator
+      @enabled_entry_enumerator ||= EnabledEntryEnumerator.new(configuration: @configuration, registry: @registry)
+    end
+
+    def log_configuration_error(prefix, error, logger: @configuration.logger)
+      logger&.error("#{prefix} due to configuration error: #{error.message}")
+    end
+
+    def log_runtime_error(prefix, error, logger: @configuration.logger)
+      logger&.error("#{prefix}: #{error.message}")
     end
   end
 end

data/lib/kaal/core/enabled_entry_enumerator.rb

@@ -0,0 +1,51 @@
+# 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
+  # Enumerates scheduler entries from persisted definitions or the in-memory registry.
+  class EnabledEntryEnumerator
+    def initialize(configuration:, registry:, definition_registry_provider: -> { Kaal.definition_registry })
+      @configuration = configuration
+      @registry = registry
+      @definition_registry_provider = definition_registry_provider
+    end
+
+    def each(&)
+      resolve_entries.each(&)
+    rescue StandardError => e
+      @configuration.logger&.warn("Failed to iterate enabled definitions: #{e.message}")
+      yield_registry_entries(&)
+    end
+
+    private
+
+    def yield_registry_entries(&)
+      @registry.each(&)
+    end
+
+    def resolve_entries
+      registry_entries = @registry.to_enum
+      definition_registry = @definition_registry_provider.call
+      return registry_entries unless definition_registry
+
+      definitions = definition_registry.enabled_definitions || []
+      return registry_entries if definitions.empty? && definition_registry.all_definitions.to_a.empty?
+
+      definitions.filter_map { |definition| build_entry(definition) }
+    end
+
+    def build_entry(definition)
+      key = definition[:key]
+      callback_entry = @registry.find(key)
+      unless callback_entry&.enqueue
+        @configuration.logger&.warn("No enqueue callback registered for definition '#{key}', skipping")
+        return nil
+      end
+
+      Registry::Entry.new(key: key, cron: definition[:cron], enqueue: callback_entry.enqueue).freeze
+    end
+  end
+end

data/lib/kaal/core/occurrence_finder.rb

@@ -0,0 +1,38 @@
+# 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
+  # Finds all absolute fire times for a parsed cron expression within a window.
+  class OccurrenceFinder
+    def initialize(configuration:)
+      @configuration = configuration
+    end
+
+    def call(cron:, start_time:, end_time:)
+      occurrences = []
+      current_time = start_time.getutc
+      normalized_end_time = end_time.getutc
+      normalized_end_time_unix = normalized_end_time.to_f
+
+      while current_time <= normalized_end_time
+        next_occurrence = cron.next_time(current_time)
+        break unless next_occurrence
+
+        next_occurrence_unix = next_occurrence.to_f
+        break if next_occurrence_unix > normalized_end_time_unix
+
+        fire_time = Time.at(next_occurrence_unix).utc
+        occurrences << fire_time
+        current_time = Time.at(next_occurrence_unix + 1).utc
+      end
+
+      occurrences
+    rescue StandardError => e
+      @configuration.logger&.error("Failed to calculate occurrences: #{e.message}")
+      []
+    end
+  end
+end

data/lib/kaal/core.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/core/coordinator'
+require 'kaal/core/occurrence_finder'
+require 'kaal/core/enabled_entry_enumerator'
+
+module Kaal
+  # Core scheduling orchestration types.
+  module Core
+    Coordinator = ::Kaal::Coordinator
+    OccurrenceFinder = ::Kaal::OccurrenceFinder
+    EnabledEntryEnumerator = ::Kaal::EnabledEntryEnumerator
+  end
+end

data/lib/kaal/definition/database_engine.rb

@@ -4,46 +4,84 @@
 #
 # 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'
+require 'json'
+require 'kaal/definition/registry'
+require 'kaal/definition/persistence_helpers'
+require 'kaal/persistence/database'
 
 module Kaal
   module Definition
-    # ActiveRecord-backed definition registry persisted in kaal_definitions.
+    # Sequel-backed definition registry persisted in kaal_definitions.
     class DatabaseEngine < Registry
-      def initialize
-        super
-        @definition_model = ::Kaal::CronDefinition
+      def initialize(database:)
+        super()
+        @database = Kaal::Persistence::Database.new(database)
       end
 
       def upsert_definition(key:, cron:, enabled: true, source: 'code', metadata: {})
-        @definition_model.upsert_definition!(
+        rows = dataset.where(key: key)
+        existing = rows.first
+        now = Time.now.utc
+        payload = {
           key: key,
           cron: cron,
           enabled: enabled,
           source: source,
-          metadata: metadata
-        ).to_definition_hash
+          metadata: JSON.generate(metadata || {}),
+          created_at: existing ? existing[:created_at] : now,
+          updated_at: now,
+          disabled_at: PersistenceHelpers.disabled_at_for(existing, enabled, now)
+        }
+
+        if existing
+          rows.update(payload)
+        else
+          dataset.insert(payload)
+        end
+
+        find_definition(key)
       end
 
       def remove_definition(key)
-        record = @definition_model.find_by(key: key)
-        return nil unless record
+        rows = dataset.where(key: key)
+        row = rows.first
+        return nil unless row
 
-        record.destroy_and_return_definition_hash
+        rows.delete
+        self.class.normalize_row(row)
       end
 
       def find_definition(key)
-        record = @definition_model.find_by(key: key)
-        record&.to_definition_hash
+        self.class.normalize_row(dataset.where(key: key).first)
       end
 
       def all_definitions
-        @definition_model.order(:key).map(&:to_definition_hash)
+        dataset.order(:key).all.map { |row| self.class.normalize_row(row) }
       end
 
       def enabled_definitions
-        @definition_model.where(enabled: true).order(:key).map(&:to_definition_hash)
+        dataset.where(enabled: true).order(:key).all.map { |row| self.class.normalize_row(row) }
+      end
+
+      def self.normalize_row(row)
+        return nil unless row
+
+        {
+          key: row[:key],
+          cron: row[:cron],
+          enabled: row[:enabled] ? true : false,
+          source: row[:source],
+          metadata: PersistenceHelpers.parse_metadata(row[:metadata]),
+          created_at: row[:created_at],
+          updated_at: row[:updated_at],
+          disabled_at: row[:disabled_at]
+        }
+      end
+
+      private
+
+      def dataset
+        @database.definitions_dataset
       end
     end
   end

data/lib/kaal/definition/memory_engine.rb

@@ -4,14 +4,16 @@
 #
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
-
-require 'active_support/core_ext/object/deep_dup'
 require_relative 'registry'
+require_relative 'persistence_helpers'
+require 'kaal/support/hash_tools'
 
 module Kaal
   module Definition
     # In-memory definition registry used when no persistent backend is configured.
     class MemoryEngine < Registry
+      include Kaal::Support::HashTools
+
       def initialize
         super
         @definitions = {}
@@ -20,42 +22,33 @@ module Kaal
 
       def upsert_definition(key:, cron:, enabled: true, source: 'code', metadata: {})
         @mutex.synchronize do
-          now = Time.current
+          now = Time.now.utc
           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,
+            metadata: deep_dup(metadata || {}),
             created_at: existing ? existing[:created_at] : now,
             updated_at: now,
-            disabled_at:
+            disabled_at: PersistenceHelpers.disabled_at_for(existing, enabled, now)
           }
           @definitions[key] = definition
-
-          definition.deep_dup
+          deep_dup(definition)
         end
       end
 
       def remove_definition(key)
-        @mutex.synchronize { @definitions.delete(key)&.deep_dup }
+        @mutex.synchronize { deep_dup(@definitions.delete(key)) }
       end
 
       def find_definition(key)
-        @mutex.synchronize { @definitions[key]&.deep_dup }
+        @mutex.synchronize { deep_dup(@definitions[key]) }
       end
 
       def all_definitions
-        @mutex.synchronize { @definitions.values.map(&:deep_dup) }
+        @mutex.synchronize { @definitions.values.sort_by { |definition| definition[:key] }.map { |definition| deep_dup(definition) } }
       end
 
       def clear

data/lib/kaal/definition/persistence_helpers.rb

@@ -0,0 +1,31 @@
+# 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'
+
+module Kaal
+  module Definition
+    # Shared pure helpers for persisted definition rows and metadata.
+    module PersistenceHelpers
+      module_function
+
+      def disabled_at_for(existing, enabled, now)
+        return nil if enabled
+        return existing[:disabled_at] if existing && existing[:enabled] == false
+
+        now
+      end
+
+      def parse_metadata(value)
+        return {} if value.to_s.empty?
+
+        JSON.parse(value, symbolize_names: true)
+      rescue JSON::ParserError
+        {}
+      end
+    end
+  end
+end

data/lib/kaal/definition/redis_engine.rb

@@ -4,15 +4,18 @@
 #
 # 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 'time'
 require_relative 'registry'
+require 'kaal/support/hash_tools'
+require 'kaal/definition/persistence_helpers'
 
 module Kaal
   module Definition
     # Redis-backed definition registry shared across processes.
     class RedisEngine < Registry
+      include Kaal::Support::HashTools
+
       def initialize(redis, namespace: 'kaal')
         super()
         @redis = redis
@@ -20,21 +23,21 @@ module Kaal
       end
 
       def upsert_definition(key:, cron:, enabled: true, source: 'code', metadata: {})
-        now = Time.current
+        now = Time.now.utc
         existing = find_definition(key)
         payload = {
           key: key,
           cron: cron,
           enabled: enabled,
           source: source,
-          metadata: metadata,
+          metadata: deep_dup(metadata || {}),
           created_at: existing ? existing[:created_at] : now,
           updated_at: now,
-          disabled_at: enabled ? nil : now
+          disabled_at: PersistenceHelpers.disabled_at_for(existing, enabled, now)
         }
 
         @redis.hset(storage_key, key, JSON.generate(self.class.serialize_payload(payload)))
-        payload
+        deep_dup(payload)
       end
 
       def remove_definition(key)
@@ -49,7 +52,7 @@ module Kaal
       end
 
       def all_definitions
-        @redis.hvals(storage_key).filter_map { |raw| self.class.deserialize_payload(raw) }
+        @redis.hvals(storage_key).filter_map { |raw| self.class.deserialize_payload(raw) }.sort_by { |definition| definition[:key] }
       end
 
       private

data/lib/kaal/definition/registry.rb

@@ -4,9 +4,31 @@
 #
 # 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 Definition
+    # Pure helpers for extracting persisted definition attributes without ActiveSupport.
+    module AttributeHelpers
+      module_function
+
+      def definition_attributes(definition)
+        {
+          key: definition[:key],
+          cron: definition[:cron],
+          source: definition[:source],
+          metadata: definition[:metadata]
+        }
+      end
+
+      def persisted_definition_attributes(definition)
+        return {} unless definition
+
+        {
+          enabled: definition[:enabled],
+          metadata: definition[:metadata]
+        }
+      end
+    end
+
     # Base abstraction for cron definition storage.
     class Registry
       def upsert_definition(**)
@@ -43,7 +65,7 @@ module Kaal
         definition = find_definition(key)
         return nil unless definition
 
-        attributes = definition.slice(:key, :cron, :source, :metadata).merge(enabled: enabled)
+        attributes = AttributeHelpers.definition_attributes(definition).merge(enabled: enabled)
         upsert_definition(**attributes)
       end
     end

data/lib/kaal/definitions/registration_service.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 Definitions
+    # Registers code-defined jobs while preserving persisted definition state.
+    class RegistrationService
+      include RegisterConflictSupport
+
+      attr_reader :configuration, :definition_registry, :registry
+
+      def initialize(configuration:, definition_registry:, registry:)
+        @configuration = configuration
+        @definition_registry = definition_registry
+        @registry = registry
+      end
+
+      def call(key:, cron:, enqueue:)
+        existing_definition = @definition_registry.find_definition(key)
+        existing_entry = @registry.find(key)
+        if existing_entry
+          conflict_result = resolve_register_conflict(
+            key: key,
+            cron: cron,
+            enqueue: enqueue,
+            existing_definition: existing_definition,
+            existing_entry: existing_entry
+          )
+
+          return conflict_result if conflict_result
+
+          raise RegistryError, "Key '#{key}' is already registered"
+        end
+
+        persisted_attributes = {
+          enabled: true,
+          source: 'code',
+          metadata: {}
+        }.merge(Definition::AttributeHelpers.persisted_definition_attributes(existing_definition))
+        @definition_registry.upsert_definition(key: key, cron: cron, **persisted_attributes)
+        with_registered_definition_rollback(key, existing_definition) do
+          @registry.add(key: key, cron: cron, enqueue: enqueue)
+        end
+      end
+
+      private
+
+      def rollback_registered_definition(key, existing_definition)
+        if existing_definition
+          @definition_registry.upsert_definition(
+            **Definition::AttributeHelpers.definition_attributes(existing_definition), enabled: existing_definition[:enabled]
+          )
+        elsif !@registry.registered?(key)
+          @definition_registry.remove_definition(key)
+        end
+      end
+    end
+  end
+end

data/lib/kaal/definitions/registry_accessor.rb

@@ -0,0 +1,33 @@
+# 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 Definitions
+    # Resolves the active definition registry with an in-memory fallback.
+    class RegistryAccessor
+      def initialize(configuration:, fallback_registry_provider:)
+        @configuration = configuration
+        @fallback_registry_provider = fallback_registry_provider
+      end
+
+      def call
+        configured_backend = @configuration.backend
+        registry = configured_backend&.definition_registry
+        return registry if registry
+
+        fallback_registry
+      rescue NoMethodError
+        fallback_registry
+      end
+
+      private
+
+      def fallback_registry
+        @fallback_registry_provider.call
+      end
+    end
+  end
+end