kaal 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3171d908e9cb61c59b265540ca3f8fbfece4ac67081b4fab19b45c5b371994e8
-  data.tar.gz: 19a7540e6594434fe227532fcd4a92435c57cb436a945c7b1f8a05d77e3c94bd
+  metadata.gz: 54a0eb1cebfc4adc18c4b4ed105d47bb26a84d3512fbce891243a356bca5715a
+  data.tar.gz: dd1fb18c3060c4688ea0f96c5628cd40001fb318b7745d411c46108fa06b45b3
 SHA512:
-  metadata.gz: 2b28d2b723591834f9425b0ae9044a73e83fc8aa61c9b186a283c18e7282d91d461b8601b59c62e536c2fdc9d27c4a64b518fa438802577556166b8a529e996a
-  data.tar.gz: 5a1ea96d68f3e8b482b0e9d28639e390e2af5764a8a82138a8a5cd5e7c60c1d8ef7acf0fe808471066f5f3f462dbaab4c3cb96e12fca33d2ba13ffd46cbb797b
+  metadata.gz: fda7173306897889b750707be46778bfc0b4893ce87759f30f060a37879212eab2731316a31c875acdcf0e7aad9db1caddbc11e7c0b0b16e3707edbfd1b1eec3
+  data.tar.gz: a8d64f8ca728665167e8be7ad5e1e6a417066f6016ff2b838aa47cde5aa3369045b1ea2c3aaf326ce4b00cc94d0f519ebe464978660ad13cc29f6db90cf3c834

data/README.md

@@ -1,340 +1,135 @@
-# ⏰ Kaal
+# Kaal
 
-> Kaal is a distributed cron scheduler for Ruby that safely executes scheduled tasks across multiple nodes.
+Distributed cron scheduling for plain Ruby.
 
-[![Gem](https://img.shields.io/gem/v/kaal.svg?style=flat-square)](https://rubygems.org/gems/kaal)
-[![CI](https://github.com/Code-Vedas/kaal/actions/workflows/ci.yml/badge.svg)](https://github.com/Code-Vedas/kaal/actions/workflows/ci.yml)
-[![Maintainability](https://qlty.sh/gh/Code-Vedas/projects/kaal/maintainability.svg)](https://qlty.sh/gh/Code-Vedas/projects/kaal)
-[![Code Coverage](https://qlty.sh/gh/Code-Vedas/projects/kaal/coverage.svg)](https://qlty.sh/gh/Code-Vedas/projects/kaal)
-![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)
-![PostgreSQL](https://img.shields.io/badge/PostgreSQL-12%2B-336791?style=flat-square&logo=postgresql&logoColor=white)
-![Redis](https://img.shields.io/badge/Redis-6%2B-d92b2b?style=flat-square&logo=redis&logoColor=white)
+`kaal` is the core engine gem. It owns scheduler/runtime behavior, the registry APIs, and the plain Ruby CLI. SQL persistence lives in adapter gems such as `kaal-sequel` and `kaal-activerecord`.
 
----
+## Installation
 
-## ✨ Overview
-
-`kaal` lets you **bind cron expressions to Ruby code or shell commands** without depending on any specific job system or scheduler.
-
-It guarantees that:
-
-- Each scheduled tick **enqueues work exactly once** across all running Ruby nodes.
-- You remain **agnostic** to your background job system (`ActiveJob`, `Sidekiq`, `Resque`, etc.).
-- Locks are coordinated safely via **Redis** or **PostgreSQL advisory locks**.
-- Cron syntax can be **validated, linted, humanized, and translated** with i18n.
-
----
-
-## 🧩 Why Kaal?
-
-| Problem                              | Kaal Solution                                         |
-| ------------------------------------ | ----------------------------------------------------- |
-| Multiple nodes running the same cron | Distributed locks → exactly-once execution            |
-| Cron syntax not human-friendly       | Built-in parser + `to_human` translations             |
-| Missed runs during downtime          | Configurable _lookback_ window replays missed ticks   |
-| Coupled to job system                | Scheduler-agnostic, works with any Ruby queue backend |
-
----
-
-## ⚙️ Installation
-
-Add to your Gemfile:
+Use `kaal` by itself when you want the engine plus non-SQL coordination backends.
 
 ```ruby
-gem "kaal"
+gem 'kaal'
 ```
 
-Then run:
+Then install and initialize:
 
 ```bash
 bundle install
-bin/rails g kaal:install --backend=sqlite
+bundle exec kaal init --backend=memory
 ```
 
-The install generator creates `config/initializers/kaal.rb` and, for database-backed backends, generates only the migrations you need:
+`kaal init` creates:
 
-- `--backend=sqlite`: dispatches, locks, and definitions tables
-- `--backend=postgres` or `--backend=mysql`: dispatches and definitions tables
-- `--backend=redis` or `--backend=memory`: no database migrations
-
-Example initializer (`config/initializers/kaal.rb`):
-
-```ruby
-Kaal.configure do |c|
-  # Choose your backend adapter
-  # See the Kaal documentation for backend-specific setup and the full
-  # configuration reference.
-  #
-  # Redis (recommended)
-  # c.backend = Kaal::Backend::RedisAdapter.new(Redis.new(url: ENV["REDIS_URL"]))
-
-  # or Postgres advisory locks
-  # c.backend = Kaal::Backend::PostgresAdapter.new
-
-  c.tick_interval    = 5      # seconds between scheduler ticks
-  c.window_lookback  = 120    # recover missed runs (seconds)
-  c.lease_ttl        = 125    # must be >= window_lookback + tick_interval
-  c.recovery_window = 3600
-  c.enable_dispatch_recovery = true
-  c.enable_log_dispatch_registry = false
-
-  # Scheduler file loading
-  c.scheduler_config_path = "config/scheduler.yml"
-  c.scheduler_conflict_policy = :error # :error, :code_wins, :file_wins
-  c.scheduler_missing_file_policy = :warn # :warn, :error
-end
-```
-
-Example scheduler file (`config/scheduler.yml`):
-
-```yaml
-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"
+- `config/kaal.rb`
+- `config/scheduler.yml`
 
-production:
-  jobs:
-    - key: "reports:daily_digest"
-      cron: "<%= ENV.fetch('DAILY_DIGEST_CRON', '0 7 * * *') %>"
-      job_class: "DailyDigestJob"
-```
+Supported backends:
 
-`scheduler.yml` supports ERB and environment sections (`defaults`, `development`, `test`, `production`, etc.).
-Allowed runtime placeholders in `args` and `kwargs` values (not keys): `{{fire_time.iso8601}}`, `{{fire_time.unix}}`, `{{idempotency_key}}`, `{{key}}`.
+- `memory`
+- `redis`
 
-👉 [See full installation guide →](https://kaal.codevedas.com/install)
+If you want SQL persistence instead, add one of:
 
----
+- `kaal-sequel` for Sequel-backed SQL in plain Ruby
+- `kaal-activerecord` for Active Record-backed SQL in plain Ruby
+- `kaal-rails` for Rails
 
-## 🚀 Quick Start
+## Configuration
 
-Register a scheduled job anywhere during boot (e.g., `config/initializers/kaal_jobs.rb`):
+Generated `config/kaal.rb` is the primary entrypoint:
 
 ```ruby
-Kaal.register(
-  key: "reports:weekly_summary",
-  cron: "0 9 * * 1", # every Monday at 9 AM
-  enqueue: ->(fire_time:, idempotency_key:) {
-    WeeklySummaryJob.perform_later(fire_time: fire_time, key: idempotency_key)
-  }
-)
-```
-
-Start the scheduler:
-
-`Kaal` does **not** auto-start by default. Start it explicitly via `Kaal.start!` or `kaal:start`.
-
-```bash
-bundle exec rails kaal:start
-```
-
-> 💡 Recommended: run as a **dedicated process** in production (Procfile, systemd, Kubernetes).
-
----
-
-## 🧰 CLI & Rake Tasks
-
-### CLI Examples
-
-```bash
-$ kaal explain "*/15 * * * *"
-Every 15 minutes
-
-$ kaal next "0 9 * * 1" --count 3
-2025-11-03 09:00:00 UTC
-2025-11-10 09:00:00 UTC
-2025-11-17 09:00:00 UTC
-```
-
-### Rails Tasks
-
-```bash
-bin/rails kaal:start          # Start scheduler loop
-bin/rails kaal:status         # Show registry & configuration
-bin/rails kaal:tick           # Trigger one tick manually
-bin/rails kaal:explain["*/5 * * * *"] # Humanize cron expression
+require 'kaal'
+
+Kaal.configure do |config|
+  config.backend = Kaal::Backend::MemoryAdapter.new
+  config.tick_interval = 5
+  config.window_lookback = 120
+  config.lease_ttl = 125
+  config.scheduler_config_path = 'config/scheduler.yml'
+end
 ```
 
----
-
-## 🧠 Cron Utilities
+Redis path:
 
 ```ruby
-Kaal.valid?("0 * * * *")     # => true
-Kaal.simplify("0 0 * * *")   # => "@daily"
-Kaal.lint("*/61 * * * *")    # => ["invalid minute step: 61"]
-
-I18n.locale = :fr
-Kaal.to_human("0 9 * * 1")   # => "À 09h00 chaque lundi"
-```
-
-> 🈶 All tokens are i18n-based — override translations under `kaal.*` keys.
+require 'redis'
 
----
+redis = Redis.new(url: ENV.fetch('REDIS_URL'))
 
-## 🧱 Running the Scheduler
-
-Run the scheduler as a dedicated process in production.  
-Do not run it inside web server processes by default.
+Kaal.configure do |config|
+  config.backend = Kaal::Backend::RedisAdapter.new(redis)
+  config.scheduler_config_path = 'config/scheduler.yml'
+end
+```
 
-**Procfile (process manager):**
+Time zone behavior is explicit:
 
-```procfile
-web:       bundle exec puma -C config/puma.rb
-scheduler: bundle exec rails kaal:start
-```
+- use `config.time_zone = 'America/Toronto'` when needed
+- otherwise scheduling runs in `UTC`
 
-**systemd unit:**
-
-```ini
-[Unit]
-Description=Kaal scheduler
-After=network.target
-
-[Service]
-Type=simple
-User=deploy
-WorkingDirectory=/var/apps/myapp/current
-Environment=RAILS_ENV=production
-ExecStart=/usr/bin/bash -lc 'bundle exec rails kaal:start'
-ExecStartPre=/usr/bin/bash -lc 'bundle exec rails kaal:status'
-ExecReload=/bin/kill -TERM $MAINPID
-Restart=always
-RestartSec=5
-
-[Install]
-WantedBy=multi-user.target
-```
+## Scheduler File
 
-**Kubernetes Deployment:**
+Default scheduler definitions live at `config/scheduler.yml`:
 
 ```yaml
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: kaal-scheduler
-spec:
-  replicas: 1
-  selector:
-    matchLabels:
-      app: kaal-scheduler
-  template:
-    metadata:
-      labels:
-        app: kaal-scheduler
-    spec:
-      containers:
-        - name: scheduler
-          image: your-app:latest
-          command: ["bash", "-lc", "bundle exec rails kaal:start"]
+defaults:
+  jobs:
+    - key: "example:heartbeat"
+      cron: "*/5 * * * *"
+      job_class: "ExampleHeartbeatJob"
+      enabled: true
+      args:
+        - "{{fire_time.iso8601}}"
+      kwargs:
+        idempotency_key: "{{idempotency_key}}"
 ```
 
-For Kubernetes, the scheduler process is the container's main process; if it exits, Kubernetes restarts it.  
-Do not use `kaal:status` as a liveness/readiness probe for scheduler thread health because it runs in a separate process.
-
-Use one of these for health checks:
-
-- Process-level checks from your runtime/supervisor for the main scheduler process.
-- A shared heartbeat/lease signal (Redis, Postgres, pidfile, etc.) written by the scheduler and read by probes.
-
----
-
-## 🔍 Troubleshooting
-
-| Symptom                    | Likely Cause          | Fix                                      |
-| -------------------------- | --------------------- | ---------------------------------------- |
-| Jobs run multiple times    | Using memory lock     | Use Redis or Postgres adapter            |
-| Missed jobs after downtime | Short lookback window | Increase `window_lookback`               |
-| Scheduler exits early      | Normal SIGTERM        | Exits gracefully after tick              |
-| Redis timeout              | Network latency       | Increase Redis timeout or switch adapter |
+`job_class` must resolve to a Ruby constant that responds to one of:
 
-📖 [See FAQ →](https://kaal.codevedas.com/faq)
+- `.perform(*args, **kwargs)`
+- `.perform_later(*args, **kwargs)`
+- `.set(queue: ...).perform_later(*args, **kwargs)`
 
----
+For plain Ruby `.perform` jobs, Kaal treats the dispatch as successful unless the job raises an exception. Return values are ignored.
 
-## 🧪 Testing Example
-
-```ruby
-RSpec.describe "multi-node safety" do
-  it "dispatches exactly once across two threads" do
-    redis = FakeRedis::Redis.new
-    lock  = Kaal::Backend::RedisAdapter.new(redis)
-    Kaal.configure { |c| c.backend = lock }
-
-    threads = 2.times.map { Thread.new { Kaal.tick! } }
-    threads.each(&:join)
-
-    expect(redis.keys.grep(/dispatch/).size).to eq(1)
-  end
-end
-```
-
-### Local Test Commands
-
-Run the fast unit suite from the gem directory:
+## CLI
 
 ```bash
-bin/rspec-unit
+bundle exec kaal init --backend=memory
+bundle exec kaal start
+bundle exec kaal status
+bundle exec kaal tick
+bundle exec kaal explain "*/15 * * * *"
+bundle exec kaal next "0 9 * * 1" --count 3
 ```
 
-Run end-to-end adapter coverage with the same entrypoint used in CI:
+## E2E Verification
 
 ```bash
 bin/rspec-e2e memory
-bin/rspec-e2e sqlite
-DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/kaal_test bin/rspec-e2e pg
-DATABASE_URL=mysql2://root:rootROOT\!1@127.0.0.1:3306/kaal_test bin/rspec-e2e mysql
 REDIS_URL=redis://127.0.0.1:6379/0 bin/rspec-e2e redis
 ```
 
-`pg` and `mysql` require `DATABASE_URL`. `redis` requires `REDIS_URL`. `memory` and `sqlite` use local test defaults.
-
----
-
-## 🧩 Roadmap
-
-| Area             | Description                      | Label     |
-| ---------------- | -------------------------------- | --------- |
-| Registry & API   | Cron registration and validation | `feature` |
-| Coordinator Loop | Safe ticking and dispatch        | `feature` |
-| Lock Adapters    | Redis / Postgres                 | `build`   |
-| CLI Tool         | `kaal` executable                | `build`   |
-| i18n Humanizer   | Multi-language support           | `lang`    |
-| Docs & Examples  | Developer onboarding             | `lang`    |
+## Runtime API
 
----
-
-## 🤝 Contributing
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/my-feature`)
-3. Run tests (`bundle exec rspec`)
-4. Open a PR using the [Feature Request template](.github/ISSUE_TEMPLATE/feature_request.md)
-
-Labels: `feature`, `build`, `ci`, `lang`
-
----
-
-## 📚 Documentation
+```ruby
+Kaal.register(
+  key: 'reports:daily',
+  cron: '0 9 * * *',
+  enqueue: ->(fire_time:, idempotency_key:) {
+    ReportsJob.perform(fire_time: fire_time, idempotency_key: idempotency_key)
+  }
+)
 
-- [Overview & Motivation](https://kaal.codevedas.com)
-- [Installation](https://kaal.codevedas.com/install)
-- [Usage](https://kaal.codevedas.com/usage)
-- [FAQ / Troubleshooting](https://kaal.codevedas.com/faq)
+Kaal.start!
+```
 
----
+## Adapter Gems
 
-## 📄 License
+Use adapter gems when you want persisted SQL registries:
 
-Released under the [MIT License](LICENSE).
-© 2025 **Codevedas Inc.** — All rights reserved.
+- `kaal-sequel` for Sequel-backed persistence
+- `kaal-activerecord` for Active Record-backed persistence
+- `kaal-rails` for Rails plugin integration over `kaal-activerecord`

data/Rakefile

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

data/config/kaal.rb

@@ -0,0 +1,15 @@
+# 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'
+
+Kaal.configure do |config|
+  config.backend = Kaal::Backend::MemoryAdapter.new
+  config.tick_interval = 5
+  config.window_lookback = 120
+  config.lease_ttl = 125
+  config.scheduler_config_path = 'config/scheduler.yml'
+end

data/config/scheduler.yml

@@ -0,0 +1,12 @@
+defaults:
+  jobs:
+    - key: "example:heartbeat"
+      cron: "*/5 * * * *"
+      job_class: "ExampleHeartbeatJob"
+      enabled: true
+      args:
+        - "{{fire_time.iso8601}}"
+      kwargs:
+        idempotency_key: "{{idempotency_key}}"
+      metadata:
+        owner: "ops"

data/{lib/tasks/kaal_tasks.rake → exe/kaal}

@@ -1,10 +1,12 @@
+#!/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.
+gemfile_path = File.expand_path('../Gemfile', __dir__)
+require 'bundler/setup' if File.exist?(gemfile_path)
+require 'kaal/cli'
 
-require 'kaal/rake_tasks'
-
-Kaal::RakeTasks.install
+Kaal::CLI.start(ARGV)

data/lib/kaal/backend/adapter.rb

@@ -4,7 +4,6 @@
 #
 # 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 Backend
     ##

data/lib/kaal/backend/dispatch_attempt_logger.rb

@@ -0,0 +1,33 @@
+# 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 'socket'
+
+module Kaal
+  module Backend
+    # Logs dispatch attempts through a backend-provided dispatch registry.
+    class DispatchAttemptLogger
+      def initialize(configuration:, dispatch_registry_provider:, logger: nil, node_id_provider: Socket.method(:gethostname))
+        @configuration = configuration
+        @dispatch_registry_provider = dispatch_registry_provider
+        @logger = logger
+        @node_id_provider = node_id_provider
+      end
+
+      def call(lock_key)
+        return unless @configuration.enable_log_dispatch_registry
+
+        registry = @dispatch_registry_provider.call
+        return unless registry
+
+        cron_key, fire_time = DispatchLogging.parse_lock_key(lock_key)
+        registry.log_dispatch(cron_key, fire_time, @node_id_provider.call, 'dispatched')
+      rescue StandardError => e
+        (@logger || @configuration.logger)&.error("Failed to log dispatch for #{lock_key}: #{e.message}")
+      end
+    end
+  end
+end

data/lib/kaal/backend/dispatch_logging.rb

@@ -4,8 +4,7 @@
 #
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
-
-require 'socket'
+require_relative 'dispatch_attempt_logger'
 
 module Kaal
   module Backend
@@ -25,6 +24,10 @@ module Kaal
     #     end
     #   end
     module DispatchLogging
+      def dispatch_registry
+        nil
+      end
+
       ##
       # Log a dispatch attempt via the dispatch registry.
       #
@@ -33,23 +36,7 @@ module Kaal
       # @param key [String] the lock key (format: "namespace:dispatch:cron_key:fire_time")
       # @return [void]
       def log_dispatch_attempt(key)
-        logger = nil
-        logging_enabled = Kaal.configuration.then do |configuration|
-          logger = configuration.logger
-          configuration.enable_log_dispatch_registry
-        end
-        return unless logging_enabled
-        return unless respond_to?(:dispatch_registry)
-
-        registry = dispatch_registry
-        return unless registry
-
-        cron_key, fire_time = parse_lock_key(key)
-        node_id = Socket.gethostname
-
-        registry.log_dispatch(cron_key, fire_time, node_id, 'dispatched')
-      rescue StandardError => e
-        logger&.error("Failed to log dispatch for #{key}: #{e.message}")
+        dispatch_attempt_logger.call(key)
       end
 
       ##
@@ -67,13 +54,39 @@ module Kaal
 
       def self.parse_lock_key(key)
         parts = key.split(':')
-        fire_time_unix = parts.pop.to_i
-        2.times { parts.shift } # Remove namespace and "dispatch"
-        cron_key = parts.join(':')
-        fire_time = Time.at(fire_time_unix)
+        invalid_message = "Invalid dispatch lock key format: #{key.inspect}"
+        dispatch_index = parts[0...-1].rindex('dispatch')
+        timestamp = parts[-1]
+        valid_key = parts.length >= 4 && dispatch_index&.positive? && timestamp.match?(/\A\d+\z/)
+        validate_lock_key!(valid_key, invalid_message)
+
+        fire_time_unix = timestamp.to_i
+        cron_key = parts[(dispatch_index + 1)...-1].join(':')
+        validate_lock_key!(!cron_key.empty?, invalid_message)
+
+        fire_time = Time.at(fire_time_unix).utc
 
         [cron_key, fire_time]
       end
+
+      def self.validate_lock_key!(valid, message)
+        invalid_dispatch_lock_key!(message) unless valid
+      end
+      private_class_method :validate_lock_key!
+
+      def self.invalid_dispatch_lock_key!(message)
+        raise ArgumentError, message
+      end
+      private_class_method :invalid_dispatch_lock_key!
+
+      private
+
+      def dispatch_attempt_logger
+        @dispatch_attempt_logger ||= DispatchAttemptLogger.new(
+          configuration: Kaal.configuration,
+          dispatch_registry_provider: -> { dispatch_registry }
+        )
+      end
     end
   end
 end

data/lib/kaal/backend/dispatch_registry_accessor.rb

@@ -0,0 +1,43 @@
+# 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 Backend
+    # Reads dispatch registry state through the configured backend adapter.
+    class DispatchRegistryAccessor
+      def initialize(configuration:)
+        @configuration = configuration
+      end
+
+      def dispatched?(key, fire_time)
+        registry = fetch_registry
+        return false unless registry
+
+        registry.dispatched?(key, fire_time)
+      rescue StandardError => e
+        @configuration.logger&.warn("Error checking dispatch status for #{key}: #{e.message}")
+        false
+      end
+
+      def registry
+        fetch_registry
+      rescue StandardError => e
+        @configuration.logger&.warn("Error accessing dispatch registry: #{e.message}")
+        nil
+      end
+
+      private
+
+      def fetch_registry
+        adapter = @configuration.backend
+        return nil unless adapter
+        return nil unless adapter.respond_to?(:dispatch_registry)
+
+        adapter.dispatch_registry
+      end
+    end
+  end
+end