Topic alias support

[andsel]

General description

TopicAlias is used to lower the payload of publishes that recurrently use the same topic. The publish instead of transmitting a topic name in its variable header can use the topic alias property, but before the sender has send a publish with both topic name and topic alias so that the receiver can create the association. From this point onward the sender can just set the topic_alias in the PUB message.
A sender can modify the Topic Alias mapping by sending another PUBLISH in the same Network Connection with the same Topic Alias value and a different non-zero length Topic Name.

Topic Alias mappings exist only within a Network Connection and last only for the lifetime of that Network Connection.

During the CONNECT the client can specify the size of its topic alias cache, by topic alias maximum property so that the server can't send a topic alias bigger than this value. The same can be done by the server in the CONNACK packet specifying an analogous topic alias maximum property.

MQTT5 specification

In CONNECT

3.1.2.11.5 Topic Alias Maximum

34 (0x22) Byte, Identifier of the Topic Alias Maximum.

Followed by the Two Byte Integer representing the Topic Alias Maximum value. It is a Protocol Error to include the Topic Alias Maximum value more than once. If the Topic Alias Maximum property is absent, the default value is 0.

This value indicates the highest value that the Client will accept as a Topic Alias sent by the Server. The Client uses this value to limit the number of Topic Aliases that it is willing to hold on this Connection. The Server MUST NOT send a Topic Alias in a PUBLISH packet to the Client greater than Topic Alias Maximum [MQTT-3.1.2-26]. A value of 0 indicates that the Client does not accept any Topic Aliases on this connection. If Topic Alias Maximum is absent or zero, the Server MUST NOT send any Topic Aliases to the Client [MQTT-3.1.2-27].

In CONNACK

3.2.2.3.8 Topic Alias Maximum

34 (0x22) Byte, Identifier of the Topic Alias Maximum.

Followed by the Two Byte Integer representing the Topic Alias Maximum value. It is a Protocol Error to include the Topic Alias Maximum value more than once. If the Topic Alias Maximum property is absent, the default value is 0.

This value indicates the highest value that the Server will accept as a Topic Alias sent by the Client. The Server uses this value to limit the number of Topic Aliases that it is willing to hold on this Connection. The Client MUST NOT send a Topic Alias in a PUBLISH packet to the Server greater than this value [MQTT-3.2.2-17]. A value of 0 indicates that the Server does not accept any Topic Aliases on this connection. If Topic Alias Maximum is absent or 0, the Client MUST NOT send any Topic Aliases on to the Server [MQTT-3.2.2-18].

In PUBLISH

3.3.2.3.4 Topic Alias

35 (0x23) Byte, Identifier of the Topic Alias.

Followed by the Two Byte integer representing the Topic Alias value. It is a Protocol Error to include the Topic Alias value more than once.

A Topic Alias is an integer value that is used to identify the Topic instead of using the Topic Name. This reduces the size of the PUBLISH packet, and is useful when the Topic Names are long and the same Topic Names are used repetitively within a Network Connection.

The sender decides whether to use a Topic Alias and chooses the value. It sets a Topic Alias mapping by including a non-zero length Topic Name and a Topic Alias in the PUBLISH packet. The receiver processes the PUBLISH as normal but also sets the specified Topic Alias mapping to this Topic Name.

If a Topic Alias mapping has been set at the receiver, a sender can send a PUBLISH packet that contains that Topic Alias and a zero length Topic Name. The receiver then treats the incoming PUBLISH as if it had contained the Topic Name of the Topic Alias.

A sender can modify the Topic Alias mapping by sending another PUBLISH in the same Network Connection with the same Topic Alias value and a different non-zero length Topic Name.

Topic Alias mappings exist only within a Network Connection and last only for the lifetime of that Network Connection. A receiver MUST NOT carry forward any Topic Alias mappings from one Network Connection to another [MQTT-3.3.2-7].

A Topic Alias of 0 is not permitted. A sender MUST NOT send a PUBLISH packet containing a Topic Alias which has the value 0 [MQTT-3.3.2-8].

A Client MUST NOT send a PUBLISH packet with a Topic Alias greater than the Topic Alias Maximum value returned by the Server in the CONNACK packet [MQTT-3.3.2-9]. A Client MUST accept all Topic Alias values greater than 0 and less than or equal to the Topic Alias Maximum value that it sent in the CONNECT packet [MQTT-3.3.2-10].

A Server MUST NOT send a PUBLISH packet with a Topic Alias greater than the Topic Alias Maximum value sent by the Client in the CONNECT packet [MQTT-3.3.2-11]. A Server MUST accept all Topic Alias values greater than 0 and less than or equal to the Topic Alias Maximum value that it returned in the CONNACK packet [MQTT-3.3.2-12].

The Topic Alias mappings used by the Client and Server are independent from each other. Thus, when a Client sends a PUBLISH containing a Topic Alias value of 1 to a Server and the Server sends a PUBLISH with a Topic Alias value of 1 to that Client they will in general be referring to different Topics.

In PUBLISH action

If the PUBLISH packet contains a Topic Alias, the receiver processes it as follows:

• 1. A Topic Alias value of 0 or greater than the Maximum Topic Alias is a Protocol Error, the receiver uses DISCONNECT with Reason Code of 0x94 (Topic Alias invalid) as described in section 4.13.
• 2. If the receiver has already established a mapping for the Topic Alias, then

  • a) If the packet has a zero length Topic Name, the receiver processes it using the Topic Name that corresponds to the Topic Alias

  • b) If the packet contains a non-zero length Topic Name, the receiver processes the packet using that Topic Name and updates its mapping for the Topic Alias to the Topic Name from the incoming packet

• 3. If the receiver does not already have a mapping for this Topic Alias

  • a) If the packet has a zero length Topic Name field it is a Protocol Error and the receiver uses DISCONNECT with Reason Code of 0x82 (Protocol Error) as described in section 4.13.

  • b) If the packet contains a Topic Name with a non-zero length, the receiver processes the packet using that Topic Name and sets its mappings for the Topic Alias to Topic Name from the incoming packet.

Implementation

The implementation can be split in 2 halves, the first and mandatory is that the broker needs to handle the publishes with topic alias sent from clients. The second, optional, is that the broker autonomously use topic alias when forwards publish messages to MQTT5 clients, if the client can handle this feature.

Broker handle publish from clients with topic alias

• expose a configuration setting so that user can set different sizes of topic alias cache per connection, or even disable it.
• in CONNACK set the Topic Alias Maximum property to what's the default or the configured by the user. If zero do not send the property and mark the connection as not able to handle topic aliases.
• if a connection with topic alias maximum set to 0 (disabled) receives a PUBLISH with topic alias, disconnect with proper reason code
• when a publish is received and contains topic alias verify it's in the range (0..topic alias maximum] if not, disconnect with reason code 0x94 (Topic Alias invalid).
• create a topic alias cache to be used from the MQTTConnection so that when a PUBLISH contains topic alias:
  • if it doesn't have a mapping for the topic alias
    • if Topic Name is empty (zero length) then DISCONNECT with 0x82 (Protocol Error)
    • if Topic Name is not empty then set the Topic Name to the Topic Alias in the cache
  • if already has mapping for the topic alias
    • if Topic Name is empty (zero length) then use the mapped Topic Alias name in forwarding the message
    • if Topic Name is not empty then update the Topic Name to the Topic Alias in the cache
• when forwarding a message for a PUBLISH with topic alias defined do not forward the property just the Topic Name
• do not store the Topic Alias in persisted messages.

[Optional] Broker use Topic Alias in forwarded publishes

TODO