An AMQP network consists of nodes connected via links. 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. A link attaches to a node at a terminus. There are two kinds of terminus: sources and targets. A terminus is responsible for tracking the state of a particular stream of incoming or outgoing messages. Sources track outgoing messages and targets track incoming messages. Messages only travel along a link if they meet the entry criteria at the source.

As a message travels through an AMQP network, the responsibility for safe storage and delivery of the message is transferred between the nodes it encounters. The link protocol (defined in section 2.6) manages the transfer of responsibility between the source and target.

Nodes exist within a container. Examples of containers are brokers and client applications. Each container MAY hold many nodes. Examples of AMQP nodes are producers, consumers, and queues. Producers and consumers are the elements within an application that generate and process messages. Queues are entities that store and forward messages.

The AMQP transport specification defines a peer-to-peer protocol for transferring messages between nodes in an 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.

In order for communication to occur between nodes in different containers a connection needs be established.

An AMQP connection consists of a full-duplex, reliably ordered sequence of frames. A frame is the unit of work carried on the wire. Connections have a negotiated maximum frame size allowing byte streams to be easily defragmented into complete frame bodies representing the independently parsable units formally defined in section 2.7. 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 can 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 framing system used to parse a byte stream into a sequence of frames for use in establishing an AMQP connection (see section 2.3).

An AMQP connection is divided into a negotiated number of independent unidirectional channels. Each frame is marked with the channel number indicating its parent channel, and the frame sequence for each channel is multiplexed into a single frame sequence for the connection.

An AMQP session correlates two unidirectional channels to form a bidirectional, sequential conversation between two containers. Sessions provide a flow control scheme based on the number of transfer frames transmitted. Since frames have a maximum size for a given connection, this provides flow control based on the number of bytes transmitted and can be used to optimize performance.

A single connection MAY have multiple independent sessions active simultaneously, up to the negotiated channel limit. Both connections and sessions are modeled by each peer as endpoints that store local and last known remote state regarding the connection or session in question.

In order to transfer messages between nodes (e.g., to move messages from a queue to a consumer) a link needs to be established between the nodes. A link is a unidirectional route between two nodes. A link attaches to a node at a terminus. There are two kinds of terminus: sources and targets. A terminus is responsible for tracking the state of a particular stream of incoming or outgoing messages. Sources track outgoing messages and targets track incoming messages. Messages only travel along a link if they meet the entry criteria at the source.

Links provide a credit-based flow control scheme based on the number of messages transmitted, allowing applications to control which nodes to receive messages from at a given point (e.g., to explicitly fetch a message from a given queue).

Sessions provide the context for communication between sources and targets. A link endpoint associates a terminus with a session endpoint. Within a session, the link protocol (defined in section 2.6) is used to establish links between sources and targets and to transfer messages across them. A single session can be simultaneously associated with any number of links.

Links are named, and the state at the termini can live longer than the connection on which they were established.

The retained state at the termini can be used to reestablish the link on a new connection (and session) with precise control over delivery guarantees (e.g., ensuring "exactly once" delivery).

The diagram below shows the relationship between the three AMQP communication endpoints, Connection, Session and Link.

The protocol consists of nine frame body types that are formally defined in section 2.7. The following table lists the frame bodies and defines which endpoints handle them.

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 1 (MAJOR), 0 (MINOR), 0 (REVISION)). In total this is an 8-octet sequence:

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.

The AMQP peer which acted in the role of the TCP client (i.e. the peer that actively opened the connection) MUST immediately send its outgoing protocol header on establishment of the TCP connection. 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. This permits a multi protocol server implementation to choose the correct protocol version to fit each client.

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):

• When the client opens a new socket connection to a server, it MUST send a protocol header with the client's preferred protocol version.

• 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.

• If the requested protocol version is not supported, the server MUST send a protocol header with a supported protocol version and then close the socket.

• 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.

• If the server cannot parse the protocol header, the server MUST send a valid protocol header with a supported protocol version and then close the socket.

• Note that if the server only supports a single protocol version, it is consistent with the above rules for the server to send its protocol header prior to receiving anything from the client and to subsequently close the socket if the client's protocol header does not match the server's.

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.

Please note that the above examples use the literal notation defined in RFC 2234 [RFC2234] for non alphanumeric values.

The protocol id is not a part of the protocol version and thus the rule above regarding the highest supported version does not apply. A client might request use of a protocol id that is unacceptable to a server - for example, it might request a raw AMQP connection when the server is configured to require a TLS or SASL security layer (See section 5.1). In this case, the server MUST send a protocol header with an acceptable protocol id (and version) and then close the socket. It MAY choose any protocol id.

Frames are divided into three distinct areas: a fixed width frame header, a variable width extended header, and a variable width frame body.

frame header

The frame header is a fixed size (8 byte) structure that precedes each frame. The frame header includes mandatory information necessary to parse the rest of the frame including size and type information.

extended header

The extended header is a variable width area preceding the frame body. This is an extension point defined for future expansion. The treatment of this area depends on the frame type.

frame body

The frame body is a variable width sequence of bytes the format of which depends on the frame type.

The diagram below shows the details of the general frame layout for all frame types.

SIZE

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 of the frame header, extended header, and frame body. The frame is malformed if the size is less than the size of the frame header (8 bytes).

DOFF

Byte 4 of the frame header is the data offset. This gives the position of the body within the frame. The value of the data offset is an unsigned, 8-bit integer specifying a count of 4-byte words. Due to the mandatory 8-byte frame header, the frame is malformed if the value is less than 2.

TYPE

Byte 5 of the frame header is a type code. The type code indicates the format and purpose of the frame. The subsequent bytes in the frame header MAY be interpreted differently depending on the type of the frame. A type code of 0x00 indicates that the frame is an AMQP frame. A type code of 0x01 indicates that the frame is a SASL frame, see section 5.3.

Bytes 6 and 7 of an AMQP frame contain the channel number (see section 2.1). The frame body is defined as a performative followed by an opaque payload. The performative MUST be one of those defined in section 2.7 and is encoded as a described type in the AMQP type system. The remaining bytes in the frame body form the payload for that frame. The presence and format of the payload is defined by the semantics of the given performative.

An AMQP frame with no body MAY be used to generate artificial traffic as needed to satisfy any negotiated idle timeout interval (see subsection 2.4.5).

AMQP connections are divided into a number of unidirectional channels. A connection endpoint contains two kinds of channel endpoints: incoming and outgoing. A connection endpoint maps incoming frames other than open and close to an incoming channel endpoint based on the incoming channel number, as well as relaying frames produced by outgoing channel endpoints, marking them with the associated outgoing channel number before sending them.

This requires connection endpoints to contain two mappings. One from incoming channel number to incoming channel endpoint, and one from outgoing channel endpoint, to outgoing channel number.

Channels are unidirectional, and thus at each connection endpoint the incoming and outgoing channels are completely distinct. Channel numbers are scoped relative to direction, thus there is no causal relation between incoming and outgoing channels that happen to be identified by the same number. This means that if a bidirectional endpoint is constructed from an incoming channel endpoint and an outgoing channel endpoint, the channel number used for incoming frames is not necessarily the same as the channel number used for outgoing frames.

Although not strictly directed at the connection endpoint, the begin and end frames are potentially useful for the connection endpoint to intercept as these frames are how sessions mark the beginning and ending of communication on a given channel (see section 2.5).

Each AMQP connection begins with an exchange of capabilities and limitations, including the maximum frame size. Prior to any explicit negotiation, the maximum frame size is 512 (MIN-MAX-FRAME-SIZE) and the maximum channel number is 0. After establishing or accepting a TCP connection and sending the protocol header, each peer MUST send an open frame before sending any other frames. The open frame describes the capabilities and limits of that peer. The open frame can only be sent on channel 0. After sending the open frame and reading its partner's open frame a peer MUST operate within mutually acceptable limitations from this point forward.

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 subsequent frames before receiving the partner's connection header or open frame. This is permitted so long as the pipelined frames are known a priori to conform to the capabilities and limitations of its partner. For example, this can 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 open frame.

The use of pipelined frames by a peer cannot be distinguished by the peer's partner from non-pipelined use so long as the pipelined frames conform to the partner's capabilities and limitations.

Prior to closing a connection, each peer MUST write a close frame with a code indicating the reason for closing. This frame MUST be the last thing ever written onto a connection. After writing this frame the peer SHOULD continue to read from the connection until it receives the partner's close frame (in order to guard against erroneously or maliciously implemented partners, a peer SHOULD implement a timeout to give its partner a reasonable time to receive and process the close before giving up and simply closing the underlying transport mechanism). A close frame MAY be received on any channel up to the maximum channel number negotiated in open. However, implementations SHOULD send it on channel 0, and MUST send it on channel 0 if pipelined in a single batch with the corresponding open.

Implementations SHOULD NOT expect to be able to reuse open TCP sockets after close performatives have been exchanged. There is no requirement for an implementation to read from a socket after a close performative has been received.

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.

Connections are subject to an idle timeout threshold. The timeout is triggered by a local peer when no frames are received after a threshold value is exceeded. The idle timeout is measured in milliseconds, and starts from the time the last frame is received. If the threshold is exceeded, then a peer SHOULD try to gracefully close the connection using a close frame with an error explaining why. If the remote peer does not respond gracefully within a threshold to this, then the peer MAY close the TCP socket.

Each peer has its own (independent) idle timeout. At connection open each peer communicates the maximum period between activity (frames) on the connection that it desires from its partner.The open frame carries the idle-time-out field for this purpose. To avoid spurious timeouts, the value in idle-time-out SHOULD be half the peer's actual timeout threshold.

If a peer can not, for any reason support a proposed idle timeout, then it SHOULD close the connection using a close frame with an error explaining why. There is no requirement for peers to support arbitrarily short or long idle timeouts.

The use of idle timeouts is in addition to any network protocol level control. Implementations SHOULD make use of TCP keep-alive wherever possible in order to be good citizens.

If a peer needs to satisfy the need to send traffic to prevent idle timeout, and has nothing to send, it MAY send an empty frame, i.e., a frame consisting solely of a frame header, with no frame body. Implementations MUST be prepared to handle empty frames arriving on any valid channel, though implementations SHOULD use channel 0 when sending empty frames, and MUST use channel 0 if a maximum channel number has not yet been negotiated (i.e., before an open frame has been received). Apart from this use, empty frames have no meaning.

Empty frames can only be sent after the open frame is sent. As they are a frame, they MUST NOT be sent after the close frame has been sent.

As an alternative to using an empty frame to prevent an idle timeout, if a connection is in a permissible state, an implementation MAY choose to send a flow frame for a valid session.

If during operation a peer exceeds the remote peer's idle timeout's threshold, e.g., because it is heavily loaded, it SHOULD gracefully close the connection by using a close frame with an error explaining why.

START

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.

HDR_RCVD

In this state the connection header has been received from the peer but a connection header has not been sent.

HDR_SENT

In this state the connection header has been sent to the peer but no connection header has been received.

HDR_EXCH

In this state the connection header has been sent to the peer and a connection header has been received from the peer.

OPEN_PIPE

In this state both the connection header and the open frame have been sent but nothing has been received.

OC_PIPE

In this state, the connection header, the open frame, any pipelined connection traffic, and the close frame have been sent but nothing has been received.

OPEN_RCVD

In this state the connection headers have been exchanged. An open frame has been received from the peer but an open frame has not been sent.

OPEN_SENT

In this state the connection headers have been exchanged. An open frame has been sent to the peer but no open frame has yet been received.

CLOSE_PIPE

In this state the connection headers have been exchanged. An open frame, any pipelined connection traffic, and the close frame have been sent but no open frame has yet been received from the peer.

OPENED

In this state the connection header and the open frame have been both sent and received.

CLOSE_RCVD

In this state a close frame has been received indicating that the peer has initiated an AMQP close. No further frames are expected to arrive on the connection; however, frames can still be sent. If desired, an implementation MAY do a TCP half-close at this point to shut down the read side of the connection.

CLOSE_SENT

In this state a close frame has been sent to the peer. It is illegal to write anything more onto the connection, however there could potentially still be incoming frames. If desired, an implementation MAY do a TCP half-close at this point to shutdown the write side of the connection.

DISCARDING

The DISCARDING state is a variant of the CLOSE_SENT state where the close is triggered by an error. In this case any incoming frames on the connection MUST be silently discarded until the peer's close frame is received.

END

In this state it is illegal for either endpoint to write anything more onto the connection. The connection can be safely closed and discarded.

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.

A session is a bidirectional sequential conversation between two containers that provides a grouping for related links. Sessions serve as the context for link communication. Any number of links of any directionality can be attached to a given session. However, a link MUST NOT be attached to more than one session at a time.

Messages transferred on a link are sequentially identified within the session. A session can be viewed as multiplexing link traffic, much like a connection multiplexes session traffic. However, unlike the sessions on a connection, links on a session are not entirely independent since they share a common delivery sequence scoped to the session. This common sequence allows endpoints to efficiently refer to sets of deliveries regardless of the originating link. This is of particular benefit when a single application is receiving messages along a large number of different links. In this case the session provides aggregation of otherwise independent links into a single stream that can be efficiently acknowledged by the receiving application.

Sessions are established by creating a session endpoint, assigning it to an unused channel number, and sending a begin announcing the association of the session endpoint with the outgoing channel. Upon receiving the begin the partner will check the remote-channel field and find it empty. This indicates that the begin is referring to remotely initiated session. The partner will therefore allocate an unused outgoing channel for the remotely initiated session and indicate this by sending its own begin setting the remote-channel field to the incoming channel of the remotely initiated session.

To make it easier to monitor AMQP sessions, it is RECOMMENDED that implementations always assign the lowest available unused channel number.

The remote-channel field of a begin frame MUST be empty for a locally initiated session, and MUST be set when announcing the endpoint created as a result of a remotely initiated session.

Sessions end automatically when the connection is closed or interrupted. Sessions are explicitly ended when either endpoint chooses to end the session. When a session is explicitly ended, an end frame is sent to announce the disassociation of the endpoint from its outgoing channel, and to carry error information when relevant.

Due to the potentially asynchronous nature of sessions, it is possible that both peers simultaneously decide to end a session. If this happens, it will appear to each peer as though their partner's spontaneously initiated end frame is actually an answer to the peers initial end frame.

When a session is unable to process input, it MUST indicate this by issuing an END with an appropriate error indicating the cause of the problem. It MUST then proceed to discard all incoming frames from the remote endpoint until receiving the remote endpoint's corresponding end frame.

UNMAPPED

In the UNMAPPED state, the session endpoint is not mapped to any incoming or outgoing channels on the connection endpoint. In this state an endpoint cannot send or receive frames.

BEGIN_SENT

In the BEGIN_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 frames but cannot receive them.

BEGIN_RCVD

In the BEGIN_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 frames, but cannot send them.

MAPPED

In the MAPPED state, the session endpoint has both an outgoing channel number and an entry in the incoming channel map. The endpoint MAY both send and receive frames.

END_SENT

In the END_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 frames, but cannot send them.

END_RCVD

In the END_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 frames, but cannot receive them.

DISCARDING

The DISCARDING state is a variant of the END_SENT state where the end is triggered by an error. In this case any incoming frames on the session MUST be silently discarded until the peer's end frame is received.

There is no obligation to retain a session endpoint after it transitions to the UNMAPPED state.

The session endpoint assigns each outgoing transfer frame an implicit transfer-id from a session scoped sequence. Each session endpoint maintains the following state to manage incoming and outgoing transfer frames:

next-incoming-id

The next-incoming-id identifies the expected transfer-id of the next incoming transfer frame.

incoming-window

The incoming-window defines the maximum number of incoming transfer frames that the endpoint can currently receive. This identifies a current maximum incoming transfer-id that can be computed by subtracting one from the sum of incoming-window and next-incoming-id.

next-outgoing-id

The next-outgoing-id is the transfer-id to assign to the next transfer frame. The next-outgoing-id MAY be initialized to an arbitrary value and is incremented after each successive transfer according to RFC-1982 [RFC1982] serial number arithmetic.

outgoing-window

The outgoing-window defines the maximum number of outgoing transfer frames that the endpoint can currently send. This identifies a current maximum outgoing transfer-id that can be computed by subtracting one from the sum of outgoing-window and next-outgoing-id.

remote-incoming-window

The remote-incoming-window reflects the maximum number of outgoing transfers that can be sent without exceeding the remote endpoint's incoming-window. This value MUST be decremented after every transfer frame is sent, and recomputed when informed of the remote session endpoint state.

remote-outgoing-window

The remote-outgoing-window reflects the maximum number of incoming transfers that MAY arrive without exceeding the remote endpoint's outgoing-window. This value MUST be decremented after every incoming transfer frame is received, and recomputed when informed of the remote session endpoint state. When this window shrinks, it is an indication of outstanding transfers. Settling outstanding transfers can cause the window to grow.

Once initialized, this state is updated by various events that occur in the lifespan of a session and its associated links:

sending a transfer

Upon sending a transfer, the sending endpoint will increment its next-outgoing-id, decrement its remote-incoming-window, and MAY (depending on policy) decrement its outgoing-window.

receiving a transfer

Upon receiving a transfer, the receiving endpoint will increment the next-incoming-id to match the implicit transfer-id of the incoming transfer plus one, as well as decrementing the remote-outgoing-window, and MAY (depending on policy) decrement its incoming-window.

receiving a flow

When the endpoint receives a flow frame from its peer, it MUST update the next-incoming-id directly from the next-outgoing-id of the frame, and it MUST update the remote-outgoing-window directly from the outgoing-window of the frame.

The remote-incoming-window is computed as follows:

next-incoming-id_flow + incoming-window_flow - next-outgoing-id_endpoint

If the next-incoming-id field of the flow frame is not set, then remote-incoming-window is computed as follows:

initial-outgoing-id_endpoint + incoming-window_flow - next-outgoing-id_endpoint

A link provides a unidirectional transport for messages between a source and a target. The primary responsibility of a source or target (a terminus) is to maintain a record of the status of each active delivery attempt until such a time as it is safe to forget. These are referred to as unsettled deliveries. When a terminus forgets the state associated with a delivery-tag, it is considered settled. Settling a delivery at a terminus is an idempotent idempotent, i.e., a delivery can transition from unsettled to settled, but never the reverse. Each delivery attempt is assigned a unique delivery-tag at the source. The status of an active delivery attempt is known as the delivery state of the delivery.

Link endpoints interface between a terminus and a session endpoint, and maintain additional state used for active communication between the local and remote endpoints. Therefore there are two types of endpoint: senders and receivers. When the sending application submits a message to the sender for transport, it also supplies the delivery-tag used by the source to track the delivery state. The link endpoint assigns each message a unique delivery-id from a session scoped sequence. These delivery-ids are used to efficiently reference subsets of the outstanding deliveries on a session.

Termini can exist beyond their associated link endpoints, so it is possible for a session to terminate and the termini to remain. A link is said to be suspended if the termini exist, but have no associated link endpoints. The process of associating new link endpoints with existing termini and re-establishing communication is referred to as resuming a link.

The original link endpoint state is not necessary for resumption of a link. Only the unsettled delivery state maintained at the termini is necessary for link resume, and this need not be stored directly. The form of delivery-tags is intentionally left open-ended so that they and their related delivery state can, if desired, be (re)constructed from application state, thereby minimizing or eliminating the need to retain additional protocol-specific state in order to resume a link.

Links are named so that they can be recovered when communication is interrupted. Link names MUST uniquely identify the link amongst all links of the same direction between the two participating containers. Link names are only used when attaching a link, so they can be arbitrarily long without a significant penalty.

A link's name uniquely identifies the link from the container of the source to the container of the target node, i.e., if the container of the source node is A, and the container of the target node is B, the link can be globally identified by the (ordered) tuple (A,B,<name>). Consequently, a link can only be active in one connection at a time. If an attempt is made to attach the link subsequently when it is not suspended, then the link can be 'stolen', i.e., the second attach succeeds and the first attach MUST then be closed with a link error of stolen. This behavior ensures that in the event of a connection failure occurring and being noticed by one party, that re-establishment has the desired effect.

Each link endpoint is assigned a numeric handle used by the peer as a shorthand to refer to the link in all frames that reference the link (attach, detach, flow, transfer, disposition). This handle is assigned by the initial attach frame and remains in use until the link is detached. 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. The locally chosen handle is referred to as the output handle. The remotely chosen handle is referred to as the input handle.

At an endpoint, a link is considered to be attached when the link endpoint exists and has both input and output handles assigned at an active session endpoint. A link is considered to be detached when the link endpoint exists, but is not assigned either input or output handles. A link can be considered half attached (or half detached) when only one of the input or output handles is assigned.

Links are established and/or resumed by creating a link endpoint associated with a local terminus, assigning it to an unused handle, and sending an attach frame. This frame carries the state of the newly created link endpoint, including the local and remote termini, one being the source and one being the target depending on the directionality of the link endpoint. On receipt of the attach, the remote session endpoint creates a corresponding link endpoint and informs its application of the attaching link. The application attempts to locate the terminus previously associated with the link. This terminus is associated with the link endpoint and can be updated if its properties do not match those sent by the remote link endpoint. If no such terminus exists, the application MAY choose to create one using the properties supplied by the remote link endpoint. The link endpoint is then mapped to an unused handle, and an attach frame is issued carrying the state of the newly created endpoint. Note that if the application chooses not to create a terminus, the session endpoint will still create a link endpoint and issue an attach indicating that the link endpoint has no associated local terminus. In this case, the session endpoint MUST immediately detach the newly created link endpoint.

If there is no pre-existing terminus, and the peer does not wish to create a new one, this is indicated by setting the local terminus (source or target as appropriate) to null.

If either end of the link is already associated with a terminus, the attach frame MUST include its unsettled delivery state.

Note that it is possible that the expected terminus properties do not match the actual terminus properties reported by the remote endpoint. In this case, the link is always considered to be between the source as described by the sender, and the target as described by the receiver. This can happen both when establishing and when resuming a link.

When a link is established, it is possible for an endpoint not to have all the capabilities necessary to create the terminus exactly matching the expectations of the peer. If this happens, the endpoint MAY adjust the properties in order to succeed in creating the terminus. In this case the endpoint MUST report the actual properties of the terminus as created.

When resuming a link, it is possible that the properties of the source and target have changed while the link was suspended. When this happens, the termini properties communicated in the source and target fields of the attach frames could be in conflict. In this case, the sender is considered to hold the authoritative version of the source properties, the receiver is considered to hold the authoritative version of the target properties. As above, the resulting link is constructed to be between the source as described by the sender, and the target as described by the receiver. Once the link is resumed, either peer is free to continue if the updated properties are acceptable, or, if not, detach the link.

Note that a peer MUST take responsibility for verifying that the remote terminus meets its requirements. The remote peer SHOULD NOT attempt to preempt whether the terminus will meet the requirements of its partner. This is equally true both for creating and resuming links.

It is possible to resume a link even if one of the termini has lost nearly all its state. All that is necessary is the link name and direction. This is referred to as recovering a link. 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. If the remote peer has no record of the link, then no terminus will be located, and local terminus (source or target as appropriate) field in the attach frame will be null.

A session endpoint can choose to unmap its output handle for a link. In this case, the endpoint MUST send a detach frame to inform the remote peer that the handle is no longer attached to the link endpoint. If both endpoints do this, the link MAY return to a fully detached state. Note that in this case the link endpoints MAY still indirectly communicate via the session, as there could still be active deliveries on the link referenced via delivery-id.

When the state of a link endpoint changes, this is can be communicated by detaching and then reattaching with the updated state on the attach frame. This can be used to update the properties of the link endpoints, or to update the properties of the termini.

When an error occurs at a link endpoint, the endpoint MUST be detached with appropriate error information supplied in the error field of the detach frame. The link endpoint MUST then be destroyed. If any input (other than a detach) related to the endpoint either via the input handle or delivery-ids be received, the session MUST be terminated with an errant-link session-error. Since the link endpoint has been destroyed, the peer cannot reattach, and MUST resume the link in order to restore communication. In order to disambiguate the resume request from a pipelined re-attach the resuming attach performative MUST contain a non-null value for its unsettled field. Receipt of a pipelined attach MUST result in the session being terminated with an errant-link session-error.

A peer closes a link by sending the detach frame with the handle for the specified link, and the closed flag set to true. The partner will destroy the corresponding link endpoint, and reply with its own detach frame with the closed flag set to true.

Note that one peer MAY send a closing detach while its partner is sending a non-closing detach. In this case, the partner MUST signal that it has closed the link by reattaching and then sending a closing detach.

Once attached, a link is subject to flow control of message transfers. Link endpoints maintain the following flow control state. This state defines when it is legal to send transfers on an attached link, as well as indicating when certain interesting conditions occur, such as insufficient messages to consume the currently available link-credit, or insufficient link-credit to send available messages:

delivery-count

The delivery-count is initialized by the sender when a link endpoint is created, and is incremented whenever a message is sent. Only the sender MAY independently modify this field. The receiver's value is calculated based on the last known value from the sender and any subsequent messages received on the link. Note that, despite its name, the delivery-count is not a count but a sequence number initialized at an arbitrary point by the sender.

link-credit

The link-credit variable defines the current maximum legal amount that the delivery-count can be increased by. This identifies a delivery-limit that can be computed by adding the link-credit to the delivery-count.

Only the receiver can independently choose a value for this field. The sender's value MUST always be maintained in such a way as to match the delivery-limit identified by the receiver. This means that the sender's link-credit variable MUST be set according to this formula when flow information is given by the receiver:

link-credit_snd := delivery-count_rcv + link-credit_rcv - delivery-count_snd.

In the event that the receiver does not yet know the delivery-count, i.e., delivery-count_rcv is unspecified, the sender MUST assume that the delivery-count_rcv is the first delivery-count_snd sent from sender to receiver, i.e., the delivery-count_snd specified in the flow state carried by the initial attach frame from the sender to the receiver.

Additionally, whenever the sender increases delivery-count, it MUST decrease link-credit by the same amount in order to maintain the delivery-limit identified by the receiver.

available

The available variable is controlled by the sender, and indicates to the receiver, that the sender could make use of the indicated amount of link-credit. Only the sender can independently modify this field. The receiver's value is calculated based on the last known value from the sender and any subsequent incoming messages received. The sender MAY transfer messages even if the available variable is zero. If this happens, the receiver MUST maintain a floor of zero in its calculation of the value of available.

drain

The drain flag indicates how the sender SHOULD behave when insufficient messages are available to consume the current link-credit. If set, the sender will (after sending all available messages) advance the delivery-count as much as possible, consuming all link-credit, and send the flow state to the receiver. Only the receiver can independently modify this field. The sender's value is always the last known value indicated by the receiver.

If the link-credit is less than or equal to zero, i.e., the delivery-count is the same as or greater than the delivery-limit, a sender MUST NOT send more messages. If the link-credit is reduced by the receiver when transfers are in-flight, the receiver MAY either handle the excess messages normally or detach the link with a transfer-limit-exceeded error code.

If the sender's drain flag is set and there are no available messages, the sender MUST advance its delivery-count until link-credit is zero, and send its updated flow state to the receiver.

The delivery-count is an absolute value. While the value itself is conceptually unbounded, it is encoded as a 32-bit integer that wraps around and compares according to RFC-1982 [RFC1982] serial number arithmetic.

The initial flow state of a link endpoint is determined as follows. The link-credit and available variables are initialized to zero. The drain flag is initialized to false. The sender MAY choose an arbitrary point to initialize the delivery-count. This value is communicated in the initial attach frame. The receiver initializes its delivery-count upon receiving the sender's attach.

The flow control semantics defined in this section provide the primitives necessary to implement a wide variety of flow control strategies. Additionally, by manipulating the link-credit and drain flag, a receiver can provide a variety of different higher level behaviors often useful to applications, including synchronous blocking fetch, synchronous fetch with a timeout, asynchronous notifications, and stopping/pausing.

A synchronous get of a message from a link is accomplished by incrementing the link-credit, sending the updated flow state, and waiting indefinitely for a transfer to arrive.

Synchronous get with a timeout is accomplished by incrementing the link-credit, sending the updated flow state and waiting for the link-credit to be consumed. When the desired time has elapsed the receiver then sets the drain flag and sends the newly updated flow state again, while continuing to wait for the link-credit to be consumed. Even if no messages are available, this condition will be met promptly because of the drain flag. Once the link-credit is consumed, the receiver can unambiguously determine whether a message has arrived or whether the operation has timed out.

Asynchronous notification can be accomplished as follows. The receiver maintains a target amount of link-credit for that link. As transfers arrive on the link, the sender's link-credit decreases as the delivery-count increases. When the sender's link-credit falls below a threshold, the flow state MAY be sent to increase the sender's link-credit back to the desired target amount.

Stopping the transfers on a given link is accomplished by updating the link-credit to be zero and sending the updated flow state. It is possible that some transfers could be in flight at the time the flow state is sent, so incoming transfers could still arrive on the link. The echo field of the flow frame MAY be used to request the sender's flow state be echoed back. This MAY be used to determine when the link has finally quiesced.

The transport layer assumes as little as possible about messages and allows alternative message representations to be layered above. Message data is carried as the payload in frames containing the transfer performative. Messages can be fragmented across several transfer frames as indicated by the more flag of the transfer performative.

When an application initiates a message transfer, it assigns a delivery-tag used to track the state of the delivery while the message is in transit. A delivery is considered unsettled at the sender/receiver from the point at which it was sent/received until it has been settled by the sending/receiving application. Each delivery MUST be identified by a delivery-tag chosen by the sending application. The delivery-tag MUST be unique amongst all deliveries that could be considered unsettled by either end of the link.

Upon initiating a transfer, the application will supply the sending link endpoint (Sender) with the message data and its associated delivery-tag. The sender will create an entry in its unsettled map, and send a transfer frame that includes the delivery-tag, the delivery's initial state, and its associated message data. For brevity on the wire, the delivery-tag is also associated with a delivery-id assigned by the session. The delivery-id is then used to refer to the delivery-tag in all subsequent interactions on that session.

The following diagrams illustrate the fundamentals involved in transferring a message. For normative semantics please refer to the definitions of the transfer and disposition performatives. For simplicity the delivery-id is omitted in the following diagrams and the delivery-tag is itself used directly. These diagrams also assume that this interaction takes place in the context of a single established link, and as such omit other details that would be present on the wire in practice such as the channel number, link handle, fragmentation flags, etc., focusing only on the essential aspects of message transfer.

Upon receiving the transfer, the receiving link endpoint (receiver) will create an entry in its own unsettled map and make the transferred message data available to the application to process.

Once notified of the received message data, the application processes the message, indicating the updated delivery state to the link endpoint as desired. Applications MAY wish to classify delivery states as terminal or non-terminal depending on whether an endpoint will ever update the state further once it has been reached. In some cases (e.g., large messages or transactions), the receiving application MAY wish to indicate non-terminal delivery states to the sender. This is done via the disposition frame.

Once the receiving application has finished processing the message, it indicates to the link endpoint a terminal delivery state that reflects the outcome of the application processing (successful or otherwise) and thus the outcome which the receiver wishes to occur at the sender. This state is communicated back to the sender via the disposition frame.

Upon receiving the updated delivery state from the receiver, the sender will, if it has not already spontaneously attained a terminal state (e.g., through the expiry of the TTL at the sender), update its view of the state and communicate this back to the sending application.

The sending application will then typically perform some action based on this terminal state and then settle the delivery, causing the sender to remove the delivery-tag from its unsettled map. The sender will then send its final delivery state along with an indication that the delivery is settled at the sender. Note that this amounts to the sender announcing that it is forever forgetting everything about the delivery-tag in question, and as such it is only possible to make such an announcement once, since after the sender forgets, it has no way of remembering to make the announcement again. If this frame gets lost due to an interruption in communication, the receiver will find out that the sender has settled the delivery upon link recovery. When the sender re-attaches the receiver will examine the unsettled state of the sender (i.e., what has not been forgotten) and from this can derive that the delivery in question has been settled (since its tag will not be in the unsettled state).

When the receiver finds out that the sender has settled the delivery, the receiver will update its view of the remote state to indicate this, and then notify the receiving application.

The application can then perform some final action, e.g., remove the delivery-tag from a set kept for de-duplication, and then notify the receiver that the delivery is settled. The receiver will then remove the delivery-tag from its unsettled map. Note that because the receiver knows that the delivery is already settled at the sender, it makes no effort to notify the other endpoint that it is settling the delivery.

As alluded to above, it is possible for the sending application to transition a delivery to a terminal state at the sender spontaneously (i.e., not as a consequence of a disposition that has been received from the receiver). In this case the sender SHOULD send a disposition to the receiver, but not settle until the receiver confirms, via a disposition in the opposite direction, that it has updated the state at its endpoint.

This set of exchanges illustrates the basic principals of message transfer. While a delivery is unsettled the endpoints exchange the current state of the delivery. Eventually both endpoints reach a terminal state as indicated by the application. This triggers the other application to take some final action and settle the delivery, and once one endpoint settles, this usually triggers the application at the other endpoint to settle.

This basic pattern can be modified in a variety of ways to achieve different guarantees. For example if the sending application settles the delivery before sending it, this results in an at-most-once guarantee. The sender has indicated up front with his initial transmission that he has forgotten everything about this delivery and will therefore make no further attempts to send it. If this delivery makes it to the receiver, the receiver clearly has no obligation to respond with updates of the receiver's delivery state, as they would be meaningless and ignored by the sender.

Similarly, if the basic scenario is modified such that the receiving application chooses to settle immediately upon processing the message rather than waiting for the sender to settle first, that yields an at-least-once guarantee. If the disposition frame indicated below is lost, then upon link recovery the sender will not see the delivery-tag in the receiver's unsettled map and will therefore assume the delivery was lost and resend it, resulting in duplicate processing of the message at the receiver.

As one might guess, the scenario presented initially where the sending application settles when the receiver reaches a terminal state, and the receiving application settles when the sender settles, results in an exactly-once guarantee. More generally if the receiver settles prior to the sender, it is possible for duplicate messages to occur, except in the case where the sender settles before the initial transmission. Similarly, if the sender settles before the receiver reaches a terminal state, it is possible for messages to be lost.

The sender and receiver policy regarding settling can either be preconfigured for the entire link, thereby allowing for optimized endpoint choices, or can be determined on an ad-hoc basis for each delivery. An application MAY also choose to settle at an endpoint independently of its delivery state, for example the sending application MAY choose to settle a delivery due to the message ttl expiring regardless of whether the receiver has reached a terminal state.

When a suspended link having unsettled deliveries is resumed, the unsettled field from the attach frame will carry the delivery-tags and delivery state of all deliveries considered unsettled by the issuing link endpoint. The set of delivery tags and delivery states contained in the unsettled maps from both endpoints can be divided into three categories:

Deliveries that only the source considers unsettled

Deliveries in this category MAY be resumed at the discretion of the sending application. If the sending application marks the resend attempt as a resumed delivery then it MUST be ignored by the receiver. (This allows the sender to pipeline resumes without risk of duplication at the sender).

Deliveries that only the target considers unsettled

Deliveries in this category MUST be ignored by the sender, and MUST be considered settled by the receiver.

Deliveries that both the source and target consider unsettled

Deliveries in this category MUST be resumed by the sender.

Note that in the case where an endpoint indicates that the unsettled map is incomplete, the absence of an entry in the unsettled map is not an indication of settlement. In this case the two endpoints MUST reduce the levels of unsettled state as much as they can by the sender resuming and/or settling transfers that it observes that the receiver considers unsettled. Upon completion of this reduction of state, the two parties MUST suspend and re-attempt to resume the link. Only when both sides have complete unsettled maps can new unsettled state be created by the sending of non-resuming transfers.

A delivery is resumed much the same way it is initially transferred with the following exceptions:

• The resume flag of the transfer frame MUST be set to true when resuming a delivery.

• The sender MAY omit message data when the delivery state of the receiver indicates retransmission is unnecessary.

Note that unsettled delivery-tags do NOT have any valid delivery-ids associated until they are resumed, as the delivery-ids from their original link endpoints are meaningless to the new link endpoints.

Each transfer frame can carry an arbitrary amount of message data up to the limit imposed by the maximum frame size. For messages that are too large to fit within the maximum frame size, additional data MAY be transferred in additional transfer frames by setting the more flag on all but the last transfer frame. When a message is split up into multiple transfer frames in this manner, messages being transferred along different links MAY be interleaved. However, messages transferred along a single link MUST NOT be interleaved.

The sender MAY indicate an aborted attempt to deliver a message by setting the abort flag on the last transfer. In this case the receiver MUST discard the message data that was transferred prior to the abort.

The first frame sent on a connection in either direction MUST contain an open performative. Note that the connection header which is sent first on the connection is not a frame.

The fields indicate the capabilities and limitations of the sending peer.

Indicate that a session has begun on the channel.

The attach frame indicates that a link endpoint has been attached to the session.

Updates the flow state for the specified link.

The transfer frame is used to send messages across a link. Messages MAY be carried by a single transfer up to the maximum negotiated frame size for the connection. Larger messages MAY be split across several transfer frames.

The disposition frame is used to inform the remote peer of local changes in the state of deliveries. The disposition frame MAY reference deliveries from many different links associated with a session, although all links MUST have the directionality indicated by the specified role.

Note that it is possible for a disposition sent from sender to receiver to refer to a delivery which has not yet completed (i.e., a delivery which is spread over multiple frames and not all frames have yet been sent). The use of such interleaving is discouraged in favor of carrying the modified state on the next transfer performative for the delivery.

The disposition performative MAY refer to deliveries on links that are no longer attached. As long as the links have not been closed or detached with an error then the deliveries are still "live" and the updated state MUST be applied.

Detach the link endpoint from the session. This unmaps the handle and makes it available for use by other links.

Indicates that the session has ended.

Sending a close signals that the sender will not be sending any more frames (or bytes of any other kind) on the connection. Orderly shutdown requires that this frame MUST be written by the sender. It is illegal to send any more frames (or bytes of any other kind) after sending a close frame.

An alias established by the attach frame and subsequently used by endpoints as a shorthand to refer to the link in all outgoing frames. The two endpoints MAY potentially use different handles to refer to the same link. Link handles MAY be reused once a link is closed for both send and receive.

A delivery-tag can be up to 32 octets of binary data.

A sequence-no encodes a serial number as defined in RFC-1982 [RFC1982]. The arithmetic and operators for these numbers are defined by RFC-1982.

The upper three octets of a message format code identify a particular message format. The lowest octet indicates the version of said message format. Any given version of a format is forwards compatible with all higher versions.

IETF language tags are abbreviated language codes as defined in the IETF Best Current Practice BCP-47 [BCP47] (incorporating IETF RFC-5646 [RFC5646]). A list of registered subtags is maintained in the IANA Language Subtag Registry [IANASUBTAG].

All AMQP implementations SHOULD understand at the least the IETF language tag en-US (note that this uses a hyphen separator, not an underscore).

The fields type is a map where the keys are restricted to be of type symbol (this excludes the possibility of a null key). There is no further restriction implied by the fields type on the allowed values for the entries or the set of allowed keys.