kaal 0.2.1 → 0.3.0

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/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

data/lib/kaal/dispatch/memory_engine.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 'registry'
 
 module Kaal
@@ -17,8 +16,8 @@ module Kaal
     #
     # @example Usage
     #   registry = Kaal::Dispatch::MemoryEngine.new
-    #   registry.log_dispatch('daily_report', Time.current, 'node-1')
-    #   registry.dispatched?('daily_report', Time.current) # => true
+    #   registry.log_dispatch('daily_report', Time.now.utc, 'node-1')
+    #   registry.dispatched?('daily_report', Time.now.utc) # => true
     class MemoryEngine < Registry
       ##
       # Initialize a new in-memory registry.
@@ -42,7 +41,7 @@ module Kaal
           @dispatches[storage_key] = {
             key: key,
             fire_time: fire_time,
-            dispatched_at: Time.current,
+            dispatched_at: Time.now.utc,
             node_id: node_id,
             status: status
           }

data/lib/kaal/dispatch/redis_engine.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 'json'
 require_relative 'registry'
 
@@ -19,7 +18,7 @@ module Kaal
     # @example Usage
     #   redis = Redis.new(url: ENV['REDIS_URL'])
     #   registry = Kaal::Dispatch::RedisEngine.new(redis, namespace: 'myapp')
-    #   registry.log_dispatch('daily_report', Time.current, 'node-1')
+    #   registry.log_dispatch('daily_report', Time.now.utc, 'node-1')
     class RedisEngine < Registry
       # Default TTL for dispatch records (7 days in seconds)
       DEFAULT_TTL = 7 * 24 * 60 * 60
@@ -50,7 +49,7 @@ module Kaal
         record = {
           key: key,
           fire_time: fire_time.to_i,
-          dispatched_at: Time.current.to_i,
+          dispatched_at: Time.now.utc.to_i,
           node_id: node_id,
           status: status
         }

data/lib/kaal/dispatch/registry.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
   module Dispatch
     ##

data/lib/kaal/register_conflict_support.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
   # Register conflict handling helpers shared by Kaal singleton methods.
   module RegisterConflictSupport

data/lib/kaal/registry.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
   ##
   # Thread-safe registry for storing and managing registered cron jobs.

data/lib/kaal/runtime/runtime_context.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.
+require 'pathname'
+
+module Kaal
+  # Resolves environment and path information for plain-Ruby runtime loading.
+  class RuntimeContext
+    DEFAULT_ENVIRONMENT_NAME = 'development'
+    ENVIRONMENT_KEYS = %w[KAAL_ENV RAILS_ENV APP_ENV RACK_ENV].freeze
+
+    attr_reader :environment_name, :root_path
+
+    def self.default(env: ENV, root_path: Dir.pwd)
+      new(root_path: root_path, environment_name: environment_name_from(env))
+    end
+
+    def self.environment_name_from(env)
+      ENVIRONMENT_KEYS.each do |key|
+        value = env[key].to_s.strip
+        return value unless value.empty?
+      end
+
+      DEFAULT_ENVIRONMENT_NAME
+    end
+
+    def initialize(root_path:, environment_name:)
+      @root_path = Pathname.new(root_path)
+      @environment_name = environment_name.to_s
+    end
+
+    def resolve_path(path)
+      return path.to_s if Pathname.new(path).absolute?
+
+      root_path.join(path).to_s
+    end
+  end
+end

data/lib/kaal/runtime/scheduler_boot_loader.rb

@@ -0,0 +1,52 @@
+# 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
+  # Loads scheduler.yml at framework boot time while respecting missing-file policy.
+  class SchedulerBootLoader
+    def initialize(configuration_provider:, logger:, runtime_context:, load_scheduler_file:)
+      @configuration_provider = configuration_provider
+      @logger = logger
+      @runtime_context = runtime_context
+      @load_scheduler_file = load_scheduler_file
+    end
+
+    def load_on_boot
+      load_on_boot!
+    end
+
+    def load_on_boot!
+      configuration = fetch_configuration
+      return unless configuration
+
+      return load_scheduler_file if configuration.scheduler_missing_file_policy == :error
+
+      scheduler_path = configuration.scheduler_config_path.to_s.strip
+      return if scheduler_path.empty?
+
+      absolute_path = @runtime_context.resolve_path(scheduler_path)
+      unless File.exist?(absolute_path)
+        @logger&.warn("Scheduler file not found at #{absolute_path}")
+        return
+      end
+
+      load_scheduler_file
+    end
+
+    private
+
+    def load_scheduler_file
+      @load_scheduler_file.call
+    end
+
+    def fetch_configuration
+      @configuration_provider.call
+    rescue NameError => e
+      @logger&.debug("Skipping scheduler file boot load due to configuration error: #{e.message}")
+      nil
+    end
+  end
+end

data/lib/kaal/runtime/signal_handler_chain.rb

@@ -0,0 +1,42 @@
+# 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
+  # Invokes a previously registered signal handler when it is safe to do so.
+  class SignalHandlerChain
+    RESERVED_COMMAND_HANDLERS = %w[DEFAULT IGNORE].freeze
+
+    def initialize(signal:, previous_handler:, logger:)
+      @signal = signal
+      @previous_handler = previous_handler
+      @logger = logger
+    end
+
+    def call(...)
+      return unless @previous_handler
+
+      case @previous_handler
+      when Proc, Method
+        invoke_callable(...)
+      when String
+        return if RESERVED_COMMAND_HANDLERS.include?(@previous_handler)
+
+        @logger&.debug("Previous #{@signal} handler was a command: #{@previous_handler}")
+      end
+    end
+
+    private
+
+    def invoke_callable(*args)
+      arity = @previous_handler.arity
+      return @previous_handler.call if arity.zero?
+
+      argument_length = args.length
+      argument_count = arity.negative? ? argument_length : [arity, argument_length].min
+      @previous_handler.call(*args.first(argument_count))
+    end
+  end
+end

data/lib/kaal/runtime/signal_handler_installer.rb

@@ -0,0 +1,39 @@
+# 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
+  # Installs signal handlers while preserving the previous handlers for chaining.
+  class SignalHandlerInstaller
+    SIGNALS = %w[TERM INT].freeze
+    IGNORE_HANDLER = 'IGNORE'
+
+    def initialize(signal_module: Signal)
+      @signal_module = signal_module
+    end
+
+    def install(signals: SIGNALS)
+      signals.each_with_object({}) do |signal, previous_handlers|
+        previous_handler = capture_previous_handler(signal)
+        @signal_module.trap(signal) { yield(signal, previous_handler) }
+        previous_handlers[signal] = previous_handler
+      end
+    end
+
+    private
+
+    def capture_previous_handler(signal)
+      previous_handler = @signal_module.trap(signal, IGNORE_HANDLER)
+      restore_previous_handler(signal, previous_handler)
+      previous_handler
+    end
+
+    def restore_previous_handler(signal, previous_handler)
+      return unless previous_handler && previous_handler != IGNORE_HANDLER
+
+      @signal_module.trap(signal, previous_handler)
+    end
+  end
+end

data/lib/kaal/runtime.rb

@@ -0,0 +1,20 @@
+# 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/runtime/runtime_context'
+require 'kaal/runtime/scheduler_boot_loader'
+require 'kaal/runtime/signal_handler_chain'
+require 'kaal/runtime/signal_handler_installer'
+
+module Kaal
+  # Runtime wiring and lifecycle helpers.
+  module Runtime
+    RuntimeContext = ::Kaal::RuntimeContext
+    SchedulerBootLoader = ::Kaal::SchedulerBootLoader
+    SignalHandlerChain = ::Kaal::SignalHandlerChain
+    SignalHandlerInstaller = ::Kaal::SignalHandlerInstaller
+  end
+end

data/lib/kaal/scheduler_file/hash_transform.rb

@@ -0,0 +1,22 @@
+# 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/support/hash_tools'
+
+module Kaal
+  # Shared deep hash key transformation helpers for scheduler payloads.
+  module SchedulerHashTransform
+    private
+
+    def stringify_keys(object)
+      Kaal::Support::HashTools.stringify_keys(object)
+    end
+
+    def symbolize_keys_deep(object)
+      Kaal::Support::HashTools.symbolize_keys(object)
+    end
+  end
+end

data/lib/kaal/scheduler_file/helper_bundle.rb

@@ -0,0 +1,28 @@
+# 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
+  class SchedulerFileLoader
+    # Exposes hash/placeholder helpers to extracted scheduler-file collaborators.
+    class HelperBundle
+      def initialize(loader:)
+        @loader = loader
+      end
+
+      def stringify_keys(payload)
+        @loader.send(:stringify_keys, payload)
+      end
+
+      def resolve_placeholders(value, context)
+        @loader.send(:resolve_placeholders, value, context)
+      end
+
+      def validate_placeholders(value, key:)
+        @loader.send(:validate_placeholders, value, key:)
+      end
+    end
+  end
+end