stomper 0.3.0

data/lib/stomper/transaction.rb

@@ -0,0 +1,180 @@
+module Stomper
+  # An exception raised whenever a Transaction object has been aborted
+  # due to an unhandled exception generated by its supplied block, or when
+  # the block explicitly aborts the transaction.
+  #
+  # See also: Stomper::Transaction#perform
+  class TransactionAborted < RuntimeError; end
+
+  # An encapsulation of a stomp transaction.  Manually managing transactions
+  # is possible through the use of Stomper::Client#begin, Stomper::Client#commit,
+  # and Stomper::Client#abort.
+  #
+  # === Example Usage
+  #
+  # When the transaction is passed to the block:
+  #
+  #   client.transaction do |t|
+  #     t.send("/queue/target", "doing some work")
+  #
+  #     # do something that might raise an exception, indicating that any
+  #     # messages and acknowledgements we have sent should be "undone"
+  #
+  #     t.send("/queue/target", "completed work")
+  #   end
+  #
+  # When the block is evaluated within the transaction:
+  #
+  #   client.transaction do
+  #     send("/queue/target", "doing some work")
+  #
+  #     # ...
+  #
+  #     send("/queue/target", "completed work")
+  #   end
+  #
+  # Nesting transactions:
+  #
+  #   client.transaction do |t|
+  #     t.transaction do |nt|
+  #       nt.send("/queue/target", ...)
+  #
+  #       nt.transaction do |nnt|
+  #         nnt.send("/queue/target", ...)
+  #
+  #         # do something with potentially exceptional results
+  #       end
+  #
+  #       nt.send("/queue/target", ...)
+  #     end
+  #
+  #     t.send("/queue/target", ...)
+  #   end
+  #
+  # See also: Stomper::Client#transaction
+  #
+  class Transaction
+    # The id of this transaction, used to reference the transaction with the stomp broker.
+    attr_reader :id
+
+    # Creates a new Transaction instance.  The +client+ parameter
+    # is an instance of Stomper::Client and is required so that the Transaction
+    # instance has somewhere to forward +begin+, +ack+ and +abort+ methods
+    # to.  If the +trans_id+ parameter is not specified, an id is automatically
+    # generated of the form "tx-{Time.now.to_f}".  This name can be accessed
+    # through the +id+ attribute and is used in naming the transaction to
+    # the stomp broker.  If +block+ is given, the Transaction instance immediately
+    # calls its perform method with the supplied +block+.
+    def initialize(client, trans_id=nil, &block)
+      @client = client
+      @id = trans_id || "tx-#{Time.now.to_f}"
+      @committed = false
+      @aborted = false
+      perform(&block) if block_given?
+    end
+
+    # Invokes the given +block+.  If the +block+ executes normally, the
+    # transaction is committed, otherwise it is aborted.
+    # If +block+ accepts a parameter, this method yields itself to the block,
+    # otherwise, +block+ is evaluated within the context of this instance through
+    # +instance_eval+.
+    #
+    # If a call to +abort+ is issued within the block, the transaction is aborted
+    # as demanded, and no attempt is made to commit it; however, no code after the
+    # call to +abort+ will be evaluated, as +abort+ raises a TransactionAborted
+    # exception.
+    #
+    # If a call to +commit+ is issued within the block, the transaction is committed
+    # as demanded, and no attempt is made to commit it after +block+ has finished
+    # executing.  As +commit+ does not raise an excpetion, all code after the call
+    # to commit will be evaluated.
+    #
+    # If you are using Transaction objects directly, and not relying on their
+    # generation through Stomper::Client#transaction, be warned that this method
+    # will raise a TransactionAborted exception if the +block+ evaluation fails.
+    # This behavior allows for nesting transactions and ensuring that if a nested
+    # transaction fails, so do all of its ancestors.
+    def perform(&block) #:yields: transaction
+      begin
+        @client.begin(@id)
+        if block.arity == 1
+          yield self
+        else
+          instance_eval(&block)
+        end
+        commit
+      rescue => err
+        _abort
+        raise TransactionAborted, "aborted transaction '#{@id}' originator: #{err.to_s}"
+      end
+    end
+
+    # Returns true if the Transaction object has already been committed, false
+    # otherwise.
+    def committed?
+      @committed
+    end
+
+    # Returns true if the Transaction object has already been aborted, false
+    # otherwise.
+    def aborted?
+      @aborted
+    end
+
+    # Similar to Stomper::Client#transaction, this method creates a new
+    # Transaction object, nested inside of this one.  To prevent name
+    # collisions, this method automatically generates a transaction id,
+    # if one is not specified, of the form "#{parent_transaction_id}-#{Time.now.to_f}.
+    def transaction(transaction_id=nil,&block)
+      # To get a transaction name guaranteed to not collide with this one
+      # we will supply an explicit id to the constructor unless an id was
+      # provided
+      transaction_id ||= "#{@id}-#{Time.now.to_f}"
+      self.class.new(@client, transaction_id, &block)
+    end
+
+    # Wraps the Stomper::Client#send method, injecting a "transaction" header
+    # into the +headers+ hash, thus informing the stomp broker that the message
+    # generated here is part of this transaction.
+    def send(destination, body, headers={})
+      headers['transaction'] = @id
+      @client.send(destination, body, headers)
+    end
+
+    # Wraps the Stomper::Client#ack method, injecting a "transaction" header
+    # into the +headers+ hash, thus informing the stomp broker that the message
+    # acknowledgement is part of this transaction.
+    def ack(message_or_id, headers={})
+      headers['transaction'] = @id
+      @client.ack(message_or_id, headers)
+    end
+
+    # Aborts this transaction if it has not already been committed or aborted.
+    # Note that it does so by raising a TransactionAborted exception, allowing
+    # the +abort+ call to force any ancestral transactions to also fail.
+    #
+    # See also: commit, committed?, aborted?
+    def abort
+      raise TransactionAborted, "transaction '#{@id}' aborted explicitly" if _abort
+    end
+
+    # Commits this transaction unless it has already been committed or aborted.
+    #
+    # See also: abort, committed?, aborted?
+    def commit
+      # Guard against sending multiple commit messages to the server for a
+      # single transaction.
+      @client.commit(@id) unless committed? || aborted?
+      @committed = true
+    end
+
+    private
+    def _abort
+      # Guard against sending multiple abort messages to the server for a
+      # single transaction.
+      return false if committed? || aborted?
+      @client.abort(@id)
+      @aborted = true
+    end
+  end
+end

data/spec/client_spec.rb

@@ -0,0 +1,167 @@
+require File.expand_path(File.join(File.dirname(__FILE__), 'spec_helper'))
+
+module Stomper
+  describe Client do
+    before(:each) do
+      # For the client, we want to mock the underlying connection
+      @mock_connection = mock("connection")
+      @mock_connection.should_receive(:disconnect).with(no_args()).at_most(:once).and_return(nil)
+      Stomper::Connection.stub!(:new).and_return(@mock_connection)
+      @client = Client.new("stomp:///")
+    end
+    
+    describe "expected interface" do
+      it "should provide a send method" do
+        @client.should respond_to(:send)
+        @mock_connection.should_receive(:transmit).with(an_instance_of(Stomper::Frames::Send)).twice.and_return(nil)
+        @client.send("/queue/to", "message body", {:additional => 'header'})
+        @client.send("/queue/to", "message body")
+      end
+      it "should provide a subscribe method" do
+        @client.should respond_to(:subscribe)
+        @mock_connection.should_receive(:transmit).with(an_instance_of(Stomper::Frames::Subscribe)).twice.and_return(nil)
+        @client.subscribe("/queue/to", {:additional => 'header'})
+        @client.subscribe("/queue/to")
+      end
+      it "should provide an unsubscribe method" do
+        @client.should respond_to(:unsubscribe)
+        @mock_connection.should_receive(:transmit).with(an_instance_of(Stomper::Frames::Subscribe)).twice.and_return(nil)
+        @client.subscribe("/queue/to", {:id => 'subscription-id'})
+        @client.subscribe("/queue/to")
+        @mock_connection.should_receive(:transmit).with(an_instance_of(Stomper::Frames::Unsubscribe)).twice.and_return(nil)
+        @client.unsubscribe("/queue/to", 'subscription-id')
+        @client.unsubscribe("/queue/to")
+      end
+      it "should provide an ack method" do
+        @client.should respond_to(:ack)
+        @mock_connection.should_receive(:transmit).with(an_instance_of(Stomper::Frames::Ack)).exactly(3).times.and_return(nil)
+        @client.ack("message-id", {:additional => "header"})
+        @client.ack("message-id")
+        @client.ack(Stomper::Frames::Message.new({:'message-id' => 'msg-001'}, "body"))
+      end
+      it "should provide a begin method" do
+        @client.should respond_to(:begin)
+        @mock_connection.should_receive(:transmit).with(an_instance_of(Stomper::Frames::Begin)).once.and_return(nil)
+        @client.begin("tx-001")
+      end
+      it "should proivde an abort method" do
+        @client.should respond_to(:abort)
+        @mock_connection.should_receive(:transmit).with(an_instance_of(Stomper::Frames::Abort)).once.and_return(nil)
+        @client.abort("tx-001")
+      end
+      it "should provide a commit method" do
+        @client.should respond_to(:commit)
+        @mock_connection.should_receive(:transmit).with(an_instance_of(Stomper::Frames::Commit)).once.and_return(nil)
+        @client.commit("tx-001")
+      end
+      it "should provide a recieve method" do
+        @client.should respond_to(:receive)
+      end
+      it "should provide a disconnect method" do
+        @client.should respond_to(:disconnect)
+      end
+      it "should provide a close method" do
+        @client.should respond_to(:close)
+      end
+      it "should provide a connectivity test" do
+        @client.should respond_to(:connected?)
+      end
+    end
+
+    describe "threaded receiver" do
+      it "should respond to start and stop" do
+        @client.should respond_to(:start)
+        @client.should respond_to(:stop)
+        @client.should respond_to(:receiving?)
+      end
+      it "should only be receiving when it is started" do
+        @mock_connection.stub!(:receive).and_return(nil)
+        @mock_connection.should_receive(:connected?).any_number_of_times.and_return(true)
+        @client.receiving?.should be_false
+        @client.start
+        @client.receiving?.should be_true
+        @client.stop
+        @client.receiving?.should be_false
+      end
+    end
+
+    describe "subscribing to queue" do
+      before(:each) do
+        @message_sent = Stomper::Frames::Message.new({'destination' => "/queue/test"}, "test message")
+        @mock_connection.should_receive(:connected?).any_number_of_times.and_return(true)
+        @mock_connection.should_receive(:transmit).with(duck_type(:to_stomp)).at_least(:once).and_return(nil)
+        @mock_connection.should_receive(:receive).any_number_of_times.and_return(@message_sent)
+      end
+
+      it "should subscribe to a destination with a block" do
+        wait_for_message = true
+        @message_received = nil
+        @client.start
+        @client.subscribe("/queue/test") do |msg|
+          @message_received = msg
+          wait_for_message = false
+        end
+        true while wait_for_message
+        @client.stop
+        @message_received.should == @message_sent
+      end
+
+      it "should not unsubscribe from all destinations when a subscription id is provided" do
+        @client.subscribe("/queue/test", { 'id' => 'subscription-1' }) do |msg|
+          @message_received = msg
+        end
+        @client.subscribe("/queue/test") do |msg|
+          @message_received = msg
+        end
+        @client.subscribe("/queue/test", :id => 'subscription-2') do |msg|
+          @message_received = msg
+        end
+        @client.unsubscribe("/queue/test", 'subscription-1')
+        @client.subscriptions.size.should == 2
+      end
+
+      it "should not unsubscribe from non-naive subscriptions when only a destination is supplied" do
+        @client.subscribe("/queue/test", { 'id' => 'subscription-1' }) do |msg|
+          @message_received = msg
+        end
+        @client.subscribe("/queue/test") do |msg|
+          @message_received = msg
+        end
+        @client.subscribe("/queue/test") do |msg|
+          @message_received = msg
+        end
+        @client.unsubscribe("/queue/test")
+        @client.subscriptions.size.should == 1
+      end
+
+      # Due to the receiver running in a separate thread, this may not be correct?
+      it "should unsubscribe from a destination and receive no more messages" do
+        @mutex = Mutex.new
+        @last_message_received = nil
+        @client.start
+        @client.subscribe("/queue/test") do |msg|
+          @last_message_received = Time.now
+        end
+        true until @last_message_received
+        @client.unsubscribe("/queue/test")
+        @unsubscribed_at = Time.now
+        @client.stop
+        (@last_message_received < @unsubscribed_at).should be_true
+      end
+    end
+
+    describe "transactions" do
+      before(:each) do
+        @mock_connection.should_receive(:transmit).with(duck_type(:to_stomp)).at_least(:once).and_return(nil)
+      end
+
+      it "should provide a transaction method that generates a new Transaction" do
+        @evaluated = false
+        @client.transaction do |t|
+          @evaluated = true
+        end
+        @evaluated.should be_true
+      end
+    end
+  end
+end

data/spec/connection_spec.rb

@@ -0,0 +1,12 @@
+require File.expand_path(File.join(File.dirname(__FILE__), 'spec_helper'))
+require File.expand_path(File.join(File.dirname(__FILE__), 'shared_connection_examples'))
+
+module Stomper
+  describe Connection do
+    before(:each) do
+      @connection = Connection.new("stomp:///")
+    end
+    
+    it_should_behave_like "All Client Connections"
+  end
+end

data/spec/frames/client_frame_spec.rb

@@ -0,0 +1,142 @@
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'spec_helper'))
+
+module Stomper::Frames
+  describe ClientFrame do
+    before(:each) do
+      ClientFrame.generate_content_length = true
+      @client_frame = ClientFrame.new('COMMAND')
+    end
+
+    def str_size(str)
+      str.respond_to?(:bytesize) ? str.bytesize : str.size
+    end
+
+    it "should be provide a headers as an instance of Headers" do
+      @client_frame.headers.should be_an_instance_of(Stomper::Frames::Headers)
+    end
+
+    it "should be convertable into a stomp frame" do
+      @client_frame.to_stomp.should == "COMMAND\n\n\0"
+      @client_frame.headers.destination = "/queue/test/1"
+      @client_frame.headers['transaction-id'] = '2'
+      @client_frame.headers[:ack] = 'client'
+      @client_frame.to_stomp.should == "COMMAND\nack:client\ndestination:/queue/test/1\ntransaction-id:2\n\n\0"
+    end
+
+    describe "generating content-length header" do
+      it "should provide the header by default, overriding any existing header" do
+        @frame_body = 'testing'
+        @client_frame = ClientFrame.new('COMMAND', {'content-length' => 1}, @frame_body)
+        @client_frame.to_stomp.should == "COMMAND\ncontent-length:#{str_size(@frame_body)}\n\n#{@frame_body}\0"
+      end
+
+      it "should not provide the header if the class option is set to false, unless explicitly set on the frame in particular" do
+        ClientFrame.generate_content_length = false
+        @frame_body = 'testing'
+        @client_frame = ClientFrame.new('COMMAND', {}, @frame_body)
+        @client_frame.to_stomp.should == "COMMAND\n\n#{@frame_body}\0"
+        @client_frame = ClientFrame.new('COMMAND', {}, @frame_body)
+        @client_frame.generate_content_length = true
+        @client_frame.to_stomp.should == "COMMAND\ncontent-length:#{str_size(@frame_body)}\n\n#{@frame_body}\0"
+      end
+
+      it "should not provide the header if instance option is set false, when the class option is true" do
+        @frame_body = 'testing'
+        @client_frame = ClientFrame.new('COMMAND', {}, @frame_body)
+        @client_frame.generate_content_length = false
+        @client_frame.to_stomp.should == "COMMAND\n\n#{@frame_body}\0"
+        @client_frame = ClientFrame.new('COMMAND', {:generate_content_length => false}, @frame_body)
+        @client_frame.to_stomp.should == "COMMAND\n\n#{@frame_body}\0"
+      end
+
+      it "should not overwrite an explicit content-length header when option is off at class or instance level" do
+        @frame_body = 'testing'
+        @client_frame = ClientFrame.new('COMMAND', { 'content-length' => 4}, @frame_body)
+        @client_frame.generate_content_length = false
+        @client_frame.to_stomp.should == "COMMAND\ncontent-length:4\n\n#{@frame_body}\0"
+        ClientFrame.generate_content_length = false
+        @client_frame = ClientFrame.new('COMMAND', {'content-length' => 2}, @frame_body)
+        @client_frame.to_stomp.should == "COMMAND\ncontent-length:2\n\n#{@frame_body}\0"
+      end
+
+      it "should the class option should be scoped to the class it is set on" do
+        @frame_body = 'testing'
+        Send.generate_content_length = false
+        @send_frame = Send.new('/queue/test/1', @frame_body)
+        @client_frame = ClientFrame.new('COMMAND', {}, @frame_body)
+        @client_frame.to_stomp.should == "COMMAND\ncontent-length:#{str_size(@frame_body)}\n\n#{@frame_body}\0"
+        @send_frame.to_stomp.should == "SEND\ndestination:#{@send_frame.headers.destination}\n\n#{@frame_body}\0"
+        Send.generate_content_length = true
+        ClientFrame.generate_content_length = false
+        @send_frame = Send.new('/queue/test/1', @frame_body)
+        @client_frame = ClientFrame.new('COMMAND', {}, @frame_body)
+        @client_frame.to_stomp.should == "COMMAND\n\n#{@frame_body}\0"
+        @send_frame.to_stomp.should == "SEND\ncontent-length:#{str_size(@frame_body)}\ndestination:#{@send_frame.headers.destination}\n\n#{@frame_body}\0"
+      end
+    end
+    describe "client frames" do
+      describe Abort do
+        it "should produce a proper stomp message" do
+          @abort = Abort.new("transaction-test", { :a_header => 'test'})
+          @abort.to_stomp.should == "ABORT\na_header:test\ntransaction:transaction-test\n\n\0"
+        end
+      end
+      describe Ack do
+        it "should produce a proper stomp message" do
+          @ack = Ack.new("message-test", { :a_header => 'test'})
+          @ack.to_stomp.should == "ACK\na_header:test\nmessage-id:message-test\n\n\0"
+        end
+
+        it "should provide an Ack for a given message frame" do
+          @ack = Ack.ack_for(Message.new({'message-id' => 'test'}, "a body"))
+          @ack.to_stomp.should == "ACK\nmessage-id:test\n\n\0"
+          @ack = Ack.ack_for(Message.new({'message-id' => 'test', 'transaction' => 'tx-test'}, "a body"))
+          @ack.to_stomp.should == "ACK\nmessage-id:test\ntransaction:tx-test\n\n\0"
+        end
+
+      end
+      describe Begin do
+        it "should produce a proper stomp message" do
+          @begin = Begin.new("transaction-test", { :a_header => 'test'})
+          @begin.to_stomp.should == "BEGIN\na_header:test\ntransaction:transaction-test\n\n\0"
+        end
+      end
+      describe Commit do
+        it "should produce a proper stomp message" do
+          @commit = Commit.new("transaction-test", { :a_header => 'test'})
+          @commit.to_stomp.should == "COMMIT\na_header:test\ntransaction:transaction-test\n\n\0"
+        end
+      end
+      describe Connect do
+        it "should produce a proper stomp message" do
+          @connect = Connect.new('uzer','s3cr3t', { :a_header => 'test' })
+          @connect.to_stomp.should == "CONNECT\na_header:test\nlogin:uzer\npasscode:s3cr3t\n\n\0"
+        end
+      end
+      describe Disconnect do
+        it "should produce a proper stomp message" do
+          @disconnect = Disconnect.new({ :a_header => 'test'})
+          @disconnect.to_stomp.should == "DISCONNECT\na_header:test\n\n\0"
+        end
+      end
+      describe Send do
+        it "should produce a proper stomp message" do
+          @send = Send.new("/queue/a/target", "a body", { :a_header => 'test'})
+          @send.to_stomp.should == "SEND\na_header:test\ncontent-length:6\ndestination:/queue/a/target\n\na body\0"
+        end
+      end
+      describe Subscribe do
+        it "should produce a proper stomp message" do
+          @subscribe = Subscribe.new("/topic/some/target", { :a_header => 'test'})
+          @subscribe.to_stomp.should == "SUBSCRIBE\na_header:test\nack:auto\ndestination:/topic/some/target\n\n\0"
+        end
+      end
+      describe Unsubscribe do
+        it "should produce a proper stomp message" do
+          @unsubscribe = Unsubscribe.new("/topic/target.name.path", { :a_header => 'test'})
+          @unsubscribe.to_stomp.should == "UNSUBSCRIBE\na_header:test\ndestination:/topic/target.name.path\n\n\0"
+        end
+      end
+    end
+  end
+end