onstomp 1.0.0pre1

data/lib/onstomp/components/threaded_processor.rb

@@ -0,0 +1,62 @@
+# -*- encoding: utf-8 -*-
+
+# An IO processor that does its work on its own thread. 
+class OnStomp::Components::ThreadedProcessor
+  # Creates a new processor for the {OnStomp::Client client}
+  # @param [OnStomp::Client] client
+  def initialize client
+    @client = client
+    @run_thread = nil
+  end
+  
+  # Returns true if its IO thread has been created and is alive, otherwise
+  # false.
+  # @return [true,false]
+  def running?
+    @run_thread && @run_thread.alive?
+  end
+
+  # Starts the processor by creating a new thread that continually invokes
+  # {OnStomp::Connections::Base#io_process} while the client is
+  # {OnStomp::Client#connected? connected}.
+  # @return [self]
+  def start
+    @run_thread = Thread.new do
+      begin
+        while @client.connected?
+          @client.connection.io_process
+        end
+      rescue OnStomp::StopReceiver
+      rescue Exception
+        raise
+      end
+    end
+    self
+  end
+  
+  # Causes the thread this method was invoked in to +pass+ until the
+  # processor is no longer {#running? running}.
+  # @return [self]
+  def join
+    Thread.pass while running?
+    @run_thread && @run_thread.join
+    self
+  end
+  
+  # Forcefully stops the processor and joins its IO thread to the
+  # callee's thread.
+  # @return [self]
+  # @raise [IOError, SystemCallError] if either were raised in the IO thread
+  #   and the {OnStomp::Client client} is still
+  #   {OnStomp::Client#connected? connected} after the thread is joined.
+  def stop
+    begin
+      @run_thread.raise OnStomp::StopReceiver if @run_thread.alive?
+      @run_thread.join
+    rescue IOError, SystemCallError
+      raise if @client.connected?
+    end
+    @run_thread = nil
+    self
+  end
+end

data/lib/onstomp/components/uri.rb

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+
+# Subclasses of URI::Generic to ease working with Stomp URIs.
+module OnStomp::Components::URI
+  # A URI class for representing URIs with a 'stomp' scheme.
+  class STOMP < ::URI::Generic
+    # The default port to use for these kinds of URI objects when none has
+    # been specified.
+    DEFAULT_PORT = 61613
+    # The type of socket to use with these kinds of URI objects.
+    # @return [:tcp]
+    def onstomp_socket_type; :tcp; end
+  end
+  
+  # A URI class for representing URIs with a 'stomp+ssl' scheme.
+  class STOMP_SSL < STOMP
+    # The default port to use for these kinds of URI objects when none has
+    # been specified.
+    DEFAULT_PORT = 61612
+    # The type of socket to use with these kinds of URI objects.
+    # @return [:ssl]
+    def onstomp_socket_type; :ssl; end
+  end
+end
+
+# Add the new URI classes to +URI+'s set of known schemes.
+module ::URI
+  @@schemes['STOMP'] = OnStomp::Components::URI::STOMP
+  @@schemes['STOMP+SSL'] = OnStomp::Components::URI::STOMP_SSL
+end

data/lib/onstomp/components.rb

@@ -0,0 +1,13 @@
+# -*- encoding: utf-8 -*-
+
+# Namespace for various components used by OnStomp library.
+module OnStomp::Components
+end
+
+require 'onstomp/components/uri'
+require 'onstomp/components/frame_headers'
+require 'onstomp/components/frame'
+require 'onstomp/components/subscription'
+require 'onstomp/components/nil_processor'
+require 'onstomp/components/threaded_processor'
+require 'onstomp/components/scopes'

data/lib/onstomp/connections/base.rb

@@ -0,0 +1,208 @@
+# -*- encoding: utf-8 -*-
+
+# Common behavior for all connections.
+class OnStomp::Connections::Base
+  include OnStomp::Interfaces::ConnectionEvents
+  attr_reader :version, :socket, :client
+  attr_reader :last_transmitted_at, :last_received_at
+  
+  # The approximate maximum number of bytes to write per call to
+  # {#io_process_write}.
+  MAX_BYTES_PER_WRITE = 1024 * 8
+  # The maximum number of bytes to read per call to {#io_process_read}
+  MAX_BYTES_PER_READ = 1024 * 4
+  
+  # Creates a new connection using the given {#socket} object and
+  # {OnStomp::Client client}. The {#socket} object will generally be a +TCPSocket+
+  # or an +OpenSSL::SSL::SSLSocket+ and must support the methods +read_nonblock+
+  # +write_nonblock+, and +close+.
+  # @param [TCPSocket,OpenSSL::SSL::SSLSocket] socket
+  # @param [OnStomp::Client] client
+  def initialize socket, client
+    @socket = socket
+    @write_mutex = Mutex.new
+    @closing = false
+    @write_buffer = []
+    @read_buffer = []
+    @client = client
+    @connection_up = false
+  end
+  
+  # Performs any necessary configuration of the connection from the CONNECTED
+  # frame sent by the broker and a +Hash+ of pending callbacks. This method
+  # is called after the protocol negotiation has taken place between client
+  # and broker, and the connection that receives it will be the connection
+  # used by the client for the duration of the session.
+  # @param [OnStomp::Components::Frame] connected
+  # @param [{Symbol => Proc}] con_cbs
+  def configure connected, con_cbs
+    @version = connected.header?(:version) ? connected[:version] : '1.0'
+    install_bindings_from_client con_cbs
+  end
+  
+  # Returns true if the socket has not been closed, false otherwise.
+  # @return [true,false]
+  def connected?
+    !socket.closed?
+  end
+  
+  # Closes the {#socket}. If +blocking+ is true, the socket will be closed
+  # immediately, otherwies the socket will remain open until {#io_process_write}
+  # has finished writing all of its buffered data. Once this method has been
+  # invoked, {#write_frame_nonblock} will not enqueue any additional frames
+  # for writing.
+  # @param [true,false] blocking
+  def close blocking=false
+    @write_mutex.synchronize { @closing = true }
+    if blocking
+      io_process_write until @write_buffer.empty?
+      socket.close
+    end
+  end
+  
+  # Exchanges the CONNECT/CONNECTED frame handshake with the broker and returns
+  # the version detected along with the received CONNECTED frame. The supplied
+  # list of headers will be merged into the CONNECT frame sent to the broker.
+  # @param [OnStomp::Client] client
+  # @param [Array<Hash>] headers
+  def connect client, *headers
+    write_frame_nonblock connect_frame(*headers)
+    client_con = nil
+    until client_con
+      io_process_write { |f| client_con ||= f }
+    end
+    broker_con = nil
+    until broker_con
+      io_process_read { |f| broker_con ||= f }
+    end
+    raise OnStomp::ConnectFailedError if broker_con.command != 'CONNECTED'
+    vers = broker_con.header?(:version) ? broker_con[:version] : '1.0'
+    raise OnStomp::UnsupportedProtocolVersionError, vers unless client.versions.include?(vers)
+    @connection_up = true
+    [ vers, broker_con ]
+  end
+  
+  # Checks if the missing method ends with '_frame', and if so raises a
+  # {OnStomp::UnsupportedCommandError} exception.
+  # @raise [OnStomp::UnsupportedCommandError]
+  def method_missing meth, *args, &block
+    if meth.to_s =~ /^(.*)_frame$/
+      raise OnStomp::UnsupportedCommandError, $1.upcase
+    else
+      super
+    end
+  end
+  
+  # Makes a single call to {#io_process_write} and a single call to
+  # {#io_process_read}
+  def io_process &cb
+    io_process_write &cb
+    io_process_read &cb
+    if @connection_up && !connected?
+      triggered_close :died
+    end
+  end
+  
+  # Serializes the given frame and adds the data to the connections internal
+  # write buffer
+  # @param [OnStomp::Components::Frame] frame
+  def write_frame_nonblock frame
+    ser = serializer.frame_to_bytes frame
+    push_write_buffer ser, frame
+  end
+  
+  # Adds data and frame pair to the end of the write buffer
+  # @param [String] data
+  # @param [OnStomp::Components::Frame]
+  def push_write_buffer data, frame
+    @write_mutex.synchronize {
+      @write_buffer << [data, frame] unless @closing
+    }
+  end
+  # Removes the first data and frame pair from the write buffer
+  # @param [String] data
+  # @param [OnStomp::Components::Frame]
+  def shift_write_buffer
+    @write_mutex.synchronize { @write_buffer.shift }
+  end
+  # Adds the remains of data and frame pair to the head of the write buffer
+  # @param [String] data
+  # @param [OnStomp::Components::Frame]
+  def unshift_write_buffer data, frame
+    @write_mutex.synchronize { @write_buffer.unshift [data, frame] }
+  end
+  
+  # Writes serialized frame data to the socket if the write buffer is not
+  # empty and socket is ready for writing. Once a complete frame has
+  # been written, this method will call {OnStomp::Client#dispatch_transmitted}
+  # to notify the client that the frame has been sent to the broker. If a
+  # complete frame cannot be written without blocking, the unsent data is
+  # sent to the head of the write buffer to be processed first the next time
+  # this method is invoked.
+  def io_process_write
+    if @write_buffer.length > 0 && IO.select(nil, [socket], nil, 0.1)
+      to_shift = @write_buffer.length / 3
+      written = 0
+      while written < MAX_BYTES_PER_WRITE
+        data, frame = shift_write_buffer
+        break unless data && connected?
+        begin
+          w = socket.write_nonblock(data)
+          written += w
+          @last_transmitted_at = Time.now
+          if w < data.length
+            unshift_write_buffer data[w..-1], frame
+          else
+            yield frame if block_given?
+            client.dispatch_transmitted frame
+          end
+        rescue Errno::EINTR, Errno::EAGAIN, Errno::EWOULDBLOCK
+          # writing will either block, or cannot otherwise be completed,
+          # put data back and try again some other day
+          unshift_write_buffer data, frame
+          break
+        rescue Exception
+          triggered_close :terminated
+          raise
+        end
+      end
+    end
+    if @write_buffer.empty? && @closing
+      triggered_close
+    end
+  end
+  
+  # Reads serialized frame data from the socket if we're connected and
+  # and the socket is ready for reading.  The received data will be pushed
+  # to the end of a read buffer, which is then sent to the connection's
+  # {OnStomp::Connections::Serializers serializer} for processing.
+  def io_process_read
+    if connected? && IO.select([socket], nil, nil, 0.1)
+      begin
+        data = socket.read_nonblock(MAX_BYTES_PER_READ)
+        @read_buffer << data
+        @last_received_at = Time.now
+        serializer.bytes_to_frame(@read_buffer) do |frame|
+          yield frame if block_given?
+          client.dispatch_received frame
+        end
+      rescue Errno::EINTR, Errno::EAGAIN, Errno::EWOULDBLOCK
+        # do not
+      rescue EOFError
+        triggered_close
+      rescue Exception
+        triggered_close :terminated
+        raise
+      end
+    end
+  end
+  
+  private
+  def triggered_close *evs
+    @connection_up = false
+    @closing = false
+    socket.close
+    evs.each { |ev| trigger_connection_event ev }
+    trigger_connection_event :closed
+  end
+end

data/lib/onstomp/connections/heartbeating.rb

@@ -0,0 +1,82 @@
+# -*- encoding: utf-8 -*-
+
+# Mixin for connections to include heartbeating functionality.
+module OnStomp::Connections::Heartbeating
+  # A pair of integers indicating the maximum number of milliseconds the
+  # client and broker can go without transmitting data respectively. If
+  # either value is 0, the respective heartbeating is not enabled.
+  # @return [[Fixnum, Fixnum]]
+  attr_reader :heartbeating
+  
+  # Configures heartbeating strategy by taking the maximum timeout
+  # for clients and brokers.  If either pair contains a zero, the respective
+  # beating is disabled.
+  # @param [[Fixnum, Fixnum]] client_beats
+  # @param [[Fixnum, Fixnum]] broker_beats
+  def configure_heartbeating client_beats, broker_beats
+    c_x, c_y = client_beats
+    s_x, s_y = broker_beats
+    @heartbeating = [ (c_x == 0||s_y == 0 ? 0 : [c_x,s_y].max), 
+      (c_y == 0||s_x == 0 ? 0 : [c_y,s_x].max) ]
+  end
+  
+  # Returns true if both the client and broker are transmitting data in
+  # accordance with the heartbeating strategy. If this method returns false,
+  # the connection is effectively dead and should be {OnStomp::Connections::Base#close closed}
+  # @return [true, false]
+  def pulse?
+    client_pulse? && broker_pulse?
+  end
+  
+  # Maximum number of milliseconds allowed between bytes being sent by
+  # the client, or 0 if there is no limit. This method will add a 10% margin
+  # of error to the timeout determined from heartbeat negotiation to allow a
+  # little slack before a connection is deemed 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 allowed between bytes being sent from
+  # the broker, or 0 if there is no limit. This method will add a 10% margin
+  # of error to the timeout determined from heartbeat negotiation to allow a
+  # little slack before a connection is deemed 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
+  
+  # Number of milliseconds since data was last transmitted to the broker or
+  # +nil+ if no data has been transmitted when the method is called.
+  # @return [Fixnum, nil]
+  def duration_since_transmitted
+    last_transmitted_at && ((Time.now - last_transmitted_at)*1000).to_i
+  end
+  
+  # Number of milliseconds since data was last received from the broker or
+  # +nil+ if no data has been received when the method is called.
+  # @return [Fixnum, nil]
+  def duration_since_received
+    last_received_at && ((Time.now - last_received_at)*1000).to_i
+  end
+
+  # Returns true if client-side heartbeating is disabled, or 
+  # {#duration_since_transmitted} has not exceeded {#heartbeat_client_limit}
+  # @return [true, false]
+  def client_pulse?
+    heartbeat_client_limit == 0 || duration_since_transmitted <= heartbeat_client_limit
+  end
+
+  # Returns true if broker-side heartbeating is disabled, or 
+  # {#duration_since_received} has not exceeded {#heartbeat_broker_limit}
+  # @return [true, false]
+  def broker_pulse?
+    heartbeat_broker_limit == 0 || duration_since_received <= heartbeat_broker_limit
+  end
+end

data/lib/onstomp/connections/serializers/stomp_1.rb

@@ -0,0 +1,166 @@
+# -*- encoding: utf-8 -*-
+
+# Classes that mix this in must define +split_header+ and +prepare_parsed_frame+
+# The method +frame_to_string_base+ is provided as a factoring out of the
+# common tasks of serializing a frame for STOMP 1.0 and STOMP 1.1.
+module OnStomp::Connections::Serializers::Stomp_1
+  # Resets the parser that converts byte strings to {OnStomp::Components::Frame frames}
+  def reset_parser
+    @parse_accum = ''
+    @cur_frame = nil
+    @parse_state = :command
+  end
+  
+  # The common elements of serializing a {OnStomp::Components::Frame frame}
+  # as a string in STOMP 1.0 and STOMP 1.1 protocols.
+  def frame_to_string_base frame
+    if frame.command
+      frame.force_content_length
+      str = "#{frame.command}\n"
+      frame.headers.inject(str) do |acc, (k,v)|
+        acc << yield(k,v)
+      end
+      str << "\n"
+      str << "#{frame.body}" if frame.body
+      str << "\000"
+      str
+    else
+      "\n"
+    end
+  end
+  
+  # Parses a {OnStomp::Components::Frame frame} command from the buffer
+  # @param [Array<String>] buffer
+  def parse_command buffer
+    data = buffer.shift
+    eol = data.index("\n")
+    if eol
+      parser_flush(buffer, data, eol, :finish_command)
+    else
+      @parse_accum << data
+    end
+  end
+  
+  # Parses a {OnStomp::Components::Frame frame} header line from the buffer
+  # @param [Array<String>] buffer
+  def parse_header_line buffer
+    data = buffer.shift
+    eol = data.index("\n")
+    if eol
+      parser_flush(buffer, data, eol, :finish_header_line)
+    else
+      @parse_accum << data
+    end
+  end
+  
+  # Parses a {OnStomp::Components::Frame frame} body from the buffer
+  # @param [Array<String>] buffer
+  def parse_body buffer
+    data = buffer.shift
+    if rlen = @cur_frame.content_length
+      rlen -= @parse_accum.length
+    end
+    body_upto = rlen ? (rlen < data.length && rlen) : data.index("\000")
+    if body_upto
+      if data[body_upto, 1] != "\000"
+        raise OnStomp::MalformedFrameError, 'missing terminator'
+      end
+      parser_flush(buffer, data, body_upto, :finish_body)
+    else
+      @parse_accum << data
+    end
+  end
+  
+  # Adds the substring +data[0...idx]+ to the parser's accumulator,
+  # unshifts the remaining data back onto the buffer, and calls +meth+
+  # with the parser's accumulated string.
+  # @param [Array<String>] buffer
+  # @param [String] data
+  # @param [Fixnum] idx
+  # @param [Symbol] meth
+  def parser_flush buffer, data, idx, meth
+    remain = data[(idx+1)..-1]
+    buffer.unshift(remain) unless remain.empty?
+    __send__ meth, (@parse_accum + data[0...idx])
+    @parse_accum = ''
+  end
+  
+  # Called when a frame's command has been fully read from the buffer. This
+  # method will create a new "current frame", set its
+  # {OnStomp::Components::Frame#command command} attribute, and tell the parser
+  # to move on to the next state.
+  # @param [String] command
+  def finish_command command
+    @cur_frame = OnStomp::Components::Frame.new
+    if command.empty?
+      @parse_state = :completed
+    else
+      @cur_frame.command = command
+      @parse_state = :header_line
+    end
+  end
+  
+  # Called when a header line has been fully read from the buffer. This
+  # method will split the header line into a name/value pair,
+  # {OnStomp::Components::FrameHeaders#append append} the
+  # header to the "current frame" and tell the parser to move on to the next
+  # state
+  # @param [String] headline
+  def finish_header_line headline
+    if headline.empty?
+      @parse_state = :body
+    else
+      k,v = split_header(headline)
+      @cur_frame.headers.append(k, v)
+    end
+  end
+  
+  # Called when a frame's body has been fully read from the buffer. This
+  # method will set the frame's {OnStomp::Components::Frame#body body}
+  # attribute, call +prepare_parsed_frame+ with the "current frame",
+  # and tell the parser to move on to the next state.
+  # @param [String] body
+  def finish_body body
+    @cur_frame.body = body
+    prepare_parsed_frame @cur_frame
+    @parse_state = :completed
+  end
+  
+  # Takes a buffer of strings and constructs all the
+  # {OnStomp::Components::Frame frames} it can from the data. The parser
+  # builds a "current frame" and updates it with attributes as they are
+  # parsed from the buffer. It is only safe to invoke this method from a
+  # single thread as no synchronization is being performed. This will work
+  # fine with the {OnStomp::Components::ThreadedProcessor threaded} processor
+  # as it performs its calls all within a single thread, but if you wish
+  # to develop your own processor that can call
+  # {OnStomp::Connections::Base#io_process_read} across separate threads, you
+  # will have to implement your own synchronization strategy.
+  # @note It is NOT safe to invoke this method from multiple threads as-is.
+  # @param [Array<String>] buffer
+  def bytes_to_frame buffer
+    until buffer.first.nil? && @parse_state != :completed
+      if @parse_state == :completed
+        yield @cur_frame
+        reset_parser
+      else
+        __send__(:"parse_#{@parse_state}", buffer)
+      end
+    end
+  end
+  
+  if RUBY_VERSION >= "1.9"
+    # Takes the result of +frame_to_string+ and forces it to use a binary
+    # encoding
+    # @return [String] string serialization of frame with 'ASCII-8BIT' encoding
+    def frame_to_bytes frame
+      frame_to_string(frame).tap { |s| s.force_encoding('ASCII-8BIT') }
+    end
+  else
+    # Takes the result of +frame_to_string+ and passes it along. Ruby 1.8.7
+    # treats strings as a collection of bytes, so we don't need to do any
+    # further work.
+    # @return [String]
+    def frame_to_bytes(frame); frame_to_string(frame); end
+  end
+end

data/lib/onstomp/connections/serializers/stomp_1_0.rb

@@ -0,0 +1,41 @@
+# -*- encoding: utf-8 -*-
+
+# Frame serializer / parser for STOMP 1.0 connections.
+class OnStomp::Connections::Serializers::Stomp_1_0
+  include OnStomp::Connections::Serializers::Stomp_1
+  
+  # Creates a new serializer and calls {#reset_parser}
+  def initialize
+    reset_parser
+  end
+
+  # Converts a {OnStomp::Components::Frame frame} to a string
+  # @param [OnStomp::Components::Frame] frame
+  # @return [String]
+  def frame_to_string frame
+    frame_to_string_base(frame) do |k,v|
+      "#{k.gsub(/[\n:]/, '')}:#{v.gsub(/\n/, '')}\n"
+    end
+  end
+  
+  # Splits a header line into a header name / header value pair at the first
+  # ':' character and returns the pair.
+  # @param [String] str header line to split
+  # @return [[String, String]]
+  # @raise [OnStomp::MalformedHeaderError] if the header line
+  #   lacks a ':' character
+  def split_header(str)
+    col = str.index(':')
+    unless col
+      raise OnStomp::MalformedHeaderError, "unterminated header: '#{str}'"
+    end
+    [ str[0...col], str[(col+1)..-1] ]
+  end
+  
+  # Nothing special needs to be done with frames parsed from a STOMP 1.0
+  # connection, so this is a no-op.
+  # @param [OnStomp::Components::Frame] frame
+  # @return [nil]
+  def prepare_parsed_frame frame
+  end
+end