ruote-amqp 2.2.0 → 2.3.0

data/CHANGELOG.txt

@@ -2,6 +2,11 @@
 = ruote-amqp
 
 
+== ruote-amqp - 2.3.0    released 2012/09/02
+
+- complete rework to better adhere to the AMQP philosophy
+
+
 == ruote-amqp - 2.2.0    released 2011/03/01
 
 - receiver : exposing #decode_workitem for overwriting

data/CREDITS.txt

@@ -12,6 +12,7 @@
 
 == CONTRIBUTORS
 
+* Jiří Kubíček - https://github.com/kubicek
 * Mario Camou
 * Sean Johnson - https://github.com/belucid
 * Victor Liu - https://github.com/pennymax
@@ -27,3 +28,6 @@
 
 == FEEDBACK
 
+* Jim Li - https://github.com/marsbomber - auto_recovery and co
+* Marco Sehrer - https://github.com/pixelvitamina - ruote 2.2 vs 2.3
+

data/LICENSE.txt

@@ -0,0 +1,21 @@
+
+Copyright (c) 2010-2012 Kenneth Kalmer
+
+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.
+

data/README.md

@@ -0,0 +1,173 @@
+
+# ruote-amqp
+
+ruote-amqp is a set of classes that let a ruote engine publish and/or receive messages over AMQP.
+
+The most common use case is publishing workitems for processing by AMQP consumers and eventually receiving them back to resume the flow.
+
+Another use case would be to listen on an AMQP queue for workflow launch requests.
+
+Listening for arbitrary AMQP messages before resuming a flow (ambush/alert) is also possible.
+
+
+## usage
+
+### Ruote::Amqp::Participant
+
+Publishing messages
+
+```ruby
+$dashboard.register(
+  :toto,
+  Ruote::Amqp::Participant,
+  :exchange => [ 'direct', '' ],
+  :routing_key => 'alpha')
+
+pdef = Ruote.define do
+  toto
+end
+
+$dashboard.launch(pdef)
+
+# ...
+```
+
+### Ruote::Amqp::AlertParticipant
+
+Ambushing messages from a process definition. The alert participant when
+receiving a workitem starts waiting for the next message on a given queue. When
+the message arrives, it responds to the engine (with a
+
+```ruby
+$dashboard.register(
+  :wait_for_info,
+  Ruote::Amqp::AlertParticipant,
+  :queue => 'info')
+
+pdef = Ruote.define do
+  # ... before
+  wait_for_job # flows wait for first message on 'info' queue
+  # ... after
+end
+```
+
+By default it waits for 1 message that it places in the "amqp_message" field
+of the workitem going back to the engine.
+
+One can override the #handle method to change the way the workitem is modified
+according to the message.
+
+It's also OK to override the #on_workitem method of this participant if one
+waits to wait for more than 1 message.
+
+See the AlertParticipant rdoc for more.
+
+### Ruote::Amqp::Receiver
+
+Receiving messages.
+
+A receiver is a ruote service subscribed to a queue. When a message comes on
+the queue, the receiver will look at it and, according to the payload, either
+launch a new workflow instance, resume a currently workflow instance segment
+or pass an error back from a participant to the engine.
+
+(In fact the resume workflow / pass participant error back to the engine are
+closely related)
+
+(NTS: at some point, receivers should be able to deal with "cancel messages")
+
+```ruby
+# A simple coupling between participant "toto" and a receiver via AMQP
+#
+# A real world example would have toto publishing somewhere, the message
+# getting fetched by the real (remote) participant and then handed back
+# on the queue the receiver is subscribed to.
+
+$dashboard.register(
+  :toto,
+  Ruote::Amqp::Participant,
+  :exchange => [ 'direct', '' ],
+  :routing_key => 'alpha')
+
+receiver = Ruote::Amqp::Receiver.new(
+  $dashboard, AMQP::Channel.new.queue('alpha'))
+
+# ...
+```
+
+### Controlling the connection (AMQP session)
+
+The Ruote::Amqp module has a handy singleton for connections (actually
+AMQP::Session instances).
+
+```ruby
+# (before registering participants)
+
+Ruote::Amqp.session = AMQP.connect(:auto_recovery => true) do |con|
+  con.on_recovery do |con|
+    puts "Recovered..."
+  end
+  connection.on_tcp_connection_loss do |con, settings|
+    puts "Reconnecting... please wait"
+    conn.reconnect(false, 20)
+  end
+end
+```
+
+When a participant tries to connect to AMQP, it will automatically use the value in Ruote::Amqp.session (else it will set up a new connection).
+
+The receivers expect a queue when they are set up, feel free to set Ruote::Amqp.session, then use it when instantiating receivers (the participant will follow suit).
+
+If you want a different way of connecting to AMQP for the participants, you can override their #amqp_connect methods (or pass them AMQP connection settings when registering them).
+
+
+## requirements
+
+* ruote[http://ruote.rubyforge.org] 2.3.0 or later
+* amqp[http://rubyamqp.info/] 0.9.0 or later
+* rabbitmq[http://www.rabbitmq.com/] 2.2.0 or later
+
+
+## install
+
+Please be sure to have read the requirements section above
+
+    gem install ruote-amqp
+
+or via your Gemfile (thanks [bundler](http://gembundler.com)).
+
+
+## tests / specs
+
+To run the tests you need the following requirements met, or the testing environment will fail horribly (or simply get stuck without output).
+
+
+### RabbitMQ vhost
+
+The tests use dedicated vhost on a running AMQP broker. To configure RabbitMQ
+you can run the following commands (the RabbitMQ server must be running):
+
+    $ rabbitmqctl add_vhost ruote-test
+    $ rabbitmqctl add_user ruote ruote
+    $ rabbitmqctl set_permissions -p ruote-test ruote '.*' '.*' '.*'
+
+or by running:
+
+    $ rake prepare
+
+
+If you need to change the AMQP configuration used by the tests, edit the
++spec/spec_helper.rb+ file.
+
+
+## daemon-kit
+
+Kenneth Kalmer, the original author of the ruote-amqp gem is also the author of [DaemonKit](https://github.com/kennethkalmer/daemon-kit) a library/toolbox for building daemons.
+
+It used to be the preferred way to wrap remote participants (as daemons) but lately Kenneth hasn't had much time for support. It's still full of excellent ideas.
+
+
+## license
+
+MIT, see LICENSE.txt
+

data/Rakefile

@@ -6,7 +6,7 @@ require 'rubygems/user_interaction' if Gem::RubyGemsVersion == '1.5.0'
 
 require 'rake'
 require 'rake/clean'
-require 'rake/rdoctask'
+#require 'rake/rdoctask'
 
 
 #
@@ -68,34 +68,36 @@ task :prepare do
 end
 
 
+##
+## rdoc
+##
+## make sure to have rdoc 2.5.x to run that
 #
-# rdoc
+#Rake::RDocTask.new do |rd|
 #
-# make sure to have rdoc 2.5.x to run that
-
-Rake::RDocTask.new do |rd|
-
-  rd.main = 'README.rdoc'
-  rd.rdoc_dir = 'rdoc'
-
-  rd.rdoc_files.include(
-    'README.rdoc', 'CHANGELOG.txt', 'CREDITS.txt', 'lib/**/*.rb')
-
-  rd.title = "#{GEMSPEC.name} #{GEMSPEC.version}"
-end
-
-
+#  rd.main = 'README.rdoc'
+#  rd.rdoc_dir = 'rdoc'
 #
-# upload_rdoc
-
-desc %{
-  upload the rdoc to rubyforge
-}
-task :upload_rdoc => [ :clean, :rdoc ] do
-
-  account = 'jmettraux@rubyforge.org'
-  webdir = '/var/www/gforge-projects/ruote'
-
-  sh "rsync -azv -e ssh rdoc/#{GEMSPEC.name}_rdoc #{account}:#{webdir}/"
-end
+#  rd.rdoc_files.include(
+#    'README.rdoc', 'CHANGELOG.txt', 'CREDITS.txt', 'lib/**/*.rb')
+#
+#  rd.title = "#{GEMSPEC.name} #{GEMSPEC.version}"
+#end
+#
+#
+##
+## upload_rdoc
+#
+#desc %{
+#  upload the rdoc to rubyforge
+#}
+#task :upload_rdoc => [ :clean, :rdoc ] do
+#
+#  account = 'jmettraux@rubyforge.org'
+#  webdir = '/var/www/gforge-projects/ruote'
+#
+#  sh "rsync -azv -e ssh rdoc/#{GEMSPEC.name}_rdoc #{account}:#{webdir}/"
+#end
+  #
+  # leverarge rdoc.info instead
 

data/TODO.txt

@@ -6,3 +6,11 @@
 [ ] have a class method ParticipantProxy.stop_all ?
 [ ] use Ruote::Workitem #as_json and #from_json(s)
 
+*** 2.3.0
+
+[x] https://gist.github.com/1944228
+[ ] ON_CANCEL !
+
+[ ] incorporate
+    https://github.com/marsbomber/ruote-amqp/commit/0f36a41f4a0254847a7b9a7c4b2098c8164f21f3
+

data/lib/ruote/amqp/alert_participant.rb

@@ -0,0 +1,146 @@
+#--
+# Copyright (c) 2010-2012, Kenneth Kalmer, John Mettraux.
+#
+# 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.
+#++
+
+
+module Ruote::Amqp
+
+  #
+  # The alert participant, when invoked from a process instance will
+  # lay in wait for the next message on a given queue. As soon as the message
+  # comes in, it will pack it in the workitem fields and let the process
+  # definition resume.
+  #
+  #   @dashboard.register(
+  #     :wait_for_info,
+  #     Ruote::Amqp::AlertParticipant,
+  #     :queue => 'info')
+  #
+  #   pdef = Ruote.define do
+  #     wait_for_job
+  #     # ... the rest of the flow
+  #   end
+  #
+  # == configuration
+  #
+  # This class is mostly a subclass of Ruote::Amqp::Participant, it accepts
+  # the same configuration options (but has no need for 'exchange'). It
+  # accepts a 'queue' option in the form [ 'queue_name', { queue options } ].
+  #
+  #
+  # == overriding #handle(header, payload)
+  #
+  # The default implementation for this method is:
+  #
+  #   def handle(header, payload)
+  #     workitem.fields['amqp_message'] = [ header.to_hash, payload ]
+  #   end
+  #
+  # One is free to override it:
+  #
+  #   class MyAlertParticipant < Ruote::Amqp::AlertParticipant
+  #     def handle(header, payload)
+  #       fields = Rufus::Json.decode(payload)
+  #       workitem.fields.merge!(fields)
+  #     end
+  #   end
+  #
+  #
+  # == overriding #on_workitem
+  #
+  # Out of the box, the alert participant listens for 1 message on 1 queue.
+  # It's not too difficult to change that.
+  #
+  # Resuming after 3 messages:
+  #
+  #   class MyAlertParticipant < Ruote::Amqp::AlertParticipant
+  #
+  #     def on_workitem
+  #
+  #       messages = []
+  #
+  #       queue.subscribe { |header, payload |
+  #
+  #         messages << payload
+  #
+  #         if messages.size > 2
+  #           queue.unsubscribe
+  #           workitem.fields['messages'] = messages
+  #           reply # let the flow resume
+  #         end
+  #       }
+  #     end
+  #   end
+  #
+  # Observing 2 queues:
+  #
+  #   class MyAlertParticipant < Ruote::Amqp::AlertParticipant
+  #
+  #     def on_workitem
+  #
+  #       messages = []
+  #
+  #       q0 = channel.queue('zero')
+  #       q1 = channel.queue('one')
+  #
+  #       [ q0, q1 ].subscribe { |header, payload |
+  #         messages << payload
+  #       }
+  #
+  #       sleep 1.0 while messages.size < 2
+  #
+  #       reply # let the flow resume
+  #     end
+  #   end
+  #
+  class AlertParticipant < Participant
+
+    def on_workitem
+
+      queue.subscribe { |header, payload|
+
+        queue.unsubscribe
+        handle(header, payload)
+        reply
+      }
+    end
+
+    protected
+
+    # Called when the AMQP message comes in. This default implementation
+    # stuffs the AMQP [ header, payload ] into an 'amqp_message' workitem
+    # field.
+    #
+    def handle(header, payload)
+
+      workitem.fields['amqp_message'] = [ header.to_hash, payload ]
+    end
+
+    # Looks at the configuration options ('connection' and 'queue') and
+    # returns the queue the participant will fetch a message from.
+    #
+    def queue
+
+      @queue ||= channel.queue(*(opt('queue') || [ '' ]))
+    end
+  end
+end
+