kaal 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3171d908e9cb61c59b265540ca3f8fbfece4ac67081b4fab19b45c5b371994e8
-  data.tar.gz: 19a7540e6594434fe227532fcd4a92435c57cb436a945c7b1f8a05d77e3c94bd
+  metadata.gz: f078489fc2106826b98a1890f15dd5aad38a627ef9db230bd11db3785dc66f86
+  data.tar.gz: 10ec39fb62e2082d7a8191153af335950fb14d584c0ed33737298baaa2b2f270
 SHA512:
-  metadata.gz: 2b28d2b723591834f9425b0ae9044a73e83fc8aa61c9b186a283c18e7282d91d461b8601b59c62e536c2fdc9d27c4a64b518fa438802577556166b8a529e996a
-  data.tar.gz: 5a1ea96d68f3e8b482b0e9d28639e390e2af5764a8a82138a8a5cd5e7c60c1d8ef7acf0fe808471066f5f3f462dbaab4c3cb96e12fca33d2ba13ffd46cbb797b
+  metadata.gz: 5be3591420c49e0149f58e6d76abdb3bfc7a7c10f2249754fb427f89e9ce414bad044d44fc17ed8016b4766182558a2a513598dcc212a0d899872f31007da19b
+  data.tar.gz: 60857c850fe9ca808fd198bcd8480ee63962bc1df5de69bab5953168aa7641f1a739c74d970c67b20a7f71d1858abe2a043ac004191b473a94aee7380cf8ce50

data/README.md

@@ -1,340 +1,132 @@
-# ⏰ 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, the plain Ruby CLI, and the optional SQL backend surfaces.
 
----
+## 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:
-
-- `--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"
+`kaal init` creates:
 
-production:
-  jobs:
-    - key: "reports:daily_digest"
-      cron: "<%= ENV.fetch('DAILY_DIGEST_CRON', '0 7 * * *') %>"
-      job_class: "DailyDigestJob"
-```
+- `config/kaal.rb`
+- `config/scheduler.yml`
 
-`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}}`.
+Supported backends:
 
-👉 [See full installation guide →](https://kaal.codevedas.com/install)
+- `memory`
+- `redis`
 
----
+If you want SQL persistence instead, add the runtime libraries your app uses, such as `sequel`, `activerecord`, `sqlite3`, `pg`, or `mysql2`, then configure one of the explicit `Kaal::Backend::*` SQL backends.
 
-## 🚀 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"
-```
+require 'redis'
 
-> 🈶 All tokens are i18n-based — override translations under `kaal.*` keys.
+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
+`job_class` must resolve to a Ruby constant that responds to one of:
 
-| 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 |
+- `.perform(*args, **kwargs)`
+- `.perform_later(*args, **kwargs)`
+- `.set(queue: ...).perform_later(*args, **kwargs)`
 
-📖 [See FAQ →](https://kaal.codevedas.com/faq)
+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!
+```
 
----
+## SQL Backends
 
-## 📄 License
+Use the explicit SQL backends when you want persisted registries:
 
-Released under the [MIT License](LICENSE).
-© 2025 **Codevedas Inc.** — All rights reserved.
+- `Kaal::Backend::SQLite`
+- `Kaal::Backend::Postgres`
+- `Kaal::Backend::MySQL`
+- `kaal-rails` for Rails-native install and auto-wiring

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/active_record_support.rb

@@ -0,0 +1,82 @@
+# 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'
+
+module Kaal
+  # Active Record migration/install support for SQL-backed Kaal backends.
+  module ActiveRecord
+    module_function
+
+    def install_postgres_migration(target_dir:, migration_name: 'Create Kaal Postgres Backend')
+      install_migrations(target_dir:, backend: 'postgres', migration_name:)
+    end
+
+    def install_mysql_migration(target_dir:, migration_name: 'Create Kaal MySQL Backend')
+      install_migrations(target_dir:, backend: 'mysql', migration_name:)
+    end
+
+    def install_sqlite_migration(target_dir:, migration_name: 'Create Kaal SQLite Backend')
+      install_migrations(target_dir:, backend: 'sqlite', migration_name:)
+    end
+
+    def install_migrations(target_dir:, backend:, migration_name: nil, time_source: -> { Time.now.utc })
+      class_name = normalize_migration_name(migration_name, fallback: default_migration_class_for(backend))
+      base_path = File.expand_path(target_dir)
+      FileUtils.mkdir_p(base_path)
+      templates = Kaal::Internal::ActiveRecord::MigrationTemplates.for_backend(backend)
+
+      templates.map.with_index do |(_name, contents), index|
+        suffix = underscore(class_name)
+        suffix = "#{suffix}_#{migration_suffixes_for(backend).fetch(index)}" if templates.length > 1
+        path = File.expand_path("#{(time_source.call + index).strftime('%Y%m%d%H%M%S')}_#{suffix}.rb", base_path)
+        File.write(path, contents)
+        path
+      end
+    end
+
+    def require_activerecord!
+      require 'active_record'
+      require 'active_support/inflector'
+    rescue LoadError => e
+      raise LoadError,
+            "#{e.message}. Add `gem 'activerecord'` to your Gemfile to use Active Record-backed Kaal SQL support.",
+            cause: e
+    end
+
+    def normalize_migration_name(name, fallback:)
+      normalized = name.to_s.each_char.with_object(+'') do |char, buffer|
+        if alphanumeric?(char)
+          buffer << char
+        elsif !buffer.empty? && !buffer.end_with?(' ')
+          buffer << ' '
+        end
+      end.split.map!(&:capitalize).join
+      normalized.empty? ? fallback : normalized
+    end
+
+    def underscore(value)
+      require_activerecord!
+      ::ActiveSupport::Inflector.underscore(value)
+    end
+
+    def default_migration_class_for(backend)
+      "CreateKaal#{backend.capitalize}Backend"
+    end
+
+    def migration_suffixes_for(backend)
+      return %w[dispatches locks definitions] if backend.to_s == 'sqlite'
+
+      %w[dispatches definitions]
+    end
+
+    def alphanumeric?(char)
+      char.between?('a', 'z') ||
+        char.between?('A', 'Z') ||
+        char.between?('0', '9')
+    end
+  end
+end

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