stomper 0.3.0

data/lib/stomper/connection.rb

@@ -0,0 +1,176 @@
+module Stomper
+  # A low level connection to a Stomp message broker.
+  # Instances of Connection are not synchronized and thus not
+  # directly thread safe.  This is a deliberate decision as instances of
+  # Stomper::Client are the preferred way of communicating with
+  # Stomp message broker services.
+  class Connection
+    attr_reader :uri
+    attr_reader :socket
+
+    # Creates a new connection to the Stomp broker specified by +uri+.
+    # The +uri+ parameter may be either a URI object, or something that can
+    # be parsed by URI.parse, such as a string.
+    # Some examples of acceptable +uri+ forms include:
+    # [stomp:///] Connection will be made to 'localhost' on port 61613 with no login credentials.
+    # [stomp+ssl:///] Same as above, but connection will be made on port 61612 and wrapped by SSL.
+    # [stomp://user:pass@host.tld] Connection will be made to 'host.tld', authenticating as 'user' with a password of 'pass'.
+    # [stomp://user:pass@host.tld:86753] Connection will be made to 'host.tld' on port 86753, authenticating as above.
+    # [stomp://host.tld:86753] Connection will be made to 'host.tld' on port 86753, with no authentication.
+    #
+    # In order to wrap the connection with SSL, the schema of +uri+ must be 'stomp+ssl';
+    # however, if SSL is not required, the schema is essentially ignored.
+    # The default port for the 'stomp+ssl' schema is 61612, all other schemas
+    # default to port 61613.
+    #
+    # The +opts+ parameter is a hash of options, and can include:
+    #
+    # [:connect_now] Immediately connect to the broker when a new instance is created (default: true)
+    def initialize(uri, opts = {})
+      connect_now = opts.delete(:connect_now) { true }
+      @uri = (uri.is_a?(URI) && uri) || URI.parse(uri)
+      @uri.port = (@uri.scheme == "stomp+ssl") ? 61612 : 61613 if @uri.port.nil?
+      @uri.host = 'localhost' if @uri.host.nil?
+      @uri.freeze
+      @use_ssl = (@uri.scheme == "stomp+ssl")
+      if @use_ssl
+        @ssl_context = OpenSSL::SSL::SSLContext.new
+        @ssl_context.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      end
+      @connected = false
+      connect if connect_now
+    end
+
+
+    # Connects to the broker specified by the +uri+ attribute.
+    # By default, this method is invoked when a new Stomper::Connection
+    # is created.
+    #
+    # See also: new
+    def connect
+      s = TCPSocket.open(@uri.host, @uri.port)
+      if @use_ssl
+        s = OpenSSL::SSL::SSLSocket.new(s, @ssl_context)
+        s.sync_close = true
+        s.connect
+      end
+      @socket = s
+      transmit Stomper::Frames::Connect.new(@uri.user, @uri.password)
+      # Block until the first frame is received
+      connect_frame = receive(true)
+      @connected = connect_frame.instance_of?(Stomper::Frames::Connected)
+    end
+
+    # Returns true when there is an open connection
+    # established to the broker.
+    def connected?
+      # FIXME: @socket.eof? appears to block or otherwise "wonk out", not sure
+      # why yet.
+      #!(@socket.closed? || @socket.eof?)
+      @connected && @socket && !@socket.closed?
+    end
+
+    # Immediately closes the connection to the broker.
+    #
+    # See also: disconnect
+    def close
+      @socket.close
+    ensure
+      @connected = false
+    end
+
+    # Transmits a Stomper::Frames::Disconnect frame to the broker
+    # then terminates the connection by invoking +close+.
+    #
+    # See also: close
+    def disconnect
+      transmit(Stomper::Frames::Disconnect.new)
+    ensure
+      close
+    end
+
+    # Converts an instance of Stomper::Frames::ClientFrame into
+    # a string conforming to the Stomp protocol and sends it
+    # to the broker.
+    def transmit(frame)
+      @socket.write(frame.to_stomp)
+    end
+
+    # Receives a single Stomper::Frames::ServerFrame from the broker.
+    # If the frame received is known to the Stomper library, an instance of
+    # the appropriate subclass will be returned (eg: Stomper::Frames::Message),
+    # otherwise an instance of Stomper::Frames::ServerFrame is returned with
+    # the +command+ attribute set to the frame type.
+    # If the +blocking+ parameter is set to true, +receive+ will
+    # block until there is a frame available from the server, otherwise if no frame
+    # is currently available, +nil+ is returned.
+    #
+    # If an incoming message is malformed (not terminated with a NULL (\0)
+    # character, or has an incorrectly specified +content+-+length+ header,
+    # this method will raise an exception. [Type the exception, don't rely on
+    # a basic RuntimeError or whatever the default is.]
+    def receive(blocking=false)
+      command = ''
+      while (ready? || blocking) && (command = @socket.gets)
+        command.chomp!
+        break if command.size > 0
+      end
+      # If we got a command, continue on, potentially blocking until
+      # the entire message is received, otherwise we bail out now.
+      return nil if command.nil? || command.size == 0
+      headers = {}
+      while (line = @socket.gets)
+        line.chomp!
+        break if line.size == 0
+        delim = line.index(':')
+        if delim
+          key = line[0..(delim-1)]
+          val = line[(delim+1)..-1]
+          headers[key] = val
+        end
+      end
+      body = nil
+      # Have we been given a content length?
+      if headers['content-length']
+        body = @socket.read(headers['content-length'].to_i)
+        raise "Invalid message terminator or content-length header" if socket_c_to_i(@socket.getc) != 0
+      else
+        body = ''
+        # We read until we find the first nil character
+        while (c = @socket.getc)
+          # Both Ruby 1.8 and 1.9 should support this even though the behavior
+          # of getc is different between the two.  However, jruby is particular
+          # about this.  And that sucks.
+          break if socket_c_to_i(c) == 0
+          body << socket_c_to_chr(c)
+        end
+      end
+      # Messages should be forever immutable.
+      Stomper::Frames::ServerFrame.build(command, headers, body).freeze
+    end
+
+    private
+    def ready?
+      (@use_ssl) ? @socket.io.ready? : @socket.ready?
+    end
+
+    def socket_c_to_i(c)
+      if c.respond_to?(:ord)
+        def socket_c_to_i(char); char.ord; end
+        c.ord
+      else
+        def socket_c_to_i(char); char; end
+        c
+      end
+    end
+    def socket_c_to_chr(c)
+      if c.respond_to?(:chr)
+        def socket_c_to_chr(char); char.chr; end
+        c.chr
+      else
+        def socket_c_to_chr(char); char; end
+        c
+      end
+    end
+  end
+end

data/lib/stomper/frames.rb

@@ -0,0 +1,24 @@
+require 'stomper/frames/headers'
+require 'stomper/frames/client_frame'
+require 'stomper/frames/server_frame'
+require 'stomper/frames/abort'
+require 'stomper/frames/ack'
+require 'stomper/frames/begin'
+require 'stomper/frames/commit'
+require 'stomper/frames/connect'
+require 'stomper/frames/connected'
+require 'stomper/frames/disconnect'
+require 'stomper/frames/error'
+require 'stomper/frames/message'
+require 'stomper/frames/receipt'
+require 'stomper/frames/send'
+require 'stomper/frames/subscribe'
+require 'stomper/frames/unsubscribe'
+
+module Stomper
+  # This module holds all known encapsulations of
+  # frames that are part of the
+  # {Stomp Protocol Specification}[http://stomp.codehaus.org/Protocol]
+  module Frames
+  end
+end

data/lib/stomper/frames/abort.rb

@@ -0,0 +1,14 @@
+module Stomper
+  module Frames
+    # Encapsulates an "ACK" frame from the Stomp Protocol.
+    #
+    # See the {Stomp Protocol Specification}[http://stomp.codehaus.org/Protocol]
+    # for more details.
+    class Abort < Stomper::Frames::ClientFrame
+      def initialize(transaction_id, headers={})
+        super('ABORT', headers)
+        @headers.transaction = transaction_id
+      end
+    end
+  end
+end

data/lib/stomper/frames/ack.rb

@@ -0,0 +1,29 @@
+module Stomper
+  module Frames
+    # Encapsulates an "ACK" frame from the Stomp Protocol.
+    #
+    # See the {Stomp Protocol Specification}[http://stomp.codehaus.org/Protocol]
+    # for more details.
+    class Ack < Stomper::Frames::ClientFrame
+      def initialize(message_id, headers={})
+        super('ACK', headers)
+        @headers["message-id"] = message_id
+      end
+
+      # Creates a new Ack instance that corresponds to an acknowledgement
+      # of the supplied +message+, with any additional +headers+.  The
+      # +message+ parameter may be an instance of Stomper::Frames::Message, or
+      # a message id.  If +message+ is an instance of Stomper::Frames::Message
+      # and was exchanged as part of a transaction, the transaction header from
+      # +message+ will be injected into the newly created Ack object's headers.
+      def self.ack_for(message, headers = {})
+        if message.is_a?(Message)
+          headers['transaction'] = message.headers.transaction if message.headers.transaction
+          new(message.id, headers)
+        else
+          new(message.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/stomper/frames/begin.rb

@@ -0,0 +1,14 @@
+module Stomper
+  module Frames
+    # Encapsulates a "BEGIN" frame from the Stomp Protocol.
+    #
+    # See the {Stomp Protocol Specification}[http://stomp.codehaus.org/Protocol]
+    # for more details.
+    class Begin < Stomper::Frames::ClientFrame
+      def initialize(transaction_id, headers={})
+        super('BEGIN', headers)
+        @headers.transaction = transaction_id
+      end
+    end
+  end
+end

data/lib/stomper/frames/client_frame.rb

@@ -0,0 +1,86 @@
+module Stomper
+  module Frames
+    # Encapsulates a client side frame for the Stomp Protocol.
+    #
+    # See the {Stomp Protocol Specification}[http://stomp.codehaus.org/Protocol]
+    # for more details.
+    class ClientFrame
+      attr_reader :headers, :body, :command
+
+      # Creates a new ClientFrame instance with the specified +command+,
+      # +headers+ and +body+.
+      # If +headers+ includes a key of :generate_content_length, the
+      # associated value will determine if a 'content-length' header is automatically
+      # generated for this particular frame instance.  This key can be
+      # specified in the +headers+ parameter of any of the subclasses of ClientFrame,
+      # and it will be interpretted in the same fashion.
+      def initialize(command, headers={}, body=nil)
+        @command = command
+        @generate_content_length = headers.delete(:generate_content_length)
+        @headers = Headers.new(headers)
+        @body = body
+      end
+
+      # If +bool+ false or nil, this frame instance will not attempt to
+      # automatically generate a content-length header.  This is useful when
+      # dealing with ActiveMQ as a stomp message broker, which will treat incoming
+      # messages lacking a content-length header as +TextMessage+s and
+      # +BytesMessage+s if the header is present.  For more information see:
+      # {Apache ActiveMQ - Stomp}[http://activemq.apache.org/stomp.html]
+      def generate_content_length=(bool)
+        @generate_content_length=bool
+      end
+
+      # If generate_content_length= has been called on this instance, then the
+      # value supplied there is returned here.  Otherwise, we defer to the
+      # class method of the same name.
+      def generate_content_length?
+        @generate_content_length.nil? ? self.class.generate_content_length? : @generate_content_length
+      end
+
+      # Converts the frame instance into a valid string representation of the
+      # desired command according to the specifications of the
+      # {Stomp Protocol}[http://stomp.codehaus.org/Protocol]
+      #
+      # This is where the content-length header is generated if the frame
+      # has a body of non-zero length and generate_content_length? is true.
+      def to_stomp
+        @headers["content-length"] = str_size(@body) if @body && !@body.empty? && generate_content_length?
+        "#{@command}\n#{@headers.to_stomp}\n#{@body}\0"
+      end
+
+      class << self
+        # Sets a class level setting for determining if a content-length header
+        # should automatically be generated.
+        def generate_content_length=(bool)
+          @generate_content_length = bool
+        end
+
+        # Returns the value passed to the class level generate_content_length=
+        # method, or true if no value has been set (thus, defaults to true.)
+        #
+        # The precedence for resolving whether or not a content-length header
+        # is generated by the to_stomp method is: check the instance setting,
+        # if it has not been set, defer to the class setting, if it hasn't
+        # been set, default to true.
+        def generate_content_length?
+          if @generate_content_length.nil?
+            @generate_content_length = true
+          end
+          @generate_content_length
+        end
+      end
+
+      private
+      def str_size(str)
+        if str.respond_to?(:bytesize)
+          def str_size(strng); strng.bytesize; end
+          str.bytesize
+        else
+          def str_size(strng); strng.size; end
+          str.size
+        end
+      end
+    end
+  end
+end

data/lib/stomper/frames/commit.rb

@@ -0,0 +1,14 @@
+module Stomper
+  module Frames
+    # Encapsulates a "COMMIT" frame from the Stomp Protocol.
+    #
+    # See the {Stomp Protocol Specification}[http://stomp.codehaus.org/Protocol]
+    # for more details.
+    class Commit < Stomper::Frames::ClientFrame
+      def initialize(transaction_id, headers={})
+        super('COMMIT', headers)
+        @headers.transaction = transaction_id
+      end
+    end
+  end
+end

data/lib/stomper/frames/connect.rb

@@ -0,0 +1,15 @@
+module Stomper
+  module Frames
+    # Encapsulates a "CONNECT" frame from the Stomp Protocol.
+    #
+    # See the {Stomp Protocol Specification}[http://stomp.codehaus.org/Protocol]
+    # for more details.
+    class Connect < Stomper::Frames::ClientFrame
+      def initialize(username='', password='', headers={})
+        super('CONNECT', headers)
+        @headers.login = username
+        @headers.passcode = password
+      end
+    end
+  end
+end

data/lib/stomper/frames/connected.rb

@@ -0,0 +1,27 @@
+module Stomper
+  module Frames
+    # Encapsulates a "CONNECTED" server side frame for the Stomp Protocol.
+    #
+    # See the {Stomp Protocol Specification}[http://stomp.codehaus.org/Protocol]
+    # for more details.
+    class Connected < Stomper::Frames::ServerFrame
+      # This class is a factory for incoming 'CONNECTED' commands.
+      factory_for :connected
+
+      # Builds a Connected frame instance with the supplied
+      # +headers+ and +body+
+      def initialize(headers, body)
+        super('CONNECTED', headers, body)
+      end
+
+      # A convenience method that returns the value of
+      # the session header, if it is set.
+      #
+      # This value can also be accessed as:
+      # frame.headers.session or frame.headers['session'] or frame.headers[:session]
+      def session
+        @headers.session
+      end
+    end
+  end
+end

data/lib/stomper/frames/disconnect.rb

@@ -0,0 +1,13 @@
+module Stomper
+  module Frames
+    # Encapsulates a "DISCONNECT" frame from the Stomp Protocol.
+    #
+    # See the {Stomp Protocol Specification}[http://stomp.codehaus.org/Protocol]
+    # for more details.
+    class Disconnect < Stomper::Frames::ClientFrame
+      def initialize(headers={})
+        super('DISCONNECT', headers)
+      end
+    end
+  end
+end

data/lib/stomper/frames/error.rb

@@ -0,0 +1,26 @@
+module Stomper
+  module Frames
+    # Encapsulates an "ERROR" server side frame for the Stomp Protocol.
+    #
+    # See the {Stomp Protocol Specification}[http://stomp.codehaus.org/Protocol]
+    # for more details.
+    class Error < Stomper::Frames::ServerFrame
+      # This class is a factory for all incoming ERROR frames.
+      factory_for :error
+
+      # Creates a new Error frame with the supplied +headers+ and +body+
+      def initialize(headers, body)
+        super('ERROR', headers, body)
+      end
+
+      # Returns the message responsible for the generation of this Error frame,
+      # if applicable.
+      #
+      # This is a convenience method for:
+      # frame.headers[:message], frame.headers['message'], or frame.headers.message
+      def message
+        @headers.message
+      end
+    end
+  end
+end