taskinator 0.0.5 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 96866a7042bc2b7082aaeead94c5c90f00448f0b
-  data.tar.gz: 42636386ce754b64ce167fe858a59e8c2a0a8286
+  metadata.gz: bb55f92dd0ef5d48b4fb0d1f3d82093c59fdca7c
+  data.tar.gz: c87595e40a584e0913571dbc50176ae8236010d2
 SHA512:
-  metadata.gz: 061588463242d2d1d11827a339dc17a7903b07631b7194a7ce43639e1d3c4c1a96ec7a24cd62a79e7bb8fa0354a59539ae7fc026377acc22be801f816b6bd3e0
-  data.tar.gz: 19da642b98496489815a1f2e741cda7e8f6fc9885c2becf896e09be7f48b7cdf0d85a5c0c8fb9e9bcd2aac26ecfed2fdcb7bdbb4d114d52faff356ca56eddf73
+  metadata.gz: 71858572f752ee6a0572607fb70607e36a49df6334e83c5c1a477675b70f41f75cbefc04e23cefb802bac39adc1207d947d69d580954d51e9992804a7ef2aa95
+  data.tar.gz: a405c8209923653109f732d03601f2747cf35642ae452b44598ad78487c3c639a3ae91ba065c887116e7b47c7e512374104994a8b8c9a9f7b812e47530af5b96

data/Gemfile.lock

@@ -8,7 +8,7 @@ GIT
 PATH
   remote: .
   specs:
-    taskinator (0.0.5)
+    taskinator (0.0.7)
       connection_pool (>= 2.0.0)
       json (>= 1.8.1)
       redis (>= 3.0.6)
@@ -38,18 +38,18 @@ GEM
       term-ansicolor
       thor
     debugger-linecache (1.2.0)
-    delayed_job (4.0.3)
+    delayed_job (4.0.4)
       activesupport (>= 3.0, < 4.2)
     diff-lcs (1.2.5)
     docile (1.1.5)
     i18n (0.6.11)
     json (1.8.1)
     method_source (0.8.2)
-    mime-types (2.3)
-    minitest (5.4.1)
+    mime-types (2.4.2)
+    minitest (5.4.2)
     mono_logger (1.1.0)
     multi_json (1.10.1)
-    netrc (0.7.7)
+    netrc (0.7.8)
     pry (0.9.12.6)
       coderay (~> 1.0)
       method_source (~> 0.8)
@@ -82,23 +82,23 @@ GEM
       rspec-core (~> 3.1.0)
       rspec-expectations (~> 3.1.0)
       rspec-mocks (~> 3.1.0)
-    rspec-core (3.1.3)
+    rspec-core (3.1.7)
       rspec-support (~> 3.1.0)
-    rspec-expectations (3.1.1)
+    rspec-expectations (3.1.2)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.1.0)
-    rspec-mocks (3.1.0)
+    rspec-mocks (3.1.3)
       rspec-support (~> 3.1.0)
-    rspec-support (3.1.0)
+    rspec-support (3.1.2)
     sidekiq (3.2.5)
       celluloid (= 0.15.2)
       connection_pool (>= 2.0.0)
       json
       redis (>= 3.0.6)
       redis-namespace (>= 1.3.1)
-    simplecov (0.9.0)
+    simplecov (0.9.1)
       docile (~> 1.1.0)
-      multi_json
+      multi_json (~> 1.0)
       simplecov-html (~> 0.8.0)
     simplecov-html (0.8.0)
     sinatra (1.4.5)
@@ -112,7 +112,7 @@ GEM
     thread_safe (0.3.4)
     tilt (1.4.1)
     timers (1.1.0)
-    tins (1.3.2)
+    tins (1.3.3)
     tzinfo (1.2.2)
       thread_safe (~> 0.1)
     vegas (0.1.11)

data/README.md

@@ -69,8 +69,28 @@ module MyProcess
 end
 ```
 
-Specify the tasks with their corresponding implementation methods, that make up the process, using the `task` method and providing
-a `name` and `method` to execute for the task.
+The `define_process` method optionally takes the list of expected arguments which are used to validate the
+arguments supplied when creating a new process. These should be specified with symbols.
+
+```ruby
+module MyProcess
+  extend Taskinator::Definition
+
+  # defines a process
+  define_process :date, :options do
+    # ...
+  end
+end
+
+# when creating a process, 2 arguments are expected
+process = MyProcess.create_process Date.today, :option_1 => true
+```
+
+NOTE: The current implementation performs a naive check on the count of arguments, but this will be
+improved in subsequent versions.
+
+Next, specify the tasks with their corresponding implementation methods, that make up the process,
+using the `task` method and providing the `method` to execute for the task.
 
 ```ruby
 module MyProcess
@@ -124,7 +144,35 @@ module MyProcess
 end
 ```
 
-You can define data driven tasks using the `for_each` method, which takes an iterator method as an argument.
+It is likely that you have already have worker classes for one of the queueing libraries, such as resque or delayed_job, and wish to
+reuse them for executing them in the sequence defined by the process definition.
+
+You define a `job` step, providing the class of the worker, and them taskinator will execute that worker as part of the process definition.
+The `job` step will be queued and executed on the configured queue for `delayed_job`, or that of the worker for `resque` and `sidekiq`.
+
+```ruby
+# E.g. A resque worker
+class DoSomeWork
+  queue :high_priority
+
+  def self.perform(arg1, arg2)
+    # code to do the work
+  end
+end
+
+module MyProcess
+  extend Taskinator::Definition
+
+  # when creating the process, supply the same arguments
+  # that the DoSomeWork worker expects
+
+  define_process do
+    job DoSomeWork
+  end
+end
+```
+
+You can also define data driven tasks using the `for_each` method, which takes an iterator method name as an argument.
 The iterator method yields the items to produce a parameterized task for that item. Notice that the task method
 takes a parameter in this case, which will be the item provided by the iterator.
 
@@ -149,6 +197,67 @@ module MyProcess
 end
 ```
 
+It is possible to branch the process logic based on the options hash passed in when creating a process.
+The `options?` method takes the options key as an argument and calls the supplied block if the option
+is present and it's value is truthy.
+
+```ruby
+module MyProcess
+  extend Taskinator::Definition
+
+  define_process do
+
+    option?(:some_setting) do
+      task :prerequisite_step
+    end
+
+    task :work_step
+
+  end
+
+  def prerequisite_step
+    # ...
+  end
+
+  def work_step
+    # ...
+  end
+
+end
+
+# now when creating the process, the `:some_setting` option can be used to branch the logic
+process1 = MyProcess.create_process :some_setting => true
+process1.tasks.count #=> 2
+
+process2 = MyProcess.create_process
+process2.tasks.count #=> 1
+```
+
+In addition, it is possible to transform the arguments used by a task or job, by including a `transform` step in the definition.
+Similarly to the `for_each` method, `transform` takes a method name as an argument. The transformer method must yield the new arguments as required.
+
+```ruby
+module MyProcess
+  extend Taskinator::Definition
+
+  # this process is created with a hash argument
+
+  define_process do
+    transform :convert_args do
+      task :work_step
+    end
+  end
+
+  def convert_args(options)
+    yield *[options[:date_from], options[:date_to]]
+  end
+
+  def work_step(date_from, date_to)
+    # TODO: supply implementation
+  end
+end
+```
+
 Processes can be composed of other processes too:
 
 ```ruby
@@ -207,6 +316,33 @@ In this example, the `work_step_begin` is executed, followed by the `work_step_a
 the sub process `MySubProcess` is created and executed, followed by the `work_step_one_by_one` tasks which are executed sequentially and
 finally the `work_step_end` is executed.
 
+It is also possible to embed conditional logic within the process definition stages in order to produce steps based on the required logic.
+All builder methods are available within the scope of the `define_process` block. These methods include `args` and `options`
+which are passed into the `create_process` method of the definition.
+
+E.g.
+
+```ruby
+module MyProcess
+  extend Taskinator::Definition
+
+  define_process do
+    task :task_1
+    task :task_2
+    task :task_3 if args[3] == 1
+    task :send_notification if options[:send_notification]
+  end
+
+  # "task" methods are omitted for brevity
+
+end
+
+# when creating this proces, you supply to option when calling `create_process`
+# in this example, 'args' will be an array [1,2,3] and options will be a Hash {:send_notification => true}
+MyProcess.create_process(1, 2, 3, :send_notification => true)
+
+```
+
 ### Execution
 
 A process is executed by calling the generated `create_process` method on your "process" module.
@@ -216,9 +352,201 @@ process = MyProcess.create_process
 process.enqueue!
 ```
 
+Or, to start immediately, call the `start!` method.
+
+```ruby
+process = MyProcess.create_process
+process.start!
+```
+
 #### Arguments
 
-_TBD_
+Argument handling for defining and executing process definitions is where things can get trickey.
+_This may be something that gets refactored down the line_.
+
+To best understand how arguments are handled, you need to break it down into 3 phases. Namely:
+
+  * Definition,
+  * Creation and
+  * Execution
+
+Firstly, a process definition is declarative in that the `define_process` and a mix of `sequential`, `concurrent`, `for_each`,
+`task` and `job` directives provide the way to specify the sequencing of the steps for the process.
+Taskinator will interprete this definition and execute each step in the desired sequence or concurrency.
+
+Consider the following process definition:
+
+```ruby
+module MySimpleProcess
+  extend Taskinator::Definition
+
+  # definition
+
+  define_process do
+    task :work_step_1
+    task :work_step_2
+
+    for_each :additional_step do
+      task :work_step_3
+    end
+  end
+
+  # creation
+
+  def additional_step(options)
+    options.steps.each do |k, v|
+      yield k, v
+    end
+  end
+
+  # execution
+
+  def work_step_1(options)
+    # ...
+  end
+
+  def work_step_2(options)
+    # ...
+  end
+
+  def work_step_3(k, v)
+    # ...
+  end
+
+end
+```
+
+There are three tasks; namely `:work_step_1`, `:work_step_2` and `:work_step_3`.
+
+The third task, `:work_step_3`, is built up using the `for_each` iterator, which means that the number of `:work_step_3` tasks
+will depend on how many times the `additional_step` iterator method yields to the definition.
+
+This brings us to the creation part. When `create_process` is called on the given module, you provide arguments to it, which will get
+passed onto the respective `task` and `for_each` iterator methods.
+
+So, considering the `MySimpleProcess` module shown above, `work_step_1`, `work_step_2` and `work_step_3` methods each expect arguments.
+These will ultimately come from the arguments passed into the `create_process` method.
+
+E.g.
+
+```ruby
+
+# Given an options hash
+options = {
+  :opt1 => true,
+  :opt2 => false,
+  :steps => {
+    :a => 1,
+    :b => 2,
+    :c => 3,
+  }
+}
+
+# You create the process, passing in the options hash
+process = MySimpleProcess.create_process(options)
+
+```
+
+To best understand how the process is created, consider the following "procedural" code for how it could work.
+
+```ruby
+# A process, which maps the target and a list of steps
+class Process
+  attr_reader :target
+  attr_reader :tasks
+
+  def initialize(target)
+    @target = target
+    @tasks = []
+  end
+end
+
+# A task, which maps the method to call and it's arguments
+class Task
+  attr_reader :method
+  attr_reader :args
+
+  def initialize(method, args)
+    @method, @args = method, args
+  end
+end
+
+# Your module, with the methods which do the actual work
+module MySimpleProcess
+
+  def self.work_step_1(options) ...
+  def self.work_step_2(options) ...
+  def self.work_step_3(k, v) ...
+
+end
+
+# Now, the creation phase of the definition
+# create a process, providing the module
+
+process = Process.new(MySimpleProcess)
+
+# create the first and second tasks, providing the method
+# for the task and it's arguments, which are the options defined above
+
+process.tasks << Task.new(:work_step_1, options)
+process.tasks << Task.new(:work_step_2, options)
+
+# iterate over the steps hash in the options, and add the third step
+# this time specify the key and value as the
+# arguments for the work_step_3 method
+
+options.steps.each do |k, v|
+  process.tasks << Task.new(:work_step_3, [k, v])
+end
+
+# we now have a process with the tasks defined
+
+process.tasks  #=> [<Task :method=>work_step_1, :args=>options, ...> ,
+               #    <Task :method=>work_step_2, :args=>options, ...>,
+               #    <Task :method=>work_step_3, :args=>[:a, 1], ...>,
+               #    <Task :method=>work_step_3, :args=>[:b, 2], ...>,
+               #    <Task :method=>work_step_3, :args=>[:c, 3], ...>]
+
+```
+
+Finally, for the execution phase, the process and tasks will act on the supplied module.
+
+```ruby
+# building out the "Process" class
+class Process
+  #...
+
+  def execute
+    tasks.each {|task| task.execute(target) )
+  end
+end
+
+# and the "Task" class
+class Task
+  #...
+
+  def execute(target)
+    puts "Calling '#{method}' on '#{target.name}' with #{args.inspect}..."
+    target.send(method, *args)
+  end
+end
+
+# executing the process iterates over each task and
+# the target modules method is called with the arguments
+
+process.execute
+
+# Calling 'work_step_1' on 'MySimpleProcess' with {:opt1 => true, :opt2 => false, ...}
+# Calling 'work_step_2' on 'MySimpleProcess' with {:opt1 => true, :opt2 => false, ...}
+# Calling 'work_step_3' on 'MySimpleProcess' with [:a, 1]
+# Calling 'work_step_3' on 'MySimpleProcess' with [:b, 2]
+# Calling 'work_step_3' on 'MySimpleProcess' with [:c, 3]
+
+```
+
+In reality, each task is executed by a worker process, possibly on another host, so the execution process isn't as simple,
+but this example should help you to understand conceptually how the process is executed, and how the arguments are propagated
+through.
 
 ### Monitoring
 

data/lib/taskinator/definition/builder.rb

@@ -5,14 +5,20 @@ module Taskinator
       attr_reader :process
       attr_reader :definition
       attr_reader :args
+      attr_reader :options
 
-      def initialize(process, definition, args)
+      def initialize(process, definition, *args)
         @process = process
         @definition = definition
         @args = args
+        @options = args.last.is_a?(Hash) ? args.last : {}
         @executor = Taskinator::Executor.new(@definition)
       end
 
+      def option?(key, &block)
+        yield if @options.key?(key) && @options[key]
+      end
+
       # defines a sub process of tasks which are executed sequentially
       def sequential(options={}, &block)
         raise ArgumentError, 'block' unless block_given?

data/lib/taskinator/definition.rb

@@ -3,10 +3,14 @@ module Taskinator
     class UndefinedProcessError < RuntimeError; end
 
     # defines a process
-    def define_process(&block)
+    def define_process(*arg_list, &block)
       define_singleton_method :_create_process_ do |*args|
+
+        # TODO: better validation of arguments
+        raise ArgumentError, "wrong number of arguments (#{args.length} for #{arg_list.length})" if args.length < arg_list.length
+
         process = Process.define_sequential_process_for(self)
-        Builder.new(process, self, args).instance_eval(&block)
+        Builder.new(process, self, *args).instance_eval(&block)
         process.save
         process
       end

data/lib/taskinator/version.rb

@@ -1,3 +1,3 @@
 module Taskinator
-  VERSION = "0.0.5"
+  VERSION = "0.0.7"
 end

data/spec/support/test_flow.rb

@@ -1,7 +1,7 @@
 module TestFlow
   extend Taskinator::Definition
 
-  define_process do
+  define_process :some_arg1, :some_arg2 do
     task :error_task, :continue_on_error => true
 
     task :the_task
@@ -54,7 +54,7 @@ module TestFlow
   module TestSubFlow
     extend Taskinator::Definition
 
-    define_process do
+    define_process :some_arg1, :some_arg2 do
       task :the_task
       task :the_task
       task :the_task

data/spec/taskinator/definition/builder_spec.rb

@@ -15,7 +15,7 @@ describe Taskinator::Definition::Builder do
     Class.new(Taskinator::Process).new(definition)
   }
 
-  let(:args) { [:arg1, :arg2] }
+  let(:args) { [:arg1, :arg2, {:option => 1, :another => false}] }
 
   let(:block) { SpecSupport::Block.new() }
 
@@ -24,12 +24,30 @@ describe Taskinator::Definition::Builder do
     Proc.new {|*args| the_block.call }
   }
 
-  subject { Taskinator::Definition::Builder.new(process, definition, args) }
+  subject { Taskinator::Definition::Builder.new(process, definition, *args) }
 
   it "assign attributes" do
     expect(subject.process).to eq(process)
     expect(subject.definition).to eq(definition)
     expect(subject.args).to eq(args)
+    expect(subject.options).to eq({:option => 1, :another => false})
+  end
+
+  describe "#option?" do
+    it "invokes supplied block for 'option' option" do
+      expect(block).to receive(:call)
+      subject.option?(:option, &define_block)
+    end
+
+    it "does not invoke supplied block for 'another' option" do
+      expect(block).to_not receive(:call)
+      subject.option?(:another, &define_block)
+    end
+
+    it "does not invoke supplied block for an unspecified option" do
+      expect(block).to_not receive(:call)
+      subject.option?(:unspecified, &define_block)
+    end
   end
 
   describe "#sequential" do
@@ -154,7 +172,8 @@ describe Taskinator::Definition::Builder do
       Module.new() do
         extend Taskinator::Definition
 
-        define_process {}
+        define_process :some_arg1, :some_arg2, :some_arg3 do
+        end
       end
     end
 
@@ -164,7 +183,7 @@ describe Taskinator::Definition::Builder do
     end
 
     it "creates a sub process task" do
-      sub_process = sub_definition.create_process(:argX, :argY)
+      sub_process = sub_definition.create_process(:argX, :argY, :argZ)
       allow(sub_definition).to receive(:create_process) { sub_process }
       expect(Taskinator::Task).to receive(:define_sub_process_task).with(process, sub_process, {})
       subject.sub_process(sub_definition)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: taskinator
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.7
 platform: ruby
 authors:
 - Chris Stefano
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-17 00:00:00.000000000 Z
+date: 2014-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis