nebulous_stomp 2.0.2 → 3.0.0

data/lib/nebulous_stomp.rb

@@ -6,48 +6,51 @@ require 'devnull'
 require 'nebulous_stomp/version'
 require 'nebulous_stomp/param'
 require 'nebulous_stomp/message'
-require 'nebulous_stomp/nebrequest'
+require 'nebulous_stomp/target'
+require 'nebulous_stomp/listener'
+require 'nebulous_stomp/request'
 require 'nebulous_stomp/stomp_handler'
 require 'nebulous_stomp/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.
+# NebulousStomp
+# =============
 #
-# There are two use cases:
+# A little module that implements The Nebulous Protocol, a way of passing data over STOMP between
+# different systems. Specifically, it allows you to send a message, a *Request*, and receive another
+# message in answer, a *Response*.  (Which is not something STOMP does, out of the box).
 #
-# 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.
+# This library covers two specific use cases (three if you are picky):
 #
-# 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.
+#     1) Request-Response: a program that consumes incoming messages, works out what message to
+#        send in response, and sends it.
 #
-# Some configuratuion is required: see Nebulous.init, Nebulous.add_target &
-# Nebulous.add_logger.
+#     2) Question-Answer: a program that sends a request and then waits for a response; the other
+#        end of the Request-Response use case. We support optional caching of responses in Redis,
+#        to speed things up if your program is likely to make the same request repeatedly within a
+#        short time.
 #
-# 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.
+#     3) Since we are talking to Redis, we expose a basic, simple interface for you to talk to it
+#        yourself.
 #
-# a complete list of classes & modules:
+# These are the externally-facing classes:
 #
-# * NebulousStomp
-# * NebulousStomp::Param
-# * NebulousStomp::NebRequest
-# * NebulousStomp::NebRequestNull
-# * NebulousStomp::Message
-# * NebulousStomp::StompHandler
-# * NebulousStomp::StompHandlerNull
-# * NebulousStomp::RedisHandler
-# * NebulousStomp::RedisHandlerNull
+#     * Listener      -- implements the request-response use case
+#     * Message       -- a Nebulous-Stomp message
+#     * NebulousStomp -- main class
+#     * RedisHelper   -- implements the Redis use case
+#     * Request       -- implements the Request-Response use case; a wrapper for Message
+#     * Target        -- represents a single Target
+#
+# These classes are used internally:
+#
+#     * Param            -- helper class to store and return configuration
+#     * RedisHandler     -- internal class to wrap the Redis gem
+#     * RedisHandlerNull -- a "mock" version of  RedisHandler for use in testing
+#     * StompHandler     -- internal class to wrap the Stomp gem
+#     * StompHandlerNull -- a "mock" version of StompHandler for use in testing
 #
-# If you want the null classes, you must require them seperately.
 module NebulousStomp
 
 
@@ -60,56 +63,67 @@ module NebulousStomp
   # Thrown when we can't connect to STOMP or the connection is lost somehow
   class ConnectionError < NebulousError; end
 
-
+  ##
   # :call-seq: 
-  # Nebulous.init(paramHash) -> (nil)
+  # NebulousStomp.init(paramHash) -> (nil)
   #
-  # Initialise library for use and override default options with any in
-  # <paramHash>.
+  # 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
+    nil
   end
 
-
+  ##
   # :call-seq: 
-  # Nebulous.add_target(name, targetHash) -> (nil)
+  # NebulousStomp.add_target(name, targetHash) -> Target
+  #
+  # Add a Nebulous target called <name> with a details as per <targetHash>.
   #
-  # 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
+  # raised. Have a look in NebulousStomp::Target for the default hash you are overriding here.
   #
-  # <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.
+  # Note that Param expects the target hash to have a :name key. We don't; we add it in.
   #
-  def self.add_target(name, targetHash) # -> nil
-    Param.add_target(name, targetHash)
-    return nil
+  def self.add_target(name, targetHash) 
+    t = NebulousStomp::Target.new targetHash.merge(name: name)
+    Param.add_target(t)
+    t
   end
 
+  ##
+  # :call-seq:
+  #   NebulousStomp.get_target(name) # -> Target
+  #
+  # Given a target name, return the Target object.
+  #
+  def self.get_target(name)
+    Param.get_target(name)
+  end
 
   ##
+  # :call-seq:
+  #   NebulousStomp.set_logger(Logger.new STDOUT)
+  #
   # 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" }
+  #   NebulousStomp.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.
+  # 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
@@ -121,7 +135,6 @@ module NebulousStomp
     !(h.nil? || h.empty?)
   end
 
-
   ##
   # :call-seq:
   #     Nebulous.redis_on? -> Boolean

data/md/LICENSE.txt

@@ -1,3 +1,21 @@
-Copyright (c) 2015 James Hall & Co Ltd
+The MIT License (MIT)
 
-Permission to use copy etc etc withheld. No-one is reading this, but.
+Copyright (c) 2016 Andrew Jones
+
+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/md/nebulous_protocol.md

@@ -6,8 +6,10 @@ Nebulous: The Protocol
 
 Introduction
 ------------
-Project Nebulous is a STOMP client written in ABL, and also the protocol that allows our different
-systems, ABL or not, to pass messages. This document, obviously, concentrates on the protocol.
+This document defines some specific rules of engagement for processes to communicate using STOMP.
+It so happens that NebulousStomp is currently the only open-source thing to use these rules -- I
+made them up -- but technically speaking, that's a "protocol", and I'm going to call it such
+because you can't stop me.
 
 The basic idea is this: one system passes a message, a _request_; and then waits for an answer to
 that message, a _response_, from another system. STOMP doesn't explicitly support that; the
@@ -20,7 +22,8 @@ message is both a response and a request, and the terms get rather less useful.)
 
 The Protocol
 ------------
-Let's start with the actual protocol, the rules. They won't make sense without reading the rest of the document, but:
+Let's start with the actual protocol, the rules. They won't make sense without reading the rest of
+the document, but:
 
 1. Every valid request (that is, every message with an identifiable verb other than "success" or
    "error") will always generate a response. If the handling routine cannot generate a valid
@@ -45,7 +48,7 @@ Let's start with the actual protocol, the rules. They won't make sense without r
 6. A given queue that is the target of requests within The Protocol will be for only one system or
    common group of systems. They may consume (ACK) messages sent to it even if they do not have the
    facility to process them.  If multiple systems share a queue, they should understand that
-   messages will be consumed from it at random.
+   messages will be consumed from it at random. (So, don't do that.)
 
 
 Components
@@ -74,9 +77,9 @@ The Protocol specifies a format for the message body. It consists of three field
 
 * _description_ is a text field and can contain anything. It is optional.
 
-Nebulous supports message bodies in either JSON (in which case parameters is probably an array) or
-plain text (in which case it expects to find the fields formatted in the same way as STOMP headers:
-seperated by line breaks, where each line consists of the field name, a colon, and the value).
+Nebulous supports message bodies in either JSON or plain text (in which case it expects to find the
+fields formatted in the same way as STOMP headers: seperated by line breaks, where each line
+consists of the field name, a colon, and the value).
 
 There are a couple of special verbs:
 
@@ -97,12 +100,11 @@ responses to be sent.
 
 ### Responder ###
 
-Let's talk about the Responder use case first, since it's simpler; we've basically been talking
-about it for the whole of this document. You'll need to designate a queue for incoming requests on
-any given system. You might want more than one; in ABL, where traffic jams are likely because I
-can't just spawn up a thread to handle each incoming message, my current thinking is to have two
-incoming queues, one for reqests that take a few seconds, and another for requests that take
-longer. 
+Let's talk about the Responder use case first, since it's simpler. On any given system, you'll need
+to designate a queue for incoming requests. You might want more than one. (In ABL, where traffic
+jams are likely because I can't just spawn up a thread to handle each incoming message, my current
+thinking is to have two incoming queues, one for reqests that take a few seconds, and another for
+requests that take longer.)
 
 Remember that rule 6 says that any messages that go to a queue like this will be consumed without
 concern for whether the message will make sense to the system in question; this is basically there
@@ -126,8 +128,8 @@ really falls outside of The Protocol.
 
 In theory, Rule 3 says you can fail to use _neb-reply-to_ and pick up your response from the same
 queue you posted the message to. But rule 6 says that if you do that you don't have any guarantee
-at all of getting your message; the Responder will take it. So for practical purposes you almost
-always *have* to set a reply-to queue in your request. 
+at all of getting your message; the Responder will take it. So for practical purposes you *have* to
+set a reply-to queue in your request. 
 
 Likewise, Rule 4 says that _neb-reply-id_ is optional. But in practice you should almost certainly
 set it. Yes, you can specify a brand new queue that is unique to your request -- or probably
@@ -145,14 +147,16 @@ avoiding consuming those messages that are not.
 For a unique reply-id you could do worse than starting with the session ID that STOMP returns when
 you send a CONNECT frame; clearly the message server thinks that is unique, and it should know. In
 the Ruby Stomp gem, you can get it with `client.connection_frame().headers["session"]` where client
-is your `Stomp::Client` instance; in my ABL jhstomp.p library call `get_session_id()`.
+is your `Stomp::Client` instance; in my ABL jhstomp.p library call `get_session_id()`. (This is how
+NebulousStomp does it.)
 
 Now that you have a good reply ID you can tell which is yours by Rule 4; just test the
 _neb-in-reply-to_ header of each message. 
 
 The second problem, of avoiding consuming messages that don't match your reply-id, is handled by
 careful use of STOMP. If when subscribing you set the header `ack:client-individual`, then you must
-manually acknowledge each message you want to consume with an ACK frame.
+manually acknowledge each message you want to consume with an ACK frame. (Again, how NebulousStomp
+does it.)
 
 Finally, you get to handle the response. Rule 1 says that it will either be an error verb, a
 success verb ... or something else specific to the verb. The nature of messages in responses is
@@ -163,5 +167,8 @@ enforce that.
 
 Note also that while The Protocol says that a request should always result in a response, there is
 nothing to say that the sender of the request should care -- say, in the example of a request that
-results in a report being emailed, which takes 20 minutes. 
+results in a report being emailed, which takes 20 minutes. In practice where that is the case I've
+been sending the success verb early, to say "yes, got your message, I see that it is valid -- don't
+wait up"; but the party that sends the message doesn't have to check it, since it's not very
+helpful.
 

data/spec/listener_spec.rb

@@ -0,0 +1,104 @@
+require 'nebulous_stomp/listener'
+require 'nebulous_stomp/stomp_handler_null'
+
+include NebulousStomp
+
+
+describe Listener do
+
+  let(:target1)   { Target.new(name: "foo", sendQueue: "alpha", receiveQueue: "beta") }
+  let(:listener1) { Listener.new(target1) }
+  let(:handler)   { StompHandlerNull.new }
+
+
+  describe "#new" do
+
+    it "should accept a queue name or a Target" do
+      expect{ Listener.new }.to raise_error ArgumentError
+
+      expect{ Listener.new target1 }.not_to raise_error
+      expect{ Listener.new "alpha" }.not_to raise_error
+    end
+
+  end
+
+
+  describe "#queue" do
+
+    it "should return the queue name when object was given one" do
+      expect( Listener.new("beta").queue ).to eq "beta"
+    end
+
+    it "should return Target.receive_queue when the object was given a target" do
+      expect( Listener.new(target1).queue ).to eq target1.receive_queue
+    end
+
+  end
+
+
+  describe "#stomp_handler" do
+
+    it "allows you to insert a stomp_handler object for test purposes" do
+      expect{ listener1.stomp_handler = handler }.not_to raise_exception
+      expect( listener1.send :stomp_handler ).to eq handler
+    end
+
+    it "defaults to StompHandler if none is inserted" do
+      expect( listener1.send(:stomp_handler).class ).to eq StompHandler
+    end
+
+  end
+
+
+  describe "#consume_messages" do
+
+    before do
+      listener1.stomp_handler = handler
+      handler.insert_fake "foo"
+      handler.insert_fake "bar"
+      handler.insert_fake "baz"
+    end
+     
+    it "should yield each message on the queue" do
+      expect{|b| listener1.consume_messages &b }.to yield_successive_args("foo", "bar", "baz")
+    end
+    
+  end
+
+
+  describe "#reply" do
+
+    before do
+      listener1.stomp_handler = handler
+    end
+
+    it "takes a queue name and a Message object" do
+      expect{ listener1.reply        }.to raise_error ArgumentError
+      expect{ listener1.reply("foo") }.to raise_error ArgumentError
+
+      expect{ listener1.reply("alpha", "foo") }.not_to raise_error
+    end
+
+    it "sends the message to its reply_to queue" do
+      expect( handler ).to receive(:send_message).with("beta", "bar").and_return("bar")
+
+      listener1.reply("beta", "bar")
+    end
+
+  end
+
+
+  describe "#quit" do
+     
+    it "calls StompHandler.stomp_disconnect" do
+      listener1.stomp_handler = handler
+      expect( handler ).to receive(:stomp_disconnect)
+      listener1.quit
+    end
+      
+    
+  end
+  
+
+end
+