An AMQP network consists of
A link is a unidirectional route between two nodes. A link attaches to a node at
a
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
Nodes exist within a
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
An AMQP connection is divided into a negotiated number of independent unidirectional
An AMQP
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
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
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
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
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
[
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
Frames are divided into three distinct areas: a fixed width frame header, a variable width extended header, and a variable width frame body.
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.
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.
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.
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).
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.
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
Bytes 6 and 7 of an AMQP frame contain the channel number (see
An AMQP frame with no body MAY be used to generate artificial traffic as needed to
satisfy any negotiated idle timeout interval (see
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
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
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
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
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
Implementations SHOULD NOT expect to be able to reuse open TCP sockets after
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
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
If a peer can not, for any reason support a proposed idle timeout, then it SHOULD close
the connection using a
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
Empty frames can only be sent after the
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
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.
In this state the connection header has been received from the peer but a connection header has not been sent.
In this state the connection header has been sent to the peer but no connection header has been received.
In this state the connection header has been sent to the peer and a connection header has been received from the peer.
In this state both the connection header and the
In this state, the connection header, the
In this state the connection headers have been exchanged. An
In this state the connection headers have been exchanged. An
In this state the connection headers have been exchanged. An
In this state the connection header and the
In this state a
In this state a
The DISCARDING state is a variant of the CLOSE_SENT state where the
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
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
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
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
When a session is unable to process input, it MUST indicate this by issuing an END with an
appropriate
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.
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.
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.
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.
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.
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.
The DISCARDING state is a variant of the END_SENT state where the
There is no obligation to retain a session endpoint after it transitions to the UNMAPPED state.
The session endpoint assigns each outgoing
The next-incoming-id identifies the expected transfer-id of the next incoming
The incoming-window defines the maximum number of incoming
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
The outgoing-window defines the maximum number of outgoing
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
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
Once initialized, this state is updated by various events that occur in the lifespan of a session and its associated links:
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.
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.
When the endpoint receives a
The remote-incoming-window is computed as follows:
next-incoming-idflow + incoming-windowflow - next-outgoing-idendpoint
If the next-incoming-id field of the
initial-outgoing-idendpoint + incoming-windowflow - next-outgoing-idendpoint
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
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:
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
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
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 (
At an endpoint, a link is considered to be
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
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
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
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
A session endpoint can choose to unmap its output handle for a link. In this case, the
endpoint MUST send a
When the state of a link endpoint changes, this is can be communicated by detaching and then
reattaching with the updated state on the
When an error occurs at a link endpoint, the endpoint MUST be detached with appropriate
error information supplied in the error field of the
A peer closes a link by sending the
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:
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.
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-creditsnd := delivery-countrcv + link-creditrcv - delivery-countsnd.
In the event that the receiver does not yet know the delivery-count, i.e.,
delivery-countrcv is unspecified, the sender MUST assume that
the delivery-countrcv is the first
delivery-countsnd sent from sender to receiver, i.e., the
delivery-countsnd specified in the flow state carried by the initial
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.
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.
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
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
[
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
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
Synchronous get with a timeout is accomplished by incrementing the link-credit, sending the
updated
Asynchronous notification can be accomplished as follows. The receiver maintains a target
amount of link-credit for that link. As
Stopping the transfers on a given link is accomplished by updating the link-credit to be
zero and sending the updated
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
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
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
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
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
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 in this category MUST be ignored by the sender, and MUST be considered settled by the receiver.
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
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
The sender MAY indicate an aborted attempt to deliver a message by setting the abort flag on
the last
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.
The name of the host (either fully qualified or relative) to which the sending peer is connecting. It is not mandatory to provide the hostname. If no hostname is provided the receiving peer SHOULD select a default based on its own configuration. This field can be used by AMQP proxies to determine the correct back-end service to connect the client to.
This field MAY already have been specified by the
The largest frame size that the sending peer is able to accept on this connection. If this field is not set it means that the peer does not impose any specific limit. A peer MUST NOT send frames larger than its partner can handle. A peer that receives an oversized frame MUST close the connection with the framing-error error-code.
Both peers MUST accept frames of up to
The channel-max value is the highest channel number that can be used on the connection. This value plus one is the maximum number of sessions that can be simultaneously active on the connection. A peer MUST not use channel numbers outside the range that its partner can handle. A peer that receives a channel number outside the supported range MUST close the connection with the framing-error error-code.
The idle timeout REQUIRED by the sender (see
If the value is not set, then the sender does not have an idle time-out. However, senders doing this SHOULD be aware that implementations MAY choose to use an internal default to efficiently manage a peer's resources.
A list of the locales that the peer supports for sending informational text. This
includes connection, session and link error descriptions. A peer MUST support at least
the en-US locale (see
A list of locales that the sending peer permits for incoming informational text. This list is ordered in decreasing level of preference. The receiving partner will choose the first (most preferred) incoming locale from those which it supports. If none of the requested locales are supported, en-US will be chosen. Note that en-US need not be supplied in this list as it is always the fallback. A peer MAY determine which of the permitted incoming locales is chosen by examining the partner's supported locales as specified in the outgoing-locales field. A null value or an empty list implies that only en-US is supported.
If the receiver of the offered-capabilities requires an extension capability which is not present in the offered-capability list then it MUST close the connection.
A registry of commonly defined connection capabilities and their meanings is maintained
[
The desired-capability list defines which extension capabilities the sender MAY use if the receiver offers them (i.e., they are in the offered-capabilities list received by the sender of the desired-capabilities). The sender MUST NOT attempt to use any capabilities it did not declare in the desired-capabilities field. If the receiver of the desired-capabilities offers extension capabilities which are not present in the desired-capabilities list it received, then it can be sure those (undesired) capabilities will not be used on the connection.
The properties map contains a set of fields intended to indicate information about the connection and its container.
A registry of commonly defined connection properties and their meanings is maintained
[
Indicate that a session has begun on the channel.
If a session is locally initiated, the remote-channel MUST NOT be set. When an endpoint responds to a remotely initiated session, the remote-channel MUST be set to the channel on which the remote session sent the begin.
See
See
See
The handle-max value is the highest handle value that can be used on the session. A peer MUST NOT attempt to attach a link using a handle value outside the range that its partner can handle. A peer that receives a handle outside the supported range MUST close the connection with the framing-error error-code.
A registry of commonly defined session capabilities and their meanings is maintained
[
The sender MUST NOT attempt to use any capability other than those it has declared in desired-capabilities field.
The properties map contains a set of fields intended to indicate information about the session and its container.
A registry of commonly defined session properties and their meanings is maintained
[
The
This name uniquely identifies the link from the container of the source to the container of the target node, e.g., if the container of the source node is A, and the container of the target node is B, the link MAY be globally identified by the (ordered) tuple (A,B,<name>).
The numeric handle assigned by the the peer as a shorthand to refer to the link in all
performatives that reference the link until the it is detached. See
The handle MUST NOT be used for other open links. An attempt to attach using a handle
which is already associated with a link MUST be responded to with an immediate
To make it easier to monitor AMQP link attach frames, it is RECOMMENDED that implementations always assign the lowest available handle to this field.
The role being played by the peer, i.e., whether the peer is the sender or the receiver of messages on the link.
The delivery settlement policy for the sender. When set at the receiver this indicates the desired value for the settlement mode at the sender. When set at the sender this indicates the actual settlement mode in use. The sender SHOULD respect the receiver's desired settlement mode if the receiver initiates the attach exchange and the sender supports the desired mode.
The delivery settlement policy for the receiver. When set at the sender this indicates the desired value for the settlement mode at the receiver. When set at the receiver this indicates the actual settlement mode in use. The receiver SHOULD respect the sender's desired settlement mode if the sender initiates the attach exchange and the receiver supports the desired mode.
If no source is specified on an outgoing link, then there is no source currently attached to the link. A link with no source will never produce outgoing messages.
If no target is specified on an incoming link, then there is no target currently attached to the link. A link with no target will never permit incoming messages.
This is used to indicate any unsettled delivery states when a suspended link is resumed.
The map is keyed by delivery-tag with values indicating the delivery state. The local
and remote delivery states for a given delivery-tag MUST be compared to resolve any
in-doubt deliveries. If necessary, deliveries MAY be resent, or resumed based on the
outcome of this comparison. See
If the local unsettled map is too large to be encoded within a frame of the agreed
maximum frame size then the session MAY be ended with the
The unsettled map MUST NOT contain null valued keys.
When reattaching (as opposed to resuming), the unsettled map MUST be null.
If set to true this field indicates that the unsettled map provided is not complete. When the map is incomplete the recipient of the map cannot take the absence of a delivery tag from the map as evidence of settlement. On receipt of an incomplete unsettled map a sending endpoint MUST NOT send any new deliveries (i.e. deliveries where resume is not set to true) to its partner (and a receiving endpoint which sent an incomplete unsettled map MUST detach with an error on receiving a transfer which does not have the resume flag set to true).
Note that if this flag is set to true then the endpoints MUST detach and reattach at least once in order to send new deliveries. This flag can be useful when there are too many entries in the unsettled map to fit within a single frame. An endpoint can attach, resume, settle, and detach until enough unsettled state has been cleared for an attach where this flag is set to false.
This MUST NOT be null if role is sender, and it is ignored if the role is receiver. See
This field indicates the maximum message size supported by the link endpoint. Any
attempt to deliver a message larger than this results in a message-size-exceeded
A registry of commonly defined link capabilities and their meanings is maintained
[
The sender MUST NOT attempt to use any capability other than those it has declared in desired-capabilities field.
The properties map contains a set of fields intended to indicate information about the link and its container.
A registry of commonly defined link properties and their meanings is maintained
[
Updates the flow state for the specified link.
Identifies the expected transfer-id of the next incoming
Defines the maximum number of incoming
The transfer-id that will be assigned to the next outgoing
Defines the maximum number of outgoing
If set, indicates that the flow frame carries flow state information for the local link endpoint associated with the given handle. If not set, the flow frame is carrying only information pertaining to the session endpoint.
If set to a handle that is not currently associated with an attached link, the
recipient MUST respond by ending the session with an
See
When the handle field is not set, this field MUST NOT be set.
When the handle identifies that the flow state is being sent from the sender link endpoint to receiver link endpoint this field MUST be set to the current delivery-count of the link endpoint.
When the flow state is being sent from the receiver endpoint to the sender endpoint this
field MUST be set to the last known value of the corresponding sending endpoint. In the
event that the receiving link endpoint has not yet seen the initial
The current maximum number of messages that can be handled at the receiver
endpoint of the link. Only the receiver endpoint can independently set this value. The
sender endpoint sets this to the last known value seen from the receiver. See
When the handle field is not set, this field MUST NOT be set.
The number of messages awaiting credit at the link sender endpoint. Only the
sender can independently set this value. The receiver sets this to the last known value
seen from the sender. See
When the handle field is not set, this field MUST NOT be set.
When flow state is sent from the sender to the receiver, this field contains the actual
drain mode of the sender. When flow state is sent from the receiver to the sender, this
field contains the desired drain mode of the receiver. See
When the handle field is not set, this field MUST NOT be set.
If set to true then the receiver SHOULD send its state at the earliest convenient opportunity.
If set to true, and the handle field is not set, then the sender only requires session endpoint state to be echoed, however, the receiver MAY fulfil this requirement by sending a flow performative carrying link-specific state (since any such flow also carries session state).
If a sender makes multiple requests for the same state before the receiver can reply, the receiver MAY send only one flow in return.
Note that if a peer responds to echo requests with flows which themselves have the echo field set to true, an infinite loop could result if its partner adopts the same policy (therefore such a policy SHOULD be avoided).
A registry of commonly defined link state properties and their meanings is maintained
[
When the handle field is not set, this field MUST NOT be set.
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.
Specifies the link on which the message is transferred.
The delivery-id MUST be supplied on the first transfer of a multi-transfer delivery. On continuation transfers the delivery-id MAY be omitted. It is an error if the delivery-id on a continuation transfer differs from the delivery-id on the first transfer of a delivery.
Uniquely identifies the delivery attempt for a given message on this link. This field MUST be specified for the first transfer of a multi-transfer message and can only be omitted for continuation transfers. It is an error if the delivery-tag on a continuation transfer differs from the delivery-tag on the first transfer of a delivery.
This field MUST be specified for the first transfer of a multi-transfer message and can only be omitted for continuation transfers. It is an error if the message-format on a continuation transfer differs from the message-format on the first transfer of a delivery.
If not set on the first (or only) transfer for a (multi-transfer) delivery, then the settled flag MUST be interpreted as being false. For subsequent transfers in a multi-transfer delivery if the settled flag is left unset then it MUST be interpreted as true if and only if the value of the settled flag on any of the preceding transfers was true; if no preceding transfer was sent with settled being true then the value when unset MUST be taken as false.
If the negotiated value for snd-settle-mode at attachment is
If the negotiated value for snd-settle-mode at attachment is
Note that if both the more and aborted fields are set to true, the aborted flag takes precedence. That is, a receiver SHOULD ignore the value of the more field if the transfer is marked as aborted. A sender SHOULD NOT set the more flag to true if it also sets the aborted flag to true.
If
If
If not set, this value is defaulted to the value negotiated on link attach.
If the negotiated link value is
If the message is being sent settled by the sender, the value of this field is ignored.
The (implicit or explicit) value of this field does not form part of the transfer state, and is not retained if a link is suspended and subsequently resumed.
When set this informs the receiver of the state of the delivery at the sender. This is
particularly useful when transfers of unsettled deliveries are resumed after resuming a
link. Setting the state on the transfer can be thought of as being equivalent to sending
a disposition immediately before the
Note that if the
If true, the resume flag indicates that the transfer is being used to reassociate an
unsettled delivery from a dissociated link endpoint. See
The receiver MUST ignore resumed deliveries that are not in its local unsettled map. The sender MUST NOT send resumed transfers for deliveries not in its local unsettled map.
If a resumed delivery spans more than one transfer performative, then the resume flag MUST be set to true on the first transfer of the resumed delivery. For subsequent transfers for the same delivery the resume flag MAY be set to true, or MAY be omitted.
In the case where the exchange of unsettled maps makes clear that all message data has been successfully transferred to the receiver, and that only the final state (and potentially settlement) at the sender needs to be conveyed, then a resumed delivery MAY carry no payload and instead act solely as a vehicle for carrying the terminal state of the delivery at the sender.
Aborted messages SHOULD be discarded by the recipient (any payload within the frame carrying the performative MUST be ignored). An aborted message is implicitly settled.
If true, then the issuer is hinting that there is no need for the peer to urgently communicate updated delivery state. This hint MAY be used to artificially increase the amount of batching an implementation uses when communicating delivery states, and thereby save bandwidth.
If the message being delivered is too large to fit within a single frame, then the
setting of batchable to true on any of the
The batchable value does not form part of the transfer state, and is not retained if a link is suspended and subsequently resumed.
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
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.
The role identifies whether the disposition frame contains information about sending link endpoints or receiving link endpoints.
Identifies the lower bound of delivery-ids for the deliveries in this set.
Identifies the upper bound of delivery-ids for the deliveries in this set. If not set, this is taken to be the same as first.
If true, indicates that the referenced deliveries are considered settled by the issuing endpoint.
Communicates the state of all the deliveries referenced by this disposition.
If true, then the issuer is hinting that there is no need for the peer to urgently communicate the impact of the updated delivery states. This hint MAY be used to artificially increase the amount of batching an implementation uses when communicating delivery states, and thereby save bandwidth.
Detach the link endpoint from the session. This unmaps the handle and makes it available for use by other links.
See
If set, this field indicates that the link is being detached due to an error condition. The value of the field SHOULD contain details on the cause of the error.
Indicates that the session has ended.
If set, this field indicates that the session is being ended due to an error condition. The value of the field SHOULD contain details on the cause of the error.
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.
If set, this field indicates that the connection is being closed due to an error condition. The value of the field SHOULD contain details on the cause of the error.
The sender will send all deliveries initially unsettled to the receiver.
The sender will send all deliveries settled to the receiver.
The sender MAY send a mixture of settled and unsettled deliveries to the receiver.
The receiver will spontaneously settle all incoming transfers.
The receiver will only settle after sending the
An alias established by the
A delivery-tag can be up to 32 octets of binary data.
A sequence-no encodes a serial number as defined in 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 [
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
A symbolic value indicating the error condition.
This text supplies any supplementary details not indicated by the condition field. This text can be logged as an aid to resolving issues.
An internal error occurred. Operator intervention might be necessary to resume normal operation.
A peer attempted to work with a remote entity that does not exist.
A peer attempted to work with a remote entity to which it has no access due to security settings.
Data could not be decoded.
A peer exceeded its resource allocation.
The peer tried to use a frame in a manner that is inconsistent with the semantics defined in the specification.
An invalid field was passed in a frame body, and the operation could not proceed.
The peer tried to use functionality that is not implemented in its partner.
The client attempted to work with a server entity to which it has no access because another client is working with it.
The client made a request that was not allowed because some precondition failed.
A server entity the client is working with has been deleted.
The peer sent a frame that is not permitted in the current state.
The peer cannot send a frame because the smallest encoding of the performative with the
currently valid values would be too large to fit within a frame of the agreed maximum
frame size. When transferring a message the message data can be sent in multiple
An operator intervened to close the connection for some reason. The client could retry at some later date.
A valid frame header cannot be formed from the incoming byte stream.
The container is no longer available on the current connection. The peer SHOULD attempt reconnection to the container using the details provided in the info map.
the hostname of the container. This is the value that SHOULD be supplied in the
hostname field of the
the DNS hostname or IP address of the machine hosting the container.
the port number on the machine hosting the container.
The peer violated incoming window for the session.
Input was received for a link that was detached with an error.
An attach was received using a handle that is already in use for an attached link.
A frame (other than attach) was received referencing a handle which is not currently in use of an attached link.
An operator intervened to detach for some reason.
The peer sent more message transfers than currently allowed on the link.
The peer sent a larger message than is supported on the link.
The address provided cannot be resolved to a terminus at the current container. The info map MAY contain the following information to allow the client to locate the attach to the terminus.
the hostname of the container hosting the terminus. This is the value that SHOULD
be supplied in the hostname field of the
the DNS hostname or IP address of the machine hosting the container.
the port number on the machine hosting the container.
the address of the terminus at the container.
The link has been attached elsewhere, causing the existing attachment to be forcibly closed.
The standard AMQP port number that has been assigned by IANA for TCP, UDP, and SCTP.
There are currently no UDP or SCTP mappings defined for AMQP. The port number is reserved for future transport mappings to these protocols.
The standard AMQP port number that has been assigned by IANA for secure TCP using TLS.
Implementations listening on this port SHOULD NOT expect a protocol handshake before TLS is negotiated.
During the initial connection negotiation, the two peers MUST agree upon a maximum frame size. This constant defines the minimum value to which the maximum frame size can be set. By defining this value, the peers can guarantee that they can send frames of up to this size until they have agreed a definitive maximum frame size for that connection.