dynflow 0.3.0 → 0.4.0

data/lib/dynflow.rb

@@ -7,6 +7,7 @@ require 'active_support/core_ext/hash/indifferent_access'
 # TODO validate in/output, also validate unknown keys
 # TODO performance testing, how many actions will it handle?
 # TODO profiling, find bottlenecks
+# FIND change ids to uuid, uuid-<action_id>, uuid-<action_id-(plan, run, finalize)
 module Dynflow
 
   class Error < StandardError
@@ -20,9 +21,9 @@ module Dynflow
   require 'dynflow/transaction_adapters'
   require 'dynflow/persistence'
   require 'dynflow/middleware'
-  require 'dynflow/action'
   require 'dynflow/flows'
   require 'dynflow/execution_plan'
+  require 'dynflow/action'
   require 'dynflow/listeners'
   require 'dynflow/executors'
   require 'dynflow/logger_adapters'

data/lib/dynflow/action.rb

@@ -1,64 +1,40 @@
 require 'active_support/inflector'
 
 module Dynflow
-
-  # TODO unify phases into one class, check what can be called in what phase at runtime
   class Action < Serializable
+
+    OutputReference = ExecutionPlan::OutputReference
+
     include Algebrick::TypeCheck
     include Algebrick::Matching
 
     require 'dynflow/action/format'
     extend Format
 
-    extend Middleware::Action
-
     require 'dynflow/action/progress'
     include Progress
 
     require 'dynflow/action/suspended'
     require 'dynflow/action/missing'
 
-    require 'dynflow/action/plan_phase'
-    require 'dynflow/action/flow_phase'
-    require 'dynflow/action/run_phase'
-    require 'dynflow/action/finalize_phase'
-
-    require 'dynflow/action/presenter'
     require 'dynflow/action/polling'
     require 'dynflow/action/cancellable_polling'
 
-    # Override this to extend the phase classes
-    def self.phase_modules
-      { plan_phase:     [PlanPhase],
-        run_phase:      [RunPhase],
-        finalize_phase: [FinalizePhase],
-        presenter:      [Presenter] }.freeze
-    end
-
-    phase_modules.each do |phase_name, _|
-      define_singleton_method phase_name do
-        instance_variable_get :"@#{phase_name}" or
-            instance_variable_set :"@#{phase_name}", __send__("create_#{phase_name}")
-      end
-
-      define_singleton_method "create_#{phase_name}" do
-        generate_phase(*phase_modules[phase_name])
-      end
+    def self.all_children
+      children.inject(children) { |children, child| children + child.all_children }
     end
 
-    def self.generate_phase(*modules)
-      Class.new(self) { modules.each { |m| include m } }
+    def self.inherited(child)
+      children << child
+      super child
     end
 
-    def self.phase?
-      [PlanPhase, RunPhase, FinalizePhase, Presenter].any? { |phase| self < phase }
+    def self.children
+      @children ||= []
     end
 
-    def self.all_children
-      #noinspection RubyArgCount
-      children.
-          inject(children) { |children, child| children + child.all_children }.
-          select { |ch| !ch.phase? }
+    def self.middleware
+      @middleware ||= Middleware::Register.new
     end
 
     # FIND define subscriptions in world independent on action's classes,
@@ -68,108 +44,190 @@ module Dynflow
       nil
     end
 
-    def self.attr_indifferent_access_hash(*names)
-      attr_reader(*names)
-      names.each do |name|
-        define_method("#{name}=") { |v| indifferent_access_hash_variable_set name, v }
+    ERROR   = Object.new
+    SUSPEND = Object.new
+    Phase   = Algebrick.type do
+      Executable = type do
+        variants Plan     = atom,
+                 Run      = atom,
+                 Finalize = atom
       end
+      variants Executable, Present = atom
     end
 
-    def indifferent_access_hash_variable_set(name, value)
-      Type! value, Hash
-      instance_variable_set :"@#{name}", value.with_indifferent_access
+    module Executable
+      def execute_method_name
+        match self,
+              (on Plan, :execute_plan),
+              (on Run, :execute_run),
+              (on Finalize, :execute_finalize)
+      end
     end
 
-    def self.from_hash(hash, phase, *args)
-      check_class_key_present hash
-      raise ArgumentError, "unknown phase '#{phase}'" unless [:plan_phase, :run_phase, :finalize_phase].include? phase
-      Action.constantize(hash[:class]).send(phase).new_from_hash(hash, *args)
+    def self.constantize(action_name)
+      super action_name
+    rescue NameError
+      Action::Missing.generate(action_name)
     end
 
-    attr_reader :world, :execution_plan_id, :id, :plan_step_id, :run_step_id, :finalize_step_id
+    attr_reader :world, :phase, :execution_plan_id, :id, :input,
+                :plan_step_id, :run_step_id, :finalize_step_id
 
     def initialize(attributes, world)
-      raise "It's not expected to initialize this class directly, use phases." unless self.class.phase?
-
       Type! attributes, Hash
 
+      @phase             = Type! attributes.fetch(:phase), Phase
       @world             = Type! world, World
-      @step              = Type! attributes[:step], ExecutionPlan::Steps::Abstract
-      @execution_plan_id = attributes[:execution_plan_id] || raise(ArgumentError, 'missing execution_plan_id')
-      @id                = attributes[:id] || raise(ArgumentError, 'missing id')
-      @plan_step_id      = attributes[:plan_step_id]
-      @run_step_id       = attributes[:run_step_id]
-      @finalize_step_id  = attributes[:finalize_step_id]
-    end
-
-    def self.action_class
-      # superclass because we run this from the phases of action class
-      if phase?
-        superclass
+      @step              = Type!(attributes.fetch(:step),
+                                 ExecutionPlan::Steps::Abstract) if phase? Executable
+      @execution_plan_id = Type! attributes.fetch(:execution_plan_id), String
+      @id                = Type! attributes.fetch(:id), Integer
+      @plan_step_id      = Type! attributes.fetch(:plan_step_id), Integer
+      @run_step_id       = Type! attributes.fetch(:run_step_id), Integer, NilClass
+      @finalize_step_id  = Type! attributes.fetch(:finalize_step_id), Integer, NilClass
+
+      @execution_plan    = Type!(attributes.fetch(:execution_plan),
+                                 ExecutionPlan) if phase? Plan, Present
+      @trigger           = Type! attributes.fetch(:trigger), Action, NilClass if phase? Plan
+
+      getter =-> key, required do
+        required ? attributes.fetch(key) : attributes.fetch(key, {})
+      end
+
+      @input  = OutputReference.deserialize getter.(:input, phase?(Run, Finalize, Present))
+      @output = OutputReference.deserialize getter.(:output, false) if phase? Run, Finalize, Present
+    end
+
+    def phase?(*phases)
+      Match? phase, *phases
+    end
+
+    def phase!(*phases)
+      phase?(*phases) or
+          raise TypeError, "Wrong phase #{phase}, required #{phases}"
+    end
+
+    def input=(hash)
+      Type! hash, Hash
+      phase! Plan
+      @input = hash.with_indifferent_access
+    end
+
+    def output=(hash)
+      Type! hash, Hash
+      phase! Run
+      @output = hash.with_indifferent_access
+    end
+
+    def output
+      if phase? Plan
+        @output_reference or
+            raise 'plan_self has to be invoked before being able to reference the output'
       else
-        self
+        @output
       end
     end
 
-    def self.constantize(action_name)
-      action_name.constantize
-    rescue NameError
-      Action::Missing.generate(action_name)
+    def trigger
+      phase! Plan
+      @trigger
+    end
+
+    def execution_plan
+      phase! Plan, Present
+      @execution_plan
     end
 
     def action_logger
+      phase! Executable
       world.action_logger
     end
 
-    def action_class
-      self.class.action_class
+    def plan_step
+      phase! Present
+      execution_plan.steps.fetch(plan_step_id)
     end
 
-    def to_hash
-      recursive_to_hash class:             action_class.name,
-                        execution_plan_id: execution_plan_id,
-                        id:                id,
-                        plan_step_id:      plan_step_id,
-                        run_step_id:       run_step_id,
-                        finalize_step_id:  finalize_step_id
+    def run_step
+      phase! Present
+      execution_plan.steps.fetch(run_step_id) if run_step_id
     end
 
-    # @api private
-    # @return [Array<Fixnum>] - ids of steps referenced from action
-    def required_step_ids(value = self.input)
-      ret = case value
-            when Hash
-              value.values.map { |val| required_step_ids(val) }
-            when Array
-              value.map { |val| required_step_ids(val) }
-            when ExecutionPlan::OutputReference
-              value.step_id
-            else
-              # no reference hidden in this arg
-            end
-      return Array(ret).flatten.compact
+    def finalize_step
+      phase! Present
+      execution_plan.steps.fetch(finalize_step_id) if finalize_step_id
+    end
+
+    def steps
+      [plan_step, run_step, finalize_step_id]
+    end
+
+    def to_hash
+      recursive_to_hash(
+          { class:             self.class.name,
+            execution_plan_id: execution_plan_id,
+            id:                id,
+            plan_step_id:      plan_step_id,
+            run_step_id:       run_step_id,
+            finalize_step_id:  finalize_step_id,
+            input:             input },
+          if phase? Run, Finalize, Present
+            { output: output }
+          end)
     end
 
     def state
+      phase! Executable
       @step.state
     end
 
     def error
+      phase! Executable
       @step.error
     end
 
+    def execute(*args)
+      phase! Executable
+      self.send phase.execute_method_name, *args
+    end
+
+    # @api private
+    # @return [Array<Fixnum>] - ids of steps referenced from action
+    def required_step_ids(input = self.input)
+      results   = []
+      recursion =-> value do
+        case value
+        when Hash
+          value.values.each { |v| recursion.(v) }
+        when Array
+          value.each { |v| recursion.(v) }
+        when ExecutionPlan::OutputReference
+          results << value.step_id
+        else
+          # no reference hidden in this arg
+        end
+        results
+      end
+      recursion.(input)
+    end
+
     protected
 
     def state=(state)
+      phase! Executable
       @world.logger.debug "step #{execution_plan_id}:#{@step.id} #{self.state} >> #{state}"
       @step.state = state
     end
 
     def save_state
+      phase! Executable
       @step.save
     end
 
-    # @override
+    # @override to implement the action's *Plan phase* behaviour.
+    # By default it plans itself and expects input-hash.
+    # Use #plan_self and #plan_action methods to plan actions.
+    # It can use DB in this phase.
     def plan(*args)
       if trigger
         # if the action is triggered by subscription, by default use the
@@ -184,16 +242,71 @@ module Dynflow
       self
     end
 
+    # Add this method to implement the action's *Run phase* behaviour.
+    # It should not use DB in this phase.
+    def run(event = nil)
+      # just a rdoc placeholder
+    end
+    remove_method :run
+
+    # Add this method to implement the action's *Finalize phase* behaviour.
+    # It can use DB in this phase.
+    def finalize
+      # just a rdoc placeholder
+    end
+    remove_method :finalize
+
     def self.new_from_hash(hash, world)
       new(hash, world)
     end
 
     private
 
-    ERROR = Object.new
+    # DSL for plan phase
+
+    def concurrence(&block)
+      phase! Plan
+      @execution_plan.switch_flow(Flows::Concurrence.new([]), &block)
+    end
+
+    def sequence(&block)
+      phase! Plan
+      @execution_plan.switch_flow(Flows::Sequence.new([]), &block)
+    end
+
+    def plan_self(input)
+      phase! Plan
+      self.input = input
+      if self.respond_to?(:run)
+        run_step          = @execution_plan.add_run_step(self)
+        @run_step_id      = run_step.id
+        @output_reference = OutputReference.new(@execution_plan.id, run_step.id, id)
+      end
+
+      if self.respond_to?(:finalize)
+        finalize_step     = @execution_plan.add_finalize_step(self)
+        @finalize_step_id = finalize_step.id
+      end
+
+      return self # to stay consistent with plan_action
+    end
+
+    def plan_action(action_class, *args)
+      phase! Plan
+      @execution_plan.add_plan_step(action_class, self).execute(@execution_plan, nil, *args)
+    end
+
+    # DSL for run phase
+
+    def suspend(&block)
+      phase! Run
+      block.call Action::Suspended.new self if block
+      throw SUSPEND, SUSPEND
+    end
 
     # DSL to terminate action execution and set it to error
     def error!(error)
+      phase! Executable
       set_error(error)
       throw ERROR
     end
@@ -219,22 +332,79 @@ module Dynflow
     end
 
     def set_error(error)
+      phase! Executable
       Type! error, Exception, String
       action_logger.error error
       self.state  = :error
-      @step.error = if error.is_a?(String)
-                      ExecutionPlan::Steps::Error.new(nil, error, nil)
-                    else
-                      ExecutionPlan::Steps::Error.new(error.class.name, error.message, error.backtrace)
-                    end
+      @step.error = ExecutionPlan::Steps::Error.new(error)
     end
 
-    def self.inherited(child)
-      children << child
+    def execute_plan(*args)
+      phase! Plan
+      self.state = :running
+      save_state
+      with_error_handling do
+        concurrence do
+          world.middleware.execute(:plan, self, *args) do |*new_args|
+            plan(*new_args)
+          end
+        end
+
+        subscribed_actions = world.subscribed_actions(self.class)
+        if subscribed_actions.any?
+          # we encapsulate the flow for this action into a concurrence and
+          # add the subscribed flows to it as well.
+          trigger_flow = @execution_plan.current_run_flow.sub_flows.pop
+          @execution_plan.switch_flow(Flows::Concurrence.new([trigger_flow].compact)) do
+            subscribed_actions.each do |action_class|
+              new_plan_step = @execution_plan.add_plan_step(action_class, self)
+              new_plan_step.execute(@execution_plan, self, *args)
+            end
+          end
+        end
+      end
     end
 
-    def self.children
-      @children ||= []
+    def execute_run(event)
+      phase! Run
+      @world.logger.debug "step #{execution_plan_id}:#{@step.id} got event #{event}" if event
+      @input = OutputReference.dereference @input, world.persistence
+
+      case
+      when state == :running
+        raise NotImplementedError, 'recovery after restart is not implemented'
+
+      when [:pending, :error, :suspended].include?(state)
+        if [:pending, :error].include?(state) && event
+          raise 'event can be processed only when in suspended state'
+        end
+
+        self.state = :running
+        save_state
+        with_error_handling do
+          result = catch(SUSPEND) do
+            world.middleware.execute(:run, self, *[event].compact) { |*args| run(*args) }
+          end
+          if result == SUSPEND
+            self.state = :suspended
+          end
+        end
+
+      else
+        raise "wrong state #{state} when event:#{event}"
+      end
+    end
+
+    def execute_finalize
+      phase! Finalize
+      @input     = OutputReference.dereference @input, world.persistence
+      self.state = :running
+      save_state
+      with_error_handling do
+        world.middleware.execute(:finalize, self) do
+          finalize
+        end
+      end
     end
   end
 end