kaal-rails 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 800bd823b767eafa640969d895f5c1b408f6cfdbce1ea386ca98950eadd2ccc1
+  data.tar.gz: 8f611cf0bd2b4f9002184cbf5f5743444aeb8ebcd0b2faa8482f761a5c48ddfb
+SHA512:
+  metadata.gz: ea626952cb9cf77da562331ebb7ba727fdae05ff434d99a652e5c9d19c1549a12754d546d63ea69188962dab96391802ce04052f9e2014f46119a20437e9c913
+  data.tar.gz: 6cbb6b3d94a29f3b3217fd19052c74feaad8f009ec2b69e6ebfaae41687f51f73ddf17e7a1c4e07d9d32541b115f33563d9d4a3926b841cb5706f9bf0e7e4959

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Codevedas Inc. and the Kaal Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,83 @@
+# Kaal::Rails
+
+Rails plugin gem for Kaal.
+
+`kaal-rails` depends on:
+
+- `kaal`
+- `kaal-activerecord`
+
+It owns the Rails integration surface:
+
+- Railtie
+- rake tasks
+- generators
+- Active Record migration generation
+- Rails dummy app and Rails-specific test coverage
+
+## Install
+
+```ruby
+gem 'kaal-rails'
+```
+
+Then generate the scheduler config and migrations:
+
+```bash
+bundle exec rails generate kaal:install --backend=sqlite
+bundle exec rails db:migrate
+```
+
+PostgreSQL:
+
+```bash
+bundle exec rails generate kaal:install --backend=postgres
+bundle exec rails db:migrate
+```
+
+MySQL:
+
+```bash
+bundle exec rails generate kaal:install --backend=mysql
+bundle exec rails db:migrate
+```
+
+## What It Provides
+
+- Rails-native setup on top of the Kaal engine
+- Active Record-backed persistence through `kaal-activerecord`
+- migration templates for the Kaal tables required by the selected backend
+- automatic backend selection from the Rails database adapter unless the app sets `Kaal.configuration.backend` itself
+
+## Usage
+
+Add the gem to your Rails app and configure only if you need overrides:
+
+```ruby
+Kaal.configure do |config|
+  config.scheduler_config_path = Rails.root.join('config/scheduler.yml')
+end
+```
+
+If you do nothing, `kaal-rails` will auto-wire:
+
+- SQLite to `Kaal::ActiveRecord::DatabaseAdapter`
+- PostgreSQL to `Kaal::ActiveRecord::PostgresAdapter`
+- MySQL to `Kaal::ActiveRecord::MySQLAdapter`
+
+Available Rails surfaces:
+
+- `bin/rails generate kaal:install --backend=sqlite`
+- `bin/rails generate kaal:install --backend=postgres`
+- `bin/rails generate kaal:install --backend=mysql`
+- `bin/rake kaal:install:all`
+- `bin/rake kaal:install:migrations`
+
+## Development
+
+```bash
+bin/rspec-unit
+bin/rspec-e2e sqlite
+bin/rubocop
+bin/reek
+```

data/Rakefile

@@ -0,0 +1,10 @@
+# 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 'bundler/setup'
+APP_RAKEFILE = File.expand_path('spec/dummy/Rakefile', __dir__)
+load 'rails/tasks/engine.rake'
+require 'bundler/gem_tasks'

data/bin/importmap

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# 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_relative '../config/application'
+require 'importmap/commands'

data/bin/rails

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+# 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.
+# This command will automatically be run when you run "rails" with Rails gems
+# installed from the root of your application.
+
+APP_PATH = File.expand_path('../test/dummy/config/application', __dir__)
+
+# Set up gems listed in the Gemfile.
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../Gemfile', __dir__)
+require 'bundler/setup' if File.exist?(ENV['BUNDLE_GEMFILE'])
+
+require 'rails/all'
+require 'rails/engine/commands'

data/bin/reek

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+# 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 'pty'
+
+root_dir = File.expand_path('..', __dir__)
+Dir.chdir(root_dir)
+
+command = ['bundle', 'exec', 'reek', *ARGV]
+output = +''
+status = nil
+
+PTY.spawn(*command) do |reader, _writer, pid|
+  reader.each { |line| output << line }
+rescue Errno::EIO
+  nil
+ensure
+  _, status = Process.wait2(pid)
+end
+
+print(output.gsub("\r\n", "\n"))
+exit(status.exitstatus || 1)

data/bin/rspec

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+# 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.
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../Gemfile', __dir__)
+
+bundle_binstub = File.expand_path('bundle', __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?('This file was generated by Bundler')
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rspec-core', 'rspec')

data/bin/rspec-e2e

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ADAPTER="${1:-nshift}"  # default adapter
+shift || true            # remove first arg, leave the rest in "$@"
+
+# Run RSpec with environment variables and proper tags
+E2E="1" NO_COVERAGE=1 bin/rspec spec/e2e --tag "integration:${ADAPTER}" "$@"

data/bin/rspec-unit

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+set -euo pipefail
+bin/rspec spec/kaal --tag ~feature --tag ~integration "$@"

data/bin/rubocop

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+# 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.
+#
+# This file was generated by Bundler.
+#
+# The application 'rubocop' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../Gemfile', __dir__)
+
+bundle_binstub = File.expand_path('bundle', __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?('This file was generated by Bundler')
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rubocop', 'rubocop')

data/bin/update-bundle

@@ -0,0 +1,9 @@
+#!/bin/sh
+
+set -e
+
+bundle update
+BUNDLE_GEMFILE=gemfiles/rails_7_2.gemfile bundle update
+BUNDLE_GEMFILE=gemfiles/rails_8_0.gemfile bundle update
+BUNDLE_GEMFILE=gemfiles/rails_8_1.gemfile bundle update
+BUNDLE_GEMFILE=gemfiles/rails_edge.gemfile bundle update

data/lib/generators/kaal/install_generator.rb

@@ -0,0 +1,31 @@
+# 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'
+
+module Kaal
+  module Generators
+    # Installs Kaal scheduler config and Active Record migrations into a Rails app.
+    class InstallGenerator < ::Rails::Generators::Base
+      class_option :backend, type: :string, desc: 'sqlite, postgres, or mysql'
+
+      def install_kaal
+        results = Kaal::Rails.install!(root: destination_root, backend: selected_backend)
+        scheduler_config = results.fetch(:scheduler_config)
+        say_status(scheduler_config.fetch(:status), scheduler_config.fetch(:path))
+        results.fetch(:migrations).each do |migration|
+          say_status(migration.fetch(:status), migration.fetch(:path))
+        end
+      end
+
+      private
+
+      def selected_backend
+        options[:backend] || Kaal::Rails.detect_backend_name
+      end
+    end
+  end
+end

data/lib/kaal/rails/installer.rb

@@ -0,0 +1,90 @@
+# 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'
+require 'pathname'
+
+module Kaal
+  module Rails
+    # Installs scheduler config and Active Record migrations into a Rails app.
+    class Installer
+      SCHEDULER_TEMPLATE = <<~YAML
+        defaults:
+          jobs:
+            - key: "example:heartbeat"
+              cron: "*/5 * * * *"
+              job_class: "ExampleHeartbeatJob"
+              enabled: true
+              args:
+                - "{{fire_time.iso8601}}"
+              kwargs:
+                idempotency_key: "{{idempotency_key}}"
+      YAML
+
+      def initialize(root:, backend:, time_source: -> { Time.now.utc })
+        @root = Pathname(root)
+        @backend = validate_backend(backend.to_s)
+        @time_source = time_source
+      end
+
+      def install_scheduler_config
+        ensure_scheduler_config_dir
+        return { status: :exists, path: scheduler_config_path_string } if scheduler_config_exists?
+
+        File.write(scheduler_config_path, SCHEDULER_TEMPLATE)
+        { status: :create, path: scheduler_config_path_string }
+      end
+
+      def install_migrations
+        migrations_dir = root.join('db', 'migrate')
+        base_time = time_source.call
+        FileUtils.mkdir_p(migrations_dir)
+
+        Kaal::ActiveRecord::MigrationTemplates.for_backend(backend).map.with_index do |(name, contents), index|
+          slug = name.sub(/^\d+_/, '')
+          existing = Dir[migrations_dir.join("*_#{slug}").to_s].first
+          next({ status: :exists, path: existing.to_s }) if existing
+
+          timestamp = (base_time + index).strftime('%Y%m%d%H%M%S')
+          target = migrations_dir.join("#{timestamp}_#{slug}")
+          File.write(target, contents)
+          { status: :create, path: target.to_s }
+        end
+      end
+
+      private
+
+      attr_reader :backend, :root, :time_source
+
+      def validate_backend(backend_name)
+        if backend_name.strip.empty?
+          raise ArgumentError,
+                'Could not detect backend from ActiveRecord adapter; pass --backend (sqlite/postgres/mysql)'
+        end
+
+        return backend_name if %w[sqlite postgres mysql].include?(backend_name)
+
+        raise ArgumentError, "Unsupported Rails datastore backend: #{backend_name.inspect}"
+      end
+
+      def scheduler_config_path
+        root.join('config', 'scheduler.yml')
+      end
+
+      def scheduler_config_exists?
+        scheduler_config_path.exist?
+      end
+
+      def scheduler_config_path_string
+        scheduler_config_path.to_s
+      end
+
+      def ensure_scheduler_config_dir
+        FileUtils.mkdir_p(scheduler_config_path.dirname)
+      end
+    end
+  end
+end

data/lib/kaal/rails/railtie.rb

@@ -0,0 +1,22 @@
+# 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/railtie'
+
+module Kaal
+  module Rails
+    # Railtie that wires Kaal into a Rails app.
+    class Railtie < ::Rails::Railtie
+      initializer 'kaal-rails.configure_backend', after: 'active_record.initialize_database' do
+        Kaal::Rails.configure_backend!
+      end
+
+      rake_tasks do
+        load File.expand_path('../../tasks/kaal/rails_tasks.rake', __dir__)
+      end
+    end
+  end
+end

data/lib/kaal/rails/version.rb

@@ -0,0 +1,11 @@
+# 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 Rails
+    VERSION = '0.3.0'
+  end
+end

data/lib/kaal/rails.rb

@@ -0,0 +1,61 @@
+# 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'
+require 'kaal'
+require 'kaal/active_record'
+require 'kaal/rails/version'
+require 'kaal/rails/installer'
+require 'kaal/rails/railtie'
+
+module Kaal
+  # Rails integration surface for Kaal.
+  module Rails
+    class << self
+      DETECT_BACKEND_DEFAULT = Object.new
+
+      def detect_backend_name(db_config = DETECT_BACKEND_DEFAULT)
+        db_config = ::ActiveRecord::Base.connection_db_config if db_config.equal?(DETECT_BACKEND_DEFAULT)
+        adapter = db_config&.adapter.to_s.downcase
+
+        return 'sqlite' if adapter.include?('sqlite')
+        return 'postgres' if adapter.include?('postgres')
+        return 'mysql' if adapter.include?('mysql') || adapter.include?('trilogy')
+
+        nil
+      rescue ::ActiveRecord::ConnectionNotEstablished
+        nil
+      end
+
+      def build_backend(backend_name = detect_backend_name)
+        case backend_name.to_s
+        when 'sqlite'
+          Kaal::ActiveRecord::DatabaseAdapter.new
+        when 'postgres'
+          Kaal::ActiveRecord::PostgresAdapter.new
+        when 'mysql'
+          Kaal::ActiveRecord::MySQLAdapter.new
+        end
+      end
+
+      def configure_backend!(configuration: Kaal.configuration, backend: build_backend)
+        current_backend = configuration.backend
+        return current_backend if current_backend
+        return nil unless backend
+
+        configuration.backend = backend
+      end
+
+      def install!(root: ::Rails.root, backend: detect_backend_name)
+        installer = Installer.new(root:, backend:)
+        {
+          scheduler_config: installer.install_scheduler_config,
+          migrations: installer.install_migrations
+        }
+      end
+    end
+  end
+end

data/lib/tasks/kaal/rails_tasks.rake

@@ -0,0 +1,27 @@
+# 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.
+
+namespace :kaal do
+  namespace :install do
+    desc 'Install Kaal scheduler config and Active Record migrations'
+    task all: :environment do
+      results = Kaal::Rails.install!
+      puts "#{results.fetch(:scheduler_config).fetch(:status)} #{results.fetch(:scheduler_config).fetch(:path)}"
+      results.fetch(:migrations).each do |migration|
+        puts "#{migration.fetch(:status)} #{migration.fetch(:path)}"
+      end
+    end
+
+    desc 'Install Kaal Active Record migrations'
+    task migrations: :environment do
+      installer = Kaal::Rails::Installer.new(root: Rails.root, backend: Kaal::Rails.detect_backend_name)
+      installer.install_migrations.each do |migration|
+        puts "#{migration.fetch(:status)} #{migration.fetch(:path)}"
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,135 @@
+--- !ruby/object:Gem::Specification
+name: kaal-rails
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Nitesh Purohit
+- Codevedas Inc.
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: kaal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.3.0
+- !ruby/object:Gem::Dependency
+  name: kaal-activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.3.0
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: rails-i18n
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: "    Kaal-Rails is a Ruby gem that provides seamless integration of Kaal
+  with Ruby on Rails, allowing you to easily schedule and manage cron jobs in a distributed
+  environment using ActiveRecord models. With Kaal-Rails, you can define your cron
+  jobs as ActiveRecord models, and Kaal will handle the scheduling and execution of
+  those jobs across multiple instances of your Rails application. This makes it easy
+  to build scalable and reliable background job processing systems in your Rails applications.\n"
+email:
+- nitesh.purohit.it@gmail.com
+- team@codevedas.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- bin/importmap
+- bin/rails
+- bin/reek
+- bin/rspec
+- bin/rspec-e2e
+- bin/rspec-unit
+- bin/rubocop
+- bin/update-bundle
+- lib/generators/kaal/install_generator.rb
+- lib/kaal/rails.rb
+- lib/kaal/rails/installer.rb
+- lib/kaal/rails/railtie.rb
+- lib/kaal/rails/version.rb
+- lib/tasks/kaal/rails_tasks.rake
+homepage: https://github.com/Code-Vedas/kaal
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/Code-Vedas/kaal/issues
+  changelog_uri: https://github.com/Code-Vedas/kaal/blob/main/CHANGELOG.md
+  documentation_uri: https://kaal.codevedas.com
+  homepage_uri: https://github.com/Code-Vedas/kaal
+  source_code_uri: https://github.com/Code-Vedas/kaal.git
+  funding_uri: https://github.com/sponsors/Code-Vedas
+  support_uri: https://kaal.codevedas.com/support
+  rubygems_uri: https://rubygems.org/gems/kaal-rails
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Kaal-Rails provides seamless integration of Kaal with Ruby on Rails
+test_files: []