kaal 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54a0eb1cebfc4adc18c4b4ed105d47bb26a84d3512fbce891243a356bca5715a
-  data.tar.gz: dd1fb18c3060c4688ea0f96c5628cd40001fb318b7745d411c46108fa06b45b3
+  metadata.gz: f078489fc2106826b98a1890f15dd5aad38a627ef9db230bd11db3785dc66f86
+  data.tar.gz: 10ec39fb62e2082d7a8191153af335950fb14d584c0ed33737298baaa2b2f270
 SHA512:
-  metadata.gz: fda7173306897889b750707be46778bfc0b4893ce87759f30f060a37879212eab2731316a31c875acdcf0e7aad9db1caddbc11e7c0b0b16e3707edbfd1b1eec3
-  data.tar.gz: a8d64f8ca728665167e8be7ad5e1e6a417066f6016ff2b838aa47cde5aa3369045b1ea2c3aaf326ce4b00cc94d0f519ebe464978660ad13cc29f6db90cf3c834
+  metadata.gz: 5be3591420c49e0149f58e6d76abdb3bfc7a7c10f2249754fb427f89e9ce414bad044d44fc17ed8016b4766182558a2a513598dcc212a0d899872f31007da19b
+  data.tar.gz: 60857c850fe9ca808fd198bcd8480ee63962bc1df5de69bab5953168aa7641f1a739c74d970c67b20a7f71d1858abe2a043ac004191b473a94aee7380cf8ce50

data/README.md

@@ -2,7 +2,7 @@
 
 Distributed cron scheduling for plain Ruby.
 
-`kaal` is the core engine gem. It owns scheduler/runtime behavior, the registry APIs, and the plain Ruby CLI. SQL persistence lives in adapter gems such as `kaal-sequel` and `kaal-activerecord`.
+`kaal` is the core engine gem. It owns scheduler/runtime behavior, the registry APIs, the plain Ruby CLI, and the optional SQL backend surfaces.
 
 ## Installation
 
@@ -29,11 +29,7 @@ Supported backends:
 - `memory`
 - `redis`
 
-If you want SQL persistence instead, add one of:
-
-- `kaal-sequel` for Sequel-backed SQL in plain Ruby
-- `kaal-activerecord` for Active Record-backed SQL in plain Ruby
-- `kaal-rails` for Rails
+If you want SQL persistence instead, add the runtime libraries your app uses, such as `sequel`, `activerecord`, `sqlite3`, `pg`, or `mysql2`, then configure one of the explicit `Kaal::Backend::*` SQL backends.
 
 ## Configuration
 
@@ -126,10 +122,11 @@ Kaal.register(
 Kaal.start!
 ```
 
-## Adapter Gems
+## SQL Backends
 
-Use adapter gems when you want persisted SQL registries:
+Use the explicit SQL backends when you want persisted registries:
 
-- `kaal-sequel` for Sequel-backed persistence
-- `kaal-activerecord` for Active Record-backed persistence
-- `kaal-rails` for Rails plugin integration over `kaal-activerecord`
+- `Kaal::Backend::SQLite`
+- `Kaal::Backend::Postgres`
+- `Kaal::Backend::MySQL`
+- `kaal-rails` for Rails-native install and auto-wiring

data/lib/kaal/active_record_support.rb

@@ -0,0 +1,82 @@
+# 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 'fileutils'
+
+module Kaal
+  # Active Record migration/install support for SQL-backed Kaal backends.
+  module ActiveRecord
+    module_function
+
+    def install_postgres_migration(target_dir:, migration_name: 'Create Kaal Postgres Backend')
+      install_migrations(target_dir:, backend: 'postgres', migration_name:)
+    end
+
+    def install_mysql_migration(target_dir:, migration_name: 'Create Kaal MySQL Backend')
+      install_migrations(target_dir:, backend: 'mysql', migration_name:)
+    end
+
+    def install_sqlite_migration(target_dir:, migration_name: 'Create Kaal SQLite Backend')
+      install_migrations(target_dir:, backend: 'sqlite', migration_name:)
+    end
+
+    def install_migrations(target_dir:, backend:, migration_name: nil, time_source: -> { Time.now.utc })
+      class_name = normalize_migration_name(migration_name, fallback: default_migration_class_for(backend))
+      base_path = File.expand_path(target_dir)
+      FileUtils.mkdir_p(base_path)
+      templates = Kaal::Internal::ActiveRecord::MigrationTemplates.for_backend(backend)
+
+      templates.map.with_index do |(_name, contents), index|
+        suffix = underscore(class_name)
+        suffix = "#{suffix}_#{migration_suffixes_for(backend).fetch(index)}" if templates.length > 1
+        path = File.expand_path("#{(time_source.call + index).strftime('%Y%m%d%H%M%S')}_#{suffix}.rb", base_path)
+        File.write(path, contents)
+        path
+      end
+    end
+
+    def require_activerecord!
+      require 'active_record'
+      require 'active_support/inflector'
+    rescue LoadError => e
+      raise LoadError,
+            "#{e.message}. Add `gem 'activerecord'` to your Gemfile to use Active Record-backed Kaal SQL support.",
+            cause: e
+    end
+
+    def normalize_migration_name(name, fallback:)
+      normalized = name.to_s.each_char.with_object(+'') do |char, buffer|
+        if alphanumeric?(char)
+          buffer << char
+        elsif !buffer.empty? && !buffer.end_with?(' ')
+          buffer << ' '
+        end
+      end.split.map!(&:capitalize).join
+      normalized.empty? ? fallback : normalized
+    end
+
+    def underscore(value)
+      require_activerecord!
+      ::ActiveSupport::Inflector.underscore(value)
+    end
+
+    def default_migration_class_for(backend)
+      "CreateKaal#{backend.capitalize}Backend"
+    end
+
+    def migration_suffixes_for(backend)
+      return %w[dispatches locks definitions] if backend.to_s == 'sqlite'
+
+      %w[dispatches definitions]
+    end
+
+    def alphanumeric?(char)
+      char.between?('a', 'z') ||
+        char.between?('A', 'Z') ||
+        char.between?('0', '9')
+    end
+  end
+end

data/lib/kaal/backend/mysql.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.
+module Kaal
+  module Backend
+    # MySQL-backed backend for either Sequel or Active Record persistence.
+    class MySQL < Adapter
+      def initialize(database: nil, connection: nil, namespace: nil, **)
+        super()
+        @engine = if database
+                    Kaal::Sequel.require_sequel!
+                    require 'kaal/internal/sequel'
+                    Kaal::Internal::Sequel::MySQLBackend.new(database, namespace:)
+                  else
+                    Kaal::ActiveRecord.require_activerecord!
+                    require 'kaal/internal/active_record'
+                    Kaal::Internal::ActiveRecord::MySQLBackend.new(connection, namespace:, **)
+                  end
+      end
+
+      def dispatch_registry
+        @engine.dispatch_registry
+      end
+
+      def definition_registry
+        @engine.definition_registry
+      end
+
+      def acquire(key, ttl)
+        @engine.acquire(key, ttl)
+      end
+
+      def release(key)
+        @engine.release(key)
+      end
+    end
+  end
+end

data/lib/kaal/backend/postgres.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.
+module Kaal
+  module Backend
+    # PostgreSQL-backed backend for either Sequel or Active Record persistence.
+    class Postgres < Adapter
+      def initialize(database: nil, connection: nil, namespace: nil, **)
+        super()
+        @engine = if database
+                    Kaal::Sequel.require_sequel!
+                    require 'kaal/internal/sequel'
+                    Kaal::Internal::Sequel::PostgresBackend.new(database, namespace:)
+                  else
+                    Kaal::ActiveRecord.require_activerecord!
+                    require 'kaal/internal/active_record'
+                    Kaal::Internal::ActiveRecord::PostgresBackend.new(connection, namespace:, **)
+                  end
+      end
+
+      def dispatch_registry
+        @engine.dispatch_registry
+      end
+
+      def definition_registry
+        @engine.definition_registry
+      end
+
+      def acquire(key, ttl)
+        @engine.acquire(key, ttl)
+      end
+
+      def release(key)
+        @engine.release(key)
+      end
+    end
+  end
+end

data/lib/kaal/backend/sqlite.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.
+module Kaal
+  module Backend
+    # SQLite-backed backend for either Sequel or Active Record persistence.
+    class SQLite < Adapter
+      def initialize(database: nil, connection: nil, namespace: nil, **)
+        super()
+        @engine = if database
+                    Kaal::Sequel.require_sequel!
+                    require 'kaal/internal/sequel'
+                    Kaal::Internal::Sequel::DatabaseBackend.new(database, namespace:)
+                  else
+                    Kaal::ActiveRecord.require_activerecord!
+                    require 'kaal/internal/active_record'
+                    Kaal::Internal::ActiveRecord::DatabaseBackend.new(connection, namespace:, **)
+                  end
+      end
+
+      def dispatch_registry
+        @engine.dispatch_registry
+      end
+
+      def definition_registry
+        @engine.definition_registry
+      end
+
+      def acquire(key, ttl)
+        @engine.acquire(key, ttl)
+      end
+
+      def release(key)
+        @engine.release(key)
+      end
+    end
+  end
+end

data/lib/kaal/definition/database_engine.rb

@@ -0,0 +1,88 @@
+# 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'
+require 'kaal/persistence/database'
+
+module Kaal
+  module Definition
+    # Sequel-backed definition registry persisted in kaal_definitions.
+    class DatabaseEngine < Registry
+      def initialize(database:)
+        super()
+        @database = Kaal::Persistence::Database.new(database)
+      end
+
+      def upsert_definition(key:, cron:, enabled: true, source: 'code', metadata: {})
+        rows = dataset.where(key: key)
+        existing = rows.first
+        now = Time.now.utc
+        payload = {
+          key: key,
+          cron: cron,
+          enabled: enabled,
+          source: source,
+          metadata: JSON.generate(metadata || {}),
+          created_at: existing ? existing[:created_at] : now,
+          updated_at: now,
+          disabled_at: PersistenceHelpers.disabled_at_for(existing, enabled, now)
+        }
+
+        if existing
+          rows.update(payload)
+        else
+          dataset.insert(payload)
+        end
+
+        find_definition(key)
+      end
+
+      def remove_definition(key)
+        rows = dataset.where(key: key)
+        row = rows.first
+        return nil unless row
+
+        rows.delete
+        self.class.normalize_row(row)
+      end
+
+      def find_definition(key)
+        self.class.normalize_row(dataset.where(key: key).first)
+      end
+
+      def all_definitions
+        dataset.order(:key).all.map { |row| self.class.normalize_row(row) }
+      end
+
+      def enabled_definitions
+        dataset.where(enabled: true).order(:key).all.map { |row| self.class.normalize_row(row) }
+      end
+
+      def self.normalize_row(row)
+        return nil unless row
+
+        {
+          key: row[:key],
+          cron: row[:cron],
+          enabled: row[:enabled] ? true : false,
+          source: row[:source],
+          metadata: PersistenceHelpers.parse_metadata(row[:metadata]),
+          created_at: row[:created_at],
+          updated_at: row[:updated_at],
+          disabled_at: row[:disabled_at]
+        }
+      end
+
+      private
+
+      def dataset
+        @database.definitions_dataset
+      end
+    end
+  end
+end

data/lib/kaal/dispatch/database_engine.rb

@@ -0,0 +1,120 @@
+# 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'
+require 'kaal/persistence/database'
+
+module Kaal
+  module Dispatch
+    # Sequel-backed dispatch registry stored in kaal_dispatches.
+    class DatabaseEngine < Registry
+      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')
+        now = Time.now.utc
+        storage_key = namespaced_key(key)
+        attributes = {
+          key: storage_key,
+          fire_time: fire_time,
+          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
+
+      def find_dispatch(key, fire_time)
+        self.class.normalize_row(dataset.where(key: namespaced_key(key), fire_time: fire_time).first, namespace: @namespace)
+      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_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
+end

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