CronHelper

The Cron Helper gem is designed to add a few additional features to cron jobs created with the Whenever gem.

Features include:

• File based locking to prevent jobs from running if they are already running. This is especially useful if a job takes longer than it should (such as an hourly cron that happens to take two hours to run).
• Stdout and Stderr interception.
• The concept of "tasks" within a job (more on this below) for ordering and exception handling.
• Custom handling of output (write your own email handling, custom logging, alerting, etc).

Installation

Add this line to your application's Gemfile:

gem 'cron_helper'

And then execute:

$ bundle

Or install it yourself as:

$ gem install cron_helper

Usage

For your typical Rails or Ruby app, you will first want to create your ApplicationJob. This is the class that all of your custom jobs should inherit from. Here you put methods that are shared by all your custom jobs.

class ApplicationJob < CronHelper::Job
end

Next you will create your app specific job classes. The idea is to pick logical names that relate to how they are going to be scheduled and grouped. Inside of each class you will register your tasks.

class HourlyJob < ApplicationJob
  register :do_some_work
  register :do_some_other_work
  register :do_even_more_work

  private

  def do_some_work
    raise 'I am a task that breaks quite often.'
  end

  def do_some_other_work
    puts 'I am a task that loves to talk.'
    STDERR.puts 'I even like to talk about errors.'
  end

  def do_even_more_work
    # I am a silent champion of a task.
  end
end

Finally you will schedule your jobs using the Whenever gem. Below is an example config/schedule.rb that also forces your jobs to run at a low priority. Running jobs at a low priority is recommended when your server has other roles (web, app, db, etc).

job_type :runner,  "cd :path && nice -n 20 script/rails runner -e :environment ':task' :output"

every 1.hour do
  runner('HourlyJob.new.run')
end

Tasks

Think of tasks as methods with exception protection and ordering. Tasks are guaranteed to run in the order you register them. They are also guaranteed to run even if a previous task encountered an exception. This gives you control over creating new tasks without having to worry about breaking old ones.

Customization

You can customize where stdout/stderr are sent to by overriding the output_handler method. Normally you will want to put this in ApplicationJob.

class ApplicationJob < CronHelper::Job
  private
  def output_handler(output)
    # Log the output to your custom destination (email, DB, SMS alerts, etc).
  end
end

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/cron_helper.

License

The gem is available as open source under the terms of the MIT License.