kaal 0.2.1 → 0.3.0

data/lib/kaal.rb

@@ -4,224 +4,94 @@
 #
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
-
 require 'kaal/version'
-require 'kaal/configuration'
+require 'kaal/config'
 require 'kaal/registry'
 require 'kaal/dispatch/registry'
 require 'kaal/dispatch/memory_engine'
 require 'kaal/dispatch/redis_engine'
-require 'kaal/dispatch/database_engine'
 require 'kaal/definition/registry'
 require 'kaal/definition/memory_engine'
 require 'kaal/definition/redis_engine'
-require 'kaal/definition/database_engine'
 require 'kaal/backend/adapter'
 require 'kaal/backend/memory_adapter'
 require 'kaal/backend/redis_adapter'
-require 'kaal/backend/postgres_adapter'
-require 'kaal/backend/mysql_adapter'
-require 'kaal/backend/sqlite_adapter'
-require 'kaal/idempotency_key_generator'
-require 'kaal/cron_utils'
-require 'kaal/cron_humanizer'
-require 'kaal/scheduler_config_error'
-require 'kaal/scheduler_file_loader'
+require 'kaal/backend/dispatch_registry_accessor'
+require 'kaal/backend/dispatch_attempt_logger'
+require 'kaal/utils'
 require 'kaal/register_conflict_support'
-require 'kaal/rake_tasks'
-require 'kaal/coordinator'
-require 'kaal/railtie'
-
-##
-# Kaal module is the main namespace for the gem.
-# Provides configuration, job registration, and registry access.
-#
-# @example Configure Kaal
-#   Kaal.configure do |config|
-#     config.tick_interval = 5
-#     config.backend = Kaal::Backend::RedisAdapter.new(Redis.new(url: ENV["REDIS_URL"]))
-#   end
-#
-# @example Register a cron job
-#   Kaal.register(
-#     key: "reports:daily",
-#     cron: "0 9 * * *",
-#     enqueue: ->(fire_time:, idempotency_key:) { MyJob.perform_later }
-#   )
+require 'kaal/definitions/registry_accessor'
+require 'kaal/definitions/registration_service'
+require 'kaal/runtime'
+require 'kaal/scheduler_file'
+require 'kaal/core'
+require 'kaal/support/hash_tools'
+
+# Plain-Ruby scheduler surface with configurable backends, registries, and CLI helpers.
 module Kaal
   class << self
     include RegisterConflictSupport
 
-    ##
-    # Get the current configuration instance.
-    #
-    # @return [Configuration] the global configuration object
     def configuration
       @configuration ||= Configuration.new
     end
 
-    ##
-    # Get the current registry instance.
-    #
-    # @return [Registry] the global registry object
     def registry
       @registry ||= Registry.new
     end
 
-    ##
-    # Get the coordinator instance.
-    #
-    # @return [Coordinator] the global coordinator object
     def coordinator
       @coordinator ||= Coordinator.new(configuration: configuration, registry: registry)
     end
 
-    ##
-    # Reset configuration to defaults. Primarily used in tests.
-    #
-    # @return [Configuration] a fresh configuration object
     def reset_configuration!
       @configuration = Configuration.new
-      @coordinator = nil # Invalidate coordinator so it rebuilds with new config
+      @coordinator = nil
       @definition_registry = nil
+      @definitions_registry_accessor = nil
+      @dispatch_registry_accessor = nil
     end
 
-    ##
-    # Reset registry to empty state. Primarily used in tests.
-    #
-    # @return [Registry] a fresh registry object
     def reset_registry!
       @registry = Registry.new
-      @definition_registry&.clear
-      @coordinator = nil # Invalidate coordinator so it rebuilds with new registry
+      definition_registry = @definition_registry
+      definition_registry.clear if definition_registry.respond_to?(:clear)
+      @coordinator = nil
     end
 
-    ##
-    # Reset coordinator to initial state. Primarily used in tests.
-    #
-    # Stops any running coordinator and creates a fresh instance.
-    #
-    # @return [Coordinator] a fresh coordinator object
-    # @raise [RuntimeError] if the running coordinator cannot be stopped within timeout
     def reset_coordinator!
-      # Stop the existing coordinator if it's running
       if @coordinator&.running?
         stopped = @coordinator.stop!
         raise 'Failed to stop coordinator thread within timeout' unless stopped
       end
 
-      # Create and return a fresh coordinator
       @coordinator = nil
       coordinator
     end
 
-    ##
-    # Configure Kaal via a block.
-    #
-    # @yield [config] yields the configuration object
-    # @yieldparam config [Configuration] the configuration instance to customize
-    # @return [void]
-    #
-    # @example
-    #   Kaal.configure do |config|
-    #     config.tick_interval = 10
-    #     config.lease_ttl = 120
-    #   end
     def configure
       yield(configuration) if block_given?
     end
 
-    ##
-    # Register a new cron job.
-    #
-    # @param key [String] unique identifier for the cron task
-    # @param cron [String] cron expression (e.g., "0 9 * * *", "@daily")
-    # @param enqueue [Proc, Lambda] callable executed when cron fires
-    # @return [Registry::Entry] the registered entry
-    #
-    # @raise [ArgumentError] if parameters are invalid
-    # @raise [RegistryError] if key is already registered
-    #
-    # @example
-    #   Kaal.register(
-    #     key: "reports:weekly_summary",
-    #     cron: "0 9 * * 1",
-    #     enqueue: ->(fire_time:, idempotency_key:) { WeeklySummaryJob.perform_later }
-    #   )
     def register(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(existing_definition&.slice(:enabled, :metadata) || {})
-      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
+      registration_service.call(key:, cron:, enqueue:)
     end
 
-    ##
-    # Load scheduler definitions from the configured scheduler YAML file.
-    #
-    # @return [Array<Hash>] normalized jobs applied from scheduler file
-    # @raise [SchedulerConfigError] if scheduler file is invalid
-    def load_scheduler_file!
-      loader = SchedulerFileLoader.new(
+    def load_scheduler_file!(runtime_context: RuntimeContext.default)
+      SchedulerFileLoader.new(
         configuration: configuration,
         definition_registry: definition_registry,
         registry: registry,
-        logger: configuration.logger
-      )
-      loader.load
+        logger: configuration.logger,
+        runtime_context: runtime_context
+      ).load
     end
 
-    ##
-    # Unregister (remove) a cron job by key.
-    #
-    # @param key [String] the unique identifier of the job to remove
-    # @return [Registry::Entry, nil] the removed entry, or nil if not found
     def unregister(key:)
       definition_registry.remove_definition(key)
       registry.remove(key)
     end
 
-    def rollback_registered_definition(key, existing_definition)
-      if existing_definition
-        definition_registry.upsert_definition(
-          key: existing_definition[:key],
-          cron: existing_definition[:cron],
-          enabled: existing_definition[:enabled],
-          source: existing_definition[:source],
-          metadata: existing_definition[:metadata]
-        )
-      elsif !registry.registered?(key)
-        definition_registry.remove_definition(key)
-      end
-    end
-    private :rollback_registered_definition
-
-    ##
-    # Get all registered cron jobs.
-    #
-    # @return [Array<Registry::Entry>] array of all registered entries
-    #
-    # @example
-    #   Kaal.registered.each { |entry| puts entry.key }
     def registered
       definition_registry.all_definitions.map do |definition|
         key = definition[:key]
@@ -230,297 +100,97 @@ module Kaal
       end
     end
 
-    ##
-    # Check if a cron job is registered by key.
-    #
-    # @param key [String] the unique identifier to check
-    # @return [Boolean] true if the key is registered, false otherwise
-    #
-    # @example
-    #   Kaal.registered?(key: "reports:daily") # => true
     def registered?(key:)
-      definition_registry.find_definition(key).present?
+      !!definition_registry.find_definition(key)
     end
 
-    ##
-    # Enable a registered cron definition by key.
-    #
-    # @param key [String] the unique identifier to enable
-    # @return [Hash, nil] enabled definition hash or nil if missing
     def enable(key:)
       definition_registry.enable_definition(key)
     end
 
-    ##
-    # Disable a registered cron definition by key.
-    #
-    # @param key [String] the unique identifier to disable
-    # @return [Hash, nil] disabled definition hash or nil if missing
     def disable(key:)
       definition_registry.disable_definition(key)
     end
 
-    ##
-    # Start the scheduler background thread.
-    #
-    # The coordinator will calculate due fire times for each registered cron
-    # on each tick and attempt to dispatch work.
-    #
-    # @return [Thread] the started thread, or nil if already running
-    #
-    # @example
-    #   Kaal.start!
     def start!
       coordinator.start!
     end
 
-    ##
-    # Stop the scheduler gracefully.
-    #
-    # Signals the coordinator to stop after the current tick completes,
-    # then waits for the thread to finish.
-    #
-    # @param timeout [Integer] seconds to wait for graceful shutdown (default: 30)
-    # @return [Boolean] true if stopped successfully
-    #
-    # @example
-    #   Kaal.stop!
-    # @example
-    #   Kaal.stop!(timeout: 60)
     def stop!(timeout: 30)
       coordinator.stop!(timeout: timeout)
     end
 
-    ##
-    # Check if the scheduler is currently running.
-    #
-    # @return [Boolean] true if running, false otherwise
-    #
-    # @example
-    #   if Kaal.running?
-    #     puts "Scheduler is active"
-    #   end
     def running?
       coordinator.running?
     end
 
-    ##
-    # Restart the scheduler (stop then start).
-    #
-    # @return [Thread] the started thread
-    #
-    # @example
-    #   Kaal.restart!
     def restart!
       coordinator.restart!
     end
 
-    ##
-    # Execute a single scheduler tick manually.
-    #
-    # This is useful for testing and Rake tasks that want to trigger
-    # the scheduler without running the background loop.
-    #
-    # @return [void]
-    #
-    # @example
-    #   Kaal.tick!
     def tick!
       coordinator.tick!
     end
 
-    ##
-    # Generate an idempotency key for a cron job and yield to a block.
-    #
-    # Useful for advanced use cases where you need to generate an idempotency key
-    # outside of the normal enqueue flow, or for internal utilities.
-    #
-    # @param key [String] the cron job key
-    # @param fire_time [Time] the fire time
-    # @yield [String] yields the generated idempotency key
-    # @return [Object] the result of the block
-    #
-    # @raise [ArgumentError] if no block is provided
-    #
-    # @example
-    #   Kaal.with_idempotency('reports:daily', Time.current) do |idempotency_key|
-    #     MyJob.perform_later(key: idempotency_key)
-    #   end
     def with_idempotency(key, fire_time)
       raise ArgumentError, 'block required' unless block_given?
 
-      idempotency_key = IdempotencyKeyGenerator.call(key, fire_time, configuration: configuration)
-      yield(idempotency_key)
-    end
-
-    ##
-    # Check if a cron job has already been dispatched for a given fire time.
-    #
-    # Useful for implementing deduplication logic to prevent duplicate job enqueues.
-    # Returns true if dispatch logging is enabled and the job was previously dispatched,
-    # returns false if not found or dispatch logging is disabled.
-    #
-    # Safe to call from enqueue callbacks - will return false on any error (e.g., backend
-    # misconfiguration or temporary failure), log via configuration.logger, and never raise.
-    #
-    # @param key [String] the cron job key
-    # @param fire_time [Time] the fire time to check
-    # @return [Boolean] true if dispatch exists, false otherwise (never raises)
-    #
-    # @example
-    #   Kaal.dispatched?('reports:daily', Time.current)
-    #   # => true if already dispatched, false otherwise
-    def dispatched?(key, fire_time)
-      adapter = configuration.backend
-      return false if adapter.nil? || !adapter.respond_to?(:dispatch_registry)
-
-      registry = adapter.dispatch_registry
-      return false if registry.nil?
-
-      registry.dispatched?(key, fire_time)
-    rescue StandardError => e
-      configuration.logger&.warn("Error checking dispatch status for #{key}: #{e.message}")
-      false
-    end
-
-    ##
-    # Get the dispatch log registry for querying dispatch history.
-    #
-    # Returns the underlying dispatch registry engine which allows querying
-    # dispatch records. The specific methods available depend on the adapter type:
-    #
-    # **Common methods (all adapters):**
-    # - `find_dispatch(key, fire_time)` - Find a specific dispatch record
-    # - `dispatched?(key, fire_time)` - Check if a dispatch exists
-    #
-    # **Database adapter specific methods:**
-    # - `find_by_key(key)` - Find all dispatches for a job key
-    # - `find_by_node(node_id)` - Find all dispatches from a node, ordered by fire_time
-    # - `find_by_status(status)` - Find dispatches by status ('dispatched', 'failed', etc.)
-    # - `cleanup(recovery_window: 86400)` - Delete dispatch records older than window
-    #
-    # **Redis adapter:**
-    # - Uses automatic TTL expiration (no cleanup needed)
-    #
-    # **Memory adapter (development/testing):**
-    # - `clear()` - Clear all stored records
-    # - `size()` - Get count of stored records
-    #
-    # Safe for production diagnostics - will return nil on any error (e.g., backend
-    # misconfiguration or temporary failure), log via configuration.logger, and never raise.
-    #
-    # @return [Dispatch::Registry, nil] the dispatch registry instance, or nil if adapter doesn't support it or on error
-    #
-    # @example Query dispatches with database adapter
-    #   registry = Kaal.dispatch_log_registry
-    #   # Find all dispatches for a job
-    #   registry.find_by_key('reports:daily')
-    #   # Find failed attempts
-    #   registry.find_by_status('failed')
-    #   # Clean up old records (over 30 days old)
-    #   registry.cleanup(recovery_window: 30 * 24 * 60 * 60)
-    #
-    # @example Query dispatches with memory adapter
-    #   registry = Kaal.dispatch_log_registry
-    #   record = registry.find_dispatch('reports:daily', Time.current)
-    #   total = registry.size
-    #   registry.clear
-    def dispatch_log_registry
-      adapter = configuration.backend
-      return nil if adapter.nil? || !adapter.respond_to?(:dispatch_registry)
-
-      registry = adapter.dispatch_registry
-      return nil if registry.nil?
+      yield(IdempotencyKeyGenerator.call(key, fire_time, configuration: configuration))
+    end
 
-      registry
-    rescue StandardError => e
-      configuration.logger&.warn("Error accessing dispatch registry: #{e.message}")
-      nil
+    def dispatched?(key, fire_time)
+      dispatch_registry_accessor.dispatched?(key, fire_time)
     end
 
-    ##
-    # Configuration accessors for convenience.
-    def tick_interval
-      configuration.tick_interval
+    def dispatch_log_registry
+      dispatch_registry_accessor.registry
     end
 
+    def tick_interval = configuration.tick_interval
+    def window_lookback = configuration.window_lookback
+    def window_lookahead = configuration.window_lookahead
+    def lease_ttl = configuration.lease_ttl
+    def namespace = configuration.namespace
+    def backend = configuration.backend
+    def logger = configuration.logger
+    def time_zone = configuration.time_zone
+
     def tick_interval=(value)
       configuration.tick_interval = value
     end
 
-    def window_lookback
-      configuration.window_lookback
-    end
-
     def window_lookback=(value)
       configuration.window_lookback = value
     end
 
-    def window_lookahead
-      configuration.window_lookahead
-    end
-
     def window_lookahead=(value)
       configuration.window_lookahead = value
     end
 
-    def lease_ttl
-      configuration.lease_ttl
-    end
-
     def lease_ttl=(value)
       configuration.lease_ttl = value
     end
 
-    def namespace
-      configuration.namespace
-    end
-
     def namespace=(value)
       configuration.namespace = value
     end
 
-    def backend
-      configuration.backend
-    end
-
     def backend=(value)
       configuration.backend = value
     end
 
-    ##
-    # Definition registry access.
-    #
-    # Uses backend-provided definition registry when available, otherwise a
-    # process-local in-memory fallback.
-    #
-    # @return [Kaal::Definition::Registry]
-    def definition_registry
-      configured_backend = configuration.backend
-      registry = configured_backend&.definition_registry
-      return registry if registry
-
-      @definition_registry ||= Definition::MemoryEngine.new
-    rescue NoMethodError
-      @definition_registry ||= Definition::MemoryEngine.new
-    end
-
-    def logger
-      configuration.logger
-    end
-
     def logger=(value)
       configuration.logger = value
     end
 
-    def time_zone
-      configuration.time_zone
-    end
-
     def time_zone=(value)
       configuration.time_zone = value
     end
 
+    def definition_registry
+      definitions_registry_accessor.call
+    end
+
     def validate
       configuration.validate
     end
@@ -529,43 +199,53 @@ module Kaal
       configuration.validate!
     end
 
-    ##
-    # Validate a cron expression.
-    #
-    # @param expression [String] cron expression
-    # @return [Boolean] true if valid, false otherwise
     def valid?(expression)
       CronUtils.valid?(expression)
     end
 
-    ##
-    # Simplify a cron expression to a predefined macro when possible.
-    #
-    # @param expression [String] cron expression
-    # @return [String] simplified expression or canonical input
-    # @raise [ArgumentError] when expression is invalid
     def simplify(expression)
       CronUtils.simplify(expression)
     end
 
-    ##
-    # Lint a cron expression and return warnings/errors.
-    #
-    # @param expression [String] cron expression
-    # @return [Array<String>] lint warnings/errors
     def lint(expression)
       CronUtils.lint(expression)
     end
 
-    ##
-    # Convert a cron expression to a human-friendly phrase.
-    #
-    # @param expression [String] cron expression
-    # @param locale [Symbol, String, nil] locale override (defaults to current I18n.locale)
-    # @return [String] localized phrase
-    # @raise [ArgumentError] when expression is invalid
     def to_human(expression, locale: nil)
       CronHumanizer.to_human(expression, locale: locale)
     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
+
+    def registration_service
+      @registration_service ||= Definitions::RegistrationService.new(
+        configuration: configuration,
+        definition_registry: definition_registry,
+        registry: registry
+      )
+    end
+
+    def definitions_registry_accessor
+      @definitions_registry_accessor ||= Definitions::RegistryAccessor.new(
+        configuration: configuration,
+        fallback_registry_provider: lambda {
+          @definition_registry ||= Definition::MemoryEngine.new
+        }
+      )
+    end
+
+    def dispatch_registry_accessor
+      @dispatch_registry_accessor ||= Backend::DispatchRegistryAccessor.new(configuration: configuration)
+    end
   end
 end