The messaging layer builds on top of the concepts described in Types and Transport. The transport layer defines a number of extension points suitable for use in a variety of different messaging applications. The messaging layer specifies a standardized use of these to provide interoperable messaging capabilities. This standard covers:

• message format

  • properties for the bare message

  • formats for structured and unstructured sections in the bare message

  • headers and footers for the annotated message

• delivery states for messages traveling between nodes

• states for messages stored at a distribution node

• sources and targets

  • default disposition of transfers

  • supported outcomes

  • filtering of messages from a node

  • distribution-mode for access to messages stored at a distribution node

  • on-demand node creation

The term message is used with various connotations in the messaging world. The sender might like to think of the message as an immutable payload handed off to the messaging infrastructure for delivery. The receiver often thinks of the message as not only that immutable payload from the sender, but also various annotations supplied by the messaging infrastructure along the way. To avoid confusion we formally define the term bare message to mean the message as supplied by the sender and the term annotated message to mean the message as seen at the receiver.

An annotated message consists of the bare message plus sections for annotation at the head and tail of the bare message. There are two classes of annotations: annotations that travel with the message indefinitely, and annotations that are consumed by the next node.

The bare message consists of three sections: standard properties, application-properties, and application-data (the body).

The bare message is immutable within the AMQP network. That is, none of the sections can be changed by any node acting as an AMQP intermediary. If a section of the bare message is omitted, one MUST NOT be inserted by an intermediary. The exact encoding of sections of the bare message MUST NOT be modified. This preserves message hashes, HMACs and signatures based on the binary encoding of the bare message.

The exact structure of a message, together with its encoding, is defined by the message format. This document defines the structure and semantics of message format 0 (MESSAGE-FORMAT). Altogether a message consists of the following sections:

• Zero or one header sections.

• Zero or one delivery-annotation sections.

• Zero or one message-annotation sections.

• Zero or one properties sections.

• Zero or one application-properties sections.

• The body consists of one of the following three choices: one or more data sections, one or more amqp-sequence sections, or a single amqp-value section.

• Zero or one footer sections.

The header section carries standard delivery details about the transfer of a message through the AMQP network. If the header section is omitted the receiver MUST assume the appropriate default values (or the meaning implied by no value being set) for the fields within the header unless other target or node specific defaults have otherwise been set.

The delivery-annotations section is used for delivery-specific non-standard properties at the head of the message. Delivery annotations convey information from the sending peer to the receiving peer. If the recipient does not understand the annotation it cannot be acted upon and its effects (such as any implied propagation) cannot be acted upon. Annotations might be specific to one implementation, or common to multiple implementations. The capabilities negotiated on link attach and on the source and target SHOULD be used to establish which annotations a peer supports. A registry of defined annotations and their meanings is maintained [AMQPDELANN]. The symbolic key "rejected" is reserved for the use of communicating error information regarding rejected messages. Any values associated with the "rejected" key MUST be of type error.

If the delivery-annotations section is omitted, it is equivalent to a delivery-annotations section containing an empty map of annotations.

The message-annotations section is used for properties of the message which are aimed at the infrastructure and SHOULD be propagated across every delivery step. Message annotations convey information about the message. Intermediaries MUST propagate the annotations unless the annotations are explicitly augmented or modified (e.g., by the use of the modified outcome).

The capabilities negotiated on link attach and on the source and target can be used to establish which annotations a peer understands; however, in a network of AMQP intermediaries it might not be possible to know if every intermediary will understand the annotation. Note that for some annotations it might not be necessary for the intermediary to understand their purpose, i.e., they could be used purely as an attribute which can be filtered on.

A registry of defined annotations and their meanings is maintained [AMQPMESSANN].

If the message-annotations section is omitted, it is equivalent to a message-annotations section containing an empty map of annotations.

The properties section is used for a defined set of standard properties of the message. The properties section is part of the bare message; therefore, if retransmitted by an intermediary, it MUST remain unaltered.

The application-properties section is a part of the bare message used for structured application data. Intermediaries can use the data within this structure for the purposes of filtering or routing.

The keys of this map are restricted to be of type string (which excludes the possibility of a null key) and the values are restricted to be of simple types only, that is, excluding map, list, and array types.

A data section contains opaque binary data.

A sequence section contains an arbitrary number of structured data elements.

An amqp-value section contains a single AMQP value.

The footer section is used for details about the message or delivery which can only be calculated or evaluated once the whole bare message has been constructed or seen (for example message hashes, HMACs, signatures and encryption details).

A registry of defined footers and their meanings is maintained [AMQPFOOTER].

The annotations type is a map where the keys are restricted to be of type symbol or of type ulong. All ulong keys, and all symbolic keys except those beginning with "x-" are reserved. Keys beginning with "x-opt-" MUST be ignored if not understood. On receiving an annotation key which is not understood, and which does not begin with "x-opt", the receiving AMQP container MUST detach the link with a not-implemented error.

The messaging layer defines a set of states for a distribution node, defined as a node that stores messages for distribution. Not all nodes are distribution nodes; however, these definitions permit some standardized interaction with those nodes that do. The transitions between these states are controlled by the transfer of messages to/from a distribution node and the resulting terminal delivery state. Note that the state of a message at one distribution node does not affect the state of the same message at a separate node.

By default a message will begin in the AVAILABLE state. Prior to initiating an acquiring transfer, the message will transition to the ACQUIRED state. Once in the ACQUIRED state, a message is ineligible for acquiring transfers to any other links.

A message will remain ACQUIRED at the distribution node until the transfer is settled. The delivery state at the receiver determines how the message transitions when the transfer is settled. If the delivery state at the receiver is not yet known, (e.g., the link endpoint is destroyed before recovery occurs) the default-outcome of the source is used (see source).

State transitions can also occur spontaneously at the distribution node. For example if a message with a ttl expires, the effect of expiry might be (depending on specific type and configuration of the distribution node) to move spontaneously from the AVAILABLE state into the ARCHIVED state. In this case any transfers of the message are transitioned to a terminal outcome at the distribution node regardless of receiver state.

The messaging layer defines a concrete set of delivery states which can be used (via the disposition frame) to indicate the state of the message at the receiver. Delivery states can be either terminal or non-terminal. Once a delivery reaches a terminal delivery state, the state for that delivery will no longer change. A terminal delivery state is referred to as an outcome.

The following outcomes are formally defined by the messaging layer to indicate the result of processing at the receiver:

• accepted: indicates successful processing at the receiver.

• rejected: indicates an invalid and unprocessable message.

• released: indicates that the message was not (and will not be) processed.

• modified: indicates that the message was modified, but not processed.

The following non-terminal delivery-state is formally defined by the messaging layer for use during link recovery to allow the sender to resume the transfer of a large message without retransmitting all the message data:

• received: indicates partial message data seen by the receiver as well as the starting point for a resumed transfer.

At the target the received state indicates the furthest point in the payload of the message which the target will not need to have resent if the link is resumed. At the source the received state represents the earliest point in the payload which the sender is able to resume transferring at in the case of link resumption. When resuming a delivery, if this state is set on the first transfer performative it indicates the offset in the payload at which the first resumed delivery is starting. The sender MUST NOT send the received state on transfer or disposition performatives except on the first transfer performative on a resumed delivery.

At the source the accepted state means that the message has been retired from the node, and transfer of payload data will not be able to be resumed if the link becomes suspended. A delivery can become accepted at the source even before all transfer frames have been sent, this does not imply that the remaining transfers for the delivery will not be sent - only the aborted flag on the transfer performative can be used to indicate a premature termination of the transfer.

At the target, the accepted outcome is used to indicate that an incoming message has been successfully processed, and that the receiver of the message is expecting the sender to transition the delivery to the accepted state at the source.

The accepted outcome does not increment the delivery-count in the header of the accepted message.

At the target, the rejected outcome is used to indicate that an incoming message is invalid and therefore unprocessable. The rejected outcome when applied to a message will cause the delivery-count to be incremented in the header of the rejected message.

At the source, the rejected outcome means that the target has informed the source that the message was rejected, and the source has taken the necessary action. The delivery SHOULD NOT ever spontaneously attain the rejected state at the source.

At the source the released outcome means that the message is no longer acquired by the receiver, and has been made available for (re-)delivery to the same or other targets receiving from the node. The message is unchanged at the node (i.e., the delivery-count of the header of the released message MUST NOT be incremented). As released is a terminal outcome, transfer of payload data will not be able to be resumed if the link becomes suspended. A delivery can become released at the source even before all transfer frames have been sent. This does not imply that the remaining transfers for the delivery will not be sent. The source MAY spontaneously attain the released outcome for a message (for example the source might implement some sort of time-bound acquisition lock, after which the acquisition of a message at a node is revoked to allow for delivery to an alternative consumer).

At the target, the released outcome is used to indicate that a given transfer was not and will not be acted upon.

At the source the modified outcome means that the message is no longer acquired by the receiver, and has been made available for (re-)delivery to the same or other targets receiving from the node. The message has been changed at the node in the ways indicated by the fields of the outcome. As modified is a terminal outcome, transfer of payload data will not be able to be resumed if the link becomes suspended. A delivery can become modified at the source even before all transfer frames have been sent. This does not imply that the remaining transfers for the delivery will not be sent. The source MAY spontaneously attain the modified outcome for a message (for example the source might implement some sort of time-bound acquisition lock, after which the acquisition of a message at a node is revoked to allow for delivery to an alternative consumer with the message modified in some way to denote the previous failed, e.g., with delivery-failed set to true).

At the target, the modified outcome is used to indicate that a given transfer was not and will not be acted upon, and that the message SHOULD be modified in the specified ways at the node.

subsection 2.6.13 provides the general scheme for how two endpoints can re-establish state after link resumption was provided. The concrete delivery states defined above allow for a more comprehensive set of examples of link resumption.

In this example, for delivery-tags 1 to 4 inclusive the sender indicates that it can resume sending from the start of the message.

For delivery-tag 1, the receiver has no record of the delivery. To preserve "exactly once" or "at least once" delivery guarantees, the sender MUST resend the message; however, the delivery is not being resumed (since the receiver does not remember the delivery tag) so transfers MUST NOT have the resume flag set to true. If the sender were to mark the transfers as resumes then they would be ignored at the receiver.

For delivery-tag 2, the receiver has retained some of the data making up the message, but not the whole. In order to complete the delivery the sender needs to resume sending from some point before or at the next position which the receiver is expecting.

For delivery-tag 3, the receiver indicates that it has processed the delivery to the point where it desires a terminal outcome (in this case accepted). In this case the sender will either apply that outcome at the source, or in the rare case that it cannot apply that outcome, indicate the terminal outcome that has been applied. To do this the sender MUST send a resuming transfer to associate delivery-tag 3 with a delivery-id. On this transfer the sender SHOULD set the delivery-state at the source. If this is the same outcome as at the receiver then the sender MAY also send the resuming transfer as settled.

For delivery-tag 4, the receiver indicates that it is aware that the delivery had begun, but does not provide any indication that it has retained any data about that delivery except the fact of its existence. To preserve "exactly once" or "at least once" delivery guarantees, the sender MUST resend the whole message. Unlike the case with delivery-tag 1 the resent delivery MUST be sent with the resume flag set to true and the delivery-tag set to 4. (While this use of null in the receivers map is valid, it is discouraged. It is RECOMMENDED that receiver SHOULD NOT retain such an entry in its map, in which case the situation would be as for delivery-tag 1 in this example).

For delivery-tags 5 to 9 inclusive the sender indicates that it can resume at some point beyond start of the message data. This is usually indicative of the fact that the receiver had previously confirmed reception of message data to the given point, removing responsibility from the sender to retain the ability to resend that data after resuming the link. The sender MAY still retain the ability to resend the message as a new delivery (i.e. it MAY not have completely discarded the data from which the original delivery was generated).

For delivery-tag 5, the receiver has no record of the delivery. To preserve "exactly once" or "at least once" delivery guarantees, the sender MUST resend the message; however, the delivery is not being resumed (since the receiver does not remember the delivery tag) so transfers MUST NOT have the resume flag set to true. If the sender does not have enough data to resend the message, then the sender MAY take some action to indicate that it believes there is a possibility that there has been message loss, for example, notify the application.

For delivery-tag 6, the receiver has retained some of the data making up the message, but not the whole. The first position within the message which the receiver has not received is after the first position at which the sender can resume sending. In order to complete the delivery the sender needs to resume sending from some point before or at the next position which the receiver is expecting.

For delivery-tag 7, the receiver has retained some of the data making up the message, but not the whole. The first position within the message which the receiver has not received is before the first position at which the sender can resume sending. It is thus not possible for the sender to resume sending the message to completion. The only option available to the sender is to abort the transfer and to then (if possible) resend as a new delivery or else to report the possible message loss in some way if it cannot.

For delivery-tag 8, the receiver indicates that it has processed the delivery to the point where it desires a terminal outcome (in this case accepted). This is the same case as for delivery-tag 3.

For delivery-tag 9, the receiver indicates that it is aware that the delivery had begun, but does not provide any indication that it has retained any data about that delivery except the fact of its existence. This is the same case as for delivery-tag 7.

For delivery-tags 10 to 14 inclusive the sender indicates that it has reached a terminal outcome, namely accepted. Once the sender has arrived at a terminal outcome it MUST NOT change. As such, if a sender is capable of resuming a delivery (even if the only possible outcome of the delivery is a pre-defined terminal outcome such as accepted) it MUST NOT use this state as the value of the state in its unsettled map until it is sure that the receiver will not require the resending of the message data.

For delivery-tag 10 the receiver has no record of the delivery. However, in contrast to the cases of delivery-tag 1 and delivery-tag 5, since it is known that the sender can only have arrived at this state through knowing that the receiver has received the whole message (or that the sender had spontaneously reached a terminal outcome with no possibility of resumption) there is no need to resend the message.

For delivery-tag 11 it MUST be assumed that the sender spontaneously attained the terminal outcome (and is unable to resume). In this case the sender can simply abort the delivery as it cannot be resumed.

For delivery-tag 12 both the sender and receiver have attained the same view of the terminal outcome, but neither has settled. In this case the sender SHOULD simply settle the delivery.

For delivery-tag 13 the sender and receiver have both attained terminal outcomes, but the outcomes differ. In this case, since the outcome actually takes effect at the sender, it is the sender's view that is definitive. The sender thus MUST restate this as the terminal outcome, and the receiver SHOULD then echo this and settle.

For delivery-tag 14 the case is essentially the same as for delivery-tag 11, as the null state at the receiver is essentially identical to having the state Received with section-number=0 and section-offset=0.

The messaging layer defines two concrete types (source and target) to be used as the source and target of a link. These types are supplied in the source and target fields of the attach frame when establishing or resuming link. The source is comprised of an address (which the container of the outgoing link endpoint will resolve to a node within that container) coupled with properties which determine:

• which messages from the sending node will be sent on the link,

• how sending the message affects the state of that message at the sending node,

• the behavior of messages which have been transferred on the link, but have not yet reached a terminal state at the receiver, when the source is destroyed.

A source can restrict the messages transferred from a source by specifying a filter. A filter can be thought of as a function which takes a message as input and returns a boolean value: true if the message will be accepted by the source, false otherwise. A filter MUST NOT change its return value for a message unless the state or annotations on the message at the node change (e.g., through an updated delivery state).

The source optionally defines a distribution-mode that informs and/or indicates how distribution nodes are to behave with respect to the link. The distribution-mode of a source determines how messages from a distribution node are distributed among its associated links. There are two defined distribution-modes: move and copy. When specified, the distribution-mode has two related effects on the behavior of a distribution node with respect to the link associated with the source.

The move distribution-mode causes messages transferred from the distribution node to transition to the ACQUIRED state prior to transfer over the link, and subsequently to the ARCHIVED state when the transfer is settled with a successful outcome. The copy distribution-mode leaves the state of the message unchanged at the distribution node.

A source MUST NOT resend a message which has previously been successfully transferred from the source, i.e., reached an ACCEPTED delivery state at the receiver. For a move link with a default configuration this is trivially achieved as such an end result will lead to the message in the ARCHIVED state on the node, and thus ineligible for transfer. For a copy link, state MUST be retained at the source to ensure compliance. In practice, for nodes which maintain a strict order on messages at the node, the state might simply be a record of the most recent message transferred.

A registry of commonly defined non-standard distribution-modes and their meanings is maintained [AMQPDISTMODE].

For containers which do not implement address resolution (and do not admit spontaneous link attachment from their partners) but are instead only used as producers of messages, it is unnecessary to provide spurious detail on the source. For this purpose it is possible to use a "minimal" source in which all the fields are left unset.

For containers which do not implement address resolution (and do not admit spontaneous link attachment from their partners) but are instead only used as consumers of messages, it is unnecessary to provide spurious detail on the source. For this purpose it is possible to use a "minimal" target in which all the fields are left unset.

Determines which state of the terminus is held durably.

Determines when the expiry timer of a terminus starts counting down from the timeout value. If the link is subsequently re-attached before the terminus is expired, then the count down is aborted. If the conditions for the terminus-expiry-policy are subsequently re-met, the expiry timer restarts from its originally configured timeout value.

Policies for distributing messages when multiple links are connected to the same node.

A set of named filters. Every key in the map MUST be of type symbol, every value MUST be either null or of a described type which provides the archetype filter. A filter acts as a function on a message which returns a boolean result indicating whether the message can pass through that filter or not. A message will pass through a filter-set if and only if it passes through each of the named filters. If the value for a given key is null, this acts as if there were no such key present (i.e., all messages pass through the null filter).

Filter types are a defined extension point. The filter types that a given source supports will be indicated by the capabilities of the source. A registry of commonly defined filter types and their capabilities is maintained [AMQPFILTERS].

A symbol-keyed map containing properties of a node used when requesting creation or reporting the creation of a dynamic node.

The following common properties are defined:

lifetime-policy

The lifetime of a dynamically generated node.

Definitionally, the lifetime will never be less than the lifetime of the link which caused its creation, however it is possible to extend the lifetime of dynamically created node using a lifetime policy. The value of this entry MUST be of a type which provides the lifetime-policy archetype. The following standard lifetime-policies are defined below: delete-on-close, delete-on-no-links, delete-on-no-messages or delete-on-no-links-or-messages.

supported-dist-modes

The distribution modes that the node supports.

The value of this entry MUST be one or more symbols which are valid distribution-modes. That is, the value MUST be of the same type as would be valid in a field defined with the following attributes:

type="symbol" multiple="true" requires="distribution-mode"

A node dynamically created with this lifetime policy will be deleted at the point that the link which caused its creation ceases to exist.

A node dynamically created with this lifetime policy will be deleted at the point that there remain no links for which the node is either the source or target.

A node dynamically created with this lifetime policy will be deleted at the point that the link which caused its creation no longer exists and there remain no messages at the node.

A node dynamically created with this lifetime policy will be deleted at the point that the there are no links which have this node as their source or target, and there remain no messages at the node.