say_when 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5f6591f3f5206b517960a08efa500fbf3334ff56
-  data.tar.gz: 4daa2a598bf163817da9b7987938cc7216ed1f58
+  metadata.gz: 92b39148a95c13f3b9fc5d55d56ef49d3566576f
+  data.tar.gz: d30b25ecd756ae2eb187a70c7511578fb0ddfc74
 SHA512:
-  metadata.gz: 236e345d76fb90f946e90a6d7ed8581bf670823b36965da9110e680f39847656c309e00ecc77d931e113a27648bc29bc37f72223f9a32c94f45a240c64fbff47
-  data.tar.gz: 3eb871a517e9e1c7246d7b52957b423c56fc58d47127f1523d2383a6f605314901684ad2a21c70bc3bd620964f6346403d3bf9e10ec70a79a9192a6cb55fda13
+  metadata.gz: 62ac59b8bd6d443cde57281aa883e3aaedba830737c4c9ea296914fd1c032628c9d316b5b9f920895bcc226694ab9e1568eb03dee8a759533cca671cb6afac3f
+  data.tar.gz: 0a30ee197ca109d14c57377f1c55c48d9e8f3b337a7a062dab0c93adf70e508e942e825420cbde5eb8b6fee2ec61a7a174ebb58be93081a55d8644dc5ec13156

data/.gitignore

@@ -14,3 +14,4 @@
 *.DS_Store
 .ruby-version
 test/db/test.db
+notes.md

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - "2.2.4"
+  - "2.3.1"

data/Guardfile

@@ -0,0 +1,50 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+## Uncomment and set this to only include directories you want to watch
+# directories %w(app lib config test spec features)
+
+## Uncomment to clear the screen before every task
+# clearing :on
+
+## Guard internally checks for changes in the Guardfile and exits.
+## If you want Guard to automatically start up again, run guard in a
+## shell loop, e.g.:
+##
+##  $ while bundle exec guard; do echo "Restarting Guard..."; done
+##
+## Note: if you are using the `directories` clause above and you are not
+## watching the project directory ('.'), then you will want to move
+## the Guardfile to a watched dir and symlink it back, e.g.
+#
+#  $ mkdir config
+#  $ mv Guardfile config/
+#  $ ln -s config/Guardfile .
+#
+# and, you'll have to watch "config/Guardfile" instead of "Guardfile"
+
+guard :minitest do
+  # with Minitest::Unit
+  watch(%r{^test/(.*)\/?(.*)_test\.rb$})
+  watch(%r{^lib/(.*/)?([^/]+)\.rb$})     { |m| "test/#{m[1]}#{m[2]}_test.rb" }
+  watch(%r{^test/minitest_helper\.rb$})  { 'test' }
+
+  # with Minitest::Spec
+  # watch(%r{^spec/(.*)_spec\.rb$})
+  # watch(%r{^lib/(.+)\.rb$})         { |m| "spec/#{m[1]}_spec.rb" }
+  # watch(%r{^spec/spec_helper\.rb$}) { 'spec' }
+
+  # Rails 4
+  # watch(%r{^app/(.+)\.rb$})                               { |m| "test/#{m[1]}_test.rb" }
+  # watch(%r{^app/controllers/application_controller\.rb$}) { 'test/controllers' }
+  # watch(%r{^app/controllers/(.+)_controller\.rb$})        { |m| "test/integration/#{m[1]}_test.rb" }
+  # watch(%r{^app/views/(.+)_mailer/.+})                   { |m| "test/mailers/#{m[1]}_mailer_test.rb" }
+  # watch(%r{^lib/(.+)\.rb$})                               { |m| "test/lib/#{m[1]}_test.rb" }
+  # watch(%r{^test/.+_test\.rb$})
+  # watch(%r{^test/test_helper\.rb$}) { 'test' }
+
+  # Rails < 4
+  # watch(%r{^app/controllers/(.*)\.rb$}) { |m| "test/functional/#{m[1]}_test.rb" }
+  # watch(%r{^app/helpers/(.*)\.rb$})     { |m| "test/helpers/#{m[1]}_test.rb" }
+  # watch(%r{^app/models/(.*)\.rb$})      { |m| "test/unit/#{m[1]}_test.rb" }
+end

data/README.md

@@ -1,6 +1,19 @@
 # SayWhen
 
-TODO: Write a gem description
+SayWhen is a job scheduling library for use in any project, but with a few extra hooks for rails projects.
+It was roughly inspired by the [Quartz scheduler](http://quartz-scheduler.org/).
+
+You add it to a ruby program (optionally configure it) and then schedule jobs using a few different strategies, with cron-like expressions the most powerful.
+
+When scheduling, you specify a trigger which controls when execution will occur, such as a cron trigger, or an execute only once trigger, and a job, which is the actual work to perform.
+
+The cron triggers are based on the [extended cron capabilities](http://wiki.opensymphony.com/display/QRTZ1/CronTriggers+Tutorial).
+
+Jobs can be stored different ways, either in memory (e.g. loaded on start from a ruby file), or saved to a database.
+
+The scheduler can execute the jobs in different ways, either by loading and running them itself synchronously, or by delegating the processing to ActiveJob.
+
+SayWhen can be run either in its own process, or can run as a supervised actor in a Celluloid process (e.g. sidekiq or shoryuken).
 
 ## Installation
 
@@ -18,9 +31,129 @@ Or install it yourself as:
 
     $ gem install say_when
 
+## Configuration
+
+To use, first configure how jobs are stored and processed.
+Be default, they are in memory, and processed synchronously, but that can be configured to behave differently.
+
+The currently available storage options are:
+- Memory (default) - usually jobs are initialized in code on load
+- ActiveRecord - stores the scheduled jobs and can log execution information to database tables
+
+The processor options are:
+- Simple - the scheduler process executes the job itself synchronously
+- ActiveJob - delegates the work to an ActiveJob async call
+- Test - stubs out processing, useful for testing only
+
+You also have some options for running SayWhen:
+- SimplePoller - just a simple looping process, can be started with rake
+- CelluloidPoller - defines a Celluloid Actor appropriate for adding to a running Celluloid process, such as from Shoryuken
+
+Finally, there are options for triggers that determine when jobs run:
+- Cron expression
+- Once
+- Instance
+
+```ruby
+# config/intializers/say_when.rb
+
+require 'say_when'
+
+# you can specify a the logger
+SayWhen.logger = Rails.logger
+
+# configure the scheduler for how to store and process scheduled jobs
+# it will default to a :memory strategy and :simple processor
+SayWhen.configure do |options|
+  options[:storage_strategy]   = :active_record
+  options[:processor_strategy] = :simple
+end
+```
+
 ## Usage
 
-TODO: Write usage instructions here
+### Basics
+There is a very verbose way to create a scheduled job, setting the options for the trigger and job explicitly, and then some helper methods that make this easier for common cases.
+
+Here is an example of the verbose way of scheduling a job, which is a good place to start:
+```ruby
+
+  job = SayWhen::Scheduler.schedule(
+    trigger_strategy: 'once',
+    trigger_options: { at: 10.second.since },
+    job_class: SomeTask,
+    job_method: 'execute',
+    data: { id: 123 }
+  )
+```
+
+There are also convenience methods on the `Scheduler`:
+```ruby
+
+```
+## ActiveRecord integration
+
+Besides storing jobs in ActiveRecord, you can also associate jobs with other models.
+
+There is an `acts_as_scheduled` method you can call in an ActiveRecord class for this purpose.
+It both makes it easier to schedule a job, and to see manage the list of related jobs.
+
+For example, you might create a job to send a reminder a week after a user is created, and relate this new job to that user.
+By associating it with the `ActiveRecord` object, you can more easily manage this reminder, such as canceling it if they close their account.
+
+When using `ActiveRecord` integration in Rails, there is a generator for the migration to create the tables for saving scheduled jobs:
+```
+bundle exec rails generate say_when:migration
+```
+
+The resulting migration assumes the scheduled jobs will use a integer based id column, please update the default migration if this is not the case in your system:
+```ruby
+# change this to string or other type as needed
+t.integer   :scheduled_id
+```
+
+## Pollers
+
+The `SimplePoller` does what you would expect; when you run it, it starts up a loop of checking for jobs to run, sleeping, and then checking again.
+
+It can be executed from the rake task:
+```
+bundle exec rake say_when:start
+```
+
+But that isn't doing much except loading the environment then this:
+```ruby
+require 'say_when'
+require 'say_when/poller/simple_poller'
+
+SayWhen::Poller::SimplePoller.start
+```
+
+For my own purposes, I use things like `daemontools` and `god` to daemonize, so this has been enough for me, but it would not be hard to write a command line script for it.
+
+Most of the time I am also running a job processor, either `shoryuken` or `sidekiq`, and I would prefer to piggyback on that same process instead of starting up another. Since both of those use Celluloid (or did, Sidekiq no longer does), I also created a Celluloid actor class that can be added to the celluloid based job process via hooks in their startup.
+
+For Shoryuken, add this to your initializer (probably `config/initializers/shoryuken.rb`):
+```ruby
+require 'say_when/poller/celluloid_poller'
+
+Shoryuken.on_start do
+  # check for new jobs to run every 5 seconds
+  SayWhen::Poller::CelluloidPoller.supervise_as :say_when, 5
+end
+```
+
+For Sidekiq, there is a slightly different syntax, but basically the same idea
+(via https://github.com/mperham/sidekiq/wiki/Deployment#events):
+```ruby
+require 'say_when/poller/celluloid_poller'
+
+Sidekiq.configure_server do |config|
+  config.on(:startup) do
+    SayWhen::Poller::CelluloidPoller.supervise_as :say_when, 5
+  end
+end
+```
 
 ## Contributing
 

data/Rakefile

@@ -1,5 +1,6 @@
 require 'bundler/gem_tasks'
 require 'rake/testtask'
+require 'say_when/tasks'
 
 Rake::TestTask.new(:test) do |t|
   t.libs << 'test'

data/lib/say_when.rb

@@ -1,32 +1,47 @@
 # encoding: utf-8
 
-require 'active_support'
+require 'active_support/all'
 
-require "say_when/version"
-require 'say_when/base_job'
+require 'say_when/version'
+require 'say_when/configuration'
+require 'say_when/utils'
 require 'say_when/cron_expression'
-require 'say_when/processor/base'
-require 'say_when/processor/simple'
 require 'say_when/scheduler'
 
-require 'say_when/processor/active_messaging' if defined?(::ActiveMessaging)
-require 'say_when/processor/shoryuken' if defined?(::Shoryuken)
-require 'say_when/storage/active_record/job' if defined?(::ActiveRecord)
 require 'say_when/railtie' if defined?(Rails)
 
 module SayWhen
-  def SayWhen.logger=(logger)
-    @@logger = logger
-  end
-
-  def SayWhen.logger
-    if !defined?(@@logger) || !@@logger
-      if defined?(Rails.logger) && Rails.logger
-        @@logger = Rails.logger
+  class << self
+    def logger
+      @logger ||= if defined?(Rails)
+        Rails.logger
+      else
+        Logger.new(STDOUT)
       end
+    end
+
+    def logger=(l)
+      @logger = l
+    end
+
+    def options
+      @options ||= SayWhen::Configuration.default_options
+    end
+
+    def configure(opts = {})
+      @lock ||= Mutex.new
+      options.merge(opts)
+      yield options if block_given?
+    end
+
+    def scheduler
+      return @scheduler if defined?(@scheduler) && @scheduler
+      @lock.synchronize { @scheduler = SayWhen::Scheduler.new }
+      @scheduler
+    end
 
-      @@logger = Logger.new(STDOUT) unless defined?(@@logger)
+    def schedule(job)
+      scheduler.schedule(job)
     end
-    @@logger
   end
 end

data/lib/say_when/configuration.rb

@@ -0,0 +1,16 @@
+require 'yaml'
+require 'erb'
+
+module SayWhen
+  class Configuration
+    def self.default_options
+      {}.tap do |defaults|
+        defaults[:processor_strategy] = :simple
+        defaults[:storage_strategy] = :memory
+        defaults[:tick_length] = (ENV['SAY_WHEN_TICK_LENGTH'] || '5').to_i
+        defaults[:queue] = ENV['SAY_WHEN_QUEUE'] || 'default'
+        defaults[:reset_acquired_length] = (ENV['SAY_WHEN_RESET_ACQUIRED_LENGTH'] || '3600').to_i
+      end
+    end
+  end
+end

data/lib/say_when/cron_expression.rb

@@ -3,14 +3,13 @@
 require 'date'
 
 module SayWhen
-
   # Based on the extended cron capabilties
-  # http://wiki.opensymphony.com/display/QRTZ1/CronTriggers+Tutorial
+  # http://www.quartz-scheduler.org/documentation/quartz-2.2.x/tutorials/tutorial-lesson-06.html
   class CronExpression
     attr_reader :expression
     attr_accessor :time_zone, :seconds, :minutes, :hours, :days_of_month, :months, :days_of_week, :years
 
-    def initialize(expression, time_zone=nil)
+    def initialize(expression = {}, time_zone = nil)
       if expression.is_a?(Hash)
         opts = expression
 
@@ -28,19 +27,14 @@ module SayWhen
           "#{opts[:seconds]} #{opts[:minutes]} #{opts[:hours]} #{opts[:days_of_month]} #{opts[:months]} #{opts[:days_of_week]} #{opts[:years]}"
         end
 
-        self.time_zone = if opts.has_key?(:time_zone) && !opts[:time_zone].blank?
-          opts[:time_zone]
-        else
-          Time.zone.nil? ? "UTC" : Time.zone.name
-        end
-
+        @time_zone = opts[:time_zone]
       else
         @expression = expression
-        self.time_zone = if time_zone.blank?
-            Time.zone.nil? ? "UTC" : Time.zone.name
-          else
-            time_zone
-          end
+      end
+
+      @time_zone ||= time_zone
+      if @time_zone.blank?
+        @time_zone = Time.zone.try(:name) || "UTC"
       end
 
       parse
@@ -122,7 +116,6 @@ module SayWhen
       [before, false]
     end
 
-
   end
 
   class CronValue
@@ -154,19 +147,24 @@ module SayWhen
       values = []
       case val
         #check for a '/' for increments
-        when /(\w+)\/(\d+)/ then (( $1 == "*") ? min : $1.to_i).step(max, $2.to_i) { |x| values << x }
+        when /(.+)\/(\d+)/
+          (( $1 == "*") ? min : $1.to_i).step(max, $2.to_i) { |x| values << x }
 
         #check for ',' for list of values
-        when /(\d+)(,\d+)+/ then values = val.split(',').map{ |v| v.to_i }.sort
+        when /(\d+)(,\d+)+/
+          values = val.split(',').map{ |v| v.to_i }.sort
 
         #check for '-' for range of values
-        when /(\d+)-(\d+)/ then values = (($1.to_i)..($2.to_i)).to_a
+        when /(\d+)-(\d+)/
+          values = (($1.to_i)..($2.to_i)).to_a
 
         #check for '*' for all values between min and max
-        when /^(\*)$/ then values = (min..max).to_a
+        when /^(\*)$/
+          values = (min..max).to_a
 
         #lastly, should just be a number
-        when /^(\d+)$/ then values << $1.to_i
+        when /^(\d+)$/
+          values << $1.to_i
 
         #if nothing else, leave values as []
         else values = []
@@ -535,7 +533,7 @@ module SayWhen
 
   class YearsCronValue < CronValue
     def initialize(exp)
-      super(:year, 1970, 2099, exp)
+      super(:year, 1970, (Date.today.year + 100), exp)
     end
 
     def next(date)

data/lib/say_when/poller/base_poller.rb

@@ -0,0 +1,108 @@
+# encoding: utf-8
+
+require 'say_when/utils'
+
+module SayWhen
+  module Poller
+    module BasePoller
+      def self.included(mod)
+        mod.include(SayWhen::Utils)
+        attr_accessor :reset_next_at
+      end
+
+      def stop
+      end
+
+      def start
+      end
+
+      def reset_acquired
+        time_now = Time.now
+        self.reset_next_at ||= time_now
+
+        if reset_acquired_length > 0 && reset_next_at <= time_now
+          self.reset_next_at = time_now + reset_acquired_length
+          logger.debug "SayWhen:: reset acquired at #{time_now}, try again at #{reset_next_at}"
+          storage.reset_acquired(reset_acquired_length)
+        end
+      end
+
+      def job_error(msg, job, ex)
+        job_msg = job && " job:'#{job.inspect}'"
+        logger.error "#{self.class.name} #{msg}#{job_msg}: #{ex.message}\n\t#{ex.backtrace.join("\t\n")}"
+        release(job)
+      end
+
+      def process_jobs
+        reset_acquired
+        time_now = Time.now
+        while job = acquire(time_now)
+          process(job, time_now)
+          time_now = Time.now
+        end
+      rescue StandardError => ex
+        job_error("Error!", job, ex)
+        tick(error_tick_length)
+      rescue Interrupt => ex
+        job_error("Interrupt!", job, ex)
+        raise ex
+      rescue Exception => ex
+        job_error("Exception!", job, ex)
+        raise ex
+      end
+
+      def acquire(time_now)
+        logger.debug "SayWhen:: Looking for job that should be ready to fire before #{time_now}"
+        if job = self.storage.acquire_next(time_now)
+          logger.debug "SayWhen:: got a job: #{job.inspect}"
+        else
+          logger.debug "SayWhen:: no jobs to acquire"
+        end
+        job
+      end
+
+      def process(job, time_now)
+        # delegate processing the trigger to the processor
+        processor.process(job)
+        logger.debug "SayWhen:: job processed: #{job.inspect}"
+
+        # this should update next fire at, and put back in list of scheduled jobs
+        storage.fired(job, time_now)
+        logger.debug "SayWhen:: job fired: #{job.inspect}"
+      end
+
+      def release(job)
+        logger.info "SayWhen::Scheduler release: #{job.inspect}"
+        job.release if job
+      end
+
+      def tick(t = tick_length)
+        sleep(t.to_f)
+      end
+
+      def tick_length
+        @tick_length ||= SayWhen.options[:tick_length].to_f
+      end
+
+      def error_tick_length
+        @error_tick_length ||= SayWhen.options[:error_tick_length].to_f || tick_length
+      end
+
+      def reset_acquired_length
+        @reset_acquired_length ||= SayWhen.options[:reset_acquired_length].to_f
+      end
+
+      def processor
+        @processor ||= load_strategy(:processor, SayWhen.options[:processor_strategy])
+      end
+
+      def storage
+        @storage ||= load_strategy(:storage, SayWhen.options[:storage_strategy])
+      end
+
+      def logger
+        SayWhen.logger
+      end
+    end
+  end
+end