ruote-stomp 2.2.0.a

data/CHANGELOG.txt

@@ -0,0 +1,10 @@
+
+= ruote-stomp
+
+
+== ruote-stomp - 2.2.0    released ?
+
+- work has just begun, porting from ruote-amqp
+
+
+

data/CREDITS.txt

@@ -0,0 +1,32 @@
+
+= CREDITS
+
+(probably incomplete, don't hesitate to tell us if a mention is missing)
+
+== AUTHORS
+
+* Kit Plummer - http://kitplummer.github.com
+
+== AUTHORS (from ruote-amqp)
+
+* Kenneth Kalmer - http://www.opensourcery.co.za/
+* John Mettraux - https://github.com/jmettraux
+
+
+== CONTRIBUTORS (from ruote-amqp)
+
+* Mario Camou
+* Sean Johnson - https://github.com/belucid
+* Victor Liu - https://github.com/pennymax
+* weifeng - https://github.com/weifeng365
+* David Greaves - https://github.com/lbt
+* Hartog C. de Mik - https://github.com/coffeeaddict
+* Torsten Schoenebaum - https://github.com/tosch
+* Jordan Ritter - https://github.com/jpr5
+* Charles Magid - https://github.com/ChasManRors
+* Marc Mauger - https://github.com/simianarmy
+* Jason - https://github.com/asm
+
+
+== FEEDBACK
+

data/PostInstall.txt

@@ -0,0 +1,12 @@
+
+For more information on ruote-stomp, see http://github.com/maestrodev/ruote-stomp
+
+Please note that this gem requires access to an Stomp broker and a good 
+understanding of Stomp and remote participants in general.
+
+Join us in #ruote on Freenode or on the openwfe-users Google Group to discuss
+it's uses.
+
+You might also want to look at daemon-kit for help with writing external
+participants that communicate with ruote via Stomp.
+

data/README.rdoc

@@ -0,0 +1,77 @@
+
+= ruote-stomp
+
+* http://github.com/kitplummer/ruote-stomp
+
+== DESCRIPTION:
+
+ruote-stomp provides a Stomp participant/listener pair that allows you to 
+distribute workitems out to Stomp consumers for processing, as well as launching
+processes over Stomp.
+
+To learn more about remote participants in ruote please see
+http://ruote.rubyforge.org/part_implementations.html
+
+== FEATURES/PROBLEMS:
+
+* Flexible participant for sending workitems
+* Flexible receiver for receiving replies
+* Flexible launch item listener for launching processes over Stomp
+* Fully evented (thanks to the stomp gem)
+
+== SYNOPSIS:
+
+Please review the code for information (rdocs to be updated soon.)
+
+== REQUIREMENTS:
+
+* ruote[http://ruote.rubyforge.org] 2.2.0 or later
+* stomp[https://gitorious.org/stomp] 1.1.8 or later
+* a server that supports Stomp (stompserver, ActiveMQ, RabbitMQ)
+
+== INSTALL:
+
+Please be sure to have read the requirements section above
+
+* sudo gem install ruote-stomp
+
+== TESTS:
+
+To run the tests you need the following requirements met, or the testing environment
+will fail horribly (or simply get stuck without output).
+
+=== Stomp server
+
+I've tested it with stompserver and ActiveMQ. 
+
+I'll work on getting the Ruby stompserver setup to start/shutdown with the tests.
+
+== DAEMON-KIT:
+
+Will work on adding Daemon-Kit support for ruote-stomp next. :)
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2010-2011 Kit Plummer (and Kenneth Kalmer for
+ruote-amqp, which this works is based on)
+
+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/Rakefile

@@ -0,0 +1,101 @@
+
+$:.unshift('.') # 1.9.2
+
+require 'rubygems'
+require 'rubygems/user_interaction' if Gem::RubyGemsVersion == '1.5.0'
+
+require 'rake'
+require 'rake/clean'
+require 'rake/task'
+
+
+#
+# clean
+
+CLEAN.include('pkg', 'rdoc')
+
+
+#
+# test / spec
+
+task :spec do
+
+  sh 'rspec spec/'
+end
+
+task :test => [ :spec ]
+task :default => [ :spec ]
+
+
+#
+# gem
+
+GEMSPEC_FILE = Dir['*.gemspec'].first
+GEMSPEC = eval(File.read(GEMSPEC_FILE))
+GEMSPEC.validate
+
+
+desc %{
+  builds the gem and places it in pkg/
+}
+task :build do
+
+  sh "gem build #{GEMSPEC_FILE}"
+  sh "mkdir pkg" rescue nil
+  sh "mv #{GEMSPEC.name}-#{GEMSPEC.version}.gem pkg/"
+end
+
+desc %{
+  builds the gem and pushes it to rubygems.org
+}
+task :push => :build do
+
+  sh "gem push pkg/#{GEMSPEC.name}-#{GEMSPEC.version}.gem"
+end
+
+
+#
+# rabbitmq preparation
+
+desc %{
+  prepare RabbitMQ (vhost, user, perms)
+}
+task :prepare do
+
+  sh "rabbitmqctl add_vhost ruote-test"
+  sh "rabbitmqctl add_user ruote ruote"
+  sh "rabbitmqctl set_permissions -p ruote-test ruote '.*' '.*' '.*'"
+end
+
+
+#
+# rdoc
+#
+# 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
+
+
+#
+# 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
+

data/TODO.txt

@@ -0,0 +1,4 @@
+
+[ ] have a class method ParticipantProxy.stop_all ?
+[ ] use Ruote::Workitem #as_json and #from_json(s)
+

data/lib/ruote-stomp/launchitem_listener.rb

@@ -0,0 +1,22 @@
+
+module RuoteStomp
+
+  #
+  # Got replaced by RuoteStomp::Receiver
+  #
+  # This class is kept for backward compatibility.
+  #
+  class LaunchitemListener < ::RuoteStomp::Receiver
+
+    # Start a new LaunchItem listener
+    #
+    # @param [ Ruote::Engine, Ruote::Storage ] A configured ruote engine or storage instance
+    # @param opts :queue / :unsubscribe
+    #
+    def initialize(engine_or_storage, opts={})
+
+      super(engine_or_storage, opts.merge(:launchitems => :only))
+    end
+  end
+end
+

data/lib/ruote-stomp/participant.rb

@@ -0,0 +1,225 @@
+
+require 'ruote/part/local_participant'
+require 'ruote-stomp'
+
+
+module RuoteStomp
+
+  #
+  # = Stomp Participants
+  #
+  # The RuoteStomp::ParticipantProxy allows you to send workitems (serialized as
+  # JSON) or messages to any Stomp queues right from the process
+  # definition. When combined with the RuoteStomp::Receiver you can easily
+  # leverage an extremely powerful local/remote participant
+  # combinations.
+  #
+  # For local/remote participants The local part of the
+  # RuoteStomp::ParticipantProxy relies on the presence of a
+  # RuoteStomp::Receiver. Workitems are sent to the remote participant
+  # and the local part does not normally reply to the engine.  Instead
+  # the engine will continue when a reply is received on the
+  # 'ruote_workitems' queue (see RuoteStomp::Receiver).
+  #
+  # Of course, the standard :forget => true format can be used even
+  # with remote particpants and :forget can even be set as a default in
+  # the options.
+  #
+  # [NOTE: Working this port next!!!]
+  # A simple way to create a remote participant to act upon workitems
+  # is to use the daemon-kit ruote responder.
+  #
+  # Simple Stomp messages are treated as 'fire and forget' and the flow
+  # will continue when the local participant has queued the message
+  # for sending. (As there is no meaningful way to receive a workitem
+  # in reply).
+  #
+  # == Configuration
+  #
+  # Stomp configuration is handled by directly manipulating the
+  # values of the +Stomp.settings+ hash, as provided by the Stomp
+  # gem. No Stomp defaults are set by the participant.
+  #
+  # == Usage
+  #
+  # Define the queue used by an AMQP participant :
+  #
+  #   engine.register_participant(
+  #     :delete_user, RuoteStomp::ParticipantProxy, 'queue' => 'user_manager')
+  #
+  # Sending a workitem to the remote participant defined above:
+  #
+  #   Ruote.process_definition do
+  #     sequence do
+  #       delete_user
+  #     end
+  #   end
+  #
+  # Let the local participant reply to the engine without involving
+  # the receiver
+  #
+  #   Ruote.process_definition do
+  #     sequence do
+  #       delete_user :forget => true
+  #     end
+  #   end
+  #
+  # Setting up the participant in a slightly more 'raw' way:
+  #
+  #   engine.register_participant(
+  #     :stomp, RuoteStomp::ParticipantProxy )
+  #
+  # Sending a workitem to a specific queue:
+  #
+  #   Ruote.process_definition do
+  #     sequence do
+  #       stomp :queue => 'test', 'command' => '/run/regression_test'
+  #     end
+  #   end
+  #
+  # Setup a 'fire and forget' participant that always replies to the
+  # engine:
+  #
+  #   engine.register_participant(
+  #     :jfdi, RuoteStomp::ParticipantProxy, 'forget' => true )
+  #
+  # Sending a message example to a specific queue (both steps are
+  # equivalent):
+  #
+  #   Ruote.process_definition do
+  #     sequence do
+  #       stomp :queue => 'test', :message => 'foo'
+  #       stomp :queue => 'test', :message => 'foo', :forget => true
+  #     end
+  #   end
+  #
+  #
+  # == Stomp notes
+  #
+  # The direct exchanges are always marked as durable by the
+  # participant, and messages are marked as persistent by default (see
+  # #RuoteStomp)
+  #
+  class ParticipantProxy
+
+    include Ruote::LocalParticipant
+
+    # The following parameters are used in the process definition.
+    #
+    # An options hash with the same keys to provide defaults is
+    # accepted at registration time (see above).
+    #
+    # * :queue => (string) The Stomp queue used by the remote participant.
+    #   nil by default.
+    # * :forget => (bool) Whether the flow should block until the remote
+    #   participant replies.
+    #   false by default
+    #
+    def initialize(options)
+      @options = {
+        'queue' => nil,
+        'forget' => false,
+      }.merge(options.inject({}) { |h, (k, v)|
+        h[k.to_s] = v; h
+      })
+        #
+        # the inject is here to make sure that all options have String keys
+    end
+
+    # Process the workitem at hand. By default the workitem will be
+    # published to the direct exchange specified in the +queue+
+    # workitem parameter. You can specify a +message+ workitem
+    # parameter to have that sent instead of the workitem.
+    #
+    def consume(workitem)
+
+      RuoteStomp.start!
+      target_queue = determine_queue(workitem)
+
+      raise 'no queue specified (outbound delivery)' unless target_queue
+
+      #q = MQ.queue(target_queue, :durable => true)
+      forget = determine_forget(workitem)
+
+      opts = {
+        :persistent => RuoteStomp.use_persistent_messages?,
+        :content_type => 'application/json' }
+
+      if message = workitem.fields['message'] || workitem.params['message']
+
+        forget = true # sending a message implies 'forget' => true
+        $stomp.publish target_queue, message, opts         
+        #q.publish(message, opts)
+
+      else
+        $stomp.publish target_queue, encode_workitem(workitem), opts
+        #q.publish(encode_workitem(workitem), opts)
+      end
+
+      reply_to_engine(workitem) if forget
+    end
+
+    # (Stops the underlying queue subscription)
+    #
+    def stop
+
+      RuoteStomp.stop!
+    end
+
+    def cancel(fei, flavour)
+      #
+      # TODO : sending a cancel item is not a bad idea, especially if the
+      #        job done over the stomp fence lasts...
+      #
+    end
+
+    # [NOT sure about this behavior with Stomp yet.  Need to dive.]
+    
+    def do_not_thread
+
+      true
+    end
+
+    private
+
+    def determine_forget(workitem)
+
+      return workitem.params['forget'] if workitem.params.has_key?('forget')
+      return @options['forget'] if @options.has_key?('forget')
+      false
+    end
+
+    def determine_queue(workitem)
+
+      workitem.params['queue'] || @options['queue']
+    end
+
+    # Encodes the workitem as JSON. Makes sure to add to the field 'params'
+    # an entry named 'participant_options' which contains the options of
+    # this participant.
+    #
+    def encode_workitem(wi)
+
+      wi.params['participant_options'] = @options
+
+      Rufus::Json.encode(wi.to_h)
+    end
+  end
+
+  #
+  # Kept for backward compatibility.
+  #
+  # You should use RuoteStomp::ParticipantProxy.
+  #
+  class Participant < ParticipantProxy
+
+    def initialize(options)
+      puts '=' * 80
+      puts "RuoteStomp::Participant will be deprecated soon (2.1.12)"
+      puts "please use RuoteStomp::ParticipantProxy instead"
+      puts '=' * 80
+      super
+    end
+  end
+end
+