amqp 0.8.0.rc13 → 0.8.0.rc14

data/.rspec

@@ -1,2 +1,3 @@
 --color
---format nested
+--format
+progress

data/.travis.yml

@@ -1,10 +1,16 @@
+# https://github.com/travis-ci/travis-ci/wiki/.travis.yml-options
+bundler_args: --without development
 script: "bundle exec rake spec:ci"
+before_script: ./bin/ci/before_build.sh
 rvm:
   - 1.8.7
-  - rbx
   - 1.9.2
-  - ree
   - jruby
+  - ree
+  - rbx-2.0
 gemfile:
   - Gemfile
   - gemfiles/eventmachine-pre
+notifications:
+  recipients:
+    - michaelklishin@me.com

data/.yardopts

@@ -3,6 +3,7 @@
 --markup="textile" lib/**/*.rb
 --main README.md
 --asset docs:docs --asset examples:examples
+--hide-tag todo
 -
 LICENSE
 CHANGELOG

data/CHANGELOG

@@ -1,5 +1,14 @@
 = Version 0.8.0
 
+  * [API] AMQP::Exchange#publish calls now use a mutex on the channel exchange is declared on. Sharing channels between threads is discouraged but amqp gem covers your back in the most dangerous case.
+  * [API] AMQP::Channel#synchronize now can be used to guarantee mutual exclusion of multiple threads on channel instances.
+  * [BUG] Empty messages can finally be published fine. Yes, it took us just 3 years.
+  * [FEATURE] When connected to RabbitMQ, RabbitMQ-specific extensions are required automatically
+  * [FEATURE] AMQP::Session#broker and AMQP::Broker allow for broker capabilities inspection
+  * [FEATURE] New bitset-based channel id allocator
+  * [FEATURE] Multiple consumers per queue with AMQP::Consumer
+  * [FEATURE] Automatic recovery mode for channels
+  * [FEATURE] Network connection recovery callbacks for channels, exchanges, queues, consumers
   * [API] Connection URI (string) format for vhosts no longer assumes that vhosts begin with a slash (/), learn more at http://bit.ly/mfzwcB
   * [FEATURE] Returned messages, including header & content via AMQP::Exchange#on_publish. Callback accepts 3 args: basic_return, header, body
   * [BUG] Ruby 1.8.7-p249 is not supported because of this (p249-specific) Ruby bug: http://bit.ly/iONBmH

data/Gemfile

@@ -14,27 +14,33 @@ def custom_gem(name, options = Hash.new)
 end
 
 custom_gem "eventmachine"
-gem "json", :platform => :ruby_18
+# gem "json", :platform => :ruby_18
 custom_gem "amq-client",   :git => "git://github.com/ruby-amqp/amq-client.git",   :branch => "master"
 custom_gem "amq-protocol", :git => "git://github.com/ruby-amqp/amq-protocol.git", :branch => "master"
 
 group(:development) do
-  gem "yard", ">= 0.7.1"
+  gem "yard", ">= 0.7.2"
   # yard tags this buddy along
-  gem "RedCloth"
-  gem "rdiscount"
-
-  custom_gem "nake",         :platform => :ruby_19
-  custom_gem "contributors", :platform => :ruby_19
+  gem "RedCloth",  :platform => :mri
+  gem "rdiscount", :platform => :ruby
+  gem "yajl-ruby", :platform => :ruby
 
   # To test event loop helper and various Rack apps
-  gem "thin"
+  gem "thin",    :platform => :ruby
   gem "unicorn", :platform => :ruby
+
   gem "changelog"
 end
 
-group(:test) do
-  gem "rspec", ">=2.5.0"
-  gem "rake"
+group :test do
+  gem "rspec", "~> 2.6.0"
+  gem "rake",  "~> 0.9.2"
+
   custom_gem "evented-spec", :git => "git://github.com/ruby-amqp/evented-spec.git", :branch => "master"
+  gem "effin_utf8"
+
+  gem "multi_json"
+
+  gem "json",      :platform => :jruby
+  gem "yajl-ruby", :platform => :ruby_18
 end

data/README.md

@@ -3,9 +3,9 @@
 Ruby amqp gem is a widely used, feature-rich, well-maintained asynchronous AMQP 0.9.1 client with batteries included.
 This library works with Ruby 1.8.7 (p174 and p334), Ruby 1.9.2, [JRuby](http://jruby.org) (highly recommended to Microsoft Windows users), [REE](http://www.rubyenterpriseedition.com) and [Rubinius](http://rubini.us), and is licensed under the [Ruby License](http://www.ruby-lang.org/en/LICENSE.txt)
 
-Versions 0.8.0 and later of amqp gem implement [AMQP 0.9.1](http://bit.ly/hw2ELX) and supports [RabbitMQ extensions to AMQP 0.9.1](http://www.rabbitmq.com/extensions.html).
+Versions 0.8.0.RC13 and later of amqp gem implement [AMQP 0.9.1](http://bit.ly/amqp-model-explained) (see also [AMQP 0.9.1 spec document](http://bit.ly/hw2ELX)) and support [RabbitMQ extensions to AMQP 0.9.1](http://www.rabbitmq.com/extensions.html).
 
-[![Continuous Integration status](http://travis-ci.org/ruby-amqp/amqp.png)](http://travis-ci.org/ruby-amqp/amqp)
+[![Continuous Integration status](https://secure.travis-ci.org/ruby-amqp/amqp.png)](http://travis-ci.org/ruby-amqp/amqp)
 
 
 ## I know what AMQP is, how do I get started? ##
@@ -20,7 +20,7 @@ AMQP is an [open standard for messaging middleware](http://www.amqp.org/confluen
 emphasizes interoperability between different technologies (for example, Java, .NET, Ruby, Python, Node.js, Erlang, C and so on).
 
 Key features of AMQP are very flexible yet simple routing and binary protocol efficiency. AMQP supports many sophisticated features, for example,
-message acknowledgements, returning messages to producer, delivery confirmation, flow control and so on.
+message acknowledgements, returning of messages to producer, redelivery of messages that couldn't be processed, load balancing between message consumers and so on.
 
 
 ## What is amqp gem good for? ##
@@ -32,11 +32,15 @@ dozens or hundreds of applications built with all kinds of technologies.
 
 Specific examples:
 
+ * Events collectors, metrics & analytics applications can aggregate events produced by various applications
+   (Web and not) in the company network.
+
  * A Web application may route messages to a Java app that works
    with SMS delivery gateways.
 
- * Periodically run (Cron-driven) application may notify other systems that
-   there are some new results.
+ * MMO games can use flexible routing AMQP provides to propagate event notifications to players and locations.
+
+ * Price updates from public markets or other sources can be distributed between interested parties, from trading systems to points of sale in a specific geographic region.
 
  * Content aggregators may update full-text search and geospatial search indexes
    by delegating actual indexing work to other applications over AMQP.
@@ -44,8 +48,8 @@ Specific examples:
  * Companies may provide streaming/push APIs to their customers, partners
    or just general public.
 
- * A new shiny Ruby-based system may be integrated with an existing C++-based component
-   using AMQP.
+ * Continuous integration systems can distribute builds between multiple machines with various hardware and software
+   configurations using advanced routing features of AMQP.
 
  * An application that watches updates from a real-time stream (be it markets data
    or Twitter stream) can propagate updates to interested parties, including
@@ -67,11 +71,11 @@ with are outdated even in recent (10.10) releases. Learn more in the [RabbitMQ v
 On Microsoft Windows 7
 
     gem install eventmachine --pre
-    gem install amqp --pre --version "~> 0.8.0.RC12"
+    gem install amqp --pre
 
 On other OSes or [JRuby](http://jruby.org):
 
-    gem install amqp --pre --version "~> 0.8.0.RC12"
+    gem install amqp --pre
 
 
 ### "Hello, World" example ###
@@ -110,7 +114,8 @@ On other OSes or [JRuby](http://jruby.org):
 
 
 [Getting started guide](http://bit.ly/getting-started-with-amqp-ruby-gem) explains this and two more examples in detail,
-and is written in a form of a tutorial.
+and is written in a form of a tutorial. See [AMQP Model Explained](http://bit.ly/amqp-model-explained) if you want
+to learn more about AMQP principles & concepts.
 
 
 
@@ -118,7 +123,7 @@ and is written in a form of a tutorial.
 
 We believe that in order to be a library our users **really** love, we need to care about documentation as much as (or more)
 code readability, API beauty and autotomated testing across 5 Ruby implementations on multiple operating systems. We do care
-about our documentation: **if you don't find your answer in documentation, we consider it a high severity bug** that you
+about our [documentation](http://bitly.com/amqp-gem-docs): **if you don't find your answer in documentation, we consider it a high severity bug** that you
 should [file to us](http://github.com/ruby-amqp/amqp/issues). Or just complain to [@rubyamqp](https://twitter.com/rubyamqp) on Twitter.
 
 
@@ -140,10 +145,13 @@ of the page.
 You can find many examples (both real-world cases and simple demonstrations) under [examples directory](https://github.com/ruby-amqp/amqp/tree/master/examples) in the repository.
 Note that those examples are written against version 0.8.0.rc1 and later. 0.6.x and 0.7.x may not support certain AMQP protocol or "DSL syntax" features.
 
+There is also a work-in-progress [Messaging Patterns and Use Cases With AMQP](http://bit.ly/amqp-gem-patterns) documentation guide.
+
 
 ### Documentation guides ###
 
-[Documentation guides](http://bit.ly/amqp-gem-docs) describe the library itself as well as AMQP usage scenarios, topics like routing, error handing & recovery, broker-specific extensions, TLS support, troubleshooting and so on.
+[Documentation guides](http://bit.ly/amqp-gem-docs) describe the library itself as well as AMQP concepts, usage scenarios, topics like working with exchanges and queues,
+error handing & recovery, broker-specific extensions, TLS support, troubleshooting and so on. Most of the documentation is in these guides.
 
 
 ### API reference ###
@@ -165,7 +173,7 @@ what wasn't clear.
  * Join [Ruby AMQP mailing list](http://groups.google.com/group/ruby-amqp)
  * Follow [@rubyamqp](https://twitter.com/rubyamqp) on Twitter for Ruby AMQP ecosystem updates.
  * Join also [RabbitMQ mailing list](https://lists.rabbitmq.com/cgi-bin/mailman/listinfo/rabbitmq-discuss) (AMQP community epicenter).
- * Stop by #rabbitmq on irc.freenode.net. You can use [Web IRC client](http://webchat.freenode.net?channels=rabbitmq) if you don't have an IRC client installed.
+ * Stop by #rabbitmq on irc.freenode.net. You can use [Web IRC client](http://webchat.freenode.net?channels=rabbitmq) if you don't have IRC client installed.
 
 
 
@@ -223,9 +231,9 @@ Special thanks to Dmitriy Samovskiy, Ben Hood and Tony Garnock-Jones.
 This library is developed and tested primarily with [RabbitMQ](http://rabbitmq.com), although it should be compatible with any
 server implementing the [AMQP 0.9.1 spec](http://bit.ly/hw2ELX). For AMQP 0.8 brokers, use amqp gem version 0.7.x.
 
-### Why isn't Ruby 1.8.7.-p249 supported? ###
+### Why isn't Ruby 1.8.7.-p249 supported? Will it be supported in the future? ###
 
-Because there is absolutely no way we can both make code like the following (pseudo-synchronous) work
+In order to make code like the following (pseudo-synchronous) work
 
     conn = AMQP.connect
     ch   = AMQP::Channel.new(conn)
@@ -233,7 +241,9 @@ Because there is absolutely no way we can both make code like the following (pse
     ex   = ch.default_exchange
     ex.publish(some_data)
 
-and not be affected by this [Ruby 1.8.7-p249-specific bug (super called outside of method)](http://bit.ly/iONBmH)
+and not be affected by this [Ruby 1.8.7-p249-specific bug (super called outside of method)](http://bit.ly/iONBmH), we need to
+avoid any inheritance for key amqp gem classes: Channel, Queue, Exchange. This will take a moderate refactoring effort, and
+is likely to happen in 0.8.0.RC15.
 
 
 ### How does amqp gem relate to amq-client gem, amq-protocol and libraries like bunny? ###

data/amqp.gemspec

@@ -23,8 +23,8 @@ Gem::Specification.new do |s|
 
   # Dependencies
   s.add_dependency "eventmachine"
-  s.add_dependency "amq-client",   ">= 0.7.0.alpha34"
-  s.add_dependency "amq-protocol", ">= 0.7.0.alpha6"
+  s.add_dependency "amq-client",   ">= 0.8.0"
+  s.add_dependency "amq-protocol", ">= 0.8.0"
 
   begin
     require "changelog"

data/bin/ci/before_build.sh

@@ -0,0 +1,21 @@
+#!/bin/sh
+
+# guest:guest has full access to /
+
+sudo rabbitmqctl add_vhost /
+sudo rabbitmqctl add_user guest guest
+sudo rabbitmqctl set_permissions -p / guest ".*" ".*" ".*"
+
+
+# amqp_gem:amqp_gem_password has full access to amqp_gem_testbed
+
+sudo rabbitmqctl add_vhost amqp_gem_testbed
+sudo rabbitmqctl add_user amqp_gem amqp_gem_password
+sudo rabbitmqctl set_permissions -p amqp_gem_testbed amqp_gem ".*" ".*" ".*"
+
+
+# amqp_gem_reader:reader_password has read access to amqp_gem_testbed
+
+sudo rabbitmqctl add_user amqp_gem_reader reader_password
+sudo rabbitmqctl clear_permissions -p amqp_gem_testbed guest
+sudo rabbitmqctl set_permissions -p amqp_gem_testbed amqp_gem_reader "^---$" "^---$" ".*"

data/docs/08Migration.textile

@@ -1,28 +1,222 @@
 # @title Ruby AMQP gem: Migrating to version 0.8.0 and later
 
-h1. TBD
+h1. amqp gem 0.8 migration guide
 
 
 h2. About this guide
 
-TBD
+This guide explains how (and why) applications that use amqp gem versions 0.6.x and 0.7.x should migrate
+to 0.8.0.RCs and future versions. It also outlines deprecated features, when and why they will be removed.
 
 
 h2. Covered versions
 
-This guide covers "Ruby amqp gem":http://github.com/ruby-amqp/amqp v0.8.0 and later.
+This guide covers "Ruby amqp gem":http://github.com/ruby-amqp/amqp v0.6.x and v0.7.x.
 
 
 
-h2. TBD
+h2. Brief history of amqp gem
+
+amqp gem was born in early July 2008. Since then, it has seen 7 releases, used by all kinds of companies, have been
+key component to systems that process more than 100 gigabytes of data per day and, despite not being a "1.0 library",
+proven to be very usable.
+
+For the most part of 2008 and 2009 the gem did not receive much of attention. In 2010, some other AMQP clients (for example,
+RabbitMQ Java & .NET clients) switched to AMQP 0.9.1 specification. By the fall of 2010 it became clear that amqp gem needs
+a new team of maintainers, deep refactoring, new solid test suite and extensive documentation guides. Long story short,
+by December 2010, the "new maintainers group":https://github.com/ruby-amqp was formed and now maintains number of other libraries
+in the Ruby AMQP ecosystem, most notably the "Bunny gem":github.com/ruby-amqp/bunny.
+
+Over first few months of 2011, amqp gem undergone a number of maintenance releases (known as 0.7.x series), a ground up rewrite of
+the test suite, major documentation update as well as a major refactoring. It was upgraded to AMQP 0.9.1 specification and
+based on a new, much more efficient AMQP serialization library, "amq-protocol":https://github.com/ruby-amqp/amq-protocol.
+
+As part of this transition, amqp gem maintainers team pursued a number of goals:
+
+ * Implement AMQP 0.9.1 spec plus all the RabbitMQ extensions
+ * End "300 of 1 patch forks" situation that had gotten especially bad in early 2010
+ * Produce a solid end-to-end test suite that imitates real asynchronous applications
+ * Resolve many API usability issues: inconsistent behavior, weird class and method naming, heavy reliance on implicit connection objects and so on
+ * Produce documentation guides that other AMQP client users will be envious of
+ * Define a stable public API
+ * Improve memory efficiency and performance
+ * Resolve many limitations of the original API and implementation design
+ * Drop all the "experimental-stuff-that-was-never-finished"
+
+In the end, several projects like "evented-spec":https://github.com/ruby-amqp/evented-spec were born and became part of the amqp gem
+family of libraries. "300 one patch forks" hell is a thing of the past. Even initial pure Ruby implementation of the new serialization
+library is "several times as memory efficient":http://www.rabbitmq.com/blog/2011/03/01/ruby-amqp-benchmarks/. "Documentation guides":http://bit.ly/amqp-gem-docs
+response if very positive. amqp gem 0.8.0.RCs implement all but 1 RabbitMQ extensions as well as AMQP 0.9.1 spec features original gem
+never implemented fully. Many large users of the gem upgraded to 0.8.0.RCs. The future for amqp gem and its spin-offs is bright.
+
+
+h2. amqp gem 0.8.0 backwards compatibility policy
+
+amqp gem 0.8.0 is *not 100% backwards compatible*. That said, for most applications, upgrade path will be easy.
+Over 90% of the deprecated API classes & methods are still in place and will only be dropped in the 0.9.0 release.
+
+Plenty of incompatibilities between 0.6.x and 0.7.x series were ironed out in 0.8.0.RCs. Finally, this guide will explain
+what has changed, why, why it is the right thing to do and how you should adapt your application code.
+
+
+
+h2. Why developers should upgrade to 0.8.0
+
+ * Great documentation
+ * amqp gem 0.8.0 RCs and later versions are actively maintained
+ * Largest library users either already switched to amqp gem 0.8.0 RCs or are switching in the near future (2011)
+ * AMQP 0.9.1 spec implementation: many other popular clients, for example the RabbitMQ Java client, has dropped support for AMQP 0.8 specification
+ * RabbitMQ extensions
+ * Several AMQP brokers, including RabbitMQ (by far the most popular from the maintainers team observation), are planning to drop AMQP 0.8 spec support
+ * Applications that do not use depricated API features & behaviors will have very seamless upgrade path to the amqp gem 0.9.0 and beyond
+
+
+
+h2. AMQP protocol version change
+
+amqp gem before 0.8.0.RCs series implemented (most of) AMQP 0.8 specification.
+
+
+
+h2. Follow established AMQP terminology
+
+h3. require "mq" is deprecated
+
+Instead of the following:
+
+<pre>
+<code>
+require "amqp"
+require "mq"
+</code>
+</pre>
+
+or
+
+<pre>
+<code>
+require "mq"
+</code>
+</pre>
+
+
+switch to
+
+<pre>
+<code>
+require "amqp"
+</code>
+</pre>
+
+<span class="note">
+mq.rb will be removed before 1.0 release.
+</span>
+
+
+h3. MQ class is deprecated
+
+Please use {AMQP::Channel} instead. MQ class & its methods are implemented in amqp gem 0.8.x for backwards compatibility,
+but only for transition period (that will end after 0.9 release).
+
+Why is it deprecated? Because it was a poor name choice all along. Both mq.rb and MQ class step away from AMQP terminology and
+make 8 out of 10 engineers think it has something to do with AMQP queues (in fact, MQ should have been called Channel all along).
+No other AMQP client library we know of invents its own terminology when it comes to AMQP entities, and amqp gem shouldn't, too.
+
+<span class="note">
+MQ class and class methods that use implicit connection (MQ.queue and so on) will be removed before 1.0 release.
+</span>
+
+
+h2. MQ class is now AMQP::Channel
 
 TBD
 
 
+h2. MQ::Queue is now AMQP::Queue
+
+TBD
+
+
+h2. MQ::Exchange is now AMQP::Exchange
+
+TBD
+
+
+h2. MQ::Header is now AMQP::Header
+
+TBD
+
+
+
+h2. MQ::RPC is deprecated
+
+It was an experiment that was never finished. Some API design choices are very opinionated as well. amqp gem should not ship with
+half-baked poorly designed or overly opinionated solutions.
+
+<span class="note">
+MQ::RPC class will be removed before 1.0 release.
+</span>
+
+
+h2. MQ::Logger is removed
+
+It was an experiment that was never finished. Some API design choices are very opinionated as well. amqp gem should not ship with
+half-baked poorly designed or overly opinionated solutions.
+
+<span class="note">
+MQ::Logger class was removed in the the amqp gem 0.8.0 development cycle.
+</span>
+
+
+h2. AMQP::Buffer is removed
+
+AMQP::Buffer was AMQP 0.8 protocol implementation detail. With the new "amq-protocol gem":http://rubygems.org/gems/amq-protocol, it is no
+longer relevant.
+
+<span class="note">
+AMQP::Buffer class was removed in the the amqp gem 0.8.0 development cycle.
+</span>
+
+
+h2. AMQP::Frame is removed
+
+AMQP::Frame was AMQP 0.8 protocol implementation detail. With the new "amq-protocol gem":http://rubygems.org/gems/amq-protocol, it is no
+longer relevant.
+
+<span class="note">
+AMQP::Frame class was removed in the the amqp gem 0.8.0 development cycle.
+</span>
+
+
+h2. AMQP::Server is removed
+
+AMQP::Server was (an unfinished) toy implementation of AMQP 0.8 broker in Ruby on top of EventMachine. We believe that Ruby is not an optimal
+choice for AMQP broker implementations. We also never heard from anyone using it.
+
+<span class="note">
+AMQP::Server class was removed in the the amqp gem 0.8.0 development cycle.
+</span>
+
+
+h2. AMQP::Protocol::* classes are removed
+
+AMQP::Protocol::* classes were AMQP 0.8 protocol implementation detail. With the new "amq-protocol gem":http://rubygems.org/gems/amq-protocol, they are no
+longer relevant.
+
+<span class="note">
+AMQP::Protocol::* classes were removed in the the amqp gem 0.8.0 development cycle.
+</span>
+
+
+
+
+h2. TBD
+
+
 
 h2. Tell us what you think!
 
-Please take a moment and tell us what you think about this guide on "Ruby AMQP mailing list":http://groups.google.com/group/ruby-amqp:
+Please take a moment and tell us what you think about this guide "on Twitter":http://twitter.com/rubyamqp or "Ruby AMQP mailing list":http://groups.google.com/group/ruby-amqp:
 what was unclear? what wasn't covered? maybe you don't like guide style or grammar and spelling are incorrect? Readers feedback is
 key to making documentation better.