Implements Subscription Options

[andsel]

General description

Subscription options permit to customize the forwarding behavior of the server when sending events matching a topic filter.
MQTT 5.0 introduces four subscription options: QoS, No Local, Retain As Published, and Retain Handling.
MQTT 3.1.1 support only QoS option.

QoS

Represents the maximum QoS level that the server can use when sending messages to the subscriber; when the client subscribed to a topic filter it defines also the maximum qos it can handle.

No Local

The No Local option has only two possible values, 0 and 1. A value of 1 indicates that the server must not forward the message to the client that published it, while 0 means the opposite.
This is used in bridge situations, so that one server publishing a message on a topic it's subscribed doesn't receive a reflected message.

Retain As Published

The Retain As Published option has two possible values, 0 and 1.

• 1 means the server should preserve the Retain flag unchanged when forwarding application messages to subscribers
• 0 means that the Retain flag must be cleared.
  Also this setting is used in bridging situations.

Retain Handling

The Retain Handling subscription option indicates to the server whether to send retained messages when a subscription is established.

When a subscription is established, the retained messages matching the subscription in the server will be delivered by default.

It can have 3 possible value:

• 0 means that retained messages are sent whenever a subscription is established.
• 1 means retained messages are sent only when establishing a new subscription, not a repeated one.
• 2 means no retained messages are sent when a subscription is established.

References:

• https://www.emqx.com/en/blog/an-introduction-to-subscription-options-in-mqtt

MQTT 5 specification (relevant to server implementation)

Subscribe Payload 3.8.3.1

• Bits 0 and 1 of the Subscription Options represent Maximum QoS field. This gives the maximum QoS level at which the Server can send Application Messages to the Client. It is a Protocol Error if the Maximum QoS field has the value 3.

• Bit 2 of the Subscription Options represents the No Local option. If the value is 1, Application Messages MUST NOT be forwarded to a connection with a ClientID equal to the ClientID of the publishing connection [MQTT-3.8.3-3].
  It is a Protocol Error to set the No Local bit to 1 on a Shared Subscription [MQTT-3.8.3-4].

• Bit 3 of the Subscription Options represents the Retain As Published option.

  • If 1, Application Messages forwarded using this subscription keep the RETAIN flag they were published with. [MQTT-3.3.1-13]
  • If 0, Application Messages forwarded using this subscription have the RETAIN flag set to 0. Retained messages sent when the subscription is established have the RETAIN flag set to 1. [MQTT-3.3.1-12]

• Bits 4 and 5 of the Subscription Options represent the Retain Handling option. This option specifies whether retained messages are sent when the subscription is established. This does not affect the sending of retained messages at any point after the subscribe. If there are no retained messages matching the Topic Filter, all of these values act the same. The values are:

  • 0 = Send retained messages at the time of the subscribe [MQTT-3.3.1-9]
  • 1 = Send retained messages at subscribe only if the subscription does not currently exist [MQTT-3.3.1-10]
  • 2 = Do not send retained messages at the time of the subscribe [MQTT-3.3.1-11]

It is a Protocol Error to send a Retain Handling value of 3.

• Bits 6 and 7 of the Subscription Options byte are reserved for future use. The Server MUST treat a SUBSCRIBE packet as malformed if any of Reserved bits in the Payload are non-zero [MQTT-3.8.3-5].

Non-normative comment

The No Local and Retain As Published subscription options can be used to implement bridging where the Client is sending the message on to another Server.

Non-normative comment

Not sending retained messages for an existing subscription is useful when a reconnect is done and the Client is not certain whether the subscriptions were completed in the previous connection to the Session.

Non-normative comment

Not sending stored retained messages because of a new subscription is useful where a Client wishes to receive change notifications and does not need to know the initial state.

Non-normative comment

For a Server that indicates it does not support retained messages, all valid values of Retain As Published and Retain Handling give the same result which is to not send any retained messages at subscribe and to set the RETAIN flag to 0 for all messages.

Task list

• manage the persistence of SubscriptionOption to disk, and reload when restarting. Move from qos to subscription option #810
• make QoS level handled by server configurable by a configuration setting instead of being hardcoded to QoS2. Make configurable the maximum qos that a server can handle #811
• manage the no local Subscription Option to not republish to sender, with integration tests. Update subscription option handling to account no local #814
• manage retain as published Subscription Option, with integration tests. Implements subscription options retain as published feature #815
• manage the three kinds of retain handling Subscription Option, with integration tests. Implement subscription retain policy handling #816

[andsel]

Closed because all tasks were completed.