Declared Shared Subscriptions
Declared shared subscriptions allow your HiveMQ MQTT broker to enqueue messages that are published to specific preconfigured shared subscriptions on demand as soon as HiveMQ starts. Unlike a standard shared subscription, messages to a declared shared subscription are enqueued even if there are no connected shared subscribers for the topic.
To ensure that the desired messages are enqueued, the same
declared-shared-subscriptions.xml configuration file must be present on each node of your HiveMQ cluster.
|If the declared shared subscriptions configuration is not the same on all nodes of the cluster, HiveMQ logs a warning. The presence of inconsistent declared shared subscription configurations does not prevent HiveMQ startup. However, inconsistent configurations lessens your protection form message loss in disaster situations.|
The declared shared subscriptions must be provided in a configuration file before the HiveMQ instance starts.
For more information, see Configuration.
To configure declared shared subscriptions, add a file called
declared-shared-subscriptions.xml to the
conf folder in your HiveMQ instance.
For your convenience, an example
declared-shared-subscriptions.xml file that you can copy and modify is included in the
conf/examples/configuration/declared-shared-subscriptions folder of your HiveMQ installation.
Your declared shared subscriptions must be listed in the XML file as shown in the example.
If HiveMQ detects an invalid or malformed
<declared-shared-subscriptions> <subscription> <topic-filter>device/status</topic-filter> <share-name>group1</share-name> </subscription> <subscription> <topic-filter>device/update</topic-filter> <share-name>group2</share-name> </subscription> ... </declared-shared-subscriptions>
It is not possible to make changes to your declared shared subscriptions configuration at runtime.
If you want to change your
Declared Shared Subscription Concepts
If multiple nodes in a cluster crash and the configured replication factor for the cluster is not greater than the number of crashed nodes, session information such as shared subscriptions can be lost. PUBLISH messages that arrive during the break in connection are not enqueued for the lost shared subscription until the client reconnects and recreates the shared subscription.
In the unlikely event that multiple HiveMQ instances fail, session data and subscriptions can be lost for the remaining cluster and result in lost messages. A similar problem can occur during cluster splits if partitions of the cluster do not have all the sessions and subscriptions and therefore cannot deliver all messages.
To avoid possible message loss, you can declare shared subscriptions on demand that are resilient against node outages or cluster splits and available as soon as you start HiveMQ.
Declared Shared Subscription Use Cases
Declared shared subscriptions can be particularly useful in scenarios that rely heavily on shared subscription messages to guarantee the continuity of their business operations. Here are a few use case where declared shared subscriptions can be beneficial:
Your business model requires that messages to specific known shared subscriptions must be delivered to clients that subscribe to the shared subscription, even if the client connection is not yet established or lost.
The backend systems that ingest MQTT messages must be able to consume all shared messages, even if the backend service is temporarily not available.
You need assurance that no messages published to specific known shared subscriptions are lost regardless of cluster splits and disasters.