rails_cron 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d26dbece688aa7396ae1e25181a68e9533fdf63d46d2c52c7425ccb61f92fa12
+  data.tar.gz: 1fd1a1f048c6e5afc26650b20bf6d9a6ba76571a541d86980087f2c1f64b6e59
+SHA512:
+  metadata.gz: b020b0b130364c6194d91dd3480ebbdb3915519f6a3e707e1a6d895f45ca4d288b61f77720d95b86566a82056bf7a1290fe7bc99cd54d0c7edff9214f9c04850
+  data.tar.gz: cceba70a62f2bcf14471dc7c824fa110b8a2ff0258206862517e0bbf4a6aad40fffc23213a58db1af961b96fc7eb2188f40c5cd16a7ebf41885207417956cdc0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 The rails_cron 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,247 @@
+# ⏰ RailsCron
+
+> First release 0.1.0 is empty gem.
+> 🕒 A scheduler-agnostic, multi-node-safe cron runner for Ruby and Rails — with Redis or Postgres advisory locks.
+
+[![Gem](https://img.shields.io/gem/v/rails_cron.svg?style=flat-square)](https://rubygems.org/gems/rails_cron)
+[![CI](https://github.com/Code-Vedas/rails_cron/actions/workflows/ci.yml/badge.svg)](https://github.com/Code-Vedas/rails_cron/actions/workflows/ci.yml)
+[![Maintainability](https://qlty.sh/gh/Code-Vedas/projects/rails_cron/maintainability.svg)](https://qlty.sh/gh/Code-Vedas/projects/rails_cron)
+[![Code Coverage](https://qlty.sh/gh/Code-Vedas/projects/rails_cron/coverage.svg)](https://qlty.sh/gh/Code-Vedas/projects/rails_cron)
+![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
+
+`rails_cron` lets you **bind cron expressions to Ruby code or shell commands** —  
+without depending on any specific job system or scheduler (like Sidekiq-Cron or Rufus).
+
+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 RailsCron?
+
+| Problem                              | RailsCron 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 "rails_cron"
+```
+
+Then run:
+
+```bash
+bundle install
+bin/rails g rails_cron:install
+```
+
+Example initializer (`config/initializers/rails_cron.rb`):
+
+```ruby
+RailsCron.configure do |c|
+  # Choose your distributed lock adapter
+  # Redis (recommended)
+  # c.lock_adapter = RailsCron::Lock::Redis.new(url: ENV["REDIS_URL"])
+
+  # or Postgres advisory locks
+  # c.lock_adapter = RailsCron::Lock::Postgres.new(connection: ActiveRecord::Base.connection)
+
+  c.tick_interval    = 5      # seconds between scheduler ticks
+  c.window_lookback  = 120    # recover missed runs (seconds)
+  c.lease_ttl        = 60     # lock TTL in seconds
+end
+```
+
+👉 [See full installation guide →](https://rails-cron.codevedas.com/install)
+
+---
+
+## 🚀 Quick Start
+
+Register a scheduled job anywhere during boot (e.g., `config/initializers/rails_cron_jobs.rb`):
+
+```ruby
+RailsCron.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:
+
+```bash
+bundle exec rails rails_cron:start
+```
+
+> 💡 Recommended: run as a **dedicated process** in production (Procfile, systemd, Kubernetes).
+
+---
+
+## 🧰 CLI & Rake Tasks
+
+### CLI Examples
+
+```bash
+$ rails-cron explain "*/15 * * * *"
+Every 15 minutes
+
+$ rails-cron 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 rails_cron:start          # Start scheduler loop
+bin/rails rails_cron:status         # Show registry & configuration
+bin/rails rails_cron:tick           # Trigger one tick manually
+bin/rails rails_cron:explain["*/5 * * * *"] # Humanize cron expression
+```
+
+---
+
+## 🧠 Cron Utilities
+
+```ruby
+RailsCron.valid?("0 * * * *")     # => true
+RailsCron.simplify("0 0 * * *")   # => "@daily"
+RailsCron.lint("*/61 * * * *")    # => ["invalid minute step: 61"]
+
+I18n.locale = :fr
+RailsCron.to_human("0 9 * * 1")   # => "À 09h00 chaque lundi"
+```
+
+> 🈶 All tokens are i18n-based — override translations under `rails_cron.*` keys.
+
+---
+
+## 🧱 Running the Scheduler
+
+**Procfile (Heroku / Foreman):**
+
+```procfile
+web:       bundle exec puma -C config/puma.rb
+scheduler: bundle exec rails rails_cron:start
+```
+
+**systemd unit:**
+
+```ini
+[Service]
+Type=simple
+WorkingDirectory=/var/apps/myapp/current
+ExecStart=/usr/bin/bash -lc 'bundle exec rails rails_cron:start'
+Restart=always
+```
+
+**Kubernetes Deployment:**
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: rails-cron
+spec:
+  replicas: 1
+  template:
+    spec:
+      containers:
+        - name: scheduler
+          image: your-app:latest
+          command: ["bash", "-lc", "bundle exec rails rails_cron:start"]
+```
+
+---
+
+## 🔍 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://rails-cron.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  = RailsCron::Lock::Redis.new(client: redis)
+    RailsCron.configure { |c| c.lock_adapter = lock }
+
+    threads = 2.times.map { Thread.new { RailsCron.tick! } }
+    threads.each(&:join)
+
+    expect(redis.keys.grep(/dispatch/).size).to eq(1)
+  end
+end
+```
+
+---
+
+## 🧩 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         | `rails-cron` 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://rails-cron.codevedas.com)
+- [Installation](https://rails-cron.codevedas.com/install)
+- [Usage](https://rails-cron.codevedas.com/usage)
+- [FAQ / Troubleshooting](https://rails-cron.codevedas.com/faq)
+
+---
+
+## 📄 License
+
+Released under the [MIT License](LICENSE).
+© 2025 **Codevedas Inc.** — All rights reserved.

data/Rakefile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+require 'bundler/gem_tasks'

data/lib/rails_cron/railtie.rb

@@ -0,0 +1,13 @@
+# 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.
+
+# Define a Railtie to integrate with Rails applications
+module RailsCron
+  # Define the Railtie class
+  class Railtie < ::Rails::Railtie
+  end
+end

data/lib/rails_cron/version.rb

@@ -0,0 +1,10 @@
+# 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 RailsCron
+  VERSION = '0.1.0'
+end

data/lib/rails_cron.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 'rails_cron/version'
+require 'rails_cron/railtie'
+
+##
+# RailsCron module is the main namespace for the gem
+##
+module RailsCron
+end

data/lib/tasks/rails_crons_tasks.rake

@@ -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.
+
+# desc "Explaining what the task does"
+# task :rails_cron do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: rails_cron
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nitesh Purohit
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: rails-i18n
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: "    Rails Cron is a Ruby gem that simplifies the management of cron
+  jobs in Rails applications, providing an easy-to-use interface for scheduling and
+  monitoring background tasks.\n"
+email:
+- nitesh.purohit.it@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- lib/rails_cron.rb
+- lib/rails_cron/railtie.rb
+- lib/rails_cron/version.rb
+- lib/tasks/rails_crons_tasks.rake
+homepage: https://github.com/Code-Vedas/rails_cron
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/Code-Vedas/rails_cron/issues
+  changelog_uri: https://github.com/Code-Vedas/rails_cron/blob/main/CHANGELOG.md
+  documentation_uri: https://rails-cron.codevedas.com
+  homepage_uri: https://github.com/Code-Vedas/rails_cron
+  source_code_uri: https://github.com/Code-Vedas/rails_cron.git
+  funding_uri: https://github.com/sponsors/Code-Vedas
+  support_uri: https://rails-cron.codevedas.com/support
+  rubygems_uri: https://rubygems.org/gems/rails_cron
+  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: Ruby gem for managing cron jobs in Rails applications.
+test_files: []