This document (in progress) describes the detailed architecture of the proton library. At its heart, proton provides a protocol engine that implements the AMQP 1.0 protocol specification. The concept of a Protocol Engine is central to the proton library, so please read the Protocol Engines document for some important background, in particular the concepts of the top half and the bottom half of a protocol engine.

The UML diagram below contains a relatively complete model of the engine API, along with the dividing line between its top and bottom halves. At its core a protocol engine is simply modelling the endpoint state machine defined by a given protocol specification, in this case the AMQP 1.0 specification. As such it should be no surprise that the top half of the engine API corresponds quite directly to entities defined within the AMQP specification itself. I'll describe each of these briefly here, but ultimately a good familiarity with the AMQP 1.0 specification is helpful to fully understand the API in depth.

Engine UML

These objects capture protocol endpoint state. An endpoint is an entity responsible for remembering key state for a given participant in a multi-way conversation. Connections, Sessions, and Links are all endpoints. Links track all the conversational state relating to message transfer between a specific Source and Target. There can be multiple Links established simultaneously on a single Session, and multiple Sessions established simultaneously on a single Connection, therefore each Connection endpoint may contain multiple Session endpoints, and likewise each Session endpoint may contain multiple Link endpoints At any given point in time a Connection endpoint will be associated with at most one TCP Connection (see Transport).

Every endpoint object may be in one of three states: UNINIT, ACTIVE, and CLOSED. The open(), close(), and reset() methods transition the endpoint between these states as depicted in the diagram below. Each endpoint additionally tracks the last known state of the remote endpoint.

Endpoint State

Endpoint objects are created in one of two scenarios. In the most basic case the local application directly triggers creation of an endpoint object in order to initiate the given type of conversation (Connection, Session, or Link). In the case of Sessions and Links, the remote application might trigger the engine to internally create an endpoint. The local and last known remote endpoint state may be used to distinguish between the various scenarios. In total there are 9 possible combinations of these states described in more detail in the table below.

UNINITUNINITThis would be the initial state of an endpoint that is newly created by the local application.
UNINITACTIVEThis would be the initial state of an endpoint that was created by the engine in response to actions taken by the remote application.It can be thought of as "half open".
UNINITCLOSEDSame as the above except the remote application has chosen to close its own endpoint prior to reaching a fully established state, i.e. the remote application is aborting.
ACTIVEUNINITLocally initiated "half open".
ACTIVEACTIVEPairing between the two endpoints is fully established.
ACTIVECLOSEDIn the process of a remotely initiated closing. (Half closed).
CLOSEDUNINITIn the process of a locally initiated abort.
CLOSEDACTIVEIn the process of a locallly initiated closing. (Half Closed)


In addition to holding the common endpoint state described above, Link endpoints also track the state of messages in the process of being transferred between a designated Source and Target. Each message transfer is associated with a Delivery object, and the Link endpoint internally keeps an ordered set of these objects. Depending on the directionality of the given Link endpoint (Receiver vs Sender), the Deliveries are kept in either incoming or outgoing order. Each Link endpoint also tracks the current delivery. The Receiver.recv() and Sender.send() methods may be used to access/supply message data for the current delivery.

Link-Delivery Object Diagram


The Messenger API is a simple utility built on top of the engine API. It provides a message oriented API for sending and receiving messages.

Messenger UML




  • No labels

1 Comment

  1. This is a great document.

    Request: can we have a little more detail explaining how to do work queue processing of Deliveries?   Specifically:

    o) On receive, how does the application know a delivery has pending data to be read?

    o) On send, how does the application know when enough credit has been granted by the remote in order to make the delivery "writable"?

    o) How does an app process multi-frame messages - both inbound and outbound?