serially 0.3.1 → 0.4.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    ZWY0MjUzYTA4ODcwYjY1NmM3NDliZjZlZDIzY2NkMDBkZjNjNGM1NQ==
+    NzlmMzhlZjEwYWU1ZjRmMmUyYjA5MGVmZjZiMDQ2NTAyYzQwMzMyNQ==
   data.tar.gz: !binary |-
-    YjJlZGE3YjEwYzQwYTUwYTc3ZDczZTg5OWM1YTdjZDc4M2IwMTEyYw==
+    YjU1YjBlNGM4NjQ2ZmUxZDVkNTQyZGY2MzVkNTdlYjIyODQ4NTYwZQ==
 SHA512:
   metadata.gz: !binary |-
-    NTkwZmQ5NzVkNDczM2Y1ZDliYjUxOWFmYzlhNjdhZGY3N2Y5ZjJkMjdhM2Q1
-    NzI0Yjg4ZWZkZjM4MWE4MTlkMWI4ODEyOTQ1MmUyZDJkMTBkMTliZDQ3NDBk
-    MzU5MTk0ZmIxOTJhZDZhN2E3ZmJmN2UyN2MxNTRlNjQxZTM1ZDc=
+    MjFlYjZkOTcxODg5NjBiYjUzOTU0YWZmNjljZjc1NTA2OWZkYTgxNGE1ODhl
+    NmNiYTdhYzI5MzNmYzY5MGE0YmNlMDc4MmNlZjZlYTU2YmU3MTA2MzYwN2Uy
+    ODYwNDQ1YTFmOGUxMDQyMDBkNzZlYjdiYTY5N2M3OTk4NDhhNDI=
   data.tar.gz: !binary |-
-    YjEyNzMxNWYwODIyMThjYWY5NjE2Y2JkZDM5OTllM2NjYjUxNjg0YjAxZjU2
-    YzQzNTBhOWRlYWY4ZDBkMzAyZDMxMjcwMGJlODE0MjA5ODg2NTNlNDhhODVl
-    Y2JjNzdjMWMzN2E3NmQ0Yjc1NDQ5NTQ3ZjZiZDA5YWY3MWQxMzk=
+    OGJhOTg2NDJjMzNjZDljZjY0YWRkNTE5MGE4MmEzMGVjZTM1MmUxMzNjMzA1
+    ZjljNTFhZjJhODg5ZDU5ZjQ5ZmQ4M2ZjYzRkMGI3OWFjZmFmNTcwNDIxOGU3
+    MzdiZDU4MjVlMGQ0OTdlMjRkODMxODhkYjUyOWQ5ZDliYjJiZGQ=

data/README.md

@@ -50,13 +50,15 @@ class Post < ActiveRecord::Base
      end
 
      def draft
+        # each task must return a boolean, signifying whether it has succeeded or not
         puts "Post #{self.id} drafted"
         true
      end
 
      def review
         puts "Post #{self.id} reviewed by staff"
-        [true, 'reviewed by staff']
+        # in addition to a boolean status, task can also return a string and an arbitrary object
+        [true, 'reviewed by staff', {reviewed_by: 'Mike', reviewed_at: Date.today}]
      end
 
      def publish
@@ -70,7 +72,7 @@ class Post < ActiveRecord::Base
      end
    end
 ```
-### Start for Instance
+### Schedule for a Single Instance
 
 After creating an instance of a Post, you can run `post.serially.start!` to schedule your Post tasks to run serially. They will run one after the other in the scope of the same `Serially::Job`
 in the default `serially` queue.
@@ -90,7 +92,7 @@ Post 1 not published - bibliography is missing
 Post 2 reviewed by staff
 Post 2 not published - bibliography is missing
 ```
-### Start for Batch
+### Schedule Batch
 If you want to schedule serially tasks for multiple instances, you can do it in a single call:
 ```ruby
 Post.start_batch!([post1.id, post2.id, post3.id])
@@ -99,7 +101,7 @@ Post.start_batch!([post1.id, post2.id, post3.id])
 ### Task Return Values
 
 * A task should at minimum return a boolean value, signifying whether that task finished successfully or not
-* A task can also return a string with details of the task completion
+* A task can also return a string with details of the task completion and an arbitrary object
 * If a task returns _false_, the execution stops and the next tasks in the chain won't be performed for current instance
 
 ### Inspection
@@ -141,7 +143,9 @@ end
 ```
 Jobs for different instances of Post will all be scheduled in 'posts' queue, without any interference to each other.
 
-### Blocks
+### Callbacks
+
+#### Blocks
 In addition to instance methods, you can pass a block as a task callback, and you can mix both syntaxes in your class:
 
 ```ruby
@@ -151,21 +155,52 @@ class Post < ActiveRecord::Base
      serially do
         task :draft
         task :review do |post|
-            puts "Reviewing #{post.id}"
+            # finished successfully
             true
         end
         task :publish do |post|
-            puts "Publishing #{post.id}"
-            true
+            # block can return message and result object in addition to boolean status, just like the instance method
+            [true, 'published ok', {author: 'Mike}]
         end
      end
 
      def draft
-        puts "Drafting #{self.id}"
+        # using instance methods makes sense when your callback is more than 1 or 2 lines of code
         [false, 'drafting failed']
      end
 end
 ```
+#### On Error Callback
+You can provide an error handling callback for each task, which will be called if a task fails to finish successfully. If the error handling
+callback returns `true`, the execution will continue to next task, despite the failure of the previous one, otherwise tasks
+execution will stop as expected.
+
+```ruby
+class Post < ActiveRecord::Base
+     include Serially
+
+     serially do
+        task :draft, on_error: handle_draft_error
+        ...
+     end
+
+     def draft
+        # something happened here that caused draft to fail
+        result_obj = {author: 'Mike'}
+        [false, 'drafting failed', result_obj]
+     end
+
+     def handle_draft_error(msg, result_obj)
+        if result_obj[:author] == 'Mike'
+            # let's continue to next task
+            true
+        else
+            # can't continue executing tasks like nothing happened, have to stop
+            false
+        end
+     end
+end
+```
 
 ## Customize Plain Ruby Class Instantiation
 Before the first task runs, Serially creates an instance of your class, on which your task callbacks are then called. By default, instances of plain ruby classes

data/lib/generators/serially/install/templates/create_serially_task_runs.rb

@@ -7,7 +7,9 @@ class CreateSeriallyTaskRuns < ActiveRecord::Migration
       t.integer :task_order,      null: false
       t.integer  :status,         default: 0
       t.datetime :finished_at
-      t.text     :result_message
+      t.text :result_message
+      t.text :result_object
+      t.boolean :error_handled, default: false
       t.timestamps null: false
     end
 

data/lib/serially.rb

@@ -1,5 +1,6 @@
 require "serially/version"
 require 'serially/errors'
+require 'serially/options'
 require 'serially/serially'
 require 'serially/base'
 require 'serially/instance_base'
@@ -8,4 +9,4 @@ require 'serially/task_manager'
 require 'serially/task_runner'
 require 'serially/task_run'
 require 'serially/task_run_writer'
-require 'serially/job'
+require 'serially/job'

data/lib/serially/job.rb

@@ -9,7 +9,7 @@ module Serially
     extend Resque::Plugins::LonelyJob
 
     def self.queue
-      Serially::Options.default_queue
+      Serially::GlobalOptions.default_queue
     end
 
     # this ensures that for item_class=Invoice, and item_id=34500, only one job will run at a time

data/lib/serially/options.rb

@@ -0,0 +1,40 @@
+module Serially
+
+  class Options
+    # this should be overridden in sub-classes
+    def self.allowed
+      []
+    end
+
+    def self.validate(options)
+      invalid_options = {}
+
+      valid_options = options.select{ |k,v| allowed.include?(k) }
+      invalid_keys = options.keys.select{ |k| !allowed.include?(k) }
+      empty_values = valid_options.select{ |k, v| v.blank? }.keys
+
+      invalid_options['Unrecognized Keys'] = invalid_keys if invalid_keys.present?
+      invalid_options['Empty Values'] = empty_values if empty_values.present?
+
+      invalid_options
+    end
+  end
+
+  class GlobalOptions < Options
+    def self.allowed
+      [:in_queue]
+    end
+
+    def self.default_queue
+      'serially'
+    end
+  end
+
+  class TaskOptions < Options
+    def self.allowed
+      [:on_error]
+    end
+
+  end
+
+end

data/lib/serially/serially.rb

@@ -16,7 +16,7 @@ module Serially
 
       def serially(*args, &block)
         options = args[0] || {}
-        invalid_options = Serially::Options.validate(options)
+        invalid_options = Serially::GlobalOptions.validate(options)
         raise Serially::ConfigurationError.new("Serially received the following invalid options: #{invalid_options}") if invalid_options.present?
 
         # If TaskManager for current including class doesn't exist, create it
@@ -48,20 +48,23 @@ module Serially
 
       # override this to provide a custom way of creating instances of your class
       def create_instance(*args)
+        instance = nil
         args = args.flatten
         if self.is_active_record?
           if args.count == 1
-            args[0].is_a?(Fixnum) ? self.where(id: args[0]).first : self.where(args[0]).first
+            instance = args[0].is_a?(Fixnum) ? self.where(id: args[0]).first : self.where(args[0]).first
+            raise Serially::ArgumentError.new("Serially: couldn't create ActiveRecord instance with provided arguments: #{args[0]}") if instance.blank?
           else
             raise Serially::ArgumentError.new("Serially: default implementation of ::create_instance expects to receive either id or hash")
           end
         else
           begin
-            args.blank? ? new : new(*args)
+            instance = args.blank? ? new : new(*args)
           rescue StandardError => exc
             raise Serially::ArgumentError.new("Serially: since no implementation of ::create_instance is provided in #{self}, tried to call new, but failed with provided arguments: #{args}")
           end
         end
+        instance
       end
     end
 
@@ -72,30 +75,11 @@ module Serially
 
     # override this to provide a custom way of fetching id of your class' instance
     def instance_id
-      self.respond_to?(:id) ? self.id : self.object_id
-    end
-
-
-
-
-    class Options
-      ALLOWED = [:in_queue]
-
-      def self.default_queue
-        'serially'
-      end
-
-      def self.validate(options)
-        invalid_options = {}
-
-        valid_options = options.select{ |k,v| ALLOWED.include?(k) }
-        invalid_keys = options.keys.select{ |k| !ALLOWED.include?(k) }
-        empty_values = valid_options.select{ |k, v| v.blank? }.keys
-
-        invalid_options['Unrecognized Keys'] = invalid_keys if invalid_keys.present?
-        invalid_options['Empty Values'] = empty_values if empty_values.present?
-
-        invalid_options
+      if self.respond_to?(:id)
+        self.id
+      else
+        raise Serially::ArgumentError.new("Serially: default implementation of ::instance_id is not defined for plain Ruby class, please provide one")
       end
     end
+
 end

data/lib/serially/task.rb

@@ -34,23 +34,40 @@ module Serially
 
     # <i>args</i> - arguments needed to create an instance of your class. If you don't provide custom implementation for create_instance,
     # pass instance_id or hash of arguments,
-    def run!(*args)
-      instance = args[0].blank? ? instance = @klass.send(:create_instance) : @klass.send(:create_instance, *args)
+    def run!(instance)
       if instance
         if !@run_block && !instance.respond_to?(@name)
           raise Serially::ConfigurationError.new("Serially task #{@name} in class #{@klass} doesn't have an implementation method or a block to run")
         end
         begin
-          status, msg = @run_block ? @run_block.call(instance) : instance.send(@name)
+          status, msg, result_obj = @run_block ? @run_block.call(instance) : instance.send(@name)
         rescue StandardError => exc
-          return [false, "Serially: task '#{@name}' raised exception: #{exc.message}"]
+          return [false, "Serially: task '#{@name}' raised exception: #{exc.message}", exc]
         end
       else
         return [false, "Serially: instance couldn't be created, task '#{@name}'' not started"]
       end
-      # returns true (unless status == nil/false/[]) and '' (unless msg is a not empty string)
-      [status.present?, msg.to_s]
+      # returns true (unless status == nil/false/[]), '' (unless msg is a not empty string) and result_obj, which might be nil
+      # if task doesn't return it
+      [status.present?, msg.to_s, result_obj]
+    end
+
+    def on_error!(instance, result_msg, result_obj)
+      if options[:on_error]
+        if !klass.method_defined?(options[:on_error])
+          raise Serially::ConfigurationError.new("Serially: error handler #{options[:on_error]} not found for task #{self.name}")
+        end
+
+        begin
+          status = instance.send(options[:on_error], result_msg, result_obj)
+        rescue StandardError => exc
+          Resque.logger.error("Serially: error handler for task '#{@name}' raised exception: #{exc.message}")
+          status = false
+        end
+        status
+      end
     end
 
   end
+
 end

data/lib/serially/task_manager.rb

@@ -34,6 +34,10 @@ module Serially
     def add_task(task_name, task_options, &block)
       raise Serially::ConfigurationError.new("Task #{task_name} is already defined in class #{@klass}") if @tasks.include?(task_name)
       raise Serially::ConfigurationError.new("Task name #{task_name} defined in class #{@klass} is not a symbol") if !task_name.is_a?(Symbol)
+
+      invalid_options = Serially::TaskOptions.validate(task_options)
+      raise Serially::ConfigurationError.new("Task #{task_name} received the following invalid options: #{invalid_options}") if invalid_options.present?
+
       @tasks[task_name] = Serially::Task.new(task_name, next_task_order!, task_options, self, &block)
     end
 

data/lib/serially/task_run.rb

@@ -3,6 +3,7 @@ require 'active_record'
 module Serially
   class TaskRun < ActiveRecord::Base
     enum status: { pending: 0, started: 1, started_async: 2, finished_ok: 3, finished_error: 4 }
+    serialize :result_object
 
     self.table_name = 'serially_task_runs'
 
@@ -19,7 +20,7 @@ module Serially
       finished_ok? || finished_error?
     end
 
-    def self.write_task_run(task, item_id, success, msg)
+    def self.write_task_run(task, item_id, success, result_msg, result_obj, error_handled)
       task_run = TaskRun.where(item_class: task.klass, item_id: item_id, task_name: task.name).first_or_initialize
       if task_run.finished?
         Resque.logger.warn("Serially: task '#{task.name}' for #{task.klass}/#{item_id} finished already, not saving this task run")
@@ -28,7 +29,9 @@ module Serially
         saved = task_run.tap {|t|
           t.task_order = task.task_order
           t.status = success ? TaskRun.statuses[:finished_ok] : TaskRun.statuses[:finished_error]
-          t.result_message = msg
+          t.result_message = result_msg
+          t.result_object = result_obj
+          t.error_handled = error_handled
           t.finished_at = DateTime.now
         }.save
         saved

data/lib/serially/task_run_writer.rb

@@ -1,9 +1,9 @@
 module Serially
   class TaskRunWriter
 
-    # called by TaskRunner, after each task has finished running
-    def update(task, item_id, success, msg)
-      TaskRun.write_task_run(task, item_id, success, msg)
+    # called by TaskRunner, after each task and its error handler have finished running
+    def update(task, instance, success, msg, result_obj, error_handled)
+      TaskRun.write_task_run(task, instance.instance_id, success, msg, result_obj, error_handled)
     end
 
   end

data/lib/serially/task_runner.rb

@@ -10,6 +10,7 @@ module Serially
 
     def run!(item_class, item_id = nil)
       last_run = []
+      instance = item_id.blank? ? item_class.send(:create_instance) : item_class.send(:create_instance, item_id)
       Serially::TaskManager[item_class].each do |task|
         # if task.async?
         #   started_async_task = SerialTasksManager.begin_task(task)
@@ -18,14 +19,15 @@ module Serially
         # else
         #started_async_task = false
 
-        success, msg = task.run!(item_id)
-        last_run = [task, success, msg]
+        success, msg, result_obj = task.run!(instance)
+        error_handled = task.on_error!(instance, msg, result_obj) if !success
+        last_run = [task, success, msg, result_obj]
 
         # write result log to DB
         changed
-        notify_observers(task, item_id, success, msg)
-        # if task didn't complete successfully, exit
-        break if !success
+        notify_observers(task, instance, success, msg, result_obj, error_handled)
+        # if task didn't complete successfully, and error handler didn't return true, exit
+        break if !success && !error_handled
       end
       # if started_async_task
       #   msg = "SerialTasksManager: started async task for #{item_class}/#{item_id}. Worker is exiting..."

data/lib/serially/version.rb

@@ -1,3 +1,3 @@
 module Serially
-  VERSION = "0.3.1"
+  VERSION = "0.4.0"
 end

data/serially.gemspec

@@ -35,9 +35,8 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'sqlite3'
 
   spec.description   = <<desc
-Have you ever had a class that required a series of background tasks to run serially, strictly one after another? Than Serially is for you.
-Declare the tasks using a simple DSL in the order you want them to to run. Serially will wrap them in a single job, and schedule it using Resque
-in a queue you specify (or a default one). The next task will run only if previous one finished successfully. All task runs are written to DB and can be inspected (if
+Have you ever had a class whose instances required a series of background tasks to run serially, strictly one after another? Than Serially is for you.
+Declare the tasks using a simple DSL in the order you want them to to run. The tasks for each instance will run inside a separate Resque job, in a queue you specify. The next task will run only if the previous one has finished successfully. All task runs are written to DB and can be inspected (if
 your class is an ActiveRecord object).
 desc
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: serially
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Mike Polischuk
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-01-09 00:00:00.000000000 Z
+date: 2016-01-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: resque
@@ -164,15 +164,13 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: ! 'Have you ever had a class that required a series of background tasks
-  to run serially, strictly one after another? Than Serially is for you.
+description: ! 'Have you ever had a class whose instances required a series of background
+  tasks to run serially, strictly one after another? Than Serially is for you.
 
-  Declare the tasks using a simple DSL in the order you want them to to run. Serially
-  will wrap them in a single job, and schedule it using Resque
-
-  in a queue you specify (or a default one). The next task will run only if previous
-  one finished successfully. All task runs are written to DB and can be inspected
-  (if
+  Declare the tasks using a simple DSL in the order you want them to to run. The tasks
+  for each instance will run inside a separate Resque job, in a queue you specify.
+  The next task will run only if the previous one has finished successfully. All task
+  runs are written to DB and can be inspected (if
 
   your class is an ActiveRecord object).
 
@@ -202,6 +200,7 @@ files:
 - lib/serially/errors.rb
 - lib/serially/instance_base.rb
 - lib/serially/job.rb
+- lib/serially/options.rb
 - lib/serially/serially.rb
 - lib/serially/task.rb
 - lib/serially/task_manager.rb