Merge pull request #4 from jobready/feature/AV-2123

[AV-2123] Add ability to finish workflow

Author: schlick

.travis.yml

@@ -1,5 +1,7 @@
 # Decision Tree
 
+[![Build status](https://badge.buildkite.com/ed9359ddd05b5fcf16c05eebd63e23d303b3028cd4daf2d32d.svg)](https://buildkite.com/jobready/decision-tree)
+
 Decision Tree is an easy way of defining rules/workflows that progress an
 object's state through a series of boolean decisions.
 
@@ -90,6 +92,73 @@ class Change < ActiveRecord::Base
 end
 ```
 
+##Finishing the Workflow
+When a workflow has been completed, and you don't want it to evaluate again, you can call `finish!` on the workflow.
+
+```ruby
+class TestWorkflow < DecisionTree::Workflow
+  def do_something
+  	...
+  end
+
+  start do
+  	do_something
+  end
+
+  decision :do_something do
+  	yes { finish! }
+  	no  { finish! }
+  end
+end
+```
+
+This will mark the workflow as finished in the state cache, and call `store_steps!` on the carrier, passing the list of `DecisionTree::Step` objects that were taken on the path to finishing the workflow. After it is finished, subsequent invocations of the workflow will no longer execute the workflow, but call `fetch_steps` on the state carrier.
+
+## Storing Steps
+Implementation of the storage of the steps is left to the application, and does not need to be implemented. DecisionTree will still work correctly without the step storage, but you will be unable to retrieve/display the steps when reloading the workflow after completion. If this is satisfactory, you can leave `store_steps!` and `fetch_steps` empty.
+
+If you do need to store the final steps, below is an example implementation:
+
+```ruby
+class Change < ActiveRecord::Base
+  has_many :workflow_steps, as: :workflowable
+
+  def store_steps!(steps)
+    workflow_steps.destroy_all
+
+    steps.each_with_index do |step, position|
+      new_step = WorkflowStep.from_decision_step(step, self, position)
+      new_step.save!
+    end
+  end
+
+  def fetch_steps
+    workflow_steps
+  end
+end
+
+class WorkflowStep < ActiveRecord::Base
+  belongs_to :workflowable, polymorphic: true
+  default_scope { order(position: :asc) }
+
+  delegate :display, to: :decision_step, allow_nil: true
+  def decision_step
+    @step ||= DecisionTree::Step.new(step_type, step_info)
+  end
+
+  def self.from_decision_step(decision_step, parent, position)
+    step_attrs = {
+      step_type: decision_step.step_type,
+      step_info: decision_step.step_info,
+      workflowable: parent,
+      position: position
+    }
+    self.new(step_attrs)
+  end
+end
+```
+
+
 ##Displaying the Workflow
 Human readable display of workflow steps can be achieved by using `DecisionTree::Step#display`.
 E.g.
@@ -123,7 +192,7 @@ Any idempotent calls (identified by a trailing `!`) are defined under `idempoten
 Any regular steps (with a yes/no outcome) are defined directly under `workflow_steps`, and contain values for both 'yes', and 'no'. Note that these keys should be defined as strings (explicitly wrapped in quotes), otherwise YAML helpfully converts these to booleans, which will not be matched when looking for a description.
 
 ### Implicit Display Values
-Semi-friendly display values are still returned if no translation has been defined.  
+Semi-friendly display values are still returned if no translation has been defined.
 For a regular step, the question will be rendered, followed by the answer.
 
 ```

README.md

@@ -16,4 +16,4 @@ def yes(&block)
   def no(&block)
     @no = block
   end
-end
+end

lib/decision_tree/options_grabber.rb

@@ -3,13 +3,13 @@ class DecisionTree::Proxy < BasicObject
     def initialize(proxied_object)
         @proxied_object = proxied_object
     end
-    
+
     def exit(&block)
         @proxied_object.instance_eval(&block)
         throw :exit
         false # This isn't chainable.
     end
-    
+
     def method_missing(name, *args, &block)
         if name.to_s =~ /!\Z/
             # Method names ending with a bang are assumed to be non-idempotent,
@@ -23,6 +23,5 @@ def method_missing(name, *args, &block)
             else
             return @proxied_object.send(name, *args, &block)
         end
-        
     end
 end

lib/decision_tree/proxy.rb

@@ -9,4 +9,13 @@ def start_workflow(&block)
   def state!(value)
     @state = value
   end
+
+  # Step storing/fetching
+  # Do nothing by default. Implement in application.
+  def store_steps!(steps)
+  end
+
+  # Do nothing by default. Implement in application.
+  def fetch_steps
+  end
 end

lib/decision_tree/store.rb

@@ -1,3 +1,3 @@
 module DecisionTree
-  VERSION = "0.0.2"
+  VERSION = "0.1.0"
 end

lib/decision_tree/version.rb

@@ -20,6 +20,32 @@ def initialize(store=nil)
     initialize_persistent_state
     @proxy = DecisionTree::Proxy.new(self)
 
+    if finished?
+      @steps = store.fetch_steps
+    else
+      execute_workflow
+    end
+  end
+
+  def logger
+    @logger ||= Logger.new(STDERR)
+  end
+
+  def finish!
+    @nonidempotent_calls << 'finish!'
+    @steps << DecisionTree::Step.new('Workflow Finished', '__finish_workflow')
+    store.store_steps!(@steps)
+  end
+
+  def finished?
+    @nonidempotent_calls.include?('finish!')
+  end
+
+  private
+
+  # Actually executes the workflow steps, by executing all the steps from
+  # either the start, or all previously reached entry points
+  def execute_workflow
     # We're using pessimistic locking here, so this will block until an
     # exclusive lock can be obtained on the change.
     store.start_workflow do
@@ -37,12 +63,6 @@ def initialize(store=nil)
     end
   end
 
-  def logger
-    @logger ||= Logger.new(STDERR)
-  end
-
-  private
-
   # We use a DecisionTree::Store to persist workflow across
   # instantiations of the workflow object, and guarantee idempotency. The
   # actual data is stored as a slug:

lib/decision_tree/workflow.rb

@@ -0,0 +1,17 @@
+#!/bin/bash
+set -e
+
+echo '--- setting ruby version'
+rbenv local 2.1.3
+
+echo '--- bundling'
+bundle install -j $(nproc) --without production --quiet
+
+echo '--- running specs'
+REVISION=https://github.com/$BUILDBOX_PROJECT_SLUG/commit/$BUILDBOX_COMMIT
+if bundle exec rake spec; then
+  echo "[Successful] $BUILDBOX_PROJECT_SLUG - Build - $BUILDBOX_BUILD_URL - Commit - $REVISION" | hipchat_room_message -t $HIPCHAT_TOKEN -r $HIPCHAT_ROOM -f "Buildbox" -c "green"
+else
+  echo "[Failed] Build $BUILDBOX_PROJECT_SLUG - Build - $BUILDBOX_BUILD_URL - Commit - $REVISION" | hipchat_room_message -t $HIPCHAT_TOKEN -r $HIPCHAT_ROOM -f "Buildbox" -c "red"
+  exit 1;
+fi

script/buildkite.sh

@@ -186,4 +186,116 @@ def decision_method
       expect(store.state).to match(/__start_workflow/)
     end
   end
+
+  describe '.initialize' do
+    before do
+      class TestWorkflow < DecisionTree::Workflow
+      end
+
+      allow_any_instance_of(TestWorkflow).to receive(:finished?) { finished }
+    end
+
+    subject { TestWorkflow.new(store) }
+
+    context 'when workflow not previously completed' do
+      let(:finished) { false }
+      specify 'executes the workflow' do
+        expect_any_instance_of(TestWorkflow).to receive(:execute_workflow)
+        subject
+      end
+    end
+
+    context 'when workflow previously completed' do
+      let(:finished) { true }
+
+      specify 'does not execute the workflow' do
+        expect_any_instance_of(TestWorkflow).to_not receive(:execute_workflow)
+        subject
+      end
+
+      specify 'fetches previously executed steps from the store' do
+        expect(store).to receive(:fetch_steps)
+        subject
+      end
+    end
+  end
+
+  describe 'finish!' do
+    subject { workflow.instance_variable_get(:@nonidempotent_calls) }
+    let(:finish!) { workflow.finish! }
+
+    before do
+      class TestWorkflow < DecisionTree::Workflow
+        start {}
+      end
+    end
+
+    let(:workflow) { TestWorkflow.new(store) }
+
+    specify 'records the finish call' do
+      finish!
+      expect(subject).to include('finish!')
+    end
+  end
+
+  describe 'calling finish!' do
+    let(:workflow) { TestWorkflow.new(store) }
+
+    context 'from a start block' do
+
+      before do
+        class TestWorkflow < DecisionTree::Workflow
+          start { finish! }
+        end
+      end
+
+      specify 'calls finish! on the workflow' do
+        expect_any_instance_of(TestWorkflow).to receive(:finish!)
+        workflow
+      end
+    end
+
+    context 'from a decision block' do
+      before do
+        class TestWorkflow < DecisionTree::Workflow
+          def decision_method
+            true
+          end
+
+          start { decision_method }
+
+          decision :decision_method do
+            yes { finish! }
+            no  {  }
+          end
+        end
+      end
+
+      specify 'calls finish! on the workflow' do
+        expect_any_instance_of(TestWorkflow).to receive(:finish!)
+        workflow
+      end
+    end
+  end
+
+  describe '.finished?' do
+    subject { workflow.finished? }
+
+    before do
+      class TestWorkflow < DecisionTree::Workflow
+        start {}
+      end
+    end
+
+    let(:workflow) { TestWorkflow.new(store) }
+
+    context 'when workflow has been finished' do
+      before { workflow.finish! }
+      specify { expect(subject).to be_truthy }
+    end
+
+    context 'when workflow has not been finished' do
+      specify { expect(subject).to be_falsey }
+    end
+  end
 end

spec/decision_tree/workflow_spec.rb

@@ -22,4 +22,6 @@
   config.filter_run :focus
   config.filter_run_excluding perf: true
   config.order = 'random'
+  config.color = true
+  config.formatter = :documentation
 end