nebulous_stomp 1.1.5

data/lib/nebulous/stomp_handler.rb

@@ -0,0 +1,290 @@
+# COding: UTF-8
+
+require 'stomp'
+require 'json'
+require 'time'
+
+
+module Nebulous
+
+
+  ##
+  # A Class to deal with talking to STOMP via the Stomp gem
+  #
+  class StompHandler
+
+    attr_reader :client
+
+
+    ##
+    # Class methods
+    #
+    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)
+      #
+      # Run a routine with a timeout.
+      #
+      # Example:
+      #  StompHandler.with_timeout(10) do |r|
+      #    sleep 20
+      #    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.
+      #
+      # 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.
+      #
+      def with_timeout(secs)
+        mutex    = Mutex.new
+        resource = ConditionVariable.new
+
+        t = Thread.new do
+          mutex.synchronize { yield resource }
+        end
+
+        mutex.synchronize { resource.wait(mutex, secs) }
+
+        nil
+      end
+
+    end
+    ##
+
+
+    ##
+    # Initialise StompHandler by passing the parameter hash.
+    # ONLY set testClient when testing.
+    #
+    def initialize(connectHash, testClient=nil)
+      @stomp_hash  = connectHash ? connectHash.dup : nil
+      @test_client = testClient
+      @client      = nil
+    end
+
+
+    ##
+    # Connect to the STOMP client.
+    #
+    def stomp_connect
+      return self unless nebulous_on?
+      Nebulous.logger.info(__FILE__) {"Connecting to STOMP"} 
+
+      @client = @test_client || Stomp::Client.new( @stomp_hash.dup )
+      raise ConnectionError, "Stomp Connection failed" unless connected?
+
+      conn = @client.connection_frame()
+      if conn.command == Stomp::CMD_ERROR
+        raise ConnectionError, "Connect Error: #{conn.body}"
+      end
+
+      self
+
+    rescue => err
+      raise ConnectionError, err
+    end
+
+
+    ##
+    # Drop the connection to the STOMP Client
+    #
+    def stomp_disconnect
+      if @client
+        Nebulous.logger.info(__FILE__) {"STOMP Disconnect"}
+        @client.close if @client
+        @client = nil
+      end
+
+      self
+    end
+
+
+    ##
+    # return true if we are connected to the STOMP server
+    #
+    def connected?
+      @client && @client.open?
+    end
+
+
+    ##
+    # return true if Nebulous is turned on in the parameters
+    #
+    def nebulous_on?
+      @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
+    # like:
+    #     loop; sleep 5; end
+    #
+    def listen(queue)
+      return unless nebulous_on?
+      Nebulous.logger.info(__FILE__) {"Subscribing to #{queue}"}
+
+      stomp_connect unless @client
+
+      # Startle the queue into existence. You can't subscribe to a queue that
+      # does not exist, BUT, you can create a queue by posting to it...
+      @client.publish( queue, "boo" )
+
+      @client.subscribe( queue, {ack: "client-individual"} ) do |msg|
+        begin
+          @client.ack(msg)
+          yield Message.from_stomp(msg) unless msg.body == 'boo'
+        rescue =>e
+          Nebulous.logger.error(__FILE__) {"Error during polling: #{e}" }
+        end
+      end
+
+    end
+
+
+    ##
+    # As listen() but give up after yielding a single message, and only wait
+    # for a set number of seconds before giving up anyway.
+    #--
+    # Ideally I'd like to DRY this and listen() up, but with this
+    # yield-within-a-thread stuff going on, I'm actually not sure how to do
+    # that safely.
+    #
+    # Actually i'm not even sure how to stop once I've read one message. The
+    # Stomp gem behaves very strangely.
+    #++
+    #
+    def listen_with_timeout(queue, timeout)
+      return unless nebulous_on?
+
+      Nebulous.logger.info(__FILE__) do
+        "Subscribing to #{queue} with timeout #{timeout}"
+      end
+
+      stomp_connect unless @client
+
+      @client.publish( queue, "boo" )
+
+      done = false
+
+      StompHandler.with_timeout(timeout) do |resource|
+        @client.subscribe( queue, {ack: "client-individual"} ) do |msg|
+
+          begin
+            if msg.body == 'boo'
+              @client.ack(msg)
+            elsif done == false
+              yield Message.from_stomp(msg) 
+              done = true
+            end
+          rescue =>e
+            Nebulous.logger.error(__FILE__) {"Error during polling: #{e}" }
+          end
+
+        end # of Stomp client subscribe block
+
+        # Not that this seems to do any good when the Stomp gem is in play, but.
+        resource.signal if done
+
+      end # of with_timeout
+
+      raise NebulousTimeout unless done
+    end
+
+
+    ##
+    # Send a Message to a queue; return the message.
+    #
+    def send_message(queue, mess)
+      return nil unless nebulous_on?
+      raise Nebulous::NebulousError, "That's not a Message" \
+        unless mess.respond_to?(:body_for_stomp) \
+            && mess.respond_to?(:headers_for_stomp)
+
+      stomp_connect unless @client
+      @client.publish(queue, mess.body_for_stomp, mess.headers_for_stomp)
+      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
+
+      @client.connection_frame().headers["session"] \
+        << "_" \
+        << Time.now.to_f.to_s
+
+    end
+
+
+  end
+  ##
+
+
+end
+

data/lib/nebulous/stomp_handler_null.rb

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

data/lib/nebulous/version.rb

@@ -0,0 +1,5 @@
+module Nebulous
+
+  # Nebulous version number
+  VERSION = "1.1.5"
+end

data/lib/nebulous.rb

@@ -0,0 +1,140 @@
+# coding: UTF-8
+
+require 'stomp'
+require 'redis'
+require 'logger'
+require 'devnull'
+
+require 'nebulous/version'
+require 'nebulous/param'
+require 'nebulous/message'
+require 'nebulous/nebrequest'
+require 'nebulous/stomp_handler'
+require 'nebulous/redis_handler'
+
+
+##
+# A little module that implements the Nebulous Protocol, a way of passing data
+# over STOMP between different systems. We also support message cacheing via
+# Redis.
+#
+# There are two use cases:
+#
+# First, sending a request for information and waiting for a response, which
+# might come from a cache of previous responses, if you allow it. To do
+# this you should create a Nebulous::NebRequest, which will return a
+# Nebulous::Message.
+#
+# Second, the other end of the deal: hanging around waiting for requests and
+# sending responses. To do this, you need to use the Nebulous::StompHandler
+# class, which will again furnish Nebulous::Meessage objects, and allow you to
+# create them.
+#
+# Some configuratuion is required: see Nebulous.init, Nebulous.add_target &
+# Nebulous.add_logger.
+#
+# Since you are setting the Redis connection details as part of initialisation,
+# you can also use it to connect to Redis, if you want. See
+# Nebulous::RedisHandler.
+#
+# a complete list of classes & modules:
+#
+# * Nebulous
+# * Nebulous::Param
+# * Nebulous::NebRequest
+# * Nebulous::NebRequestNull
+# * Nebulous::Message
+# * Nebulous::StompHandler
+# * Nebulous::StompHandlerNull
+# * Nebulous::RedisHandler
+# * Nebulous::RedisHandlerNull
+#
+# If you want the null classes, you must require them seperately.
+module Nebulous
+
+
+  # Thrown when anything goes wrong.
+  class NebulousError < StandardError; end
+
+  # Thrown when nothing went wrong, but a timeout expired.
+  class NebulousTimeout < StandardError; end
+
+  # Thrown when we can't connect to STOMP or the connection is lost somehow
+  class ConnectionError < NebulousError; end
+
+
+  # :call-seq: 
+  # Nebulous.init(paramHash) -> (nil)
+  #
+  # Initialise library for use and override default options with any in
+  # <paramHash>.
+  #
+  # The default options are defined in Nebulous::Param.
+  #
+  def self.init(paramHash={}) 
+    Param.set(paramHash)
+    return nil
+  end
+
+
+  # :call-seq: 
+  # Nebulous.add_target(name, targetHash) -> (nil)
+  #
+  # Add a nebulous target called <name> with a details as per <targetHash>.
+  #
+  # <targetHash> must contain a send queue and a receive queue, or a
+  # NebulousError will be thrown. Have a look in Nebulous::Param for the
+  # default hash you are overriding here.
+  #
+  def self.add_target(name, targetHash) # -> nil
+    Param.add_target(name, targetHash)
+    return nil
+  end
+
+
+  ##
+  # Set an instance of Logger to log stuff to.
+  def self.set_logger(logger)
+    Param.set_logger(logger)
+  end
+
+
+  ##
+  # :call-seq:
+  #   Nebulous.logger.info(__FILE__) { "message" }
+  #
+  # Return a Logger instance to log things to.
+  # If one was not given to Param, return a logger instance that
+  # uses a DevNull IO object, that is, goes nowhere.
+  #
+  def self.logger
+    Param.get_logger || Logger.new( DevNull.new )
+  end
+
+
+  ##
+  # :call-seq:
+  #     Nebulous.on? -> Boolean
+  #
+  # True if Nebulous is configured to be running
+  #
+  def self.on?
+    h = Param.get(:stompConnectHash)
+    !(h.nil? || h.empty?)
+  end
+
+
+  ##
+  # :call-seq:
+  #     Nebulous.redis_on? -> Boolean
+  #
+  # True if the Redis cache is configured to be running
+  #
+  def self.redis_on?
+    h = Param.get(:redisConnectHash)
+    !(h.nil? || h.empty?)
+  end
+
+
+end
+

data/md/LICENSE.txt

@@ -0,0 +1,3 @@
+Copyright (c) 2015 James Hall & Co Ltd
+
+Permission to use copy etc etc withheld. No-one is reading this, but.