kaal 0.2.1 → 0.4.0

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

data/lib/kaal/internal/sequel.rb

@@ -0,0 +1,12 @@
+# 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/dispatch/database_engine'
+require 'kaal/persistence/database'

data/lib/kaal/persistence/database.rb

@@ -0,0 +1,35 @@
+# 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
+    end
+  end
+end

data/lib/kaal/persistence/migration_templates.rb

@@ -0,0 +1,97 @@
+# 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
+    # Sequel migration templates emitted by `kaal init`.
+    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
+          }
+        when 'postgres', 'mysql'
+          {
+            '001_create_kaal_dispatches.rb' => dispatches_template,
+            '002_create_kaal_definitions.rb' => definitions_template
+          }
+        else
+          {}
+        end
+      end
+
+      def dispatches_template
+        <<~RUBY
+          Sequel.migration do
+            change do
+              create_table?(:kaal_dispatches) do
+                primary_key :id
+                String :key, null: false
+                Time :fire_time, null: false
+                Time :dispatched_at, null: false
+                String :node_id, null: false
+                String :status, null: false, default: 'dispatched', size: 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
+          Sequel.migration do
+            change do
+              create_table?(:kaal_locks) do
+                primary_key :id
+                String :key, null: false
+                Time :acquired_at, null: false
+                Time :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
+        <<~RUBY
+          Sequel.migration do
+            change do
+              create_table?(:kaal_definitions) do
+                primary_key :id
+                String :key, null: false
+                String :cron, null: false
+                TrueClass :enabled, null: false, default: true
+                String :source, null: false
+                String :metadata, text: true, null: false, default: '{}'
+                Time :disabled_at
+                Time :created_at, null: false
+                Time :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

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.
@@ -21,9 +20,7 @@ module Kaal
 
     ##
     # Entry class representing a single registered cron job
-    # rubocop:disable Style/RedundantStructKeywordInit
     Entry = Struct.new(:key, :cron, :enqueue, keyword_init: true)
-    # rubocop:enable Style/RedundantStructKeywordInit
 
     ##
     # Initialize a new Registry instance.

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