Canvas Delayed Jobs

This gem is a very heavily modified fork of delayed_job. It used to live directly inside canvas-lms, but was extracted for use in other Rails applications.

Features

TODO: explain the differences and additions

Installation

canvas-jobs requires Rails 3.2 or above, and Ruby 1.9.3 or above. It is tested through Rails 4.2 and Ruby 2.1.

Add this line to your Rails application's Gemfile:

gem 'canvas-jobs'

If you are using Ruby >= 2.0, you'll also need to install the syck gem. We can't have this gem do it automatically without breaking support for ruby 1.9.

gem 'syck'

And then execute:

$ bundle

Or install it yourself as:

$ gem install canvas-jobs

Usage

Lifecycle Events

There are several callbacks you can hook into from outside the library, find them at the top of the "lifecycle.rb" class.

To hook into a callback, write something that looks like this in an initializer:

Delayed::Worker.lifecycle.before(:error) do |worker, exception|
  ErrorThingy.notify(exception)
end

ActiveRecord Backend

If you are using the ActiveRecord backend, you'll need to install and run the migrations:

$ rake delayed_engine:install:migrations
$ rake db:migrate

To use a separate database connection, specify it in an initializer:

Delayed::Backend::ActiveRecord::Job.establish_connection(my_db_queue_config)

The ActiveRecord backend only supports PostgreSQL.

Redis Backend

The redis backend doesn't require any migrations. To connect, you'll need to add an application initializer such as config/initializers/delayed_job.rb:

Delayed::Backend::Redis::Job.redis = Redis.new(url: 'redis://my-redis-host:6379/')
Delayed.select_backend(Delayed::Backend::Redis::Job)

Worker Configuration

Worker and queue information is hard-coded to read from config/delayed_jobs.yml, this will change in the future:

development:
  workers:
  - workers: 2

production:
  workers:
  - workers: 10

Periodic Jobs

Periodic jobs need to be configured during application startup, so that workers have access to the schedules. For instance, create a config/initializers/periodic_jobs.rb:

Delayed::Periodic.cron 'Alerts::DelayedAlertSender.process', '30 11 * * *' do
  Alerts::DelayedAlertSender.process
end

Running Workers

$ canvas_job # display help
$ canvas_job start # start a worker in the background
$ canvas_job run # start a worker in the foreground

Testing

To write tests that interact with canvas-jobs, you'll need to configure an actual ActiveRecord or Redis backend. In the future we may add an in-memory testing backend.

By default, if you have postgres and redis running on their default ports, and if you have run:

$> createdb canvas-jobs-test-1

Then you should be able to run the tests that come with the library with:

$> bundle exec rspec spec

There are a few basic testing helpers available:

require 'delayed/testing'

Delayed::Testing.drain # run all queued jobs
Delayed::Testing.run_job(job) # run a single job

before(:each) do
  Delayed::Testing.clear_all! # delete all queued jobs
end

Contributing

1. Fork it ( https://github.com/instructure/canvas-jobs/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request