stomper 1.0.0 → 2.0.0

data/lib/stomper/extensions/heartbeat.rb

@@ -0,0 +1,101 @@
+# -*- encoding: utf-8 -*-
+
+# Provides the heart-beating interface for a {Stomper::Connection} object.
+module Stomper::Extensions::Heartbeat
+  # Extends an object with any additional modules that are appropriate
+  # for the Stomp protocol being used.
+  def self.extend_by_protocol_version(instance, version)
+    if EXTEND_BY_VERSION[version]
+      EXTEND_BY_VERSION[version].each do |mod|
+        instance.extend mod
+      end
+    end
+  end
+  
+  # By default, this method does nothing. If the established connection
+  # utilizes the Stomp 1.1 protocol, this method will be overridden by
+  # {Stomper::Protocols::V1_1::Heartbeating#beat}.
+  def beat; end
+
+  # By default, a connection is alive if it is connected.
+  # If the established connection utilizes the Stomp 1.1 protocol, this
+  # method will be overridden by {Stomper::Protocols::V1_1::Heartbeating#alive?}.
+  # @return [true,false]
+  # @see #dead?
+  def alive?
+    connected?
+  end
+
+  # A {Stomper::Connection connection} is dead if it is not +alive?+
+  # @return [true, false]
+  # @see #alive?
+  def dead?
+    !alive?
+  end
+  
+  # Stomp Protocol 1.1 extensions to the heart-beating interface
+  module V1_1
+    # Send a heartbeat to the broker
+    def beat
+      transmit ::Stomper::Frame.new
+    end
+
+    # Stomp 1.1 {Stomper::Connection connections} are alive if they are
+    # +connected?+ and are meeting their negotiated heart-beating obligations.
+    # @return [true, false]
+    # @see #dead?
+    def alive?
+      connected? && client_alive? && broker_alive?
+    end
+    
+    # Maximum number of milliseconds that can pass between frame / heartbeat
+    # transmissions before we consider the client to be dead.
+    # @return [Fixnum]
+    def heartbeat_client_limit
+      unless defined?(@heartbeat_client_limit)
+        @heartbeat_client_limit = heartbeating[0] > 0 ? (1.1 * heartbeating[0]) : 0
+      end
+      @heartbeat_client_limit
+    end
+    
+    # Maximum number of milliseconds that can pass between frames / heartbeats
+    # received before we consider the broker to be dead.
+    # @return [Fixnum]
+    def heartbeat_broker_limit
+      unless defined?(@heartbeat_broker_limit)
+        @heartbeat_broker_limit = heartbeating[1] > 0 ? (1.1 * heartbeating[1]) : 0
+      end
+      @heartbeat_broker_limit
+    end
+    
+    # Returns true if the client is alive. Client is alive if client heartbeating
+    # is disabled, or the number of milliseconds that have passed since last
+    # transmission is less than or equal to {#heartbeat_client_limit client} limit
+    # @return [true,false]
+    # @see #heartbeat_client_limit
+    # @see #broker_alive?
+    def client_alive?
+      # Consider some benchmarking to determine if this is faster than
+      # re-writing the method after its first invocation.
+      heartbeat_client_limit == 0 ||
+        duration_since_transmitted <= heartbeat_client_limit
+    end
+    
+    # Returns true if the broker is alive. Broker is alive if broker heartbeating
+    # is disabled, or the number of milliseconds that have passed since last
+    # receiving is less than or equal to {#heartbeat_broker_limit broker} limit
+    # @return [true,false]
+    # @see #heartbeat_broker_limit
+    # @see #client_alive?
+    def broker_alive?
+      heartbeat_broker_limit == 0 ||
+        duration_since_received <= heartbeat_broker_limit
+    end
+  end
+  
+  # A mapping between protocol versions and modules to include
+  EXTEND_BY_VERSION = {
+    '1.0' => [ ],
+    '1.1' => [ ::Stomper::Extensions::Heartbeat::V1_1 ]
+  }
+end

data/lib/stomper/extensions/scoping.rb

@@ -0,0 +1,56 @@
+# -*- encoding: utf-8 -*-
+
+# Provides the scoping interface for a {Stomper::Connection} object.
+module Stomper::Extensions::Scoping
+  # Creates a new {Stomper::Scopes::TransactionScope} to perform
+  # a transaction. If a block is provided, all SEND, ACK, NACK, COMMIT and
+  # ABORT frames generated within the block are bound to the same transaction.
+  # Further, if an exception is raised within the block, the transaction is
+  # rolled back through an ABORT frame, otherwise it is automatically committed
+  # through a COMMIT frame. If a block is not provided, the transaction must
+  # be manually aborted or committed through the returned
+  # {Stomper::Scopes::TransactionScope} object.
+  # @param [{Symbol => Object}] headers
+  # @yield [tx] block is evaluated as a transaction
+  # @yieldparam [Stomper::Scopes::TransactionScope] tx
+  # @return [Stomper::Scopes::TransactionScope]
+  # @example Gonna need an example or two
+  def with_transaction(headers={}, &block)
+    create_scope(::Stomper::Scopes::TransactionScope, headers, block)
+  end
+
+  # Creates a new {Stomper::Scopes::ReceiptScope} using
+  # a supplied block as the receipt handler. If no block is provided, no
+  # receipt handler is created; however, all frames generated through this
+  # {Stomper::Scopes::ReceiptScope} will still request a RECEIPT
+  # from the broker.
+  # @param [{Symbol => Object}] headers
+  # @yield [receipt] callback invoked upon receiving the RECEIPT frame
+  # @yieldparam [Stomper::Frame] the received RECEIPT frame
+  # @return [Stomper::Scopes::ReceiptScope]
+  # @example Gonna need an example or two
+  # @see Stomper::Extensions::Events#on_receipt}
+  def with_receipt(headers={}, &block)
+    create_scope(::Stomper::Scopes::ReceiptScope, headers, block)
+  end
+  
+  # Creates a new {Stomper::Scopes::HeaderScope} from the
+  # supplied hash of headers. If a block is provided, it will be invoked with
+  # with this {Stomper::Scopes::HeaderScope} as its only parameter.
+  # @param [{Symbol => Object}] headers
+  # @yield [header_scope] block is evaluated applying the specified headers to
+  #   all frames generated within the block.
+  # @yieldparam [Stomper::Scopes::HeaderScope] header_scope
+  # @return [Stomper::Scopes::HeaderScope]
+  # @example Gonna need an example or two
+  def with_headers(headers, &block)
+    create_scope(::Stomper::Scopes::HeaderScope, headers, block)
+  end
+  
+  def create_scope(klass, headers, callback)
+    klass.new(self, headers).tap do |scoped|
+      scoped.apply_to(callback)
+    end
+  end
+  private :create_scope
+end

data/lib/stomper/frame.rb

@@ -0,0 +1,54 @@
+# -*- encoding: utf-8 -*-
+
+# A generic encapsulation of a frame as specified by the Stomp protocol.
+class Stomper::Frame
+  # The command name of this frame (CONNECTED, SEND, RECEIPT, etc.)
+  # @return [String]
+  attr_accessor :command
+  
+  # The body of this frame
+  # @return [String] if a body has been set
+  attr_accessor :body
+  
+  # The headers associated with this frame
+  # @return [Stomper::Headers]
+  attr_reader :headers
+  
+  # Creates a new frame. The frame will be initialized with the optional
+  # +command+ name, a {Stomper::Headers headers} collection initialized
+  # with the optional +headers+ hash, and an optional body.
+  def initialize(command=nil, headers={}, body=nil)
+    @command = command
+    @headers = ::Stomper::Headers.new(headers)
+    @body = body
+  end
+  
+  # Gets the header value paired with the supplied name.  This is a convenient
+  # shortcut for `frame.headers[name]`.
+  #
+  # @param [Object] name the header name associated with the desired value
+  # @return [String] the value associated with the requested header name
+  # @see Stomper::Headers#[]
+  # @example
+  #   frame['content-type'] #=> 'text/plain'
+  def [](name); @headers[name]; end
+  
+  # Sets the header value paired with the supplied name.  This is a convenient
+  # shortcut for `frame.headers[name] = val`.
+  #
+  # @param [Object] name the header name to associate with the supplied value
+  # @param [Object] val the value to associate with the supplied header name
+  # @return [String] the supplied value as a string, or `nil` if `nil` was supplied as the value.
+  # @see Stomper::Headers#[]=
+  # @example
+  #   frame['content-type'] = 'text/plain' #=> 'text/plain'
+  #   frame['other header'] = 42 #=> '42'
+  def []=(name, val); @headers[name] = val; end
+  
+  # A convenience method for getting the 'content-type' header without
+  # any parameters.
+  # @return [String]
+  def content_type
+    @headers[:'content-type'] && @headers[:'content-type'].split(';').first || ''
+  end
+end

data/lib/stomper/frame_serializer.rb

@@ -0,0 +1,217 @@
+# -*- encoding: utf-8 -*-
+
+# This class serializes Stomp frames to IO streams. Submodule mixins within
+# this class are used to adjust the serialization behavior depending upon
+# the Stomp Protocol version being used.
+# @see Stomper::Support::Ruby1_8::FrameSerializer Implementation for Ruby 1.8.7
+# @see Stomper::Support::Ruby1_9::FrameSerializer Implementation for Ruby 1.9
+class Stomper::FrameSerializer
+  # The character that must be present at the end of every Stomp frame.
+  FRAME_TERMINATOR = "\000"
+  
+  # Creates a new frame serializer that will read {Stomper::Frame frames} from
+  # and write {Stomper::Frame frames} to the supplied IO object (typically
+  # a TCP or SSL socket.)
+  # @param [IO] io IO stream to read from and write to
+  def initialize(io)
+    @io = io
+    @write_mutex = ::Mutex.new
+    @read_mutex = ::Mutex.new
+  end
+  
+  # Extends the serializer based on the version of the protocol being used.
+  # @param [String] version protocol version being used
+  # @return [self]
+  def extend_for_protocol(version)
+    if EXTEND_BY_VERSION[version]
+      EXTEND_BY_VERSION[version].each { |m| extend m }
+    end
+    self
+  end
+  
+  # Serializes and writes a {Stomper::Frame} to the underlying IO stream. This
+  # includes setting the appropriate values for 'content-length' and
+  # 'content-type' headers, if applicable.
+  # @param [Stomper::Frame] frame
+  # @return [Stomper::Frame] the frame that was passed to the method
+  def write_frame(frame)
+    @write_mutex.synchronize { __write_frame__(frame) }
+  end
+  
+  # Deserializes and returns a {Stomper::Frame} read from the underlying IO
+  # stream. If the IO stream produces data that violates the Stomp protocol
+  # specification, an instance of {Stomper::Errors::FatalProtocolError}, or
+  # one of its subclasses, will be raised.
+  # @return [Stomper::Frame]
+  # @raise [Stomper::Errors::MalformedFrameError] if the frame is not properly terminated
+  # @raise [Stomper::Errors::MalformedHeaderError] if a header is malformed (eg: contains no ':' separator)
+  def read_frame
+    @read_mutex.synchronize { __read_frame__ }
+  end
+  
+  # Converts the headers of the supplied frame into a single "\n" delimited
+  # string that's suitable for writing to io.
+  # @param [Stomper::Frame] frame the frame whose headers should be serialized
+  # @return [String]
+  def serialize_headers(frame)
+    serialized = frame.headers.inject('') do |head_str, (k, v)|
+      k = escape_header_name(k)
+      next head_str if k.empty? || ['content-type', 'content-length'].include?(k)
+      head_str << "#{k}:#{escape_header_value(v)}\n"
+    end
+    if frame.body
+      if ct = determine_content_type(frame)
+        serialized << "content-type:#{ct}\n"
+      end
+      if clen = determine_content_length(frame)
+        serialized << "content-length:#{clen}\n"
+      end
+    end
+    serialized
+  end
+  
+  # Escape a header name to comply with Stomp Protocol 1.0 specifications.
+  # All LF ("\n") and ":" characters are replaced with empty strings.
+  # @note If the connection is using the 1.1 protocol, this method will
+  #   be overridden by {FrameSerializer::V1_1#escape_header_name}
+  # @param [String] str
+  # @return [String] escaped header name
+  def escape_header_name(str)
+    str.gsub(/[\n:]/, '')
+  end
+  
+  # Escape a header value to comply with Stomp Protocol 1.0 specifications.
+  # All LF ("\n") characters are replaced with empty strings.
+  # @note If the connection is using the 1.1 protocol, this method will
+  #   be overridden by {FrameSerializer::V1_1#escape_header_value}
+  # @param [String] str
+  # @return [String] escaped header value
+  def escape_header_value(str)
+    str.gsub(/\n/, '')
+  end
+  
+  # Return the header name as it was passed. Stomp 1.0 does not provide
+  # any means for escaping special characters such as ":" and "\n"
+  # @note If the connection is using the 1.1 protocol, this method will
+  #   be overridden by {FrameSerializer::V1_1#unescape_header_name}
+  # @param [String] str
+  # @return [String]
+  def unescape_header_name(str); str; end
+  alias :unescape_header_value :unescape_header_name
+  
+  private
+  # These are the un-synchronized methods that do the real reading/writing
+  # of frames. This approach facilitates easier testing of Thread safety
+  def __write_frame__(frame)
+    if frame.command
+      @io.write [frame.command, "\n", serialize_headers(frame),
+        "\n", frame.body, FRAME_TERMINATOR].compact.join
+    else
+      @io.write "\n"
+    end
+    frame
+  end
+  def __read_frame__
+    command = @io.gets
+    return nil if command.nil?
+    command.chomp!
+    frame = Stomper::Frame.new
+    unless command.nil? || command.empty?
+      frame.command = command
+    
+      while (header_line = get_header_line.chomp).length > 0
+        raise ::Stomper::Errors::MalformedHeaderError,
+          "unterminated header: '#{header_line}'" unless header_line.include? ':'
+        k, v = header_line.split(':', 2)
+        frame.headers.append(unescape_header_name(k), unescape_header_value(v))
+      end
+    
+      body = nil
+      if frame[:'content-length'] && (len = frame[:'content-length'].to_i) > 0
+        body = @io.read len
+        raise ::Stomper::Errors::MalformedFrameError, "frame was not properly terminated" if get_body_byte
+      else
+        while (c = get_body_byte)
+          body ||= ""
+          body << c
+        end
+      end
+      frame.body = body && encode_body(body, frame[:'content-type'])
+    end
+    frame
+  end
+  
+  # Stomp Protocol 1.1 specific frame writing / reading methods.
+  module V1_1
+    # Mapping of characters to their appropriate escape sequences. This
+    # is used when escaping headers for frames being written to the stream.
+    CHARACTER_ESCAPES = {
+      ':' => "\\c",
+      "\n" => "\\n",
+      "\\" => "\\\\"
+    }
+    
+    # Mapping of escape sequences to their appropriate characters. This
+    # is used when unescaping headers being read from the stream.
+    ESCAPE_SEQUENCES = {
+      'c' => ':',
+      '\\' => "\\",
+      'n' => "\n"
+    }
+    
+    # Escape a header name to comply with Stomp Protocol 1.1 specifications.
+    # All special characters (the keys of {CHARACTER_ESCAPES}) are replaced
+    # by their corresponding escape sequences.
+    # @param [String] str
+    # @return [String] escaped header name
+    def escape_header_name(hdr)
+      hdr.each_char.inject('') do |esc, ch|
+        esc << (CHARACTER_ESCAPES[ch] || ch)
+      end
+    end
+    alias :escape_header_value :escape_header_name
+    
+    # Return the header name after known escape sequences have been
+    # translated to their respective values. The keys of {ESCAPE_SEQUENCES},
+    # prefixed with a '\' character, denote the allowed escape sequences.
+    # If an unknown escape sequence is encountered, an error is raised.
+    # @param [String] str header string to unescape
+    # @return [String] unescaped header string
+    # @raise [Stomper::Errors::InvalidHeaderEscapeSequenceError] if an
+    #   unknown escape sequence is encountered within the string or if
+    #   an escape sequence is not properly completed (the last character of
+    #   +str+ is '\')
+    def unescape_header_name(str)
+      state = :read
+      str.each_char.inject('') do |unesc, ch|
+        case state
+        when :read
+          if ch == '\\'
+            state = :unescape
+          else
+            unesc << ch
+          end
+        when :unescape
+          state = :read
+          if ESCAPE_SEQUENCES[ch]
+            unesc << ESCAPE_SEQUENCES[ch]
+          else
+            raise ::Stomper::Errors::InvalidHeaderEscapeSequenceError,
+              "invalid header escape sequence encountered '\\#{ch}'"
+          end
+        end
+        unesc
+      end.tap do
+        raise ::Stomper::Errors::InvalidHeaderEscapeSequenceError,
+          "incomplete escape sequence encountered in '#{str}'" if state != :read
+      end
+    end
+    alias :unescape_header_value :unescape_header_name
+  end
+  
+  # The modules to mix-in to {FrameSerializer} instances depending upon which
+  # protocol version is being used.
+  EXTEND_BY_VERSION = {
+    '1.1' => [ ::Stomper::FrameSerializer::V1_1 ]
+  }
+end

data/lib/stomper/headers.rb

@@ -0,0 +1,15 @@
+# -*- encoding: utf-8 -*-
+
+# A specialized container for storing header name / value pairs for a Stomp
+# {Stomper::Frame Frame}.  This container behaves much like a +Hash+, but
+# is specialized for the Stomp protocol.  Header names are always converted
+# into +String+s through the use of +to_s+ and may have more than one value
+# associated with them.
+#
+# @note Header names are case sensitive, therefore the names 'header'
+#   and 'Header' will not refer to the same values.
+# @see Stomper::Support::Ruby1_8::Headers Implementation for Ruby 1.8.7
+# @see Stomper::Support::Ruby1_9::Headers Implementation for Ruby 1.9
+class Stomper::Headers
+  include ::Enumerable
+end