activemq-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cmacn...@apache.org
Subject svn commit: r898181 [3/5] - in /activemq/sandbox/activemq-apollo-actor/activemq-amqp-generator: ./ specification/ specification/1.0-PR2/ src/ src/main/ src/main/java/ src/main/java/org/ src/main/java/org/apache/ src/main/java/org/apache/activemq/ src/m...
Date Tue, 12 Jan 2010 04:23:34 GMT
Added: activemq/sandbox/activemq-apollo-actor/activemq-amqp-generator/specification/1.0-PR2/transport.xml
URL: http://svn.apache.org/viewvc/activemq/sandbox/activemq-apollo-actor/activemq-amqp-generator/specification/1.0-PR2/transport.xml?rev=898181&view=auto
==============================================================================
--- activemq/sandbox/activemq-apollo-actor/activemq-amqp-generator/specification/1.0-PR2/transport.xml (added)
+++ activemq/sandbox/activemq-apollo-actor/activemq-amqp-generator/specification/1.0-PR2/transport.xml Tue Jan 12 04:23:30 2010
@@ -0,0 +1,3535 @@
+<?xml version="1.0"?>
+
+<!--
+  Copyright Notice
+  ================
+  (c) Copyright Cisco Systems, Credit Suisse, Deutsche Borse Systems, Envoy Technologies, Inc.,
+  Goldman Sachs, IONA Technologies PLC, iMatix Corporation sprl.,JPMorgan Chase Bank Inc. N.A,
+  Novell, Rabbit Technologies Ltd., Red Hat, Inc., TWIST Process Innovations ltd, and 29West Inc.
+  2006, 2007. All rights reserved.
+
+  License
+  =======
+
+  Cisco Systems, Credit Suisse, Deutsche Borse Systems, Envoy Technologies, Inc.,Goldman Sachs,
+  IONA Technologies PLC, iMatix Corporation sprl.,JPMorgan Chase Bank Inc. N.A, Novell, Rabbit
+  Technologies Ltd., Red Hat, Inc., TWIST Process Innovations ltd, and 29West Inc. (collectively,
+  the "Authors") each hereby grants to you a worldwide, perpetual, royalty-free, nontransferable,
+  nonexclusive license to (i) copy, display, distribute and implement the Advanced Messaging Queue
+  Protocol ("AMQP") Specification and (ii) the Licensed Claims that are held by the Authors, all for
+  the purpose of implementing the Advanced Messaging Queue Protocol Specification. Your license and
+  any rights under this Agreement will terminate immediately without notice from any Author if you
+  bring any claim, suit, demand, or action related to the Advanced Messaging Queue Protocol
+  Specification against any Author. Upon termination, you shall destroy all copies of the Advanced
+  Messaging Queue Protocol Specification in your possession or control.
+
+  As used hereunder, "Licensed Claims" means those claims of a patent or patent application,
+  throughout the world, excluding design patents and design registrations, owned or controlled, or
+  that can be sublicensed without fee and in compliance with the requirements of this Agreement, by
+  an Author or its affiliates now or at any future time and which would necessarily be infringed by
+  implementation of the Advanced Messaging Queue Protocol Specification. A claim is necessarily
+  infringed hereunder only when it is not possible to avoid infringing it because there is no
+  plausible non-infringing alternative for implementing the required portions of the Advanced
+  Messaging Queue Protocol Specification. Notwithstanding the foregoing, Licensed Claims shall not
+  include any claims other than as set forth above even if contained in the same patent as Licensed
+  Claims; or that read solely on any implementations of any portion of the Advanced Messaging Queue
+  Protocol Specification that are not required by the Advanced Messaging Queue Protocol
+  Specification, or that, if licensed, would require a payment of royalties by the licensor to
+  unaffiliated third parties. Moreover, Licensed Claims shall not include (i) any enabling
+  technologies that may be necessary to make or use any Licensed Product but are not themselves
+  expressly set forth in the Advanced Messaging Queue Protocol Specification (e.g., semiconductor
+  manufacturing technology, compiler technology, object oriented technology, networking technology,
+  operating system technology, and the like); or (ii) the implementation of other published
+  standards developed elsewhere and merely referred to in the body of the Advanced Messaging Queue
+  Protocol Specification, or (iii) any Licensed Product and any combinations thereof the purpose or
+  function of which is not required for compliance with the Advanced Messaging Queue Protocol
+  Specification. For purposes of this definition, the Advanced Messaging Queue Protocol
+  Specification shall be deemed to include both architectural and interconnection requirements
+  essential for interoperability and may also include supporting source code artifacts where such
+  architectural, interconnection requirements and source code artifacts are expressly identified as
+  being required or documentation to achieve compliance with the Advanced Messaging Queue Protocol
+  Specification.
+
+  As used hereunder, "Licensed Products" means only those specific portions of products (hardware,
+  software or combinations thereof) that implement and are compliant with all relevant portions of
+  the Advanced Messaging Queue Protocol Specification.
+
+  The following disclaimers, which you hereby also acknowledge as to any use you may make of the
+  Advanced Messaging Queue Protocol Specification:
+
+  THE ADVANCED MESSAGING QUEUE PROTOCOL SPECIFICATION IS PROVIDED "AS IS," AND THE AUTHORS MAKE NO
+  REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF
+  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS
+  OF THE ADVANCED MESSAGING QUEUE PROTOCOL SPECIFICATION ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE
+  IMPLEMENTATION OF THE ADVANCED MESSAGING QUEUE PROTOCOL SPECIFICATION WILL NOT INFRINGE ANY THIRD
+  PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
+
+  THE AUTHORS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
+  DAMAGES ARISING OUT OF OR RELATING TO ANY USE, IMPLEMENTATION OR DISTRIBUTION OF THE ADVANCED
+  MESSAGING QUEUE PROTOCOL SPECIFICATION.
+
+  The name and trademarks of the Authors may NOT be used in any manner, including advertising or
+  publicity pertaining to the Advanced Messaging Queue Protocol Specification or its contents
+  without specific, written prior permission. Title to copyright in the Advanced Messaging Queue
+  Protocol Specification will at all times remain with the Authors.
+
+  No other rights are granted by implication, estoppel or otherwise.
+
+  Upon termination of your license or rights under this Agreement, you shall destroy all copies of
+  the Advanced Messaging Queue Protocol Specification in your possession or control.
+
+  Trademarks
+  ==========
+  "JPMorgan", "JPMorgan Chase", "Chase", the JPMorgan Chase logo and the Octagon Symbol are
+  trademarks of JPMorgan Chase & Co.
+
+  IMATIX and the iMatix logo are trademarks of iMatix Corporation sprl.
+
+  IONA, IONA Technologies, and the IONA logos are trademarks of IONA Technologies PLC and/or its
+  subsidiaries.
+
+  LINUX is a trademark of Linus Torvalds. RED HAT and JBOSS are registered trademarks of Red Hat,
+  Inc. in the US and other countries.
+
+  Java, all Java-based trademarks and OpenOffice.org are trademarks of Sun Microsystems, Inc. in the
+  United States, other countries, or both.
+
+  Other company, product, or service names may be trademarks or service marks of others.
+
+  Links to full AMQP specification:
+  i================================
+  http://www.envoytech.org/spec/amq/
+  http://www.iona.com/opensource/amqp/
+  http://www.redhat.com/solutions/specifications/amqp/
+  http://www.twiststandards.org/tiki-index.php?page=AMQ
+  http://www.imatix.com/amqp
+-->
+
+<!DOCTYPE amqp SYSTEM "amqp.dtd">
+<!-- http://www.amqp.org/schema/amqp.xsd -->
+<amqp xmlns="http://www.amqp.org/schema/amqp.xsd" name="transport" label="working version">
+
+  <!-- == Section: transport =================================================================== -->
+
+  <section name="transport" label="transport overview">
+    <doc>
+      <p>
+        The AMQP Network consists of <i>Nodes</i> connected via <i>Links</i>. Nodes are named
+        entities responsible for the safe storage and/or delivery of Messages. Messages can
+        originate from, terminate at, or be relayed by Nodes. A Link is a unidirectional route
+        between two Nodes along which Messages may travel if they meet the entry criteria of the
+        Link. As a Message travels through the AMQP network, the responsibility for safe storage and
+        delivery of the Message is transferred between the Nodes it encounters. The Link Protocol
+        (defined in the <xref name="links"/> section) manages the transfer of responsibility between
+        two Nodes.
+      </p>
+
+      <picture>
+        <![CDATA[
+  +------------+                             +------------+
+ /    Node A    \                           /    Node B    \
++----------------+   +--filter             +----------------+
+|                |   |                     |                |
+|  MSG_3 <MSG_1> |  +-+                    |         MSG_1  |
+|                |--|?|------------------->|                |
+| <MSG_2> MSG_4  |  +-+                    |  MSG_2         |
+|                |        Link(A,B)        |                |
++----------------+                         +----------------+
+
+            Key: <MSG_n> = old location of MSG_n
+]]>
+      </picture>
+
+      <p>
+        Nodes exist within a <i>Container</i>, and each Container may hold many Nodes. Examples of
+        AMQP Nodes are Producers, Consumers, and Queues. Producers and Consumers are the elements
+        within a client Application that generate and process Messages. Queues are entities within a
+        Broker that store and forward Messages. Examples of containers are Brokers and Client
+        Applications.
+      </p>
+
+      <picture>
+        <![CDATA[
+   +---------------+                       +----------+
+   | <<Container>> | 1..1             0..n | <<Node>> |
+   |---------------|<>-------------------->|----------|
+   | container-id  |                       | name     |
+   +---------------+                       +----------+
+          /_\                                   /_\
+           |                                     |
+           |                                     |
+     +-----+-----+                    +----------+----------+
+     |           |                    |          |          |
+     |           |                    |          |          |
++--------+  +--------+        +----------+  +----------+  +-------+
+| Broker |  | Client |        | Producer |  | Consumer |  | Queue |
+|--------|  |--------|        |----------|  |----------|  |-------|
+|        |  |        |        |          |  |          |  |       |
++--------+  +--------+        +----------+  +----------+  +-------+
+]]>
+      </picture>
+
+      <p>
+        The AMQP Transport Specification defines a peer-to-peer protocol for transferring Messages
+        between Nodes in the AMQP network. This portion of the specification is not concerned with
+        the internal workings of any sort of Node, and only deals with the mechanics of
+        unambiguously transferring a Message from one Node to another.
+      </p>
+
+      <p>
+        Containers communicate via <i>Connections</i>. An AMQP Connection consists of a full-duplex,
+        ordered, reliable, authenticated, and (optionally) encrypted sequence of <i>Frames</i>. The
+        precise requirement for a Connection is that if the n-th Frame arrives, all Frames prior to
+        n MUST also have arrived. It is assumed Connections are transient and may fail for a variety
+        of reasons resulting in the loss of an unknown number of frames, but they are still subject
+        to the aforementioned ordered reliability criteria. This is similar to the guarantee that
+        TCP or SCTP provides for byte streams, and the specification defines a
+        <xref name="framing"/> system used to parse a byte stream into a sequence of Frames for use
+        in establishing an AMQP Connection over TCP or SCTP.
+      </p>
+
+      <p>
+        Containers conduct stateful dialogs via named <i>Sessions</i>. An AMQP Session is a
+        full-duplex, ordered, reliable command transport with positive acknowledgment, flow control,
+        and error handling. Sessions send commands over an associated Connection. When a Session is
+        associated with a Connection it is said to be <i>attached</i>. When a Session is not
+        associated with a Connection it is said to be <i>detached</i>. Detached Sessions retain
+        conversational state for a period determined by a negotiated timeout. A single Connection
+        may have multiple Sessions attached, up to a negotiated limit. Both Connections and Sessions
+        are modeled by each peer as <i>endpoints</i> that store local and last known remote state
+        regarding the Connection or Session in question.
+      </p>
+
+      <picture>
+        <![CDATA[
+Session A-------+                           +-------Session A
+                |                           |
+               \|/                         \|/
+Session B---> Connection <---------> Connection <---Session B
+               /|\                         /|\
+                |                           |
+Session C-------+                           +-------Session C
+
+
+Session D (detached)                                Session D (detached)
+]]>
+      </picture>
+
+      <p>
+        A Session defines a strict order of execution on commands and maps to a single thread of
+        control (note this does not necessarily imply a single OS thread). Sessions provide a scope
+        for transactional interactions, and a facility for demarcating transactional units of work.
+        Within a Session, the Link Protocol (defined in the <xref name="links"/> section) is used to
+        establish Links between local and remote Nodes and to transfer Messages across them. A
+        single Session may simultaneously operate on any number of Links.
+      </p>
+
+      <picture><![CDATA[
+                         +-------------+
+                         |    Link     |  Message Transport
+                         +-------------+  (Node to Node)
+                         | name        |
+                         | local-node  |
+                         | remote-node |
+                         +-------------+
+                              /|\ 0..n
+                               |
+                               |
+                               |
+                              \|/ 0..1
++-------------+          +------------+
+| Transaction | 0..1     |  Session   |  Command Transport
++-------------+ <------- +------------+  (Container to Container)
+|             |          | name       |
++-------------+          | timeout    |
+                         +------------+
+                              /|\ 0..n
+                               |
+                               |
+                               |
+                              \|/ 0..1
+                         +------------+
+                         | Connection |  Frame Transport
+                         +------------+  (Container to Container)
+                         | principal  |
+                         +------------+
+]]>
+      </picture>
+
+      <p>
+        A <i>Frame</i> is the unit of work carried by a Connection. There are two types of
+        frames: <i>Connection</i> frames, and <i>Session</i> frames. <i>Connection</i> frames are
+        processed by the Connection endpoint. Connection frames are used to open and close an AMQP
+        Connection as well as to establish a secure transport prior to initiating an AMQP
+        Connection. <i>Session</i> frames are processed by the Session endpoint. Session frames
+        carry additional state pertaining to the acknowledgment and flow control features of the
+        Session. Session frames are used to attach and detach Session endpoints, as well as to carry
+        the Commands sent over a Session. Specific Session Commands are defined for transferring
+        Messages along a Link (See <xref name="links"/>) as well as establishing transactional
+        boundaries.
+      </p>
+
+      <!-- <p>TODO: put tabular control and command summary here</p> -->
+
+      <p>
+        Controls: <xref type="type" name="open"/>, <xref type="type" name="attach"/>,
+        <xref type="type" name="detach"/>, <xref type="type" name="close"/>
+      </p>
+
+      <p>
+        Commands: <xref type="type" name="noop"/>, <xref type="type" name="enlist"/>,
+        <xref type="type" name="txn"/>, <xref type="type" name="link"/>,
+        <xref type="type" name="relink"/>, <xref type="type" name="unlink"/>,
+        <xref type="type" name="flow"/>, <xref type="type" name="drain"/>,
+        <xref type="type" name="transfer"/>, <xref type="type" name="bar"/>,
+        <xref type="type" name="disposition"/>
+      </p>
+    </doc>
+  </section>
+
+  <section name="version-negotiation" title="Version Negotiation"
+           label="definition of version negotiation steps">
+    <doc >
+      <p>
+        Prior to sending any frames on a Connection, each peer MUST start by sending a protocol
+        header that indicates the protocol version used on the Connection. The protocol header
+        consists of the upper case ASCII letters "AMQP" followed by a protocol id of zero, followed
+        by three unsigned bytes representing the major, minor, and revision of the protocol version
+        (currently <xref name="MAJOR"/>, <xref name="MINOR"/>, <xref name="REVISION"/>). In total
+        this is an 8-octet sequence:
+      </p>
+
+      <picture><![CDATA[
+  4 OCTETS   1 OCTET   1 OCTET   1 OCTET   1 OCTET
++----------+---------+---------+---------+----------+
+|  "AMQP"  |   %d0   |  major  |  minor  | revision |
++----------+---------+---------+---------+----------+
+]]>
+      </picture>
+
+      <p>
+        Any data appearing beyond the protocol header MUST match the version indicated by the
+        protocol header. If the incoming and outgoing protocol headers do not match, both peers MUST
+        close their outgoing stream and SHOULD read the incoming stream until it is terminated.
+      </p>
+
+      <p>
+        The AMQP peer which acted in the role of the TCP client (i.e. the peer that opened the
+        Connection) MUST immediately send its outgoing protocol header on establishment of the TCP
+        Session. The AMQP peer which acted in the role of the TCP server MAY elect to wait until
+        receiving the incoming protocol header before sending its own outgoing protocol header.
+      </p>
+
+      <p>
+        Two AMQP peers agree on a protocol version as follows (where the words "client" and
+        "server" refer to the roles being played by the peers at the TCP Connection level):
+      </p>
+
+      <ul>
+        <li>
+          <p>
+            When the client opens a new socket Connection to a server, it MUST send a protocol
+            header with the client's preferred protocol version.
+          </p>
+        </li>
+
+        <li>
+          <p>
+            If the requested protocol version is supported, the server MUST send its own protocol
+            header with the requested version to the socket, and then proceed according to the
+            protocol definition.
+          </p>
+        </li>
+
+        <li>
+          <p>
+            If the requested protocol version is <b>not</b> supported, the server MUST send a
+            protocol header with a <b>supported</b> protocol version and then close the socket.
+          </p>
+        </li>
+
+        <li>
+          <p>
+            When choosing a protocol version to respond with, the server SHOULD choose the highest
+            supported version that is less than or equal to the requested version. If no such
+            version exists, the server SHOULD respond with the highest supported version.
+          </p>
+        </li>
+
+        <li>
+          <p>
+            If the server can't parse the protocol header, the server MUST send a valid protocol
+            header with a supported protocol version and then close the socket.
+          </p>
+        </li>
+      </ul>
+
+      <p>
+        Based on this behavior a client can discover which protocol versions a server supports by
+        attempting to connect with its highest supported version and reconnecting with a version
+        less than or equal to the version received back from the server.
+      </p>
+
+      <picture title="Version Negotiation Examples"><![CDATA[
+TCP Client                               TCP Server
+======================================================
+AMQP%d1.0.0.0       ------------->
+                    <-------------       AMQP%d1.0.0.0 (1)
+                          ...            *proceed*
+
+AMQP%d1.1.0.0       ------------->
+                    <-------------       AMQP%d1.0.0.0 (2)
+                                         *TCP CLOSE*
+
+HTTP                ------------->
+                    <-------------       AMQP%d1.0.0.0 (3)
+                                         *TCP CLOSE*
+------------------------------------------------------
+  (1) Server accepts Connection for: AMQP, major=1,
+      minor=0, revision=0, flags=0
+
+  (2) Server rejects Connection for: AMQP, major=1,
+      minor=1, revision=0, flags=0. Server responds
+      that it supports: AMQP, major=1, minor=0,
+      revision=0, flags=0
+
+  (3) Server rejects Connection for: HTTP. Server
+      responds it supports: AMQP, major=1, minor=0,
+      revision=0, flags=0
+ ]]>
+      </picture>
+
+      <p>
+        Please note that the above examples use the literal notation defined in RFC 2234 for non
+        alphanumeric values.
+      </p>
+    </doc>
+  </section>
+
+  <section name="framing" label="frame layout and encoding">
+    <doc title="Frame Layout">
+      <p>
+        Frames are divided into two distinct areas: a fixed width frame header, and a variable width
+        frame body.
+      </p>
+
+      <picture><![CDATA[
++--------------+------------+
+| frame header | frame body |
++--------------+------------+
+    24 bytes     *variable*
+]]>
+      </picture>
+
+      <dl>
+        <dt>frame header</dt>
+        <dd><p>The frame header is a fixed size (24 byte) structure that precedes each frame. The
+            frame header includes information required to parse the rest of the frame.</p></dd>
+
+        <dt>frame body</dt>
+        <dd><p>The frame body is a variable width sequence of bytes whose interpretation depends on
+            the frame type. For Connection and Session frames, this will, when non-empty, contain an
+            encoded control or command.</p></dd>
+      </dl>
+    </doc>
+
+    <doc title="Frame Header">
+      <p>
+        The first 8 bytes of the frame header are formatted identically for all frame types. The
+        semantics of the frame flags, and the format of the last 16 bytes of the frame header are
+        dependent on the specific type of frame as indicated by the value of the type field. There
+        are two frame types defined: Connection frames and Session frames.
+      </p>
+
+      <picture><![CDATA[
+        +0         +1         +2         +3
+   +-------------------------------------------+ -.
+ 0 |                   size                    |  |
+   +-------------------------------------------+  |
+ 4 |  type  |   flags    |       channel       |  |
+   +-------------------------------------------+  |
+ 8 |             <type-dependent>              |  |
+   +-------------------------------------------+  |---> frame header
+12 |             <type-dependent>              |  |      (24 bytes)
+   +-------------------------------------------+  |
+16 |             <type-dependent>              |  |
+   +-------------------------------------------+  |
+20 |             <type-dependent>              |  |
+   +-------------------------------------------+ -'
+   +-------------------------------------------+ -.
+   |                    ...                    |  |
+   .                                           .  |
+   .                                           .  |---> frame body
+   .                                           .  |  (size - 24) bytes
+   |                    ...                    |  |
+   +-------------------------------------------+ -'
+]]>
+      </picture>
+
+      <dl>
+        <dt>size</dt>
+        <dd><p>Bytes 0-3 of the frame header contain the frame size. This is an unsigned 32-bit
+            integer that MUST contain the total frame size including the frame header. The frame is
+            malformed if the size is less than the the size of the header (24 bytes).</p></dd>
+
+        <dt>type</dt>
+        <dd><p>Byte 4 of the frame header is a type code. The type code indicates the format and
+            purpose of the frame. A type code of 0x00 indicates that the frame is a Connection
+            frame. A type code of 0x01 indicates that the frame is a Session frame. The subsequent
+            bytes in the frame header may be interpreted differently depending on the type of the
+            frame.</p></dd>
+
+        <dt>flags</dt>
+        <dd><p>Byte 5 of the frame header is reserved for frame flags. The semantics of the frame
+            flags are determined by the frame type.</p></dd>
+
+        <dt>channel</dt>
+        <dd><p>Bytes 6 and 7 of the frame header contain the channel number. The channel number
+            uniquely identifies one of the Sessions associated with the Connection.</p></dd>
+      </dl>
+    </doc>
+
+    <doc title="Frame Body">
+      <p>
+        The frame body contains a variable number of octets, anywhere from zero, up to the maximum
+        frame size minus 24 bytes for the header. Prior to any explicit negotiation, the maximum
+        frame size is <xref name="MIN-MAX-FRAME-SIZE"/>. For Connection and Session frames, the
+        frame body, if non-empty, will consist of a command or control operation encoded as a
+        compound value (see <xref name="compound-types"/>). The complete set of compound type
+        definitions for the core AMQP protocol commands and controls are defined in the
+        <xref name="commands"/> and <xref name="controls"/> sections respectively.
+      </p>
+    </doc>
+
+    <doc title="Connection Frames">
+      <p>
+        Connection frames carry encoded Connection controls. Connection controls are exchanged by
+        the Connection endpoints in order to setup and teardown an AMQP Connection. For Connection
+        frames, all flag bits and type-specific fields in the frame header are reserved.
+      </p>
+
+      <picture><![CDATA[
+            type: 0x00 - connection frame
+           flags: 0|0|0|0|0|0|0|0
+
+        +0         +1         +2         +3
+   +-------------------------------------------+ -.
+ 0 |                   size                    |  |
+   +-------------------------------------------+  |
+ 4 |  type  |   flags    |       channel       |  |
+   +-------------------------------------------+  |
+ 8 |                <reserved>                 |  |
+   +-------------------------------------------+  |---> frame header
+12 |                <reserved>                 |  |      (24 bytes)
+   +-------------------------------------------+  |
+16 |                <reserved>                 |  |
+   +-------------------------------------------+  |
+20 |                <reserved>                 |  |
+   +-------------------------------------------+ -'
+   +-------------------------------------------+ -.
+   |                    ...                    |  |
+   .                                           .  |
+   .                                           .  |---> frame body
+   .                                           .  |  (size - 24) bytes
+   |                    ...                    |  |
+   +-------------------------------------------+ -'
+]]>
+      </picture>
+
+      <p>
+        Connection Controls: <xref type="type" name="open"/>, <xref type="type" name="close"/>
+      </p>
+
+      <p>
+        A Connection control frame with an empty body may be used to generate artificial traffic as
+        needed to satisfy any negotiated heartbeat interval. Other than resetting the heartbeat
+        timer, an empty Connection control has no effect on the receiver.
+      </p>
+    </doc>
+
+    <doc title="Session Frames">
+      <p>
+        Session frames carry encoded Session controls and commands. Session controls are exchanged
+        by two Session endpoints in order to attach and detach them, as well as to manage the
+        acknowledgment, and flow control of the commands sent on a Session. The flags and
+        type-dependent header fields for Session frames are used to carry key Session state
+        variables.
+      </p>
+
+      <picture><![CDATA[
+            type: 0x01 - session frame
+           flags: 0|0|0|0|S|F|N|C
+
+               C: command flag     (flags bit 0)
+               N: no-executed flag (flags bit 1)
+               S: sync flag        (flags bit 2)
+
+        +0         +1         +2         +3
+   +-------------------------------------------+ -.
+ 0 |                   size                    |  |
+   +-------------------------------------------+  |
+ 4 |  type  |   flags    |       channel       |  |
+   +-------------------------------------------+  |
+ 8 |               acknowledged                |  |
+   +-------------------------------------------+  |---> frame header
+12 |                 executed                  |  |      (24 bytes)
+   +-------------------------------------------+  |
+16 |                 capacity                  |  |
+   +-------------------------------------------+  |
+20 |                command-id                 |  |
+   +-------------------------------------------+ -'
+   +-------------------------------------------+ -.
+   |                    ...                    |  |
+   .                                           .  |
+   .                                           .  |---> frame body
+   .                                           .  |  (size - 24) bytes
+   |                    ...                    |  |
+   +-------------------------------------------+ -'
+]]>
+      </picture>
+
+      <dl>
+        <dt>flags</dt>
+        <dd><p>For Session frames, bits 3-7 of the frame flags are reserved. Bit 0 is defined as the
+            command flag, bit 1 is defined as the no-executed flag, and bit 2 is defined as the sync
+            flag. All bit numbers start at 0 for the least significant bit and increase to 7 for the
+            most significant bit.</p></dd>
+
+        <dt>command flag</dt>
+        <dd><p>The command flag, if set, indicates that the frame contains a command. If this flag
+            is not set, then the frame contains a Session control.</p></dd>
+
+        <dt>no-executed flag</dt>
+        <dd><p>The no-executed flag, if set, indicates that no commands have yet been executed. In
+            this case the executed field is considered reserved and MUST be set to zero. If the
+            no-executed flag is not set, then the executed field contains a valid value.</p></dd>
+
+        <dt>sync flag</dt>
+        <dd><p>If the command flag is true, the sync flag is a signal to the receiving Session
+            endpoint to promptly send the newly updated Session state after the framed command has
+            been executed. If the command flag is false, then the sync flag indicates that the
+            receiving Session endpoint should promptly send its current Session state.</p></dd>
+
+        <dt>acknowledged</dt>
+        <dd><p>Bytes 8-11 of a command frame contain the acknowledged field. This field indicates
+            which outgoing commands have been acknowledged. The value is encoded as a 32-bit
+            serial-number as defined by RFC-1982. The acknowledged field is part of the Session
+            state as defined in the <xref type="section" name="sessions"/> section.</p></dd>
+
+        <dt>executed</dt>
+        <dd><p>Bytes 12-15 of a command frame contain the executed field. This field indicates which
+            incoming commands have been executed. The field is encoded as a 32-bit serial-number as
+            defined by RFC-1982. The executed field is part of the Session state as defined in the
+            <xref type="section" name="sessions"/> section. If the ex-init flag is not set, then
+            this field is considered reserved and MUST be set to zero.</p></dd>
+
+        <dt>capacity</dt>
+        <dd><p>Bytes 16-19 of a command frame contain the capacity field. This field indicates how
+            many more incoming commands are permitted beyond those that have already been executed.
+            The field is encoded as a 32-bit serial-number as defined by RFC-1982. The capacity
+            field is part of the Session state as defined in the <xref type="section"
+            name="sessions"/> section.</p></dd>
+
+        <dt>command-id</dt>
+        <dd><p>Bytes 20-23 of a command frame contain the command-id field. This field contains the
+            id of the next command to be sent. If the frame contains a command this is the id of the
+            framed command. If the frame does not contain a command (the command flag is not set),
+            then this contains the id that will be assigned to the next command sent. The command-id
+            must be set in strict sequence order - that is it is an error for a command-id to be
+            skipped or commands to be sent out of order with respect to their ids with respect to
+            their ids. The command-id is encoded as a 32-bit serial-number as defined by RFC-1982.
+            See the <xref type="section" name="sessions"/> section for more details.</p>
+        </dd>
+      </dl>
+
+      <p>Session Controls: <xref type="type" name="attach"/>, <xref type="type" name="detach"/></p>
+
+      <p>
+        Session Commands: <xref type="type" name="noop"/>, <xref type="type" name="enlist"/>,
+        <xref type="type" name="txn"/>, <xref type="type" name="link"/>,
+        <xref type="type" name="relink"/>, <xref type="type" name="unlink"/>,
+        <xref type="type" name="flow"/>, <xref type="type" name="drain"/>,
+        <xref type="type" name="transfer"/>, <xref type="type" name="bar"/>,
+        <xref type="type" name="disposition"/>
+      </p>
+
+      <p>
+        A Session control frame with an empty body is used to exchange Session state variables
+        without sending an additional command. A Session command frame with an empty body is
+        considered a noop command.
+      </p>
+    </doc>
+
+  </section>
+
+  <!-- == Section: connections ================================================================= -->
+
+  <section name="connections" label="Connection life-cycle controls">
+    <doc title="Opening a Connection">
+      <p>
+        Each AMQP Connection begins with an exchange of capabilities and limitations. After
+        establishing or accepting a TCP Connection and sending the protocol header, each peer must
+        send an <xref type="type" name="open"/> control before sending any other frames. The
+        <xref type="type" name="open"/> control describes the capabilities and limits of that peer.
+        After sending the <xref type="type" name="open"/> control each peer must read its partner's
+        <xref type="type" name="open"/> control and must operate within mutually acceptable
+        limitations from this point forward.
+      </p>
+
+      <picture><![CDATA[
+TCP Client              TCP Server
+==================================
+TCP-CONNECT             TCP-ACCEPT
+PROTO-HDR               PROTO-HDR
+OPEN        ---+   +--- OPEN
+                \ /
+wait             x      wait
+                / \
+proceed     <--+   +--> proceed
+
+                ...
+]]>
+      </picture>
+    </doc>
+
+    <doc title="Pipelined Open">
+      <p>
+        For applications that use many short-lived Connections, it may be desirable to pipeline the
+        Connection negotiation process. A peer may do this by starting to send commands or controls
+        before receiving the partner's Connection header or <xref type="type" name="open"/> control.
+        This is permitted so long as the pipelined commands and controls are known a priori to
+        conform to the capabilities and limitations of its partner. For example, this may be
+        accomplished by keeping the use of the Connection within the capabilities and limits
+        expected of all AMQP implementations as defined by the specification of the
+        <xref type="type" name="open"/> control.
+      </p>
+
+      <picture><![CDATA[
+TCP Client                    TCP Server
+===============================================
+TCP-CONNECT                   TCP-ACCEPT
+PROTO-HDR                     PROTO-HDR
+OPEN              ---+   +--- OPEN
+                      \ /
+pipelined cmd/ctl      x      pipelined cmd/ctl
+                      / \
+proceed           <--+   +--> proceed
+
+                      ...
+-----------------------------------------------
+
+]]>
+      </picture>
+      <p>
+        The use of pipelined commands and/or controls by a peer cannot be distinguished by the
+        peer's partner from non-pipelined use so long as the pipelined commands and controls
+        conform to the partner's capabilities and limitations.
+      </p>
+    </doc>
+
+    <doc title="Closing a Connection">
+      <p>
+        Prior to closing a Connection, each peer must write a <xref type="type" name="close"/>
+        control with a code indicating the reason for closing. This control must be the last thing
+        ever written onto a Connection. After writing this control the peer should continue to read
+        from the Connection until it receives the partner's <xref type="type" name="close"/>
+        control.
+      </p>
+
+      <picture><![CDATA[
+TCP Client         TCP Server
+=============================
+            ...
+
+CLOSE     ------->
+               +-- CLOSE
+              /    TCP-CLOSE
+TCP-CLOSE <--+
+]]>
+      </picture>
+    </doc>
+
+    <doc title="Simultaneous Close">
+      <p>
+        Normally one peer will initiate the Connection close, and the partner will send its close in
+        response. However, because both endpoints may simultaneously choose to close the Connection
+        for independent reasons, it is possible for a simultaneous close to occur. In this case, the
+        only potentially observable difference from the perspective of each endpoint is the code
+        indicating the reason for the close.
+      </p>
+
+      <picture><![CDATA[
+TCP Client            TCP Server
+================================
+              ...
+
+CLOSE     ---+   +--- CLOSE
+              \ /
+               x
+              / \
+TCP-CLOSE <--+   +--> TCP-CLOSE
+]]>
+      </picture>
+    </doc>
+
+    <doc title="Connection States">
+      <dl>
+        <dt>START</dt>
+        <dd><p>In this state a Connection exists, but nothing has been sent or received. This is the
+            state an implementation would be in immediately after performing a socket connect or
+            socket accept.</p></dd>
+
+        <dt>HDR_RCVD</dt>
+        <dd><p>In this state the Connection header has been received from our peer, but we have not
+            yet sent anything.</p></dd>
+
+        <dt>HDR_SENT</dt>
+        <dd><p>In this state the Connection header has been sent to our peer, but we have not yet
+            received anything.</p></dd>
+
+        <dt>OPEN_PIPE</dt>
+        <dd><p>In this state we have sent both the Connection header and the
+               <xref type="type" name="open"/> control, but we have not yet received anything.
+            </p></dd>
+
+        <dt>OC_PIPE</dt>
+        <dd><p>In this state we have sent the Connection header, the <xref type="type" name="open"/>
+            control, any pipelined Connection traffic, and the <xref type="type" name="close"/>
+            control, but we have not yet received anything.</p></dd>
+
+        <dt>OPEN_RCVD</dt>
+        <dd><p>In this state we have sent and received the Connection header, and received an
+            <xref type="type" name="open"/> control from our peer, but have not yet sent an
+            <xref type="type" name="open"/> control.</p></dd>
+
+        <dt>OPEN_SENT</dt>
+        <dd><p>In this state we have sent and received the Connection header, and sent an
+            <xref type="type" name="open"/> control to our peer, but have not yet received an
+            <xref type="type" name="open"/> control.</p></dd>
+
+        <dt>CLOSE_PIPE</dt>
+        <dd><p>In this state we have send and received the Connection header, sent an
+            <xref type="type" name="open"/> control, any pipelined Connection traffic, and the
+            <xref type="type" name="close"/> control, but we have not yet received an
+            <xref type="type" name="open"/> control.</p></dd>
+
+        <dt>OPENED</dt>
+        <dd><p>In this state the the Connection header and the <xref type="type" name="open"/>
+            control have both been sent and received.</p></dd>
+
+        <dt>CLOSE_RCVD</dt>
+        <dd><p>In this state we have received a <xref type="type" name="close"/> control indicating
+            that our partner has initiated a close. This means we will never have to read anything
+            more from this Connection, however we can continue to write commands/controls onto the
+            Connection.  If desired, an implementation could do a TCP half-close at this point to
+            shutdown the read side of the Connection.</p></dd>
+
+        <dt>CLOSE_SENT</dt>
+        <dd><p>In this state we have sent a <xref type="type" name="close"/> control to our partner.
+            It is illegal to write anything more onto the Connection, however there may still be
+            incoming controls and/or commands. If desired, an implementation could do a TCP
+            half-close at this point to shutdown the write side of the Connection.</p></dd>
+
+        <dt>END</dt>
+        <dd><p>In this state it is illegal for either endpoint to write anything more onto the
+            Connection. The Connection may be safely closed and discarded.</p></dd>
+      </dl>
+    </doc>
+
+    <doc title="Connection State Diagram">
+      <p>
+        The graph below depicts a complete state diagram for each endpoint. The boxes represent
+        states, and the arrows represent state transitions. Each arrow is labeled with the action
+        that triggers that particular transition.
+      </p>
+
+      <picture><![CDATA[
+             R:HDR @=======@ S:HDR             R:HDR[!=S:HDR]
+          +--------| START |-----+    +--------------------------------+
+          |        @=======@     |    |                                |
+         \|/                    \|/   |                                |
+     @==========@             @==========@ S:OPEN                      |
++----| HDR_RCVD |             | HDR_SENT |------+                      |
+|    @==========@             @==========@      |      R:HDR[!=S:HDR]  |
+|   S:HDR |                      | R:HDR        |    +-----------------+
+|         +--------+      +------+              |    |                 |
+|                 \|/    \|/                   \|/   |                 |
+|                @==========@               +-----------+ S:CLOSE      |
+|                | HDR_EXCH |               | OPEN_PIPE |----+         |
+|                @==========@               +-----------+    |         |
+|           R:OPEN |      | S:OPEN              | R:HDR      |         |
+|         +--------+      +------+      +-------+            |         |
+|        \|/                    \|/    \|/                  \|/        |
+|   @===========@             @===========@ S:CLOSE       +---------+  |
+|   | OPEN_RCVD |             | OPEN_SENT |-----+         | OC_PIPE |--+
+|   @===========@             @===========@     |         +---------+  |
+|  S:OPEN |                      | R:OPEN      \|/           | R:HDR   |
+|         |       @========@     |          +------------+   |         |
+|         +------>| OPENED |<----+          | CLOSE_PIPE |<--+         |
+|                 @========@                +------------+             |
+|           R:CLOSE |    | S:CLOSE              | R:OPEN               |
+|         +---------+    +-------+              |                      |
+|        \|/                    \|/             |                      |
+|   @============@            @============@    |                      |
+|   | CLOSE_RCVD |            | CLOSE_SENT |<---+                      |
+|   @============@            @============@                           |
+| S:CLOSE |                      | R:CLOSE                             |
+|         |         @=====@      |                                     |
+|         +-------->| END |<-----+                                     |
+|                   @=====@                                            |
+|                     /|\                                              |
+|    S:HDR[!=R:HDR]    |                R:HDR[!=S:HDR]                 |
++----------------------+-----------------------------------------------+
+
+                     R:<CTRL> = Received <CTRL>
+                     S:<CTRL> = Sent <CTRL>
+]]>
+      </picture>
+
+      <picture><![CDATA[
+State        Legal Sends     Legal Receives    Legal Connection Actions
+=======================================================================
+START        HDR             HDR
+HDR_RCVD     HDR             OPEN
+HDR_SENT     OPEN            HDR
+HDR_EXCH     OPEN            OPEN
+OPEN_RCVD    OPEN            *
+OPEN_SENT    **              OPEN
+OPEN_PIPE    **              HDR
+CLOSE_PIPE   -               OPEN              TCP Close for Write
+OC_PIPE      -               HDR               TCP Close for Write
+OPENED       *               *
+CLOSE_RCVD   *               -                 TCP Close for Read
+CLOSE_SENT   -               *                 TCP Close for Write
+END          -               -                 TCP Close
+
+*  = any command or control
+-  = no command or control
+** = any command or control known a priori to conform to the
+     peer's capabilities and limitations
+]]>
+      </picture>
+    </doc>
+
+  </section>
+
+  <!-- == Section: sessions ==================================================================== -->
+
+  <section name="sessions" label="command transport">
+    <doc>
+      <p>
+        An AMQP Session is a named dialog between two AMQP peers. Each participant maintains a
+        Session Endpoint that stores the conversational state for that Session. Session Endpoints
+        must be associated with an open Connection in order to be <i>attached</i>. Session Endpoints
+        may become detached deliberately, or when a failure occurs (either in the network or at one
+        of the endpoints). While detached the Session Endpoint will retain state while the
+        Connection it was last associated with remains open, and thereafter for its configured
+        timeout value. The timeout setting may be zero (indicating state should not be retained
+        beyond Connection closure) or it may be set such that the endpoint retains state
+        indefinitely.
+      </p>
+    </doc>
+
+    <doc title="Naming a Session">
+      <p>
+        Session names are supplied by the initiating peer, and MUST be globally unique among all
+        open Sessions. Once a Session is cleanly closed, its name may be reused. Session names are
+        represented by opaque binary strings. Example naming schemes include mechanically generated
+        UUID-based names as well as stable, manually chosen URI based names. Session names are only
+        exchanged during the attach and detach procedures, so there is no significant overhead to
+        choosing long names.
+      </p>
+    </doc>
+
+    <doc title="Establishing a Session">
+      <p>
+        Sessions are established by creating a Session Endpoint, assigning it to an unused channel
+        number, and sending an <xref type="type" name="attach"/> carrying the state of the newly
+        created Endpoint. The partner responds with an <xref type="type" name="attach"/> carrying
+        the state of the corresponding Endpoint, creating and/or mapping the Endpoint to an unused
+        channel number if necessary. To avoid accidentally resuming an existing Session, the
+        initiating peer may optionally wish to verify that the corresponding Endpoint is newly
+        created by checking that the received opening flag matches the sent opening flag.
+      </p>
+
+      <picture><![CDATA[
+    Endpoint                                Endpoint
+    ====================================================================
+    [CH3] ATTACH(name=...,       --------->
+                 opening=1, ...)        +-- [CH7] ATTACH(name=...,
+                                       /                 opening=1, ...)
+                                      /
+(1)                              <---+
+
+                                    ...
+
+    --------------------------------------------------------------------
+
+      (1) The initiating peer can at this point verify that the
+          corresponding Endpoint is newly created.
+]]>
+      </picture>
+    </doc>
+
+    <doc title="Resuming a Session">
+      <p>
+        Sessions are resumed by assigning the existing detached Session Endpoint to an unused
+        channel number and sending an <xref type="type" name="attach"/> carrying the state of the
+        resuming Endpoint. The partner responds with an <xref type="type" name="attach"/> carrying
+        the state of the corresponding Endpoint, creating and/or mapping the Endpoint to an unused
+        channel number if necessary. The resuming peer may wish to verify that the corresponding
+        Endpoint is not newly created. This may be used to detect whether conversational state has
+        been lost.
+      </p>
+
+      <picture><![CDATA[
+    Endpoint                                Endpoint
+    ====================================================================
+    [CH3] ATTACH(name=...,       --------->
+                 opening=0, ...)        +-- [CH7] ATTACH(name=...,
+                                       /                 opening=0, ...)
+                                      /
+(1)                              <---+
+
+                                    ...
+
+    --------------------------------------------------------------------
+
+      (1) The resuming peer can at this point verify that the
+          corresponding Endpoint is not newly created.
+]]>
+      </picture>
+    </doc>
+
+    <doc title="Detaching a Session">
+      <p>
+        Sessions become detached automatically when the Connection is cleanly closed (with the
+        exchange of AMQP <xref type="type" name="close"/> controls), interrupted (when the network
+        transport is removed without a <xref type="type" name="close"/> exchange), or when an error
+        is encountered while executing a command. A Session is explicitly detached by sending a
+        <xref type="type" name="detach"/> control. Once the <xref type="type" name="detach"/> is
+        sent, no more commands or controls may be sent to the other Session Endpoint without first
+        reattaching. The detaching peer MUST read and discard incoming commands until the other
+        Endpoint's <xref type="type" name="detach"/> is received.
+      </p>
+
+      <picture><![CDATA[
+    Endpoint A                              Endpoint B
+    ====================================================================
+
+                                     ...
+
+    [CH3] DETACH(name=...,       --------->
+                 closing=0, ...)        +-- [CH7] DETACH(name=...,
+(1)                                    /                 closing=0, ...)
+                                      /                                  (2)
+(3)                              <---+
+
+                                     ...
+
+    --------------------------------------------------------------------
+
+      (1) At this point no more commands or controls may be sent to
+          Endpoint B without first reattaching to it, but incoming
+          commands and controls may still be received.
+
+      (2) At this point Endpoint B is fully detached from the
+          Connection.
+
+      (3) At this point Endpoint A is fully detached from the
+          Connection.
+]]>
+      </picture>
+    </doc>
+
+    <doc title="Closing a Session">
+      <p>
+        Sessions are closed by setting the closing bit on the <xref type="type" name="detach"/>
+        control, and detaching in the normal way. If an Endpoint sets the closing bit, it indicates
+        that after the detach is confirmed (via the receipt of a corresponding
+        <xref type="type" name="detach"/> control, also with the closing bit set) the Endpoint will
+        be destroyed.
+      </p>
+
+      <picture><![CDATA[
+    Endpoint A                              Endpoint B
+    ====================================================================
+
+                                    ...
+
+    [CH3] DETACH(name=...,       --------->
+                 closing=1, ...)        +-- [CH7] DETACH(name=...,
+(1)                                    /                 closing=1, ...)
+                                      /                                  (2)
+(3)                              <---+
+
+                                     ...
+
+    --------------------------------------------------------------------
+
+      (1) At this point no more commands or controls may be sent to
+          Endpoint B without first reattaching to it, but incoming
+          commands and controls may still be received.
+
+      (2) At this point Endpoint B is fully detached from the
+          Connection.
+
+      (3) At this point Endpoint A is fully detached from the
+          Connection and can be destroyed.
+]]>
+      </picture>
+
+      <p>
+        If a Session becomes detached without being cleanly closed, then the Endpoints are required
+        to retain state until the the Connection closes and the timeout has been reached. If in this
+        case an Endpoint has locally set its closing bit, but has not had confirmation from the
+        other Endpoint that it too is closing, then it has a responsibility to attempt to reattach
+        in order to close cleanly.
+      </p>
+    </doc>
+
+    <doc title="Simultaneous Detach/Close">
+      <p>
+        Due to the potentially asynchronous nature of Sessions, it is possible that both peers may
+        simultaneously decide to detach and/or close the Session. If this should happen, it will
+        appear to each peer as though their partner's spontaneously initiated
+        <xref type="type" name="detach"/> is actually an answer to the peers initial
+        <xref type="type" name="detach"/> control. One observable consequence of this occurrence is
+        that if one Endpoint is closing and the other Endpoint is detaching, the values of the
+        closing flag may not match. In this case, the closing Endpoint should reattach and verify
+        that the detaching Endpoint was actually closed.
+      </p>
+
+      <picture><![CDATA[
+    Endpoint A                            Endpoint B
+    =================================================================
+
+                                   ...
+
+    [CH3] DETACH(name=..., ...) --+   +-- [CH7] DETACH(name=..., ...)
+(1)                                \ /                                (2)
+                                    x
+                                   / \
+(3)                             <-+   +->                             (4)
+
+                                   ...
+
+    -----------------------------------------------------------------
+
+      (1) At this point no more commands or controls may be sent
+          by A.
+
+      (2) At this point no more commands or controls may be sent
+          by B.
+
+      (3) At this point Endpoint A is fully detached from the
+          Connection.
+
+      (4) At this point Endpoint B is fully detached from the
+          Connection.
+]]>
+      </picture>
+    </doc>
+
+    <doc title="Session States">
+      <dl>
+        <dt>DETACHED</dt>
+        <dd><p>In the detached state, the Session endpoint is not mapped to an open Connection. In
+            this state an endpoint cannot send or receive commands and controls.</p></dd>
+
+        <dt>ATTACH_SENT</dt>
+        <dd><p>In the ATTACH_SENT state, the Session endpoint is assigned an outgoing channel
+            number, but there is no entry in the incoming channel map. In this state the endpoint
+            may send commands and controls but cannot receive them.</p></dd>
+
+        <dt>ATTACH_RCVD</dt>
+        <dd><p>In the ATTACH_RCVD state, the Session endpoint has an entry in the incoming channel
+            map, but has not yet been assigned an outgoing channel number. The endpoint may receive
+            commands and controls, but cannot send them.</p></dd>
+
+        <dt>ATTACHED</dt>
+        <dd><p>In the ATTACHED state, the Session endpoint has both an outgoing channel number and
+            an entry in the incoming channel map. The endpoint may send and receive commands and
+            controls.</p></dd>
+
+        <dt>DETACH_SENT</dt>
+        <dd><p>In the DETACH_SENT state, the Session endpoint has an entry in the incoming channel
+            map, but is no longer assigned an outgoing channel number. The endpoint may receive
+            commands and controls, but cannot send them.</p></dd>
+
+        <dt>DETACH_RCVD</dt>
+        <dd><p>In the DETACH_RCVD state, the Session endpoint is assigned an outgoing channel
+            number, but there is no entry in the incoming channel map. The endpoint may send
+            commands and controls, but cannot receive them.</p></dd>
+      </dl>
+
+      <picture title="State Transitions"><![CDATA[
+              DETACHED<----------------+
+                 |                     |
+         +-------+-------+             |
+         |               |             |
+S:ATTACH |               | R:ATTACH    |
+         |               |             |
+        \|/             \|/            |
+    ATTACH_SENT     ATTACH_RCVD        |
+         |               |             |
+         |               |             |
+R:ATTACH |               | S:ATTACH    |
+         +-------+-------+             |
+                 |                     |
+                \|/                    |
+              ATTACHED                 |
+                 |                     |
+         +-------+-------+             |
+         |               |             |
+S:DETACH |               | R:DETACH    |
+         |               |             |
+        \|/             \|/            |
+    DETACH_SENT     DETACH_RCVD        |
+         |               |             |
+         |               |             |
+R:DETACH |               | S:DETACH    |
+         +-------+-------+             |
+                 |                     |
+                 |                     |
+                 +---------------------+
+]]>
+      </picture>
+    </doc>
+
+    <doc title="Command Transport">
+      <p>
+        A Session may be used as both a synchronous and an asynchronous command transport. By
+        waiting for each command to be acknowledged prior to sending the next command, a Session
+        becomes a fully synchronous command transport, and by permitting many unacknowledged
+        commands a Session can become a fully asynchronous, full-duplex, transport.
+      </p>
+
+      <p>
+        The diagram below depicts a snapshot of a Sender and Receiver in the process of sending and
+        executing commands. The snapshot assumes perfect knowledge of the Sender and Receiver states
+        at a given instant, and serves as an essential illustration of the different possible
+        conditions that may occur when sending commands. For simplicity, the diagram shows only the
+        state for a single Sender and Receiver pair.
+      </p>
+
+      <picture title="Snapshot of a Session"><![CDATA[
+              Endpoint                                 Endpoint
+        +- - - - - - - - - +                      +- - - - - - - - +
+        |     Receiver     |   <- - - - - - - -   |     Sender     |
+        +- - - - - - - - - +                      +- - - - - - - - +
+        +------------------+                      +----------------+
+       /|      Sender      |\  --------------->  /|    Receiver    |\
+      / +------------------+ \                  / +----------------+ \
+     / /                    \ \                / /                  \ \
+    / /                      \ \              / /                    \ \
+   / /                        \ \            / /                      \ \
+  / /                          \ \          / /                        \ \
+ / /              replay buffer \ \        / /             input buffer \ \
++------------+---------------------+      +------------+-------------------+
+| ... C2 C3  |  C4 C5 C6 C7 C8 C9  |      | ... C3 C4  |  C5 C6  |  __ __  |
++------------+---------------------+      +------------+-------------------+
+ acknowledged           |     | |            executed  | received          |
+                        +-----+ |                      +-------------------+
+                           |    |                                |
+                           +    +                             capacity
+                          /      \
+                   in-flight*   blocked
+
+C1, C2, C3: executed by the receiver, and acknowledged at the sender
+        C4: executed by the receiver, but not acknowledged at the sender
+    C5, C6: received, but not yet executed by the receiver
+    C7, C8: transmitted by the sender, but not yet received (in-flight)*
+        C9: held by the sender awaiting capacity at the receiver
+
+  * Note that should a network failure occur at this instant, the
+    in-flight commands will be lost. In practice, neither the
+    sender nor receiver knows explicitly which of the
+    unacknowledged commands will be lost should a network failure
+    occur.
+]]>
+      </picture>
+
+      <dl title="Sender State">
+        <dt>acknowledged</dt>
+        <dd><p>The id of the last command acknowledged. This marks the head of the replay
+            buffer.</p></dd>
+
+        <dt>command-id</dt>
+        <dd><p>The id that will be assigned to the next command sent on the Session. This marks the
+            tail of the replay buffer. The id of any command in the replay buffer must fall between
+            acknowledged and command-id: acknowledged &lt; C.id &lt; command-id for all C in the
+            replay buffer</p></dd>
+      </dl>
+
+      <dl title="Receiver State">
+        <dt>executed</dt>
+        <dd><p>The id of the last command executed. This marks the head of the input
+            buffer.</p></dd>
+
+        <dt>received</dt>
+        <dd><p>The id of the last command received. This marks the end of the filled slots in the
+            input buffer.</p></dd>
+
+        <dt>capacity</dt>
+        <dd><p>The capacity of the input buffer. The sum of executed and capacity is the id of the
+            command that will fill the last slot in the input buffer.</p></dd>
+      </dl>
+    </doc>
+
+    <doc title="State Exchange">
+      <p>
+        Session Endpoints periodically exchange the following state
+        variables: <i>executed</i>, <i>capacity</i>, <i>acknowledged</i>, and <i>command-id</i>.
+        These state variables are carried on session frames (see <xref name="framing"/>). In
+        addition, endpoints also exchange the <i>received</i> state variable whenever they
+        (re)attach.
+      </p>
+
+      <p>
+        Each endpoint uses the knowledge of its partner's executed state to shrink the replay buffer
+        for outgoing commands. Each endpoint uses the knowledge of its partners capacity to match
+        its transmission rate to its partner's available receive capacity. Endpoints may use the
+        knowledge of their partners acknowledged state to bound the set of incoming commands subject
+        to replay at any given point.
+      </p>
+
+      <p>
+        When Session endpoints (re)attach, they compute where to begin replay (if necessary), the id
+        of the next incoming command, and when to block outgoing commands.
+      </p>
+
+      <picture><![CDATA[
+    Endpoint                               Endpoint
+    ================================================================
+    [CH3] [A,E,C,I] ATTACH(R)  ---------->                           (1)
+                                      +--- [CH7] [A,E,C,I] ATTACH(R)
+                                     /
+                                    /
+(1)                            <---+
+
+                                   ...
+
+    [CH3] [A,E,C,I] <CMD>      ---+   +--- [CH7] [A,E,C,I] <CMD>
+                                   \ /
+                                    x
+                                   / \
+(2)                            <--+   +--> (2)
+
+                                   ...
+
+    ----------------------------------------------------------------
+
+  Key:
+        A: acknowledged
+        E: executed
+        C: capacity
+        I: command-id
+        R: received
+    <CMD>: any command
+    CH<n>: channel number <n>
+
+  (1) Endpoints can establish where to begin replay, the
+      expected id of the next incoming command, and the
+      last outgoing command that may be sent before
+      blocking.
+
+  (2) The updated state may permit endpoints to reclaim
+      space in the replay buffer for outgoing commands,
+      transmit additional commands, and bound the set of
+      incoming commands subject to replay.
+]]>
+      </picture>
+
+      <p>
+        When sending a command, the session state carried with the command represents a snapshot of
+        the endpoint state at the time the command is first sent. This implies it MUST NOT be
+        altered if a command is replayed.
+      </p>
+
+      <p>
+        Any state update detected by the recipient MUST be processed <b>after</b> the contained
+        command is executed. This means the receiver infers an ordering between issued commands and
+        state updates that may be different from the actual ordering in which they occurred at the
+        sender. If it is important for the receiver to know the true ordering, the sender MUST send
+        the relevant state update in a separate frame. This may be done by sending an empty command
+        or control frame.
+      </p>
+    </doc>
+
+    <doc title="Session Exceptions" >
+      <p>
+        Session exceptions occur when an error is encountered while processing a command. In this
+        case the receiving peer MUST detach the Session by issuing an outgoing detach control
+        acknowledging the last successfully executed command and carrying information about the
+        exceptional condition.
+      </p>
+
+      <p>
+        Upon receiving any explicit detach, including those caused by exceptions, clients may choose
+        to reattach and resume just as they would from an ordinary network failure. If the detach
+        was caused by an exception, the client may choose, upon resume, to alter or omit any
+        unexecuted commands, i.e. those following the exceptional condition. A client SHOULD examine
+        the cause of failure and determine if it is likely to resolve itself before replaying
+        unmodified commands.
+      </p>
+
+      <picture><![CDATA[
+Endpoint                      Endpoint
+======================================================
+COMMAND_1         ---------->
+COMMAND_2         ---------->
+COMMAND_3         ---+   +--- DETACH(executed=1,
+                      \ /             exception="...")
+                       x
+                      / \
+                  <--+   +--> *discarded*
+DETACH            ---------->
+                      ...
+ATTACH            ---------->
+                  <---------- ATTACH(executed=1, ...)
+COMMAND_2'        ---------->
+COMMAND_3         ---------->
+                      ...
+======================================================
+]]>
+      </picture>
+    </doc>
+
+    <doc title="Transactional Sessions">
+      <p>
+        A Transactional Session is one in which one of the two Applications using the Session
+        behaves as a Transactional Resource, and the other behaves as a Transaction Controller. A
+        Transactional Session must be in one of three modes: "local", "distributed", or
+        "promotable". In these modes, the Transaction Controller defines transactional units of
+        work, and indicates whether each unit of work is a success or failure. On a Session with a
+        txn-mode of "local", each successful unit of work is immediately committed as a complete
+        transaction, and failed units of work are immediately rolled back. On a Session with a
+        txn-mode of "distributed", each unit of work is given an xid and becomes part of a
+        distributed transaction that is externally coordinated. On a Session with a txn-mode of
+        "promotable", each unit of work may optionally be given an xid to become part of an
+        externally coordinated distributed transaction, or if not given an xid it is treated as in
+        the "local" mode.
+      </p>
+
+      <p>
+        Applications capable of behaving as a Transactional Resource may advertise this when
+        establishing a Session by setting the txn-support field of the
+        <xref type="type" name="attach"/> control to "local", "distributed", or "promotable".
+        Applications that wish to behave as a Transaction Controller may indicate this and choose
+        the mode for the Transactional Session by setting the txn-mode field of the
+        <xref type="type" name="attach"/> control when establishing a Session. Only one end of a
+        Session can be the Transaction Controller. It is an error for both Session endpoints to set
+        the txn-mode field when when establishing a Session.
+      </p>
+
+      <p>
+        The transactional implications of each Command are determined by the semantics of the
+        Transactional Resource. Some Commands sent from the Transaction Controller to the
+        Transactional Resource may modify transactional state, while others may not. Likewise, some
+        Commands sent from the Resource to the Controller may carry information about the
+        transactional state of the Resource, while others may not. The state of the Command
+        Transport itself is not transactional. A Commit or Rollback may negate or confirm the
+        effects of a Command carried by the Transport, but it has no effect on the command-ids,
+        replay-buffers, or other Transport related state that falls within the scope of the
+        transaction.
+      </p>
+    </doc>
+
+  </section>
+
+  <!-- == Section: links ======================================================================= -->
+
+  <section name="links" label="the Link Protocol">
+    <doc>
+      <p>
+        The Link Protocol is used to transfer Messages between Nodes. A <i>Link</i> forms a
+        unidirectional conduit for Messages. Each Link consists of two <i>Link Endpoints</i>:
+        an <i>outgoing</i> endpoint, and an <i>incoming</i> endpoint. The outgoing endpoint is
+        associated with a <i>Source</i>, and the incoming endpoint is associated with
+        a <i>Target</i>. The source defines which Messages are supplied to the outgoing endpoint for
+        transfer, and the target defines how incoming Messages are disseminated. A Link may be
+        established from either the outgoing or incoming end.
+      </p>
+
+      <p>
+        Once established, Links impose a <i>transfer-limit</i> that is used by the incoming endpoint
+        to control the flow of Messages. When permitted by the transfer-limit, the outgoing endpoint
+        initiates the transfer of available Messages and communicates a disposition for each
+        transfer back to the Message source.
+      </p>
+
+      <p>
+        The scope of a Link controls what happens to open Links when a Session is closed.
+        A <i>container-scoped</i> Link Endpoint will be retained as long as the source and/or target
+        continue to exist. A <i>session-scoped</i> Link Endpoint is discarded upon Session closure.
+      </p>
+    </doc>
+
+    <doc title="Naming a Link">
+      <p>
+        Links are named so that Link Endpoints may be reconnected to each other when communication
+        is interrupted. Link names are chosen by the initiating peer, and MUST be unique within
+        their defined scope. The name of a container scoped Link MUST be unique among all Links from
+        the incoming container to the outgoing container, and the name of a Session scoped Link MUST
+        be similarly unique within the Session. This means that if either peer is permitted to
+        initiate a Link, then a strategy must be employed for avoiding conflicts, e.g. using a UUID
+        or dividing the available namespace in a prearranged manner. Link names are only used during
+        the initial establishment or reestablishment of a Link, so they may be arbitrarily long
+        without a significant penalty.
+      </p>
+    </doc>
+
+    <doc title="Link Handles">
+      <p>
+        Each Link Endpoint is assigned a numeric handle used by the peer as a shorthand to refer to
+        the Link in all commands that it sends in reference to the Link
+        (<xref type="type" name="link"/>, <xref type="type" name="relink"/>,
+        <xref type="type" name="unlink"/>, <xref type="type" name="flow"/>,
+        <xref type="type" name="drain"/>, <xref type="type" name="transfer"/>,
+        <xref type="type" name="bar"/>, <xref type="type" name="disposition"/>). The two Endpoints
+        are not required to use the same handle. This means a peer is free to independently chose
+        its handle when a Link Endpoint is associated with the Session. Each peer informs the parter
+        of its chosen handle for a given Link in the Link establishment phase.
+      </p>
+
+      <picture><![CDATA[
++--------------------+                             +--------------------+
+|      name: Link_1  |                             |      name: Link_1  |
+|     scope: session |                             |     scope: session |
+|    handle: i       |                             |    handle: j       |
+|--------------------|                             |--------------------|
+| direction: IN      |                             | direction: OUT     |
+|    source: NODE_A  |<---+                   +--->|    source: NODE_A  |
+|    target: NODE_B  |    |                   |    |    target: NODE_B  |
++--------------------+    |                   |    +--------------------+
+                          |                   |
+                          |    +---------+    |
+          ...         <---+--->| Session |<---+--->          ...
+                          |    +---------+    |
+                          |                   |
++--------------------+    |                   |    +--------------------+
+|      name: Link_N  |    |                   |    |      name: Link_N  |
+|     scope: cont    |<---+                   +--->|   durable: cont    |
+|    handle: k       |                             |    handle: l       |
+|--------------------|                             |--------------------|
+| direction: OUT     |                             | direction: IN      |
+|    source: NODE_C  |                             |    source: NODE_C  |
+|    target: NODE_D  |                             |    target: NODE_D  |
++--------------------+                             +--------------------+
+]]>
+      </picture>
+    </doc>
+
+    <doc title="Establishing a Link">
+      <p>
+        Links are established by creating a Link Endpoint, assigning it to an unused handle, and
+        sending a <xref type="type" name="link"/> command carrying the state of the newly created
+        Endpoint. The partner responds with a <xref type="type" name="link"/> command carrying the
+        state of the corresponding Endpoint, creating and/or mapping the Endpoint to an unused
+        handle if necessary.
+      </p>
+
+      <picture><![CDATA[
+Peer                                  Partner
+============================================================
+*create link endpoint*
+LINK(name=N, handle=1,    ----------> *create link endpoint*
+     scope=session,              +--- LINK(name=N, handle=2,
+     direction=OUT,             /          scope=session,
+     source=A,                 /           direction=IN,
+     target=B)                /            source=A,
+                          <--+             target=B)
+                              ...
+------------------------------------------------------------
+]]>
+      </picture>
+
+      <p>
+        If the partner finds a preexisting Link Endpoint, it MUST respond with the state of the
+        existing endpoint rather than creating a new endpoint. This state may not match the state of
+        the peer's endpoint. In the case where a Link is established between two endpoints with
+        conflicting state, the outgoing endpoint is considered to hold the authoritative version of
+        the source, the incoming endpoint is considered to hold the authoritative version of the
+        target, and the resulting Link state is constructed from the authoritative source and
+        target. Once such a Link is established, either peer is free to continue if the resulting
+        state is acceptable, or if not, <xref type="type" name="unlink"/> or
+        <xref type="type" name="relink"/>.
+      </p>
+
+      <picture><![CDATA[
+    Peer                                  Partner
+    ===============================================================
+    *create link endpoint*
+    LINK(name=N, handle=1,    ----------> *found existing endpoint*
+         scope=session,              +--- LINK(name=N, handle=2,    (1)
+         direction=OUT,             /          scope=session,
+         source=A,                 /           direction=IN,
+         target=B)                /            source=X,
+(2)                           <--+             target=Y)
+                                  ...
+    ---------------------------------------------------------------
+      (1) The Link Endpoint already exists, so its state
+          may not match the Peer's endpoint.
+      (2) At this point the Link is established with source=A,
+          target=Y.
+]]>
+      </picture>
+    </doc>
+
+    <doc title="Resuming a Link">
+      <p>
+        Container scoped Links exist beyond their host Session, so it is possible for a Session to
+        terminate and the container scoped Link Endpoints to remain. In this case the Link may be
+        resumed the same way a Link is initially established. The existing Link Endpoint is assigned
+        a handle within the new Session, and a <xref type="type" name="link"/> command is sent with
+        the state of the resuming endpoint.
+      </p>
+
+      <picture><![CDATA[
+    Peer                                  Partner
+    ===============================================================
+    *existing link endpoint*
+    LINK(name=N, handle=1,    ----------> *found existing endpoint*
+         scope=session,              +--- LINK(name=N, handle=2,    (1)
+         direction=OUT,             /          scope=session,
+         source=X,                 /           direction=IN,
+         target=Y)                /            source=X,
+(2)                           <--+             target=Y)
+                                  ...
+    ---------------------------------------------------------------
+      (1) The Link Endpoint already exists, and its state
+          matches the peer's endpoint.
+      (2) At this point the Link is reestablished with source=X,
+          target=Y.
+]]>
+      </picture>
+
+      <p>
+        It is possible to resume any container scoped Link knowing only the Link name and direction.
+        This is done by creating a new Link Endpoint with an empty source or target for incoming or
+        outgoing Links respectively. The full Link state is then constructed from the authoritative
+        source or target supplied by the other endpoint once the Link is established.
+      </p>
+
+      <picture><![CDATA[
+    Peer                                  Partner
+    ===============================================================
+    *create link endpoint*
+    LINK(name=N, handle=1,    ----------> *found existing endpoint*
+         scope=session,              +--- LINK(name=N, handle=2,    (1)
+         direction=OUT,             /          scope=session,
+         source=X,                 /           direction=IN,
+         target=-)                /            source=X,
+(2)                           <--+             target=Y)
+                                  ...
+    ---------------------------------------------------------------
+      (1) The Link Endpoint already exists, and its target
+          is authoritative.
+      (2) At this point the Link is reestablished with source=X,
+          target=Y.
+]]>
+      </picture>
+    </doc>
+
+    <doc title="Closing a Link">
+      <p>
+        A peer closes a Link by sending the <xref type="type" name="unlink"/> command with the Link
+        handle for the specified Link. The partner will destroy the corresponding Link end, and
+        reply with its own <xref type="type" name="unlink"/> command.
+      </p>
+
+      <picture><![CDATA[
+    Peer                                Partner
+    =============================================================
+    *create link endpoint*
+    LINK(name=N, handle=1,    ----------> *create link endpoint*
+         scope=session,              +--- LINK(name=N, handle=2,
+         direction=OUT,             /          scope=session,
+         source=A,                 /           direction=IN,
+         target=B)                /            source=A,
+                              <--+             target=B)
+                                  ...
+   *use link*                 <---------> *use link*
+                                  ...
+    UNLINK(handle=1)          ----------> *destroy link endpoint*
+(1) *destroy link endpoint*   <---------- UNLINK(handle=2)
+    -------------------------------------------------------------
+      (1) At this point both endpoints are destroyed.
+]]>
+      </picture>
+    </doc>
+
+    <doc title="Flow Control">
+      <p>
+        Once established, the outgoing end of a Link is subject to flow control of Message
+        transfers. The outgoing end of the Link maintains a <i>transfer-count</i>, as well as a
+        <i>transfer-limit</i>. The <i>transfer-count</i> is initialized to zero when the link is
+        established, and is incremented as message data is sent. If the transfer-count is the same
+        or greater than the transfer-limit, it is illegal to send more transfer commands until the
+        transfer-limit is increased. The <i>transfer-unit</i> defines how the transfer-count is
+        incremented. (See the <xref type="type" name="link"/> definition for details.)
+      </p>
+
+      <p>
+        The incoming end of the Link updates the transfer-limit by sending <xref type="type"
+        name="flow"/> commands. Flow control may be disabled entirely if the incoming end sends a
+        <xref type="type" name="flow"/> command with an empty value for the limit. Although not
+        required in all cases, it is often convenient for the incoming end of the Link to maintain a
+        transfer-count based on the received message data for use in determining an appropriate
+        value for the updated transfer-limit when sending a <xref type="type" name="flow"/> command.
+        The transfer-count, the received transfer-count, and the transfer-limit are all absolute
+        values. While the values themselves are conceptually unbounded, they are encoded as 32-bit
+        integers that wraparound and compare according to RFC-1982 serial number arithmetic.
+      </p>
+
+      <picture><![CDATA[
++----------------+                                 +----------------+
+|     Link_1     |                                 |     Link_1     |
+|----------------|                                 |----------------|
+| direction=OUT  |<----+                     +---->| direction=IN   |
+| transfer-count |     |                     |     | rcvd-xfr-count |
+| transfer-limit |     |                     |     |                |
++----------------+     |                     |     +----------------+
+                       |                     |
+                       |     +---------+     |
+       ...        <----+---->| Session |<----+---->       ...
+                       |     +---------+     |
+                       |                     |
++----------------+     |                     |     +----------------+
+|     Link_N     |     |                     |     |     Link_N     |
+|----------------|     |                     |     |----------------|
+| direction=IN   |<----+                     +---->| direction=OUT  |
+| rcvd-xfr-count |                                 | transfer-count |
+|                |                                 | transfer-limit |
++----------------+                                 +----------------+
+]]>
+      </picture>
+    </doc>
+
+    <doc title="Controlling Outgoing Transfers">
+      <p>
+        As message data is transferred on a Session, the sender increments the transfer-count for
+        the Link on which it is sent. AMQP peers must not send transfers in excess of the current
+        transfer-limit of a Link. If the transfer-limit is reduced by the receiving peer when
+        transfers are in-flight, the receiving peer may either handle the excess transfers normally
+        or detach the Session with a transfer-limit-exceeded error code.
+      </p>
+
+      <picture><![CDATA[
+      +--------+
+M1 -->| Link 1 |----+
+      +--------+    |
+                    |                 +---------+
+           ...  ----+---- M1, M2 ---->| Session |---->
+                    |                 +---------+
+      +--------+    |
+M2 -->| Link N |----+
+      +--------+
+          |
+          |
+          |
+ if transfer-count >= transfer-limit then block
+
+              M<n>: Message Transfer<n>
+]]>
+      </picture>
+    </doc>
+
+    <doc title="Controlling Incoming Transfers">
+      <p>
+        The <xref type="type" name="flow"/> and <xref type="type" name="drain"/> commands control
+        incoming transfers for a specific Link. The <xref type="type" name="flow"/> command updates
+        the transfer-limit for the specified Link. The <xref type="type" name="drain"/> command
+        tells the peer to send any immediately available transfers, and then set the transfer-limit
+        equal to the sent transfer-count, thus stopping the Link. Once the <xref type="type"
+        name="drain"/> command is complete, the Link will be stopped, and any immediately available
+        transfers will have been sent if permitted by the transfer-limit prior to receiving the
+        <xref type="type" name="drain"/>. These commands may be used to provide a variety of
+        different behaviors for receiving Messages.
+      </p>
+
+      <picture><![CDATA[
+            +--------+

[... 1783 lines stripped ...]


Mime
View raw message