amqp 0.8.0.rc10 → 0.8.0.rc11

data/CHANGELOG

@@ -1,5 +1,6 @@
 = Version 0.8.0
 
+  * [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
   * [FEATURE] AMQP::Utilities::EventLoopHelper detects app server (if any) being used and starts EventMachine reactor in an optimal way.
   * [FEATURE] AMQP 0.9.1 support, including tx.* operations class.

data/amqp.gemspec

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

data/examples/error_handling/handling_vhost_misconfiguration_with_a_rescue_block.rb

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "bundler"
+Bundler.setup
+
+$:.unshift(File.expand_path("../../../lib", __FILE__))
+
+require 'amqp'
+
+
+puts "=> Authentication failure/vhost misconfiguration handling with a rescue block"
+puts
+
+handler             = Proc.new { |settings| puts "Failed to connect, as expected"; EM.stop }
+connection_settings = {
+  :port     => 5672,
+  :vhost    => "/a/b/c/d/#{rand}/#{Time.now.to_i}",
+  :user     => "amq_client_gem",
+  :password => "amq_client_gem_password_that_is_incorrect #{Time.now.to_i}",
+  :timeout        => 0.3,
+  :on_tcp_connection_failure => handler
+}
+
+
+begin
+  AMQP.start(connection_settings) do |connection, open_ok|
+    raise "This should not be reachable"
+  end
+rescue AMQP::PossibleAuthenticationFailureError => afe
+  puts "Authentication failed, as expected, caught #{afe.inspect}"
+  EventMachine.stop if EventMachine.reactor_running?
+end

data/examples/hello_world_with_eventmachine_in_a_separate_thread.rb

@@ -31,7 +31,7 @@ EventMachine.next_tick {
     }
   end
 
-  exchange.publish "Hello, world!", :routing_key => queue.name  
+  exchange.publish "Hello, world!", :routing_key => queue.name
 }
 
 t.join

data/examples/hello_world_with_large_payload.rb

@@ -0,0 +1,399 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "bundler"
+Bundler.setup
+
+$:.unshift(File.expand_path("../../lib", __FILE__))
+
+require 'amqp'
+
+t = Thread.new { EventMachine.run }
+if defined?(JRUBY_VERSION)
+  # on the JVM, event loop startup takes longer and .next_tick behavior
+  # seem to be a bit different. Blocking current thread for a moment helps.
+  sleep 0.5
+end
+
+EventMachine.next_tick {
+  connection = AMQP.connect(:host => '127.0.0.1')
+  puts "Connected to AMQP broker. Running #{AMQP::VERSION} version of the gem..."
+
+  channel  = AMQP::Channel.new(connection)
+  queue    = channel.queue("amqpgem.examples.hello_world", :auto_delete => true)
+  exchange = channel.direct("")
+
+  queue.subscribe do |payload|
+    puts "Received a message #{payload.bytesize} bytes in size.\n\nDisconnecting..."
+
+    connection.close {
+      EM.stop { exit }
+    }
+  end
+
+
+  message = <<-MESSAGE
+  Historical origin
+
+  In May, 1974, the Institute of Electrical and Electronic Engineers (IEEE) published a paper entitled "A Protocol for Packet Network Interconnection."[1] The paper's authors, Vinton G. Cerf and Bob Kahn, described an internetworking protocol for sharing resources using packet-switching among the nodes. A central control component of this model was the Transmission Control Program that incorporated both connection-oriented links and datagram services between hosts. The monolithic Transmission Control Program was later divided into a modular architecture consisting of the Transmission Control Protocol at the connection-oriented layer and the Internet Protocol at the internetworking (datagram) layer. The model became known informally as TCP/IP, although formally it was henceforth called the Internet Protocol Suite.
+  Network function
+
+  TCP provides a communication service at an intermediate level between an application program and the Internet Protocol (IP). That is, when an application program desires to send a large chunk of data across the Internet using IP, instead of breaking the data into IP-sized pieces and issuing a series of IP requests, the software can issue a single request to TCP and let TCP handle the IP details.
+
+  IP works by exchanging pieces of information called packets. A packet is a sequence of octets and consists of a header followed by a body. The header describes the packet's destination and, optionally, the routers to use for forwarding until it arrives at its destination. The body contains the data IP is transmitting.
+
+  Due to network congestion, traffic load balancing, or other unpredictable network behavior, IP packets can be lost, duplicated, or delivered out of order. TCP detects these problems, requests retransmission of lost data, rearranges out-of-order data, and even helps minimize network congestion to reduce the occurrence of the other problems. Once the TCP receiver has reassembled the sequence of octets originally transmitted, it passes them to the application program. Thus, TCP abstracts the application's communication from the underlying networking details.
+
+  TCP is utilized extensively by many of the Internet's most popular applications, including the World Wide Web (WWW), E-mail, File Transfer Protocol, Secure Shell, peer-to-peer file sharing, and some streaming media applications.
+
+  TCP is optimized for accurate delivery rather than timely delivery, and therefore, TCP sometimes incurs relatively long delays (in the order of seconds) while waiting for out-of-order messages or retransmissions of lost messages. It is not particularly suitable for real-time applications such as Voice over IP. For such applications, protocols like the Real-time Transport Protocol (RTP) running over the User Datagram Protocol (UDP) are usually recommended instead.[2]
+
+  TCP is a reliable stream delivery service that guarantees delivery of a data stream sent from one host to another without duplication or losing data. Since packet transfer is not reliable, a technique known as positive acknowledgment with retransmission is used to guarantee reliability of packet transfers. This fundamental technique requires the receiver to respond with an acknowledgment message as it receives the data. The sender keeps a record of each packet it sends, and waits for acknowledgment before sending the next packet. The sender also keeps a timer from when the packet was sent, and retransmits a packet if the timer expires. The timer is needed in case a packet gets lost or corrupted.[2]
+
+  TCP consists of a set of rules: for the protocol, that are used with the Internet Protocol, and for the IP, to send data "in a form of message units" between computers over the Internet. At the same time that IP takes care of handling the actual delivery of the data, TCP takes care of keeping track of the individual units of data transmission, called segments, that a message is divided into for efficient routing through the network. For example, when an HTML file is sent from a Web server, the TCP software layer of that server divides the sequence of octets of the file into segments and forwards them individually to the IP software layer (Internet Layer). The Internet Layer encapsulates each TCP segment into an IP packet by adding a header that includes (among other data) the destination IP address. Even though every packet has the same destination address, they can be routed on different paths through the network. When the client program on the destination computer receives them, the TCP layer (Transport Layer) reassembles the individual segments and ensures they are correctly ordered and error free as it streams them to an application.
+  TCP segment structure
+
+  Transmission Control Protocol accepts data from a data stream, 'segments' it into chunks, and adds a TCP header creating a TCP segment. The TCP segment is then encapsulated into an IP datagram. A TCP segment is "the packet of information that TCP uses to exchange data with its peers." [3]
+
+  Note that the term TCP packet, though sometimes informally used, is not in line with current terminology, where segment refers to the TCP PDU (Protocol Data Unit), datagram[4] to the IP PDU and frame to the data link layer PDU:
+
+      Processes transmit data by calling on the TCP and passing buffers of data as arguments. The TCP packages the data from these buffers into segments and calls on the internet module [e.g. IP] to transmit each segment to the destination TCP.[5]
+
+  A TCP segment consists of a segment header and a data section. The TCP header contains 10 mandatory fields, and an optional extension field (Options, pink background in table).
+
+  The data section follows the header. Its contents are the payload data carried for the application. The length of the data section is not specified in the TCP segment header. It can be calculated by subtracting the combined length of the TCP header and the encapsulating IP segment header from the total IP segment length (specified in the IP segment header).
+  TCP Header Bit offset 	 0 	 1 	 2 	 3 	 4 	 5 	 6 	 7 	 8 	 9 	10 	11 	12 	13 	14 	15 	16 	17 	18 	19 	20 	21 	22 	23 	24 	25 	26 	27 	28 	29 	30 	31
+  0 	Source port 	Destination port
+  32 	Sequence number
+  64 	Acknowledgment number (if ACK set)
+  96 	Data offset 	Reserved 	C
+  W
+  R 	E
+  C
+  E 	U
+  R
+  G 	A
+  C
+  K 	P
+  S
+  H 	R
+  S
+  T 	S
+  Y
+  N 	F
+  I
+  N 	Window Size
+  128 	Checksum 	Urgent pointer (if URG set)
+  160
+  ... 	Options (if Data Offset > 5)
+  ... 	padding
+
+      Source port (16 bits) – identifies the sending port
+      Destination port (16 bits) – identifies the receiving port
+      Sequence number (32 bits) – has a dual role:
+
+          If the SYN flag is set (1), then this is the initial sequence number. The sequence number of the actual first data byte and the acknowledged number in the corresponding ACK are then this sequence number plus 1.
+          If the SYN flag is clear (0), then this is the accumulated sequence number of the first data byte of this packet for the current session.
+
+      Acknowledgment number (32 bits) – if the ACK flag is set then the value of this field is the next sequence number that the receiver is expecting. This acknowledges receipt of all prior bytes (if any). The first ACK sent by each end acknowledges the other end's initial sequence number itself, but no data.
+      Data offset (4 bits) – specifies the size of the TCP header in 32-bit words. The minimum size header is 5 words and the maximum is 15 words thus giving the minimum size of 20 bytes and maximum of 60 bytes, allowing for up to 40 bytes of options in the header. This field gets its name from the fact that it is also the offset from the start of the TCP segment to the actual data.
+      Reserved (4 bits) – for future use and should be set to zero
+      Flags (8 bits) (aka Control bits) – contains 8 1-bit flags
+
+          CWR (1 bit) – Congestion Window Reduced (CWR) flag is set by the sending host to indicate that it received a TCP segment with the ECE flag set and had responded in congestion control mechanism (added to header by RFC 3168).
+          ECE (1 bit) – ECN-Echo indicates
+
+              If the SYN flag is set (1), that the TCP peer is ECN capable.
+              If the SYN flag is clear (0), that a packet with Congestion Experienced flag in IP header set is received during normal transmission (added to header by RFC 3168).
+
+          URG (1 bit) – indicates that the Urgent pointer field is significant
+          ACK (1 bit) – indicates that the Acknowledgment field is significant. All packets after the initial SYN packet sent by the client should have this flag set.
+          PSH (1 bit) – Push function. Asks to push the buffered data to the receiving application.
+          RST (1 bit) – Reset the connection
+          SYN (1 bit) – Synchronize sequence numbers. Only the first packet sent from each end should have this flag set. Some other flags change meaning based on this flag, and some are only valid for when it is set, and others when it is clear.
+          FIN (1 bit) – No more data from sender
+
+      Window size (16 bits) – the size of the receive window, which specifies the number of bytes (beyond the sequence number in the acknowledgment field) that the receiver is currently willing to receive (see Flow control and Window Scaling)
+      Checksum (16 bits) – The 16-bit checksum field is used for error-checking of the header and data
+      Urgent pointer (16 bits) – if the URG flag is set, then this 16-bit field is an offset from the sequence number indicating the last urgent data byte
+      Options (Variable 0-320 bits, divisible by 32) – The length of this field is determined by the data offset field. Options 0 and 1 are a single byte (8 bits) in length. The remaining options indicate the total length of the option (expressed in bytes) in the second byte.
+      Padding – The TCP header padding is used to ensure that the TCP header ends and data begins on a 32 bit boundary. The padding is composed of zeros.[6]
+
+  Some options may only be sent when SYN is set; they are indicated below as [SYN].
+
+          0 (8 bits) - End of options list
+          1 (8 bits) - No operation (NOP, Padding) This may be used to align option fields on 32-bit boundaries for better performance.
+          2,4,SS (32 bits) - Maximum segment size (see maximum segment size) [SYN]
+          3,3,S (24 bits) - Window scale (see window scaling for details) [SYN][7]
+          4,2 (16 bits) - Selective Acknowledgement permitted. [SYN] (See selective acknowledgments for details)[8]
+          5,N,BBBB,EEEE,... (variable bits, N is either 10, 18, 26, or 34)- Selective ACKnowledgement (SACK)[9] These first two bytes are followed by a list of 1-4 blocks being selectively acknowledged, specified as 32-bit begin/end pointers.
+          8,10,TTTT,EEEE (80 bits)- Timestamp and echo of previous timestamp (see TCP timestamps for details)[10]
+          14,3,S (24 bits) - TCP Alternate Checksum Request. [SYN][11]
+          15,N,... (variable bits) - TCP Alternate Checksum Data.
+
+      (The remaining options are obsolete, experimental, not yet standardized, or unassigned)
+
+  Protocol operation
+  A Simplified TCP State Diagram. See TCP EFSM diagram for a more detailed state diagram including the states inside the ESTABLISHED state.
+
+  TCP protocol operations may be divided into three phases. Connections must be properly established in a multi-step handshake process (connection establishment) before entering the data transfer phase. After data transmission is completed, the connection termination closes established virtual circuits and releases all allocated resources.
+
+  A TCP connection is managed by an operating system through a programming interface that represents the local end-point for communications, the Internet socket. During the lifetime of a TCP connection it undergoes a series of state changes:[12]
+
+      LISTENING : In case of a server, waiting for a connection request from any remote client.
+      SYN-SEND : waiting for the remote peer to send back a TCP segment with the SYN and ACK flags set. (usually set by TCP clients)
+      SYN-RECEIVED : waiting for the remote peer to send back an acknowledgment after having sent back a connection acknowledgment to the remote peer. (usually set by TCP servers)
+      ESTABLISHED : the port is ready to receive/send data from/to the remote peer.
+      FIN-WAIT-1 :
+      FIN-WAIT-2 :Indicates that the client is waiting for the servers fin segment ( which indicates the servers application process is ready to close and the server is ready to initiate it's side of the connection termination)
+      CLOSE-WAIT :
+      LAST-ACK : indicates that the server is in the process of sending it's own fin segment ( which indicates the server's application process is ready to close and the server is ready to initiate it's side of the connection termination )
+      TIME-WAIT : represents waiting for enough time to pass to be sure the remote peer received the acknowledgment of its connection termination request. According to RFC 793 a connection can stay in TIME-WAIT for a maximum of four minutes know as a MSL (maximum segment lifetime).
+      CLOSED : connection is closed
+
+  Connection establishment
+
+  To establish a connection, TCP uses a three-way handshake. Before a client attempts to connect with a server, the server must first bind to a port to open it up for connections: this is called a passive open. Once the passive open is established, a client may initiate an active open. To establish a connection, the three-way (or 3-step) handshake occurs:
+
+      SYN: The active open is performed by the client sending a SYN to the server. It sets the segment's sequence number to a random value A.
+      SYN-ACK: In response, the server replies with a SYN-ACK. The acknowledgment number is set to one more than the received sequence number (A + 1), and the sequence number that the server chooses for the packet is another random number, B.
+      ACK: Finally, the client sends an ACK back to the server. The sequence number is set to the received acknowledgement value i.e. A + 1, and the acknowledgement number is set to one more than the received sequence number i.e. B + 1.
+
+  At this point, both the client and server have received an acknowledgment of the connection.
+  Resource usage
+
+  Most implementations allocate an entry in a table that maps a session to a running operating system process. Because TCP packets do not include a session identifier, both endpoints identify the session using the client's address and port. Whenever a packet is received, the TCP implementation must perform a lookup on this table to find the destination process.
+
+  The number of sessions in the server side is limited only by memory and can grow as new connections arrive, but the client must allocate a random port before sending the first SYN to the server. This port remains allocated during the whole conversation, and effectively limits the number of outgoing connections from each of the client's IP addresses. If an application fails to properly close unrequired connections, a client can run out of resources and become unable to establish new TCP connections, even from other applications.
+
+  Both endpoints must also allocate space for unacknowledged packets and received (but unread) data.
+  Data transfer
+
+  There are a few key features that set TCP apart from User Datagram Protocol:
+
+      Ordered data transfer - the destination host rearranges according to sequence number[2]
+      Retransmission of lost packets - any cumulative stream not acknowledged is retransmitted[2]
+      Error-free data transfer[13]
+      Flow control - limits the rate a sender transfers data to guarantee reliable delivery. The receiver continually hints the sender on how much data can be received (controlled by the sliding window). When the receiving host's buffer fills, the next acknowledgment contains a 0 in the window size, to stop transfer and allow the data in the buffer to be processed.[2]
+      Congestion control [2]
+
+  Reliable transmission
+
+  TCP uses a sequence number to identify each segment of data. The sequence number identifies the order of the segments sent from each computer so that the data can be reconstructed in order, regardless of any fragmentation, disordering, or packet loss that may occur during transmission. For every payload segment transmitted the sequence number must be incremented. In the first two steps of the 3-way handshake, both computers exchange an initial sequence number (ISN). This number can be arbitrary, and should in fact be unpredictable to defend against TCP Sequence Prediction Attacks.
+
+  TCP primarily uses a cumulative acknowledgment scheme, where the receiver sends an acknowledgment signifying that the receiver has received all data preceding the acknowledged sequence number. Essentially, the first byte in a segment's data field is assigned a sequence number, which is inserted in the sequence number field, and the receiver sends an acknowledgment specifying the sequence number of the next segment they expect to receive. For example, if computer A sends 4 segments with a sequence number of 100 (conceptually, the four segments would have a sequence number of 100, 101, 102 and 103 assigned) then the receiver would send back an acknowledgment of 104 since that is the next segment it expects to receive in the next packet.
+
+  In addition to cumulative acknowledgments, TCP receivers can also send selective acknowledgments to provide further information.
+
+  If the sender infers that data has been lost in the network, it retransmits the data.
+  Error detection
+
+  Sequence numbers and acknowledgments cover discarding duplicate packets, retransmission of lost packets, and ordered-data transfer. To assure correctness a checksum field is included (see TCP segment structure for details on checksumming).
+
+  The TCP checksum is a weak check by modern standards. Data Link Layers with high bit error rates may require additional link error correction/detection capabilities. The weak checksum is partially compensated for by the common use of a CRC or better integrity check at layer 2, below both TCP and IP, such as is used in PPP or the Ethernet frame. However, this does not mean that the 16-bit TCP checksum is redundant: remarkably, introduction of errors in packets between CRC-protected hops is common, but the end-to-end 16-bit TCP checksum catches most of these simple errors.[14] This is the end-to-end principle at work.
+  Flow control
+
+  TCP uses an end-to-end flow control protocol to avoid having the sender send data too fast for the TCP receiver to receive and process it reliably. Having a mechanism for flow control is essential in an environment where machines of diverse network speeds communicate. For example, if a PC sends data to a hand-held PDA that is slowly processing received data, the PDA must regulate data flow so as not to be overwhelmed.[2]
+
+  TCP uses a sliding window flow control protocol. In each TCP segment, the receiver specifies in the receive window field the amount of additional received data (in bytes) that it is willing to buffer for the connection. The sending host can send only up to that amount of data before it must wait for an acknowledgment and window update from the receiving host.
+  TCP sequence numbers and receive windows behave very much like a clock. The receive window shifts each time the receiver receives and acknowledges a new segment of data. Once it runs out of sequence numbers, the sequence number loops back to 0.
+
+  When a receiver advertises a window size of 0, the sender stops sending data and starts the persist timer. The persist timer is used to protect TCP from a deadlock situation that could arise if a subsequent window size update from the receiver is lost, and the sender cannot send more data until receiving a new window size update from the receiver. When the persist timer expires, the TCP sender attempts recovery by sending a small packet so that the receiver responds by sending another acknowledgement containing the new window size.
+
+  If a receiver is processing incoming data in small increments, it may repeatedly advertise a small receive window. This is referred to as the silly window syndrome, since it is inefficient to send only a few bytes of data in a TCP segment, given the relatively large overhead of the TCP header. TCP senders and receivers typically employ flow control logic to specifically avoid repeatedly sending small segments. The sender-side silly window syndrome avoidance logic is referred to as Nagle's algorithm.
+  Congestion control
+
+  The final main aspect of TCP is congestion control. TCP uses a number of mechanisms to achieve high performance and avoid congestion collapse, where network performance can fall by several orders of magnitude. These mechanisms control the rate of data entering the network, keeping the data flow below a rate that would trigger collapse. They also yield an approximately max-min fair allocation between flows.
+
+  Acknowledgments for data sent, or lack of acknowledgments, are used by senders to infer network conditions between the TCP sender and receiver. Coupled with timers, TCP senders and receivers can alter the behavior of the flow of data. This is more generally referred to as congestion control and/or network congestion avoidance.
+
+  Modern implementations of TCP contain four intertwined algorithms: Slow-start, congestion avoidance, fast retransmit, and fast recovery (RFC 5681).
+
+  In addition, senders employ a retransmission timeout (RTO) that is based on the estimated round-trip time (or RTT) between the sender and receiver, as well as the variance in this round trip time. The behavior of this timer is specified in RFC 2988. There are subtleties in the estimation of RTT. For example, senders must be careful when calculating RTT samples for retransmitted packets; typically they use Karn's Algorithm or TCP timestamps (see RFC 1323). These individual RTT samples are then averaged over time to create a Smoothed Round Trip Time (SRTT) using Jacobson's algorithm. This SRTT value is what is finally used as the round-trip time estimate.
+
+  Enhancing TCP to reliably handle loss, minimize errors, manage congestion and go fast in very high-speed environments are ongoing areas of research and standards development. As a result, there are a number of TCP congestion avoidance algorithm variations.
+  Maximum segment size
+
+  The Maximum segment size (MSS) is the largest amount of data, specified in bytes, that TCP is willing to send in a single segment. For best performance, the MSS should be set small enough to avoid IP fragmentation, which can lead to excessive retransmissions if there is packet loss. To try to accomplish this, typically the MSS is negotiated using the MSS option when the TCP connection is established, in which case it is determined by the maximum transmission unit (MTU) size of the data link layer of the networks to which the sender and receiver are directly attached. Furthermore, TCP senders can use Path MTU discovery to infer the minimum MTU along the network path between the sender and receiver, and use this to dynamically adjust the MSS to avoid IP fragmentation within the network.
+
+  Strictly speaking, the MSS is not negotiated between the originator and the receiver, because that would imply that both originator and receiver will negotiate and agree upon a single, unified MSS that applies to all communication in both directions of the connection. In fact, two completely independent values of MSS are permitted for the two directions of data flow in a TCP connection.[15] This situation may arise, for example, if one of the devices participating in a connection has an extremely limited amount memory reserved (perhaps even smaller than the overall discovered Path MTU) for processing incoming TCP segments.
+  Selective acknowledgments
+
+  Relying purely on the cumulative acknowledgment scheme employed by the original TCP protocol can lead to inefficiencies when packets are lost. For example, suppose 10,000 bytes are sent in 10 different TCP packets, and the first packet is lost during transmission. In a pure cumulative acknowledgment protocol, the receiver cannot say that it received bytes 1,000 to 9,999 successfully, but failed to receive the first packet, containing bytes 0 to 999. Thus the sender may then have to resend all 10,000 bytes.
+
+  To solve this problem TCP employs the selective acknowledgment (SACK) option, defined in RFC 2018, which allows the receiver to acknowledge discontinuous blocks of packets that were received correctly, in addition to the sequence number of the last contiguous byte received successively, as in the basic TCP acknowledgment. The acknowledgement can specify a number of SACK blocks, where each SACK block is conveyed by the starting and ending sequence numbers of a contiguous range that the receiver correctly received. In the example above, the receiver would send SACK with sequence numbers 1,000 and 9,999. The sender thus retransmits only the first packet, bytes 0 to 999.
+
+  An extension to the SACK option is the "duplicate-SACK" option, defined in RFC 2883. An out-of-order packet delivery can often falsely indicate the TCP sender of lost packet and, in turn, the TCP sender retransmits the suspected-to-be-lost packet and slow down the data delivery to prevent network congestion. The TCP sender undoes the action of slow-down, that is a recovery of the original pace of data transmission, upon receiving a D-SACK that indicates the retransmitted packet is duplicate.
+
+  The SACK option is not mandatory and it is used only if both parties support it. This is negotiated when connection is established. SACK uses the optional part of the TCP header (see TCP segment structure for details). The use of SACK is widespread - all popular TCP stacks support it. Selective acknowledgment is also used in Stream Control Transmission Protocol (SCTP).
+  Window scaling
+  Main article: TCP window scale option
+
+  For more efficient use of high bandwidth networks, a larger TCP window size may be used. The TCP window size field controls the flow of data and its value is limited to between 2 and 65,535 bytes.
+
+  Since the size field cannot be expanded, a scaling factor is used. The TCP window scale option, as defined in RFC 1323, is an option used to increase the maximum window size from 65,535 bytes to 1 Gigabyte. Scaling up to larger window sizes is a part of what is necessary for TCP Tuning.
+
+  The window scale option is used only during the TCP 3-way handshake. The window scale value represents the number of bits to left-shift the 16-bit window size field. The window scale value can be set from 0 (no shift) to 14 for each direction independently. Both sides must send the option in their SYN segments to enable window scaling in either direction.
+
+  Some routers and packet firewalls rewrite the window scaling factor during a transmission. This causes sending and receiving sides to assume different TCP window sizes. The result is non-stable traffic that may be very slow. The problem is visible on some sending and receiving sites behind the path of defective routers.[16]
+  TCP timestamps
+
+  TCP timestamps, defined in RFC 1323, help TCP compute the round-trip time between the sender and receiver. Timestamp options include a 4-byte timestamp value, where the sender inserts its current value of its timestamp clock, and a 4-byte echo reply timestamp value, where the receiver generally inserts the most recent timestamp value that it has received. The sender uses the echo reply timestamp in an acknowledgement to compute the total elapsed time since the acknowledged segment was sent.[2]
+
+  TCP timestamps are also used to help in the case where TCP sequence numbers encounter their 232 bound and "wrap around" the sequence number space. This scheme is known as Protect Against Wrapped Sequence numbers, or PAWS (see RFC 1323 for details). Furthermore, the Eifel detection algorithm, defined in RFC 3522, which detects unnecessary loss recovery requires TCP timestamps.
+  Out of band data
+
+  One is able to interrupt or abort the queued stream instead of waiting for the stream to finish. This is done by specifying the data as urgent. This tells the receiving program to process it immediately, along with the rest of the urgent data. When finished, TCP informs the application and resumes back to the stream queue. An example is when TCP is used for a remote login session, the user can send a keyboard sequence that interrupts or aborts the program at the other end. These signals are most often needed when a program on the remote machine fails to operate correctly. The signals must be sent without waiting for the program to finish its current transfer.[2]
+
+  TCP OOB data was not designed for the modern Internet. The urgent pointer only alters the processing on the remote host and doesn't expedite any processing on the network itself. When it gets to the remote host there are two slightly different interpretations of the protocol, which means only single bytes of OOB data are reliable. This is assuming it's reliable at all as it's one of the least commonly used protocol elements and tends to be poorly implemented. [17][18]
+  Forcing data delivery
+
+  Normally, TCP waits for the buffer to exceed the maximum segment size before sending any data. This creates serious delays when the two sides of the connection are exchanging short messages and need to receive the response before continuing. For example, the login sequence at the beginning of a telnet session begins with the short message "Login", and the session cannot make any progress until these five characters have been transmitted and the response has been received. This process can be seriously delayed by TCP's normal behavior when the message is provided to TCP in several send calls.
+
+  However, an application can force delivery of segments to the output stream using a push operation provided by TCP to the application layer.[2] This operation also causes TCP to set the PSH flag or control bit to ensure that data is delivered immediately to the application layer by the receiving transport layer.
+
+  In the most extreme cases, for example when a user expects each keystroke to be echoed by the receiving application, the push operation can be used each time a keystroke occurs. More generally, application programs use this function to force output to be sent after writing a character or line of characters. By forcing the data to be sent immediately, delays and wait time are reduced.
+  Connection termination
+
+  The connection termination phase uses, at most, a four-way handshake, with each side of the connection terminating independently. When an endpoint wishes to stop its half of the connection, it transmits a FIN packet, which the other end acknowledges with an ACK. Therefore, a typical tear-down requires a pair of FIN and ACK segments from each TCP endpoint. After both FIN/ACK exchanges are concluded, the terminating side waits for a timeout before finally closing the connection, during which time the local port is unavailable for new connections; this prevents confusion due to delayed packets being delivered during subsequent connections.
+
+  A connection can be "half-open", in which case one side has terminated its end, but the other has not. The side that has terminated can no longer send any data into the connection, but the other side can. The terminating side should continue reading the data until the other side terminates as well.
+
+  It is also possible to terminate the connection by a 3-way handshake, when host A sends a FIN and host B replies with a FIN & ACK (merely combines 2 steps into one) and host A replies with an ACK.[19] This is perhaps the most common method.
+
+  It is possible for both hosts to send FINs simultaneously then both just have to ACK. This could possibly be considered a 2-way handshake since the FIN/ACK sequence is done in parallel for both directions.
+
+  Some host TCP stacks may implement a "half-duplex" close sequence, as Linux or HP-UX do. If such a host actively closes a connection but still has not read all the incoming data the stack already received from the link, this host sends a RST instead of a FIN (Section 4.2.2.13 in RFC 1122). This allows a TCP application to be sure the remote application has read all the data the former sent—waiting the FIN from the remote side, when it actively closes the connection. However, the remote TCP stack cannot distinguish between a Connection Aborting RST and this Data Loss RST. Both cause the remote stack to throw away all the data it received, but that the application still didn't read.[clarification needed]
+
+  Some application protocols may violate the OSI model layers, using the TCP open/close handshaking for the application protocol open/close handshaking - these may find the RST problem on active close. As an example:
+
+  s = connect(remote);
+  send(s, data);
+  close(s);
+
+  For a usual program flow like above, a TCP/IP stack like that described above does not guarantee that all the data arrives to the other application.
+  Vulnerabilities
+
+  TCP may be attacked in a variety of ways. The results of a thorough security assessment of the TCP, along with possible mitigations for the identified issues, was published in 2009,[20] and is currently being pursued within the IETF.[21]
+  Denial of service
+
+  By using a spoofed IP address and repeatedly sending purposely assembled SYN packets, attackers can cause the server to consume large amounts of resources keeping track of the bogus connections. This is known as a SYN flood attack. Proposed solutions to this problem include SYN cookies and Cryptographic puzzles. Sockstress is a similar attack, that might be mitigated with system resource management.[22] An advanced DoS attack involving the exploitation of the TCP Persist Timer was analyzed at Phrack #66.[23]
+  Connection hijacking
+  Main article: TCP sequence prediction attack
+
+  An attacker who is able to eavesdrop a TCP session and redirect packets can hijack a TCP connection. To do so, the attacker learns the sequence number from the ongoing communication and forges a false segment that looks like the next segment in the stream. Such a simple hijack can result in one packet being erroneously accepted at one end. When the receiving host acknowledges the extra segment to the other side of the connection, synchronization is lost. Hijacking might be combined with ARP or routing attacks that allow taking control of the packet flow, so as to get permanent control of the hijacked TCP connection.[24]
+
+  Impersonating a different IP address was not difficult prior to RFC 1948, when the initial sequence number was easily guessable. That allowed an attacker to blindly send a sequence of packets that the receiver would believe to come from a different IP address, without the need to deploy ARP or routing attacks: it is enough to ensure that the legitimate host of the impersonated IP address is down, or bring it to that condition using denial of service attacks. This is why the initial sequence number is chosen at random.
+  TCP ports
+  Main article: TCP and UDP port
+
+  TCP uses the notion of port numbers to identify sending and receiving application end-points on a host, or Internet sockets. Each side of a TCP connection has an associated 16-bit unsigned port number (0-65535) reserved by the sending or receiving application. Arriving TCP data packets are identified as belonging to a specific TCP connection by its sockets, that is, the combination of source host address, source port, destination host address, and destination port. This means that a server computer can provide several clients with several services simultaneously, as long as a client takes care of initiating any simultaneous connections to one destination port from different source ports.
+
+  Port numbers are categorized into three basic categories: well-known, registered, and dynamic/private. The well-known ports are assigned by the Internet Assigned Numbers Authority (IANA) and are typically used by system-level or root processes. Well-known applications running as servers and passively listening for connections typically use these ports. Some examples include: FTP (21), SSH (22), TELNET (23), SMTP (25) and HTTP (80). Registered ports are typically used by end user applications as ephemeral source ports when contacting servers, but they can also identify named services that have been registered by a third party. Dynamic/private ports can also be used by end user applications, but are less commonly so. Dynamic/private ports do not contain any meaning outside of any particular TCP connection.
+  Development
+
+  TCP is a complex protocol. However, while significant enhancements have been made and proposed over the years, its most basic operation has not changed significantly since its first specification RFC 675 in 1974, and the v4 specification RFC 793, published in September 1981. RFC 1122, Host Requirements for Internet Hosts, clarified a number of TCP protocol implementation requirements. RFC 2581, TCP Congestion Control, one of the most important TCP-related RFCs in recent years, describes updated algorithms that avoid undue congestion. In 2001, RFC 3168 was written to describe explicit congestion notification (ECN), a congestion avoidance signaling mechanism.
+
+  The original TCP congestion avoidance algorithm was known as "TCP Tahoe", but many alternative algorithms have since been proposed (including TCP Reno, TCP Vegas, FAST TCP, TCP New Reno, and TCP Hybla).
+
+  TCP Interactive (iTCP) [25] is a research effort into TCP extensions that allows applications to subscribe to TCP events and register handler components that can launch applications for various purposes, including application-assisted congestion control.
+
+  Multipath TCP (MPTCP) [26] is an ongoing effort within the IETF that aims at allowing a TCP connection to use multiple paths to maximise resource usage and increase redundancy. The redundancy offered by Multipath TCP in the context of wireless networks [27] enables statistical multiplexing of resources, and thus increases TCP throughput dramatically.
+
+  TCP Cookie Transactions (TCPCT) is an extension proposed in December 2009 to secure servers against denial-of-service attacks. Unlike SYN cookies, TCPCT does not conflict with other TCP extensions such as window scaling. TCPCT was designed due to necessities of DNSSEC, where servers have to handle large numbers of short-lived TCP connections.
+
+  tcpcrypt is an extension proposed in July 2010 to provide transport-level encryption directly in TCP itself. It's designed to work transparently and not require any configuration. Unlike TLS (SSL), tcpcrypt itself does not provide authentication, but provides simple primitives down to the application to do that. As of 2010, the first tcpcrypt IETF draft has been published and implementations exist for several major platforms.
+  TCP over wireless networks
+
+  TCP has been optimized for wired networks. Any packet loss is considered to be the result of network congestion and the congestion window size is reduced dramatically as a precaution. However, wireless links are known to experience sporadic and usually temporary losses due to fading, shadowing, hand off, and other radio effects, that cannot be considered congestion. After the (erroneous) back-off of the congestion window size, due to wireless packet loss, there can be a congestion avoidance phase with a conservative decrease in window size. This causes the radio link to be underutilized. Extensive research has been done on the subject of how to combat these harmful effects. Suggested solutions can be categorized as end-to-end solutions (which require modifications at the client or server),[28] link layer solutions (such as RLP in CDMA2000), or proxy based solutions (which require some changes in the network without modifying end nodes.[28][29]
+  Hardware implementations
+
+  One way to overcome the processing power requirements of TCP is to build hardware implementations of it, widely known as TCP Offload Engines (TOE). The main problem of TOEs is that they are hard to integrate into computing systems, requiring extensive changes in the operating system of the computer or device. One company to develop such a device was Alacritech.
+  Debugging
+
+  A packet sniffer, which intercepts TCP traffic on a network link, can be useful in debugging networks, network stacks and applications that use TCP by showing the user what packets are passing through a link. Some networking stacks support the SO_DEBUG socket option, which can be enabled on the socket using setsockopt. That option dumps all the packets, TCP states, and events on that socket, which is helpful in debugging. Netstat is another utility that can be used for debugging.
+  Alternatives
+
+  For many applications TCP is not appropriate. One big problem (at least with normal implementations) is that the application cannot get at the packets coming after a lost packet until the retransmitted copy of the lost packet is received. This causes problems for real-time applications such as streaming multimedia (such as Internet radio), real-time multiplayer games and voice over IP (VoIP) where it is sometimes more useful to get most of the data in a timely fashion than it is to get all of the data in order.
+
+  For both historical and performance reasons, most storage area networks (SANs) prefer to use Fibre Channel protocol (FCP) instead of TCP/IP.
+
+  Also for embedded systems, network booting and servers that serve simple requests from huge numbers of clients (e.g. DNS servers) the complexity of TCP can be a problem. Finally, some tricks such as transmitting data between two hosts that are both behind NAT (using STUN or similar systems) are far simpler without a relatively complex protocol like TCP in the way.
+
+  Generally, where TCP is unsuitable, the User Datagram Protocol (UDP) is used. This provides the application multiplexing and checksums that TCP does, but does not handle building streams or retransmission, giving the application developer the ability to code them in a way suitable for the situation, or to replace them with other methods like forward error correction or interpolation.
+
+  SCTP is another IP protocol that provides reliable stream oriented services similar to TCP. It is newer and considerably more complex than TCP, and has not yet seen widespread deployment. However, it is especially designed to be used in situations where reliability and near-real-time considerations are important.
+
+  Venturi Transport Protocol (VTP) is a patented proprietary protocol that is designed to replace TCP transparently to overcome perceived inefficiencies related to wireless data transport.
+
+  TCP also has issues in high bandwidth environments. The TCP congestion avoidance algorithm works very well for ad-hoc environments where the data sender is not known in advance, but if the environment is predictable, a timing based protocol such as Asynchronous Transfer Mode (ATM) can avoid TCP's retransmits overhead.
+
+  Multipurpose Transaction Protocol (MTP/IP) is patented proprietary software that is designed to adaptively achieve high throughput and transaction performance in a wide variety of network conditions, particularly those where TCP is perceived to be inefficient.
+  Checksum computation
+  TCP checksum for IPv4
+
+  When TCP runs over IPv4, the method used to compute the checksum is defined in RFC 793:
+
+      The checksum field is the 16 bit one's complement of the one's complement sum of all 16-bit words in the header and text. If a segment contains an odd number of header and text octets to be checksummed, the last octet is padded on the right with zeros to form a 16-bit word for checksum purposes. The pad is not transmitted as part of the segment. While computing the checksum, the checksum field itself is replaced with zeros.
+
+  In other words, after appropriate padding, all 16-bit words are added using one's complement arithmetic. The sum is then bitwise complemented and inserted as the checksum field. A pseudo-header that mimics the IPv4 packet header used in the checksum computation is shown in the table below.
+  TCP pseudo-header (IPv4) Bit offset 	0–3 	4–7 	8–15 	16–31
+  0 	Source address
+  32 	Destination address
+  64 	Zeros 	Protocol 	TCP length
+  96 	Source port 	Destination port
+  128 	Sequence number
+  160 	Acknowledgement number
+  192 	Data offset 	Reserved 	Flags 	Window
+  224 	Checksum 	Urgent pointer
+  256 	Options (optional)
+  256/288+ 	 
+  Data
+
+
+  The source and destination addresses are those of the IPv4 header. The protocol value is 6 for TCP (cf. List of IP protocol numbers). The TCP length field is the length of the TCP header and data.
+  TCP checksum for IPv6
+
+  When TCP runs over IPv6, the method used to compute the checksum is changed, as per RFC 2460:
+
+      Any transport or other upper-layer protocol that includes the addresses from the IP header in its checksum computation must be modified for use over IPv6, to include the 128-bit IPv6 addresses instead of 32-bit IPv4 addresses.
+
+  A pseudo-header that mimics the IPv6 header for computation of the checksum is shown below.
+  TCP pseudo-header (IPv6) Bit offset 	0 - 7 	8–15 	16–23 	24–31
+  0 	Source address
+  32
+  64
+  96
+  128 	Destination address
+  160
+  192
+  224
+  256 	TCP length
+  288 	Zeros 	Next header
+  320 	Source port 	Destination port
+  352 	Sequence number
+  384 	Acknowledgement number
+  416 	Data offset 	Reserved 	Flags 	Window
+  448 	Checksum 	Urgent pointer
+  480 	Options (optional)
+  480/512+ 	 
+  Data
+
+
+      Source address – the one in the IPv6 header
+      Destination address – the final destination; if the IPv6 packet doesn't contain a Routing header, TCP uses the destination address in the IPv6 header, otherwise, at the originating node, it uses the address in the last element of the Routing header, and, at the receiving node, it uses the destination address in the IPv6 header.
+      TCP length – the length of the TCP header and data
+      Next Header – the protocol value for TCP
+
+  Checksum offload
+
+  Many TCP/IP software stack implementations provide options to use hardware assistance to automatically compute the checksum in the network adapter prior to transmission onto the network or upon reception from the network for validation.
+  MESSAGE
+
+  payload = message * 87
+
+  puts "Publishing a message #{payload.bytesize} bytes in size"
+  exchange.publish(payload, :routing_key => queue.name)
+}
+
+t.join

data/examples/publishing/returned_messages.rb

@@ -0,0 +1,40 @@
+#!/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 "=> Handling message returns"
+puts
+
+AMQP.start(:host => '127.0.0.1') do |connection|
+  channel  = AMQP.channel
+  channel.on_error { EM.stop; raise 'channel error' }
+
+  exchange = channel.fanout("amq.fanout")
+  exchange.on_return do |basic_return, header, payload|
+    puts "#{payload} was returned! reply_code = #{basic_return.reply_code}, reply_text = #{basic_return.reply_text}"
+  end
+
+  EventMachine.add_timer(0.3) {
+    10.times do |i|
+      exchange.publish("Message ##{i}", :immediate => true)
+    end    
+  }
+
+  EventMachine.add_timer(2) {
+    connection.close {
+      EventMachine.stop
+    }
+  }
+end

data/lib/amqp/channel.rb

@@ -225,7 +225,7 @@ module AMQP
 
       # only send channel.open when connection is actually open. Makes it possible to
       # do c = AMQP.connect; AMQP::Channel.new(c) that is what some people do. MK.
-      @connection.on_open do
+      @connection.on_connection do
         self.open do |ch, open_ok|
           @channel_is_open_deferrable.succeed
 

data/lib/amqp/session.rb

@@ -51,22 +51,11 @@ module AMQP
     end # reconnect(force = false)
 
 
-    # Defines a callback that will be executed when AMQP connection is considered open,
+    # Defines a callback that will be executed when AMQP connection is considered open:
     # after client and broker has agreed on max channel identifier and maximum allowed frame
-    # size. You can define more than one callback.
+    # size and authentication succeeds. You can define more than one callback.
     #
-    # @see #on_open
-    # @api public
-    def on_connection(&block)
-      # defined here to make this method appear in YARD documentation. MK.
-      super(&block)
-    end # on_connection(&block)
-
-    # Defines a callback that will be executed when AMQP connection is considered open,
-    # before client and broker has agreed on max channel identifier and maximum allowed frame
-    # size. You can define more than one callback.
-    #
-    # @see #on_connection
+    # @see #on_closed
     # @api public
     def on_open(&block)
       # defined here to make this method appear in YARD documentation. MK.
@@ -76,11 +65,12 @@ module AMQP
     # Defines a callback that will be run when broker confirms connection termination
     # (client receives connection.close-ok). You can define more than one callback.
     #
+    # @see #on_closed
     # @api public
-    def on_disconnection(&block)
+    def on_closed(&block)
       # defined here to make this method appear in YARD documentation. MK.
       super(&block)
-    end # on_disconnection(&block)
+    end # on_closed(&block)
 
     # Defines a callback that will be run when initial TCP connection fails.
     # You can define only one callback.

data/lib/amqp/utilities/event_loop_helper.rb

@@ -59,6 +59,12 @@ module AMQP
       #
       # @note This method, unlike EventMachine.run, DOES NOT block current thread.
       def self.run(&block)
+        if reactor_running?
+          EventMachine.run(&block)
+
+          return
+        end
+
         @eventmachine_thread  ||= begin
                                     case self.server_type
                                     when :thin, :goliath, :evented_mongrel then
@@ -78,6 +84,8 @@ module AMQP
                                       t
                                     end
                                   end
+
+        @eventmachine_thread
       end # self.run
 
 

data/lib/amqp/version.rb

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

data/spec/integration/authentication_spec.rb

@@ -7,7 +7,7 @@ describe "Authentication attempt" do
   # Environment
   #
 
-  include EventedSpec::AMQPSpec
+  include EventedSpec::EMSpec
   include EventedSpec::SpecHelper
 
 
@@ -71,6 +71,22 @@ describe "Authentication attempt" do
           connection = AMQP.connect(:username => "amqp_gem", :password => Time.now.to_i.to_s, :vhost => "/amqp_gem_testbed", :on_possible_authentication_failure => handler)
         end # it
       end
+
+
+      context "and provided vhost DOES NOT EXIST" do
+        default_timeout 10
+
+        after(:all) { done }
+
+        it "fails" do
+          handler = Proc.new { |settings|
+            puts "Callback has fired"
+            callback_has_fired = true
+            done
+          }
+          connection = AMQP.connect(:username => "amqp_gem", :password => Time.now.to_i.to_s, :vhost => "/a/b/c/#{rand}/#{Time.now.to_i}", :on_possible_authentication_failure => handler)
+        end # it
+      end
     end # context
   end
 

data/spec/integration/extensions/basic_return_spec.rb

@@ -21,7 +21,7 @@ describe "Message published as mandatory" do
     @channel   = AMQP::Channel.new
     @channel.should be_open
 
-    @exchange = @channel.fanout
+    @exchange = @channel.fanout("amqpgem.specs.#{Time.now.to_i}", :auto_delete => true, :durable => false)
   end
 
   after(:all) do
@@ -34,7 +34,7 @@ describe "Message published as mandatory" do
     it "is returned to the publisher via basic.return" do
       returned_messages  = []
 
-      @exchange.on_return do |basic_return|
+      @exchange.on_return do |basic_return, header, body|
         returned_messages << basic_return.reply_text
       end
       (1..10).to_a.each { |m| @exchange.publish(m, :immediate => true) }

metadata

@@ -1,67 +1,48 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: amqp
-version: !ruby/object:Gem::Version 
-  hash: 15424129
+version: !ruby/object:Gem::Version
+  version: 0.8.0.rc11
   prerelease: 6
-  segments: 
-  - 0
-  - 8
-  - 0
-  - rc
-  - 10
-  version: 0.8.0.rc10
 platform: ruby
-authors: 
+authors:
 - Aman Gupta
 - Jakub Stastny aka botanicus
 - Michael S. Klishin
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-05-12 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2011-05-14 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: eventmachine
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: &2156186280 !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: *2156186280
+- !ruby/object:Gem::Dependency
+  name: amq-client
+  requirement: &2156185780 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: -3702664442
-        segments: 
-        - 0
-        - 7
-        - 0
-        - alpha
-        - 21
-        version: 0.7.0.alpha21
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.7.0.alpha23
   type: :runtime
-  version_requirements: *id002
-description: Widely used, feature-rich asynchronous AMQP 0.9.1 client with batteries included
-email: 
+  prerelease: false
+  version_requirements: *2156185780
+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
@@ -77,7 +58,7 @@ extra_rdoc_files:
 - docs/RabbitMQVersions.textile
 - docs/Routing.textile
 - docs/VendorSpecificExtensions.textile
-files: 
+files:
 - .gitignore
 - .rspec
 - .travis.yml
@@ -116,6 +97,7 @@ files:
 - examples/error_handling/global_channel_level_exception_handler.rb
 - examples/error_handling/handling_authentication_failure_with_a_callback.rb
 - examples/error_handling/handling_authentication_failure_with_a_rescue_block.rb
+- examples/error_handling/handling_vhost_misconfiguration_with_a_rescue_block.rb
 - examples/error_handling/tcp_connection_failure_handling_with_a_rescue_block.rb
 - examples/error_handling/tcp_connection_failure_with_a_callback.rb
 - examples/exchanges/declare_an_exchange_without_assignment.rb
@@ -135,6 +117,7 @@ files:
 - examples/guides/queues/12_deleting_a_queue.rb
 - examples/hello_world.rb
 - examples/hello_world_with_eventmachine_in_a_separate_thread.rb
+- examples/hello_world_with_large_payload.rb
 - examples/legacy/ack.rb
 - examples/legacy/callbacks.rb
 - examples/legacy/clock.rb
@@ -146,6 +129,7 @@ files:
 - examples/legacy/primes.rb
 - examples/legacy/stocks.rb
 - examples/publishing/publishing_and_immediately_stopping_event_loop.rb
+- examples/publishing/returned_messages.rb
 - examples/publishing/simplistic_scatter_gather.rb
 - examples/queues/automatic_binding_for_default_direct_exchange.rb
 - examples/queues/basic_get.rb
@@ -225,38 +209,73 @@ files:
 - tasks.rb
 homepage: http://github.com/ruby-amqp/amqp
 licenses: []
-
-post_install_message: 
-rdoc_options: 
+post_install_message: ! "[\e[32mVersion 0.8.0\e[0m] [FEATURE] Returned messages, including
+  header & content via AMQP::Exchange#on_publish. Callback accepts 3 args: basic_return,
+  header, body\n[\e[32mVersion 0.8.0\e[0m] [BUG] Ruby 1.8.7-p249 is not supported
+  because of this (p249-specific) Ruby bug: http://bit.ly/iONBmH\n[\e[32mVersion 0.8.0\e[0m]
+  [FEATURE] AMQP::Utilities::EventLoopHelper detects app server (if any) being used
+  and starts EventMachine reactor in an optimal way.\n[\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.8.2
+rubygems_version: 1.8.1
 signing_key: 
 specification_version: 3
 summary: AMQP client implementation in Ruby/EventMachine.
 test_files: []
-