kaal-roda 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 877e7b001a2749328e275dbf9ed9c2293e83bf49db746733319936e82c0ce57e
+  data.tar.gz: fc14cad8e2f00b0283c085d198dd4d46629f957c42311ca4d046c55b8002905d
+SHA512:
+  metadata.gz: 03aeef8421ff4eeb01f7c71c0940b48a21cfa5ba55a977a9b6c91ce68003c8ec5bce0d2198c8279c59c5620e00c459e4d3fac83b7782a914d67c6337463d28d7
+  data.tar.gz: '078d579977b00c9cebb16bd553cdf1732be38249ea9863b2016b4aefa3f6015ca8437ef63ec4a9b15f4c6c6965be11630d981c64712f12cc0d0a15dfad238e63'

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Codevedas Inc.
+
+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,149 @@
+# Kaal::Roda
+
+Roda integration gem for Kaal.
+
+`kaal-roda` depends on:
+
+- `kaal`
+- `kaal-sequel`
+- `roda`
+
+It owns the Roda integration surface:
+
+- explicit boot wiring for Roda apps
+- backend wiring for memory, redis, SQLite, PostgreSQL, and MySQL
+- scheduler file boot loading relative to the Roda app root
+- opt-in scheduler startup and shutdown helpers
+- Roda-specific test coverage and a dummy app
+
+## Install
+
+```ruby
+gem 'kaal-roda'
+gem 'redis'   # for redis
+gem 'sqlite3' # or pg / mysql2 for SQL
+```
+
+If you use SQL persistence, create the Kaal tables using Sequel migrations. `kaal-sequel` exposes templates for:
+
+- SQLite: `kaal_dispatches`, `kaal_locks`, `kaal_definitions`
+- PostgreSQL: `kaal_dispatches`, `kaal_definitions`
+- MySQL: `kaal_dispatches`, `kaal_definitions`
+
+Your app should also provide `config/scheduler.yml`.
+
+## What It Provides
+
+- Roda-native wiring on top of the Kaal engine
+- explicit backend injection for memory and custom backends
+- redis convenience wiring when the app passes a redis client
+- automatic SQL backend selection from the Sequel adapter unless the app passes `adapter:`
+- explicit lifecycle helpers so web processes do not implicitly start background scheduler threads
+
+## Minimal Roda
+
+```ruby
+require 'roda'
+require 'kaal/roda'
+
+class ExampleHeartbeatJob
+  def self.perform(*)
+    puts 'heartbeat'
+  end
+end
+
+class App < Roda
+  plugin :kaal
+
+  kaal backend: Kaal::Backend::MemoryAdapter.new,
+       scheduler_config_path: 'config/scheduler.yml',
+       namespace: 'my-app',
+       start_scheduler: false
+
+  route do |r|
+    r.root { 'ok' }
+  end
+end
+```
+
+## Redis
+
+```ruby
+require 'roda'
+require 'redis'
+require 'kaal/roda'
+
+class App < Roda
+  REDIS = Redis.new(url: ENV.fetch('REDIS_URL'))
+
+  plugin :kaal
+
+  kaal redis: REDIS,
+       scheduler_config_path: 'config/scheduler.yml',
+       namespace: 'my-app',
+       start_scheduler: false
+end
+```
+
+## SQL Backends
+
+For SQL-backed Roda apps, pass a Sequel connection:
+
+```ruby
+require 'sequel'
+
+database = Sequel.connect(ENV.fetch('DATABASE_URL'))
+
+class App < Roda
+  plugin :kaal
+
+  kaal database: database,
+       adapter: 'postgres', # optional when Sequel can infer it
+       scheduler_config_path: 'config/scheduler.yml'
+end
+```
+
+## Lifecycle
+
+`kaal-roda` does not auto-start the scheduler by default.
+
+If you want the web process to run it:
+
+```ruby
+Kaal::Roda.start!
+```
+
+To stop it explicitly:
+
+```ruby
+Kaal::Roda.stop!
+```
+
+If you pass `start_scheduler: true` to `kaal`, the addon starts the scheduler and installs an `at_exit` shutdown hook for that managed scheduler instance.
+
+Preferred deployment model:
+
+- run the scheduler in a dedicated process when possible
+- use web-process startup only when you intentionally want co-located scheduling
+
+## Public API
+
+- `Kaal::Roda.register!(app, backend: nil, database: nil, redis: nil, scheduler_config_path: 'config/scheduler.yml', namespace: nil, start_scheduler: false, adapter: nil, root: nil, environment: nil)`
+- `Kaal::Roda.configure_backend!(backend: nil, database: nil, redis: nil, adapter: nil, configuration: Kaal.configuration)`
+- `Kaal::Roda.detect_backend_name(database, adapter: nil)`
+- `Kaal::Roda.load_scheduler_file!(root:, environment: nil)`
+- `Kaal::Roda.start!`
+- `Kaal::Roda.stop!`
+
+## Development
+
+```bash
+bin/rspec-unit
+bin/rspec-e2e memory
+REDIS_URL=redis://127.0.0.1:6379/0 bin/rspec-e2e redis
+bin/rspec-e2e sqlite
+DATABASE_URL=postgres://postgres:postgres@localhost:5432/kaal_test_auto bin/rspec-e2e pg
+DATABASE_URL=mysql2://root:rootROOT!1@127.0.0.1:3306/kaal_test_auto bin/rspec-e2e mysql
+bin/rubocop
+bin/reek
+```

data/Rakefile

@@ -0,0 +1,8 @@
+# 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'
+require 'bundler/gem_tasks'

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,7 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ADAPTER="${1:-memory}"
+shift || true
+
+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,5 @@
+#!/bin/sh
+
+set -e
+
+bundle update

data/lib/kaal/roda/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 Roda
+    VERSION = '0.3.0'
+  end
+end

data/lib/kaal/roda.rb

@@ -0,0 +1,182 @@
+# 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/sequel'
+require 'roda'
+require 'kaal/roda/version'
+
+module Kaal
+  # Roda integration surface for Kaal.
+  module Roda
+    class << self
+      def register!(
+        app,
+        backend: nil,
+        database: nil,
+        redis: nil,
+        scheduler_config_path: 'config/scheduler.yml',
+        namespace: nil,
+        start_scheduler: false,
+        adapter: nil,
+        root: nil,
+        environment: nil
+      )
+        configuration = Kaal.configuration
+        normalized_scheduler_config_path = scheduler_config_path.to_s.strip
+        normalized_namespace = namespace.to_s.strip
+        configuration.scheduler_config_path = normalized_scheduler_config_path unless normalized_scheduler_config_path.empty?
+        configuration.namespace = normalized_namespace unless normalized_namespace.empty?
+
+        configure_backend!(backend:, database:, redis:, adapter:, configuration:)
+        load_scheduler_file!(
+          root: root_path_for(app, root:),
+          environment: environment_name_for(app, environment:)
+        )
+
+        start_managed_scheduler! if start_scheduler
+        app
+      end
+
+      def configure_backend!(backend: nil, database: nil, redis: nil, adapter: nil, configuration: Kaal.configuration)
+        current_backend = configuration.backend
+        return current_backend if current_backend
+
+        return configuration.backend = backend if backend
+        return configuration.backend = build_redis_backend(redis, configuration) if redis
+
+        explicit_adapter = adapter.to_s.strip
+        unless explicit_adapter.empty?
+          raise ArgumentError, 'database is required when adapter is provided' unless database
+
+          backend_name = normalize_backend_name(explicit_adapter)
+          raise ArgumentError, "Unsupported Roda datastore backend: #{adapter.inspect}" unless backend_name
+
+          return configuration.backend = build_backend(backend_name, database)
+        end
+
+        return configuration.backend = Kaal::Backend::MemoryAdapter.new unless database
+
+        backend_name = detect_backend_name(database, adapter:)
+        raise ArgumentError, 'Unsupported Roda datastore backend; use memory, redis, sqlite, postgres, or mysql' unless backend_name
+
+        configuration.backend = build_backend(backend_name, database)
+      end
+
+      def detect_backend_name(database, adapter: nil)
+        explicit_adapter = normalize_backend_name(adapter)
+        return explicit_adapter if explicit_adapter
+
+        inferred_adapter = database_adapter_name(database)
+        normalize_backend_name(inferred_adapter)
+      end
+
+      def load_scheduler_file!(root:, environment: nil)
+        runtime_context = Kaal::Runtime::RuntimeContext.new(
+          root_path: root,
+          environment_name: environment || Kaal::Runtime::RuntimeContext.environment_name_from(ENV)
+        )
+
+        Kaal::Runtime::SchedulerBootLoader.new(
+          configuration_provider: -> { Kaal.configuration },
+          logger: Kaal.configuration.logger,
+          runtime_context: runtime_context,
+          load_scheduler_file: -> { Kaal.load_scheduler_file!(runtime_context:) }
+        ).load_on_boot!
+      end
+
+      def start!
+        Kaal.start!
+      end
+
+      def stop!(timeout: 30)
+        Kaal.stop!(timeout:)
+      end
+
+      private
+
+      def build_redis_backend(redis, configuration)
+        Kaal::Backend::RedisAdapter.new(redis, namespace: configuration.namespace)
+      end
+
+      def build_backend(backend_name, database)
+        case backend_name
+        when 'sqlite'
+          Kaal::Backend::DatabaseAdapter.new(database)
+        when 'postgres'
+          Kaal::Backend::PostgresAdapter.new(database)
+        when 'mysql'
+          Kaal::Backend::MySQLAdapter.new(database)
+        end
+      end
+
+      def database_adapter_name(database)
+        return if database.nil?
+
+        database_type = database.database_type if database.respond_to?(:database_type)
+        return database_type.to_s unless database_type.to_s.strip.empty?
+
+        adapter_scheme = database.adapter_scheme if database.respond_to?(:adapter_scheme)
+        adapter_scheme.to_s
+      end
+
+      def normalize_backend_name(adapter_name)
+        adapter = adapter_name.to_s.strip.downcase
+        return if adapter.empty?
+        return 'sqlite' if adapter.include?('sqlite')
+        return 'postgres' if adapter.include?('postgres')
+        return 'mysql' if adapter.include?('mysql') || adapter.include?('trilogy')
+
+        nil
+      end
+
+      def root_path_for(app, root: nil)
+        explicit_root = root.to_s.strip
+        return Pathname.new(explicit_root) unless explicit_root.empty?
+
+        app_root = app.opts[:root] if app.respond_to?(:opts)
+        Pathname.new(app_root || Dir.pwd)
+      end
+
+      def environment_name_for(app, environment: nil)
+        explicit_environment = environment.to_s.strip
+        return explicit_environment unless explicit_environment.empty?
+
+        app_environment = app.opts[:environment] if app.respond_to?(:opts)
+        app_environment.to_s.empty? ? Kaal::Runtime::RuntimeContext.environment_name_from(ENV) : app_environment.to_s
+      end
+
+      def start_managed_scheduler!
+        return if Kaal.running?
+
+        start!
+        install_shutdown_hook
+      end
+
+      def install_shutdown_hook
+        @shutdown_hook_mutex ||= Mutex.new
+        @shutdown_hook_mutex.synchronize do
+          return if @shutdown_hook_installed
+
+          @shutdown_hook_installed = true
+          Kernel.at_exit do
+            if Kaal.running?
+              begin
+                stop!
+              rescue StandardError => e
+                Kaal.configuration.logger&.error("Failed to stop Kaal during Roda shutdown: #{e.message}")
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+# Load the plugin after Kaal::Roda is defined so `require 'kaal/roda'`
+# makes `plugin :kaal` available without relying on `roda/plugins/kaal`.
+require 'roda/plugins/kaal'

data/lib/roda/plugins/kaal.rb

@@ -0,0 +1,24 @@
+# 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/roda'
+
+class Roda
+  # Roda plugin registry namespace.
+  module RodaPlugins
+    # Plugin that wires Kaal into Roda applications.
+    module Kaal
+      # Class-level DSL added by the plugin.
+      module ClassMethods
+        def kaal(**)
+          ::Kaal::Roda.register!(self, **)
+        end
+      end
+    end
+
+    register_plugin(:kaal, Kaal)
+  end
+end

metadata

@@ -0,0 +1,126 @@
+--- !ruby/object:Gem::Specification
+name: kaal-roda
+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-sequel
+  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: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: roda
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: "    Kaal-Roda provides a thin integration layer that wires Kaal and
+  Kaal-Sequel into Roda applications with explicit lifecycle control.\n"
+email:
+- nitesh.purohit.it@gmail.com
+- team@codevedas.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- bin/reek
+- bin/rspec
+- bin/rspec-e2e
+- bin/rspec-unit
+- bin/rubocop
+- bin/update-bundle
+- lib/kaal/roda.rb
+- lib/kaal/roda/version.rb
+- lib/roda/plugins/kaal.rb
+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-roda
+  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: Roda integration for Kaal, a distributed cron scheduler for Ruby.
+test_files: []