stomper 1.0.0 → 2.0.0

data/lib/stomper/receipt_manager.rb

@@ -0,0 +1,36 @@
+# -*- encoding: utf-8 -*-
+
+# Manages receipt handling for a {Stomper::Connection}
+class Stomper::ReceiptManager
+  # Creates a new receipt handler for the supplied {Stomper::Connection connection}
+  # @param [Stomper::Connection] connection
+  def initialize(connection)
+    @mon = ::Monitor.new
+    @callbacks = {}
+    connection.before_disconnect do |d, con|
+      @close_on = d[:receipt] if d[:receipt]
+    end
+    connection.on_receipt do |r, con|
+      dispatch(r)
+      connection.close if r[:'receipt-id'] == @close_on
+    end
+  end
+  
+  # Adds a callback handler for a RECEIPT frame that matches the supplied
+  # receipt ID.
+  # @param [String] r_id ID of the receipt to match
+  # @param [Proc] callback Proc to invoke when a matching RECEIPT frame is
+  #   received from the broker.
+  # @return [self]
+  def add(r_id, callback)
+    @mon.synchronize { @callbacks[r_id] = callback }
+    self
+  end
+  
+  private
+  def dispatch(receipt)
+    cb = @mon.synchronize { @callbacks.delete(receipt[:'receipt-id']) }
+    cb && cb.call(receipt)
+    self
+  end
+end

data/lib/stomper/receivers.rb

@@ -0,0 +1,7 @@
+# -*- encoding: utf-8 -*-
+
+# Namespace for {Stomper::Connection} receivers
+module Stomper::Receivers
+end
+
+require 'stomper/receivers/threaded'

data/lib/stomper/receivers/threaded.rb

@@ -0,0 +1,71 @@
+# -*- encoding: utf-8 -*-
+
+# Basic threaded receiver
+class Stomper::Receivers::Threaded
+  # Returns true if the receiver is currently running, false otherwise.
+  # If the polling thread is terminated due to a raised exception, this
+  # attribute will be false.
+  # @return [true,false]
+  attr_reader :running
+  alias :running? :running
+  
+  # Creates a new threaded receiver for the supplied {Stomper::Connection}.
+  # Invoking {#start} on this receiver will create a new thread that will
+  # continually call {Stomper::Connection#receive receive} on the
+  # {Stomper::Connection connection}. Stopping this receiver with {#stop}
+  # will terminate the thread.
+  # @param [Stomper::Connection] connection
+  def initialize(connection)
+    @connection = connection
+    @running = false
+    @run_mutex = ::Mutex.new
+    @run_thread = nil
+    @raised_while_running = nil
+  end
+  
+  # Starts the receiver by creating a new thread to continually poll the
+  # {Stomper::Connection connection} for new Stomp frames. If an error is
+  # raised while calling {Stomper::Connection#receive}, the polling thread
+  # will terminate, and {#running?} will return false.
+  # @return [self]
+  def start
+    is_starting = @run_mutex.synchronize { @running = true unless @running }
+    if is_starting
+      @run_thread = Thread.new do
+        while @running
+          begin
+            @running = false if @connection.receive.nil?
+          rescue Exception => ex
+            @running = false
+            raise ex
+          end
+        end
+      end
+    end
+    self
+  end
+  
+  # Stops the receiver by shutting down the polling thread. If an error was
+  # raised within the thread, this method will generally re-raise the error.
+  # The one exception to this behavior is if the error raised was an instance
+  # of +IOError+ and a call to {Stomper::Connection#connected?} returns false,
+  # in which case the error is ignored. The reason for this is that performing
+  # a read operation on a closed stream will raise an +IOError+. It is likely
+  # that when shutting down a connection and its receiver, the polling thread
+  # may be blocked on reading from the stream and raise such an error.
+  # @return [self]
+  # @raise [Exception]
+  def stop
+    stopped = @run_mutex.synchronize { @run_thread.nil? }
+    unless stopped
+      @running = false
+      begin
+        @run_thread.join
+      rescue IOError
+        raise if @connection.connected?
+      end
+      @run_thread = nil
+    end
+    self
+  end
+end

data/lib/stomper/scopes.rb

@@ -0,0 +1,9 @@
+# -*- encoding: utf-8 -*-
+
+# Module containing connection scopes.
+module Stomper::Scopes
+end
+
+require 'stomper/scopes/header_scope'
+require 'stomper/scopes/receipt_scope'
+require 'stomper/scopes/transaction_scope'

data/lib/stomper/scopes/header_scope.rb

@@ -0,0 +1,49 @@
+# -*- encoding: utf-8 -*-
+
+# A "connection scope" that provides much of the same interface as 
+# {Stomper::Connection}, but automatically applies header name/value pairs
+# to all frames generated on the scope.
+class ::Stomper::Scopes::HeaderScope
+  include ::Stomper::Extensions::Common
+
+  # The underlying {Stomper::Connection connection} to transmit frames through.
+  # @return [Stomper::Connection]
+  attr_reader :connection
+  # The headers to apply to all frames generated on this scope.
+  # @return [{Symbol => String}]
+  attr_reader :headers
+  
+  # Creates a new {Stomper::Scopes::HeaderScope}.  The supplied +headers+ hash will have
+  # all of its keys converted to symbols and its values converted to strings,
+  # so the key/value pairs must support this transformation (through +to_sym+
+  # and +to_s+, respectively.)
+  # @param [Stomper::Connection] connection
+  # @param [{Object => String}] headers
+  def initialize(connection, headers)
+    @headers = ::Stomper::Support.keys_to_sym(headers)
+    @connection = connection
+    ::Stomper::Extensions::Common.extend_by_protocol_version(self, @connection.version)
+  end
+  
+  # Applies this scope to a block.
+  def apply_to(callback)
+    callback.call(self) if callback
+  end
+  
+  # Transmits a frame, applying the set headers. After merging its headers
+  # into the frame, the frame is passed to the underlying connection for
+  # transmission.
+  # @param [Stomper::Frame] frame
+  def transmit(frame)
+    frame.headers.reverse_merge!(@headers)
+    @connection.transmit frame
+  end
+  
+  # Returns the connection's {Stomper::ReceiptManager}
+  # @return [Stomper::ReceiptManager]
+  def receipt_manager; @connection.receipt_manager; end
+  
+  # Returns the connection's {Stomper::SubscriptionManager}
+  # @return [Stomper::SubscriptionManager]
+  def subscription_manager; @connection.subscription_manager; end
+end

data/lib/stomper/scopes/receipt_scope.rb

@@ -0,0 +1,44 @@
+# -*- encoding: utf-8 -*-
+
+# Automatically generates "receipt" headers, if none are present and
+# applies a supplied callback to every receipt received for frames generated
+# through it. As instances of this class rely on event callbacks attached
+# to the underlying {Stomper::Connection connection}, it is entirely possible
+# for those events to be triggered on +Thread+ other than main. It is for
+# this reason that synchronization is used to ensure the integrity of
+# the internal list of receipt IDs that have not yet been processed through
+# the callback.
+class Stomper::Scopes::ReceiptScope < ::Stomper::Scopes::HeaderScope
+  # A list of frames that support being receipted.
+  # @return [Array<String>]
+  FRAME_COMMANDS = %w(SEND SUBSCRIBE UNSUBSCRIBE
+    BEGIN COMMIT ABORT ACK NACK DISCONNECT)
+  
+  # Create a new receipt scope. All receiptable frames transmitted through
+  # this instance will use the same callback for handling the RECEIPT frame
+  # sent by the broker.
+  def initialize(connection, headers)
+    super
+    @receipt_handler = nil
+  end
+  
+  # Takes a block as a callback to invoke when a receipt is received.
+  def apply_to(callback)
+    @receipt_handler = callback
+  end
+  
+  # Transmits a frame. This method will add an auto-generated +receipt+ header
+  # to the frame if one has not been set, and then set up a handler for the
+  # +receipt+ value, invoking the callback set through {#apply_to} when
+  # the corresponding RECEIPT frame is received from the broker.
+  # @param [Stomper::Frame] frame
+  def transmit(frame)
+    if @receipt_handler && FRAME_COMMANDS.include?(frame.command)
+      r_id = frame[:receipt]
+      r_id = ::Stomper::Support.next_serial if r_id.nil? || r_id.empty?
+      receipt_manager.add(r_id, @receipt_handler)
+      frame[:receipt] = r_id
+    end
+    super(frame)
+  end
+end

data/lib/stomper/scopes/transaction_scope.rb

@@ -0,0 +1,109 @@
+# -*- encoding: utf-8 -*-
+
+# A "connection scope" that provides a convenient interface for handling
+# transactions. In addition to the behaviors of {HeaderScope}, for frames
+# that the Stomp protocol allows to be enclosed within a transaction, this
+# scope automatically attaches a +transaction+ header.
+class Stomper::Scopes::TransactionScope < ::Stomper::Scopes::HeaderScope
+  # A list of frames that support being part of a transaction.
+  # @return [Array<String>]
+  FRAME_COMMANDS = %w(SEND BEGIN COMMIT ABORT ACK NACK)
+  # The value assigned to the +transaction+ header.
+  # @return [String]
+  attr_reader :transaction
+  
+  def initialize(connection, headers)
+    super
+    @headers[:transaction] ||= ::Stomper::Support.next_serial
+    @transaction = self.headers[:transaction]
+    @transaction_state = :pending
+  end
+  
+  # Overrides the standard {Stomper::Extensions::Commmon#begin} behavior
+  # to start the transaction encapsulated by this {TransactionScope transaction}.
+  def begin_with_transaction(headers={})
+    if transaction_pending?
+      @transaction_state = :starting
+    else
+      raise ::Stomper::Errors::TransactionStartedError unless transaction_pending?
+    end
+    begin_without_transaction(@transaction, headers).tap do |f|
+      @transaction_state = :started
+    end
+  end
+  alias :begin_without_transaction :begin
+  alias :begin :begin_with_transaction
+  
+  # Overrides the standard {Stomper::Extensions::Commmon#abort} behavior
+  # to abort the transaction encapsulated by this {TransactionScope transaction}.
+  def abort_with_transaction(headers={})
+    abort_without_transaction(@transaction, headers).tap do |f|
+      @transaction_state = :aborted
+    end
+  end
+  alias :abort_without_transaction :abort
+  alias :abort :abort_with_transaction
+  
+  # Overrides the standard {Stomper::Extensions::Commmon#commit} behavior
+  # to commit the transaction encapsulated by this {TransactionScope transaction}.
+  def commit_with_transaction(headers={})
+    commit_without_transaction(@transaction, headers).tap do |f|
+      @transaction_state = :committed
+    end
+  end
+  alias :commit_without_transaction :commit
+  alias :commit :commit_with_transaction
+  
+  # Transmits a frame, but only applies the +transaction+ header if the
+  # frame command is amongst those commands that can be included in a
+  # transaction.
+  # @param [Stomper::Frame] frame
+  def transmit(frame)
+    self.begin if transaction_pending?
+    if FRAME_COMMANDS.include? frame.command
+      if frame.command != 'BEGIN' && transaction_finalized?
+        raise ::Stomper::Errors::TransactionFinalizedError
+      end
+      super(frame)
+    else
+      @connection.transmit frame
+    end
+  end
+  
+  # Applies this transaction to a block. Before any transactionable frame
+  # is transmitted within the block, a BEGIN frame will be generated. If
+  # the block completes without raising an error, a COMMIT frame will be
+  # transmitted to complete the transaction, otherwise an ABORT frame will
+  # be transmitted signalling that the transaction should be rolled-back by
+  # the broker.
+  def apply_to(callback)
+    begin
+      super
+      self.commit if transaction_started?
+    rescue Exception => err
+      self.abort if transaction_started?
+      raise err
+    end
+  end
+  
+  # Returns true if a BEGIN frame has not yet been transmitted for this
+  # transaction, false otherwise.
+  # @return [true, false]
+  def transaction_pending?; @transaction_state == :pending; end
+  # Returns true if a BEGIN frame has been transmitted for this
+  # transaction but neither COMMIT nor ABORT have been sent, false otherwise.
+  # @return [true, false]
+  def transaction_started?; @transaction_state == :started; end
+  # Returns true if a COMMIT frame has been transmitted for this
+  # transaction, false otherwise.
+  # @return [true, false]
+  def transaction_committed?; @transaction_state == :committed; end
+  # Returns true if an ABORT frame has been transmitted for this
+  # transaction, false otherwise.
+  # @return [true, false]
+  def transaction_aborted?; @transaction_state == :aborted; end
+  # Returns true if a COMMIT or ABORT frame has been transmitted for this
+  # transaction, false otherwise.
+  # @return [true, false]
+  def transaction_finalized?; transaction_aborted? || transaction_committed?; end
+end

data/lib/stomper/sockets.rb

@@ -1,37 +1,75 @@
-module Stomper
-  module Sockets
-    class SSL < DelegateClass(OpenSSL::SSL::SSLSocket)
-      include FrameReader
-      include FrameWriter
+# -*- encoding: utf-8 -*-
 
-      def initialize(host, port, *args)
-        @context = OpenSSL::SSL::SSLContext.new
-        @context.verify_mode = OpenSSL::SSL::VERIFY_NONE
+# Socket helpers.
+module Stomper::Sockets
+  
+  # A wrapper for an SSL Socket that tidies up the SSL specifics so
+  # our Connection library isn't troubled by them.
+  class SSL < DelegateClass(::OpenSSL::SSL::SSLSocket)
+    # Default SSL options to use with new {SSL} connections.
+    # @return {Symbol => Object}
+    DEFAULT_SSL_OPTIONS = {
+      :verify_mode => ::OpenSSL::SSL::VERIFY_PEER |
+        ::OpenSSL::SSL::VERIFY_FAIL_IF_NO_PEER_CERT,
+      :ca_file => nil,
+      :ca_path => nil,
+      :cert => nil,
+      :key => nil,
+      :post_connection_check => true
+    }
+    
+    # Create a new {SSL} connection to +host+ on +port+.
+    # @param [String] host hostname or IP address to connect to
+    # @param [Fixnum] port port number to establish the connection on
+    # @option opts [Object] :verify_mode (OpenSSL::SSL::VERIFY_PEER | OpenSSL::SSL::VERIFY_FAIL_IF_NO_PEER_CERT)
+    #   the methodology to use when verifying SSL certificates
+    # @option opts [String] :ca_file (nil) A single file containing all known
+    #  certificates for each certificate authority (CA)
+    # @option opts [String] :ca_path (nil) An openssl hashed directory of
+    #   individual certificate files for each CA
+    # @option opts [OpenSSL::X509::Certificate] :cert (nil) Client's
+    #   certificate. This is needed when server requires client to validate
+    #   itself with a certificate.
+    # @option opts [OpenSSL::PKey::PKey] :key (nil) Client's private key.
+    #   This is needed when server requires client to validate itself with
+    #   a certificate.
+    def initialize(host, port, ssl_opts={})
+      ssl_opts = DEFAULT_SSL_OPTIONS.merge(ssl_opts)
 
-        tcp_sock = TCPSocket.new(host, port)
-        @socket = OpenSSL::SSL::SSLSocket.new(tcp_sock, @context)
-        @socket.sync_close = true
-        @socket.connect
-        super(@socket)
-      end
-
-      def ready?
-        @socket.io.ready?
-      end
+      @context = ::OpenSSL::SSL::SSLContext.new
+      post_check = ssl_opts.delete(:post_connection_check)
+      post_check_host = (post_check == true) ? host : post_check
       
-      def shutdown(mode=2)
-        @socket.io.shutdown(mode)
+      DEFAULT_SSL_OPTIONS.keys.each do |k|
+        @context.__send__(:"#{k}=", ssl_opts[k]) if ssl_opts.key?(k)
       end
-    end
 
-    class TCP < DelegateClass(TCPSocket)
-      include FrameReader
-      include FrameWriter
-
-      def initialize(host, port, *args)
-        @socket = TCPSocket.new(host, port)
-        super(@socket)
+      tcp_sock = ::TCPSocket.new(host, port)
+      @socket = ::OpenSSL::SSL::SSLSocket.new(tcp_sock, @context)
+      @socket.sync_close = true
+      @socket.connect
+      if post_check_host
+        @socket.post_connection_check(post_check_host)
       end
+      super(@socket)
+    end
+    
+    # Passes the :ready? message on to the socket's underlying io object.
+    def ready?; @socket.io.ready?; end
+    
+    # Passes the :shutdown message on to the socket's underlying io object.
+    def shutdown(mode=2); @socket.io.shutdown(mode); end
+  end
+  
+  # A wrapper for an TCP Socket that tidies up the specifics so
+  # our Connection library isn't troubled by them.
+  class TCP < DelegateClass(::TCPSocket)
+    # Create a new {TCP} connection to +host+ on +port+.
+    # @param [String] host hostname or IP address to connect to
+    # @param [Fixnum] port port number to establish the connection on
+    def initialize(host, port)
+      @socket = TCPSocket.new(host, port)
+      super(@socket)
     end
   end
 end

data/lib/stomper/subscription_manager.rb

@@ -0,0 +1,79 @@
+# -*- encoding: utf-8 -*-
+
+# Manages subscriptions for a {Stomper::Connection}
+class Stomper::SubscriptionManager
+  # Creates a new subscription handler for the supplied {Stomper::Connection connection}
+  # @param [Stomper::Connection] connection
+  def initialize(connection)
+    @mon = ::Monitor.new
+    @callbacks = {}
+    @dests_to_ids = {}
+    connection.on_message { |m, con| dispatch(m) }
+    connection.on_unsubscribe { |u, con| remove(u) }
+  end
+  
+  # Adds a callback handler for a MESSAGE frame that is sent via the subscription
+  # associated with the supplied SUBSCRIBE frame.
+  # @param [Stomper::Frame] subscribe SUBSCRIBE frame for the subscription
+  # @param [Proc] callback Proc to invoke when a matching MESSAGE frame is
+  #   received from the broker.
+  # @return [self]
+  def add(subscribe, callback)
+    s_id = subscribe[:id]
+    dest = subscribe[:destination]
+    @mon.synchronize do
+      @callbacks[s_id] = callback
+      @dests_to_ids[dest] ||= []
+      @dests_to_ids[dest] << s_id
+    end
+  end
+  
+  # Returns true if the subscription ID is registered
+  # @param [String] id
+  # @return [true,false]
+  def subscribed_id?(id)
+    @mon.synchronize { @callbacks.key? id }
+  end
+  
+  # Returns true if the subscription destination is registered
+  # @param [String] destination
+  # @return [true,false]
+  def subscribed_destination?(destination)
+    @mon.synchronize { @dests_to_ids.key? destination }
+  end
+  
+  # Returns an array of subscription IDs that correspond to
+  # the given subscription destination. If the destination is unknown,
+  # returns +nil+.
+  # @param [String] destination
+  # @return [Array<String>, nil]
+  def ids_for_destination(destination)
+    @mon.synchronize { @dests_to_ids[destination] && @dests_to_ids[destination].dup }
+  end
+  
+  private
+  def remove(unsub)
+    s_id = unsub[:id]
+    @mon.synchronize do
+      @dests_to_ids.each do |dest, ids|
+        ids.delete s_id
+        @dests_to_ids.delete dest if ids.empty?
+      end
+      @callbacks.delete(s_id)
+    end
+  end
+  
+  def dispatch(message)
+    s_id = message[:subscription]
+    dest = message[:destination]
+    if s_id.nil? || s_id.empty?
+      cbs = @mon.synchronize do
+        @dests_to_ids[dest] && @dests_to_ids[dest].map { |id| @callbacks[id] }
+      end
+      cbs && cbs.each { |cb| cb.call(message) }
+    else
+      cb = @mon.synchronize { @callbacks[s_id] }
+      cb && cb.call(message)
+    end
+  end
+end