nebulous_stomp 2.0.2 → 3.0.0

data/lib/nebulous_stomp/request.rb

@@ -0,0 +1,212 @@
+require_relative 'stomp_handler'
+require_relative 'redis_handler'
+require_relative 'message'
+require_relative 'target'
+
+
+module NebulousStomp
+
+
+  ##
+  # Class to handle a request which returns a Message; the Question-Answer use case.
+  #
+  #     message   = NebulousStomp::Message.new(verb: "ping")
+  #     request   = NebulousStomp::Request.new(:target1, message)
+  #     response1 = request.send
+  #
+  # This replaces the old NebRequest class; it's much more clearly a wrapper for a Message, now.
+  #
+  class Request
+
+    # The Target object we are sending the request to
+    attr_reader :target
+
+    # The message we are sending (might not be the Message object you passed...)
+    attr_reader :message
+
+    # If you are testing you can write these with a test object like StompHandlerNull for example
+    attr_writer :stomp_handler, :redis_handler
+
+    ##
+    # :call-seq:
+    #   Request.new(target, message) 
+    #
+    # Pass either a Target or a target name; and a Message (which has a verb)
+    #
+    def initialize(target, message)
+      @target  = parse_target(target)
+      @message = parse_message(message, @target)
+      NebulousStomp.logger.debug(__FILE__) { "New Request for verb #{@message.verb}" }
+
+      # Get a connection to StompHandler ASAP and set reply_id on @message
+      ensure_stomp_connected if NebulousStomp.on?
+    end
+
+    ##
+    # :call-seq:
+    #     request.send_no_cache           -> (Message)
+    #     request.send_no_cache(mtimeout) -> (Message)
+    #
+    # Send a request and return the response, without using the cache.
+    #
+    # Parameters:
+    #     * mTimeout -- Message timout in seconds; defaults to #message_timeout
+    #
+    # Raises ArgumentError, NebulousTimeout or NebulousError as necessary.
+    #
+    # Note that this routine completely ignores Redis. It doesn't just not check the cache; it also
+    # doesn't update it.
+    #
+    def send_no_cache(mtimeout=message_timeout)
+      return nil unless NebulousStomp.on?
+      NebulousStomp.logger.info(__FILE__) { "Sending request to target #{@target.name}" }
+
+      ensure_stomp_connected
+      neb_qna(mtimeout)
+    ensure
+      stomp_handler.stomp_disconnect
+    end
+
+    ##
+    # :call-seq:
+    #     request.send                    -> (Message)
+    #     request.send(mTImeout)          -> (Message)
+    #     request.send(mtimeout,ctimeout) -> (Message)
+    #
+    # As send_nocache, but without not using the cache :)
+    #
+    # Parameters:
+    #    * mtimeout -- Message timout in seconds; defaults to @mTimeout
+    #    * ctimeout -- Cache timout in seconds; defaults to @cTimeout
+    #
+    # Raises ArgumentError, NebulousTimeout, NebulousError as necessary.
+    #
+    def send(mtimeout=message_timeout, ctimeout=cache_timeout)
+      return nil unless NebulousStomp.on?
+      return send_no_cache(mtimeout) unless NebulousStomp.redis_on?
+      ensure_redis_connected
+
+      if (mess = cache_read).nil?
+        mess = send_no_cache(mtimeout)
+        cache_write(mess, ctimeout)
+      end
+
+      mess
+    ensure
+      redis_handler.quit
+    end
+
+    ##
+    # :call-seq:
+    #   request.clear_cache -> self
+    #
+    # Clear the cache of responses to this request - just this request.
+    #
+    def clear_cache
+      return self unless NebulousStomp.redis_on?
+      ensure_redis_connected
+      redis_handler.del(@message.protocol_json)
+      self
+    ensure
+      redis_handler.quit
+    end
+
+    ##
+    # Returns the default message timeout
+    #
+    def message_timeout
+      @target.message_timeout || Param.get(:messageTimeout)
+    end
+
+    ##
+    # Returns the default cache timeout
+    #
+    def cache_timeout
+      Param.get(:cacheTimeout)
+    end
+
+    private
+
+    def stomp_handler
+      @stomp_handler ||= StompHandler.new(Param.get :stompConnectHash)
+    end
+
+    def redis_handler
+      @redis_handler ||= RedisHandler.new(Param.get :redisConnectHash)
+    end
+
+    ##
+    # Helper routine for initialize
+    #
+    def parse_message(message, target)
+      fail ArgumentError, "Message was not a Message"    unless message.is_a? Message
+      fail ArgumentError, "Message does not have a verb" unless message.verb
+
+      new_message = ->(h){ Message.new(message.to_h.merge h) }
+      message.reply_to ? message : new_message.(replyTo: target.send_queue)
+    end
+
+    ##
+    # Helper routine for initialize
+    #
+    def parse_target(target)
+      t = target.is_a?(Target) ? target : Param.get_target(target)
+      fail ArgumentError, "Target was not a Target or a target name" unless t
+      t
+    end
+    
+    ##
+    # Connect to Stomp
+    # If we've lost the connection then reconnect but *keep replyID*
+    #
+    def ensure_stomp_connected
+      stomp_handler.stomp_connect unless stomp_handler.connected?
+      @message.reply_id = stomp_handler.calc_reply_id if @message.reply_id.nil? 
+    end
+
+    ##
+    # Connect to Redis
+    #
+    def ensure_redis_connected
+      redis_handler.connect unless redis_handler.connected?
+    end
+
+    ##
+    # Send a message via STOMP and wait for a response
+    #
+    def neb_qna(mTimeout)
+      stomp_handler.send_message(@target.receive_queue, @message)
+
+      response = nil
+      stomp_handler.listen_with_timeout(@target.send_queue, mTimeout) do |msg|
+        if @message.reply_id && msg.in_reply_to != @message.reply_id
+          false
+        else
+          response = msg
+          true
+        end
+      end
+
+      response
+    end
+
+    ##
+    # Read from the Redis cache
+    #
+    def cache_read
+      found = redis_handler.get(@message.protocol_json)
+      found.nil? ? nil : Message.from_cache(found)
+    end
+
+    ##
+    # Write to the Redis cache
+    #
+    def cache_write(response, timeout)
+      redis_handler.set(@message.protocol_json, response.to_h, ex: timeout)
+    end
+
+  end # Request
+
+
+end
+

data/lib/nebulous_stomp/stomp_handler.rb

@@ -8,9 +8,9 @@ module NebulousStomp
   ##
   # A Class to deal with talking to STOMP via the Stomp gem.
   #
-  # You will need to instantiate this yourself if you only want to listen for messages. But if you
-  # want to send a request and receive a response, you should never need this -- a NebRequest
-  # returns a Message.
+  # You shouldn't ever need to instantiate this yourself.  For listening to messages and
+  # responding, use NebulousStomp::Listener.  For sending a message and waiting for a response, you
+  # want NebulousStomp::Request (passing it a NebulousStomp::Message).
   #
   class StompHandler
 
@@ -22,51 +22,6 @@ module NebulousStomp
     #
     class << self
 
-
-      ##
-      # Parse stomp headers & body and return body as something Ruby-ish.
-      # It might not be a hash, in fact -- it could be an array of hashes.
-      #
-      # We assume that you are getting this from a STOMP message; the routine
-      # might not work if it is passed something other than Stomp::Message
-      # headers.  
-      #
-      # If you have better intelligence as to the content type of the message,
-      # pass the content type as the optional third parameter.
-      #
-      def body_to_hash(headers, body, contentType=nil)
-        hdrs = headers || {}
-
-        raise ArgumentError, "headers is not a hash" \
-          unless hdrs.kind_of? Hash
-
-        type = contentType \
-               || hdrs["content-type"] || hdrs[:content_type] \
-               || hdrs["contentType"]  || hdrs[:contentType]
-
-        hash = nil
-
-        if type =~ /json$/i 
-          begin
-            hash = JSON.parse(body)
-          rescue JSON::ParserError, TypeError
-            hash = {}
-          end
-
-        else
-          # We assume that text looks like STOMP headers, or nothing
-          hash = {}
-          body.to_s.split("\n").each do |line|
-            k,v = line.split(':', 2).each{|x| x.strip! }
-            hash[k] = v
-          end
-
-        end
-
-        hash
-      end
-
-
       ##
       # :call-seq:
       #   StompHandler.with_timeout(secs) -> (nil)
@@ -79,17 +34,16 @@ module NebulousStomp
       #    r.signal
       #  end
       #
-      # Use `r.signal` to signal when the process has finished. You need to
-      # arrange your own method of working out whether the timeout fired or not.
+      # Use `r.signal` to signal when the process has finished. You need to arrange your own method
+      # of working out whether the timeout fired or not.
       #
-      # Also, please note that when the timeout period expires, your code will
-      # keep running. The timeout will only be honoured when your block
-      # completes. This is very useful for Stomp.subscribe, but probably not
-      # for anything else...
+      # Also, please note that when the timeout period expires, your code will keep running. The
+      # timeout will only be honoured when your block completes. This is very useful for
+      # Stomp.subscribe, but probably not for anything else...
       #
-      # There is a Ruby standard library for this, Timeout. But there appears to
-      # be some argument as to whether it is threadsafe; so, we roll our own. It
-      # probably doesn't matter since both Redis and Stomp do use Timeout. But.
+      # There is a Ruby standard library for this, Timeout. But there appears to be some argument
+      # as to whether it is threadsafe; so, we roll our own. It probably doesn't matter since both
+      # Redis and Stomp do use Timeout. But.
       #
       def with_timeout(secs)
         mutex    = Mutex.new
@@ -98,7 +52,6 @@ module NebulousStomp
         t = Thread.new do
           mutex.synchronize { yield resource }
         end
-
         mutex.synchronize { resource.wait(mutex, secs) }
 
         nil
@@ -111,18 +64,12 @@ module NebulousStomp
     ##
     # Initialise StompHandler by passing the parameter hash.
     #
-    # If no hash is set we try and get it from NebulousStomp::Param.
-    # ONLY set testClient when testing.
-    #
     def initialize(connectHash=nil, testClient=nil)
-      @stomp_hash   = connectHash ? connectHash.dup : nil
-      @stomp_hash ||= Param.get(:stompConnectHash)
-
+      @stomp_hash  = connectHash ? connectHash.dup : nil
       @test_client = testClient
       @client      = nil
     end
 
-
     ##
     # Connect to the STOMP client.
     #
@@ -131,20 +78,18 @@ module NebulousStomp
       NebulousStomp.logger.info(__FILE__) {"Connecting to STOMP"} 
 
       @client = @test_client || Stomp::Client.new( @stomp_hash )
-      raise ConnectionError, "Stomp Connection failed" unless connected?
+      fail ConnectionError, "Stomp Connection failed" unless connected?
 
       conn = @client.connection_frame()
       if conn.command == Stomp::CMD_ERROR
-        raise ConnectionError, "Connect Error: #{conn.body}"
+        fail ConnectionError, "Connect Error: #{conn.body}"
       end
 
       self
-
     rescue => err
       raise ConnectionError, err
     end
 
-
     ##
     # Drop the connection to the STOMP Client
     #
@@ -158,7 +103,6 @@ module NebulousStomp
       self
     end
 
-
     ##
     # return true if we are connected to the STOMP server
     #
@@ -166,7 +110,6 @@ module NebulousStomp
       @client && @client.open?
     end
 
-
     ##
     # return true if Nebulous is turned on in the parameters
     #
@@ -174,17 +117,19 @@ module NebulousStomp
       @stomp_hash && !@stomp_hash.empty?
     end
 
-
     ##
     # Block for incoming messages on a queue.  Yield each message.
     #
-    # Note that the blocking happens in a thread somewhere inside the STOMP
-    # client. I have no idea how to join that, and if the examples on the STOMP
-    # gem are to be believed, you flat out can't -- the examples just have the
-    # main thread sleeping so that it does not termimate while the thread is
-    # running.  So to use this make sure that you at some point do something
+    # This method automatically consumes every message it reads, since the assumption is that we
+    # are using it for the request-response use case.  If you don't want that, try
+    # listen_with_timeout(), instead.
+    #
+    # Note that the blocking happens in a thread somewhere inside the STOMP client. I have no idea
+    # how to join that, and if the examples on the STOMP gem are to be believed, you flat out can't
+    # -- the examples just have the main thread sleeping so that it does not termimate while the
+    # thread is running.  So to use this make sure that you at some point do something
     # like:
-    #     loop; sleep 5; end
+    #     loop { sleep 5 }
     #
     def listen(queue)
       return unless nebulous_on?
@@ -207,10 +152,9 @@ module NebulousStomp
 
     end
 
-
     ##
-    # As listen() but give up after yielding a single message, and only wait
-    # for a set number of seconds before giving up anyway.
+    # As listen() but give up after yielding a single message, and only wait for a set number of
+    # seconds before giving up anyway.
     #
     # The behaviour here is slightly different than listen(). If you return true from your block,
     # the message will be consumed and the method will end.  Otherwise it will continue until it
@@ -221,15 +165,10 @@ module NebulousStomp
     #
     def listen_with_timeout(queue, timeout)
       return unless nebulous_on?
-
-      NebulousStomp.logger.info(__FILE__) do
-        "Subscribing to #{queue} with timeout #{timeout}"
-      end
+      NebulousStomp.logger.info(__FILE__) { "Subscribing to #{queue} with timeout #{timeout}" }
 
       stomp_connect unless @client
-
       @client.publish( queue, "boo" )
-
       done = false
 
       StompHandler.with_timeout(timeout) do |resource|
@@ -258,16 +197,15 @@ module NebulousStomp
         resource.signal if done #or here. either, but.
       end # of with_timeout
 
-      raise NebulousTimeout unless done
+      fail NebulousTimeout unless done
     end
 
-
     ##
     # Send a Message to a queue; return the message.
     #
     def send_message(queue, mess)
       return nil unless nebulous_on?
-      raise NebulousStomp::NebulousError, "That's not a Message" \
+      fail NebulousStomp::NebulousError, "That's not a Message" \
         unless mess.respond_to?(:body_for_stomp) \
             && mess.respond_to?(:headers_for_stomp)
 
@@ -275,17 +213,15 @@ module NebulousStomp
 
       headers = mess.headers_for_stomp.reject{|k,v| v.nil? || v == "" }
       @client.publish(queue, mess.body_for_stomp, headers)
-
       mess
     end
 
-
     ##
     # Return the neb-reply-id we're going to use for this connection
     #
     def calc_reply_id
       return nil unless nebulous_on?
-      raise ConnectionError, "Client not connected" unless @client
+      fail ConnectionError, "Client not connected" unless @client
 
       @client.connection_frame().headers["session"] \
         << "_" \
@@ -293,9 +229,7 @@ module NebulousStomp
 
     end
 
-
-  end
-  ##
+  end # StompHandler
 
 
 end

data/lib/nebulous_stomp/stomp_handler_null.rb

@@ -10,85 +10,71 @@ module NebulousStomp
 
 
   ##
-  # Behaves just like StompHandler, except, does nothing and expects no stomp
-  # connection
+  # Behaves just like StompHandler, except, does nothing and expects no stomp connection
   #
   class StompHandlerNull < StompHandler
 
-    attr_reader :fake_mess
-
+    attr_reader :fake_messages
 
     def initialize(hash={})
       super(hash)
-      @fake_mess = nil
+      @fake_messages = []
     end
 
-
     def insert_fake(message)
-      @fake_mess = message
+      @fake_messages << message
     end
 
-
     def stomp_connect
       NebulousStomp.logger.info(__FILE__) {"Connecting to STOMP (Null)"} 
-
       @client = true
       self
     end
 
-
     def stomp_disconnect
       NebulousStomp.logger.info(__FILE__) {"STOMP Disconnect (Null)"}
       @client = nil
       self
     end
-
     
     def connected? 
-      @fake_mess != nil
+      @fake_messages != []
     end
 
-
     def listen(queue)
       NebulousStomp.logger.info(__FILE__) {"Subscribing to #{queue} (on Null)"}
-      yield @fake_mess
+      @fake_messages.each{|m| yield m }
     end
 
-
     def listen_with_timeout(queue, timeout)
       NebulousStomp.logger.info(__FILE__) {"Subscribing to #{queue} (on Null)"}
 
-      if @fake_mess
-        yield @fake_mess
+      if @fake_messages != []
+        @fake_messages.each{|m| yield m }
       else
         sleep timeout
         raise NebulousStomp::NebulousTimeout
       end
     end
 
-
     def send_message(queue, nebMess)
       nebMess
     end
 
-
     def respond_success(nebMess)
       NebulousStomp.logger.info(__FILE__) do 
         "Responded to #{nebMess} with 'success' verb (to Null)"
       end
     end
 
-
     def respond_error(nebMess,err,fields=[])
       NebulousStomp.logger.info(__FILE__) do
         "Responded to #{nebMess} with 'error' verb: #{err} (to Null)"
       end
     end
 
-
     def calc_reply_id; 'ABCD123456789'; end
 
-
   end
 
 

data/lib/nebulous_stomp/target.rb

@@ -0,0 +1,52 @@
+module NebulousStomp
+
+
+  ##
+  # Represents a single Target. Read only.
+  #
+  # NebulousStomp.add_target returns a Target, or you can retreive one from the config using
+  # NebulousStomp.get_target.
+  # 
+  class Target
+    #
+    # The identifying name of the queue
+    attr_reader :name
+
+    # The queue that the target sends responses to
+    attr_reader :send_queue
+    
+    # The queue that the target listens for requests on
+    attr_reader :receive_queue
+
+    # The message timeout for the queue
+    attr_reader :message_timeout
+
+    VALID_KEYS = %i|sendQueue receiveQueue messageTimeout name|
+
+    ##
+    # Create a target.
+    #
+    # Valid keys for the hash:
+    #
+    #     * :sendQueue
+    #     * :receiveQeue
+    #     * :name
+    #     * :messageTimeout (optional)
+    #
+    def initialize(hash)
+      fail ArgumentError, "Argument for Target.new must be a hash" unless hash.is_a? Hash
+
+      @send_queue      = hash[:sendQueue]    or fail ArgumentError, "Missing a sendQueue" 
+      @receive_queue   = hash[:receiveQueue] or fail ArgumentError, "Missing a receiveQueue"
+      @name            = hash[:name]         or fail ArgumentError, "Missing a name"
+      @message_timeout = hash[:messageTimeout]
+
+      bad_keys = hash.reject{|k, _| VALID_KEYS.include? k }.keys
+      fail ArgumentError, "Bad keys: #{bad_keys.join ' '}" unless bad_keys.empty?
+    end
+
+  end
+
+
+end
+

data/lib/nebulous_stomp/version.rb

@@ -1,5 +1,5 @@
 module NebulousStomp
 
   # Nebulous version number
-  VERSION = "2.0.2"
+  VERSION = "3.0.0"
 end