ruote-stomp-maestrodev 2.2.2

data/CHANGELOG.txt

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

data/CREDITS.txt

@@ -0,0 +1,33 @@
+
+= CREDITS
+
+(probably incomplete, don't hesitate to tell us if a mention is missing)
+
+== AUTHORS
+
+* Kit Plummer - http://kitplummer.github.com
+* Brian Sam-Bodden = http://bsbodden.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,82 @@
+
+= 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 onstomp gem)
+
+== SYNOPSIS:
+
+Please review the code for information (rdocs to be updated soon.)
+
+== REQUIREMENTS:
+
+* ruote[http://ruote.rubyforge.org] 2.2.0 or later
+* onstomp[https://github.com/meadvillerb/onstomp] 1.0.4 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
+<<<<<<< Updated upstream
+without limitation the rights to use, copy, modify, merge, send,
+distribute, sublicense, and/or sell copies of the Software, and to
+=======
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of tshe Software, and to
+>>>>>>> Stashed changes
+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.rb

@@ -0,0 +1,116 @@
+require 'onstomp'
+
+require 'ruote-stomp/version'
+
+#
+# Stomp participant and listener pair for ruote.
+#
+# == Documentation
+#
+# See #RuoteStomp::Listener and #RuoteStomp::Participant for detailed
+# documentation on using each of them.
+#
+# == Stomp Notes
+#
+# RuoteAmqp uses durable queues and persistent messages by default, to ensure
+# no messages get lost along the way and that running expressions doesn't have
+# to be restarted in order for messages to be resent. <- not exactly sure yet
+# how RuoteStomp will handle durable queues, messages are persisted.
+#
+module RuoteStomp
+
+  autoload 'ParticipantProxy',   'ruote-stomp/participant'
+  autoload 'Receiver',           'ruote-stomp/receiver'
+  autoload 'WorkitemListener',   'ruote-stomp/workitem_listener'
+  autoload 'LaunchitemListener', 'ruote-stomp/launchitem_listener'
+
+  class << self
+
+    attr_writer :use_persistent_messages
+    
+    # Whether or not to use persistent messages (true by default)
+    def use_persistent_messages?
+      @use_persistent_messages = true if @use_persistent_messages.nil?
+      @use_persistent_messages
+    end
+
+    # Ensure the Stomp connection is started
+    def start!
+      return if started?
+      mutex = Mutex.new
+      cv = ConditionVariable.new
+      Thread.main[:ruote_stomp_connection] = Thread.new do
+        Thread.abort_on_exception = true
+
+        begin
+          if STOMP.settings[:ssl]
+            $stomp = OnStomp::Client.new(create_connection_uri(STOMP.settings),
+              :ssl => {
+                :ca_file => STOMP.settings[:cert],
+                :verify_mode => OpenSSL::SSL::VERIFY_NONE
+              }
+            )
+            $stomp.connect
+          else
+            $stomp = OnStomp.connect create_connection_uri(STOMP.settings)
+          end
+          
+          if $stomp && $stomp.connected?
+            started!
+            cv.signal
+          end
+        rescue Exception => e
+          raise RuntimeError, "Failed to connect to Stomp server. (#{e.message})"
+        end
+      end
+
+      mutex.synchronize { cv.wait(mutex) }
+
+      yield if block_given?
+    end
+
+    # Check whether the AMQP connection is started
+    def started?
+      Thread.main[:ruote_stomp_started] == true
+    end
+
+    def started! #:nodoc:
+      Thread.main[:ruote_stomp_started] = true
+    end
+
+    # Close down the Stomp connections
+    def stop!
+      return unless started?
+      $stomp.disconnect
+      Thread.main[:ruote_stomp_connection].join
+      Thread.main[:ruote_stomp_started] = false
+    end
+    
+    protected
+    
+    def create_connection_uri(config={})
+      config = config.map { |n,v| {n,v.to_s} }.reduce(:merge)
+      user = config[:user]
+      passcode = config[:passcode]
+      host = config[:host]
+      port = config[:port]
+      ssl = config[:ssl] || false
+      cert = config[:cert] || ""
+      
+      # construct the connection URI
+      user_and_password = [user,passcode].reject{|e| e.nil? || e.empty?}.join(":")
+      host_and_port = [host,port].reject{|e| e.nil? || e.empty?}.join(":")
+      uri = [host_and_port, user_and_password].reject{|e| e.nil? || e.empty?}.reverse.join("@")
+      protocol = ['stomp', ssl, '://'].reject{|e| e.nil? || e.empty?}.join
+      
+      "#{protocol}#{uri}"
+    end
+  end
+end
+
+module STOMP
+  def self.settings
+    @settings ||= {:host => "localhost", :port => "61613"}
+  end
+end
+

data/lib/ruote-stomp/launchitem_listener.rb

@@ -0,0 +1,20 @@
+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,212 @@
+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
+    # sended 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
+
+      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.send target_queue, message, opts         
+      else
+        $stomp.send target_queue, 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
+