kaal 0.3.0 → 0.4.0

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

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

@@ -0,0 +1,108 @@
+# 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')
+            }
+          when 'postgres'
+            {
+              '001_create_kaal_dispatches.rb' => dispatches_template,
+              '002_create_kaal_definitions.rb' => definitions_template('postgres')
+            }
+          when 'mysql'
+            {
+              '001_create_kaal_dispatches.rb' => dispatches_template,
+              '002_create_kaal_definitions.rb' => definitions_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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# 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 'digest'
+
+module Kaal
+  module Internal
+    module ActiveRecord
+      # MySQL named-lock engine paired with Active Record registries.
+      class MySQLBackend < Kaal::Backend::Adapter
+        include Kaal::Backend::DispatchLogging
+
+        MAX_LOCK_NAME_LENGTH = 64
+
+        def initialize(connection = nil, dispatch_registry: nil, definition_registry: nil, namespace: nil)
+          super()
+          ConnectionSupport.configure!(connection)
+          @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)
+          acquired = scalar('SELECT GET_LOCK(?, 0) AS lock_result', self.class.normalize_lock_name(key)) == 1
+          log_dispatch_attempt(key) if acquired
+          acquired
+        rescue StandardError => e
+          raise Kaal::Backend::LockAdapterError, "MySQL acquire failed for #{key}: #{e.message}"
+        end
+
+        def release(key)
+          scalar('SELECT RELEASE_LOCK(?) AS lock_result', self.class.normalize_lock_name(key)) == 1
+        rescue StandardError => e
+          raise Kaal::Backend::LockAdapterError, "MySQL release failed for #{key}: #{e.message}"
+        end
+
+        def self.normalize_lock_name(key)
+          return key if key.length <= MAX_LOCK_NAME_LENGTH
+
+          digest = Digest::SHA256.hexdigest(key)
+          prefix_length = MAX_LOCK_NAME_LENGTH - 17
+          "#{key[0...prefix_length]}:#{digest[0...16]}"
+        end
+
+        private
+
+        def scalar(sql, value)
+          result = BaseRecord.connection.exec_query(
+            BaseRecord.send(:sanitize_sql_array, [sql, value])
+          )
+          result.first.values.first
+        end
+
+        def resolved_namespace
+          @namespace || Kaal.configuration.namespace
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# 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 'digest'
+
+module Kaal
+  module Internal
+    module ActiveRecord
+      # PostgreSQL advisory-lock engine paired with Active Record registries.
+      class PostgresBackend < Kaal::Backend::Adapter
+        include Kaal::Backend::DispatchLogging
+
+        SIGNED_64_MAX = 9_223_372_036_854_775_807
+        UNSIGNED_64_RANGE = 18_446_744_073_709_551_616
+
+        def initialize(connection = nil, dispatch_registry: nil, definition_registry: nil, namespace: nil)
+          super()
+          ConnectionSupport.configure!(connection)
+          @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)
+          acquired = scalar('SELECT pg_try_advisory_lock(?) AS acquired', self.class.calculate_lock_id(key)) == true
+          log_dispatch_attempt(key) if acquired
+          acquired
+        rescue StandardError => e
+          raise Kaal::Backend::LockAdapterError, "PostgreSQL acquire failed for #{key}: #{e.message}"
+        end
+
+        def release(key)
+          scalar('SELECT pg_advisory_unlock(?) AS released', self.class.calculate_lock_id(key)) == true
+        rescue StandardError => e
+          raise Kaal::Backend::LockAdapterError, "PostgreSQL release failed for #{key}: #{e.message}"
+        end
+
+        def self.calculate_lock_id(key)
+          hash = Digest::MD5.digest(key).unpack1('Q>')
+          hash > SIGNED_64_MAX ? hash - UNSIGNED_64_RANGE : hash
+        end
+
+        private
+
+        def scalar(sql, value)
+          result = BaseRecord.connection.exec_query(
+            BaseRecord.send(:sanitize_sql_array, [sql, value])
+          )
+          result.first.values.first
+        end
+
+        def resolved_namespace
+          @namespace || Kaal.configuration.namespace
+        end
+      end
+    end
+  end
+end

data/lib/kaal/internal/active_record.rb

@@ -0,0 +1,17 @@
+# 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/internal/active_record/base_record'
+require 'kaal/internal/active_record/connection_support'
+require 'kaal/internal/active_record/definition_record'
+require 'kaal/internal/active_record/dispatch_record'
+require 'kaal/internal/active_record/lock_record'
+require 'kaal/internal/active_record/definition_registry'
+require 'kaal/internal/active_record/dispatch_registry'
+require 'kaal/internal/active_record/database_backend'
+require 'kaal/internal/active_record/postgres_backend'
+require 'kaal/internal/active_record/mysql_backend'
+require 'kaal/internal/active_record/migration_templates'

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

@@ -0,0 +1,74 @@
+# 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/dispatch_logging'
+require 'kaal/persistence/database'
+
+module Kaal
+  module Internal
+    module Sequel
+      # Shared table-backed Sequel SQL engine used by the public SQLite backend.
+      class DatabaseBackend < Kaal::Backend::Adapter
+        include Kaal::Backend::DispatchLogging
+
+        def initialize(database, namespace: nil)
+          super()
+          @database = Kaal::Persistence::Database.new(database)
+          @namespace = namespace
+        end
+
+        def dispatch_registry
+          @dispatch_registry ||= Kaal::Dispatch::DatabaseEngine.new(database: @database.connection, namespace: resolved_namespace)
+        end
+
+        def definition_registry
+          @definition_registry ||= Kaal::Definition::DatabaseEngine.new(database: @database.connection)
+        end
+
+        def acquire(key, ttl)
+          now = Time.now.utc
+          expires_at = now + ttl
+
+          2.times do |attempt|
+            cleanup_expired_locks if attempt.positive?
+
+            begin
+              dataset.insert(key: key, acquired_at: now, expires_at: expires_at)
+              log_dispatch_attempt(key)
+              return true
+            rescue ::Sequel::UniqueConstraintViolation
+              next
+            end
+          end
+
+          false
+        rescue StandardError => e
+          raise Kaal::Backend::LockAdapterError, "Database acquire failed for #{key}: #{e.message}"
+        end
+
+        def release(key)
+          dataset.where(key: key).delete.positive?
+        rescue StandardError => e
+          raise Kaal::Backend::LockAdapterError, "Database release failed for #{key}: #{e.message}"
+        end
+
+        def cleanup_expired_locks
+          dataset.where { expires_at < Time.now.utc }.delete
+        end
+
+        private
+
+        def dataset
+          @database.locks_dataset
+        end
+
+        def resolved_namespace
+          @namespace || Kaal.configuration.namespace
+        end
+      end
+    end
+  end
+end

data/lib/kaal/internal/sequel/mysql_backend.rb

@@ -0,0 +1,69 @@
+# 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 'digest'
+require 'kaal/backend/dispatch_logging'
+require 'kaal/persistence/database'
+
+module Kaal
+  module Internal
+    module Sequel
+      # MySQL named-lock engine backed by Sequel.
+      class MySQLBackend < Kaal::Backend::Adapter
+        include Kaal::Backend::DispatchLogging
+
+        MAX_LOCK_NAME_LENGTH = 64
+
+        def initialize(database, namespace: nil)
+          super()
+          @database = Kaal::Persistence::Database.new(database)
+          @namespace = namespace
+        end
+
+        def dispatch_registry
+          @dispatch_registry ||= Kaal::Dispatch::DatabaseEngine.new(database: @database.connection, namespace: resolved_namespace)
+        end
+
+        def definition_registry
+          @definition_registry ||= Kaal::Definition::DatabaseEngine.new(database: @database.connection)
+        end
+
+        def acquire(key, _ttl)
+          acquired = scalar('SELECT GET_LOCK(?, 0) AS lock_result', self.class.normalize_lock_name(key)) == 1
+          log_dispatch_attempt(key) if acquired
+          acquired
+        rescue StandardError => e
+          raise Kaal::Backend::LockAdapterError, "MySQL acquire failed for #{key}: #{e.message}"
+        end
+
+        def release(key)
+          scalar('SELECT RELEASE_LOCK(?) AS lock_result', self.class.normalize_lock_name(key)) == 1
+        rescue StandardError => e
+          raise Kaal::Backend::LockAdapterError, "MySQL release failed for #{key}: #{e.message}"
+        end
+
+        def self.normalize_lock_name(key)
+          return key if key.length <= MAX_LOCK_NAME_LENGTH
+
+          digest = Digest::SHA256.hexdigest(key)
+          prefix_length = MAX_LOCK_NAME_LENGTH - 17
+          "#{key[0...prefix_length]}:#{digest[0...16]}"
+        end
+
+        private
+
+        def scalar(sql, *binds)
+          row = @database.connection.fetch(sql, *binds).first
+          row.values.first
+        end
+
+        def resolved_namespace
+          @namespace || Kaal.configuration.namespace
+        end
+      end
+    end
+  end
+end

data/lib/kaal/internal/sequel/postgres_backend.rb

@@ -0,0 +1,67 @@
+# 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 'digest'
+require 'kaal/backend/dispatch_logging'
+require 'kaal/persistence/database'
+
+module Kaal
+  module Internal
+    module Sequel
+      # PostgreSQL advisory-lock engine backed by Sequel.
+      class PostgresBackend < Kaal::Backend::Adapter
+        include Kaal::Backend::DispatchLogging
+
+        SIGNED_64_MAX = 9_223_372_036_854_775_807
+        UNSIGNED_64_RANGE = 18_446_744_073_709_551_616
+
+        def initialize(database, namespace: nil)
+          super()
+          @database = Kaal::Persistence::Database.new(database)
+          @namespace = namespace
+        end
+
+        def dispatch_registry
+          @dispatch_registry ||= Kaal::Dispatch::DatabaseEngine.new(database: @database.connection, namespace: resolved_namespace)
+        end
+
+        def definition_registry
+          @definition_registry ||= Kaal::Definition::DatabaseEngine.new(database: @database.connection)
+        end
+
+        def acquire(key, _ttl)
+          acquired = scalar('SELECT pg_try_advisory_lock(?) AS acquired', self.class.calculate_lock_id(key)) == true
+          log_dispatch_attempt(key) if acquired
+          acquired
+        rescue StandardError => e
+          raise Kaal::Backend::LockAdapterError, "PostgreSQL acquire failed for #{key}: #{e.message}"
+        end
+
+        def release(key)
+          scalar('SELECT pg_advisory_unlock(?) AS released', self.class.calculate_lock_id(key)) == true
+        rescue StandardError => e
+          raise Kaal::Backend::LockAdapterError, "PostgreSQL release failed for #{key}: #{e.message}"
+        end
+
+        def self.calculate_lock_id(key)
+          hash = Digest::MD5.digest(key).unpack1('Q>')
+          hash > SIGNED_64_MAX ? hash - UNSIGNED_64_RANGE : hash
+        end
+
+        private
+
+        def scalar(sql, *binds)
+          row = @database.connection.fetch(sql, *binds).first
+          row.values.first
+        end
+
+        def resolved_namespace
+          @namespace || Kaal.configuration.namespace
+        end
+      end
+    end
+  end
+end