onstomp 1.0.4 → 1.0.5

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changes
 
+## 1.0.5
+* fixed a race condition that would occur if a user (or the failover extension)
+  tried to re-connect an OnStomp::Client instance within an `on_connection_closed`
+  (or similar) event handler. The fix is more of a band-aid at the moment,
+  and a proper fix will follow. Thanks to [alcy](https://github.com/alcy) for
+  helping me track this down.
+
 ## 1.0.4
 * fixed major oversight when using ruby 1.8.7 / jruby with an SSL connection.
   it will use blocking read/write methods if nonblocking methods are unavailable

data/README.md

@@ -46,10 +46,36 @@ in the hopes of increasing performance.
 The `stomp` gem is a good gem that works well, I just desired a different
 style API for working with message brokers.
 
+## Gotchas
+
+Both Ruby 1.8.7 and JRuby (as of 1.6.1) do not provide non-blocking read
+or write methods for OpenSSL connections. While a gem named
+[openssl-nonblock](https://github.com/tarcieri/openssl-nonblock) exists for
+Ruby < 1.9.2, I have not personally used it and given that it's a C extension,
+it may not be compatible with JRuby's openssl gem.  When an OnStomp connection
+is created, the socket (SSL or TCP) is checked to see whether or not the methods
+`write_nonblock` and `read_nonblock` have been defined. If not, OnStomp will
+fall back on `write` for writing and `readpartial` for reading. While both of
+these methods will block, the use of `IO::select` should help mitigate their
+effects. I initially missed this detail, so if you're using an older version
+of OnStomp (pre 1.0.4) with Ruby 1.8.7 or JRuby, you either want to upgrade
+your gem or avoid `stomp+ssl://` URIs like the plague.
+
+The final "gotcha" is more of an advanced warning.  When JRuby's support
+for the Ruby 1.9 API stabilizes (and `read_nonblock` and `write_nonblock` are
+available for OpenSSL connections), I will be dropping support for Ruby 1.8.x
+entirely. This is probably a ways off yet, but when the time comes, I'll
+post obvious warnings and increment the gem's major version. OnStomp 1.x
+will always be compatible with Ruby 1.8.7+, OnStomp 2.x will be Ruby 1.9.x
+only.
+
 ## Further Reading
 
+* The [OnStomp YARD Documentation](http://mdvlrb.com/onstomp/)
+* The [OnStomp Github Wiki](https://github.com/meadvillerb/onstomp/wiki)
+* Some [Contrived Examples](https://github.com/meadvillerb/onstomp/tree/master/examples)
 * A {file:extra_doc/UserNarrative.md User's Narrative}
-* A {file:extra_doc/DeveloperNarrative.md Developers's Narrative}
+* The {file:extra_doc/API.md OnStomp API Promise} (sort of)
 * A {file:extra_doc/CHANGELOG.md History of Changes}
 
 ## License

data/examples/basic.rb

@@ -6,21 +6,21 @@ puts "Starting demo"
 puts "----------------------------"
 
 running = true
-client = OnStomp::Client.new("stomp://localhost")
+client = OnStomp::Client.new("stomp://localhost:61613")
 client.connect
 
 puts "Connected to broker using protocol #{client.connection.version}"
 
-client.subscribe("/queue/onstomp/test") do |message|
+client.subscribe("/queue/onstomp_test") do |message|
   puts "Received: '#{message.body}'"
   if message.body == 'finished'
     running = false
   end
 end
 
-client.send("/queue/onstomp/test", "hello world")
-client.send("/queue/onstomp/test", "this is a simple demo of onstomp")
-client.send("/queue/onstomp/test", "finished")
+client.send("/queue/onstomp_test", "hello world")
+client.send("/queue/onstomp_test", "this is a simple demo of onstomp")
+client.send("/queue/onstomp_test", "finished")
 
 Thread.pass while running
 client.disconnect

data/extra_doc/API.md

@@ -33,18 +33,18 @@
     <tr>
       <td>{OnStomp::Interfaces::FrameMethods#ack ack}</td>
       <td>
-        <code>ack(message_id, headers=&lt;optional hash&gt;)</code>
+        <code>ack(message_id, subscription_id, headers=&lt;optional hash&gt;)</code>
       </td>
       <td style="background-color: #bfb;">true</td>
-      <td style="background-color: #fbb;">false</td>
+      <td style="background-color: #bfb;">true</td>
     </tr>
     <tr>
       <td>{OnStomp::Interfaces::FrameMethods#ack ack}</td>
       <td>
-        <code>ack(message_id, subscription_id, headers=&lt;optional hash&gt;)</code>
+        <code>ack(message_id, headers=&lt;optional hash&gt;)</code>
       </td>
       <td style="background-color: #bfb;">true</td>
-      <td style="background-color: #bfb;">true</td>
+      <td style="background-color: #fbb;">false</td>
     </tr>
     <tr>
       <td>{OnStomp::Interfaces::ClientEvents#after_receiving after_receiving}</td>
@@ -310,6 +310,14 @@
       <td style="background-color: #bfb;">true</td>
       <td style="background-color: #bfb;">true</td>
     </tr>
+    <tr>
+      <td>{OnStomp::Interfaces::ConnectionEvents#on_blocked on_blocked}</td>
+      <td>
+        <code>create_event_methods :blocked, :on</code>
+      </td>
+      <td style="background-color: #bfb;">true</td>
+      <td style="background-color: #bfb;">true</td>
+    </tr>
     <tr>
       <td>{OnStomp::Interfaces::ClientEvents#on_broker_beat on_broker_beat}</td>
       <td>
@@ -473,7 +481,7 @@
     <tr>
       <td>{OnStomp::Interfaces::FrameMethods#unsubscribe unsubscribe}</td>
       <td>
-        <code>unsubscribe(id, headers=&lt;optional hash&gt;)</code>
+        <code>unsubscribe(subscribe_frame, headers=&lt;optional hash&gt;)</code>
       </td>
       <td style="background-color: #bfb;">true</td>
       <td style="background-color: #bfb;">true</td>
@@ -481,7 +489,7 @@
     <tr>
       <td>{OnStomp::Interfaces::FrameMethods#unsubscribe unsubscribe}</td>
       <td>
-        <code>unsubscribe(subscribe_frame, headers=&lt;optional hash&gt;)</code>
+        <code>unsubscribe(id, headers=&lt;optional hash&gt;)</code>
       </td>
       <td style="background-color: #bfb;">true</td>
       <td style="background-color: #bfb;">true</td>

data/lib/onstomp/client.rb

@@ -79,6 +79,9 @@ class OnStomp::Client
   # @param [{#to_sym => #to_s}] headers
   # @return [self]
   def connect headers={}
+    # FIXME: This is a quick fix to force the Threaded IO processor to
+    # complete its work before we establish a connection.
+    processor_inst.stop
     @connection = OnStomp::Connections.connect self, headers,
       { :'accept-version' => @versions.join(','), :host => @host,
         :'heart-beat' => @heartbeats.join(','), :login => @login,

data/lib/onstomp/components/threaded_processor.rb

@@ -30,7 +30,9 @@ class OnStomp::Components::ThreadedProcessor
         end
       rescue OnStomp::StopReceiver
       rescue Exception
-        raise
+        # FIXME: This is pretty hacky, too. The problem is one of race
+        # conditions and how we access the connection.
+        raise if @run_thread == Thread.current
       end
     end
     self
@@ -63,13 +65,16 @@ class OnStomp::Components::ThreadedProcessor
   #   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?
+    if @run_thread
+      begin
+        @run_thread.raise OnStomp::StopReceiver if @run_thread.alive?
+        @run_thread.join
+      rescue OnStomp::StopReceiver
+      rescue IOError, SystemCallError
+        raise if @client.connected?
+      end
+      @run_thread = nil
     end
-    @run_thread = nil
     self
   end
 end

data/lib/onstomp/connections/base.rb

@@ -220,6 +220,13 @@ class OnStomp::Connections::Base
       rescue EOFError
         triggered_close $!.message
       rescue Exception
+        # TODO: Fix this potential race condition the right way.
+        # This is the problematic area!  If the user (or failover library)
+        # try to reconnect the Client when the connection is closed, the
+        # exception won't be raised until the IO Processing thread has
+        # already been joined to the main thread.  Thus, the connection gets
+        # re-established, the "dying" thread re-enters here, and immediately
+        # raises the exception that terminated it.
         triggered_close $!.message, :terminated
         raise
       end

data/lib/onstomp/connections/heartbeating.rb

@@ -53,14 +53,14 @@ module OnStomp::Connections::Heartbeating
   end
 
   # Returns true if client-side heartbeating is disabled, or 
-  # {#duration_since_transmitted} has not exceeded {#heartbeat_client_limit}
+  # {OnStomp::Connections::Base#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}
+  # {OnStomp::Connections::Base#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

data/lib/onstomp/failover/client.rb

@@ -87,16 +87,17 @@ class OnStomp::Failover::Client
   # {OnStomp::Client#disconnect disconnect} on the {#active_client}
   def disconnect *args, &block
     if active_client
-      Thread.pass until connected?
+      Thread.pass until connected? || @failed
       @client_mutex.synchronize do
         @disconnecting = true
-        active_client.disconnect *args, &block
+        active_client.disconnect *args, &block if connected?
       end
     end
   end
   
   private
   def reconnect
+    @failed = false
     attempt = 1
     until connected? || retry_exceeded?(attempt)
       sleep_for_retry attempt
@@ -112,9 +113,9 @@ class OnStomp::Failover::Client
       trigger_failover_retry :after, attempt
       attempt += 1
     end
-    connected?.tap do |b|
-      b && trigger_failover_event(:connected, :on, active_client)
-    end # <--- Until here
+    @failed = !connected?
+    trigger_failover_event(:connected, :on, active_client) unless @failed
+    !@failed
   end
   
   def retry_exceeded? attempt

data/lib/onstomp/version.rb

@@ -7,7 +7,7 @@ module OnStomp
   # Minor / feature version
   MINOR = 0
   # Patch version
-  PATCH = 4
+  PATCH = 5
   # Complete version
   VERSION = "#{MAJOR}.#{MINOR}.#{PATCH}"
 end

data/spec/onstomp/client_spec.rb

@@ -117,6 +117,7 @@ module OnStomp
           { :'accept-version' => '1.1', :host => 'my host',
             :'heart-beat' => '30,110', :login => 'my login',
             :passcode => 's3cr3t' }, pending_events, 30, 50).and_return(connection)
+        processor.should_receive(:stop)
         processor.should_receive(:start)
         client.stub(:pending_connection_events => pending_events)
         client.versions = '1.1'

data/spec/onstomp/failover/client_spec.rb

@@ -107,6 +107,27 @@ module OnStomp::Failover
         active_client.should_receive(:disconnect).with(:header1 => 'value 1')
         client.disconnect :header1 => 'value 1'
       end
+      it "should disconnect promptly if retrying exceeds maximum attempts" do
+        client.retry_attempts = 3
+        client.retry_delay = 0
+        active_client.stub(:connected? => false)
+        active_client.stub(:connect).and_return do
+          active_client.stub(:connected? => true)
+        end
+        client.connect
+        actual_disconnect = client.method(:disconnect)
+        client.stub(:disconnect).and_return do |*args|
+          active_client.stub(:connect => false)
+          active_client.stub(:connected? => false)
+          # Fire this off in a separate thread, as would be the real case
+          t = Thread.new do
+            connection.trigger_event :on_closed, active_client, connection
+          end
+          Thread.pass while t.alive?
+          actual_disconnect.call *args
+        end
+        client.disconnect :header1 => 'value 1'
+      end
     end
     
     describe ".transmit" do

metadata

@@ -1,71 +1,68 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: onstomp
-version: !ruby/object:Gem::Version 
+version: !ruby/object:Gem::Version
+  version: 1.0.5
   prerelease: 
-  version: 1.0.4
 platform: ruby
-authors: 
+authors:
 - Ian D. Eccles
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-04-20 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2011-10-13 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: rspec
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: &2156950640 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
+      - !ruby/object:Gem::Version
         version: 2.4.0
   type: :development
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: simplecov
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: *2156950640
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: &2156950180 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
         version: 0.3.0
   type: :development
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: yard
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  version_requirements: *2156950180
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: &2156949720 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
         version: 0.6.0
   type: :development
-  version_requirements: *id003
-- !ruby/object:Gem::Dependency 
-  name: rake
   prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  version_requirements: *2156949720
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &2156949340 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id004
-description: Client library for message passing with brokers that support the Stomp protocol.
-email: 
+  prerelease: false
+  version_requirements: *2156949340
+description: Client library for message passing with brokers that support the Stomp
+  protocol.
+email:
 - ian.eccles@gmail.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .autotest
 - .gitignore
 - .rspec
@@ -80,7 +77,6 @@ files:
 - examples/openuri.rb
 - extra_doc/API.md
 - extra_doc/API.md.erb
-- extra_doc/DeveloperNarrative.md
 - extra_doc/UserNarrative.md
 - lib/onstomp.rb
 - lib/onstomp/client.rb
@@ -197,32 +193,29 @@ files:
 - yard_extensions.rb
 homepage: http://github.com/meadvillerb/onstomp
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
       version: 1.8.7
-required_rubygems_version: !ruby/object:Gem::Requirement 
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: onstomp-core
-rubygems_version: 1.7.2
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: Client for message queues implementing the Stomp protocol interface.
-test_files: 
+test_files:
 - spec/onstomp/client_spec.rb
 - spec/onstomp/components/frame_headers_spec.rb
 - spec/onstomp/components/frame_spec.rb
@@ -286,4 +279,3 @@ test_files:
 - spec/support/custom_argument_matchers.rb
 - spec/support/frame_matchers.rb
 - spec/support/shared_frame_method_examples.rb
-has_rdoc: 

data/extra_doc/DeveloperNarrative.md

@@ -1,123 +0,0 @@
-# A Narrative for Developers
-
-This document explores the `OnStomp` library through a narrative aimed at end
-developers who wish to extend or modify the library.  It will start with the
-basics and work through the important code through exposition and examples.
-It may be helpful to
-review the [STOMP specification](http://stomp.github.com/index.html) before
-diving into this document. It's also important to note that `onstomp` can
-only be used with Ruby 1.8.7+.  Support for Rubies prior to 1.8.7 does not
-exist, and even requiring the library in your code will probably generate
-errors.
-
-## Clients & Frames
-
-An instance of {OnStomp::Client} is the primary way a user will interact
-with the `OnStomp` gem. It provides the helper methods to generate STOMP
-frames by including the {OnStomp::Interfaces::FrameMethods} mixin, and allows
-binding event callbacks by including {OnStomp::Interfaces::ClientEvents}
-(which in turn includes {OnStomp::Interfaces::EventManager}.) Every client
-instance will provide the same frame methods, regardless of the version of
-the STOMP protocol being used. This is accomplished through by a client's use
-of {OnStomp::Connections connections} and
-{OnStomp::Connections::Serializers serializers} to actually generate the
-frames and convert them to their appropriate string representation. You can
-read more about these components in a later section.
-
-All of the frame methods (eg: {OnStomp::Interfaces::FrameMethods#send send},
-{OnStomp::Interfaces::FrameMethods#send unsubscribe}) will either generate a
-new {OnStomp::Components::Frame} instance or raise an error if the STOMP
-protocol version negotiated between broker and client does not support
-the requested command (eg: STOMP 1.0 does not support NACK frames.)  All
-frame instances are composed of a {OnStomp::Components::Frame#command command},
-a set of {OnStomp::Components::Frame#headers headers}, and a
-{OnStomp::Components::Frame#body body}.
-
-A frame's {OnStomp::Components::Frame#command command} attribute is a string
-that matches the corresponding STOMP command (eg: SEND, RECEIPT) with one
-exception: heart-beats. The STOMP 1.1 protocol supports "heart-beating" to
-let brokers and clients know that the connection is still active on the other
-end by sending bare line-feed (ie: `\n`) characters between frame exchanges.
-As a result, calling {OnStomp::Interfaces::FrameMethods#beat beat} on a client
-will generate a frame whose command attribute is `nil`. This in turn lets the
-serializer know that this isn't a true frame and it will convert it to
-+"\n"+ instead of performing the normal serialization operation.
-
-A frame's {OnStomp::Components::FrameHeaders headers} behave much like a
-standard Ruby `Hash` but with a few important differences. First, the order
-that header names were added is preserved. This is also true of Ruby 1.9+
-hashes but not those of Ruby 1.8.7, and as a result there is some code
-to maintain the ordering when running 1.8.7. Second, accessing headers
-is somewhat indifferent:
-
-    frame[:some_header] = 'a value'
-    frame["some_header"] #=> 'a value'
-    
-What actually happens is all header names are converted to `Symbol`s
-(by calling `obj.to_sym`) before any setting or getting takes place. Using
-an object as a header name that does not respond to `to_sym` will raise an
-error. The final major difference between headers and hashes is that header
-values are only strings:
-
-    frame[:another_header] = 42
-    frame[:another_header] #=> '42'
-
-If the object passed as a header value cannot be converted to a string an
-error will be raised.
-
-For most kinds of frames, the {OnStomp::Components::Frame#body body} attribute
-will often be an empty string or `nil`. The only frames that support
-non-empty bodies are SEND, MESSAGE, and ERROR.
-
-## Events
-
-### Frame-centric Events
-
-Event triggering sequence for client generated frames:
-
-1. `client.send ...` is invoked and a SEND frame is created
-1. The event `before_transmitting` is triggered for the SEND frame
-1. The event `before_send` is triggered for the SEND frame
-1. The SEND frame is added to the {OnStomp::Connections::Base connection}'s
-   write buffer
-1. Some amount of time passes
-1. The SEND frame is serialized and fully written to the broker.
-1. The event `after_transmitting` is triggered for the SEND frame
-1. The event `on_send` is triggered for the SEND frame
-
-Event triggering sequence for broker generated frames:
-
-1. The broker writes a MESSAGE frame to the TCP/IP socket
-1. Some amount of time passes
-1. The client fully reads and de-serializes the MESSAGE frame
-1. The event `before_receiving` is triggered for the MESSAGE frame
-1. The event `before_message` is triggered for the MESSAGE frame
-1. The event `after_receiving` is triggered for the MESSAGE frame
-1. The event `on_message` is triggered for the MESSAGE frame
-
-### Connection-centric Events
-
-Event trigger sequence for connection events:
-
-1. An IO error occurs while the connection is reading or writing
-1. The connection closes its socket
-1. The connection triggers :on\_terminated
-1. The connection triggers :on\_closed
-
-## Subscription and Receipt Management
-
-### Subscription Manager
-
-### Receipt Manager
-
-## URI Based Configuration
-
-## Processors
-
-## Connections & Serializers
-
-### Connections
-
-### Serializers
-
-