kaal 0.2.1 → 0.4.0

metadata

@@ -1,11 +1,12 @@
 --- !ruby/object:Gem::Specification
 name: kaal
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Nitesh Purohit
-bindir: bin
+- Codevedas Inc.
+bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
@@ -24,91 +25,135 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.8'
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: i18n
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '7.1'
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '9.0'
+        version: '1.14'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.1'
-    - - "<"
+        version: '1.14'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '9.0'
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
 - !ruby/object:Gem::Dependency
-  name: rails-i18n
+  name: tzinfo
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '2.0'
 description: "    Kaal is a distributed cron scheduler for Ruby that safely executes
   scheduled tasks across multiple nodes.\n"
 email:
 - nitesh.purohit.it@gmail.com
-executables: []
+- team@codevedas.com
+executables:
+- kaal
 extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
 - Rakefile
-- app/models/kaal/cron_definition.rb
-- app/models/kaal/cron_dispatch.rb
-- app/models/kaal/cron_lock.rb
+- config/kaal.rb
 - config/locales/en.yml
-- lib/generators/kaal/install/install_generator.rb
-- lib/generators/kaal/install/templates/create_kaal_definitions.rb.tt
-- lib/generators/kaal/install/templates/create_kaal_dispatches.rb.tt
-- lib/generators/kaal/install/templates/create_kaal_locks.rb.tt
-- lib/generators/kaal/install/templates/kaal.rb.tt
-- lib/generators/kaal/install/templates/scheduler.yml.tt
+- config/scheduler.yml
+- exe/kaal
 - lib/kaal.rb
+- lib/kaal/active_record_support.rb
 - lib/kaal/backend/adapter.rb
+- lib/kaal/backend/dispatch_attempt_logger.rb
 - lib/kaal/backend/dispatch_logging.rb
+- lib/kaal/backend/dispatch_registry_accessor.rb
 - lib/kaal/backend/memory_adapter.rb
-- lib/kaal/backend/mysql_adapter.rb
-- lib/kaal/backend/postgres_adapter.rb
+- lib/kaal/backend/mysql.rb
+- lib/kaal/backend/postgres.rb
 - lib/kaal/backend/redis_adapter.rb
-- lib/kaal/backend/sqlite_adapter.rb
-- lib/kaal/configuration.rb
-- lib/kaal/coordinator.rb
-- lib/kaal/cron_humanizer.rb
-- lib/kaal/cron_utils.rb
+- lib/kaal/backend/sqlite.rb
+- lib/kaal/cli.rb
+- lib/kaal/config.rb
+- lib/kaal/config/configuration.rb
+- lib/kaal/config/scheduler_config_error.rb
+- lib/kaal/config/scheduler_time_zone_resolver.rb
+- lib/kaal/core.rb
+- lib/kaal/core/coordinator.rb
+- lib/kaal/core/enabled_entry_enumerator.rb
+- lib/kaal/core/occurrence_finder.rb
 - lib/kaal/definition/database_engine.rb
 - lib/kaal/definition/memory_engine.rb
+- lib/kaal/definition/persistence_helpers.rb
 - lib/kaal/definition/redis_engine.rb
 - lib/kaal/definition/registry.rb
+- lib/kaal/definitions/registration_service.rb
+- lib/kaal/definitions/registry_accessor.rb
 - lib/kaal/dispatch/database_engine.rb
 - lib/kaal/dispatch/memory_engine.rb
 - lib/kaal/dispatch/redis_engine.rb
 - lib/kaal/dispatch/registry.rb
-- lib/kaal/idempotency_key_generator.rb
-- lib/kaal/railtie.rb
-- lib/kaal/rake_tasks.rb
+- lib/kaal/internal/active_record.rb
+- lib/kaal/internal/active_record/base_record.rb
+- lib/kaal/internal/active_record/connection_support.rb
+- lib/kaal/internal/active_record/database_backend.rb
+- lib/kaal/internal/active_record/definition_record.rb
+- lib/kaal/internal/active_record/definition_registry.rb
+- lib/kaal/internal/active_record/dispatch_record.rb
+- lib/kaal/internal/active_record/dispatch_registry.rb
+- lib/kaal/internal/active_record/lock_record.rb
+- lib/kaal/internal/active_record/migration_templates.rb
+- lib/kaal/internal/active_record/mysql_backend.rb
+- lib/kaal/internal/active_record/postgres_backend.rb
+- lib/kaal/internal/sequel.rb
+- lib/kaal/internal/sequel/database_backend.rb
+- lib/kaal/internal/sequel/mysql_backend.rb
+- lib/kaal/internal/sequel/postgres_backend.rb
+- lib/kaal/persistence/database.rb
+- lib/kaal/persistence/migration_templates.rb
 - lib/kaal/register_conflict_support.rb
 - lib/kaal/registry.rb
-- lib/kaal/scheduler_config_error.rb
-- lib/kaal/scheduler_file_loader.rb
-- lib/kaal/scheduler_hash_transform.rb
-- lib/kaal/scheduler_placeholder_support.rb
+- lib/kaal/runtime.rb
+- lib/kaal/runtime/runtime_context.rb
+- lib/kaal/runtime/scheduler_boot_loader.rb
+- lib/kaal/runtime/signal_handler_chain.rb
+- lib/kaal/runtime/signal_handler_installer.rb
+- lib/kaal/scheduler_file.rb
+- lib/kaal/scheduler_file/hash_transform.rb
+- lib/kaal/scheduler_file/helper_bundle.rb
+- lib/kaal/scheduler_file/job_applier.rb
+- lib/kaal/scheduler_file/job_normalizer.rb
+- lib/kaal/scheduler_file/loader.rb
+- lib/kaal/scheduler_file/payload_loader.rb
+- lib/kaal/scheduler_file/placeholder_support.rb
+- lib/kaal/sequel_support.rb
+- lib/kaal/support/hash_tools.rb
+- lib/kaal/utils.rb
+- lib/kaal/utils/cron_humanizer.rb
+- lib/kaal/utils/cron_utils.rb
+- lib/kaal/utils/idempotency_key_generator.rb
 - lib/kaal/version.rb
-- lib/tasks/kaal_tasks.rake
 homepage: https://github.com/Code-Vedas/kaal
 licenses:
 - MIT

data/app/models/kaal/cron_definition.rb

@@ -1,76 +0,0 @@
-# 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
-  # Persistent scheduler definition model.
-  class CronDefinition < ApplicationRecord
-    self.table_name = 'kaal_definitions'
-
-    before_validation :ensure_metadata
-
-    validates :key, presence: true, uniqueness: true
-    validates :cron, presence: true
-    validates :source, presence: true
-    validates :enabled, inclusion: { in: [true, false] }
-
-    scope :enabled, -> { where(enabled: true) }
-    scope :disabled, -> { where(enabled: false) }
-    scope :by_source, ->(source) { where(source: source) }
-
-    def self.upsert_definition!(key:, cron:, enabled:, source:, metadata:)
-      persist_definition(find_or_initialize_by(key: key), cron:, enabled:, source:, metadata:)
-    rescue ActiveRecord::RecordNotUnique
-      persist_definition(find_by!(key: key), cron:, enabled:, source:, metadata:)
-    end
-
-    def to_definition_hash
-      {
-        key: key,
-        cron: cron,
-        enabled: enabled,
-        source: source,
-        metadata: metadata || {},
-        created_at: created_at,
-        updated_at: updated_at,
-        disabled_at: disabled_at
-      }
-    end
-
-    def destroy_and_return_definition_hash
-      definition_hash = to_definition_hash
-      destroy!
-      definition_hash
-    end
-
-    def self.persist_definition(record, cron:, enabled:, source:, metadata:)
-      disabled_at = if enabled
-                      nil
-                    elsif record.new_record? || record.enabled != false
-                      Time.current
-                    else
-                      record.disabled_at
-                    end
-
-      record.assign_attributes(
-        cron: cron,
-        enabled: enabled,
-        source: source,
-        metadata: metadata,
-        disabled_at:
-      )
-      record.save!
-      record
-    end
-    private_class_method :persist_definition
-
-    private
-
-    def ensure_metadata
-      self.metadata ||= {}
-    end
-  end
-end

data/app/models/kaal/cron_dispatch.rb

@@ -1,50 +0,0 @@
-# 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
-  ##
-  # Audit model for tracking cron job dispatch attempts across the cluster.
-  #
-  # CronDispatch records information about each cron job that was dispatched,
-  # including the cron key, scheduled fire time, actual dispatch time,
-  # the node that dispatched it, and the dispatch status.
-  #
-  # This model is used by the PostgreSQL lock adapter for observability and
-  # debugging in distributed deployments. You can use this table to:
-  # - Verify that jobs are only dispatched once per fire_time
-  # - Track which node dispatched each job
-  # - Monitor dispatch latency
-  # - Audit job execution history
-  #
-  # @example Query dispatch history
-  #   Kaal::CronDispatch.where(
-  #     key: 'send_emails',
-  #     status: 'dispatched'
-  #   ).order(fire_time: :desc).limit(10)
-  #
-  # @example Find all dispatches from a specific node
-  #   Kaal::CronDispatch.where(node_id: 'worker1').order(dispatched_at: :desc)
-  class CronDispatch < ApplicationRecord
-    self.table_name = 'kaal_dispatches'
-
-    ##
-    # Validations
-    validates :key, presence: true
-    validates :fire_time, presence: true
-    validates :dispatched_at, presence: true
-    validates :node_id, presence: true
-    validates :status, presence: true, inclusion: { in: %w[dispatched failed] }
-
-    ##
-    # Scopes for common queries
-    scope :recent, ->(limit = 100) { order(dispatched_at: :desc).limit(limit) }
-    scope :by_key, ->(key) { where(key: key) }
-    scope :by_node, ->(node_id) { where(node_id: node_id) }
-    scope :by_status, ->(status) { where(status: status) }
-    scope :since, ->(timestamp) { where('dispatched_at >= ?', timestamp) }
-  end
-end

data/app/models/kaal/cron_lock.rb

@@ -1,38 +0,0 @@
-# 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
-  ##
-  # Model for distributed lock records (database-backed).
-  #
-  # Used by the database-backed adapter (SQLiteAdapter) to store lock state in a database table.
-  # Works with any ActiveRecord-supported SQL database (SQLite, PostgreSQL, MySQL, etc.).
-  # Each row represents a held lock with an expiration time.
-  class CronLock < ApplicationRecord
-    self.table_name = 'kaal_locks'
-
-    validates :key, presence: true, uniqueness: true
-    validates :acquired_at, presence: true
-    validates :expires_at, presence: true
-
-    ##
-    # Find and delete any expired locks (cleanup).
-    #
-    # @return [Integer] number of locks deleted
-    def self.cleanup_expired
-      where('expires_at < ?', Time.current).delete_all
-    end
-
-    ##
-    # Check if this lock is still valid (not expired).
-    #
-    # @return [Boolean] true if not expired
-    def not_expired?
-      expires_at > Time.current
-    end
-  end
-end

data/lib/generators/kaal/install/install_generator.rb

@@ -1,72 +0,0 @@
-# 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 'rails/generators'
-require 'rails/generators/active_record'
-
-module Kaal
-  module Generators
-    # Installs the database migrations needed for the selected backend.
-    class InstallGenerator < Rails::Generators::Base
-      include Rails::Generators::Migration
-
-      source_root File.expand_path('templates', __dir__)
-
-      class_option :backend,
-                   type: :string,
-                   default: 'sqlite',
-                   desc: 'Backend to install migrations for: sqlite, postgres, mysql, redis, memory'
-
-      def create_initializer
-        template 'kaal.rb.tt', 'config/initializers/kaal.rb'
-      end
-
-      def create_scheduler_config
-        template 'scheduler.yml.tt', 'config/scheduler.yml'
-      end
-
-      def install_migrations
-        templates = migration_templates
-        return say_status(:skip, "No database migrations required for #{normalized_backend} backend", :yellow) if templates.empty?
-
-        templates.each do |template_name|
-          migration_template "#{template_name}.rb.tt", "db/migrate/#{template_name}.rb"
-        end
-      end
-
-      def self.next_migration_number(dirname)
-        ActiveRecord::Generators::Base.next_migration_number(dirname)
-      end
-
-      private
-
-      def migration_templates
-        case normalized_backend
-        when 'sqlite', 'database'
-          %w[
-            create_kaal_dispatches
-            create_kaal_locks
-            create_kaal_definitions
-          ]
-        when 'postgres', 'mysql'
-          %w[
-            create_kaal_dispatches
-            create_kaal_definitions
-          ]
-        when 'memory', 'redis'
-          []
-        else
-          raise Thor::Error, "Unsupported backend '#{options['backend']}'. Use sqlite, postgres, mysql, redis, or memory."
-        end
-      end
-
-      def normalized_backend
-        options['backend'].to_s.downcase
-      end
-    end
-  end
-end

data/lib/generators/kaal/install/templates/create_kaal_definitions.rb.tt

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-# Creates the persisted cron definitions table for database-backed definitions.
-class CreateKaalDefinitions < ActiveRecord::Migration[7.0]
-  def change
-    create_table :kaal_definitions do |t|
-      t.string :key, null: false, limit: 255
-      t.string :cron, null: false, limit: 255
-      t.boolean :enabled, null: false, default: true
-      t.string :source, null: false, limit: 50, default: 'code'
-      t.json :metadata, null: false
-      t.datetime :disabled_at
-
-      t.timestamps
-    end
-
-    add_index :kaal_definitions, :key, unique: true
-    add_index :kaal_definitions, :enabled
-    add_index :kaal_definitions, :source
-  end
-end

data/lib/generators/kaal/install/templates/create_kaal_dispatches.rb.tt

@@ -1,20 +0,0 @@
-# frozen_string_literal: true
-
-# Creates the dispatch records table for database-backed dispatch logging.
-class CreateKaalDispatches < ActiveRecord::Migration[7.0]
-  def change
-    create_table :kaal_dispatches do |t|
-      t.string :key, null: false, limit: 255
-      t.datetime :fire_time, null: false
-      t.datetime :dispatched_at, null: false
-      t.string :node_id, null: false, limit: 255
-      t.string :status, null: false, limit: 50, default: 'dispatched'
-
-      t.timestamps
-    end
-
-    add_index :kaal_dispatches, %i[key fire_time], unique: true
-    add_index :kaal_dispatches, :dispatched_at
-    add_index :kaal_dispatches, :status
-  end
-end

data/lib/generators/kaal/install/templates/create_kaal_locks.rb.tt

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-# Creates the lock table for database-backed lease coordination.
-class CreateKaalLocks < ActiveRecord::Migration[7.0]
-  def change
-    create_table :kaal_locks do |t|
-      t.string :key, null: false, limit: 255
-      t.datetime :acquired_at, null: false
-      t.datetime :expires_at, null: false
-
-      t.timestamps
-    end
-
-    add_index :kaal_locks, :key, unique: true
-    add_index :kaal_locks, :expires_at
-  end
-end

data/lib/generators/kaal/install/templates/kaal.rb.tt

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-Kaal.configure do |config|
-  # Select the backend that matches your deployment.
-  # See the Kaal documentation for backend-specific setup and the full
-  # configuration reference.
-  #
-  # Redis (recommended for multi-node deployments):
-  # config.backend = Kaal::Backend::RedisAdapter.new(Redis.new(url: ENV.fetch('REDIS_URL')))
-  #
-  # PostgreSQL advisory locks:
-  # config.backend = Kaal::Backend::PostgresAdapter.new
-  #
-  # MySQL / SQLite database-backed coordination:
-  # config.backend = Kaal::Backend::SQLiteAdapter.new
-
-  config.tick_interval = 5
-  config.window_lookback = 120
-  # Keep lease_ttl >= window_lookback + tick_interval to prevent duplicate dispatch.
-  config.lease_ttl = 125
-  config.recovery_window = 3600
-  config.enable_dispatch_recovery = true
-  config.enable_log_dispatch_registry = false
-
-  # Scheduler file loading
-  config.scheduler_config_path = 'config/scheduler.yml'
-  # :error, :code_wins, :file_wins
-  config.scheduler_conflict_policy = :error
-  # :warn, :error
-  config.scheduler_missing_file_policy = :warn
-end

data/lib/generators/kaal/install/templates/scheduler.yml.tt

@@ -1,22 +0,0 @@
-defaults:
-  jobs:
-    - key: "reports:weekly_summary"
-      cron: "0 9 * * 1"
-      job_class: "WeeklySummaryJob"
-      enabled: true
-      queue: "default"
-      args:
-        - "{{fire_time.iso8601}}"
-      kwargs:
-        idempotency_key: "{{idempotency_key}}"
-      metadata:
-        owner: "ops"
-
-development:
-  jobs: []
-
-test:
-  jobs: []
-
-production:
-  jobs: []