amqp 0.8.0.rc6 → 0.8.0.rc7

data/amqp.gemspec

@@ -25,7 +25,7 @@ Gem::Specification.new do |s|
 
   # Dependencies
   s.add_dependency "eventmachine"
-  s.add_dependency "amq-client", ">= 0.7.0.alpha18"
+  s.add_dependency "amq-client", ">= 0.7.0.alpha20"
 
   begin
     require "changelog"

data/docs/Durability.textile

@@ -51,7 +51,37 @@ TBD
 
 h3. Publisher confirms
 
-TBD
+Because transactions carry certain (for some applications, significant) overhead, RabbitMQ introduced an extension to AMQP 0.9.1
+called {http://www.rabbitmq.com/blog/2011/02/10/introducing-publisher-confirms/ publisher confirms} ({http://www.rabbitmq.com/extensions.html#confirms documentation}).
+
+amqp gem implements support for this extension, but it is not loaded by default when you require "amqp". To load it, use
+
+<pre>
+<code>
+require "amqp/extensions/rabbitmq"
+</code>
+</pre>
+
+and then define a callback for publisher confirms using {AMQP::Channel#confirm}:
+
+<pre>
+<code>
+# enable publisher acknowledgements for this channel
+channel.confirm_select
+
+# define a callback that will be executed when message is acknowledged
+channel.on_ack do |basic_ack|
+  puts "Received an acknowledgement: delivery_tag = #{basic_ack.delivery_tag}, multiple = #{basic_ack.multiple}"
+end
+
+# define a callback that will be executed when message is rejected using basic.nack (a RabbitMQ-specific extension)
+channel.on_nack do |basic_nack|
+  puts "Received a nack: delivery_tag = #{basic_nack.delivery_tag}, multiple = #{basic_nack.multiple}"
+end
+</code>
+</pre>
+
+Note that the same callback is used for all messages published via all exchanges on the given channel.
 
 
 h3. Clustering

data/docs/Queues.textile

@@ -344,6 +344,11 @@ end
 </code>
 </pre>
 
+In books, articles and documentation about AMQP 0.9.1 you may come around discussions of _consumer tags_. Consumer tag in AMQP
+parlance is an identifier for subscription: most often, it is used to unsubscribe from messages (more on that later in this chapter).
+If you need to obtain consumer tag of a queue that is subscribed to receive messages, use {AMQP::Queue#consumer_tag}.
+
+
 h3. Exclusive consumers
 
 TBD
@@ -394,7 +399,42 @@ TBD
 
 h2. Unsubscribing from messages
 
-TBD
+Sometimes it is necessary to unsubscribe from messages without deleting a queue. To do that, use {AMQP::Queue#unsubscribe} method:
+
+<pre>
+<code>
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "rubygems"
+require "amqp"
+
+AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+  AMQP::Channel.new do |channel, open_ok|
+    exchange = channel.fanout("amq.fanout")
+
+    channel.queue("", :auto_delete => true, :exclusive => true) do |queue, declare_ok|
+      queue.bind(exchange).subscribe do |headers, payload|
+        puts "Received a new message"
+      end
+
+      EventMachine.add_timer(0.3) do
+        queue.unsubscribe
+        puts "Unsubscribed. Shutting down..."
+
+        connection.close {
+          EM.stop { exit }
+        }
+      end # EventMachine.add_timer
+    end # channel.queue
+  end
+end
+</code>
+</pre>
+
+By default {AMQP::Queue#unsubscribe} uses :noack option to inform broker that there is no need to send a
+confirmation. In other words, it does not expect you to pass in a callback, because consumer tag and registered
+callbacks are cleared immediately.
 
 
 h2. Unbinding queues from exchanges

data/examples/extensions/rabbitmq/publisher_confirmations_with_transient_messages.rb

@@ -13,13 +13,13 @@ AMQP.start do |connection|
   AMQP::Channel.new(connection) do |channel|
     puts "Channel #{channel.id} is now open"
 
-    channel.confirmations
+    channel.confirm_select
     channel.on_error do
       puts "Oops, there is a channel-levle exceptions!"
     end
 
 
-    channel.confirm do |basic_ack|
+    channel.on_ack do |basic_ack|
       puts "Received basic_ack: multiple = #{basic_ack.multiple}, delivery_tag = #{basic_ack.delivery_tag}"
     end
 
@@ -50,4 +50,4 @@ AMQP.start do |connection|
   EM.add_timer(3, show_stopper)
   Signal.trap('INT',  show_stopper)
   Signal.trap('TERM', show_stopper)
-end
+end

data/examples/guides/queues/09_unsubscribing_a_consumer.rb

@@ -4,8 +4,7 @@
 require "rubygems"
 require "amqp"
 
-#AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
-AMQP.start do |connection, open_ok|
+AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
   AMQP::Channel.new do |channel, open_ok|
     exchange = channel.fanout("amq.fanout")
 
@@ -15,14 +14,12 @@ AMQP.start do |connection, open_ok|
       end
 
       EventMachine.add_timer(0.3) do
-        puts "Timer tick"
-        queue.unsubscribe do |_|
-          puts "Unsubscribed. Shutting down..."
+        queue.unsubscribe
+        puts "Unsubscribed. Shutting down..."
 
-          connection.close {
-            EM.stop { exit }
-          }
-        end
+        connection.close {
+          EM.stop { exit }
+        }
       end # EventMachine.add_timer
     end # channel.queue
   end

data/examples/publishing/publishing_and_immediately_stopping_event_loop.rb

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "bundler"
+Bundler.setup
+
+$:.unshift(File.expand_path("../../../lib", __FILE__))
+
+require 'amqp'
+
+if RUBY_VERSION == "1.8.7"
+  class Array
+    alias sample choice
+  end
+end
+
+puts "=> Publishing and immediately stopping the event loop in the callback"
+puts
+
+# WARNING: this example is born out of http://bit.ly/j6v1Uz (#67) and
+#          by no means a demonstration of how you should go about publishing one-off messages.
+#          If durability is a concern, please read our "Durability and message persistence" guide at
+#          http://bit.ly/lQP1Al
+
+EventMachine.run do
+  client   = AMQP.connect(:host => '127.0.0.1')
+  channel  = AMQP::Channel.new(client)
+  channel.on_error { puts 'channel error'; EM.stop }
+
+  queue    = channel.queue("some_topic", :auto_delete => true)
+  exchange = channel.topic("foo", :durable => true, :auto_delete => true)
+
+  exchange.publish( 'hello world', :routing_key => "some_topic", :persistent => true, :nowait => false ) do
+    puts 'enqueued message for publishing on next event loop tick'
+    EventMachine.stop
+  end
+end

data/lib/amqp/exchange.rb

@@ -364,6 +364,8 @@ module AMQP
     # and distributed to any active consumers. Routing logic is determined by exchange type and
     # configuration as well as  message attributes (like :routing_key).
     #
+    #
+    #
     # h2. Data serialization
     #
     # Note that this method calls #to_s on payload argument value. You are encouraged to take care of
@@ -375,7 +377,30 @@ module AMQP
     #
     # h2. Event loop blocking
     #
-    # To minimize blocking of EventMachine event loop, this method performs network I/O on the next event loop tick.
+    # To minimize blocking of EventMachine event loop, this method performs network I/O on the next event loop tick. This means
+    # that shutting down the event loop immediately after {Exchange#publish} returns will result in message never being sent.
+    # If you need to send a one-off message and then stop the event loop, pass a block to {Exchange#publish} that will be executed
+    # after message is pushed down the network stack, and use {AMQP::Session#disconnect} to properly tear down AMQP connection
+    # (see example under Examples section below).
+    #
+    # @example Publishing a one-off message and properly closing AMQP connection then stopping the event loop:
+    #   exchange.publish(data) do
+    #     connection.disconnect { EventMachine.stop }
+    #   end
+    #
+    #
+    # h2. Publishing and persistence
+    #
+    # In cases when you application cannot afford to lose a message, AMQP 0.9.1 has several features to offer:
+    #
+    # * Persistent messages
+    # * Messages acknowledgements
+    # * Transactions
+    # * (a RabbitMQ-specific extension) Publisher confirms
+    #
+    # This is a broad topic and we dedicate a separate guide, {file:docs/Durability.textile Durability and message persistence}, to it.
+    #
+    #
     #
     # @param  [#to_s] payload  Message payload (content). Note that this method calls #to_s on payload argument value.
     #                          You are encouraged to take care of data serialization before publishing (using JSON, Thrift,
@@ -425,7 +450,11 @@ module AMQP
         opts    = @default_publish_options.merge(options)
 
         @channel.once_open do
-          super(payload.to_s, opts[:key] || opts[:routing_key] || @default_routing_key, @default_headers.merge(options), opts[:mandatory], opts[:immediate], &block)
+          super(payload.to_s, opts[:key] || opts[:routing_key] || @default_routing_key, @default_headers.merge(options), opts[:mandatory], opts[:immediate])
+
+          # don't pass block to AMQ::Client::Exchange#publish because it will be executed
+          # immediately and we want to do it later. See ruby-amqp/amqp/#67 MK.
+          block.call if block
         end
       end
 

data/lib/amqp/queue.rb

@@ -573,7 +573,7 @@ module AMQP
     # The method accepts a block which will be executed when the
     # unsubscription request is acknowledged as complete by the server.
     #
-    # @option opts [Boolean] :nowait (false)  If set, the server will not respond to the method. The client should
+    # @option opts [Boolean] :nowait (true)  If set, the server will not respond to the method. The client should
     #                                        not wait for a reply method.  If the server could not complete the
     #                                        method it will raise a channel or connection exception.
     #

data/lib/amqp/version.rb

@@ -6,5 +6,5 @@ module AMQP
   #
   # @see AMQ::Protocol::VERSION
   # @return [String] AMQP gem version
-  VERSION = '0.8.0.rc6'
+  VERSION = '0.8.0.rc7'
 end

data/spec/integration/regressions/issue66_spec.rb

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 require "spec_helper"
 
-describe "Authentication attempt" do
+describe "Immediate disconnection" do
 
   #
   # Environment
@@ -11,25 +11,14 @@ describe "Authentication attempt" do
   include EventedSpec::SpecHelper
 
 
-  describe "with default connection parameters" do
+  after :all do
+    done
+  end
 
-    #
-    # Examples
-    #
-
-    # assuming there is an account guest with password of "guest" that has
-    # access to / (default vhost)
-    context "when guest/guest has access to /" do
-      after :all do
-        done
-      end
-
-      it "succeeds" do
-        c = AMQP.connect
-        c.disconnect
-
-        done
-      end # it
-    end # context
-  end # describe
+  it "succeeds" do
+    c = AMQP.connect
+    c.disconnect {
+      done
+    }
+  end # it
 end # describe "Authentication attempt"

metadata

@@ -1,65 +1,49 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: amqp
-version: !ruby/object:Gem::Version 
-  hash: 977940491
-  prerelease: true
-  segments: 
-  - 0
-  - 8
-  - 0
-  - rc6
-  version: 0.8.0.rc6
+version: !ruby/object:Gem::Version
+  version: 0.8.0.rc7
+  prerelease: 6
 platform: ruby
-authors: 
+authors:
 - Aman Gupta
 - Jakub Stastny aka botanicus
 - Michael S. Klishin
 autorequire: 
 bindir: bin
 cert_chain: 
-date: 2011-05-06 00:00:00 +04:00
+date: 2011-05-06 00:00:00.000000000 +04:00
 default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
+dependencies:
+- !ruby/object:Gem::Dependency
   name: eventmachine
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: &2156551420 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: amq-client
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: *2156551420
+- !ruby/object:Gem::Dependency
+  name: amq-client
+  requirement: &2156550900 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 1369027924
-        segments: 
-        - 0
-        - 7
-        - 0
-        - alpha18
-        version: 0.7.0.alpha18
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.7.0.alpha20
   type: :runtime
-  version_requirements: *id002
-description: Widely used, feature-rich asynchronous AMQP 0.9.1 client with batteries included
-email: 
+  prerelease: false
+  version_requirements: *2156550900
+description: Widely used, feature-rich asynchronous AMQP 0.9.1 client with batteries
+  included
+email:
 - michael@novemberain.com
 - stastny@101ideas.cz
 executables: []
-
 extensions: []
-
-extra_rdoc_files: 
+extra_rdoc_files:
 - README.textile
 - docs/08Migration.textile
 - docs/Bindings.textile
@@ -75,7 +59,7 @@ extra_rdoc_files:
 - docs/RabbitMQVersions.textile
 - docs/Routing.textile
 - docs/VendorSpecificExtensions.textile
-files: 
+files:
 - .gitignore
 - .rspec
 - .travis.yml
@@ -144,6 +128,7 @@ files:
 - examples/legacy/primes-simple.rb
 - examples/legacy/primes.rb
 - examples/legacy/stocks.rb
+- examples/publishing/publishing_and_immediately_stopping_event_loop.rb
 - examples/queues/automatic_binding_for_default_direct_exchange.rb
 - examples/queues/basic_get.rb
 - examples/queues/declare_a_queue_without_assignment.rb
@@ -219,38 +204,68 @@ files:
 has_rdoc: true
 homepage: http://github.com/ruby-amqp/amqp
 licenses: []
-
-post_install_message: 
-rdoc_options: 
+post_install_message: ! "[\e[32mVersion 0.8.0\e[0m] [FEATURE] AMQP 0.9.1 support,
+  including tx.* operations class.\n[\e[32mVersion 0.8.0\e[0m] [API] Default authentication
+  handler now raises AMQP::PossibleAuthenticationFailureError\n[\e[32mVersion 0.8.0\e[0m]
+  [API] AMQP::Channel#initialize now takes 3rd (optional) options hash.\n[\e[32mVersion
+  0.8.0\e[0m] [API] Broker connection class is now AMQP::Session.\n[\e[32mVersion
+  0.8.0\e[0m] [API] AMQP::Error instance now may carry cause, an exception that caused
+  exception in question to be raised.\n[\e[32mVersion 0.8.0\e[0m] [API] When initial
+  TCP connection fails, default action is now to raise AMQP::TCPConnectionFailed.\n[\e[32mVersion
+  0.8.0\e[0m] [API] AMQP::BasicClient#reconnect now takes 2nd optional argument, period
+  of waiting in seconds.\n[\e[32mVersion 0.8.0\e[0m] [FEATURE] Handlers for initial
+  connection failure, connection loss; channel-level exceptions handlers on Channel
+  instances.\n[\e[32mVersion 0.8.0\e[0m] [API] AMQP::Exchange#initialize now accepts
+  :arguments option that takes a hash.\n[\e[32mVersion 0.8.0\e[0m] [API] AMQP::Queue#initialize
+  now accepts :arguments option that takes a hash.\n[\e[32mVersion 0.8.0\e[0m] [API]
+  AMQP#Logger is deprecated. It will be removed before 1.0 release.\n[\e[32mVersion
+  0.8.0\e[0m] [API] AMQP#fork is deprecated. It will be removed before 1.0 release.\n[\e[32mVersion
+  0.8.0\e[0m] [API] AMQP::RPC is deprecated. It will be removed before 1.0 release.\n[\e[32mVersion
+  0.8.0\e[0m] [FEATURE] Significant improvements to the documentation. From now on
+  lack of/poor documentation is considered a severe bug.\n[\e[32mVersion 0.8.0\e[0m]
+  [FEATURE] Support for RabbitMQ extensions to AMQP 0.9.1\n[\e[32mVersion 0.8.0\e[0m]
+  [API] AMQP::Exchange#publish now accepts (an optional) callback.\n[\e[32mVersion
+  0.8.0\e[0m] [API] AMQP::Channel.new now accepts (an optional) callback.\n[\e[32mVersion
+  0.8.0\e[0m] [API] AMQP::Header#ack now can acknowledge multiple deliveries\n[\e[32mVersion
+  0.8.0\e[0m] [API] AMQP::Exchange#delete now takes (an optional) block that is called
+  when exchange.delete-ok response arrives.\n[\e[32mVersion 0.8.0\e[0m] [API] AMQP::Header
+  now implements #to_hash\n[\e[32mVersion 0.8.0\e[0m] [API] AMQP::Queue#pop block
+  now can take 1, 2 or 3 arguments.\n[\e[32mVersion 0.8.0\e[0m] [API] AMQP::Queue#purge
+  \ now takes an optional block which is called when queue.purge-ok response arrives.\n[\e[32mVersion
+  0.8.0\e[0m] [API] AMQP::Queue#delete now takes an optional block which is called
+  when queue.delete-ok response arrives.\n[\e[32mVersion 0.8.0\e[0m] [API] AMQP::Queue#delete
+  now accepts :nowait option.\n[\e[32mVersion 0.8.0\e[0m] [API] AMQP::Queue#unbind
+  now takes an optional block which is called when queue.unbind-ok response arrives.\n[\e[32mVersion
+  0.8.0\e[0m] [API] AMQP::Queue#unbind now accepts :routing_key as alias to :key.
+  we believe it is a good idea to use AMQP terms.\n[\e[32mVersion 0.8.0\e[0m] [API]
+  AMQP::Channel#prefetch now takes (an optional) 2nd parameter that specifies that
+  QoS settings should be applied to underlying connection, as well as optional callback.\n[\e[32mVersion
+  0.8.0\e[0m] [API] AMQP::Channel#recover now takes (an optional) callback that is
+  called when basic.recover-ok is received.\n[\e[32mVersion 0.8.0\e[0m] [API] AMQP::Frame
+  is gone.\n[\e[32mVersion 0.8.0\e[0m] [API] AMQP::Buffer is gone. Serialization &
+  framing are now handled primarily by amq-protocol.\n[\e[32mVersion 0.8.0\e[0m] [API]
+  AMQP::Queue#publish is deprecated.\n[\e[32mVersion 0.8.0\e[0m] [API] Name argument
+  for AMQP::Queue.new and Channel#queue is optional.\n"
+rdoc_options:
 - --include=examples --main README.textile
-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 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">"
-    - !ruby/object:Gem::Version 
-      hash: 25
-      segments: 
-      - 1
-      - 3
-      - 1
+  requirements:
+  - - ! '>'
+    - !ruby/object:Gem::Version
       version: 1.3.1
 requirements: []
-
 rubyforge_project: amqp
-rubygems_version: 1.3.7
+rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
 summary: AMQP client implementation in Ruby/EventMachine.
 test_files: []
-