Message Retransmission

Message retransmission is part of the MQTT protocol specification.

The protocol stipulates that the PUBLISH packets sent to the peer by the server and client as communication parties must meet their Quality of Service levels requirements , such as:

• QoS 1: it means that **the message is delivered at least once; ** that is, the sender will always resend the message unless it receives confirmation from the peer. This means that the same QoS 1 message may be received multiple times in the upper layer(the application layer of the service) of the MQTT protocol.
• QoS 2: it means the message is delivered exactly once; that is, the message will only be received once at the upper layer.

Although PUBLISH packets of QoS 1 and QoS 2 will be resent at the MQTT protocol stack layer, you must remember:

• After the retransmission of QoS 1 messages happens, these retransmitted PUBLISH packets will also be received at the upper layer of the MQTT protocol stack.
• No matter how QoS 2 message is retransmitted, only one PUBLISH packet will be received in the upper layer of the MQTT protocol stack,

Basic Configuration

EMQX retransmits unacknowledged QoS 1 and QoS 2 messages in the following scenarios:

1. When a client reconnects and resumes its session, EMQX replays unacknowledged messages to continue the QoS delivery flow.
2. While the client is connected, EMQX periodically retransmits unacknowledged messages if mqtt.retry_interval is set to a positive duration.

Configure the retransmission interval in the configuration file:

Configuration Item	Type	Optional Value	Default Value	Description
retry_interval	duration	duration or infinity	infinity	Interval between retransmissions of unacknowledged QoS 1 and QoS 2 messages while the client is connected. Set it to 0 or infinity to disable periodic retransmissions. Unacknowledged messages are still replayed when the session resumes.

Generally speaking, you only need to care about the above content.

For more details on how EMQX handles the retransmission of the MQTT protocol, see the following of this article.

Protocol Specification and Design

Retransmitted Objects

First, before understanding the retransmission mechanism design of EMQX, we need to ensure that you have understood the transmission process of QoS 1 and QoS 2 in the protocol, otherwise please refer toMQTTv3.1.1 - QoS 1: At least once delivery and MQTTv3.1.1 - QoS 2: Exactly once delivery

Only a brief review is made to illustrate what are the retransmitted objects under different QoS.

QoS 1

QoS 1 requires the message to be delivered at least once; therefore, the message may be continuously retransmitted in the MQTT protocol layer until the sender receives the confirmation message of the message.

The schematic diagram of the process is as follows:

               PUBLISH
#1 Sender  --------------->  Receiver       (*)
               PUBACK
#2 Sender  <---------------  Receiver

• Two packets are involved; there are two sending actions totally, one at the sender and one at the receiver; both packets hold the same PacketId.
• If the end of the line is marked with an *, it means that the sender may initiate a retransmission if the waiting for the confirmation message is time out.

It can be seen that QoS 1 messages only need to retransmit PUBLISH messages

QoS 2

QoS 2 requires the message to be delivered only once; so when it is implemented, a more complicated process is required. The schematic diagram of the process is as follows:

               PUBLISH
#1 Sender  --------------->  Receiver       (*)
               PUBREC
#2 Sender  <---------------  Receiver
               PUBREL
#3 Sender  --------------->  Receiver       (*)
               PUBCOMP
#4 Sender  <---------------  Receiver

• 4 packets are involved; there are 4 sending actions totally, 2 times for each of the sender and receiver; these 4 packets all hold the same PacketId.
• If the end of the line is marked with an *, it means that the sender may initiate a retransmission if the waiting for the confirmation message is time out.

It can be seen that QoS 2 messages only need to retransmit PUBLISH packet and PUBREL packet

In summary:

• Retransmission action is triggered under the condition that the expected return is not received within specified time after sending the message, and not receiving.
• Retransmission object only contains the following three types:
  • QoS 1 PUBLISH packet
  • QoS 2 PUBLISH packet
  • QoS 2 PUBREL packet

When EMQX acts as the receiver of PUBLISH messages, it does not require the retransmission operation.

Inflight Window and Maximum Receiving Value

For the definition and explanation of this concept, please refer to Inflight Window and Message Queue

The purpose of introducing these two concepts is to understand:

1. When EMQX is used as the sender, the retransmitted message must be the message stored in the inflight window.
2. When EMQX is used as the receiver, and the sender retransmits the message:
   • For QoS 1, EMQX directly reply PUBACK as response;
   • For QoS 2, EMQX will release the stored PUBLISH or PUBREL packet in the maximum received message queue.

Message Sequence

Of course, the above concepts only need to be understood. What you need to care about most is the change in message order after messages are retransmitted, especially for QoS type 1 messages. E.g:

Suppose that when the current inflight window is set to 2, EMQX plans to deliver 4 QoS 1 messages to a certain topic on the client. Assume that the client program or the network has experienced problems in the middle of the process, then the entire sending process will become:

#1  [4,3,2,1 || ]   ----->   []
#2  [4,3 || 2, 1]   ----->   [1, 2]
#3  [4 || 3, 2]     ----->   [1, 2, 3]
#4  [4 || 3, 2]     ----->   [1, 2, 3, 2, 3]
#5  [ || 4]         ----->   [1, 2, 3, 2, 3, 4]
#6  [ || ]          ----->   [1, 2, 3, 2, 3, 4]

There are 6 steps in the process; the left indicates the message queue and inflight window of EMQX, which is separated by ||; the right indicates the sequence of messages received by the client, where each step indicates:

1. Broker puts 4 messages into the message queue.
2. Broker sequentially sends 1 2 and puts it in the inflight window; the client only responds to the message 1; and at this time due to a problem with the client's sending stream, subsequent responses cannot be sen.
3. Broker receives the reply of the message 1; removes the message 1 from the inflight window; and sends out 3; continues to wait for the reply of 2 3;
4. When the waiting for the response is time out, broker retransmitted the message 2 3; the client received the retransmitted message 2 3 and responded normally.
5. Broker removed the message 2 3 from the inflight window and sent the message 4; the client received the message 4 and responded with a reply.
6. At this point, all message processing is complete. The sequence of messages received by the client is [1, 2, 3, 2, 3, 4], and it is reported to the upper layer of the MQTT protocol stack in turn.

Although there are duplicate messages, this is in full compliance with the specifications of the protocol. The first appearance of each message is in order, and the message 2 3 repeatedly received will carry an identification bit, indicating that it is a retransmission message.

The MQTT protocol and EMQX regard this topic as an Ordered Topic. See: MQTTv3.1.1 - Message ordering.

It ensures that under the same topic and QoS, messages are delivered and answered in order.

In addition, if the user expects that QoS 1 and QoS 2 messages under all topics are strictly ordered, the maximum length of the flight window needs to be set to 1, but it will reduce the client's throughput.

Related Configuration

This section lists all the configurations used in the above mechanism. They are all included in config files:

Configuration	Type	Optional Value	Default Value	Description
mqueue_store_qos0	boolean	true, false	true	Whether to store QoS 0 messages in the message queue.
max_mqueue_len	integer	0 - infinity	1000	Maximum message queue length.
max_inflight	integer	1 - 65535	32	Maximum number of unacknowledged QoS 1 and QoS 2 messages that EMQX can deliver simultaneously.
max_awaiting_rel	integer	0 - infinity	100	Maximum number of QoS 2 messages awaiting PUBREL in each session.
await_rel_timeout	duration	> 0	300s	Maximum time to wait for PUBREL. When the timeout expires, EMQX releases the packet ID and logs a warning. The QoS 2 message is delivered before EMQX starts waiting for PUBREL.