kaal 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d9c81a663455de1a4bc16743a0ec58df8e42ac5d49ec6fa2bf291f131af6772b
+  data.tar.gz: d803aba6a93b004c5b97da505a0c7021e0a50b0243c31bd537c2a5d811d04f55
+SHA512:
+  metadata.gz: 5f4142e84f230f1d82b6601162124ee9e846df08322486c613d6a35c049fc4d40054c7d1266c41929d9ac63a873609fb00d6b9ba50a9cf92c9d4e003bc6cc2a1
+  data.tar.gz: 0caaa0787fa7fb8e13aeb917221be83b657568fda4a6238df2e523fe0945a9a87a9a163ac638d4040cd9ef277c5a88c3c37612643105c0852d12693d04aff44e

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 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,340 @@
+# ⏰ Kaal
+
+> Kaal is a distributed cron scheduler for Ruby that safely executes scheduled tasks across multiple nodes.
+
+[![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)
+
+---
+
+## ✨ 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:
+
+```ruby
+gem "kaal"
+```
+
+Then run:
+
+```bash
+bundle install
+bin/rails g kaal:install --backend=sqlite
+```
+
+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"
+
+production:
+  jobs:
+    - key: "reports:daily_digest"
+      cron: "<%= ENV.fetch('DAILY_DIGEST_CRON', '0 7 * * *') %>"
+      job_class: "DailyDigestJob"
+```
+
+`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}}`.
+
+👉 [See full installation guide →](https://kaal.codevedas.com/install)
+
+---
+
+## 🚀 Quick Start
+
+Register a scheduled job anywhere during boot (e.g., `config/initializers/kaal_jobs.rb`):
+
+```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
+```
+
+---
+
+## 🧠 Cron Utilities
+
+```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.
+
+---
+
+## 🧱 Running the Scheduler
+
+Run the scheduler as a dedicated process in production.  
+Do not run it inside web server processes by default.
+
+**Procfile (process manager):**
+
+```procfile
+web:       bundle exec puma -C config/puma.rb
+scheduler: bundle exec rails kaal:start
+```
+
+**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
+```
+
+**Kubernetes Deployment:**
+
+```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"]
+```
+
+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 |
+
+📖 [See FAQ →](https://kaal.codevedas.com/faq)
+
+---
+
+## 🧪 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:
+
+```bash
+bin/rspec-unit
+```
+
+Run end-to-end adapter coverage with the same entrypoint used in CI:
+
+```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`    |
+
+---
+
+## 🤝 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
+
+- [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)
+
+---
+
+## 📄 License
+
+Released under the [MIT License](LICENSE).
+© 2025 **Codevedas Inc.** — All rights reserved.

data/Rakefile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+APP_RAKEFILE = File.expand_path('spec/dummy/Rakefile', __dir__)
+load 'rails/tasks/engine.rake'
+require 'bundler/gem_tasks'

data/app/models/kaal/cron_definition.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Kaal
+  # Persistent scheduler definition model.
+  class CronDefinition < ApplicationRecord
+    self.table_name = 'kaal_definitions'
+
+    before_validation :ensure_metadata
+
+    validates :key, presence: true, uniqueness: true
+    validates :cron, presence: true
+    validates :source, presence: true
+    validates :enabled, inclusion: { in: [true, false] }
+
+    scope :enabled, -> { where(enabled: true) }
+    scope :disabled, -> { where(enabled: false) }
+    scope :by_source, ->(source) { where(source: source) }
+
+    def self.upsert_definition!(key:, cron:, enabled:, source:, metadata:)
+      persist_definition(find_or_initialize_by(key: key), cron:, enabled:, source:, metadata:)
+    rescue ActiveRecord::RecordNotUnique
+      persist_definition(find_by!(key: key), cron:, enabled:, source:, metadata:)
+    end
+
+    def to_definition_hash
+      {
+        key: key,
+        cron: cron,
+        enabled: enabled,
+        source: source,
+        metadata: metadata || {},
+        created_at: created_at,
+        updated_at: updated_at,
+        disabled_at: disabled_at
+      }
+    end
+
+    def destroy_and_return_definition_hash
+      definition_hash = to_definition_hash
+      destroy!
+      definition_hash
+    end
+
+    def self.persist_definition(record, cron:, enabled:, source:, metadata:)
+      disabled_at = if enabled
+                      nil
+                    elsif record.new_record? || record.enabled != false
+                      Time.current
+                    else
+                      record.disabled_at
+                    end
+
+      record.assign_attributes(
+        cron: cron,
+        enabled: enabled,
+        source: source,
+        metadata: metadata,
+        disabled_at:
+      )
+      record.save!
+      record
+    end
+    private_class_method :persist_definition
+
+    private
+
+    def ensure_metadata
+      self.metadata ||= {}
+    end
+  end
+end

data/app/models/kaal/cron_dispatch.rb

@@ -0,0 +1,50 @@
+# 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
+  ##
+  # Audit model for tracking cron job dispatch attempts across the cluster.
+  #
+  # CronDispatch records information about each cron job that was dispatched,
+  # including the cron key, scheduled fire time, actual dispatch time,
+  # the node that dispatched it, and the dispatch status.
+  #
+  # This model is used by the PostgreSQL lock adapter for observability and
+  # debugging in distributed deployments. You can use this table to:
+  # - Verify that jobs are only dispatched once per fire_time
+  # - Track which node dispatched each job
+  # - Monitor dispatch latency
+  # - Audit job execution history
+  #
+  # @example Query dispatch history
+  #   Kaal::CronDispatch.where(
+  #     key: 'send_emails',
+  #     status: 'dispatched'
+  #   ).order(fire_time: :desc).limit(10)
+  #
+  # @example Find all dispatches from a specific node
+  #   Kaal::CronDispatch.where(node_id: 'worker1').order(dispatched_at: :desc)
+  class CronDispatch < ApplicationRecord
+    self.table_name = 'kaal_dispatches'
+
+    ##
+    # Validations
+    validates :key, presence: true
+    validates :fire_time, presence: true
+    validates :dispatched_at, presence: true
+    validates :node_id, presence: true
+    validates :status, presence: true, inclusion: { in: %w[dispatched failed] }
+
+    ##
+    # Scopes for common queries
+    scope :recent, ->(limit = 100) { order(dispatched_at: :desc).limit(limit) }
+    scope :by_key, ->(key) { where(key: key) }
+    scope :by_node, ->(node_id) { where(node_id: node_id) }
+    scope :by_status, ->(status) { where(status: status) }
+    scope :since, ->(timestamp) { where('dispatched_at >= ?', timestamp) }
+  end
+end

data/app/models/kaal/cron_lock.rb

@@ -0,0 +1,38 @@
+# 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
+  ##
+  # Model for distributed lock records (database-backed).
+  #
+  # Used by the database-backed adapter (SQLiteAdapter) to store lock state in a database table.
+  # Works with any ActiveRecord-supported SQL database (SQLite, PostgreSQL, MySQL, etc.).
+  # Each row represents a held lock with an expiration time.
+  class CronLock < ApplicationRecord
+    self.table_name = 'kaal_locks'
+
+    validates :key, presence: true, uniqueness: true
+    validates :acquired_at, presence: true
+    validates :expires_at, presence: true
+
+    ##
+    # Find and delete any expired locks (cleanup).
+    #
+    # @return [Integer] number of locks deleted
+    def self.cleanup_expired
+      where('expires_at < ?', Time.current).delete_all
+    end
+
+    ##
+    # Check if this lock is still valid (not expired).
+    #
+    # @return [Boolean] true if not expired
+    def not_expired?
+      expires_at > Time.current
+    end
+  end
+end

data/config/locales/en.yml

@@ -0,0 +1,46 @@
+en:
+  kaal:
+    every: "every"
+    at: "at"
+    and: "and"
+    time:
+      minute: "minute"
+      minutes: "minutes"
+      hour: "hour"
+      hours: "hours"
+      day: "day"
+      days: "days"
+      week: "week"
+      weeks: "weeks"
+      month: "month"
+      months: "months"
+    weekdays:
+      "0": "Sunday"
+      "1": "Monday"
+      "2": "Tuesday"
+      "3": "Wednesday"
+      "4": "Thursday"
+      "5": "Friday"
+      "6": "Saturday"
+    months:
+      "1": "January"
+      "2": "February"
+      "3": "March"
+      "4": "April"
+      "5": "May"
+      "6": "June"
+      "7": "July"
+      "8": "August"
+      "9": "September"
+      "10": "October"
+      "11": "November"
+      "12": "December"
+    phrases:
+      daily: "Daily"
+      weekly: "Weekly"
+      monthly: "Monthly"
+      hourly: "Hourly"
+      yearly: "Yearly"
+      at_time: "At %{time}"
+      every_interval: "Every %{count} %{unit}"
+      cron_expression: "Cron: %{expression}"

data/lib/generators/kaal/install/install_generator.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module Kaal
+  module Generators
+    # Installs the database migrations needed for the selected backend.
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      class_option :backend,
+                   type: :string,
+                   default: 'sqlite',
+                   desc: 'Backend to install migrations for: sqlite, postgres, mysql, redis, memory'
+
+      def create_initializer
+        template 'kaal.rb.tt', 'config/initializers/kaal.rb'
+      end
+
+      def create_scheduler_config
+        template 'scheduler.yml.tt', 'config/scheduler.yml'
+      end
+
+      def install_migrations
+        templates = migration_templates
+        return say_status(:skip, "No database migrations required for #{normalized_backend} backend", :yellow) if templates.empty?
+
+        templates.each do |template_name|
+          migration_template "#{template_name}.rb.tt", "db/migrate/#{template_name}.rb"
+        end
+      end
+
+      def self.next_migration_number(dirname)
+        ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      private
+
+      def migration_templates
+        case normalized_backend
+        when 'sqlite', 'database'
+          %w[
+            create_kaal_dispatches
+            create_kaal_locks
+            create_kaal_definitions
+          ]
+        when 'postgres', 'mysql'
+          %w[
+            create_kaal_dispatches
+            create_kaal_definitions
+          ]
+        when 'memory', 'redis'
+          []
+        else
+          raise Thor::Error, "Unsupported backend '#{options['backend']}'. Use sqlite, postgres, mysql, redis, or memory."
+        end
+      end
+
+      def normalized_backend
+        options['backend'].to_s.downcase
+      end
+    end
+  end
+end

data/lib/generators/kaal/install/templates/create_kaal_definitions.rb.tt

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Creates the persisted cron definitions table for database-backed definitions.
+class CreateKaalDefinitions < ActiveRecord::Migration[7.0]
+  def change
+    create_table :kaal_definitions do |t|
+      t.string :key, null: false, limit: 255
+      t.string :cron, null: false, limit: 255
+      t.boolean :enabled, null: false, default: true
+      t.string :source, null: false, limit: 50, default: 'code'
+      t.json :metadata, null: false
+      t.datetime :disabled_at
+
+      t.timestamps
+    end
+
+    add_index :kaal_definitions, :key, unique: true
+    add_index :kaal_definitions, :enabled
+    add_index :kaal_definitions, :source
+  end
+end

data/lib/generators/kaal/install/templates/create_kaal_dispatches.rb.tt

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Creates the dispatch records table for database-backed dispatch logging.
+class CreateKaalDispatches < ActiveRecord::Migration[7.0]
+  def change
+    create_table :kaal_dispatches do |t|
+      t.string :key, null: false, limit: 255
+      t.datetime :fire_time, null: false
+      t.datetime :dispatched_at, null: false
+      t.string :node_id, null: false, limit: 255
+      t.string :status, null: false, limit: 50, default: 'dispatched'
+
+      t.timestamps
+    end
+
+    add_index :kaal_dispatches, %i[key fire_time], unique: true
+    add_index :kaal_dispatches, :dispatched_at
+    add_index :kaal_dispatches, :status
+  end
+end