klomp 0.0.8 → 1.0.0

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--order rand

data/.simplecov

@@ -0,0 +1,8 @@
+# -*- ruby -*-
+
+SimpleCov.start do
+  add_filter '/vendor/'
+
+  add_group "Loldance", "lib"
+  add_group "Specs", "spec"
+end

data/ChangeLog.md

@@ -1,6 +1,16 @@
-Changes
+Klomp Changes
 --------------------------------------------------------------------------------
 
+1.0.0 (2012/10/3)
+================================================================================
+
+- BREAKING CHANGES from previous release. You will need to revisit and change
+  all code that depends on Klomp 0.0.x
+- ground-up rewrite to eliminate onstomp dependency
+- Klomp::Client => Klomp
+- preserves similar API but with fewer bells and whistles
+- read latest README.md for details
+
 0.0.8 (2012/8/15)
 ================================================================================
 

data/Gemfile

@@ -1,12 +1,18 @@
-source "http://rubygems.org"
-
-gem "onstomp", "~> 1.0.7"
-# gem 'onstomp', :path => '../onstomp'
-gem "json"
-gem "uuid", "~> 2.3.5"
-
-group :development do
-  gem "foreman"
-  gem "rake"
-  gem "ZenTest"
-end
+# -*- ruby -*-
+
+# DO NOT EDIT THIS FILE. Instead, edit Rakefile, and run `rake bundler:gemfile`.
+
+source :gemcutter
+
+
+gem "rdoc", "~>3.10", :group => [:development, :test]
+gem "hoe-bundler", "~>1.1.0", :group => [:development, :test]
+gem "hoe-gemspec", "~>1.0.0", :group => [:development, :test]
+gem "hoe-git", "~>1.5.0", :group => [:development, :test]
+gem "rspec", "~>2.11.0", :group => [:development, :test]
+gem "ZenTest", "~>4.8.0", :group => [:development, :test]
+gem "rspec-given", "~>1.0", :group => [:development, :test]
+gem "simplecov", "~>0.6.0", :group => [:development, :test]
+gem "hoe", "~>3.0", :group => [:development, :test]
+
+# vim: syntax=ruby

data/Gemfile.lock

@@ -2,25 +2,45 @@ GEM
   remote: http://rubygems.org/
   specs:
     ZenTest (4.8.0)
-    foreman (0.46.0)
-      thor (>= 0.13.6)
-    json (1.7.1)
-    macaddr (1.6.1)
-      systemu (~> 2.5.0)
-    onstomp (1.0.7)
+    diff-lcs (1.1.3)
+    hoe (3.0.3)
+      rake (~> 0.8)
+    hoe-bundler (1.1.0)
+      hoe (>= 2.2.0)
+    hoe-gemspec (1.0.0)
+      hoe (>= 2.2.0)
+    hoe-git (1.5.0)
+      hoe (>= 2.2.0)
+    json (1.6.6)
+    multi_json (1.3.6)
     rake (0.9.2.2)
-    systemu (2.5.1)
-    thor (0.15.2)
-    uuid (2.3.5)
-      macaddr (~> 1.0)
+    rdoc (3.12)
+      json (~> 1.4)
+    rspec (2.11.0)
+      rspec-core (~> 2.11.0)
+      rspec-expectations (~> 2.11.0)
+      rspec-mocks (~> 2.11.0)
+    rspec-core (2.11.1)
+    rspec-expectations (2.11.3)
+      diff-lcs (~> 1.1.3)
+    rspec-given (1.5.0)
+      rspec (> 1.2.8)
+    rspec-mocks (2.11.3)
+    simplecov (0.6.4)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.5.3)
+    simplecov-html (0.5.3)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  ZenTest
-  foreman
-  json
-  onstomp (~> 1.0.7)
-  rake
-  uuid (~> 2.3.5)
+  ZenTest (~> 4.8.0)
+  hoe (~> 3.0)
+  hoe-bundler (~> 1.1.0)
+  hoe-gemspec (~> 1.0.0)
+  hoe-git (~> 1.5.0)
+  rdoc (~> 3.10)
+  rspec (~> 2.11.0)
+  rspec-given (~> 1.0)
+  simplecov (~> 0.6.0)

data/Manifest.txt

@@ -0,0 +1,31 @@
+.rspec
+.simplecov
+ChangeLog.md
+Gemfile
+Gemfile.lock
+Manifest.txt
+README.md
+Rakefile
+klomp.gemspec
+lib/klomp.rb
+lib/klomp/connection.rb
+lib/klomp/frames.rb
+lib/klomp/sentinel.rb
+spec/acceptance/acceptance_spec.rb
+spec/frames/auth_error.txt
+spec/frames/connect.txt
+spec/frames/connect_vhost.txt
+spec/frames/connected.txt
+spec/frames/disconnect.txt
+spec/frames/error.txt
+spec/frames/greeting.txt
+spec/frames/message.txt
+spec/frames/receipt.txt
+spec/frames/subscribe.txt
+spec/frames/unsubscribe.txt
+spec/klomp/connection_spec.rb
+spec/klomp/frames_spec.rb
+spec/klomp/sentinel_spec.rb
+spec/klomp_spec.rb
+spec/spec_helper.rb
+spec/support/have_received.rb

data/README.md

@@ -1,115 +1,137 @@
-# Klomp
-
-Klomp is a simple wrapper around the [OnStomp](https://github.com/meadvillerb/onstomp/)
-library with some additional HA and usability features:
-
-* When initialized with multiple broker URIs, Klomp will publish messages to
-one broker at a time, but will consume from all brokers simultaneously. This is
-a slight improvement over the regular [OnStomp::Failover::Client](http://mdvlrb.com/onstomp/OnStomp/Failover/Client.html)
-which handles all publishing and subscribing through a single "active" broker.
-This traditional one-broker-at-a-time technique can lead to a split-brain
-scenario in which messages are only received by a subset of your STOMP clients.
-By consuming from all brokers simultaneously, Klomp ensures that no message is
-left behind.
-
-* Where applicable, message bodies are automatically translated between native
-Ruby and JSON objects.
-
-* If a reply-to header is found in a message, a response is automatically
-sent to the reply-to destination. The response will be the return value of the
-subscribe block.
-
-## Installation
-
-    gem install klomp
-
-## Example usage
-
-The goal is that you should be able to use most (if not all) of the standard
-OnStomp API (see [OnStomp's UserNarrative](https://github.com/meadvillerb/onstomp/blob/master/extra_doc/UserNarrative.md))
-via a `Klomp::Client`:
-
-    client = Klomp::Client.new([ ... ])
-
-However, there will be some differences in the API due to how `Klomp::Client`
-manages connections. For example, while the `connected?` method normally
-returns a boolean value, Klomp's `connected?` will return an array of booleans
-(i.e. one result for each broker).
-
-### Fibonacci back-off retry behavior
-
-The OnStomp failover client takes `:retry_attempts` and `:retry_delay` options,
-and Klomp supports these too. However, if you do not specify either of these
-values, Klomp's default behavior will be to try to reconnect indefinitely, but
-use a fibonacci backoff approach, i.e., it will wait `fib(N)` seconds before
-trying to reconnect on the Nth attempt.
-
-### Message IDs
-
-Klomp uses the `uuid` gem to generate per-message unique identifiers. To disable
-generated message IDs, pass `:uuid => false` in the options hash. To customize
-to use your own generator, simply pass `:uuid => object` where the object you
-pass implements a `#generate` method that returns a string ID.
-
-### Additional options for Klomp::Client
-
-<table>
-  <tr>
-    <th>Key</th>
-    <th>Default value</th>
-    <th>Description</th>
-  </tr>
-  <tr>
-    <td>:translate_json</td>
-    <td>true</td>
-    <td>Translate message bodies between native Ruby and JSON objects?</td>
-  </tr>
-  <tr>
-    <td>:auto_reply_to</td>
-    <td>true</td>
-    <td>Automatically send response to reply-to destination?</td>
-  </tr>
-  <tr>
-    <td>:logger</td>
-    <td>false</td>
-    <td>Logger object</td>
-  </tr>
-  <tr>
-    <td>:uuid</td>
-    <td>UUID.new</td>
-    <td>UUID generator object, responds to :generate and returns an ID</td>
-  </tr>
-  <tr>
-    <td>:vhost</td>
-    <td>nil</td>
-    <td>override Apollo virtual host</td>
-  </tr>
-</table>
-
-## Developers
-
-Set up the environment using `bundle install`. Note that the tests currently
-assume a specific Apollo configuration which can be created on OSX using the
-following commands:
-
-    brew install apollo
-    apollo create /usr/local/var/apollo-primary
-    apollo create /usr/local/var/apollo-secondary
-    sed -i -e 's/616/626/' /usr/local/var/apollo-secondary/etc/apollo.xml
-
-Once Apollo is configured, the brokers can be started via `foreman start`. Now
-you can run the test suite via `rake test` or `autotest`.
-
-In addition to the regular test suite, there is a rake task called
-"test_failover" that will start an infinite publish/subscribe loop. Once this
-task is running, you can randomly kill Apollo brokers to test STOMP client
-failover.
-
-## Change Log
-
-See the [ChangeLog file](/livingsocial/klomp/blob/master/ChangeLog.md).
-
-## License
+# klomp
+
+* http://github.com/livingsocial/klomp
+
+## DESCRIPTION:
+
+Klomp is a simple [Stomp] messaging client that keeps your sanity intact.
+
+The purpose of Klomp is to be the simplest possible Stomp client. No in-memory
+buffering of outgoing messages, no fanout subscriptions in-process, no
+transactions, no complicated messaging patterns. Code simple enough so that when
+something goes wrong, the problem is obvious.
+
+[Stomp]: http://stomp.github.com/
+
+## FEATURES:
+
+The API surface area is minimal. `Klomp#publish` and `Klomp#subscribe` are your
+main endpoints.
+
+```ruby
+klomp = Klomp.new(["127.0.0.1:61613"], "login" => "mylogin", "passcode" => "mypassword")
+
+klomp.publish("/queue/klomp", "sanity")
+
+# subscribe with a block that gets invoked for each message
+klomp.subscribe("/queue/klomp") do |msg|
+  puts msg.body # => sanity
+end
+
+# subscribe with an object that gets #call'd
+class Klompen
+  def call(msg)
+    puts msg.body
+  end
+end
+# replaces previous subscribe block above
+klomp.subscribe("/queue/klomp", Klompen.new)
+klomp.unsubscribe("/queue/klomp")
+
+klomp.disconnect
+```
+
+### Connecting
+
+Connections are established when a `Klomp` object is constructed. Connections
+can be established in several ways.
+
+```ruby
+# Pass a single string containing host:port
+klomp = Klomp.new "localhost:61613"
+
+# Authentication with 'login' and 'passcode'
+klomp = Klomp.new "localhost:61613", "login" => "bob", "passcode" => "farmville"
+
+# With a stomp:// URL
+klomp = Klomp.new "stomp://bob:farmville@localhost:61613"
+```
+
+#### Load-balancing
+
+Klomp can be used to load-balance and maintain connections to multiple broker
+hosts, such that if one broker goes down, the remaining broker(s) will be used.
+Each broker is expected to provide an identical list of queues. To ensure
+delivery, all Stomp clients should be connected to all brokers in the
+load-balancing scenario.
+
+Publish semantics are slightly different than those for subscribe:
+
+- *Publish*: Klomp will publish each message on a randomly-selected broker.
+- *Subscribe*: each Klomp object subscribes to the provided queues on all hosts.
+
+Load-balanced connections are achieved with an array of servers.
+
+```ruby
+klomp = Klomp.new ["broker-001:61613", "broker-002:61613"]
+klomp = Klomp.new ["broker-001:61613", "broker-002:61613"], "login" => "bob", "passcode" => "farmville"
+klomp = Klomp.new ["stomp://bob:farmville@broker-001:61613", "stomp://bob:farmville@broker-002:61613"]
+```
+
+#### Virtual hosts
+
+Klomp can use the Stomp 1.1 "virtual host" feature in several ways.
+
+```ruby
+# additional name in colon-separated triple
+klomp = Klomp.new "virtual-host:localhost:61613"
+# host option in constructor
+klomp = Klomp.new "localhost:61613", "host" => "virtual-host"
+# host query parameter in stomp:// url
+klomp = Klomp.new "stomp://bob:farmville@localhost:61613?host=virtual-host"
+```
+
+#### Automatic reconnect
+
+If a Klomp connection experiences errors reading from or writing to its socket,
+the connection will go into an "offline" state. A sentinel thread will be
+started that attempts to reconnect periodically at Fibonacci back-off intervals.
+
+#### Logging
+
+Klomp accepts a `Logger` object in the constructor options hash.
+
+```ruby
+klomp = Klomp.new "localhost:61613", "logger" => Logger.new($stdout)
+```
+
+Background exceptions that occur in the subscriber thread as well as offline and
+reconnect events will be logged at the `warn` level, while individual sent and
+received message frames will be logged at the `debug` level.
+
+## REQUIREMENTS / LIMITATIONS:
+
+- Only supports [Stomp 1.1](http://stomp.github.com/stomp-specification-1.1.html)
+- Only one subscription per queue per Klomp
+- Only one handler object/block per queue. If you want to multi-dispatch a
+  message, write your own dispatcher.
+- Only supports the following frames:
+  - CONNECT/CONNECTED (initial handshake)
+  - SEND
+  - SUBSCRIBE
+  - UNSUBSCRIBE
+  - DISCONNECT
+  - MESSAGE
+  - ERROR
+- Not supported:
+  - ACK/NACK
+  - BEGIN/COMMIT/ABORT
+  - RECEIPT
+  - ack/receipt headers
+
+## LICENSE:
+
+The MIT License
 
 Copyright (C) 2012 LivingSocial
 
@@ -130,7 +152,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-
-## Credits
-
-* [Michael Paul Thomas Conigliaro](http://conigliaro.org): Original author

data/Rakefile

@@ -1,8 +1,21 @@
 require 'bundler/setup'
-require 'bundler/gem_tasks'
-require 'rake/testtask'
+require 'hoe'
 
-Dir.glob('tasks/*.rake').each { |r| import r }
+Hoe.plugin :bundler, :git, :gemspec, :gemcutter
 
-Rake::TestTask.new
-task :default => :test
+Hoe.spec 'klomp' do
+  developer 'Nick Sieger', 'nick.sieger@livingsocial.com'
+
+  ### Use markdown for changelog and readme
+  self.history_file = 'CHANGELOG.md'
+  self.readme_file  = 'README.md'
+
+  ### dependencies!
+  self.extra_dev_deps << [ 'hoe-bundler',  '~> 1.1.0'  ]
+  self.extra_dev_deps << [ 'hoe-gemspec',  '~> 1.0.0'  ]
+  self.extra_dev_deps << [ 'hoe-git',      '~> 1.5.0'  ]
+  self.extra_dev_deps << [ 'rspec',        '~> 2.11.0' ]
+  self.extra_dev_deps << [ 'ZenTest',      '~> 4.8.0'  ]
+  self.extra_dev_deps << [ 'rspec-given',  '~> 1.0'    ]
+  self.extra_dev_deps << [ 'simplecov',    '~> 0.6.0'  ]
+end

data/klomp.gemspec

@@ -1,21 +1,56 @@
-$:.push File.expand_path(File.join(File.dirname(__FILE__), "lib"))
-require 'klomp'
+# -*- encoding: utf-8 -*-
 
-Gem::Specification.new do |gem|
-  gem.authors       = ["LivingSocial"]
-  gem.email         = ["dev.happiness@livingsocial.com"]
-  gem.description   = "A simple wrapper around the OnStomp library with additional features"
-  gem.summary       = "A simple wrapper around the OnStomp library with additional features"
-  gem.homepage      = "https://github.com/livingsocial/klomp"
+Gem::Specification.new do |s|
+  s.name = "klomp"
+  s.version = "1.0.0"
 
-  gem.files         = `git ls-files`.split($\)
-  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
-  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
-  gem.name          = "klomp"
-  gem.require_paths = ["lib"]
-  gem.version       = Klomp::VERSION
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Nick Sieger"]
+  s.date = "2012-10-03"
+  s.description = "Klomp is a simple [Stomp] messaging client that keeps your sanity intact.\n\nThe purpose of Klomp is to be the simplest possible Stomp client. No in-memory\nbuffering of outgoing messages, no fanout subscriptions in-process, no\ntransactions, no complicated messaging patterns. Code simple enough so that when\nsomething goes wrong, the problem is obvious.\n\n[Stomp]: http://stomp.github.com/"
+  s.email = ["nick.sieger@livingsocial.com"]
+  s.extra_rdoc_files = ["Manifest.txt"]
+  s.files = [".rspec", ".simplecov", "ChangeLog.md", "Gemfile", "Gemfile.lock", "Manifest.txt", "README.md", "Rakefile", "klomp.gemspec", "lib/klomp.rb", "lib/klomp/connection.rb", "lib/klomp/frames.rb", "lib/klomp/sentinel.rb", "spec/acceptance/acceptance_spec.rb", "spec/frames/auth_error.txt", "spec/frames/connect.txt", "spec/frames/connect_vhost.txt", "spec/frames/connected.txt", "spec/frames/disconnect.txt", "spec/frames/error.txt", "spec/frames/greeting.txt", "spec/frames/message.txt", "spec/frames/receipt.txt", "spec/frames/subscribe.txt", "spec/frames/unsubscribe.txt", "spec/klomp/connection_spec.rb", "spec/klomp/frames_spec.rb", "spec/klomp/sentinel_spec.rb", "spec/klomp_spec.rb", "spec/spec_helper.rb", "spec/support/have_received.rb", ".gemtest"]
+  s.homepage = "http://github.com/livingsocial/klomp"
+  s.rdoc_options = ["--main", "README.md"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = "klomp"
+  s.rubygems_version = "1.8.24"
+  s.summary = "Klomp is a simple [Stomp] messaging client that keeps your sanity intact"
 
-  gem.add_dependency("onstomp", "~> 1.0.7")
-  gem.add_dependency("json")
-  gem.add_dependency("uuid", "~> 2.3.5")
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rdoc>, ["~> 3.10"])
+      s.add_development_dependency(%q<hoe-bundler>, ["~> 1.1.0"])
+      s.add_development_dependency(%q<hoe-gemspec>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<hoe-git>, ["~> 1.5.0"])
+      s.add_development_dependency(%q<rspec>, ["~> 2.11.0"])
+      s.add_development_dependency(%q<ZenTest>, ["~> 4.8.0"])
+      s.add_development_dependency(%q<rspec-given>, ["~> 1.0"])
+      s.add_development_dependency(%q<simplecov>, ["~> 0.6.0"])
+      s.add_development_dependency(%q<hoe>, ["~> 3.0"])
+    else
+      s.add_dependency(%q<rdoc>, ["~> 3.10"])
+      s.add_dependency(%q<hoe-bundler>, ["~> 1.1.0"])
+      s.add_dependency(%q<hoe-gemspec>, ["~> 1.0.0"])
+      s.add_dependency(%q<hoe-git>, ["~> 1.5.0"])
+      s.add_dependency(%q<rspec>, ["~> 2.11.0"])
+      s.add_dependency(%q<ZenTest>, ["~> 4.8.0"])
+      s.add_dependency(%q<rspec-given>, ["~> 1.0"])
+      s.add_dependency(%q<simplecov>, ["~> 0.6.0"])
+      s.add_dependency(%q<hoe>, ["~> 3.0"])
+    end
+  else
+    s.add_dependency(%q<rdoc>, ["~> 3.10"])
+    s.add_dependency(%q<hoe-bundler>, ["~> 1.1.0"])
+    s.add_dependency(%q<hoe-gemspec>, ["~> 1.0.0"])
+    s.add_dependency(%q<hoe-git>, ["~> 1.5.0"])
+    s.add_dependency(%q<rspec>, ["~> 2.11.0"])
+    s.add_dependency(%q<ZenTest>, ["~> 4.8.0"])
+    s.add_dependency(%q<rspec-given>, ["~> 1.0"])
+    s.add_dependency(%q<simplecov>, ["~> 0.6.0"])
+    s.add_dependency(%q<hoe>, ["~> 3.0"])
+  end
 end