simple_scheduler 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8d15cd2b0b48692188a8b470d258e667dae84d08
+  data.tar.gz: 20eca360c888dbf7e482377f8d78053e988906c5
+SHA512:
+  metadata.gz: 452dae7f622c805289ade38235a8041d9ed23faeb9bd5a1acfa51577570afd07667dbb70d5d099c7630c9ca4fbe04245d80c53655f14464c50369bdb8747a52c
+  data.tar.gz: f1d49ad79d145d281ce24d4476c752c1d51ae8b37cba98e6e25830c0bc355a2b12e4c3b36a475a25f86a2456e74b0796c237ecae28f0eabd127ebf7d3ec79ac7

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2016 Brian Pattison
+
+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,234 @@
+# Simple Scheduler
+
+[![Build Status](https://travis-ci.org/simplymadeapps/simple_scheduler.svg?branch=master)](https://travis-ci.org/simplymadeapps/simple_scheduler)
+[![Code Climate](https://codeclimate.com/github/simplymadeapps/simple_scheduler/badges/gpa.svg)](https://codeclimate.com/github/simplymadeapps/simple_scheduler)
+[![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/github/simplymadeapps/simple_scheduler/)
+
+Simple Scheduler is a scheduling add-on that is designed to be used with
+[Sidekiq](http://sidekiq.org) and
+[Heroku Scheduler](https://elements.heroku.com/addons/scheduler). It
+gives you the ability to **schedule tasks at any interval** without adding
+a clock process. Heroku Scheduler only allows you to schedule tasks every 10 minutes,
+every hour, or every day.
+
+## Requirements
+
+You must be using:
+
+- Rails 4.2+
+- [Sidekiq](http://sidekiq.org)
+- [Heroku Scheduler](https://elements.heroku.com/addons/scheduler)
+
+Both Active Job and Sidekiq::Worker classes can be queued by the scheduler.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "simple_scheduler"
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+## Getting Started
+
+Create a configuration file `config/simple_scheduler.yml`:
+
+```yml
+# Global configuration options and their defaults. These can also be set on each task.
+queue_ahead: 360 # Number of minutes to queue jobs into the future
+tz: nil # The application time zone will be used by default
+
+# Runs once every 2 minutes
+simple_task:
+  class: "SomeActiveJob"
+  every: "2.minutes"
+
+# Runs once every day at 4:00 AM
+overnight_task:
+  class: "SomeSidekiqWorker"
+  every: "1.day"
+  at: "4:00"
+
+# Runs once every hour at the half hour
+half_hour_task:
+  class: "HalfHourTask"
+  every: "30.minutes"
+  at: "*:30"
+
+# Runs once every week on Saturdays at 12:00 AM
+weekly_task:
+  class: "WeeklyJob"
+  every: "1.week"
+  at: "Sat 0:00"
+  tz: "America/Chicago"
+```
+
+### Task options
+
+#### :class
+
+The class name of the ActiveJob or Sidekiq::Worker. Your job or
+worker class should accept the expected run time as a parameter
+on the `perform` method.
+
+#### :every
+
+How frequently the task should be performed as an ActiveSupport duration definition.
+
+```ruby
+1.day
+5.days
+12.hours
+20.minutes
+1.week
+```
+
+#### :at (optional)
+
+This is the starting point for the `every` duration. If not given, the job will
+run immediately when the configuration file is loaded for the first time and will
+follow the `every` duration to determine future execution times.
+
+Valid string formats/examples:
+
+```
+18:00
+ 3:30
+**:00
+ *:30
+Sun 2:00
+[Sun|Mon|Tue|Wed|Thu|Fri|Sat] 00:00
+```
+
+Add the rake task to Heroku Scheduler and set it to run every 10 minutes:
+
+```
+rake simple_scheduler
+```
+
+The file `config/simple_scheduler.yml` will be used by default, but it may be
+useful to point to another configuration file in non-production environments.
+
+```
+rake simple_scheduler["config/simple_scheduler.staging.yml"]
+```
+
+## Writing Your Jobs
+
+Your Active Job or Sidekiq Worker must accept the task name and time stamp
+as arguments. This is so they can be queued properly and so your job can
+use the scheduled time to know when it was supposed to run vs the current time.
+
+```ruby
+class ExampleJob < ActiveJob::Base
+  # @param task_name [String] This is the key used in the YAML file to define the task
+  # @param time [Integer] The epoch time for when the job was scheduled to be run
+  def perform(task_name, time)
+    puts task_name
+    puts Time.at(time)
+  end
+end
+```
+
+When writing your jobs, you need to account for any possible server downtime.
+The most common downtime would be caused by Heroku's required daily restart.
+
+To ensure that your tasks always run, the jobs are queued in advance and it's
+possible the jobs may not be executed at the exact time that you configured
+them to run. If there is extended downtime, your jobs may back up and there
+is no guarantee of the order they will be executed when your worker process
+comes back online.
+
+Because there is no guarantee that the job is run at the exact time given in
+the configuration, the time the job was expected to run will be passed to
+the job so you can handle situations where the time it was run doesn't match
+the time it was expected to run.
+
+### How It Works
+
+Once the rake task is added to Heroku Scheduler, the Simple Scheduler library
+will load the configuration file every 10 minutes, and ensure that each task
+has jobs scheduled in the future be checking the `Sidekiq::ScheduledSet`.
+
+A minimum of two jobs is always added to the scheduled set. By default all
+jobs for the next six hours are queued in advance. This ensures that there is
+always one job in the queue that can be used to determine the next run time,
+even if one of the two was executed during the 10 minute scheduler wait time.
+
+### Server Downtime Example
+
+If you're using a gem like [clockwork](https://github.com/Rykian/clockwork), there is no way for the clock process to
+know that the task was never run. If your task is scheduled for `12:00:00`, your
+clock process could possibly be restarted at `11:59:59` and your dyno might not
+be available until `12:00:20`.
+
+Simple Scheduler would have already enqueued the task hours before the task should actually
+run, so you still have to worry about the worker dyno restarting, but when the worker
+dyno becomes available, the enqueued task will be there and will be executed immediately.
+
+### Daily Digest Email Example
+
+Here's an example of a daily digest email that needs to go out at 8:00 AM for
+users in their local time zone. We need to run this every 15 minutes to handle
+all time zone offsets.
+
+config/simple_scheduler.yml:
+
+```yml
+# Runs every hour starting at the top of the hour + every 15 minutes
+daily_digest_task:
+  class: "DailyDigestEmailJob"
+  every: "15.minutes"
+  at: "*:00"
+```
+
+app/jobs/daily_digest_email_job.rb:
+
+```ruby
+class DailyDigestEmailJob < ApplicationJob
+  queue_as :default
+
+  # Called by Simple Scheduler and is given the scheduled time so decisions can be made
+  # based on when the job was scheduled to be run rather than when it was actually run.
+  # @param task_name [String] This is the key used in the YAML file to define the task
+  # @param time [Integer] The epoch time for when the job was scheduled to be run
+  def perform(task_name, time)
+    # Don't do this! This will be way too slow!
+    User.find_each do |user|
+      if user.digest_time == Time.at(time)
+        DigestMailer.daily(user).deliver_later
+      end
+    end
+  end
+end
+```
+
+app/models/user.rb:
+
+```ruby
+class User < ApplicationRecord
+  # Returns the time the user's daily digest should be
+  # delivered today based on the user's time zone.
+  # @return [Time]
+  def digest_time
+    "8:00 AM".in_time_zone(self.time_zone)
+  end
+end
+```
+
+## Contributing
+
+1. Fork it
+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 new Pull Request
+
+## License
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,13 @@
+begin
+  require "bundler/setup"
+rescue LoadError
+  puts "You must `gem install bundler` and `bundle install` to run rake tasks"
+end
+
+begin
+  require "rspec/core/rake_task"
+  RSpec::Core::RakeTask.new(:spec)
+  task default: :spec
+rescue LoadError
+  puts "Could not load Rspec Rake task"
+end

data/lib/simple_scheduler.rb

@@ -0,0 +1,10 @@
+require "active_job"
+require "sidekiq/api"
+require_relative "./simple_scheduler/railtie"
+require_relative "./simple_scheduler/scheduler_job"
+require_relative "./simple_scheduler/task"
+require_relative "./simple_scheduler/version"
+
+# Module for scheduling jobs at specific times using Sidekiq.
+module SimpleScheduler
+end

data/lib/simple_scheduler/railtie.rb

@@ -0,0 +1,8 @@
+module SimpleScheduler
+  # Load the rake task into the Rails app
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load File.join(File.dirname(__FILE__), "../tasks/simple_scheduler_tasks.rake")
+    end
+  end
+end

data/lib/simple_scheduler/scheduler_job.rb

@@ -0,0 +1,68 @@
+module SimpleScheduler
+  # Active Job class that queues jobs defined in the config file.
+  class SchedulerJob < ActiveJob::Base
+    # Load the global scheduler config from the YAML file.
+    # @param config_path [String]
+    def load_config(config_path)
+      @config = YAML.load_file(config_path)
+      @queue_ahead = @config["queue_ahead"] || Task::DEFAULT_QUEUE_AHEAD_MINUTES
+      @time_zone = @config["tz"] ? ActiveSupport::TimeZone.new(@config["tz"]) : Time.zone
+      @config.delete("queue_ahead")
+      @config.delete("tz")
+    end
+
+    # Accepts a file path to read the scheduler configuration.
+    # @param config_path [String]
+    def perform(config_path = nil)
+      config_path ||= "config/simple_scheduler.yml"
+      load_config(config_path)
+      queue_future_jobs
+    end
+
+    # Queue each of the future jobs into Sidekiq from the defined tasks.
+    def queue_future_jobs
+      tasks.each do |task|
+        new_run_times = task.future_run_times - task.existing_run_times
+        next if new_run_times.empty?
+
+        if task.job_class.included_modules.include?(Sidekiq::Worker)
+          queue_future_sidekiq_workers(task, new_run_times)
+        else
+          queue_future_active_jobs(task, new_run_times)
+        end
+      end
+    end
+
+    # The array of tasks loaded from the config YAML.
+    # @return [Array<SimpleScheduler::SchedulerJob]
+    def tasks
+      @config.map do |task_name, options|
+        task_params = options.symbolize_keys
+        task_params[:queue_ahead] ||= @queue_ahead
+        task_params[:name] = task_name
+        task_params[:tz] ||= @time_zone
+        Task.new(task_params)
+      end
+    end
+
+    private
+
+    # Queues jobs in the future using Active Job based on the task options.
+    # @param task [SimpleScheduler::Task]
+    # @param run_times [Array<Time>]
+    def queue_future_active_jobs(task, run_times)
+      run_times.each do |time|
+        task.job_class.set(wait_until: time).perform_later(task.name, time.to_i)
+      end
+    end
+
+    # Queues jobs in the future using Sidekiq based on the task options.
+    # @param task [SimpleScheduler::Task]
+    # @param run_times [Array<Time>]
+    def queue_future_sidekiq_workers(task, run_times)
+      run_times.each do |time|
+        task.job_class.perform_at(time, task.name, time.to_i)
+      end
+    end
+  end
+end

data/lib/simple_scheduler/task.rb

@@ -0,0 +1,127 @@
+module SimpleScheduler
+  # Class for parsing each task in the scheduler config YAML file and returning
+  # the values needed to schedule the task in the future.
+  class Task
+    attr_accessor :at, :frequency, :job_class, :job_class_name, :name, :queue_ahead, :time_zone
+
+    AT_PATTERN = /(Sun|Mon|Tue|Wed|Thu|Fri|Sat)?\s?(?:\*{1,2}|(\d{1,2})):(\d{1,2})/
+    DAYS = %w(Sun Mon Tue Wed Thu Fri Sat).freeze
+    DEFAULT_QUEUE_AHEAD_MINUTES = 360
+
+    # Initializes a task by parsing the params so the task can be queued in the future.
+    # @param params [Hash]
+    # @option params [String] :class The class of the Active Job or Sidekiq Worker
+    # @option params [String] :every How frequently the job will be performed
+    # @option params [String] :at The starting time for the interval
+    # @option params [Integer] :queue_ahead The number of minutes that jobs should be queued in the future
+    # @option params [String] :task_name The name of the task as defined in the YAML config
+    # @option params [ActiveSupport::TimeZone] :tz The time zone to use when parsing the `at` option
+    def initialize(params)
+      validate_params!(params)
+      @at = params[:at]
+      @frequency = parse_frequency(params[:every])
+      @job_class_name = params[:class]
+      @job_class = @job_class_name.constantize
+      @queue_ahead = params[:queue_ahead] || DEFAULT_QUEUE_AHEAD_MINUTES
+      @name = params[:name] || @job_class_name
+      @time_zone = params[:tz] || Time.zone
+    end
+
+    # Returns an array of existing jobs matching the job class of the task.
+    # @return [Array<Sidekiq::SortedEntry>]
+    def existing_jobs
+      @existing_jobs ||= SimpleScheduler::Task.scheduled_set.select do |job|
+        job.display_class == @job_class_name && job.display_args[0] == @name
+      end.to_a
+    end
+
+    # Returns an array of existing future run times that have already been scheduled.
+    # @return [Array<Time>]
+    def existing_run_times
+      @existing_run_times ||= existing_jobs.map(&:at)
+    end
+
+    # Returns the very first time a job should be run for the scheduled task.
+    # @return [Time]
+    def first_run_time
+      first_run_time = first_run_day
+      change_hour = first_run_hour
+      change_hour += 1 if at_match[2].nil? && first_run_hour == now.hour && first_run_min < now.min
+      first_run_time = first_run_time.change(hour: change_hour, min: first_run_min)
+      first_run_time += at_match[1] ? 1.week : 1.day if now > first_run_time
+      first_run_time
+    end
+
+    # Returns an array Time objects for future run times based on
+    # the current time and the given minutes to look ahead.
+    # @return [Array<Time>]
+    def future_run_times
+      future_run_times = existing_run_times.dup
+      last_run_time = future_run_times.last || first_run_time - frequency
+      last_run_time = last_run_time.in_time_zone(@time_zone)
+
+      while future_run_times.length < 2 || ((last_run_time - now) / 1.minute) < @queue_ahead
+        last_run_time = frequency.from_now(last_run_time)
+        last_run_time = last_run_time.change(hour: first_run_hour, min: first_run_min) if at_match[2]
+        future_run_times << last_run_time
+      end
+
+      future_run_times
+    end
+
+    # Loads the scheduled jobs from Sidekiq once to avoid loading from
+    # Redis for each task when looking up existing scheduled jobs.
+    # @return [Sidekiq::ScheduledSet]
+    def self.scheduled_set
+      @scheduled_set ||= Sidekiq::ScheduledSet.new
+    end
+
+    private
+
+    def at_match
+      @at_match ||= AT_PATTERN.match(@at) || []
+    end
+
+    def first_run_day
+      return @first_run_day if @first_run_day
+
+      @first_run_day = now.beginning_of_day
+
+      # If no day of the week is given, return today
+      return @first_run_day unless first_run_wday
+
+      # Shift to the correct day of the week if given
+      add_days = first_run_wday - first_run_day.wday
+      add_days += 7 if first_run_day.wday > first_run_wday
+      @first_run_day += add_days.days
+    end
+
+    def first_run_hour
+      @first_run_hour ||= (at_match[2] || now.hour).to_i
+    end
+
+    def first_run_min
+      @first_run_min ||= (at_match[3] || now.min).to_i
+    end
+
+    def first_run_wday
+      @first_run_wday ||= DAYS.index(at_match[1])
+    end
+
+    def now
+      @now ||= @time_zone.now.beginning_of_minute
+    end
+
+    def parse_frequency(every_string)
+      split_duration = every_string.split(".")
+      frequency = split_duration[0].to_i
+      frequency_units = split_duration[1]
+      frequency.send(frequency_units)
+    end
+
+    def validate_params!(params)
+      raise ArgumentError, "Missing param `class` specifying the class of the job to run." unless params.key?(:class)
+      raise ArgumentError, "Missing param `every` specifying how often the job should run." unless params.key?(:every)
+    end
+  end
+end

data/lib/simple_scheduler/version.rb

@@ -0,0 +1,3 @@
+module SimpleScheduler
+  VERSION = "0.1.0".freeze
+end

data/lib/tasks/simple_scheduler_tasks.rake

@@ -0,0 +1,4 @@
+desc "Queue future jobs defined using Simple Scheduler"
+task :simple_scheduler, [:config_path] => [:environment] do |_, args|
+  SimpleScheduler::SchedulerJob.perform_now(args[:config_path])
+end

metadata

@@ -0,0 +1,155 @@
+--- !ruby/object:Gem::Specification
+name: simple_scheduler
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Brian Pattison
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-12-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '4.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '4.2'
+- !ruby/object:Gem::Dependency
+  name: sidekiq
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '4.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '4.2'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov-rcov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |2
+                    Simple Scheduler adds the ability to enhance Heroku Scheduler by using Sidekiq to queue
+                    jobs in the future. This allows for defining specific run times (Ex: Every Sunday at 4 AM)
+                    and running tasks more often than Heroku Scheduler's 10 minute limit.
+email:
+- brian@brianpattison.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/simple_scheduler/railtie.rb
+- lib/simple_scheduler/scheduler_job.rb
+- lib/simple_scheduler/task.rb
+- lib/simple_scheduler/version.rb
+- lib/simple_scheduler.rb
+- lib/tasks/simple_scheduler_tasks.rake
+- MIT-LICENSE
+- Rakefile
+- README.md
+homepage: https://github.com/simplymadeapps/simple_scheduler
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.14.1
+signing_key: 
+specification_version: 4
+summary: An enhancement for Heroku Scheduler + Sidekiq for scheduling jobs at specific
+  times.
+test_files: []