stomper 1.0.0 → 2.0.0

data/Rakefile

@@ -0,0 +1,5 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/examples/basic.rb

@@ -0,0 +1,38 @@
+# -*- encoding: utf-8 -*-
+$:.unshift(File.expand_path('../../lib', __FILE__))
+require 'stomper'
+
+$stdout.puts "Starting demo"
+$stdout.puts "----------------------------"
+
+client = Stomper::Connection.new("stomp://localhost")
+client.start
+
+$stdout.puts "Connected to broker using protocol #{client.version}"
+
+client.subscribe("/queue/stomper/test") do |message|
+  $stdout.puts "Received: #{message.body}"
+  if message.body == 'finished'
+    client.stop
+  end
+end
+
+client.send("/queue/stomper/test", "hello world")
+client.send("/queue/stomper/test", "this is a simple demo of stomper")
+client.send("/queue/stomper/test", "finished")
+
+Thread.pass while client.running?
+$stdout.puts "----------------------------"
+$stdout.puts "End of demo"
+
+# Example output:
+#
+#
+# Starting demo
+# ----------------------------
+# Connected to broker using protocol 1.0
+# Received: hello world
+# Received: this is a simple demo of stomper
+# Received: finished
+# ----------------------------
+# End of demo

data/examples/events.rb

@@ -0,0 +1,54 @@
+# -*- encoding: utf-8 -*-
+$:.unshift(File.expand_path('../../lib', __FILE__))
+require 'stomper'
+
+$stdout.puts "Starting demo"
+$stdout.puts "----------------------------"
+
+client = Stomper::Connection.open("stomp://localhost")
+
+$stdout.puts "Connected to broker using protocol #{client.version}"
+
+client.before_transmitting do |frame|
+  $stdout.puts "Frame headers [#{frame.command}] before modification: #{frame.headers.to_a.inspect}"
+  frame[:'x-alt-header'] = 'another value'
+end
+
+client.before_send do |frame|
+  $stdout.puts "SEND headers before modification: #{frame.headers.to_a.inspect}"
+  frame[:'x-misc-header'] = 'this is a test'
+end
+
+client.after_transmitting do |frame|
+  $stdout.puts "Final frame headers [#{frame.command}]: #{frame.headers.to_a.inspect}"
+end
+
+client.before_disconnect do |frame|
+  $stdout.puts "Disconnecting from broker"
+end
+
+client.on_connection_closed do |con|
+  $stdout.puts "Connection has been closed"
+end
+
+client.send("/queue/stomper/test", "hello world")
+client.disconnect
+
+$stdout.puts "----------------------------"
+$stdout.puts "End of demo"
+
+# Example output:
+#
+#
+# Starting demo
+# ----------------------------
+# Connected to broker using protocol 1.0
+# Frame headers [SEND] before modification: [["destination", "/queue/stomper/test"]]
+# SEND headers before modification: [["destination", "/queue/stomper/test"], ["x-alt-header", "another value"]]
+# Final frame headers [SEND]: [["destination", "/queue/stomper/test"], ["x-alt-header", "another value"], ["x-misc-header", "this is a test"]]
+# Frame headers [DISCONNECT] before modification: []
+# Disconnecting from broker
+# Final frame headers [DISCONNECT]: [["x-alt-header", "another value"]]
+# Connection has been closed
+# ----------------------------
+# End of demo

data/features/acking_messages.feature

@@ -0,0 +1,147 @@
+Feature: Acking messages
+  In order inform the broker that we have received and processed a MESSAGE
+  As a client
+  I want ensure ACK frames are properly sent
+  
+  Scenario: Stomp 1.0 Acking a MESSAGE
+    Given a 1.0 connection between client and broker
+    And the broker sends a "MESSAGE" frame with headers
+    | header-name  | header-value   |
+    | message-id   | m-1234         |
+    | subscription | s-5678         |
+    | destination  | /queue/testing |
+    When the client acks the last MESSAGE
+    And the frame exchange is completed
+    Then the broker should have received an "ACK" frame with headers
+    | header-name | header-value |
+    | message-id  | m-1234       |
+  
+  Scenario: Stomp 1.0 Acking a MESSAGE by ID
+    Given a 1.0 connection between client and broker
+    And the broker sends a "MESSAGE" frame with headers
+    | header-name  | header-value   |
+    | message-id   | m-1234         |
+    | subscription | s-5678         |
+    | destination  | /queue/testing |
+    When the client acks a message by ID "m-1234"
+    And the frame exchange is completed
+    Then the broker should have received an "ACK" frame with headers
+    | header-name | header-value |
+    | message-id  | m-1234       |
+    
+  Scenario: Stomp 1.0 Nacking a MESSAGE
+    Given a 1.0 connection between client and broker
+    When the broker sends a "MESSAGE" frame with headers
+    | header-name  | header-value   |
+    | message-id   | m-1234         |
+    | subscription | s-5678         |
+    | destination  | /queue/testing |
+    Then the client nacking the last MESSAGE should raise an unsupported command error
+    
+    
+  Scenario: Stomp 1.1 Acking a MESSAGE
+    Given a 1.1 connection between client and broker
+    And the broker sends a "MESSAGE" frame with headers
+    | header-name  | header-value   |
+    | message-id   | m-1234         |
+    | subscription | s-5678         |
+    | destination  | /queue/testing |
+    When the client acks the last MESSAGE
+    And the frame exchange is completed
+    Then the broker should have received an "ACK" frame with headers
+    | header-name  | header-value |
+    | message-id   | m-1234       |
+    | subscription | s-5678       |
+
+  Scenario: Stomp 1.1 Acking a MESSAGE by ID and subscription
+    Given a 1.1 connection between client and broker
+    And the broker sends a "MESSAGE" frame with headers
+    | header-name  | header-value   |
+    | message-id   | m-1234         |
+    | subscription | s-5678         |
+    | destination  | /queue/testing |
+    When the client acks a message by ID "m-1234" and subscription "s-5678"
+    And the frame exchange is completed
+    Then the broker should have received an "ACK" frame with headers
+    | header-name  | header-value |
+    | message-id   | m-1234       |
+    | subscription | s-5678       |
+
+  Scenario: Stomp 1.1 Nacking a MESSAGE
+    Given a 1.1 connection between client and broker
+    And the broker sends a "MESSAGE" frame with headers
+    | header-name  | header-value   |
+    | message-id   | m-1234         |
+    | subscription | s-5678         |
+    | destination  | /queue/testing |
+    When the client nacks the last MESSAGE
+    And the frame exchange is completed
+    Then the broker should have received a "NACK" frame with headers
+    | header-name  | header-value |
+    | message-id   | m-1234       |
+    | subscription | s-5678       |
+  
+  Scenario: Stomp 1.1 Nacking a MESSAGE by ID and subscription
+    Given a 1.1 connection between client and broker
+    And the broker sends a "MESSAGE" frame with headers
+    | header-name  | header-value   |
+    | message-id   | m-1234         |
+    | subscription | s-5678         |
+    | destination  | /queue/testing |
+    When the client nacks a message by ID "m-1234" and subscription "s-5678"
+    And the frame exchange is completed
+    Then the broker should have received an "NACK" frame with headers
+    | header-name  | header-value |
+    | message-id   | m-1234       |
+    | subscription | s-5678       |
+
+  Scenario: Stomp 1.1 Acking a MESAGE by ID should raise an error
+    Given a 1.1 connection between client and broker
+    When the broker sends a "MESSAGE" frame with headers
+    | header-name  | header-value   |
+    | message-id   | m-1234         |
+    | subscription | s-5678         |
+    | destination  | /queue/testing |
+    Then the client acking a message by ID "m-1234" should raise an argument error
+  
+  Scenario: Stomp 1.1 Nacking a MESAGE by ID should raise an error
+    Given a 1.1 connection between client and broker
+    When the broker sends a "MESSAGE" frame with headers
+    | header-name  | header-value   |
+    | message-id   | m-1234         |
+    | subscription | s-5678         |
+    | destination  | /queue/testing |
+    Then the client nacking a message by ID "m-1234" should raise an argument error
+        
+  Scenario: Stomp 1.1 Acking a MESAGE without a subscription should raise an error
+    Given a 1.1 connection between client and broker
+    When the broker sends a "MESSAGE" frame with headers
+    | header-name  | header-value   |
+    | message-id   | m-1234         |
+    | destination  | /queue/testing |
+    Then the client acking the last MESSAGE should raise an argument error
+
+  Scenario: Stomp 1.1 Nacking a MESAGE without a subscription should raise an error
+    Given a 1.1 connection between client and broker
+    When the broker sends a "MESSAGE" frame with headers
+    | header-name  | header-value   |
+    | message-id   | m-1234         |
+    | destination  | /queue/testing |
+    Then the client nacking the last MESSAGE should raise an argument error
+    
+    Scenario: Stomp 1.1 Acking a MESAGE without a message-id should raise an error
+      Given a 1.1 connection between client and broker
+      When the broker sends a "MESSAGE" frame with headers
+      | header-name  | header-value   |
+      | subscription   | s-5678         |
+      | destination  | /queue/testing |
+      Then the client acking the last MESSAGE should raise an argument error
+
+    Scenario: Stomp 1.1 Nacking a MESAGE without a message-id should raise an error
+      Given a 1.1 connection between client and broker
+      When the broker sends a "MESSAGE" frame with headers
+      | header-name  | header-value   |
+      | subscription  | s-5678         |
+      | destination  | /queue/testing |
+      Then the client nacking the last MESSAGE should raise an argument error
+

data/features/disconnecting.feature

@@ -0,0 +1,12 @@
+Feature: Disconnecting
+  In order to shut down a connection
+  As a client
+  I want to be able to disconnect
+  
+  
+  Scenario: A standard disconnect
+    Given a Stomp broker
+    And an established connection
+    When the client disconnects
+    Then the client should not be connected
+    And the broker should have received a "DISCONNECT" frame

data/features/establish_connection.feature

@@ -0,0 +1,44 @@
+Feature: Establish connection
+  In order to actually do something useful with a Stomp broker
+  As a client
+  I want to be able to connect
+  
+  Scenario: Connecting to a Stomp 1.0 Broker
+    Given a Stomp 1.0 broker
+    When a connection is created from the broker's URI
+    And the connection is told to connect
+    Then the connection should be connected
+    And the connection should be using the 1.0 protocol
+
+  Scenario: Connecting to a Stomp 1.0 Broker by string
+    Given a Stomp 1.0 broker
+    When a connection is created from the broker's URI string
+    And the connection is told to connect
+    Then the connection should be connected
+    And the connection should be using the 1.0 protocol
+
+  Scenario: Connecting to a Stomp 1.1 Broker
+    Given a Stomp 1.1 broker
+    When a connection is created from the broker's URI
+    And the connection is told to connect
+    Then the connection should be connected
+    And the connection should be using the 1.1 protocol
+        
+  Scenario: Connecting to a Stomp 1.1 Broker by string
+    Given a Stomp 1.1 broker
+    When a connection is created from the broker's URI string
+    And the connection is told to connect
+    Then the connection should be connected
+    And the connection should be using the 1.1 protocol
+    
+  Scenario: Connecting to a Broker using an unsupported version
+    Given a Stomp 3.2 broker
+    When a connection is created from the broker's URI
+    Then connecting should raise an unsupported protocol version error
+    And the connection should not be connected
+
+  Scenario: Connecting to a Broker whose first frame is not CONNECTED
+    Given an erroring Stomp broker
+    When a connection is created from the broker's URI
+    Then connecting should raise an connect failed error
+    And the connection should not be connected

data/features/protocol_version_negotiation.feature

@@ -0,0 +1,61 @@
+Feature: Protocol version negotiation
+  In order to handle connecting to different Stomp protocol implementations
+  As a client
+  I want to be able to negotiate the Stomp protocol to use
+  
+  Scenario: By default, allow 1.1 from broker
+    Given a Stomp 1.1 broker
+    When a connection is established
+    Then the connection should be using the 1.1 protocol
+    
+  Scenario: By default, allow 1.0 from broker
+    Given a Stomp 1.0 broker
+    When a connection is established
+    Then the connection should be using the 1.0 protocol
+    
+  Scenario: By default, assume 1.0 from version-less broker
+    Given an unversioned Stomp broker
+    When a connection is established
+    Then the connection should be using the 1.0 protocol
+  
+  Scenario: By default, raise error if the broker's version isn't supported
+    Given a Stomp 2.1 broker
+    When a connection is created from the broker's URI
+    Then connecting should raise an unsupported protocol version error
+  
+  Scenario: A 1.0 client should accept a 1.0 broker
+    Given a Stomp 1.0 broker
+    When the client protocol version is "1.0"
+    And a connection is established
+    Then the connection should be using the 1.0 protocol
+  
+  Scenario: A 1.0 client should accept a version-less broker
+    Given an unversioned Stomp broker
+    When the client protocol version is "1.0"
+    And a connection is established
+    Then the connection should be using the 1.0 protocol
+    
+  Scenario: A 1.0 client should not accept a 1.1 broker
+    Given a Stomp 1.1 broker
+    When the client protocol version is "1.0"
+    And a connection is created from the broker's URI
+    Then connecting should raise an unsupported protocol version error
+    
+  Scenario: A 1.1 client should accept a 1.1 broker
+    Given a Stomp 1.1 broker
+    When the client protocol version is "1.1"
+    And a connection is established
+    Then the connection should be using the 1.1 protocol
+  
+  Scenario: A 1.1 client should not accept a 1.0 broker
+    Given a Stomp 1.0 broker
+    When the client protocol version is "1.1"
+    And a connection is created from the broker's URI
+    Then connecting should raise an unsupported protocol version error
+
+  Scenario: A 1.1 client should not accept a version-less broker
+    Given an unversioned Stomp broker
+    When the client protocol version is "1.1"
+    And a connection is created from the broker's URI
+    Then connecting should raise an unsupported protocol version error
+  

data/features/receipts.feature

@@ -0,0 +1,72 @@
+Feature: Receipts
+  In order to ensure frame delivery
+  As a client
+  I want to request and monitor RECEIPT frames
+  
+  Scenario: RECEIPT on SEND
+    Given a 1.1 connection between client and broker
+    When the client sends a receipted message "test message" to "/queue/test"
+    And the frame exchange is completed
+    Then the client should have received a receipt for the last "SEND"
+
+  Scenario: RECEIPT on SUBSCRIBE
+    Given a 1.1 connection between client and broker
+    When the client subscribes to "/queue/test" with a receipt
+    And the frame exchange is completed
+    Then the client should have received a receipt for the last "SUBSCRIBE"
+
+  Scenario: RECEIPT on UNSUBSCRIBE
+    Given a 1.1 connection between client and broker
+    And the client subscribes to "/queue/testing" with headers
+    | header-name | header-value |
+    | id          | s-1234       |
+    When the client unsubscribes from "s-1234" with a receipt
+    And the frame exchange is completed
+    Then the client should have received a receipt for the last "UNSUBSCRIBE"
+
+  Scenario: RECEIPT on BEGIN
+    Given a 1.1 connection between client and broker
+    When the client begins transaction "t-1234" with a receipt
+    And the frame exchange is completed
+    Then the client should have received a receipt for the last "BEGIN"
+
+  Scenario: RECEIPT on COMMIT
+    Given a 1.1 connection between client and broker
+    When the client commits transaction "t-1234" with a receipt
+    And the frame exchange is completed
+    Then the client should have received a receipt for the last "COMMIT"
+  
+  Scenario: RECEIPT on ABORT
+    Given a 1.1 connection between client and broker
+    When the client aborts transaction "t-1234" with a receipt
+    And the frame exchange is completed
+    Then the client should have received a receipt for the last "ABORT"
+
+  Scenario: RECEIPT on ACK
+    Given a 1.1 connection between client and broker
+    When the client acks message "m-1234" from "s-5678" with a receipt
+    And the frame exchange is completed
+    Then the client should have received a receipt for the last "ACK"
+
+  Scenario: RECEIPT on NACK
+    Given a 1.1 connection between client and broker
+    When the client nacks message "m-1234" from "s-5678" with a receipt
+    And the frame exchange is completed
+    Then the client should have received a receipt for the last "NACK"
+    
+  Scenario: RECEIPT on DISCONNECT
+    Given a 1.1 connection between client and broker
+    When the client disconnects with a receipt
+    And the frame exchange is completed without client disconnect
+    Then the client should have received a receipt for the last "DISCONNECT"
+    
+  Scenario: No RECEIPT header on CONNECT
+    Given a 1.1 connection between client and broker
+    When the client connects with a receipt
+    And the frame exchange is completed
+    Then the client should not have added a receipt header to the last "CONNECT"
+  
+  
+  
+
+  

data/features/scopes.feature

@@ -0,0 +1,32 @@
+Feature: Scopes
+  In order to apply similar behavior to a series of frames
+  As a client
+  I want to have frame scopes
+
+  Scenario: Applying a set of headers to a series of frames
+    Given a 1.1 connection between client and broker
+    And a header scope with headers
+    | header-name   | header-value |
+    | x-my-header   | some value   |
+    | canon:unisono | violini      |
+    | x-machine     | a\b\c        |
+    When the client acks a message by ID "m-1234" and subscription "s-5678" within the scope
+    And the client subscribes to "/topic/test" with headers within the scope
+    | header-name | header-value      |
+    | id          | s-9012            |
+    | ack         | client-individual |
+    Then the broker should have received an "ACK" frame with headers
+    | header-name   | header-value |
+    | x-my-header   | some value   |
+    | canon:unisono | violini      |
+    | x-machine     | a\b\c        |
+    | message-id    | m-1234       |
+    | subscription  | s-5678       |
+    And the broker should have received a "SUBSCRIBE" frame with headers
+    | header-name   | header-value      |
+    | x-my-header   | some value        |
+    | canon:unisono | violini           |
+    | x-machine     | a\b\c             |
+    | id            | s-9012            |
+    | destination   | /topic/test       |
+    | ack           | client-individual |