Skip to content

A background job scheduler for any queue backend

License

MIT, MIT licenses found

Licenses found

MIT
LICENSE.txt
MIT
MIT-LICENSE
Notifications You must be signed in to change notification settings

tubbo/activejob-scheduler

ActiveJob::Scheduler

Current Gem Version Build Status Maintainability Test Coverage

An extension to ActiveJob for running background jobs periodically, according to a schedule. Inspired by its predecessors, resque-scheduler and sidekiq-scheduler, ActiveJob::Scheduler hopes to bring the power of scheduled jobs into everyone's hands, by way of the pre-defined ActiveJob API which most popular queueing backend choices already support.

Like its predecessors, ActiveJob::Scheduler uses the same powerful syntax for describing when periodic jobs should run as Rufus::Scheduler. However, unlike its predecessors, ActiveJob::Scheduler does not require a separate process to be run. Instead, it uses an after_perform callback to re-enqueue the job after it has been performed.

Installation

Add this line to your application's Gemfile:

gem 'activejob-scheduler'

And then execute:

$ bundle

Or install it yourself as:

$ gem install activejob-scheduler

Usage

To schedule your jobs, add the repeat macro to the job definition:

class GenerateSitemapsJob < ApplicationJob
  repeat 'every day at 2am'

  def perform
    SitemapGenerator.generate
  end
end

This macro can also be used to configure the job event, like its name or arguments:

class GenerateSitemapsJob < ApplicationJob
  repeat every: '1d', name: 'Sitemap Generator', arguments: %w(foo bar)

  def perform(foo, bar)
    SitemapGenerator.generate(foo, bar) # => foo == "foo", bar == "bar"
  end
end

The DSL also allows you to iterate over a collection and pass in a different argument for each item:

class SyncOrdersJob < ApplicationJob
  repeat 'every day at 11:30am', each: -> { Order.not_synced }

  def perform(order)
    ExternalSystem.create(order)
  end
end

This will trigger the event every day at 11:30am, but enqueue a job for each model in the collection, and pass it into the job arguments. You can specify static arguments here as well, they will be passed in prior to the item argument at the end.

class SyncOrdersJob < ApplicationJob
  repeat 'every day at 11:30am',
    arguments: ['synced'],
    each: -> { Order.not_synced }

  def perform(type, order)
    ExternalSystem.create(type: type, order: order) # type is "synced"
  end
end

Start the schedule by running this command:

./bin/rails activejob:schedule

YAML Schedule

Much like resque-scheduler, you can use a YAML schedule file with activejob-scheduler with a very similar syntax. To generate a new one, run:

$ rails generate activejob:schedule

Then, add your jobs into the YAML like so:

generate_sitemaps:
  interval:
    every: '1d'

This is entirely optional, however, and both DSL-based jobs and YAML-based jobs will be included in the schedule at runtime.

Mailers

class AdminMailer < ApplicationMailer
  repeat :daily_status, 'every day at 8am'
  def daily_status
    mail to: User.admins.pluck(:email)
  end
end

This will send the email every day at 8:00am. You can also pass all the regular fields from repeat in the job DSL like arguments and the various fugit-parsed intervals.

You can also send a different email for each recipient:

class UserMailer < ApplicationMailer
  repeat :status, 'every day at 8am', each: -> { User.receive_email }
  def status(user)
  end
end

This lambda will be called when the event is enqueued, and individual mails will be sent out for each user in the collection.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake rspec 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 bin/rake install. To release a new version, update the version number in version.rb, and then run bin/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/tubbo/activejob-scheduler. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

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