kaal-sinatra 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '056818dc738336966c9f49347c9d5c848b8a326491e54d7eeb92f98846f745a2'
+  data.tar.gz: c6f2b304ec788996da55d66c9e0239aeac58e45853f9a7a9fe205fe3a2217b07
+SHA512:
+  metadata.gz: 81b6f5416d682df2d9e3b4e16fa88c7a35deb41c2bbd2c11a558c3a7d9190043cf59ba5a877eafca5a3897203ad10b73ba0b352ddd8730d48d3fab0ab2214946
+  data.tar.gz: 14c4d191e3a7b813c5753f4ff70e391a1fd8fa2786eb2a65cda56f74ee327a692de9baac67f0e4f7ef4ea4223e3ed2f177c2a98b84d613cb7ca9e112be65bbcd

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,150 @@
+# Kaal::Sinatra
+
+Sinatra integration gem for Kaal.
+
+`kaal-sinatra` depends on:
+
+- `kaal`
+- `kaal-sequel`
+- `sinatra`
+
+It owns the Sinatra integration surface:
+
+- explicit boot wiring for Sinatra apps
+- backend wiring for memory, redis, SQLite, PostgreSQL, and MySQL
+- scheduler file boot loading relative to the Sinatra app root
+- opt-in scheduler startup and shutdown helpers
+- Sinatra-specific test coverage and dummy apps
+
+## Install
+
+```ruby
+gem 'kaal-sinatra'
+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
+
+- Sinatra-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
+
+## Classic Sinatra
+
+```ruby
+require 'sinatra'
+require 'kaal/sinatra'
+
+class ExampleHeartbeatJob
+  def self.perform(*)
+    puts 'heartbeat'
+  end
+end
+
+register Kaal::Sinatra::Extension
+
+Kaal::Sinatra.register!(
+  settings,
+  backend: Kaal::Backend::MemoryAdapter.new,
+  scheduler_config_path: 'config/scheduler.yml',
+  namespace: 'my-app',
+  start_scheduler: false
+)
+```
+
+## Modular Sinatra
+
+```ruby
+require 'sinatra/base'
+require 'redis'
+require 'kaal/sinatra'
+
+class ExampleHeartbeatJob
+  def self.perform(*)
+    puts 'heartbeat'
+  end
+end
+
+class App < Sinatra::Base
+  REDIS = Redis.new(url: ENV.fetch('REDIS_URL'))
+
+  register Kaal::Sinatra::Extension
+
+  kaal redis: REDIS,
+       scheduler_config_path: 'config/scheduler.yml',
+       namespace: 'my-app',
+       start_scheduler: false
+end
+```
+
+## SQL Backends
+
+For SQL-backed Sinatra apps, pass a Sequel connection:
+
+```ruby
+require 'sequel'
+
+database = Sequel.connect(ENV.fetch('DATABASE_URL'))
+
+Kaal::Sinatra.register!(
+  settings,
+  database: database,
+  adapter: 'postgres', # optional when Sequel can infer it
+  scheduler_config_path: 'config/scheduler.yml'
+)
+```
+
+## Lifecycle
+
+`kaal-sinatra` does not auto-start the scheduler by default.
+
+If you want the web process to run it:
+
+```ruby
+Kaal::Sinatra.start!
+```
+
+To stop it explicitly:
+
+```ruby
+Kaal::Sinatra.stop!
+```
+
+If you pass `start_scheduler: true` to the extension or `Kaal::Sinatra.register!`, 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::Sinatra.register!(app, backend: nil, database: nil, redis: nil, scheduler_config_path: 'config/scheduler.yml', namespace: nil, start_scheduler: false, adapter: nil)`
+- `Kaal::Sinatra.configure_backend!(backend: nil, database: nil, redis: nil, adapter: nil, configuration: Kaal.configuration)`
+- `Kaal::Sinatra.load_scheduler_file!(root:, environment: nil)`
+- `Kaal::Sinatra.start!`
+- `Kaal::Sinatra.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/sinatra/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 Sinatra
+    VERSION = '0.3.0'
+  end
+end

data/lib/kaal/sinatra.rb

@@ -0,0 +1,184 @@
+# 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 'sinatra/base'
+require 'kaal/sinatra/version'
+
+module Kaal
+  # Sinatra integration surface for Kaal.
+  module Sinatra
+    class << self
+      def register!(
+        app,
+        backend: nil,
+        database: nil,
+        redis: nil,
+        scheduler_config_path: 'config/scheduler.yml',
+        namespace: nil,
+        start_scheduler: false,
+        adapter: 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), environment: environment_name_for(app))
+
+        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 Sinatra 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 Sinatra datastore backend; use memory, redis, sqlite, postgres, or mysql' unless backend_name
+
+        return 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)
+        settings = settings_for(app)
+        root = settings.root if settings.respond_to?(:root)
+        Pathname.new(root || Dir.pwd)
+      end
+
+      def environment_name_for(app)
+        settings = settings_for(app)
+        environment = settings.environment if settings.respond_to?(:environment)
+        environment.to_s.empty? ? Kaal::Runtime::RuntimeContext.environment_name_from(ENV) : environment.to_s
+      end
+
+      def settings_for(app)
+        app.respond_to?(:settings) ? app.settings : app
+      end
+
+      def start_managed_scheduler!
+        return if Kaal.running?
+
+        start!
+        install_shutdown_hook
+      end
+
+      def install_shutdown_hook
+        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 Sinatra shutdown: #{e.message}")
+            end
+          end
+        end
+      end
+    end
+
+    # Sinatra extension that wires Kaal into classic and modular apps.
+    module Extension
+      def self.registered(app)
+        app.extend(ClassMethods)
+      end
+
+      # DSL helpers installed onto Sinatra apps.
+      module ClassMethods
+        def kaal(**)
+          Kaal::Sinatra.register!(self, **)
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,125 @@
+--- !ruby/object:Gem::Specification
+name: kaal-sinatra
+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: sinatra
+  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-Sinatra provides a thin integration layer that wires Kaal and
+  Kaal-Sequel into Sinatra 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/sinatra.rb
+- lib/kaal/sinatra/version.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-sinatra
+  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: Sinatra integration for Kaal, a distributed cron scheduler for Ruby.
+test_files: []