Transactional messaging allows for the coordinated outcome of otherwise independent transfers. This extends to an arbitrary number of transfers spread across any number of distinct links in either direction.

For every transactional interaction, one container acts as the transactional resource, and the other container acts as the transaction controller. The transactional resource performs transactional work as requested by the transaction controller.

The transactional controller and transactional resource communicate over a control link which is established by the transactional controller. The declare and discharge messages are sent by the transactional controller over the control link to allocate and complete transactions respectively (they do not represent the demarcation of transactional work). No transactional work is allowed on the control link. Each transactional operation requested is explicitly identified with the desired transaction-id and therefore can occur on any link within the controlling session, or, if permitted by the capabilities of the controller, any link on the controlling connection. If the control link is closed while there exist non-discharged transactions it created, then all such transactions are immediately rolled back, and attempts to perform further transactional work on them will lead to failure.

The container acting as the transactional resource defines a special target that functions as a transaction coordinator. The transaction controller establishes a control link to this target. Note that links to the coordinator cannot be resumed.

To begin transactional work, the transaction controller needs to obtain a transaction identifier from the resource. It does this by sending a message to the coordinator whose body consists of the declare type in a single amqp-value section. Other standard message sections such as the header section SHOULD be ignored. This message MUST NOT be sent settled as the sender is REQUIRED to receive and interpret the outcome of the declare from the receiver. If the coordinator receives a transfer that has been settled by the sender, it SHOULD detach with an amqp:illegal-state error.

If the declaration is successful, the coordinator responds with a disposition outcome of declared which carries the assigned identifier for the transaction.

If the coordinator was unable to perform the declare as specified by the transaction controller, the transaction coordinator MUST convey the error to the controller as a transaction-error. If the source for the link to the coordinator supports the rejected outcome, then the message MUST be rejected with this outcome carrying the transaction-error. If the source does not support the rejected outcome, the transactional resource MUST detach the link to the coordinator, with the detach performative carrying the transaction-error.

Transaction controllers SHOULD establish a control link that allows the rejected outcome.

The controller will conclude the transactional work by sending a discharge message (encoded in a single amqp-value section) to the coordinator. The controller indicates that it wishes to commit or rollback the transactional work by setting the fail flag on the discharge body. As with the declare message, it is an error if the sender sends the transfer pre-settled.

If the coordinator is unable to complete the discharge, the coordinator MUST convey the error to the controller as a transaction-error. If the source for the link to the coordinator supports the rejected outcome, then the message MUST be rejected with this outcome carrying the transaction-error. If the source does not support the rejected outcome, the transactional resource MUST detach the link to the coordinator, with the detach performative carrying the transaction-error. Note that the coordinator MUST always be able to complete a discharge where the fail flag is set to true (since coordinator failure leads to rollback, which is what the controller is asking for).

Transactional work is described in terms of the message states defined in section 3.3. Transactional work is formally defined to be composed of the following operations:

• posting a message at a target, i.e., making it available

• acquiring a message at a source, i.e., transitioning it to acquired

• retiring a message at a source, i.e., applying the terminal outcome

The transactional resource performs these operations when triggered by the transaction controller:

• posting messages is initiated by incoming transfer frames

• acquiring messages is initiated by incoming flow frames

• retiring messages is initiated by incoming disposition frames

In each case, it is the responsibility of the transaction controller to identify the transaction with which the requested work is to be associated. This is done with the transactional delivery state transactional-state that combines a txn-id together with one of the terminal delivery states defined in section 3.4. The transactional-state is carried by both the transfer and the disposition frames allowing both the posting and retiring of messages to be associated with a transaction.

The transfer, disposition, and flow frames can travel in either direction, i.e., from the controller to the resource and from the resource to the controller. When these frames travel from the controller to the resource, any embedded txn-ids are requesting that the resource assigns transactional work to the indicated transaction. When traveling in the other direction, from resource to controller, the transfer and disposition frames indicate work performed, and the txn-ids included MUST correctly indicate with which (if any) transaction this work is associated. In the case of the flow frame traveling from resource to controller, the txn-id does not indicate work that has been performed, but indicates with which transaction future transfers from that link will be performed.

If the transaction controller wishes to associate an outgoing transfer with a transaction, it MUST set the state of the transfer with a transactional-state carrying the appropriate transaction identifier. Note that if delivery is split across several transfer frames then all frames MUST be explicitly associated with the same transaction. It is an error for the controller to attempt to discharge a transaction against which a partial delivery has been posted. If this happens, the control link MUST be terminated with the transaction-rollback error.

The effect of transactional posting is that the message does not become available at the destination node within the transactional resource until after the transaction has been successfully discharged.

On receiving a non-settled delivery associated with a live transaction, the transactional resource MUST inform the controller of the presumptive terminal outcome before it can successfully discharge the transaction. That is, the resource MUST send a disposition performative which covers the posted transfer with the state of the delivery being a transactional-state with the correct transaction identified, and a terminal outcome. This informs the controller of the outcome that will be in effect at the point that the transaction is successfully discharged.

The transaction controller might wish to associate the outcome of a delivery with a transaction. The delivery itself need not be associated with the same transaction as the outcome, or indeed with any transaction at all. However, the delivery MUST NOT be associated with a different non-discharged transaction than the outcome. If this happens then the control link MUST be terminated with a transaction-rollback error.

To associate an outcome with a transaction the controller sends a disposition performative which sets the state of the delivery to a transactional-state with the desired transaction identifier and the outcome to be applied upon a successful discharge.

On a successful discharge, the resource will apply the given outcome and can immediately settle the transfers. In the event of a controller-initiated rollback (a discharge where the fail flag is set to true) or a resource-initiated rollback (the discharge message being rejected, or the link to the coordinator being detached with an error), the outcome will not be applied, and the deliveries will still be "live" and will remain acquired by the controller, i.e., the resource can expect the controller to request a disposition for the delivery (either transactionally on a new transaction, or non-transactionally).

In the case of the flow frame, the transactional work is not necessarily directly initiated or entirely determined when the flow frame arrives at the resource, but can in fact occur at some later point and in ways not necessarily anticipated by the controller. To accommodate this, the resource associates an additional piece of state with outgoing link endpoints, a txn-id that identifies the transaction with which acquired messages will be associated. This state is determined by the controller by specifying a txn-id entry in the properties map of the flow frame. When a transaction is discharged, the txn-id of any link endpoints will be cleared.

If the link endpoint does not support transactional acquisition, the link MUST be terminated with a not-implemented error.

While the txn-id is cleared when the transaction is discharged, this does not affect the level of outstanding credit. To prevent the sending link endpoint from acquiring outside of any transaction, the controller SHOULD ensure there is no outstanding credit at the sender before it discharges the transaction. The controller can do this by either setting the drain mode of the sending link endpoint to true before discharging the transaction, or by reducing the link-credit to zero, and waiting to hear back that the sender has seen this state change.

If a transaction is discharged at a point where a message has been transactionally acquired, but has not been fully sent (i.e., the delivery of the message will require more than one transfer frame and at least one, but not all, such frames have been sent), then the resource MUST interpret this to mean that the fate of the acquisition is fully decided by the discharge. If the discharge indicates the failure of the transaction the resource MUST abort or complete sending the remainder of the message before completing the discharge.

The transport layer defines a notion of settlement which refers to the point at which the association of a delivery-tag to a delivery attempt is forgotten. Transactions do not in themselves change this notion, however the fact that transactional work can be rolled back does have implications for deliveries which the endpoint has marked as settled (and for which it can therefore no longer exchange state information using the previously allocated transport level identifiers).

←Transactional Posting

Delivery Sent Settled By Controller

The delivered message will not be made available at the node until the transaction has been successfully discharged. If the transaction is rolled back then the delivery is not made available. If the resource is unable to process the delivery it MUST NOT allow the successful discharge of the associated transaction. This can be communicated by immediately destroying the controlling link on which the transaction was declared, or by rejecting any attempt to discharge the transaction where the fail flag is not set to true.

Delivery Sent Unsettled By Controller; Resource Settles

The resource MUST determine the outcome of the delivery before committing the transaction, and this MUST be communicated to the controller before the acceptance of a successful discharge. The outcome communicated by the resource MUST be associated with the same transaction with which the transfer from controller to resource was associated.

If the transaction is rolled back then the delivery is not made available at the target. If the resource can no longer apply the outcome that it originally indicated would be the result of a successful discharge then it MUST NOT allow the successful discharge of the associated transaction. This can be communicated by immediately destroying the controlling link on which the transaction was declared, or by rejecting any attempt to discharge the transaction where the fail flag is not set to true.

Delivery Sent Unsettled By Controller; Resource Does Not Settle

Behavior prior to discharge is the same as the previous case.

After a successful discharge, the state of unsettled deliveries at the resource MUST reflect the outcome that was applied. If the discharge was unsuccessful then an outcome SHOULD NOT be associated with the unsettled deliveries. The controller SHOULD settle any outstanding unsettled deliveries in a timely fashion after the transaction has discharged.

←Transactional Retirement

This section considers the cases where the resource has sent messages to the controller in a non-transactional fashion. For the cases where the resource sends the messages transactionally, see subsection 4.4.3.

Delivery Sent Unsettled By Resource; Controller Settles

Upon a successful discharge the outcome specified by the controller is applied at the source. If the controller requests a rollback or the discharge attempt be unsuccessful, then the outcome is not applied. At this point the controller can no longer influence the state of the delivery as it is settled, and the resource MUST apply the default outcome.

Delivery Sent Unsettled By Resource; Controller Does Not Settle

The resource might or might not settle the delivery before the transaction is discharged. If the resource settles the delivery before the discharge then the behavior after discharge is the same as the case above.

Upon a successful discharge the outcome is applied. Otherwise the state reverts to that which occurred before the controller sent its (transactional) disposition. The controller is free to update the state using subsequent transactional or non-transactional updates.

←Transactional Acquisition

Delivery Sent Settled By Resource

In the event of a successful discharge the outcome applies at the resource, otherwise the acquisition and outcome are rolled back.

Delivery Sent Unsettled By Resource; Controller Sends Outcome

An outcome sent by the controller before the transaction has discharged MUST be associated with the same transaction. In the even of a successful discharge the outcome is applied at the source, otherwise both the acquisition and outcome are rolled back.

The coordinator type defines a special target used for establishing a link with a transaction coordinator.

The declare type defines the message body sent to the coordinator to declare a transaction. The txn-id allocated for this transaction is chosen by the transaction controller and identified in the declared resulting outcome.

The discharge type defines the message body sent to the coordinator to indicate that the txn-id is no longer in use. If the transaction is not associated with a global-id, then this also indicates the disposition of the local transaction.

A transaction-id can be up to 32 octets of binary data.

Indicates that a transaction identifier has successfully been allocated in response to a declare message sent to a transaction coordinator.

The transactional-state type defines a delivery-state that is used to associate a delivery with a transaction as well as to indicate which outcome is to be applied if the transaction commits.