nebulous_stomp 1.1.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: bbf8f806ca67f277f05c1f79b35367b60ddca32e
+  data.tar.gz: fc74eef0d2815b4e71ea82416aec54d67805f2cc
+SHA512:
+  metadata.gz: 268e71ae7696273b5e02eeffdf6e16365c4f9b467fa7fec54f3f0a2454510312da99d9a08e136ff16d054dbc02cb9b828f5052ec2b7cf936f774460b6f377db4
+  data.tar.gz: 4a81d73c3bdc947cc3c0d6b4d59a94b780c56b18d6ece2685077d10ea5f98b94e523d9a3ad3becc96b3d96b83e4924a9d49ac8e8eaa472456a70d77f6f9c4f9f

data/.hgignore

@@ -0,0 +1,19 @@
+syntax: regexp
+
+^\.bundle/
+^Gemfile.lock
+^_yardoc/
+^coverage/
+^doc/
+^pkg/
+^spec/reports/
+^tmp/
+
+syntax: glob
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+.ruby-*
+.Project

data/.hgtags

@@ -0,0 +1,16 @@
+b3bba0a8b1f87257bd0ce2635483fa855f71185e 0.0.3
+40dd1093014ca0752093e5ab59080d88ed8ebd69 0.1.0
+90fdec53c9539cef35a51b9c45569097c6170037 1.0.0
+90fdec53c9539cef35a51b9c45569097c6170037 1.0.0
+0000000000000000000000000000000000000000 1.0.0
+0000000000000000000000000000000000000000 1.0.0
+6b772affe7030b28200354909dbd85cb81d4c161 1.0.0
+4c2c5c72dde17de6f99aa07c13627354d04fdb81 1.1.0
+9fff41d765e8ff837c0322024a8780e294c37945 1.1.1
+33554a6d9a5d9ef2891524f53603b49180a6112e 1.1.2
+fc012c81f38ba6c26f47caacd3f29eb27f7d28b1 1.1.3
+cff04defabb0895ff2f032087b97ea9616bee6a9 1.14
+cff04defabb0895ff2f032087b97ea9616bee6a9 1.14
+0000000000000000000000000000000000000000 1.14
+8ad003b30ff2d61d481343ba8d822ff2ffafaabb 1.1.4
+6ddf180c9a2fc1cef55f5d128faa4d5df28d1353 1.1.5

data/.rspec

@@ -0,0 +1,8 @@
+--color
+--require spec_helper
+#--require doc_no_pending
+--require nebulous
+-I .
+
+#--fail-fast
+#--format documentation

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 1.9.3

data/.yardoc/checksums

@@ -0,0 +1,10 @@
+lib/nebulous.rb abf6f1206a030a8af2e0baab1372b4a9b489c2d1
+lib/nebulous/param.rb 2d2f933b93717eebff5a539c0e0577aaed060093
+lib/nebulous/version.rb e7ad88512b8b20bc8a0e3254f5a10ed9cb58feb9
+lib/nebulous/message.rb cf705fae7bd51c78bb26835bb1b1bc8d142a4f9b
+lib/nebulous/nebrequest.rb 79dd0a25e6a05f352dd7cfa9e6398c95f68ae830
+lib/nebulous/redis_handler.rb 5c85af0402ba532f978794cb6cf2ce9076e5230c
+lib/nebulous/stomp_handler.rb 6d7e4cc0663948dc4cd10de9f570f745275be18a
+lib/nebulous/nebrequest_null.rb 5d2fc0f5c408a3d076005f8c13d5e56c6ac15259
+lib/nebulous/stomp_handler_null.rb aa8ece8831fb2bc5739746ef16de5fd7c0a2e6ff
+lib/nebulous/redis_handler_null.rb c9dbad237ddc70d6ff48a26f8c63939a5e0aeddd

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in nebulous.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,17 @@
+clearing :on
+
+guard :rspec, cmd: 'rspec' do
+
+  watch( %r{^lib/*(.+).rb$} ) do |m|
+    "spec/#{m[1]}_spec.rb"
+  end
+
+  watch( %r{^lib/nebulous/*(.+).rb$} ) do |m|
+    "spec/#{m[1]}_spec.rb"
+  end
+
+  watch( %r{^spec/*(.+).rb$} ) do |m|
+    "spec/#{m[1]}.rb"
+  end
+
+end

data/README.md

@@ -0,0 +1,38 @@
+Nebulous
+========
+
+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
+

data/Rakefile

@@ -0,0 +1,31 @@
+#require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require 'rdoc/task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+namespace :rdoc do
+  desc "Generate local docs"
+  RDoc::Task.new do |rdoc|
+    rdoc.main = "md/README.md"
+    rdoc.rdoc_files.include("lib/*", "md/*")
+    rdoc.rdoc_dir = "doc"
+  end
+
+  desc "Push doc to HARS"
+  task :hars do
+    sh "rsync -aP --delete doc/ /home/hars/hars/public/nebulous"
+  end
+end
+
+desc "Start Guard"
+task :guard do
+  sh "bundle exec guard"
+end
+
+desc "Update vim tag data"
+task :retag do
+  sh "ripper-tags -R"
+end
+
+

data/lib/nebulous/message.rb

@@ -0,0 +1,368 @@
+# COding: UTF-8
+
+require 'json'
+
+require_relative 'stomp_handler'
+
+
+module Nebulous
+
+
+  ## 
+  # A class to encapsulate a Nebulous message (which is built on top of a
+  # STOMP message)
+  #
+  # Note that this class REPLACES the old NebResponse class from 0.1.0. There
+  # are differences:
+  #     * response.body -> message.stomp_body
+  #     * response.headers -> message.stomp_headers
+  #     * to_cache now returns a Hash, not a JSON string
+  #
+  class Message
+
+    # Might be nil: parsed from incoming messages; set by StompHandler on send
+    attr_accessor :reply_id
+
+    # Might be nil: only caught on messages that came directly from STOMP
+    attr_reader :stomp_headers, :stomp_body
+    
+    # The content type of the message
+    attr_reader :content_type
+
+    # The Nebulous Protocol
+    # Note that if you happen to pass an array as @params, it's actually
+    # writable, which is not ideal.
+    attr_reader :verb, :params, :desc
+    attr_reader :reply_to, :in_reply_to 
+
+
+    class << self
+
+
+      ##
+      # Build a Message from its components.
+      #
+      # Note that we assume a content type of JSON. But if we are building a
+      # message by hand in Ruby, this is only reasonable.
+      #
+      # You must pass a verb; you can pass nil for all the other values.
+      #
+      # * replyTo - the queue to reply to if this is a Request
+      # * inReplyTo - the reply ID if this is a Response
+      # * verb, params, desc - The Protocol; the message to pass
+      #
+      def from_parts(replyTo, inReplyTo, verb, params, desc)
+        raise ArgumentError, "missing parts" unless verb
+
+        Nebulous.logger.debug(__FILE__){ "New message from parts" }
+
+        p = 
+          case params
+            when NilClass then nil
+            when Array    then params.dup
+            else params.to_s
+          end
+
+        self.new( replyTo:     replyTo.to_s,
+                  inReplyTo:   inReplyTo.to_s,
+                  verb:        verb.to_s,
+                  params:      p,
+                  desc:        desc.nil? ? nil : desc.to_s,
+                  contentType: 'application/json' )
+
+      end
+
+
+      ##
+      # Build a Message that replies to an existing Message
+      #
+      # * msg - the Nebulous::Message that you are replying to
+      # * verb, params, desc - the new message Protocol 
+      #
+      def in_reply_to(msg, verb, params=nil, desc=nil, replyTo=nil)
+        raise ArgumentError, 'bad message' unless msg.kind_of? Message
+
+        Nebulous.logger.debug(__FILE__){ "New message reply" }
+
+        p = 
+          case params
+            when NilClass then nil
+            when Array    then params.dup
+            else params.to_s
+          end
+
+        m = msg.clone
+        self.new( replyTo:     replyTo.to_s,
+                  verb:        verb.to_s,
+                  params:      p,
+                  desc:        desc.to_s,
+                  inReplyTo:   m.reply_id,
+                  contentType: m.content_type )
+
+      end
+      
+
+      ##
+      # Build a Message from a (presumably incoming) STOMP message
+      #
+      def from_stomp(stompMsg)
+        raise ArgumentError, 'not a stomp message' \
+          unless stompMsg.kind_of? Stomp::Message
+
+        Nebulous.logger.debug(__FILE__){ "New message from STOMP" }
+
+        s = Marshal.load( Marshal.dump(stompMsg) )
+        obj = self.new( stompHeaders: s.headers,
+                        stompBody:    s.body     )
+
+      end
+
+
+      ##
+      # To build a Nebmessage from a record in the Redis cache
+      #
+      # See #to_cache for details of the hash that Redis should be storing
+      # 
+      def from_cache(json)
+        raise ArgumentError, "That can't be JSON, it's not a string" \
+          unless json.kind_of? String
+
+        Nebulous.logger.debug(__FILE__){ "New message from cache" }
+
+        # Note that the message body at this point, for a JSON message, is
+        # actually encoded to JSON *twice* - the second time was when the cache
+        # hash as a whole was encoded for store in Redis. the JSON gem copes
+        # with this so long as the whole string is not double-encoded.
+        hash = JSON.parse(json, :symbolize_names => true)
+        raise ArgumentError, 'Empty cache entry' if hash == {}
+
+        # So now if the content type is JSON then the body is still JSON now.
+        # It's only the rest of the cache hash that is a now a hash. Confused?
+        # Now join us for this weeks' episode...
+        self.new( hash.clone )
+
+      rescue JSON::ParserError => err  
+        raise ArgumentError, "Bad JSON: #{err.message}"
+      end
+
+    end
+    ##
+
+
+    alias :parameters  :params
+    alias :description :desc
+
+
+    def to_s
+      "<Message[#{@reply_id}] to:#{@reply_to} r-to:#{@in_reply_to} " \
+        << "v:#{@verb}>"
+
+    end
+
+
+    ##
+    # true if the content type appears to be JSON-y
+    #
+    def content_is_json?
+      @content_type =~ /json$/i ? true : false
+    end
+
+
+    ##
+    # Output a hash for serialization to the cache.
+    #
+    # Currently this looks like:
+    #    { stompHeaders: @stomp_headers,
+    #      stompBody:    @stomp_body,
+    #      verb:         @verb,
+    #      params:       @params,
+    #      desc:         @desc,
+    #      replyTo:      @reply_to,
+    #      replyId:      @reply_id,
+    #      inReplyTo:    @in_reply_to,
+    #      contentType:  @content_type }
+    #
+    def to_cache
+      { stompHeaders: @stomp_headers,
+        stompBody:    @stomp_body,
+        verb:         @verb,
+        params:       @params.kind_of?(Enumerable) ? @params.dup : @params,
+        desc:         @desc,
+        replyTo:      @reply_to,
+        replyId:      @reply_id,
+        inReplyTo:    @in_reply_to,
+        contentType:  @content_type }
+
+    end
+
+
+    ##
+    # Return the hash of additional headers for the Stomp gem
+    #
+    def headers_for_stomp
+      headers = { "content-type" => @content_type, 
+                  "neb-reply-id" => @reply_id }
+
+      headers["neb-reply-to"]    = @reply_to    if @reply_to
+      headers["neb-in-reply-to"] = @in_reply_to if @in_reply_to
+
+      headers
+    end
+
+
+    ##
+    # Return a body object for the Stomp gem
+    #
+    def body_for_stomp
+      hash = protocol_hash
+
+      if content_is_json?
+        hash.to_json
+      else
+        hash.map {|k,v| "#{k}: #{v}" }.join("\n") << "\n\n"
+      end
+    end
+
+
+    ##
+    # :call-seq:
+    #   message.body_to_h -> (Hash || nil)
+    #
+    # If the body is in JSON, return a hash.
+    # If body is nil, or is not JSON, then return nil; don't raise an exception
+    #
+    def body_to_h
+      x = StompHandler.body_to_hash(stomp_headers, stomp_body, @content_type)
+      x == {} ? nil : x
+    end
+
+
+    ##
+    # Return the message body formatted for The Protocol, in JSON.
+    #
+    # Raise an exception if the message body doesn't follow the protocol.
+    #
+    # (We use this as the key for the Redis cache)
+    #
+    def protocol_json
+      raise NebulousError, "no protocol in this message!" unless @verb
+      protocol_hash.to_json
+    end
+
+
+    ##
+    # Make a new 'success verb' message in response to this one
+    #
+    # returns [queue, message] so you can just pass it to
+    # stomphandler.send_message.
+    #
+    def respond_success
+      raise NebulousError, "Don''t know who to reply to" unless @reply_to
+
+      Nebulous.logger.info(__FILE__) do
+        "Responded to #{self} with 'success' verb"
+      end
+
+      [ @reply_to, Message.in_reply_to(self, 'success') ]
+    end
+
+
+    ##
+    # Make a new 'error verb' message in response to this one
+    #
+    # err can be a string or an exception
+    #
+    # returns [queue, message] so you can just pass it to
+    # stomphandler.send_message.
+    #
+    def respond_error(err,fields=[])
+      raise NebulousError, "Don''t know who to reply to" unless @reply_to
+
+      Nebulous.logger.info(__FILE__) do
+        "Responded to #{self} with 'error': #{err}" 
+      end
+
+      reply = Message.in_reply_to(self, 'error', fields, err.to_s)
+
+      [ @reply_to, reply ]
+    end
+
+
+    private
+
+
+    ##
+    # Create a record -- note that you can't call this directly on the class;
+    # you have to call Message.from_parts, .from_stomp, .from_cache or
+    # .in_reply_to.
+    #
+    def initialize(hash)
+      @stomp_headers = hash[:stompHeaders]
+      @stomp_body    = hash[:stompBody]
+
+      @verb         = hash[:verb]
+      @params       = hash[:params]
+      @desc         = hash[:desc]
+      @reply_to     = hash[:replyTo]
+      @reply_id     = hash[:replyId]
+      @in_reply_to  = hash[:inReplyTo]
+      @content_type = hash[:contentType]
+
+      fill_from_message
+    end
+
+
+    ##
+    # Return The Protocol of the message as a hash.
+    #
+    def protocol_hash
+      h = {verb: @verb}
+      h[:parameters]  = @params unless @params.nil?
+      h[:description] = @desc   unless @desc.nil?
+
+      h
+    end
+
+
+    ##
+    # Fill all the other attributes, if you can, from @stomp_headers and
+    # @stomp_body.
+    #
+    def fill_from_message
+
+      if @stomp_headers
+        @content_type ||= @stomp_headers['content-type']
+        @reply_id     ||= @stomp_headers['neb-reply-id']
+        @reply_to     ||= @stomp_headers['neb-reply-to'] 
+        @in_reply_to  ||= @stomp_headers['neb-in-reply-to']
+      end
+
+      # decode the body, which should either be a JSON string or a series of
+      # text fields. And use the body to set Protocol attributes.
+      if @stomp_body && !@stomp_body.empty?
+
+        raise "body is not a string, something is very wrong here!" \
+          unless @stomp_body.kind_of? String
+
+        h = StompHandler.body_to_hash( @stomp_headers,
+                                       @stomp_body,
+                                       @content_type )
+
+        @verb   ||= h["verb"]
+        @params ||= h["parameters"]  || h["params"]
+        @desc   ||= h["description"] || h["desc"]
+
+        # Assume that if verb is missing, the other two are just part of a
+        # response which has nothing to do with the protocol
+        @params = @desc = nil unless @verb
+      end
+
+      self
+    end
+
+  end
+  ##
+
+
+end
+