ruote-maestrodev 2.2.1

data/lib/ruote/part/engine_participant.rb

@@ -0,0 +1,189 @@
+#--
+# Copyright (c) 2005-2011, John Mettraux, jmettraux@gmail.com
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+# Made in Singapore.
+#++
+
+require 'ruote/util/subprocess'
+require 'ruote/part/local_participant'
+
+
+module Ruote
+
+  #
+  # A participant for pushing the execution of [segments of] processes to
+  # other engines.
+  #
+  # It works by giving the participant the connection information to the storage
+  # of the other engine.
+  #
+  # For instance :
+  #
+  #   engine0 =
+  #     Ruote::Engine.new(
+  #       Ruote::Worker.new(
+  #         Ruote::FsStorage.new('work0', 'engine_id' => 'engine0')))
+  #   engine1 =
+  #     Ruote::Engine.new(
+  #       Ruote::Worker.new(
+  #         Ruote::FsStorage.new('work1', 'engine_id' => 'engine1')))
+  #
+  #   engine0.register_participant('engine1',
+  #     Ruote::EngineParticipant,
+  #     'storage_class' => Ruote::FsStorage,
+  #     'storage_path' => 'ruote/storage/fs_storage',
+  #     'storage_args' => 'work1')
+  #   engine1.register_participant('engine0',
+  #     Ruote::EngineParticipant,
+  #     'storage_class' => Ruote::FsStorage,
+  #     'storage_path' => 'ruote/storage/fs_storage',
+  #     'storage_args' => 'work0')
+  #
+  # In this example, two engines are created (note that their 'engine_id' is
+  # explicitely set (else it would default to 'engine')). Each engine is then
+  # registered as participant in the other engine. The registration parameters
+  # detail the class and the arguments to the storage of the target engine.
+  #
+  # This example is a bit dry / flat. A real world example would perhaps detail
+  # a 'master' engine connected to 'departmental' engines, something more
+  # hierarchical.
+  #
+  # The example also binds reciprocally engines. If the delegated processes
+  # are always 'forgotten', one could imagine not binding the source engine
+  # as a participant in the target engine (not need to answer back).
+  #
+  # There are then two variants for calling a subprocess
+  #
+  #   subprocess :ref => 'subprocess_name', :engine => 'engine1'
+  #     # or
+  #   participant :ref => 'engine1', :pdef => 'subprocess_name'
+  #
+  # It's OK to go for the shorter versions :
+  #
+  #   subprocess_name :engine => 'engine1'
+  #     # or
+  #   participant 'engine1', :pdef => 'subprocess_name'
+  #   engine1 :pdef => 'subprocess_name'
+  #
+  # The subprocess is defined in the current process, or it's given via its
+  # URL. The third variant is a subprocess bound as an engine variable.
+  #
+  #   engine.variables['variant_3'] = Ruote.process_definition do
+  #     participant 'hello_world_3'
+  #   end
+  #
+  #   pdef = Ruote.process_definition do
+  #     sequence do
+  #       engine1 :pdef => 'variant_1'
+  #       engine1 :pdef => 'http://pdefs.example.com/variant_2.rb'
+  #       engine1 :pdef => 'variant_3'
+  #     end
+  #     define 'variant_1' do
+  #       participant 'hello_world_1'
+  #     end
+  #   end
+  #
+  class EngineParticipant
+
+    include LocalParticipant
+
+    def initialize(opts)
+
+      if pa = opts['storage_path']
+        require pa
+      end
+
+      kl = opts['storage_class']
+
+      raise(ArgumentError.new("missing 'storage_class' parameter")) unless kl
+
+      args = opts['storage_args']
+      args = args.is_a?(Hash) ? [ args ] : Array(args)
+      args << {} unless args.last.is_a?(Hash)
+      args.last['preserve_configuration'] = true
+
+      @storage = Ruote.constantize(kl).new(*args)
+    end
+
+    def consume(workitem)
+
+      wi = workitem.to_h
+      fexp = Ruote::Exp::FlowExpression.fetch(@context, wi['fei'])
+      params = wi['fields'].delete('params')
+
+      forget = (fexp.attribute(:forget).to_s == 'true')
+
+      @storage.put_msg(
+        'launch',
+        'wfid' => wi['fei']['wfid'],
+        'parent_id' => forget ? nil : wi['fei'],
+        'tree' => determine_tree(fexp, params),
+        'workitem' => wi,
+        'variables' => fexp.compile_variables)
+
+      fexp.unpersist if forget
+        #
+        # special behaviour here in case of :forget => true :
+        # parent_id of remote expression is set to nil and local expression
+        # is unpersisted immediately
+    end
+
+    def cancel(fei, flavour)
+
+      exps = @storage.get_many('expressions', /^0![^!]+!#{fei.wfid}$/)
+
+      return true if exps.size < 1
+        # participant expression will reply to its parent
+
+      @storage.put_msg(
+        'cancel',
+        'fei' => exps.first['fei'],
+        'flavour' => flavour)
+
+      false
+        # participant expression will NOT reply to its parent
+    end
+
+    def reply(fei, workitem)
+
+      @storage.put_msg(
+        'reply',
+        'fei' => fei,
+        'workitem' => workitem)
+    end
+
+    protected
+
+    def determine_tree(fexp, params)
+
+      pdef = params['def'] || params['pdef'] || params['tree']
+
+      tree = Ruote.lookup_subprocess(fexp, pdef)
+
+      raise(
+        "couldn't find process definition behind '#{pdef}'"
+      ) unless tree
+
+      tree.last
+    end
+  end
+end
+

data/lib/ruote/part/local_participant.rb

@@ -0,0 +1,138 @@
+#--
+# Copyright (c) 2005-2011, John Mettraux, jmettraux@gmail.com
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+# Made in Japan.
+#++
+
+require 'ruote/receiver/base'
+
+
+module Ruote
+
+  #
+  # Provides methods for 'local' participants.
+  #
+  # Assumes the class that includes this module has a #context method
+  # that points to the worker or engine ruote context.
+  #
+  # It's "local" because it has access to the ruote storage.
+  #
+  module LocalParticipant
+
+    include ReceiverMixin
+      # the reply_to_engine method is there
+
+    attr_accessor :context
+
+    # Use this method to re_dispatch the workitem.
+    #
+    # It takes two options :in and :at for "later re_dispatch".
+    #
+    # Look at the unschedule_re_dispatch method for an example of
+    # participant implementation that uses re_dispatch.
+    #
+    # Without one of those options, the method is a "reject".
+    #
+    def re_dispatch(workitem, opts={})
+
+      msg = {
+        'action' => 'dispatch',
+        'fei' => workitem.h.fei,
+        'workitem' => workitem.h,
+        'participant_name' => workitem.participant_name,
+        'rejected' => true
+      }
+
+      if t = opts[:in] || opts[:at]
+
+        sched_id = @context.storage.put_schedule('at', workitem.h.fei, t, msg)
+
+        fexp = fetch_flow_expression(workitem)
+        fexp.h['re_dispatch_sched_id'] = sched_id
+        fexp.try_persist
+
+      else
+
+        @context.storage.put_msg('dispatch', msg)
+      end
+    end
+
+    # Cancels the scheduled re_dispatch, if any.
+    #
+    # An example or 'retrying participant' :
+    #
+    #   class RetryParticipant
+    #     include Ruote::LocalParticipant
+    #
+    #     def initialize(opts)
+    #       @opts = opts
+    #     end
+    #
+    #     def consume(workitem)
+    #       begin
+    #         do_the_job
+    #         reply(workitem)
+    #       rescue
+    #         re_dispatch(workitem, :in => @opts['delay'] || '1s')
+    #       end
+    #     end
+    #
+    #     def cancel(fei, flavour)
+    #       unschedule_re_dispatch(fei)
+    #     end
+    #   end
+    #
+    # Note how unschedule_re_dispatch is used in the cancel method. Warning,
+    # this example could loop forever...
+    #
+    def unschedule_re_dispatch(fei)
+
+      fexp = Ruote::Exp::FlowExpression.fetch(
+        @context, Ruote::FlowExpressionId.extract_h(fei))
+
+      if s = fexp.h['re_dispatch_sched_id']
+        @context.storage.delete_schedule(s)
+      end
+    end
+
+    # This reject method replaces the workitem in the [internal] message queue
+    # of the ruote engine (since it's a local participant, it has access to
+    # the storage and it's thus easy).
+    # The idea is that another worker will pick up the workitem and
+    # do the participant dispatching.
+    #
+    # This is an advanced technique. It was requested by people who
+    # want to have multiple workers and have only certain worker/participants
+    # do the handling.
+    # Using reject is not the best method, it's probably better to implement
+    # this by re-opening the Ruote::Worker class and changing the
+    # cannot_handle(msg) method.
+    #
+    # reject could be useful anyway, not sure now, but one could imagine
+    # scenarii where some participants reject workitems temporarily (while
+    # the same participant on another worker would accept it).
+    #
+    # Well, here it is, use with care.
+    #
+    alias :reject :re_dispatch
+  end
+end
+

data/lib/ruote/part/no_op_participant.rb

@@ -0,0 +1,60 @@
+#--
+# Copyright (c) 2005-2011, John Mettraux, jmettraux@gmail.com
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+# Made in Japan.
+#++
+
+
+require 'ruote/part/local_participant'
+
+
+module Ruote
+
+  #
+  # A participant that simply replies immediately to the engine.
+  #
+  # For testing purposes, but could be useful when used in conjunction with
+  # 'listen'.
+  #
+  class NoOpParticipant
+
+    include LocalParticipant
+
+    def initialize(opts=nil)
+
+      @items = {}
+    end
+
+    #
+    # No operation : simply replies immediately to the engine.
+    #
+    def consume(workitem)
+
+      reply_to_engine(workitem)
+    end
+
+    def cancel(fei, flavour)
+
+      # nothing to do
+    end
+  end
+end
+

data/lib/ruote/part/null_participant.rb

@@ -0,0 +1,54 @@
+#--
+# Copyright (c) 2005-2011, John Mettraux, jmettraux@gmail.com
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+# Made in Japan.
+#++
+
+require 'ruote/part/local_participant'
+
+
+module Ruote
+
+  #
+  # A /dev/null participant, simply discards the workitems it receives,
+  # without doing anything.
+  #
+  # For testing purposes only.
+  #
+  class NullParticipant
+
+    include LocalParticipant
+
+    def initialize(opts=nil)
+    end
+
+    # Does nothing, discards the workitem it receives.
+    #
+    def consume(workitem)
+    end
+
+    # Does nothing.
+    #
+    def cancel(fei, flavour)
+    end
+  end
+end
+

data/lib/ruote/part/rev_participant.rb

@@ -0,0 +1,169 @@
+#--
+# Copyright (c) 2005-2011, John Mettraux, jmettraux@gmail.com
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+# Made in Japan.
+#++
+
+
+require 'open-uri'
+
+require 'ruote/part/local_participant'
+
+
+module Ruote
+
+  #
+  # This participant was born out of a suggestion from Jan Topiński in
+  # http://groups.google.com/group/openwferu-users/browse_thread/thread/be20a5d861556fd8
+  #
+  # This participant is a gateway to code placed in a directory.
+  #
+  #   engine.register do
+  #     toto, Ruote::RevParticipant, :dir => 'participants/toto/'
+  #   end
+  #
+  # Then in the participants/toto/ dir :
+  #
+  #     /my_workflow__0.1__toto_0.6.rb
+  #       # participant toto, workflow 'my_workflow' with revision '0.1'
+  #     /my_workflow__toto.rb
+  #       # participant toto, workflow 'my_workflow' any revision
+  #     /toto_0.6.rb
+  #       # participant toto with rev '0.6', any workflow
+  #     /toto.rb
+  #       # participant toto, any rev, any workflow
+  #       # ...
+  #
+  # The scheme goes like :
+  #
+  #    /wf-name__wf-revision__participant-name__p-revision.rb
+  #
+  # The files themselves look like :
+  #
+  #   def consume(workitem)
+  #     workitem.fields['kilroy'] = 'was here'
+  #     reply_to_engine(workitem)
+  #   end
+  #
+  # The file directly contains the classical participant methods defined at the
+  # top level. #cancel, #accept?, #on_reply and of course #consume are OK.
+  #
+  #
+  # Maybe, look at the tests for more clues :
+  #
+  #   https://github.com/jmettraux/ruote/blob/master/test/functional/ft_57_rev_participant.rb
+  #
+  # *Note* : It's probably not the best participant in a distributed context, it
+  # grabs the code to execute from a directory. If you use it in a distributed
+  # context, you'll have to make sure to synchronize the directory to each host
+  # running a worker.
+  #
+  # *Warning* : this participant trusts the code it deals with, there is no
+  # security check.
+  #
+  class RevParticipant
+
+    include LocalParticipant
+
+    # TODO : how to deal with >= and ~> ?
+
+    def initialize(opts=nil)
+
+      @dir = opts['dir']
+
+      raise ArgumentError.new(
+        "missing option :dir for #{self.class}"
+      ) unless @dir
+    end
+
+    def consume(workitem)
+
+      lookup_code(workitem).consume(workitem)
+    end
+
+    def cancel(fei, flavour)
+
+      lookup_code(fei).cancel(fei, flavour)
+    end
+
+    #--
+    #def accept?(workitem)
+    #  part = lookup_code(workitem)
+    #  part.respond_to?(:accept?) ? part.accept?(workitem) : true
+    #end
+    #
+    # Can't do this at this level, since it isn't the rev_participant's
+    # own accept?, it has to go in lookup_code
+    #++
+
+    def on_reply(workitem)
+
+      part = lookup_code(workitem)
+      part.on_reply(workitem) if part.respond_to?(:on_reply)
+    end
+
+    def rtimeout(workitem)
+
+      part = lookup_code(workitem)
+
+      part.respond_to?(:rtimeout) ? part.rtimeout(workitem) : nil
+    end
+
+    protected
+
+    # Maybe "lookup_real_participant_code" would be a better name...
+    #
+    def lookup_code(wi_or_fei)
+
+      wi = wi_or_fei.is_a?(Ruote::Workitem) ?  wi_or_fei : workitem(wi_or_fei)
+
+      rev = wi.params['revision'] || wi.params['rev']
+
+      [
+        [ wi.wf_name, wi.wf_revision, wi.participant_name, rev ],
+        [ wi.wf_name, wi.wf_revision, wi.participant_name ],
+        [ wi.wf_name, '', wi.participant_name ],
+        [ wi.participant_name, rev ],
+        [ wi.participant_name ],
+      ].each do |fname|
+
+        fname = File.join(@dir, "#{fname.compact.join('__')}.rb")
+        next unless File.exist?(fname)
+
+        cpart = Class.new
+        cpart.send(:include, Ruote::LocalParticipant)
+        cpart.module_eval(File.read(fname))
+        part = cpart.new
+        part.context = @context
+
+        next if part.respond_to?(:accept?) and (not part.accept?(wi))
+
+        return part
+      end
+
+      raise ArgumentError.new(
+        "couldn't find code for participant #{wi.participant_name} " +
+        "in dir #{@dir}"
+      )
+    end
+  end
+end
+