taskinator 0.2.0 → 0.3.0

data/lib/taskinator/task.rb

@@ -1,7 +1,10 @@
 module Taskinator
   class Task
     include ::Comparable
-    include ::Workflow
+
+    include Workflow
+    include Persistence
+    include Instrumentation
 
     class << self
       def define_step_task(process, method, args, options={})
@@ -25,6 +28,8 @@ module Taskinator
     attr_reader :uuid
     attr_reader :options
     attr_reader :queue
+    attr_reader :created_at
+    attr_reader :updated_at
 
     # the next task in the sequence
     attr_accessor :next
@@ -36,6 +41,8 @@ module Taskinator
       @process = process
       @options = options
       @queue = options.delete(:queue)
+      @created_at = Time.now.utc
+      @updated_at = created_at
     end
 
     def accept(visitor)
@@ -44,6 +51,8 @@ module Taskinator
       visitor.visit_task_reference(:next)
       visitor.visit_args(:options)
       visitor.visit_attribute(:queue)
+      visitor.visit_attribute_time(:created_at)
+      visitor.visit_attribute_time(:updated_at)
     end
 
     def <=>(other)
@@ -54,73 +63,98 @@ module Taskinator
       "#<#{self.class.name}:#{uuid}>"
     end
 
-    workflow do
-      state :initial do
-        event :enqueue, :transitions_to => :enqueued
-        event :start, :transitions_to => :processing
-        event :complete, :transitions_to => :completed  # specific to a SubProcess which has no tasks
-        event :fail, :transitions_to => :failed
-      end
-
-      state :enqueued do
-        event :start, :transitions_to => :processing
-        event :complete, :transitions_to => :completed
-        event :fail, :transitions_to => :failed
-      end
+    def enqueue!
+      return if paused? || cancelled?
 
-      state :processing do
-        event :complete, :transitions_to => :completed
-        event :fail, :transitions_to => :failed
+      transition(:enqueued) do
+        instrument('taskinator.task.enqueued', enqueued_payload) do
+          enqueue
+        end
       end
+    end
 
-      state :completed
-      state :failed
+    def start!
+      return if paused? || cancelled?
+      self.incr_processing if incr_count?
 
-      on_transition do |from, to, event, *args|
-        Taskinator.logger.debug("TASK: #{self.class.name}:#{uuid} :: #{from} => #{to}")
+      transition(:processing) do
+        instrument('taskinator.task.processing', processing_payload) do
+          start
+        end
       end
-
     end
 
-    # include after defining the workflow
-    # since the load and persist state methods
-    # need to override the ones defined by workflow
-    include Persistence
+    #
+    # NOTE: a task can't be paused (it's too difficult to implement)
+    #       so rather, the parent process is paused, and the task checks it
+    #
 
-    def complete
-      Taskinator.instrumenter.instrument('taskinator.task.completed', instrumentation_payload) do
-        # notify the process that this task has completed
-        process.task_completed(self)
-        self.incr_completed
+    # helper method
+    def paused?
+      super || process.paused?
+    end
+
+    def complete!
+      transition(:completed) do
+        self.incr_completed if incr_count?
+        instrument('taskinator.task.completed', completed_payload) do
+          complete if respond_to?(:complete)
+          # notify the process that this task has completed
+          process.task_completed(self)
+        end
       end
     end
 
-    # callback for when the task has failed
-    def on_failed_entry(*args)
-      Taskinator.instrumenter.instrument('taskinator.task.failed', instrumentation_payload) do
-        self.incr_failed
-        # notify the process that this task has failed
-        process.task_failed(self, args.last)
+    def cancel!
+      transition(:cancelled) do
+        self.incr_cancelled if incr_count?
+        instrument('taskinator.task.cancelled', cancelled_payload) do
+          cancel if respond_to?(:cancel)
+        end
       end
     end
 
-    # callback for when the task has cancelled
-    def on_cancelled_entry(*args)
-      Taskinator.instrumenter.instrument('taskinator.task.cancelled', instrumentation_payload) do
-        self.incr_cancelled
+    def cancelled?
+      super || process.cancelled?
+    end
+
+    def fail!(error)
+      transition(:failed) do
+        self.incr_failed if incr_count?
+        instrument('taskinator.task.failed', failed_payload(error)) do
+          fail(error) if respond_to?(:fail)
+          # notify the process that this task has failed
+          process.task_failed(self, error)
+        end
       end
     end
 
-    # helper method, delegating to process
-    def paused?
-      process.paused?
+    def incr_count?
+      true
     end
 
-    # helper method, delegating to process
-    def cancelled?
-      process.cancelled?
+    #--------------------------------------------------
+    # subclasses must implement the following methods
+    #--------------------------------------------------
+
+    def enqueue
+      raise NotImplementedError
+    end
+
+    def start
+      raise NotImplementedError
     end
 
+    #--------------------------------------------------
+    # and optionally, provide methods:
+    #--------------------------------------------------
+    #
+    #  * cancel
+    #  * complete
+    #  * fail(error)
+    #
+    #--------------------------------------------------
+
     # a task which invokes the specified method on the definition
     # the args must be intrinsic types, since they are serialized to YAML
     class Step < Task
@@ -140,15 +174,11 @@ module Taskinator
       end
 
       def enqueue
-        Taskinator.instrumenter.instrument('taskinator.task.enqueued', instrumentation_payload) do
-          Taskinator.queue.enqueue_task(self)
-        end
+        Taskinator.queue.enqueue_task(self)
       end
 
       def start
-        Taskinator.instrumenter.instrument('taskinator.task.started', instrumentation_payload) do
-          executor.send(method, *args)
-        end
+        executor.send(method, *args)
         # ASSUMPTION: when the method returns, the task is considered to be complete
         complete!
 
@@ -171,10 +201,12 @@ module Taskinator
       end
 
       def inspect
-        %(#<#{self.class.name}:0x#{self.__id__.to_s(16)} uuid="#{uuid}", method=:#{method}, args=#{args}, state=:#{current_state.name}>)
+        %(#<#{self.class.name}:0x#{self.__id__.to_s(16)} uuid="#{uuid}", method=:#{method}, args=#{args}, current_state=:#{current_state}>)
       end
     end
 
+    #--------------------------------------------------
+
     # a task which invokes the specified background job
     # the args must be intrinsic types, since they are serialized to YAML
     class Job < Task
@@ -194,17 +226,22 @@ module Taskinator
       end
 
       def enqueue
-        Taskinator.instrumenter.instrument('taskinator.task.enqueued', instrumentation_payload) do
-          Taskinator.queue.enqueue_job(self)
-        end
+        Taskinator.queue.enqueue_task(self)
       end
 
-      # can't use the start! method, since a block is required
-      def perform
-        Taskinator.instrumenter.instrument('taskinator.task.started', instrumentation_payload) do
-          yield(job, args)
+      def start
+        # NNB: if other job types are required, may need to implement how they get invoked here!
+        # FIXME: possible implement using ActiveJob instead, so it doesn't matter how the worker is implemented
+
+        if job.instance_of?(Module)
+          # resque
+          job.perform(args)
+        else
+          # delayedjob and sidekiq
+          job.new.perform(args)
         end
-        # ASSUMPTION: when the method returns, the task is considered to be complete
+
+        # ASSUMPTION: when the job returns, the task is considered to be complete
         complete!
 
       rescue => e
@@ -222,14 +259,18 @@ module Taskinator
       end
 
       def inspect
-        %(#<#{self.class.name}:0x#{self.__id__.to_s(16)} uuid="#{uuid}", job=#{job}, args=#{args}, state=:#{current_state.name}>)
+        %(#<#{self.class.name}:0x#{self.__id__.to_s(16)} uuid="#{uuid}", job=#{job}, args=#{args}, current_state=:#{current_state}>)
       end
     end
 
+    #--------------------------------------------------
+
     # a task which delegates to another process
     class SubProcess < Task
       attr_reader :sub_process
 
+      # NOTE: also wraps sequential and concurrent processes
+
       def initialize(process, sub_process, options={})
         super(process, options)
         raise ArgumentError, 'sub_process' if sub_process.nil? || !sub_process.is_a?(Process)
@@ -239,15 +280,11 @@ module Taskinator
       end
 
       def enqueue
-        Taskinator.instrumenter.instrument('taskinator.task.enqueued', instrumentation_payload) do
-          sub_process.enqueue!
-        end
+        sub_process.enqueue!
       end
 
       def start
-        Taskinator.instrumenter.instrument('taskinator.task.started', instrumentation_payload) do
-          sub_process.start!
-        end
+        sub_process.start!
 
       rescue => e
         Taskinator.logger.error(e)
@@ -256,13 +293,19 @@ module Taskinator
         raise e
       end
 
+      def incr_count?
+        # subprocess tasks aren't included in the total count of tasks
+        # since they simply delegate to the tasks of the respective subprocess definition
+        false
+      end
+
       def accept(visitor)
         super
         visitor.visit_process(:sub_process)
       end
 
       def inspect
-        %(#<#{self.class.name}:0x#{self.__id__.to_s(16)} uuid="#{uuid}", sub_process=#{sub_process.inspect}, state=:#{current_state.name}>)
+        %(#<#{self.class.name}:0x#{self.__id__.to_s(16)} uuid="#{uuid}", sub_process=#{sub_process.inspect}, current_state=:#{current_state}>)
       end
     end
   end

data/lib/taskinator/version.rb

@@ -1,3 +1,3 @@
 module Taskinator
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/taskinator/visitor.rb

@@ -10,6 +10,12 @@ module Taskinator
       def visit_attribute(attribute)
       end
 
+      def visit_attribute_time(attribute)
+      end
+
+      def visit_attribute_enum(attribute, type)
+      end
+
       def visit_process_reference(attribute)
       end
 

data/lib/taskinator/workflow.rb

@@ -0,0 +1,36 @@
+module Taskinator
+  module Workflow
+
+    def current_state
+      @current_state ||= load_workflow_state
+    end
+
+    def current_state=(new_state)
+      @current_state = persist_workflow_state(new_state)
+    end
+
+    def transition(new_state)
+      self.current_state = new_state
+      yield if block_given?
+      current_state
+    end
+
+    %i(
+      initial
+      enqueued
+      processing
+      paused
+      resumed
+      completed
+      cancelled
+      failed
+    ).each do |state|
+
+      define_method :"#{state}?" do
+        @current_state == state
+      end
+
+    end
+
+  end
+end

data/lib/taskinator.rb

@@ -1,7 +1,6 @@
 require 'json'
 require 'yaml'
 require 'securerandom'
-require 'workflow'
 
 require 'taskinator/version'
 
@@ -11,15 +10,17 @@ require 'taskinator/logger'
 
 require 'taskinator/definition'
 
+require 'taskinator/workflow'
+
 require 'taskinator/visitor'
 require 'taskinator/persistence'
+require 'taskinator/instrumentation'
 
 require 'taskinator/task'
 require 'taskinator/tasks'
 require 'taskinator/process'
 
 require 'taskinator/task_worker'
-require 'taskinator/job_worker'
 require 'taskinator/create_process_worker'
 
 require 'taskinator/executor'

data/spec/examples/process_examples.rb

@@ -2,15 +2,12 @@ require 'spec_helper'
 
 shared_examples_for "a process" do |process_type|
 
-  # NOTE: definition and process must be defined by callee
+  # NOTE: definition and subject must be defined by callee
 
-  # let(:definition) {}
-  # let(:process) {}
-
-  it { expect(process.definition).to eq(definition)  }
-  it { expect(process.uuid).to_not be_nil }
-  it { expect(process.to_s).to match(/#{process.uuid}/) }
-  it { expect(process.options).to_not be_nil }
-  it { expect(process.tasks).to_not be_nil }
+  it { expect(subject.definition).to eq(definition)  }
+  it { expect(subject.uuid).to_not be_nil }
+  it { expect(subject.to_s).to match(/#{subject.uuid}/) }
+  it { expect(subject.options).to_not be_nil }
+  it { expect(subject.tasks).to_not be_nil }
 
 end

data/spec/examples/queue_adapter_examples.rb

@@ -16,7 +16,7 @@ shared_examples_for "a queue adapter" do |adapter_name, adapter_type|
     it "should enqueue a create process" do
       expect {
         subject.enqueue_create_process(double('definition', :name => 'definition', :queue => nil), 'xx-xx-xx-xx', :foo => :bar)
-      }.to_not raise_error
+      }.to_not raise_error(StandardError)
     end
   end
 
@@ -26,17 +26,7 @@ shared_examples_for "a queue adapter" do |adapter_name, adapter_type|
     it "should enqueue a task" do
       expect {
         subject.enqueue_task(double('task', :uuid => 'xx-xx-xx-xx', :queue => nil))
-      }.to_not raise_error
-    end
-  end
-
-  describe "#enqueue_job" do
-    it { expect(subject).to respond_to(:enqueue_job) }
-
-    it "should enqueue a job" do
-      expect {
-        subject.enqueue_job(double('job', :uuid => 'xx-xx-xx-xx', :job => job, :queue => nil))
-      }.to_not raise_error
+      }.to_not raise_error(StandardError)
     end
   end
 

data/spec/examples/task_examples.rb

@@ -2,14 +2,11 @@ require 'spec_helper'
 
 shared_examples_for "a task" do |task_type|
 
-  # NOTE: process and task must be defined by callee
+  # NOTE: process and subject must be defined by callee
 
-  # let(:process) {}
-  # let(:task) {}
-
-  it { expect(task.process).to eq(process)  }
-  it { expect(task.uuid).to_not be_nil }
-  it { expect(task.to_s).to match(/#{task.uuid}/) }
-  it { expect(task.options).to_not be_nil }
+  it { expect(subject.process).to eq(process)  }
+  it { expect(subject.uuid).to_not be_nil }
+  it { expect(subject.to_s).to match(/#{subject.uuid}/) }
+  it { expect(subject.options).to_not be_nil }
 
 end

data/spec/support/process_methods.rb

@@ -0,0 +1,25 @@
+module ProcessMethods
+  def enqueue
+  end
+
+  def cancel
+  end
+
+  def start
+  end
+
+  def pause
+  end
+
+  def resume
+  end
+
+  def complete
+  end
+
+  def fail(error)
+  end
+
+  def task_completed(task)
+  end
+end

data/spec/support/task_methods.rb

@@ -0,0 +1,13 @@
+module TaskMethods
+  def enqueue
+  end
+
+  def start
+  end
+
+  def complete
+  end
+
+  def fail(error)
+  end
+end

data/spec/support/test_flows.rb

@@ -2,9 +2,7 @@ module TestFlows
 
   module Worker
     def self.perform(*args)
-    end
-
-    def perform(*args)
+      # nop
     end
   end
 

data/spec/support/test_instrumenter.rb

@@ -0,0 +1,39 @@
+class TestInstrumenter
+
+  class << self
+
+    def subscribe(callback, filter=nil, &block)
+
+      # create test instrumenter instance
+      instrumenter = TestInstrumenter.new do |name, payload|
+        if filter
+          callback.call(name, payload) if name =~ filter
+        else
+          callback.call(name, payload)
+        end
+      end
+
+      # hook up this instrumenter in the context of the spec
+      # (assuming called from RSpec binding)
+      spec_binding = block.binding.eval('self')
+      spec_binding.instance_exec do
+        allow(Taskinator).to receive(:instrumenter).and_return(instrumenter)
+      end
+
+      yield
+    end
+
+  end
+
+  attr_reader :callback
+
+  def initialize(&block)
+    @callback = block
+  end
+
+  def instrument(event, payload={})
+    @callback.call(event, payload)
+    yield(payload) if block_given?
+  end
+
+end

data/spec/support/test_queue.rb

@@ -13,7 +13,6 @@ module Taskinator
 
       attr_reader :creates
       attr_reader :tasks
-      attr_reader :jobs
 
       def initialize
         clear
@@ -33,10 +32,6 @@ module Taskinator
         @tasks << task
       end
 
-      def enqueue_job(job)
-        @jobs << job
-      end
-
       def empty?
         @creates.empty? && @tasks.empty? && @jobs.empty?
       end
@@ -62,13 +57,6 @@ module Taskinator
         end
       end
 
-      def enqueue_job(job)
-        super
-        invoke do
-          Taskinator::JobWorker.new(job.uuid).perform
-        end
-      end
-
       def invoke(&block)
         block.call
       end

data/spec/taskinator/definition_spec.rb

@@ -136,7 +136,7 @@ describe Taskinator::Definition do
       # if an error is raised, then the context was incorrect
       expect {
         subject.create_process
-      }.to_not raise_error
+      }.to_not raise_error(StandardError)
     end
 
     context "is instrumented" do
@@ -148,8 +148,7 @@ describe Taskinator::Definition do
           expect(args.first).to eq('taskinator.process.created')
         end
 
-        # temporary subscription
-        ActiveSupport::Notifications.subscribed(instrumentation_block, /taskinator.process.created/) do
+        TestInstrumenter.subscribe(instrumentation_block, /taskinator.process.created/) do
           subject.create_process :foo
         end
       end
@@ -160,8 +159,7 @@ describe Taskinator::Definition do
           expect(args.first).to eq('taskinator.process.saved')
         end
 
-        # temporary subscription
-        ActiveSupport::Notifications.subscribed(instrumentation_block, /taskinator.process.saved/) do
+        TestInstrumenter.subscribe(instrumentation_block, /taskinator.process.saved/) do
           subject.create_process :foo
         end
       end