kaal 0.2.1 → 0.4.0

data/lib/kaal/dispatch/database_engine.rb

@@ -4,90 +4,116 @@
 #
 # 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 'kaal/dispatch/registry'
+require 'kaal/persistence/database'
 
 module Kaal
   module Dispatch
-    ##
-    # Database-backed dispatch registry using ActiveRecord.
-    #
-    # Stores dispatch records in the database using the CronDispatch model.
-    # Provides persistent, queryable audit logs across all nodes.
-    #
-    # @example Usage
-    #   registry = Kaal::Dispatch::DatabaseEngine.new
-    #   registry.log_dispatch('daily_report', Time.current, 'node-1')
-    #   registry.dispatched?('daily_report', Time.current) # => true
+    # Sequel-backed dispatch registry stored in kaal_dispatches.
     class DatabaseEngine < Registry
-      ##
-      # Log a dispatch attempt in the database.
-      #
-      # @param key [String] the cron job key
-      # @param fire_time [Time] when the job was scheduled to fire
-      # @param node_id [String] identifier for the dispatching node
-      # @param status [String] dispatch status ('dispatched', 'failed', etc.)
-      # @return [Kaal::CronDispatch] the created dispatch record
-      # @raise [ActiveRecord::RecordInvalid] if the record is invalid
+      def initialize(database:, namespace: nil)
+        super()
+        @database = Kaal::Persistence::Database.new(database)
+        @namespace = namespace
+      end
+
       def log_dispatch(key, fire_time, node_id, status = 'dispatched')
-        ::Kaal::CronDispatch.create!(
-          key: key,
+        now = Time.now.utc
+        storage_key = namespaced_key(key)
+        attributes = {
+          key: storage_key,
           fire_time: fire_time,
-          dispatched_at: Time.current,
+          dispatched_at: now,
           node_id: node_id,
           status: status
-        )
+        }
+        dispatches_dataset = dataset
+        update_values = { dispatched_at: now, node_id: node_id, status: status }
+        begin
+          dispatches_dataset.insert_conflict(
+            target: %i[key fire_time],
+            update: update_values
+          ).insert(attributes)
+        rescue NoMethodError => e
+          raise unless e.name == :insert_conflict
+
+          begin
+            dispatches_dataset.insert(attributes)
+          rescue ::Sequel::UniqueConstraintViolation
+            dispatches_dataset.where(key: storage_key, fire_time: fire_time).update(update_values)
+          end
+        end
+
+        find_dispatch(key, fire_time)
       end
 
-      ##
-      # Find a dispatch record for a specific job and fire time.
-      #
-      # @param key [String] the cron job key
-      # @param fire_time [Time] when the job was scheduled to fire
-      # @return [Kaal::CronDispatch, nil] dispatch record or nil if not found
       def find_dispatch(key, fire_time)
-        ::Kaal::CronDispatch.find_by(key: key, fire_time: fire_time)
+        self.class.normalize_row(dataset.where(key: namespaced_key(key), fire_time: fire_time).first, namespace: @namespace)
       end
 
-      ##
-      # Find all dispatch records for a specific job key.
-      #
-      # @param key [String] the cron job key
-      # @return [ActiveRecord::Relation] collection of dispatch records
       def find_by_key(key)
-        ::Kaal::CronDispatch.where(key: key).order(fire_time: :desc)
+        query(key: namespaced_key(key))
       end
 
-      ##
-      # Find all dispatch records by node ID.
-      #
-      # @param node_id [String] the node identifier
-      # @return [ActiveRecord::Relation] collection of dispatch records
       def find_by_node(node_id)
-        ::Kaal::CronDispatch.where(node_id: node_id).order(fire_time: :desc)
+        query(node_id: node_id)
       end
 
-      ##
-      # Find all dispatch records with a specific status.
-      #
-      # @param status [String] the dispatch status
-      # @return [ActiveRecord::Relation] collection of dispatch records
       def find_by_status(status)
-        ::Kaal::CronDispatch.where(status: status).order(fire_time: :desc)
+        query(status: status)
       end
 
-      ##
-      # Delete old dispatch records older than the specified time.
-      #
-      # This cleanup prevents unbounded database growth by removing records
-      # that are older than the recovery window, making them irrelevant for
-      # future recovery operations.
-      #
-      # @param recovery_window [Integer] seconds to keep records for (e.g., 86400 for 24h)
-      # @return [Integer] number of records deleted
       def cleanup(recovery_window: 86_400)
-        cutoff_time = Time.current - recovery_window
-        ::Kaal::CronDispatch.where('fire_time < ?', cutoff_time).delete_all
+        cutoff_time = Time.now.utc - recovery_window
+        cleanup_dataset.where { fire_time < cutoff_time }.delete
+      end
+
+      def self.normalize_row(row, namespace: nil)
+        return nil unless row
+
+        {
+          key: strip_namespace(row[:key], namespace:),
+          fire_time: row[:fire_time],
+          dispatched_at: row[:dispatched_at],
+          node_id: row[:node_id],
+          status: row[:status]
+        }
+      end
+
+      def self.strip_namespace(key, namespace:)
+        return key if namespace.to_s.empty?
+
+        prefix = "#{namespace}:"
+        key.start_with?(prefix) ? key.delete_prefix(prefix) : key
+      end
+
+      private
+
+      def dataset
+        @database.dispatches_dataset
+      end
+
+      def namespaced_key(key)
+        return key if @namespace.to_s.empty?
+
+        "#{@namespace}:#{key}"
+      end
+
+      def query(filters)
+        query_dataset(filters).reverse_order(:fire_time).all.map { |row| self.class.normalize_row(row, namespace: @namespace) }
+      end
+
+      def query_dataset(filters)
+        relation = dataset.where(filters)
+        return relation if @namespace.to_s.empty? || filters.key?(:key)
+
+        relation.where(::Sequel.lit('key LIKE ?', "#{@namespace}:%"))
+      end
+
+      def cleanup_dataset
+        return dataset if @namespace.to_s.empty?
+
+        dataset.where(::Sequel.lit('key LIKE ?', "#{@namespace}:%"))
       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/internal/active_record/base_record.rb

@@ -0,0 +1,16 @@
+# 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 Internal
+    module ActiveRecord
+      # Shared abstract Active Record base class for Kaal tables.
+      class BaseRecord < ::ActiveRecord::Base
+        self.abstract_class = true
+      end
+    end
+  end
+end

data/lib/kaal/internal/active_record/connection_support.rb

@@ -0,0 +1,96 @@
+# 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 Internal
+    module ActiveRecord
+      # Establishes and reuses the Active Record connection for adapter models.
+      module ConnectionSupport
+        CONFIGURE_MUTEX = Mutex.new
+
+        module_function
+
+        def configure!(connection = nil)
+          return BaseRecord unless connection
+
+          CONFIGURE_MUTEX.synchronize do
+            current_config = current_connection_config
+            target_config = normalize_connection_config(connection)
+            return BaseRecord if configs_match?(current_config, target_config) && connection_active?
+
+            BaseRecord.establish_connection(connection)
+          end
+          BaseRecord
+        end
+
+        def normalize_connection_config(connection)
+          config = extract_connection_config(connection)
+          return connection unless config
+
+          config.each_with_object({}) do |(key, value), normalized|
+            normalized_key = key.to_sym
+            normalized[normalized_key] = normalize_connection_value(normalized_key, value)
+          end
+        end
+
+        def current_connection_config
+          db_config = BaseRecord.connection_db_config
+          normalize_connection_config(extract_connection_config(db_config))
+        rescue ::ActiveRecord::ConnectionNotEstablished
+          nil
+        end
+
+        def extract_connection_config(connection)
+          case connection
+          when Hash
+            connection
+          when String
+            { url: connection }
+          else
+            config = connection.configuration_hash
+            url = begin
+              connection.url
+            rescue NoMethodError
+              nil
+            end
+            url ? config.merge(url: url) : config
+          end
+        rescue NoMethodError
+          nil
+        end
+
+        def normalize_connection_value(key, value)
+          case key
+          when :adapter
+            value.to_s.downcase
+          when :port
+            integer_like?(value) ? value.to_i : value
+          else
+            value
+          end
+        end
+
+        def integer_like?(value)
+          value.is_a?(Integer) || value.to_s.match?(/\A\d+\z/)
+        end
+
+        def configs_match?(current_config, target_config)
+          return true if current_config == target_config
+
+          current_url = current_config.is_a?(Hash) ? current_config[:url] : nil
+          target_url = target_config.is_a?(Hash) ? target_config[:url] : nil
+          !!(current_url && target_url && current_url == target_url)
+        end
+
+        def connection_active?
+          BaseRecord.connection.active?
+        rescue ::ActiveRecord::ConnectionNotEstablished, StandardError
+          false
+        end
+      end
+    end
+  end
+end

data/lib/kaal/internal/active_record/database_backend.rb

@@ -0,0 +1,73 @@
+# 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/backend/adapter'
+require 'kaal/backend/dispatch_logging'
+
+module Kaal
+  module Internal
+    module ActiveRecord
+      # Table-backed lock engine used for SQLite-style Active Record storage.
+      class DatabaseBackend < Kaal::Backend::Adapter
+        include Kaal::Backend::DispatchLogging
+
+        def initialize(connection = nil, lock_model: LockRecord, dispatch_registry: nil, definition_registry: nil, namespace: nil)
+          super()
+          ConnectionSupport.configure!(connection)
+          @lock_model = lock_model
+          @dispatch_registry = dispatch_registry
+          @definition_registry = definition_registry
+          @namespace = namespace
+        end
+
+        def dispatch_registry
+          @dispatch_registry ||= DispatchRegistry.new(namespace: resolved_namespace)
+        end
+
+        def definition_registry
+          @definition_registry ||= DefinitionRegistry.new
+        end
+
+        def acquire(key, ttl)
+          now = Time.now.utc
+          expires_at = now + ttl
+
+          2.times do |attempt|
+            cleanup_expired_locks if attempt.positive?
+
+            begin
+              @lock_model.create!(key: key, acquired_at: now, expires_at: expires_at)
+              log_dispatch_attempt(key)
+              return true
+            rescue ::ActiveRecord::RecordNotUnique
+              next
+            end
+          end
+
+          false
+        rescue StandardError => e
+          raise Kaal::Backend::LockAdapterError, "Database acquire failed for #{key}: #{e.message}"
+        end
+
+        def release(key)
+          @lock_model.where(key: key).delete_all.positive?
+        rescue StandardError => e
+          raise Kaal::Backend::LockAdapterError, "Database release failed for #{key}: #{e.message}"
+        end
+
+        def cleanup_expired_locks
+          @lock_model.where(expires_at: ...Time.now.utc).delete_all
+        end
+
+        private
+
+        def resolved_namespace
+          @namespace || Kaal.configuration.namespace
+        end
+      end
+    end
+  end
+end

data/lib/kaal/internal/active_record/definition_record.rb

@@ -0,0 +1,16 @@
+# 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 Internal
+    module ActiveRecord
+      # Active Record model for persisted scheduler definitions.
+      class DefinitionRecord < BaseRecord
+        self.table_name = 'kaal_definitions'
+      end
+    end
+  end
+end

data/lib/kaal/internal/active_record/definition_registry.rb

@@ -0,0 +1,81 @@
+# 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'
+require 'kaal/definition/registry'
+require 'kaal/definition/persistence_helpers'
+
+module Kaal
+  module Internal
+    module ActiveRecord
+      # Active Record-backed registry for scheduler definitions.
+      class DefinitionRegistry < Kaal::Definition::Registry
+        def initialize(connection: nil, model: DefinitionRecord)
+          super()
+          ConnectionSupport.configure!(connection)
+          @model = model
+        end
+
+        def upsert_definition(key:, cron:, enabled: true, source: 'code', metadata: {})
+          record = @model.find_or_initialize_by(key: key)
+          existing = record.persisted? ? { enabled: record.enabled, disabled_at: record.disabled_at } : nil
+          now = Time.now.utc
+          record.cron = cron
+          record.enabled = enabled
+          record.source = source
+          record.metadata = JSON.generate(metadata || {})
+          record.created_at ||= now
+          record.updated_at = now
+          record.disabled_at = Kaal::Definition::PersistenceHelpers.disabled_at_for(existing, enabled, now)
+          record.save!
+          normalize(record)
+        end
+
+        def remove_definition(key)
+          record = @model.find_by(key: key)
+          return nil unless record
+
+          normalized = normalize(record)
+          record.destroy!
+          normalized
+        end
+
+        def find_definition(key)
+          normalize(@model.find_by(key: key))
+        end
+
+        def all_definitions
+          @model.order(:key).map { |record| normalize(record) }
+        end
+
+        def enabled_definitions
+          @model.where(enabled: true).order(:key).map { |record| normalize(record) }
+        end
+
+        private
+
+        def normalize(record)
+          return nil unless record
+
+          normalize_definition_record(record)
+        end
+
+        def normalize_definition_record(record)
+          {
+            key: record.key,
+            cron: record.cron,
+            enabled: record.enabled ? true : false,
+            source: record.source,
+            metadata: Kaal::Definition::PersistenceHelpers.parse_metadata(record.metadata),
+            created_at: record.created_at,
+            updated_at: record.updated_at,
+            disabled_at: record.disabled_at
+          }
+        end
+      end
+    end
+  end
+end

data/lib/kaal/internal/active_record/dispatch_record.rb

@@ -0,0 +1,16 @@
+# 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 Internal
+    module ActiveRecord
+      # Active Record model for persisted dispatch audit entries.
+      class DispatchRecord < BaseRecord
+        self.table_name = 'kaal_dispatches'
+      end
+    end
+  end
+end

data/lib/kaal/internal/active_record/dispatch_registry.rb

@@ -0,0 +1,100 @@
+# 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/dispatch/registry'
+
+module Kaal
+  module Internal
+    module ActiveRecord
+      # Active Record-backed registry for dispatch audit records.
+      class DispatchRegistry < Kaal::Dispatch::Registry
+        def initialize(connection: nil, model: DispatchRecord, namespace: nil)
+          super()
+          ConnectionSupport.configure!(connection)
+          @model = model
+          @namespace = namespace
+        end
+
+        def log_dispatch(key, fire_time, node_id, status = 'dispatched')
+          record = @model.find_or_initialize_by(key: namespaced_key(key), fire_time: fire_time)
+          record.dispatched_at = Time.now.utc
+          record.node_id = node_id
+          record.status = status
+          record.save!
+          normalize(record)
+        end
+
+        def find_dispatch(key, fire_time)
+          normalize(@model.find_by(key: namespaced_key(key), fire_time: fire_time))
+        end
+
+        def find_by_key(key)
+          query(key: namespaced_key(key))
+        end
+
+        def find_by_node(node_id)
+          query(node_id: node_id)
+        end
+
+        def find_by_status(status)
+          query(status: status)
+        end
+
+        def cleanup(recovery_window: 86_400)
+          cutoff_time = Time.now.utc - recovery_window
+          cleanup_scope.where(fire_time: ...cutoff_time).delete_all
+        end
+
+        private
+
+        def query(filters)
+          query_scope(filters).order(fire_time: :desc).map { |record| normalize(record) }
+        end
+
+        def namespaced_key(key)
+          "#{namespace_prefix}#{key}"
+        end
+
+        def normalize(record)
+          return nil unless record
+
+          {
+            key: strip_namespace(record.key),
+            fire_time: record.fire_time,
+            dispatched_at: record.dispatched_at,
+            node_id: record.node_id,
+            status: record.status
+          }
+        end
+
+        def strip_namespace(key)
+          key.delete_prefix(namespace_prefix)
+        end
+
+        def query_scope(filters)
+          relation = @model.where(filters)
+          return relation if filters.key?(:key)
+
+          namespace_scope(relation)
+        end
+
+        def cleanup_scope
+          namespace_scope(@model)
+        end
+
+        def namespace_scope(relation)
+          return relation if namespace_prefix.empty?
+
+          relation.where('key LIKE ?', "#{namespace_prefix}%")
+        end
+
+        def namespace_prefix
+          @namespace.to_s.empty? ? '' : "#{@namespace}:"
+        end
+      end
+    end
+  end
+end

data/lib/kaal/internal/active_record/lock_record.rb

@@ -0,0 +1,16 @@
+# 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 Internal
+    module ActiveRecord
+      # Active Record model for table-backed scheduler locks.
+      class LockRecord < BaseRecord
+        self.table_name = 'kaal_locks'
+      end
+    end
+  end
+end