kaal-hanami 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a23772c397096d568be16ed50e2b9ddfb7f26d6935756a9e2338c18eec699055
+  data.tar.gz: 44a53add8dc6b3f8d67d025196025f212985acfd672645d437e9114560e90e64
+SHA512:
+  metadata.gz: 0c4ba8e7331404d75190dae4e72034967d3997adb328e353e9f0efac91b06ecc082522bb7efcd8fffd4cdb41d88f1331f6f3b4409c145dd0e5cfb5fb3c9f3bdf
+  data.tar.gz: 1dea739720d9b1797732d75294adf8af1f15b253930a1d00e86cbb3b258959bd3c5a50acd24386f37c671abb04ccfdb07b367ceb8f1a571a5dd9575a393101ac

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

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/hanami/middleware.rb

@@ -0,0 +1,45 @@
+# 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 Hanami
+    # Rack middleware that bootstraps Kaal for Hanami applications.
+    class Middleware
+      def initialize(
+        app,
+        hanami_app:,
+        backend: nil,
+        database: nil,
+        redis: nil,
+        scheduler_config_path: 'config/scheduler.yml',
+        namespace: nil,
+        start_scheduler: false,
+        adapter: nil,
+        root: nil,
+        environment: nil
+      )
+        @app = app
+
+        Kaal::Hanami.register!(
+          hanami_app,
+          backend:,
+          database:,
+          redis:,
+          scheduler_config_path:,
+          namespace:,
+          start_scheduler:,
+          adapter:,
+          root:,
+          environment:
+        )
+      end
+
+      def call(env)
+        @app.call(env)
+      end
+    end
+  end
+end

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

data/lib/kaal/hanami.rb

@@ -0,0 +1,198 @@
+# 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 'hanami'
+require 'kaal/hanami/version'
+require 'kaal/hanami/middleware'
+
+module Kaal
+  # Hanami integration surface for Kaal.
+  module Hanami
+    class << self
+      def configure!(app, **)
+        app.config.middleware.use(Kaal::Hanami::Middleware, hanami_app: app, **)
+        app
+      end
+
+      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 Hanami 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 Hanami 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: runtime_environment_name(environment)
+        )
+
+        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.config.root if app.respond_to?(:config) && app.config.respond_to?(:root)
+        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.config.env if app.respond_to?(:config) && app.config.respond_to?(:env)
+        return app_environment.to_s unless app_environment.to_s.empty?
+
+        runtime_environment_name(nil)
+      end
+
+      def runtime_environment_name(environment)
+        explicit_environment = environment.to_s.strip
+        return explicit_environment unless explicit_environment.empty?
+
+        hanami_env = ENV['HANAMI_ENV'].to_s.strip
+        return hanami_env unless hanami_env.empty?
+
+        return ::Hanami.env.to_s if defined?(::Hanami) && ::Hanami.respond_to?(:env)
+
+        Kaal::Runtime::RuntimeContext.environment_name_from(ENV)
+      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 Hanami shutdown: #{e.message}")
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,126 @@
+--- !ruby/object:Gem::Specification
+name: kaal-hanami
+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: hanami
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !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'
+description: "    Kaal-Hanami provides a thin integration layer that wires Kaal and
+  Kaal-Sequel into Hanami 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/hanami.rb
+- lib/kaal/hanami/middleware.rb
+- lib/kaal/hanami/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-hanami
+  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: Hanami integration for Kaal, a distributed cron scheduler for Ruby.
+test_files: []