kaal 0.3.0 → 0.5.0

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

@@ -0,0 +1,89 @@
+# 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/delayed_job/mysql_version_support'
+
+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
+        UNSET_SKIP_LOCKED_SUPPORT = Object.new.freeze
+
+        def initialize(connection = nil, dispatch_registry: nil, definition_registry: nil, namespace: nil,
+                       use_skip_locked: UNSET_SKIP_LOCKED_SUPPORT)
+          super()
+          ConnectionSupport.configure!(connection)
+          @dispatch_registry = dispatch_registry
+          @definition_registry = definition_registry
+          @namespace = namespace
+          @use_skip_locked = use_skip_locked
+        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(use_skip_locked: supports_skip_locked?)
+        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)
+          sanitized_sql = if binds.empty?
+                            sql
+                          else
+                            BaseRecord.send(:sanitize_sql_array, [sql, *binds])
+                          end
+          result = BaseRecord.connection.exec_query(sanitized_sql)
+          result.first.values.first
+        end
+
+        def resolved_namespace
+          @namespace || Kaal.configuration.namespace
+        end
+
+        def supports_skip_locked?
+          return @use_skip_locked unless @use_skip_locked.equal?(UNSET_SKIP_LOCKED_SUPPORT)
+
+          version_string = scalar('SELECT VERSION() AS version')
+          Kaal::DelayedJob::MySQLVersionSupport.skip_locked_supported?(version_string)
+        end
+      end
+    end
+  end
+end

data/lib/kaal/internal/active_record/postgres_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 '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 delayed_store
+          @delayed_store ||= DelayedJobRegistry.new(use_skip_locked: true)
+        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,19 @@
+# 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/delayed_job_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/delayed_job_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,79 @@
+# 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/delayed_job/database_engine'
+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 delayed_store
+          @delayed_store ||= Kaal::DelayedJob::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,83 @@
+# 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/delayed_job/mysql_version_support'
+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
+        UNSET_SKIP_LOCKED_SUPPORT = Object.new.freeze
+
+        def initialize(database, namespace: nil, use_skip_locked: UNSET_SKIP_LOCKED_SUPPORT)
+          super()
+          @database = Kaal::Persistence::Database.new(database)
+          @namespace = namespace
+          @use_skip_locked = use_skip_locked
+        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 delayed_store
+          @delayed_store ||= Kaal::DelayedJob::DatabaseEngine.new(database: @database.connection, use_skip_locked: supports_skip_locked?)
+        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
+
+        def supports_skip_locked?
+          return @use_skip_locked unless @use_skip_locked.equal?(UNSET_SKIP_LOCKED_SUPPORT)
+
+          version_string = scalar('SELECT VERSION() AS version')
+          Kaal::DelayedJob::MySQLVersionSupport.skip_locked_supported?(version_string)
+        end
+      end
+    end
+  end
+end

data/lib/kaal/internal/sequel/postgres_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'
+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 delayed_store
+          @delayed_store ||= Kaal::DelayedJob::DatabaseEngine.new(database: @database.connection, use_skip_locked: true)
+        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

data/lib/kaal/internal/sequel.rb

@@ -0,0 +1,13 @@
+# 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/sequel/database_backend'
+require 'kaal/internal/sequel/postgres_backend'
+require 'kaal/internal/sequel/mysql_backend'
+require 'kaal/definition/database_engine'
+require 'kaal/delayed_job/database_engine'
+require 'kaal/dispatch/database_engine'
+require 'kaal/persistence/database'

data/lib/kaal/job_dispatcher.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
+  # Shared job-class resolution and dispatch rules used by recurring and delayed jobs.
+  module JobDispatcher
+    module_function
+
+    def resolve_job_class(job_class_name:, key:, queue: nil, apply_delayed_job_allow_list: true)
+      job_class = normalize_job_class(job_class_name, key, apply_delayed_job_allow_list:)
+      validate_dispatch_interface(job_class, key, queue)
+    end
+
+    def normalized_job_class_name(job_class_name:, key:, apply_delayed_job_allow_list: true)
+      normalized_job_class_name = normalize_job_class_name(job_class_name)
+      raise SchedulerConfigError, "Job class cannot be blank for key '#{key}'" if normalized_job_class_name.empty?
+
+      return normalized_job_class_name unless apply_delayed_job_allow_list
+
+      validate_allowed_job_class_name!(job_class_name: normalized_job_class_name, key:)
+      normalized_job_class_name
+    end
+
+    def dispatch(job_class:, queue:, args:, key: nil)
+      job_class_name = job_class.name
+      scheduler_context = key ? " for scheduler job '#{key}'" : ''
+
+      if queue && !job_class.respond_to?(:set)
+        raise SchedulerConfigError,
+              "job_class '#{job_class_name}' must respond to .set to use queue #{queue.inspect}#{scheduler_context}"
+      end
+
+      if queue
+        job_class.set(queue: queue).perform_later(*args)
+      elsif job_class.respond_to?(:perform_later)
+        job_class.perform_later(*args)
+      elsif job_class.respond_to?(:perform)
+        job_class.perform(*args)
+      else
+        raise SchedulerConfigError,
+              "job_class '#{job_class_name}' must respond to .perform, .perform_later, or .set(...).perform_later#{scheduler_context}"
+      end
+    end
+
+    def active_job_dispatch?(job_class, queue)
+      (queue && job_class.respond_to?(:set)) || job_class.respond_to?(:perform_later)
+    end
+
+    def normalize_job_class_name(job_class)
+      case job_class
+      when Module
+        job_class.name.to_s.strip
+      else
+        job_class.to_s.strip
+      end
+    end
+
+    def normalize_job_class(job_class_name, key, apply_delayed_job_allow_list: true)
+      normalized_job_class_name = normalized_job_class_name(
+        job_class_name:,
+        key:,
+        apply_delayed_job_allow_list:
+      )
+
+      return job_class_name if job_class_name.is_a?(Module)
+
+      job_class = begin
+        Kaal::Support::HashTools.constantize(normalized_job_class_name)
+      rescue NameError
+        nil
+      end
+
+      return job_class if job_class
+
+      raise SchedulerConfigError, "Unknown job_class #{normalized_job_class_name.inspect} for key '#{key}'"
+    end
+    private_class_method :normalize_job_class
+
+    def validate_allowed_job_class_name!(job_class_name:, key:)
+      allowed_prefixes = Array(Kaal.configuration.delayed_job_allowed_class_prefixes)
+      return if allowed_prefixes.empty?
+      return if allowed_prefixes.any? { |prefix| job_class_name.start_with?(prefix) }
+
+      raise SchedulerConfigError,
+            "job_class '#{job_class_name}' for key '#{key}' is not allowed by delayed_job_allowed_class_prefixes"
+    end
+    private_class_method :validate_allowed_job_class_name!
+
+    def validate_dispatch_interface(job_class, key, queue)
+      queue_present = !queue.nil?
+      no_queue = !queue_present
+      supports_set = job_class.respond_to?(:set)
+      supports_perform_later = job_class.respond_to?(:perform_later)
+      supports_perform = job_class.respond_to?(:perform)
+
+      return job_class if queue_present && supports_set
+      return job_class if no_queue && supports_perform_later
+      return job_class if no_queue && supports_perform
+
+      raise SchedulerConfigError,
+            "job_class '#{job_class.name}' for key '#{key}' must respond to .perform, .perform_later, or .set(...).perform_later"
+    end
+    private_class_method :validate_dispatch_interface
+  end
+end

data/lib/kaal/persistence/database.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
+  module Persistence
+    # Thin wrapper around a Sequel connection to keep table access consistent.
+    class Database
+      attr_reader :connection
+
+      def initialize(connection)
+        Kaal::Sequel.require_sequel!
+        @connection = if connection.is_a?(::Sequel::Database)
+                        connection
+                      else
+                        ::Sequel.connect(connection)
+                      end
+      end
+
+      def definitions_dataset
+        connection[:kaal_definitions]
+      end
+
+      def dispatches_dataset
+        connection[:kaal_dispatches]
+      end
+
+      def locks_dataset
+        connection[:kaal_locks]
+      end
+
+      def delayed_jobs_dataset
+        connection[:kaal_delayed_jobs]
+      end
+    end
+  end
+end