dynflow 0.8.35 → 0.8.36

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 290e1bf999cae6f5ced255f29c2b62bc5d1fb53d75a0184ca514afbd3deb9c04
-  data.tar.gz: 7e4bdad4c493342902070fa5f694569ff3cd1906c648bc403b47dccb03654646
+  metadata.gz: 9d355c9b625deb22695548050c4d72ee3c43ce3a14e43488507173554c9c04d0
+  data.tar.gz: 63693d7793f8e1f12ff03d4b0b9ea3e9bbb1114f701cd92f470dd268f8dac732
 SHA512:
-  metadata.gz: 50250e41adda66f5f8069378d916fa1a58771076420806aa9185bbd2467a36acb038aeda64f3d7757c43801796c2507e23e062307bb40e9fd5ddaed18c0a5236
-  data.tar.gz: 0aeae17937111257652845446f8ea5726d735651a57dd3d915f74e943a785566eb9340b5e1356e45bac86c2fe15033dff2e6b8fab50ae17aa05abe2bc32e4749
+  metadata.gz: 6760a74b0ec0f87e9ffb01a87f322b4151be4b1ddb578aa4ce56956f363a0a75db7bbcfbdf1eecc370dedc0b5ea1e182e4d85b86c22b411947b728ac531ed69f
+  data.tar.gz: 29a76f2faa3d93a24269c1cc233ca5f4cde5865e5c454dfb945b2605a184fc29203b7bb4f5a99100695557332bf6a0690f999ed4026dfc9570877f6085d8b374

data/.travis.yml

@@ -3,22 +3,23 @@ language:
   - ruby
 
 rvm:
-  - "2.0.0"
-  - "2.1.5"
-  - "2.2.0"
+  - "2.2.2"
   - "2.3.1"
   - "2.4.0"
+  - "2.5.0"
 
 env:
   global:
-    - "TESTOPTS=--verbose"
-  matrix:
-    - "DB=mysql DB_CONN_STRING=mysql2://root@localhost/travis_ci_test CONCURRENT_RUBY_EXT=true"
-    - "DB=postgresql DB_CONN_STRING=postgres://postgres@localhost/travis_ci_test CONCURRENT_RUBY_EXT=true"
-    - "DB=sqlite3 CONCURRENT_RUBY_EXT=true"
-    - "DB=mysql DB_CONN_STRING=mysql2://root@localhost/travis_ci_test CONCURRENT_RUBY_EXT=false"
-    - "DB=postgresql DB_CONN_STRING=postgres://postgres@localhost/travis_ci_test CONCURRENT_RUBY_EXT=false"
-    - "DB=sqlite3 CONCURRENT_RUBY_EXT=false"
+    - "TESTOPTS=--verbose DB=postgresql DB_CONN_STRING=postgres://postgres@localhost/travis_ci_test"
+
+matrix:
+  include:
+    - rvm: "2.4.0"
+      env: "DB=mysql DB_CONN_STRING=mysql2://root@localhost/travis_ci_test"
+    - rvm: "2.4.0"
+      env: "DB=sqlite3 DB_CONN_STRING=sqlite:/"
+    - rvm: "2.4.0"
+      env: "CONCURRENT_RUBY_EXT=true"
 
 install:
   - test/prepare_travis_env.sh

data/doc/pages/Gemfile

@@ -5,3 +5,5 @@ gem 'jekyll'
 gem 'pry'
 gem 'ruby-nuggets' # require by tags plugin
 gem 'therubyracer'
+gem 'redcarpet'
+gem 'pygments.rb'

data/doc/pages/README.md

@@ -0,0 +1,48 @@
+# Building dynflow.github.io
+
+1. Clone the `dynflow.github.io` to the public directory
+
+```
+git clone github.com:dynflow/dynflow.github.io public --origin upstream
+```
+
+2. Add your fork
+
+```
+cd public
+git remote add origin github.com:$MYUSERNAME/dynflow.github.io
+cd ..
+```
+
+2. Install the dependencies
+
+```
+bundle install
+```
+
+3. Make sure the public repository is in sync with upstream
+
+```
+cd public
+git fetch upstream master
+git reset --hard upstream/master
+git clean -f
+cd ..
+```
+
+4. Build new version of the pages
+
+```
+bundle exec jekyll build
+```
+
+5. Commit and push the updated version
+
+```
+cd public
+git add -A
+git commit -m Update
+git push origin master
+```
+
+6. Send us a PR

data/doc/pages/_config.yml

@@ -7,7 +7,7 @@ highlighter: pygments
 
 source:       ./source
 destination:  ./public
-plugins:      ./plugins
+plugins_dir:  ./plugins
 include:
 - .nojekyll
 

data/doc/pages/plugins/plantuml.rb

@@ -24,7 +24,7 @@ module Jekyll
       folder = "/images/plantuml/"
       create_tmp_folder(tmproot, folder)
 
-      code = @nodelist.join + background_color
+      code = nodelist.join + background_color
       filename = Digest::MD5.hexdigest(code) + ".png"
       filepath = tmproot + folder + filename
       if !File.exist?(filepath)

data/doc/pages/source/documentation/index.md

@@ -69,6 +69,8 @@ Dynflow has been developed to be able to support orchestration of services in th
     talk to each other, which is helpful for production and
     high-availability setups,
     having multiple worlds on different hosts handle the execution of the execution plans.
+    If you're still confused and come from RoR world, think about it as similar thing 
+    that is Rails object for Ruby on Rails framework.
 
 ##  Examples
 
@@ -984,7 +986,72 @@ to the chain of middleware execution.
 ### Sub-plans
 
 -   *when to use?*
--   *how to use?*
+
+To use sub-plans, you must include the `Dynflow::Action::WithSubPlans` module
+and override the `create_sub_plans` method. Inside the `create_sub_plans`
+method, you use the `trigger` method to create sub-tasks that will be executed
+in no particular order during the run phase. The parent task will wait for the
+sub-tasks to finish without blocking a thread in a pool while waiting.
+
+```rb
+class MyAction < Actions::EntryAction
+  include Dynflow::Action::WithSubPlans
+
+  ...
+
+  def create_sub_plans
+    [
+      trigger(Actions::OtherAction, action_param1, action_opts),
+      trigger(Actions::AnotherAction)
+    ]
+  end
+end
+```
+
+### Execution plan hooks
+
+Dynflow allows actions to hook into the lifecycle of their execution plans. To
+use the hooks, the user has to define a method on the action and register it as
+a hook. Currently there are hook events for every execution plan's state which
+are executed when the execution plan transitions into the state. Additionally
+there are two more hook events, `failure` and `success` which are run when the
+execution plan transitions into the `stopped` state with `error` or `success`
+result.
+
+Methods can be registered using `execution_plan_hooks.use` call, providing the
+method name as `Symbol` and optionally a `:on => HOOK_EVENT` parameter, where
+`HOOK_EVENT` can be one of the hook events or an array of them. In case the
+optional parameter is not provided, the method is executed on every state
+change. Similarly, for example inherited, hooks can be disabled by calling
+`execution_plan_hooks.do_not_use`, taking the same arguments. Hooks defined on
+an action are inherited when the action is sub-classed.
+
+The hooks are executed for every action in the execution plan and the order of
+execution is not guaranteed.
+
+```rb
+class MyAction < Actions::EntryAction
+  # Sets up a hook to call #state_change method when the execution plan changes
+  #   its state
+  execution_plan_hooks.use :state_change
+
+  # Sets up a hook to call #success_notification method when the execution plan
+  #   finishes successfully,
+  execution_plan_hooks.use :success_notification, :on => :success
+
+  # Disables running #state_change method when the execution plan starts or
+  #   finishes planning
+  execution_plan_hooks.do_not_use :state_change, :on => [:planning, :planned]
+
+  def state_change(_execution_plan)
+    # Do something on every state change
+  end
+
+  def success_notification(_execution_plan)
+    # Display a notification
+  end
+end
+```
 
 ## How it works TODO
 
@@ -1319,6 +1386,34 @@ executor is actively working on what execution plan: the executor is
 not allowed to start executing the unless it has successfully acquired
 a lock for it.
 
+### Singleton Actions
+Dynflow has a special module for actions of which there should be only
+one instance active at a time. This module provides a number of methods
+for managing the action's locks as well as a middleware for automatic
+locking.
+
+It works in the following way. The middleware tries to acquire the
+lock for this action, which is owned by the execution plan. If another
+action already holds the lock, it fill fail and the execution plan
+will transition to stopped-error state. Having obtained the lock,
+the action goes through the planning as usually. In run phase, the
+middleware checks if the execution plan still owns the lock for the action.
+If the execution plan holds the lock or there is no lock at all and
+the action manages to acquire it again, the execution proceeds. If the
+lock is held by another execution plan, the current one fails. Unlocking
+can be either done manually from within the action or can be left to the
+execution plan. The execution plan unlocks all locks it holds whenever it
+transitions to paused or stopped state.
+
+All that is needed to make an action a singleton one is including the module
+into it.
+
+```ruby
+class ExampleSingletonAction < ::Dynflow::Action
+  include ::Dynflow::Action::Singleton
+end
+```
+
 ### Thread-pools TODO
 
 -   *how it works now*

data/lib/dynflow/action.rb

@@ -34,6 +34,7 @@ module Dynflow
 
     def self.inherited(child)
       children[child.name] = child
+      child.inherit_execution_plan_hooks(execution_plan_hooks.dup)
       super child
     end
 
@@ -45,6 +46,14 @@ module Dynflow
       @middleware ||= Middleware::Register.new
     end
 
+    def self.execution_plan_hooks
+      @execution_plan_hooks ||= ExecutionPlan::Hooks::Register.new
+    end
+
+    def self.inherit_execution_plan_hooks(hooks)
+      @execution_plan_hooks = hooks
+    end
+
     # FIND define subscriptions in world independent on action's classes,
     #   limited only by in/output formats
     # @return [nil, Class] a child of Action
@@ -364,6 +373,10 @@ module Dynflow
     end
 
     def self.new_from_hash(hash, world)
+      hash.delete(:output) if hash[:output].nil?
+      unless hash[:execution_plan_uuid].nil?
+        hash[:execution_plan_id] = hash[:execution_plan_uuid]
+      end
       new(hash, world)
     end
 

data/lib/dynflow/delayed_plan.rb

@@ -38,23 +38,31 @@ module Dynflow
 
     def cancel
       error("Delayed task cancelled", "Delayed task cancelled")
-      @world.persistence.delete_delayed_plans(:execution_plan_uuid => execution_plan.id)
+      @world.persistence.delete_delayed_plans(:execution_plan_uuid => @execution_plan_uuid)
       return true
     end
 
     def execute(future = Concurrent.future)
-      @world.execute(execution_plan.id, future)
-      ::Dynflow::World::Triggered[execution_plan.id, future]
+      @world.execute(@execution_plan_uuid, future)
+      ::Dynflow::World::Triggered[@execution_plan_uuid, future]
     end
 
     def to_hash
       recursive_to_hash :execution_plan_uuid => @execution_plan_uuid,
-                        :start_at            => time_to_str(@start_at),
-                        :start_before        => time_to_str(@start_before),
+                        :start_at            => @start_at,
+                        :start_before        => @start_before,
                         :serialized_args     => @args_serializer.serialized_args,
                         :args_serializer     => @args_serializer.class.name
     end
 
+    # Retrieves arguments from the serializer
+    #
+    # @return [Array] array of the original arguments
+    def args
+      @args_serializer.perform_deserialization! if @args_serializer.args.nil?
+      @args_serializer.args
+    end
+
     # @api private
     def self.new_from_hash(world, hash, *args)
       serializer = Utils.constantize(hash[:args_serializer]).new(nil, hash[:serialized_args])

data/lib/dynflow/execution_plan.rb

@@ -51,6 +51,8 @@ module Dynflow
       @states ||= [:pending, :scheduled, :planning, :planned, :running, :paused, :stopped]
     end
 
+    require 'dynflow/execution_plan/hooks'
+
     def self.results
       @results ||= [:pending, :success, :warning, :error]
     end
@@ -109,6 +111,7 @@ module Dynflow
     end
 
     def update_state(state)
+      hooks_to_run = [state]
       original = self.state
       case self.state = state
       when :planning
@@ -117,6 +120,7 @@ module Dynflow
         @ended_at       = Time.now
         @real_time      = @ended_at - @started_at unless @started_at.nil?
         @execution_time = compute_execution_time
+        hooks_to_run << (error? ? :failure : :success)
         unlock_all_singleton_locks!
       when :paused
         unlock_all_singleton_locks!
@@ -126,6 +130,20 @@ module Dynflow
       logger.debug format('%13s %s    %9s >> %9s',
                           'ExecutionPlan', id, original, state)
       self.save
+      hooks_to_run.each { |kind| run_hooks kind }
+    end
+
+    def run_hooks(state)
+      records = persistence.load_actions_attributes(@id, [:id, :class]).select do |action|
+        Utils.constantize(action[:class])
+             .execution_plan_hooks
+             .on(state).any?
+      end
+      action_ids = records.compact.map { |record| record[:id] }
+      return if action_ids.empty?
+      persistence.load_actions(self, action_ids).each do |action|
+        action.class.execution_plan_hooks.run(self, action, state)
+      end
     end
 
     def result

data/lib/dynflow/execution_plan/hooks.rb

@@ -0,0 +1,91 @@
+module Dynflow
+  class ExecutionPlan
+    module Hooks
+
+      HOOK_KINDS = (ExecutionPlan.states + [:success, :failure]).freeze
+
+      # A register holding information about hook classes and events
+      # which should trigger the hooks.
+      #
+      # @attr_reader hooks [Hash<Class, Set<Symbol>>] a hash mapping hook classes to events which should trigger the hooks
+      class Register
+        attr_reader :hooks
+
+        def initialize(hooks = {})
+          @hooks = hooks
+        end
+
+        # Sets a hook to be run on certain events
+        #
+        # @param class_name [Class] class of the hook to be run
+        # @param on [Symbol, Array<Symbol>] when should the hook be run, one of {HOOK_KINDS}
+        # @return [void]
+        def use(class_name, on: HOOK_KINDS)
+          on = Array[on] unless on.kind_of?(Array)
+          validate_kinds!(on)
+          if hooks[class_name]
+            hooks[class_name] += on
+          else
+            hooks[class_name] = on
+          end
+        end
+
+        # Disables a hook from being run on certain events
+        #
+        # @param class_name [Class] class of the hook to disable
+        # @param on [Symbol, Array<Symbol>] when should the hook be disabled, one of {HOOK_KINDS}
+        # @return [void]
+        def do_not_use(class_name, on: HOOK_KINDS)
+          on = Array[on] unless on.kind_of?(Array)
+          validate_kinds!(on)
+          if hooks[class_name]
+            hooks[class_name] -= on
+            hooks.delete(class_name) if hooks[class_name].empty?
+          end
+        end
+
+        # Performs a deep clone of the hooks register
+        #
+        # @return [Register] new deeply cloned register
+        def dup
+          new_hooks = hooks.reduce({}) do |acc, (key, value)|
+            acc.update(key => value.dup)
+          end
+          self.class.new(new_hooks)
+        end
+
+        # Runs the registered hooks
+        #
+        # @param execution_plan [ExecutionPlan] the execution plan which triggered the hooks
+        # @param action [Action] the action which triggered the hooks
+        # @param kind [Symbol] the kind of hooks to run, one of {HOOK_KINDS}
+        def run(execution_plan, action, kind)
+          on(kind).each do |hook|
+            begin
+              action.send(hook, execution_plan)
+            rescue => e
+              execution_plan.logger.error "Failed to run hook '#{hook}' for action '#{action.class}'"
+              execution_plan.logger.debug e
+            end
+          end
+        end
+
+        # Returns which hooks should be run on certain event.
+        #
+        # @param kind [Symbol] what kind of hook are we looking for
+        # @return [Array<Class>] list of hook classes to execute
+        def on(kind)
+          hooks.select { |_key, on| on.include? kind }.keys
+        end
+
+        private
+
+        def validate_kinds!(kinds)
+          kinds.each do |kind|
+            raise "Unknown hook kind '#{kind}'" unless HOOK_KINDS.include?(kind)
+          end
+        end
+      end
+    end
+  end
+end