kaal 0.2.1 → 0.4.0

data/lib/kaal/backend/dispatch_logging.rb

@@ -4,8 +4,7 @@
 #
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
-
-require 'socket'
+require_relative 'dispatch_attempt_logger'
 
 module Kaal
   module Backend
@@ -25,6 +24,10 @@ module Kaal
     #     end
     #   end
     module DispatchLogging
+      def dispatch_registry
+        nil
+      end
+
       ##
       # Log a dispatch attempt via the dispatch registry.
       #
@@ -33,23 +36,7 @@ module Kaal
       # @param key [String] the lock key (format: "namespace:dispatch:cron_key:fire_time")
       # @return [void]
       def log_dispatch_attempt(key)
-        logger = nil
-        logging_enabled = Kaal.configuration.then do |configuration|
-          logger = configuration.logger
-          configuration.enable_log_dispatch_registry
-        end
-        return unless logging_enabled
-        return unless respond_to?(:dispatch_registry)
-
-        registry = dispatch_registry
-        return unless registry
-
-        cron_key, fire_time = parse_lock_key(key)
-        node_id = Socket.gethostname
-
-        registry.log_dispatch(cron_key, fire_time, node_id, 'dispatched')
-      rescue StandardError => e
-        logger&.error("Failed to log dispatch for #{key}: #{e.message}")
+        dispatch_attempt_logger.call(key)
       end
 
       ##
@@ -67,13 +54,39 @@ module Kaal
 
       def self.parse_lock_key(key)
         parts = key.split(':')
-        fire_time_unix = parts.pop.to_i
-        2.times { parts.shift } # Remove namespace and "dispatch"
-        cron_key = parts.join(':')
-        fire_time = Time.at(fire_time_unix)
+        invalid_message = "Invalid dispatch lock key format: #{key.inspect}"
+        dispatch_index = parts[0...-1].rindex('dispatch')
+        timestamp = parts[-1]
+        valid_key = parts.length >= 4 && dispatch_index&.positive? && timestamp.match?(/\A\d+\z/)
+        validate_lock_key!(valid_key, invalid_message)
+
+        fire_time_unix = timestamp.to_i
+        cron_key = parts[(dispatch_index + 1)...-1].join(':')
+        validate_lock_key!(!cron_key.empty?, invalid_message)
+
+        fire_time = Time.at(fire_time_unix).utc
 
         [cron_key, fire_time]
       end
+
+      def self.validate_lock_key!(valid, message)
+        invalid_dispatch_lock_key!(message) unless valid
+      end
+      private_class_method :validate_lock_key!
+
+      def self.invalid_dispatch_lock_key!(message)
+        raise ArgumentError, message
+      end
+      private_class_method :invalid_dispatch_lock_key!
+
+      private
+
+      def dispatch_attempt_logger
+        @dispatch_attempt_logger ||= DispatchAttemptLogger.new(
+          configuration: Kaal.configuration,
+          dispatch_registry_provider: -> { dispatch_registry }
+        )
+      end
     end
   end
 end

data/lib/kaal/backend/dispatch_registry_accessor.rb

@@ -0,0 +1,43 @@
+# 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 Backend
+    # Reads dispatch registry state through the configured backend adapter.
+    class DispatchRegistryAccessor
+      def initialize(configuration:)
+        @configuration = configuration
+      end
+
+      def dispatched?(key, fire_time)
+        registry = fetch_registry
+        return false unless registry
+
+        registry.dispatched?(key, fire_time)
+      rescue StandardError => e
+        @configuration.logger&.warn("Error checking dispatch status for #{key}: #{e.message}")
+        false
+      end
+
+      def registry
+        fetch_registry
+      rescue StandardError => e
+        @configuration.logger&.warn("Error accessing dispatch registry: #{e.message}")
+        nil
+      end
+
+      private
+
+      def fetch_registry
+        adapter = @configuration.backend
+        return nil unless adapter
+        return nil unless adapter.respond_to?(:dispatch_registry)
+
+        adapter.dispatch_registry
+      end
+    end
+  end
+end

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/mysql.rb

@@ -0,0 +1,41 @@
+# 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 Backend
+    # MySQL-backed backend for either Sequel or Active Record persistence.
+    class MySQL < Adapter
+      def initialize(database: nil, connection: nil, namespace: nil, **)
+        super()
+        @engine = if database
+                    Kaal::Sequel.require_sequel!
+                    require 'kaal/internal/sequel'
+                    Kaal::Internal::Sequel::MySQLBackend.new(database, namespace:)
+                  else
+                    Kaal::ActiveRecord.require_activerecord!
+                    require 'kaal/internal/active_record'
+                    Kaal::Internal::ActiveRecord::MySQLBackend.new(connection, namespace:, **)
+                  end
+      end
+
+      def dispatch_registry
+        @engine.dispatch_registry
+      end
+
+      def definition_registry
+        @engine.definition_registry
+      end
+
+      def acquire(key, ttl)
+        @engine.acquire(key, ttl)
+      end
+
+      def release(key)
+        @engine.release(key)
+      end
+    end
+  end
+end

data/lib/kaal/backend/postgres.rb

@@ -0,0 +1,41 @@
+# 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 Backend
+    # PostgreSQL-backed backend for either Sequel or Active Record persistence.
+    class Postgres < Adapter
+      def initialize(database: nil, connection: nil, namespace: nil, **)
+        super()
+        @engine = if database
+                    Kaal::Sequel.require_sequel!
+                    require 'kaal/internal/sequel'
+                    Kaal::Internal::Sequel::PostgresBackend.new(database, namespace:)
+                  else
+                    Kaal::ActiveRecord.require_activerecord!
+                    require 'kaal/internal/active_record'
+                    Kaal::Internal::ActiveRecord::PostgresBackend.new(connection, namespace:, **)
+                  end
+      end
+
+      def dispatch_registry
+        @engine.dispatch_registry
+      end
+
+      def definition_registry
+        @engine.definition_registry
+      end
+
+      def acquire(key, ttl)
+        @engine.acquire(key, ttl)
+      end
+
+      def release(key)
+        @engine.release(key)
+      end
+    end
+  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/backend/sqlite.rb

@@ -0,0 +1,41 @@
+# 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 Backend
+    # SQLite-backed backend for either Sequel or Active Record persistence.
+    class SQLite < Adapter
+      def initialize(database: nil, connection: nil, namespace: nil, **)
+        super()
+        @engine = if database
+                    Kaal::Sequel.require_sequel!
+                    require 'kaal/internal/sequel'
+                    Kaal::Internal::Sequel::DatabaseBackend.new(database, namespace:)
+                  else
+                    Kaal::ActiveRecord.require_activerecord!
+                    require 'kaal/internal/active_record'
+                    Kaal::Internal::ActiveRecord::DatabaseBackend.new(connection, namespace:, **)
+                  end
+      end
+
+      def dispatch_registry
+        @engine.dispatch_registry
+      end
+
+      def definition_registry
+        @engine.definition_registry
+      end
+
+      def acquire(key, ttl)
+        @engine.acquire(key, ttl)
+      end
+
+      def release(key)
+        @engine.release(key)
+      end
+    end
+  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