serially 0.1.2 → 0.1.3

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    NzdmYzRhYTIwNDM3YmE3ODRhOTU3YzM0Y2MwNzg2YjlmYWRkNzU4ZA==
+    M2ZlZTI1ZjYzZmYwMTBhZDQ5ZDZhM2U3MTMzYjVmYmQwYzUwZTdjMQ==
   data.tar.gz: !binary |-
-    OWNlNTI3MGMxN2ZiMjE5MGQwMTA5ZWE3MWFkNjQyM2JiY2IwY2Q3Mg==
+    YmIzNTJmZGZhMGY1ZGZhMzY5YmUzNTZjNmI3MDRkZTU1Zjg1ZmI5YQ==
 SHA512:
   metadata.gz: !binary |-
-    ZDBkMTUyNTY3ZjA5MDlmMGVkYzUyYzRmYzgxNTUxOTdmNzFjZTNiMDg3Y2Fj
-    NTZhMmViZjRhMDE1M2M4YzViNWVlY2Q1Nzg0OGZiOGE1YTBhNTc4NjljZWE5
-    MGI3Y2ViYzEzOTEzM2FhNWEwNmQ2YmYxODc3MTY3N2IwM2MyOGI=
+    YWZhYzgzMTlhY2FkMzdlMDAyMWMyYTQ1ZjIzYjhkOWZmYzE4MjZiYTRjNzRk
+    MWM2YjI5N2NiMjBmNTNmOTAwZGQxZDc4YTkxNWQ4NTg2YWM3NTFjY2YxNzcy
+    OTg1N2U0MDFjMDYwYzA1YTJhYTkxOTdiNTU0ZTIyYzBjOWQ0ZGM=
   data.tar.gz: !binary |-
-    NmJmMjJiOGM3MDQ5ZmExYjZhZjk1N2E5YzczMDQwYTBmMjZkZDYyZmI2MjQ3
-    YjgwZDc0NTQ2NjJlNzczYzM5ODlmNjhjNWZlZmI3Mzc2ODc1MjRmZTA2Y2Rh
-    NjVmY2Y5Y2VkYjUzYzNkNjBiZmMxZWRlNzIxOGYwZmYwN2I3N2U=
+    NjhjMTM3NTMwNTRhODQ3NTcxYmFkOTE5MWVjODg4ZGRlZjc3OGUyYjY2MWRj
+    MjA2ZGYwNDMwYzRjM2MyOTlmZjg2Y2M0NGRlN2FlOTI0YzkwNmI5NDdmZjhm
+    MWVkOGI0Y2YxYTM3ZjRhNjcxNGIxMjVmNGM0ZTY1MTNlNjA4MjU=

data/.pryrc

@@ -1,49 +1 @@
-require './spec/active_record_helper'
-
-class SimpleClass
-      include Serially
-
-      serially do
-        task :enrich
-        task :validate
-        task :refund
-        task :archive
-      end
-end
-
-class SimpleSubClass < SimpleClass
-  include Serially
-
-  serially do
-    task :zip
-    task :send
-    task :acknowledge
-  end
-end
-
-class SimpleModel < ActiveRecord::Base
-  include Serially
-
-  self.table_name =  'simple_items'
-
-  serially do
-    task :model_step1
-    task :model_step2
-    task :model_step3
-  end
-end
-
-def create_simple
-    simple = SimpleClass.new
-    simple
-end
-
-def create_sub
-    simple = SimpleSubClass.new
-    simple
-end
-
-def create_model
-    simple = SimpleModel.create(title: 'IAmSimple')
-    simple
-end
+require './spec/active_record_helper'

data/README.md

@@ -4,13 +4,11 @@
 [![Code Climate](https://codeclimate.com/github/mikemarsian/serially/badges/gpa.svg)](https://codeclimate.com/github/mikemarsian/serially)
 
 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.
-All background jobs are scheduled using resque in a queue called `serially`, and Serially makes sure that for every instance of your class, only one task runs at a time.
-Different instances of the same class do not interfere with each other and their tasks can run in parallel.
-Serially works for both plain ruby classes and ActiveRecord models. In case of the latter, all task runs results are written to `serially_tasks` table which you can interrogate pragmatically using `Serially::TaskRun` model.
+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 `serially` queue (the queue is customizable). The next task will start only if previous one finished successfully. All task runs are written to DB  and can be inspected (if
+your class is an ActiveRecord object).
 
-See [this rails demo app][1] that showcases how Serially gem can be used.
-
-Note: this gem is in active development and currently is not intended to run in production.
+Check [this demo app][1] to see how Serially may be used in a Rails app.
 
 ## Installation
 
@@ -30,7 +28,7 @@ Or install it yourself as:
 
 ## Optional ActiveRecord Setup
 
-If you use ActiveRecord, you can generate a migration that creates `serially_task_runs` table, which would be used to write the results of all your task runs.
+If you use ActiveRecord, you can generate a migration that creates `serially_task_runs` table, which would be used to write the results of all task runs.
 
     $ rails generate serially:install
     $ rake db:migrate
@@ -69,7 +67,7 @@ class Post < ActiveRecord::Base
    end
 ```
 
-After creating 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::Worker` job.
+After creating 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`.
 An example run:
 ```ruby
 post1 = Post.create(title: 'Critique of Pure Reason', author: 'Immanuel Kant') #=> <Post id: 1, title: 'Critique of Pure Reason'...>
@@ -93,10 +91,18 @@ Post 2 not published - bibliography is missing
 * A task can also return a string with details of the task completion
 * If a task returns _false_, the execution stops and the next tasks in the chain won't be performed for current instance
 
-### Inspecting Task Runs
-
-You can inspect task runs results using the provided `Serially::TaskRun` model and its associated `serially_task_runs` table.
-Running `Serially::TaskRun.all` for the above example, will show something like this:
+### Inspection
+The easiest way to inspect the task run results, is using `serially.task_runs` instance method (which is supported for ActiveRecord classes only):
+```ruby
+post1.serially.task_runs # => returns ActiveRecord::Relation of all task runs for post1, ordered by their order of running
+post1.serially.task_runs.finished # => returns Relation of all tasks runs that finished (successfully or not) for post1
+post1.serially.task_runs.finished_ok # => returns Relation of all tasks runs that finished successfully for post1
+post1.serially.task_runs.finished_error # => returns Relation of all tasks runs that finished with error for post1
+post1.serially.task_runs.finished.last.task_name # => returns the name of the last finished task for post1
+post1.serially.task_runs.count # => all the usual ActiveRecord queries can be used
+```
+You can also inspect task runs results using the `Serially::TaskRun` model directly. Calling `Serially::TaskRun.all`
+for the previous task runs example, will show something like this:
 ```
 +----+------------+---------+-----------+----------------+----------------------+---------------------+
 | id | item_class | item_id | task_name | status         | result_message       | finished_at         |
@@ -111,6 +117,18 @@ Running `Serially::TaskRun.all` for the above example, will show something like
 ```
 Notice that the _promote_ task didn't run at all, since the _publish_ task that ran before it returned _false_ for both posts.
 
+### Configuration
+You can specify in which Resque queue the task-containing `Serially::Job` will be scheduled:
+```ruby
+class Post
+     include Serially
+
+     serially in_queue: 'posts' do
+        ...
+     end
+end
+```
+`Serially::Job`'s of different instances of Post will all be scheduled in 'posts' queue, without any interference to each other.
 
 ### Blocks
 In addition to instance methods, you can pass a block as a task callback, and you can mix both syntaxes in your class:
@@ -123,14 +141,17 @@ class Post < ActiveRecord::Base
         task :draft
         task :review do |post|
             puts "Reviewing #{post.id}"
+            true
         end
         task :publish do |post|
             puts "Publishing #{post.id}"
+            true
         end
      end
 
      def draft
         puts "Drafting #{self.id}"
+        [false, 'drafting failed']
      end
 end
 ```
@@ -156,11 +177,11 @@ class Post
 
 
      serially do
-        # ...
+        ...
      end
 end
 
-class Post
+class PostWithAuthor
      include Serially
 
      attr_accessor :title
@@ -177,7 +198,7 @@ class Post
 
 
      serially do
-        # ...
+        ...
      end
 end
 ```
@@ -199,6 +220,8 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/mikema
 
 ## License
 
+Copyright (c) 2015-2016 Mike Polischuk
+
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
 
 [1]: https://github.com/mikemarsian/serially-demo

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

@@ -4,6 +4,7 @@ class CreateSeriallyTaskRuns < ActiveRecord::Migration
       t.string  :item_class,          null: false
       t.string :item_id,        null: false
       t.string :task_name,        null: false
+      t.integer :task_order,      null: false
       t.integer  :status,         default: 0
       t.datetime :finished_at
       t.text     :result_message

data/lib/serially/errors.rb

@@ -4,4 +4,6 @@ module Serially
 
   class ConfigurationError < RuntimeError; end
 
+  class NotSupportedError < RuntimeError; end
+
 end

data/lib/serially/instance_base.rb

@@ -11,10 +11,14 @@ module Serially
     def_delegator :@task_manager, :tasks
 
     def start!
-      Serially::Worker.enqueue(@instance.class, @instance.instance_id)
+      Serially::Job.enqueue(@instance.class, @instance.instance_id, @task_manager.queue)
+    end
+
+    def task_runs
+      raise NotSupportedError.new('Serially: task_runs query is supported only for ActiveRecord classes') unless @instance.class.is_active_record?
+      Serially::TaskRun.where(item_class: @instance.class.to_s, item_id: @instance.id).order('task_order ASC')
     end
 
-    private
 
   end
 end

data/lib/serially/{worker.rb → job.rb}

@@ -3,14 +3,13 @@ require 'resque'
 require 'resque-lonely_job'
 
 module Serially
-  class Worker
+  class Job
     # LonelyJob ensures that only one job a time runs per item_class/item_id (such as Invoice/34599), which
     # effectively means that for every invoice there is only one job a time, which ensures invoice jobs are processed serially
     extend Resque::Plugins::LonelyJob
 
-    @queue = 'serially'
     def self.queue
-      @queue
+      Serially::Options.default_queue
     end
 
     # this ensures that for item_class=Invoice, and item_id=34500, only one job will run at a time
@@ -26,12 +25,8 @@ module Serially
       Resque.logger.info(result_str)
     end
 
-    def self.enqueue(item_class, item_id)
-      Resque.enqueue(Serially::Worker, item_class.to_s, item_id)
-    end
-
-    def self.enqueue_batch(item_class, items)
-      items.each {|item| enqueue(item_class.to_s, item.instance_id)}
+    def self.enqueue(item_class, item_id, enqueue_to = nil)
+      Resque.enqueue_to(enqueue_to || self.queue, Serially::Job, item_class.to_s, item_id)
     end
   end
 end

data/lib/serially/serially.rb

@@ -16,10 +16,12 @@ module Serially
 
       def serially(*args, &block)
         options = args[0] || {}
+        invalid_options = Serially::Options.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
-        task_manager = Serially::TaskManager.new(self, options)
-        Serially::TaskManager[self] ||= task_manager
+        Serially::TaskManager[self] ||= Serially::TaskManager.new(self, options)
+        task_manager = Serially::TaskManager[self]
 
         # create a new base, and resolve DSL
         @serially = Serially::Base.new(task_manager)
@@ -65,4 +67,28 @@ module Serially
     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
+      end
+    end
 end

data/lib/serially/task.rb

@@ -1,10 +1,11 @@
 module Serially
   class Task
 
-    attr_accessor :name, :klass, :options, :run_block
+    attr_accessor :name, :task_order, :klass, :options, :run_block
 
-    def initialize(task_name, options, task_manager, &run_block)
+    def initialize(task_name, task_order, options, task_manager, &run_block)
       @name = task_name.to_sym
+      @task_order = task_order
       @klass = task_manager.klass
       @options = options
       @run_block = run_block

data/lib/serially/task_manager.rb

@@ -10,13 +10,18 @@ module Serially
       (@task_managers ||= {})[klass.to_s] = task_manager
     end
 
-    attr_accessor :tasks, :options, :klass
+    attr_accessor :tasks, :options, :klass, :queue
 
     def initialize(klass, options = {})
       @klass = klass
       @options = options
       # Hash is ordered since Ruby 1.9
       @tasks = {}
+      @last_task_order = 0
+    end
+
+    def queue
+      @options[:in_queue]
     end
 
     def clone_for(new_klass)
@@ -29,7 +34,7 @@ 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)
-      @tasks[task_name] = Serially::Task.new(task_name, task_options, self, &block)
+      @tasks[task_name] = Serially::Task.new(task_name, next_task_order!, task_options, self, &block)
     end
 
     # Allow iterating over tasks
@@ -41,5 +46,14 @@ module Serially
       end
     end
 
+    private
+
+    # returns next task order, and advances the counter
+    def next_task_order!
+      current_order = @last_task_order
+      @last_task_order += 1
+      current_order
+    end
+
   end
 end

data/lib/serially/task_run.rb

@@ -9,15 +9,10 @@ module Serially
     validates :item_class, :item_id, :task_name, presence: true
     validates :task_name, uniqueness: { scope: [:item_class, :item_id] }
 
-    def self.create_from_hash!(args = {})
-      task_run = TaskRun.new do |t|
-        t.item_class = args[:item_class] if args[:item_class].present?
-        t.item_id = args[:item_id] if args[:item_id].present?
-        t.status = args[:status] if args[:status].present?
-        t.task_name = args[:task_name] if args[:task_name].present?
-      end
-      task_run.save!
-      task_run
+    scope :finished, -> { where(status: finished_statuses) }
+
+    def self.finished_statuses
+      [TaskRun.statuses[:finished_ok], TaskRun.statuses[:finished_error]]
     end
 
     def finished?
@@ -31,6 +26,7 @@ module Serially
         false
       else
         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.finished_at = DateTime.now

data/lib/serially/task_runner.rb

@@ -35,7 +35,7 @@ module Serially
 
       # If we are here, it means that no more tasks were found
       success = last_run[1]
-      msg = success ? "Serially: finished all tasks for #{item_class}/#{item_id}. Serially::Worker is exiting..." :
+      msg = success ? "Serially: finished all tasks for #{item_class}/#{item_id}. Serially::Job is stopping..." :
                       "Serially: task '#{last_run[0]}' for #{item_class}/#{item_id} finished with success: #{last_run[1]}, message: #{last_run[2]}"
       msg
     end

data/lib/serially/version.rb

@@ -1,3 +1,3 @@
 module Serially
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 end

data/lib/serially.rb

@@ -8,4 +8,4 @@ require 'serially/task_manager'
 require 'serially/task_runner'
 require 'serially/task_run'
 require 'serially/task_run_writer'
-require 'serially/worker'
+require 'serially/job'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: serially
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Mike Polischuk
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-01-01 00:00:00.000000000 Z
+date: 2016-01-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: resque
@@ -202,6 +202,7 @@ files:
 - lib/serially/base.rb
 - lib/serially/errors.rb
 - lib/serially/instance_base.rb
+- lib/serially/job.rb
 - lib/serially/serially.rb
 - lib/serially/task.rb
 - lib/serially/task_manager.rb
@@ -209,7 +210,6 @@ files:
 - lib/serially/task_run_writer.rb
 - lib/serially/task_runner.rb
 - lib/serially/version.rb
-- lib/serially/worker.rb
 - serially.gemspec
 homepage: http://github.com/mikemarsian/serially
 licenses: