bunny 0.9.0.pre3 → 0.9.0.pre4

data/.gitignore

@@ -16,3 +16,5 @@ bin/*
 vendor/*
 playground/*
 *.org
+repl-*
+debug/*

data/ChangeLog.md

@@ -1,6 +1,61 @@
 ## Changes between Bunny 0.9.0.pre3 and 0.9.0.pre4
 
-No changes yet.
+### Heartbeats Support Fixes
+
+Heartbeats are now correctly sent at safe intervals (half of the configured
+interval). In addition, setting `:heartbeat => 0` (or `nil`) will disable
+heartbeats, just like in Bunny 0.8 and [amqp gem](http://rubyamqp.info).
+
+Default `:heartbeat` value is now `600` (seconds), the same as RabbitMQ 3.0
+default.
+
+
+### Eliminate Race Conditions When Registering Consumers
+
+Fixes a potential race condition between `basic.consume-ok` handler and
+delivery handler when a consumer is registered for a queue that has
+messages in it.
+
+GH issue: #78.
+
+### Support for Alternative Authentication Mechanisms
+
+Bunny now supports two authentication mechanisms and can be extended
+to support more. The supported methods are `"PLAIN"` (username
+and password) and `"EXTERNAL"` (typically uses TLS, UNIX sockets or
+another mechanism that does not rely on username/challenge pairs).
+
+To use the `"EXTERNAL"` method, pass `:auth_mechanism => "EXTERNAL"` to
+`Bunny.new`:
+
+``` ruby
+# uses the EXTERNAL authentication mechanism
+conn = Bunny.new(:auth_method => "EXTERNAL")
+conn.start
+```
+
+### Bunny::Consumer#cancel
+
+A new high-level API method: `Bunny::Consumer#cancel`, can be used to
+cancel a consumer. `Bunny::Queue#subscribe` will now return consumer
+instances when the `:block` option is passed in as `false`.
+
+
+### Bunny::Exchange#delete Behavior Change
+
+`Bunny::Exchange#delete` will no longer delete pre-declared exchanges
+that cannot be declared by Bunny (`amq.*` and the default exchange).
+
+
+### Bunny::DeliveryInfo#redelivered?
+
+`Bunny::DeliveryInfo#redelivered?` is a new method that is an alias
+to `Bunny::DeliveryInfo#redelivered` but follows the Ruby community convention
+about predicate method names.
+
+### Corrected Bunny::DeliveryInfo#delivery_tag Name
+
+`Bunny::DeliveryInfo#delivery_tag` had a typo which is now fixed.
 
 
 ## Changes between Bunny 0.9.0.pre2 and 0.9.0.pre3

data/README.md

@@ -1,79 +1,145 @@
 # About Bunny
 
-Bunny is a synchronous RabbitMQ client that focuses on ease of use.
+Bunny is a synchronous RabbitMQ client that focuses on ease of use. With the next
+0.9 release (currently in master), it is feature complete, supports all RabbitMQ 3.0
+features and is free of many limitations of earlier versions.
 
 
 ## Supported Ruby Versions
 
-It supports Ruby 1.9.3, 1.9.2, 1.8.7, Rubinius 2 and JRuby.
+Bunny 0.9 and more recent versions support Ruby 1.9.3, 1.9.2, JRuby 1.7, Rubinius 2.0 and 1.8.7.
 
 
 ## Supported RabbitMQ Versions
 
-Bunny versions `< 0.7.x` support RabbitMQ 1.x and 2.x. Bunny `0.8.x` and later versions only
-supports RabbitMQ 2.x.
+Bunny `0.8.x` and later versions only support RabbitMQ 2.x and 3.x.
 
+Bunny versions `0.7.x` and earlier support RabbitMQ 1.x and 2.x. 
 
-## Important: Bunny is about to undergo a lot of internal changes
+
+## Changes in Bunny 0.9
 
 Bunny is a very old library with **a lot** of missing functionality. It also implements an older version of the spec
-and may or may not work with future RabbitMQ versions. As such, Bunny is about to undergo serious internal changes.
-We will make our best to keep them as backwards compatible as possible but within reason.
+and may or may not work with future RabbitMQ versions. As such, Bunny needed serious internal changes.
+We (the maintainers) make our best to keep the new version as backwards compatible as possible but within reason.
 
 See [this announcement](https://groups.google.com/forum/?fromgroups#!topic/ruby-amqp/crNVGEuHm68) to learn more.
 
-In the meantime, consider using [Hot Bunnies](http://github.com/ruby-amqp/hot_bunnies) (JRuby-only) or [amqp gem](http://rubyamqp.info) instead.
 
+## Installation & Bundler Dependency
+
+To install Bunny 0.9.x with RubyGems:
+
+```
+gem install bunny --pre
+```
 
-## Quick Start for Bunny 0.7.x and 0.8.x
+To use Bunny 0.9.x in a project managed with Bundler:
+
+``` ruby
+gem "bunny", ">= 0.9.0.pre3" # optionally: , :git => "git://github.com/ruby-amqp/bunny.git", :branch => "master"
+```
+
+
+## Quick Start for Bunny 0.9.x
+
+Below is a small snippet that demonstrates how to publish
+and synchronously consume ("pull API") messages with Bunny 0.9.
+
+For a 15 minute tutorial using more practical examples, see [Getting Started with RabbitMQ and Ruby using Bunny](http://rubybunny.info/articles/getting_started.html).
 
 ``` ruby
 require "bunny"
 
-b = Bunny.new(:logging => true)
+# Start a communication session with RabbitMQ
+conn = Bunny.new
+conn.start
 
-# start a communication session with the amqp server
-b.start
+# open a channel
+ch = conn.create_channel
 
 # declare a queue
-q = b.queue("test1")
+q  = ch.queue("test1")
 
 # declare default direct exchange which is bound to all queues
-e = b.exchange("")
+e  = ch.default_exchange
 
 # publish a message to the exchange which then gets routed to the queue
-e.publish("Hello, everybody!", :key => 'test1')
+e.publish("Hello, everybody!", :routing_key => 'test1')
 
-# get message from the queue
-msg = q.pop[:payload]
+# fetch a message from the queue
+delivery_info, metadata, payload = q.pop
 
-puts "This is the message: " + msg + "\n\n"
+puts "This is the message: #{payload}"
 
 # close the connection
-b.stop
+conn.stop
 ```
 
-... or just:
 
-```
-require "bunny"
+## Community & Getting Help
 
-# Create a direct queue named "my_testq"
-Bunny.run { |c| c.queue("my_testq") }
-```
+### Getting Started
 
-## Community & Getting Help
+For a 15 minute tutorial using more practical examples, see [Getting Started with RabbitMQ and Ruby using Bunny](http://rubybunny.info/articles/getting_started.html).
+
+### Guides
+
+Other documentation guides are available at [rubybunny.info](http://rubybunny.info).
+
+### API Reference
+
+[Bunny API Reference](http://rubydoc.info/github/ruby-amqp/bunny/master/frames) is available at rubydoc.info.
+
+## Getting Help
+
+### Mailing List
+
+[Bunny a mailing list](groups.google.com/group/ruby-amqp). We encourage you
+to also join the [rabbitmq-discuss](https://lists.rabbitmq.com/cgi-bin/mailman/listinfo/rabbitmq-discuss) mailing list. Feel free to ask any questions that you may have.
+
+
+### IRC
+
+For more immediate help, please join `#rabbitmq` on `irc.freenode.net`.
+
+
+### News & Announcements on Twitter
+
+To subscribe for announcements of releases, important changes and so on, please follow [@rubyamqp](https://twitter.com/#!/rubyamqp) on Twitter.
+
+
+### Reporting Issues
+
+If you find a bug, poor default, missing feature or find any part of the API inconvenient, please [file an issue](http://github.com/ruby-amqp/bunny/issues) on GitHub.
+When filing an issue, please specify which Bunny and RabbitMQ versions you are using, provide recent RabbitMQ log file contents if possible,
+and try to explain what behavior you expected and why. Bonus points for contributing failing test cases.
+
+
+## Other Ruby RabbitMQ Clients
+
+Other widely used Ruby RabbitMQ clients are [Hot Bunnies](http://github.com/ruby-amqp/hot_bunnies) (JRuby-only) and [amqp gem](http://rubyamqp.info).
+Both are mature libraries and require RabbitMQ 2.x or 3.x.
+
+
+## Contributing
+
+First, clone the repository and run
+
+    bundle install --binstubs
+
+and then run tests with
 
-Please use [Ruby RabbitMQ clients Google Group](http://groups.google.com/group/ruby-amqp) for any questions you may
-have.
+    ./bin/rspec -cfs spec
 
-For news and updates, [follow @rubyamqp](http://twitter.com/rubyamqp) on Twitter.
+After that create a branch and make your changes on it. Once you are done with your changes and all tests pass, submit a pull request
+on GitHub.
 
 
 
 ## Other Resources
 
-* [AMQP 0.9.1 model explained](): introductory explanation of the AMQP v0.9.1 specification with particular reference to RabbitMQ.
+* [AMQP 0.9.1 model explained](http://www.rabbitmq.com/tutorials/amqp-concepts.html): introductory explanation of the AMQP v0.9.1 specification with particular reference to RabbitMQ.
 
 
 ## Links

data/bunny.gemspec

@@ -29,7 +29,7 @@ Gem::Specification.new do |s|
     map { |mail| Base64.decode64(mail) }
 
   # Dependencies
-  s.add_dependency "amq-protocol", ">= 1.0.0"
+  s.add_dependency "amq-protocol", ">= 1.0.1"
 
   # Files.
   s.has_rdoc = true

data/examples/connection/heartbeat.rb

@@ -9,9 +9,9 @@ $:.unshift(File.expand_path("../../../lib", __FILE__))
 require 'bunny'
 
 
-b = Bunny.new(:heartbeat_interval => 2)
-b.start
+conn = Bunny.new(:heartbeat_interval => 2)
+conn.start
 
-c = b.create_channel
+c = conn.create_channel
 
 sleep 10

data/examples/connection/unknown_host.rb

@@ -8,6 +8,6 @@ $:.unshift(File.expand_path("../../../lib", __FILE__))
 
 require 'bunny'
 
-b = Bunny.new("amqp://guest:guest@aksjhdkajshdkj.example82737.com")
-b.start
+conn = Bunny.new("amqp://guest:guest@aksjhdkajshdkj.example82737.com")
+conn.start
 

data/examples/guides/getting_started/hello_world.rb

@@ -9,13 +9,12 @@ conn.start
 
 ch = conn.create_channel
 q  = ch.queue("bunny.examples.hello_world", :auto_delete => true)
-x  = ch.default_exchange
 
 q.subscribe do |delivery_info, properties, payload|
   puts "Received #{payload}"
 end
 
-x.publish("Hello!", :routing_key => q.name)
+q.publish("Hello!", :routing_key => q.name)
 
 sleep 1.0
 conn.close

data/examples/guides/queues/redeliveries.rb

@@ -0,0 +1,79 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "rubygems"
+require "bunny"
+
+puts "=> Subscribing for messages using explicit acknowledgements model"
+puts
+
+connection1 = Bunny.new
+connection1.start
+
+connection2 = Bunny.new
+connection2.start
+
+connection3 = Bunny.new
+connection3.start
+
+ch1 = connection1.create_channel
+ch1.prefetch(1)
+
+ch2 = connection2.create_channel
+ch2.prefetch(1)
+
+ch3 = connection3.create_channel
+ch3.prefetch(1)
+
+x   = ch3.direct("amq.direct")
+q1  = ch1.queue("bunny.examples.acknowledgements.explicit", :auto_delete => false)
+q1.purge
+
+q1.bind(x).subscribe(:ack => true, :block => false) do |delivery_info, properties, payload|
+  # do some work
+  sleep(0.2)
+
+  # acknowledge some messages, they will be removed from the queue
+  if rand > 0.5
+    # FYI: there is a shortcut, Bunny::Channel.ack
+    ch1.acknowledge(delivery_info.delivery_tag, false)
+    puts "[consumer1] Got message ##{properties.headers['i']}, redelivered?: #{delivery_info.redelivered?}, ack-ed"
+  else
+    # some messages are not ack-ed and will remain in the queue for redelivery
+    # when app #1 connection is closed (either properly or due to a crash)
+    puts "[consumer1] Got message ##{properties.headers['i']}, SKIPPPED"
+  end
+end
+
+q2   = ch2.queue("bunny.examples.acknowledgements.explicit", :auto_delete => false)
+q2.bind(x).subscribe(:ack => true, :block => false) do |delivery_info, properties, payload|
+  # do some work
+  sleep(0.2)
+
+  ch2.acknowledge(delivery_info.delivery_tag, false)
+  puts "[consumer2] Got message ##{properties.headers['i']}, redelivered?: #{delivery_info.redelivered?}, ack-ed"
+end
+
+t1 = Thread.new do
+  i = 0
+  loop do
+    sleep 0.5
+
+    x.publish("Message ##{i}", :headers => { :i => i })
+    i += 1
+  end
+end
+t1.abort_on_exception = true
+
+t2 = Thread.new do
+  sleep 4.0
+
+  connection1.close
+  puts "----- Connection 1 is now closed (we pretend that it has crashed) -----"
+end
+t2.abort_on_exception = true
+
+
+sleep 7.0
+connection2.close
+connection3.close

data/lib/bunny/authentication/credentials_encoder.rb

@@ -0,0 +1,37 @@
+module Bunny
+  module Authentication
+    class CredentialsEncoder
+
+      #
+      # API
+      #
+
+      attr_reader :session
+
+      def self.for_session(session)
+        registry[session.mechanism].new(session)
+      end
+
+      def self.registry
+        @@registry ||= Hash.new { raise NotImplementedError }
+      end
+
+      def self.auth_mechanism(*mechanisms)
+        mechanisms.each do |m|
+          registry[m] = self
+        end
+      end
+
+      def encode_credentials(username, challenge)
+        raise NotImplementedError.new("Subclasses must override this method")
+      end
+
+      protected
+
+      def initialize(session)
+        @session = session
+      end
+
+    end
+  end
+end

data/lib/bunny/authentication/external_mechanism_encoder.rb

@@ -0,0 +1,26 @@
+require "bunny/authentication/credentials_encoder"
+
+module Bunny
+  module Authentication
+    class ExternalMechanismEncoder < CredentialsEncoder
+
+      auth_mechanism "EXTERNAL", "external"
+
+      # Encodes a username and password for the EXTERNAL mechanism. Since
+      # authentication is handled by an encapsulating protocol like SSL or
+      # UNIX domain sockets, EXTERNAL doesn't pass along any username or
+      # password information at all and this method always returns the
+      # empty string.
+      #
+      # @param [String] username The username to encode. This parameter is
+      #   ignored.
+      # @param [String] password The password to encode. This parameter is
+      #   ignored.
+      # @return [String] The username and password, encoded for the
+      #   EXTERNAL mechanism. This is always the empty string.
+      def encode_credentials(username, password)
+        ""
+      end
+    end
+  end
+end

data/lib/bunny/authentication/plain_mechanism_encoder.rb

@@ -0,0 +1,17 @@
+require "bunny/authentication/credentials_encoder"
+
+module Bunny
+  module Authentication
+    class PlainMechanismEncoder < CredentialsEncoder
+
+      auth_mechanism "PLAIN", "plain"
+
+      # @api public
+      # @see http://tools.ietf.org/rfc/rfc2595.txt RFC 2595
+      def encode_credentials(username, password)
+        "\0#{username}\0#{password}"
+      end
+
+    end
+  end
+end