kaal 0.3.0 → 0.5.0

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,78 @@
+# 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'
+require 'kaal/internal/active_record/delayed_job_registry'
+
+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 delayed_store
+          @delayed_store ||= DelayedJobRegistry.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/delayed_job_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 delayed jobs.
+      class DelayedJobRecord < BaseRecord
+        self.table_name = 'kaal_delayed_jobs'
+      end
+    end
+  end
+end

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

@@ -0,0 +1,119 @@
+# 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/delayed_job/registry'
+
+module Kaal
+  module Internal
+    module ActiveRecord
+      # Active Record-backed store for delayed jobs.
+      class DelayedJobRegistry < Kaal::DelayedJob::Registry
+        def initialize(connection: nil, model: DelayedJobRecord, use_skip_locked: false)
+          super()
+          ConnectionSupport.configure!(connection)
+          @model = model
+          @use_skip_locked = use_skip_locked
+        end
+
+        def enqueue(job_id:, run_at:, job_class:, args:, queue: nil, connection: nil)
+          now = Time.now.utc
+          attributes = {
+            job_id: job_id,
+            run_at: run_at,
+            job_class: job_class,
+            args: JSON.generate(args),
+            queue: queue,
+            created_at: now
+          }
+
+          if connection
+            insert_with_connection(connection, attributes)
+          else
+            @model.create!(attributes)
+          end
+
+          self.class.normalize(@model.new(attributes))
+        rescue ::ActiveRecord::RecordNotUnique
+          raise Kaal::DelayedJob::DuplicateJobError, "Delayed job #{job_id.inspect} already exists"
+        end
+
+        def pop_due(now:, limit:)
+          return pop_due_with_skip_locked(now:, limit:) if @use_skip_locked
+
+          pop_due_with_delete_confirmation(now:, limit:)
+        end
+
+        private
+
+        def pop_due_with_skip_locked(now:, limit:)
+          @model.transaction do
+            due_records = @model.where('run_at <= ?', now).order(:run_at, :job_id).lock('FOR UPDATE SKIP LOCKED').limit(limit).to_a
+            job_ids = due_records.map(&:job_id)
+            @model.where(job_id: job_ids).delete_all unless job_ids.empty?
+            due_records.filter_map { |record| self.class.normalize(record) }
+          end
+        end
+
+        def pop_due_with_delete_confirmation(now:, limit:)
+          @model.transaction do
+            @model.where('run_at <= ?', now).order(:run_at, :job_id).limit(limit).each_with_object([]) do |record, jobs|
+              normalized_job = self.class.normalize(record)
+              jobs << normalized_job if @model.where(job_id: record.job_id).delete_all.positive? && normalized_job
+            end
+          end
+        end
+
+        public
+
+        def find_job(job_id)
+          self.class.normalize(@model.find_by(job_id: job_id))
+        end
+
+        def all_jobs
+          @model.order(:run_at, :job_id).filter_map { |record| self.class.normalize(record) }
+        end
+
+        def claim_strategy
+          @use_skip_locked ? :skip_locked : :delete_confirmation
+        end
+
+        def self.normalize(record)
+          return nil unless record
+
+          {
+            job_id: record.job_id,
+            run_at: record.run_at,
+            job_class: record.job_class,
+            args: parse_args(record.args),
+            queue: record.queue,
+            created_at: record.created_at
+          }
+        rescue JSON::ParserError
+          nil
+        end
+
+        private
+
+        def insert_with_connection(connection, attributes)
+          table_name = @model.table_name
+          columns = attributes.keys
+          quoted_pairs = columns.map do |column|
+            [connection.quote_column_name(column), connection.quote(attributes.fetch(column))]
+          end
+          quoted_columns = quoted_pairs.map(&:first).join(', ')
+          quoted_values = quoted_pairs.map(&:last).join(', ')
+          connection.execute("INSERT INTO #{connection.quote_table_name(table_name)} (#{quoted_columns}) VALUES (#{quoted_values})")
+        end
+
+        def self.parse_args(args_payload)
+          JSON.parse(args_payload || '[]')
+        end
+        private_class_method :parse_args
+      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

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

@@ -0,0 +1,138 @@
+# 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
+      # Rails migration templates for Active Record-backed Kaal tables.
+      module MigrationTemplates
+        module_function
+
+        def for_backend(backend)
+          case backend.to_s
+          when 'sqlite'
+            {
+              '001_create_kaal_dispatches.rb' => dispatches_template,
+              '002_create_kaal_locks.rb' => locks_template,
+              '003_create_kaal_definitions.rb' => definitions_template('sqlite'),
+              '004_create_kaal_delayed_jobs.rb' => delayed_jobs_template('sqlite')
+            }
+          when 'postgres'
+            {
+              '001_create_kaal_dispatches.rb' => dispatches_template,
+              '002_create_kaal_definitions.rb' => definitions_template('postgres'),
+              '003_create_kaal_delayed_jobs.rb' => delayed_jobs_template('postgres')
+            }
+          when 'mysql'
+            {
+              '001_create_kaal_dispatches.rb' => dispatches_template,
+              '002_create_kaal_definitions.rb' => definitions_template('mysql'),
+              '003_create_kaal_delayed_jobs.rb' => delayed_jobs_template('mysql')
+            }
+          else
+            {}
+          end
+        end
+
+        def dispatches_template
+          <<~RUBY
+            class CreateKaalDispatches < ActiveRecord::Migration[7.1]
+              def change
+                create_table :kaal_dispatches do |t|
+                  t.string :key, null: false
+                  t.datetime :fire_time, null: false
+                  t.datetime :dispatched_at, null: false
+                  t.string :node_id, null: false
+                  t.string :status, null: false, default: 'dispatched', limit: 50
+                end
+
+                add_index :kaal_dispatches, [:key, :fire_time], unique: true
+                add_index :kaal_dispatches, :key
+                add_index :kaal_dispatches, :node_id
+                add_index :kaal_dispatches, :status
+                add_index :kaal_dispatches, :fire_time
+              end
+            end
+          RUBY
+        end
+
+        def locks_template
+          <<~RUBY
+            class CreateKaalLocks < ActiveRecord::Migration[7.1]
+              def change
+                create_table :kaal_locks do |t|
+                  t.string :key, null: false
+                  t.datetime :acquired_at, null: false
+                  t.datetime :expires_at, null: false
+                end
+
+                add_index :kaal_locks, :key, unique: true
+                add_index :kaal_locks, :expires_at
+              end
+            end
+          RUBY
+        end
+
+        def definitions_template(backend)
+          metadata_definition =
+            if backend == 'mysql'
+              't.text :metadata, null: false'
+            else
+              "t.text :metadata, null: false, default: '{}'"
+            end
+
+          <<~RUBY
+            class CreateKaalDefinitions < ActiveRecord::Migration[7.1]
+              def change
+                create_table :kaal_definitions do |t|
+                  t.string :key, null: false
+                  t.string :cron, null: false
+                  t.boolean :enabled, null: false, default: true
+                  t.string :source, null: false
+                  #{metadata_definition}
+                  t.datetime :disabled_at
+                  t.datetime :created_at, null: false
+                  t.datetime :updated_at, null: false
+                end
+
+                add_index :kaal_definitions, :key, unique: true
+                add_index :kaal_definitions, :enabled
+                add_index :kaal_definitions, :source
+              end
+            end
+          RUBY
+        end
+
+        def delayed_jobs_template(backend)
+          args_definition =
+            if backend == 'mysql'
+              't.text :args, null: false'
+            else
+              "t.text :args, null: false, default: '[]'"
+            end
+
+          <<~RUBY
+            class CreateKaalDelayedJobs < ActiveRecord::Migration[7.1]
+              def change
+                create_table :kaal_delayed_jobs do |t|
+                  t.string :job_id, null: false
+                  t.datetime :run_at, null: false
+                  t.string :job_class, null: false
+                  #{args_definition}
+                  t.string :queue
+                  t.datetime :created_at, null: false
+                end
+
+                add_index :kaal_delayed_jobs, :job_id, unique: true
+                add_index :kaal_delayed_jobs, :run_at
+              end
+            end
+          RUBY
+        end
+      end
+    end
+  end
+end