kaal 0.2.1 → 0.3.0

data/lib/kaal/backend/memory_adapter.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_relative 'dispatch_logging'
 require_relative '../definition/memory_engine'
 
@@ -65,10 +64,10 @@ module Kaal
         acquired = @mutex.synchronize do
           prune_expired_locks
           expiration_time = @locks[key]
-          current_time = Time.current
+          current_time = Time.now.utc
           next false if expiration_time && expiration_time > current_time
 
-          @locks[key] = current_time + ttl.seconds
+          @locks[key] = current_time + ttl
           true
         end
 
@@ -84,14 +83,17 @@ module Kaal
       # @return [Boolean] true if released (key was held), false if not held
       def release(key)
         @mutex.synchronize do
-          @locks.delete(key).present?
+          return false unless @locks.key?(key)
+
+          @locks.delete(key)
+          true
         end
       end
 
       private
 
       def prune_expired_locks
-        now = Time.current
+        now = Time.now.utc
         @locks.delete_if { |_key, expiration_time| expiration_time <= now }
       end
     end

data/lib/kaal/backend/redis_adapter.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 'securerandom'
 require_relative 'dispatch_logging'
 require_relative '../definition/redis_engine'
@@ -83,14 +82,15 @@ module Kaal
         # SET key value NX PX ttl returns OK if set, nil if not set
         result = @redis.set(key, lock_value, nx: true, px: ttl_ms)
 
-        if result
+        acquired = ['OK', true].include?(result)
+
+        if acquired
           @mutex.synchronize do
-            @lock_values[key] = { value: lock_value, expires_at: Time.now + ttl }
+            @lock_values[key] = { value: lock_value, expires_at: Time.now.utc + ttl }
             prune_expired_lock_values
           end
         end
 
-        acquired = result.present?
         log_dispatch_attempt(key) if acquired
 
         acquired
@@ -125,7 +125,7 @@ module Kaal
         LUA
 
         result = @redis.eval(script, keys: [key], argv: [lock_value])
-        result.present? && result.positive?
+        [1, '1', true].include?(result)
       rescue StandardError => e
         raise LockAdapterError, "Redis release failed for #{key}: #{e.message}"
       end
@@ -137,7 +137,7 @@ module Kaal
       end
 
       def prune_expired_lock_values
-        now = Time.now
+        now = Time.now.utc
         @lock_values.delete_if { |_key, entry| entry[:expires_at] <= now }
       end
     end

data/lib/kaal/cli.rb

@@ -0,0 +1,230 @@
+# 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 'thor'
+require 'fileutils'
+require 'fugit'
+require 'kaal'
+
+module Kaal
+  # Thor-powered CLI for plain-Ruby usage.
+  class CLI < Thor
+    # Internal instance helpers excluded from the public Thor command surface.
+    module Helpers
+      private
+
+      def load_project!
+        Kaal.reset_configuration!
+        Kaal.reset_registry!
+        load config_path
+        runtime_context = RuntimeContext.default(root_path: root_path)
+        Kaal.load_scheduler_file!(runtime_context: runtime_context) if File.exist?(scheduler_path)
+      end
+
+      def root_path
+        File.expand_path(options[:root])
+      end
+
+      def config_path
+        config = options[:config]
+        return File.expand_path(config) if config
+
+        File.join(root_path, 'config', 'kaal.rb')
+      end
+
+      def scheduler_path
+        File.join(root_path, 'config', 'scheduler.yml')
+      end
+
+      def render_config_template(backend)
+        case backend
+        when 'memory'
+          <<~RUBY
+            require 'kaal'
+
+            Kaal.configure do |config|
+              config.backend = Kaal::Backend::MemoryAdapter.new
+              config.tick_interval = 5
+              config.window_lookback = 120
+              config.lease_ttl = 125
+              config.scheduler_config_path = 'config/scheduler.yml'
+            end
+          RUBY
+        when 'redis'
+          <<~RUBY
+            require 'kaal'
+            require 'redis'
+
+            redis = Redis.new(url: ENV.fetch('REDIS_URL'))
+
+            Kaal.configure do |config|
+              config.backend = Kaal::Backend::RedisAdapter.new(redis, namespace: 'kaal')
+              config.tick_interval = 5
+              config.window_lookback = 120
+              config.lease_ttl = 125
+              config.scheduler_config_path = 'config/scheduler.yml'
+            end
+          RUBY
+        else
+          raise Thor::Error, "Unsupported backend '#{backend}'"
+        end
+      end
+
+      def scheduler_template
+        <<~YAML
+          defaults:
+            jobs:
+              - key: "example:heartbeat"
+                cron: "*/5 * * * *"
+                job_class: "ExampleHeartbeatJob"
+                enabled: true
+                args:
+                  - "{{fire_time.iso8601}}"
+                kwargs:
+                  idempotency_key: "{{idempotency_key}}"
+                metadata:
+                  owner: "ops"
+        YAML
+      end
+    end
+
+    package_name 'kaal'
+
+    class_option :root, type: :string, default: Dir.pwd, desc: 'Project root'
+    class_option :config, type: :string, desc: 'Path to config/kaal.rb'
+
+    desc 'init', 'Generate config/kaal.rb and config/scheduler.yml'
+    option :backend, type: :string, default: 'memory', enum: %w[memory redis]
+    def init
+      root = File.expand_path(options[:root])
+      backend = options[:backend]
+      writer = self.class
+      FileUtils.mkdir_p(File.join(root, 'config'))
+
+      writer.write_file(File.join(root, 'config', 'kaal.rb'), render_config_template(backend))
+      writer.write_file(File.join(root, 'config', 'scheduler.yml'), scheduler_template)
+
+      say("Initialized Kaal project for #{backend} backend")
+    end
+
+    desc 'start', 'Start the scheduler loop in the foreground'
+    def start
+      load_project!
+
+      signal_state = {
+        graceful_shutdown_started: false,
+        shutdown_complete: false,
+        force_exit_requested: false
+      }
+      previous_handlers = Kaal::CLI.install_foreground_signal_handlers(signal_state)
+
+      begin
+        thread = Kaal.start!
+        raise Thor::Error, 'scheduler is already running' unless thread
+
+        say('Kaal scheduler started in foreground')
+        thread.join
+      rescue Interrupt
+        raise Thor::Error, 'shutdown timed out; forced exit requested' if signal_state[:force_exit_requested]
+
+        Kaal::CLI.shutdown_scheduler(signal: 'INT', signal_state: signal_state, shell: shell)
+      ensure
+        Kaal::CLI.restore_signal_handlers(previous_handlers)
+      end
+    end
+
+    desc 'status', 'Show scheduler status and registered jobs'
+    def status
+      load_project!
+      registered = Kaal.registered
+      say("Kaal v#{Kaal::VERSION}")
+      say("Running: #{Kaal.running?}")
+      say("Tick interval: #{Kaal.tick_interval}s")
+      say("Window lookback: #{Kaal.window_lookback}s")
+      say("Window lookahead: #{Kaal.window_lookahead}s")
+      say("Lease TTL: #{Kaal.lease_ttl}s")
+      say("Namespace: #{Kaal.namespace}")
+      say("Registered jobs: #{registered.length}")
+      registered.each { |entry| say("  - #{entry.key} (#{entry.cron})") }
+    end
+
+    desc 'tick', 'Run a single scheduler tick'
+    def tick
+      load_project!
+      Kaal.tick!
+      say('Kaal tick completed')
+    end
+
+    desc 'explain EXPRESSION', 'Humanize a cron expression'
+    def explain(expression)
+      say(Kaal.to_human(expression))
+    end
+
+    desc 'next EXPRESSION', 'Print upcoming fire times'
+    option :count, type: :numeric, default: 5
+    def next(expression)
+      cron = Fugit.parse_cron(expression)
+      raise Thor::Error, "Invalid cron expression: #{expression}" unless cron
+
+      current = Time.now.utc
+      options[:count].to_i.times do
+        current = cron.next_time(current).to_t.utc
+        say(current.iso8601)
+      end
+    end
+
+    def self.exit_on_failure?
+      true
+    end
+
+    def self.write_file(path, contents)
+      return if File.exist?(path)
+
+      File.write(path, contents)
+    end
+
+    def self.install_foreground_signal_handlers(signal_state)
+      installer = SignalHandlerInstaller.new
+      installer.install do |signal, previous_handler|
+        shutdown_scheduler(signal: signal, signal_state: signal_state, previous_handler: previous_handler)
+      end
+    end
+
+    def self.restore_signal_handlers(previous_handlers)
+      previous_handlers.each do |signal, handler|
+        Signal.trap(signal, handler)
+      rescue StandardError
+        nil
+      end
+    end
+
+    def self.shutdown_scheduler(signal:, signal_state:, previous_handler: nil, shell: nil)
+      shell_instance = shell || Thor::Base.shell.new
+      return if signal_state[:shutdown_complete]
+
+      if signal_state[:graceful_shutdown_started]
+        signal_state[:force_exit_requested] = true
+        shell_instance.warn("Received #{signal} again; forcing scheduler shutdown")
+        Thread.main.raise(Interrupt)
+        return
+      end
+
+      signal_state[:graceful_shutdown_started] = true
+      shell_instance.say("Received #{signal}, stopping Kaal scheduler...")
+      stopped = Kaal.stop!(timeout: 30)
+      if stopped
+        signal_state[:shutdown_complete] = true
+        shell_instance.say('Kaal scheduler stopped')
+      else
+        shell_instance.warn('Kaal scheduler stop timed out; send TERM/INT again to force exit')
+      end
+    ensure
+      SignalHandlerChain.new(signal: signal, previous_handler: previous_handler, logger: Kaal.logger).call(signal)
+    end
+
+    no_commands { include Helpers }
+  end
+end

data/lib/kaal/{configuration.rb → config/configuration.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
   ##
   # Configuration class for Kaal

data/lib/kaal/{scheduler_config_error.rb → config/scheduler_config_error.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
   # Raised when scheduler file configuration is invalid or cannot be loaded.
   class SchedulerConfigError < StandardError; end

data/lib/kaal/config/scheduler_time_zone_resolver.rb

@@ -0,0 +1,50 @@
+# 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 'tzinfo'
+
+module Kaal
+  # Resolves the configured scheduler time zone, preferring explicit config.
+  class SchedulerTimeZoneResolver
+    DEFAULT_TIME_ZONE = 'UTC'
+
+    def initialize(configuration:)
+      @configuration = configuration
+    end
+
+    def time_zone_identifier
+      zone = begin
+        Time.zone
+      rescue NoMethodError
+        nil
+      end
+      configured_time_zone || zone&.tzinfo&.identifier || DEFAULT_TIME_ZONE
+    end
+
+    private
+
+    def configured_time_zone
+      value = normalized_time_zone_value
+      return nil if value.empty?
+
+      TZInfo::Timezone.get(value)
+      value
+    rescue TZInfo::InvalidTimezoneIdentifier
+      raise ConfigurationError, "Invalid time_zone configuration: #{raw_time_zone_value.inspect} (normalized: #{value.inspect})"
+    end
+
+    def normalized_time_zone_value
+      value = raw_time_zone_value
+      return DEFAULT_TIME_ZONE if value.casecmp?(DEFAULT_TIME_ZONE)
+
+      value
+    end
+
+    def raw_time_zone_value
+      @configuration.time_zone.to_s.strip
+    end
+  end
+end

data/lib/kaal/config.rb

@@ -0,0 +1,19 @@
+# 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/config/configuration'
+require 'kaal/config/scheduler_config_error'
+require 'kaal/config/scheduler_time_zone_resolver'
+
+module Kaal
+  # Configuration-related types and validation helpers.
+  module Config
+    Configuration = ::Kaal::Configuration
+    ConfigurationError = ::Kaal::ConfigurationError
+    SchedulerConfigError = ::Kaal::SchedulerConfigError
+    SchedulerTimeZoneResolver = ::Kaal::SchedulerTimeZoneResolver
+  end
+end

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